web-locks

library0.0.9jsnpmunverified

Node.js implementation of the Web Locks API that provides mutex and semaphore primitives for coordinating access to shared resources across worker threads. v0.0.9 (stable) uses worker_threads, Atomics, and SharedArrayBuffer for multi-threaded locking, with a fallback to single-threaded async locks. Supports a single unified API for both single-threaded and multi-threaded environments. Part of the Metarhia stack, targeting eventual inclusion in Node.js core. Minimal dependencies, MIT licensed.

testing

npm install web-locks

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEB-LOCKS

web-locks

testingjavascriptv0.0.9

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.

Lock

✓ import { Lock } from 'web-locks'

✗ const Lock = require('web-locks')

ESM-only; no CommonJS support. Lock is the constructor for the lock manager.

locks

✓ import { locks } from 'web-locks'

✗ const locks = require('web-locks').locks

Default instance of Lock manager. Preferred over instantiating Lock.

request

✓ await locks.request('name', async (lock) => { ... })

✗ locks.request('name', callback)

request returns a promise; must be awaited. Second argument must be an async function that returns a value.

Demonstrates basic usage: acquire a named lock, perform async work inside, and return a value. Shows promise-based API.

import { locks } from 'web-locks'; async function main() { const result = await locks.request('myResource', async (lock) => { console.log('Lock acquired'); // Simulate work await new Promise(resolve => setTimeout(resolve, 1000)); return 'done'; }); console.log('Result:', result); } main().catch(console.error);

Debug

Known issues

breakingThe library uses SharedArrayBuffer and Atomics, which require specific Node.js flags (--experimental-worker) or Node.js >= 11 with worker_threads enabled. Older versions of Node.js may crash without these features.

fix

Use Node.js >=11. Ensure your Node.js build supports SharedArrayBuffer (e.g., not disabled by security policies).

affects: >=0.0.0 <0.1.0

gotchaLock callbacks must be async functions; returning a non-promise value will not release the lock correctly.

fix

Always use async (lock) => { ... } or return a promise from the callback.

affects: >=0.0.1

gotchaThe library does not implement the exact same API as browser `navigator.locks`; for example, there is no `navigator` object, and options like `steal` and `ifAvailable` may not be fully supported.

fix

Check the documentation for differences. Use the `locks` manager from this package, not the global `navigator`.

affects: >=0.0.0

breakingIn v0.1.0, the import path changed from `require('web-locks')` to `import { locks } from 'web-locks'`. The old require syntax still works but triggers a deprecation warning.

fix

Update to ESM imports: `import { locks } from 'web-locks'`.

affects: >=0.1.0 <0.2.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'request')

Importing incorrectly or not using the default export as a manager instance.

fix

Use `import { locks } from 'web-locks'` (not `import Lock from 'web-locks'`).

Error: The shared array buffer is not enabled

Node.js version or build does not support SharedArrayBuffer (e.g., older Node.js or security restrictions).

fix

Use Node.js >=11 or run with `--enable-sharedarraybuffer` flag if needed.

UnhandledPromiseRejectionWarning: TypeError: lock is not a function

Passing a non-function or a synchronous function as the second argument to `request`.

fix

Pass an async function: `await locks.request('name', async (lock) => { ... })`.

ReferenceError: SharedArrayBuffer is not defined

Node.js version <11 or the environment does not support SharedArrayBuffer (e.g., some cloud environments).

fix

Upgrade to Node.js >=11 or use a polyfill if absolutely necessary.

Upgrade

Version history

0.0.9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/metarhia/web-locks ↗

packageweb-locks ↗

homepagehttps://github.com/metarhia/web-locks#readme ↗