npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

superlock

v1.4.14

Published

The minimal Node.js concurrency toolkit: mutex, semaphore and fair queue for async/await, with no dependencies.

Readme

Why

superlock aims to be:

  • Simple: Designed for usage with async and await
  • Powerful: Mutex, semaphore, and fair queuing
  • Secure: Auto lock release to avoid deadlocks
  • Lightweight: No dependencies
  • Well-tested: 100% code coverage

Install

$ npm install superlock --save

Usage

as mutex

The lock is a mutex by default: one caller holds it, the rest wait in arrival order.

const { setTimeout } = require('timers/promises')
const { withLock } = require('superlock')

const lock = withLock()

const executions = await Promise.all(
  [...Array(10).keys()].map(index =>
    lock(async () => {
      await setTimeout(Math.random() * 100)
      return index
    })
  )
)

console.log(executions)

as semaphore

Call withLock(n) with n as the maximum concurrency for the lock. Up to n callers hold it at once; a freed slot goes to the oldest waiter:

const { setTimeout } = require('timers/promises')
const { withLock } = require('superlock')

const lock = withLock(2)

const executions = await Promise.all(
  [...Array(10).keys()].map(index =>
    lock(async () => {
      await setTimeout(Math.random() * 100)
      return index
    })
  )
)

console.log(executions)

as fair queue

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.

const { withFairQueue } = require('superlock')

const queue = withFairQueue()

await queue(async () => {
  /* your code execution */
}, userId)

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 back
controller.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:

const { withLock } = require('superlock')

const lock = withLock()

await lock(() => {
  /* your code execution */
})

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:

const { createLock } = require('superlock')

const lock = createLock()
const release = await lock()

try {
  /* your code execution */
} finally {
  release()
}

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.

const { createFairQueue } = require('superlock')

const queue = createFairQueue()
const release = await queue(undefined, key)

release()

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.

const { withFairQueue } = require('superlock')

const queue = withFairQueue()

await queue(() => {
  /* your code execution */
}, key)

An AbortSignal is an optional third argument:

await queue(() => {
  /* your code execution */
}, key, signal)

If signal aborts while the call is still queued, the function is skipped and the call resolves undefined.

slots

Type: number Default: 1

How many callers can hold the queue at once.

key

Type: any

Optional second argument. Identifies the queue. A missing key shares one queue.

signal

Type: AbortSignal

Optional third argument. Aborting it while the call is queued skips the function.

.isLocked()

Type: boolean

It returns false if there is at least one free concurrency slots in the lock. createLock, createFairQueue, and withFairQueue expose it too.

.awaiting()

Type: number

How many callers are waiting for a slot. On a fair queue that is the total across every key.

License

superlock © Microlink, released under the MIT License. Authored and maintained by Kiko Beats with help from contributors.

microlink.io · GitHub microlinkhq · X @microlinkhq