mutexify

library1.4.0jsnpmunverified

mutexify is a lightweight JavaScript library providing a mutex lock mechanism, primarily designed for Node.js environments. It ensures exclusive access to critical sections of code, guaranteeing that requests are processed in the strict order they were made, thereby preventing common race conditions in asynchronous operations. The library offers two main APIs: a traditional callback-based approach for immediate execution and a modern Promise-based alternative for cleaner `async/await` syntax. Currently at version 1.4.0, the package has maintained this version for approximately four years, suggesting a stable but slow release cadence. Its key differentiator lies in its semantic simplicity and strict adherence to ordered access, making it a straightforward and focused choice for basic locking needs without the overhead of more complex concurrency primitives like read/write locks or advanced semaphore features found in other libraries.

database

npm install mutexify

github ↗package ↗

INSTALL

IMPORT

SIG · MUTEXIFY

mutexify

databasejavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

mutexify

✓ import mutexify from 'mutexify';

✗ const mutexify = require('mutexify');

While mutexify is primarily CommonJS, modern bundlers and Node.js environments often handle CJS default exports for ESM `import` statements. The library does not natively export ESM modules. For strict CommonJS, use `require`.

mutexifyPromise

✓ import mutexifyPromise from 'mutexify/promise';

✗ const mutexifyPromise = require('mutexify/promise');

This specific import path provides the Promise-based API. Similar to the main export, it's a CommonJS module that can often be imported with `import` in ESM contexts due to tooling.

Mutexify

✓ import type { Mutexify } from 'mutexify';

✗ import { Mutexify } from 'mutexify';

TypeScript type definitions are available via `@types/mutexify`. The main package itself does not ship its own types, so `import type` is used when only importing the type.

This quickstart demonstrates the Promise-based API of mutexify, showing how multiple concurrent async operations will acquire and release the lock sequentially, ensuring ordered execution of critical sections.

import mutexify from 'mutexify/promise'; const lock = mutexify(); async function performLockedOperation(id) { console.log(`[Op ${id}] Requesting lock...`); const release = await lock(); try { console.log(`[Op ${id}] Lock acquired. Performing work...`); // Simulate some asynchronous work inside the locked section await new Promise(resolve => setTimeout(resolve, Math.random() * 500 + 200)); console.log(`[Op ${id}] Work finished.`); } finally { release(); // Ensure the lock is always released console.log(`[Op ${id}] Lock released.`); } } (async () => { console.log('Starting concurrent operations...'); // Schedule multiple operations concurrently to demonstrate mutex behavior const operations = Array.from({ length: 5 }, (_, i) => performLockedOperation(i + 1)); await Promise.all(operations); console.log('All operations completed.'); })();

Debug

Known issues

gotchaMutexify does not provide native ESM exports. It is a CommonJS module, which means direct `import` statements in pure ESM environments might require bundler configuration or Node.js's `createRequire` utility, though most modern setups handle CJS default imports automatically.

fix

For CommonJS, use `const mutexify = require('mutexify')`. For ESM, `import mutexify from 'mutexify';` often works due to transpilation or Node.js's CJS interoperability. If not, consider `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const mutexify = require('mutexify');`

affects: >=1.0.0

gotchaIt is critical to ensure that the `release()` function returned by the Promise-based API is always called, even if errors occur within the locked block. Forgetting to call `release()` will lead to a permanent deadlock, where subsequent lock requests will never resolve.

fix

Always wrap the critical section in a `try...finally` block, ensuring `release()` is called in the `finally` block to guarantee its execution regardless of success or error. Example: `const release = await lock(); try { /*...*/ } finally { release(); }`

affects: >=1.0.0

gotchaThe package has not been updated in approximately four years (as of 2026). While this indicates a stable API, it also means new features, performance optimizations, or critical bug fixes are unlikely to be released promptly. Consider its maintenance status for long-term project viability.

fix

Evaluate if the current feature set is sufficient for your project. If ongoing active development or a broader set of concurrency primitives (e.g., read-write locks, semaphores) are needed, explore more actively maintained alternatives like `async-mutex`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: mutexify is not a function

Attempting to `import mutexify from 'mutexify'` in a pure ESM environment where a bundler or Node.js's default interoperability cannot correctly resolve the CommonJS default export, resulting in `mutexify` being `undefined` or a malformed module object.

fix

If using Node.js, ensure your `package.json` either has `"type": "commonjs"` (for the file containing the import) or use `const { default: mutexify } = await import('mutexify');` or `const mutexify = require('mutexify');` within an ESM module by creating a `require` function: `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const mutexify = require('mutexify');`

Application hangs indefinitely / Code stops executing after a mutex acquisition.

The `release()` function, obtained after acquiring a lock with the Promise-based API, was not called. This leaves the mutex in a permanently locked state, preventing any subsequent lock requests from resolving.

fix

Review the code paths within your critical section and ensure that `release()` is called on every exit point, especially in error handling. The most robust solution is to use a `try...finally` block to guarantee `release()` is invoked: `const release = await lock(); try { /* protected code */ } finally { release(); }`

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

inheritsrequiredInternal utility for JavaScript prototype inheritance, used by mutexify's core implementation.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/mafintosh/mutexify ↗

packagehttps://www.npmjs.com/package/mutexify ↗