@mapbox/locking 🔒

Wrap any callback or async function to use an LRU cache and prevent (lock) asynchronous operations across concurrent calls.

npm install --save @mapbox/locking

Disclaimer

This package is a thin wrapper around node-lru-cache, which does not impose strict protections around memory usage, other than the built-in max, maxSize, and ttl options (for which this package configures some sensible defaults). Use of this package should include careful consideration for the key/value design along with the aforementioned limits to ensure cache memory usage remains within the desired range. See node-lru-cache's Storage Bounds Safety documentation for some helpful tips.

Usage

import { Locking, LockingAsync } from '@mapbox/locking';

The options objects are passed directly to lru-cache allowing you to set the max age, max items, and other behaviors of the LRU cache. When options.allowStale is set to true the locking cache implements additional behavior to continue serving a stale item until the item has been refreshed in the background.

Locking(function, options)

For locking callback functions in the form function(id, callback). Returns a callable function

import { Locking } from '@mapbox/locking';
import fs from 'fs';
const readFile = Locking(fs.readFile, options);

// Reads file once, calls callback 10x.
for (let i = 0; i < 10; i++) {
  readFile('./sample.txt', function(err, data) {
    console.log(data);
  });
}

LockingAsync(function, options)

Constructor for locking promise or async functions in the form of function(...arguments). This can manage functions of arbitrary arguments and types. Returns a class with two functions, which includes a callable method get() for calling the original function.

import { LockingAsync } from '@mapbox/locking';
import got from 'got';

const jsonApi = new Locking((url) => {
  return got(url).json();
}, options);

// call function
await jsonApi.get('https://api.mapbox.com');
await jsonApi.get('https://api.mapbox.com');
await jsonApi.get('https://api.mapbox.com');

// get stats
console.log(jsonApi.stats); 
// { total: 3, hit: 2, miss: 1, locks: 2, refreshHit: 0, currentLocks: 0, size: 1 }

Developing

npm ci          # setup
npm test        # run tests
npm run build   # build typescript
npm run format  # format with prettier