{"id":15140,"library":"mutexify","title":"mutexify","description":"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.","status":"maintenance","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/mafintosh/mutexify","tags":["javascript","mutex","lock"],"install":[{"cmd":"npm install mutexify","lang":"bash","label":"npm"},{"cmd":"yarn add mutexify","lang":"bash","label":"yarn"},{"cmd":"pnpm add mutexify","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal utility for JavaScript prototype inheritance, used by mutexify's core implementation.","package":"inherits","optional":false}],"imports":[{"note":"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`.","wrong":"const mutexify = require('mutexify');","symbol":"mutexify","correct":"import mutexify from 'mutexify';"},{"note":"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.","wrong":"const mutexifyPromise = require('mutexify/promise');","symbol":"mutexifyPromise","correct":"import mutexifyPromise from 'mutexify/promise';"},{"note":"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.","wrong":"import { Mutexify } from 'mutexify';","symbol":"Mutexify","correct":"import type { Mutexify } from 'mutexify';"}],"quickstart":{"code":"import mutexify from 'mutexify/promise';\n\nconst lock = mutexify();\n\nasync function performLockedOperation(id) {\n  console.log(`[Op ${id}] Requesting lock...`);\n  const release = await lock();\n  try {\n    console.log(`[Op ${id}] Lock acquired. Performing work...`);\n    // Simulate some asynchronous work inside the locked section\n    await new Promise(resolve => setTimeout(resolve, Math.random() * 500 + 200));\n    console.log(`[Op ${id}] Work finished.`);\n  } finally {\n    release(); // Ensure the lock is always released\n    console.log(`[Op ${id}] Lock released.`);\n  }\n}\n\n(async () => {\n  console.log('Starting concurrent operations...');\n  // Schedule multiple operations concurrently to demonstrate mutex behavior\n  const operations = Array.from({ length: 5 }, (_, i) => performLockedOperation(i + 1));\n  await Promise.all(operations);\n  console.log('All operations completed.');\n})();","lang":"typescript","description":"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."},"warnings":[{"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');`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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(); }`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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');`","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.","error":"TypeError: mutexify is not a function"},{"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(); }`","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.","error":"Application hangs indefinitely / Code stops executing after a mutex acquisition."}],"ecosystem":"npm"}