Registry / testing / lock-queue

lock-queue

JSON →
library1.0.1jsnpmunverified

A simple locking mechanism for serializing access to a resource using promises. Version 1.0.1 is the latest stable release. This package provides a Locker class that manages a queue of promise-returning functions, supporting both exclusive and non-exclusive locks. Exclusive locks block all other operations until they complete, while non-exclusive locks run concurrently. This is useful for controlling access to shared resources without full mutex complexity. It has zero runtime dependencies and is designed for Node.js environments (>=0.10.0), with no browser support. Compared to alternatives like async-lock, lock-queue offers a minimal API focused on queue-based serialization with concurrency support for non-exclusive tasks.

testing
npm install lock-queue
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · LOCK-QUEUE
L
lock-queue
testingjavascriptv1.0.1
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Locker
✓ const Locker = require('lock-queue');
✗ import Locker from 'lock-queue';
This package is CommonJS only. ESM import will fail.
locker.run(fn, ctx?)
✓ locker.run(fn, ctx);
✗ locker.run(fn.bind(ctx));
The 'ctx' argument provides the 'this' context for the function. Do not use bind() as it will be overridden.
locker.lock(fn, ctx?)
✓ locker.lock(fn, ctx);
✗ locker.run(fn, { exclusive: true });
There is no option-based API. Use the separate .lock() method for exclusive lock.

Demonstrates creating a Locker, adding non-exclusive tasks with .run(), and an exclusive task with .lock(). Tasks 1 and 2 run concurrently, exclusive 3 waits for them, then task 4 waits for 3.

const Locker = require('lock-queue'); const locker = new Locker(); async function nonExclusiveTask(id) { console.log(`Task ${id} start`); await new Promise(resolve => setTimeout(resolve, 100)); console.log(`Task ${id} end`); } async function exclusiveTask(id) { console.log(`Exclusive ${id} start`); await new Promise(resolve => setTimeout(resolve, 200)); console.log(`Exclusive ${id} end`); } locker.run(() => nonExclusiveTask(1)); locker.run(() => nonExclusiveTask(2)); locker.lock(() => exclusiveTask(3)); locker.run(() => nonExclusiveTask(4)); // Tasks 1 and 2 run concurrently. // Task 3 runs after both finish. // Task 4 runs after task 3 finishes.
Debug
Known issues
gotchaFunctions added via .lock() or .run() must return a Promise. If the function does not return a promise, the locker will not wait for it and may schedule the next item incorrectly.
fix
Ensure all functions passed to .lock() and .run() return a promise (or use async functions).
affects: >=1.0.0
gotchaThe 'ctx' parameter in .lock() and .run() sets the 'this' context for the function, but if the function is an arrow function, 'this' is lexically bound and the 'ctx' argument is ignored.
fix
Use regular functions (not arrow functions) if you need a custom 'this' context.
affects: >=1.0.0
gotchaThe package uses promises but does not provide a built-in mechanism for cancellation or timeouts. Long-running exclusive locks will block the queue indefinitely.
fix
Implement your own timeout/cancellation logic within the promise-returning function.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Locker is not a constructor
Attempting to import using ES module syntax (import Locker from 'lock-queue') which does not work for CommonJS packages.
fix
Use require('lock-queue') instead of import. Alternatively, use dynamic import() which works in ESM: const { default: Locker } = await import('lock-queue');
TypeError: locker.run is not a function
Using an outdated version (pre-1.0) where the API was different? Or incorrect instantiation? Possibly the package was not installed correctly.
fix
Ensure you have installed version 1.0.1: npm install lock-queue@1.0.1. Then require: const Locker = require('lock-queue'); const locker = new Locker();
UnhandledPromiseRejectionWarning: Error: ...
A function passed to .lock() or .run() rejected, but the returned promise was not caught.
fix
Attach a .catch() handler to the promise returned by .run() or .lock(): const promise = locker.run(fn, ctx); promise.catch(err => console.error(err));
Upgrade
Version history
1.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/overlookmotel/lock-queue ↗
packagelock-queue ↗
homepagehttps://github.com/overlookmotel/lock-queue#readme ↗
lock-queue — npm install lock-queue · libregistry