mutexify

Common errors

• TypeError: mutexify is not a function

  cause 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.

  cause 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(); }`

Warnings

• gotcha Mutexify 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');`
• gotcha It 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(); }`
• gotcha The 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`.

Install

• npm install mutexify npm
• yarn add mutexify yarn
• pnpm add mutexify pnpm

Imports

• mutexify
  wrong:

  const mutexify = require('mutexify');

  correct:

  import mutexify from '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
  wrong:

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

  correct:

  import mutexifyPromise from '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
  wrong:

  import { Mutexify } from 'mutexify';

  correct:

  import type { 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.

Quickstart

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.');
})();