withLock and createLock are one FIFO queue. A caller that enqueues a lot of work keeps taking the next slot.
withFairQueue is fair queuing: one queue per key, and a free slot rotates across those keys. The same key is still served in arrival order. Callers that omit the key share one queue.
A second queued call for the same user waits until each other waiting user has had a turn. Pass an AbortSignal as the third argument when the caller can give up. Aborting while the call is queued skips the function.
with cancellation
Pass an AbortSignal to drop an acquisition that is still waiting in the queue — handy for shedding work whose caller already gave up (a timed-out request, a disconnected client):
const { withLock } = require('superlock')const lock = withLock()const controller = new AbortController()const pending = lock(() => doWork(), controller.signal)// caller no longer needs the result: give the queued slot backcontroller.abort()await pending // resolves `undefined`; `doWork` never runs
If the signal aborts before the slot is granted, the acquisition is dropped: it never takes a slot and the wrapped function never runs. Aborting after the slot is granted is a no-op (the work is already running). Aborting is silent — it resolves instead of throwing — so shedding a lot of queued work never produces rejections to handle.
API
withLock([concurrency=1])
It returns a function that can be used to wrap any code you want to execute with concurrency control:
The lock will be automatically released after your code execution is done even if an error occurred, avoiding deadlock situations.
It also accepts an optional AbortSignal as second argument:
await lock(() => { /* your code execution */}, signal)
If signal aborts while the call is still queued, the function is skipped and the call resolves undefined instead of running. Aborting after the slot is granted has no effect.
concurrency
Type: number
Default: 1
It sets the maximum of concurrency allowed for the lock.
signal
Type: AbortSignal
When provided, aborting it drops the acquisition while it is still waiting in the queue: no slot is taken and the wrapped function never runs.
createLock([slots=1])
The FIFO semaphore behind withLock. The promise resolves to a release function you call when the work is done:
An optional AbortSignal is the first argument. If it aborts while the call is queued, the promise resolves null and no slot is taken.
slots
Type: number
Default: 1
How many callers can hold the lock at once.
createFairQueue([slots=1])
The fair queue behind withFairQueue, in the same way createLock is behind withLock. The promise resolves to a release function you call when the work is done. createFairLock is this function.
One key is served in arrival order. Across keys, a free slot goes to the waiting key that has gone longest without a turn; keys that never had one go first, in arrival order. A key that still holds a slot waits behind keys that hold none. Calls that arrive while a round is being served wait until every call that was already waiting has had its turn.
A missing key shares one queue. Any other value, including null, is its own queue. null and a missing signal do not cancel. A value that is not an AbortSignal throws TypeError. Aborting after the slot was granted does nothing.
slots
Type: number
Default: 1
How many callers can hold the queue at once.
signal
Type: AbortSignal
Optional first argument. Aborting it while the call is queued resolves null and does not take a slot.
key
Type: any
Optional second argument. Identifies the queue.
withFairQueue([slots=1])
It returns a function that runs your code under fair queuing. The queue is released when the function finishes, including when it throws.