Registry / storage / cross-process-lock

cross-process-lock

library2.2.0jsnpmunverified

Cross-process file locking solution with lock-queue for Node.js. Current stable version 2.2.0, released with TypeScript support. Uses file-based locking with a lock queue and configurable timeouts (lock timeout defaults to 20 minutes, wait timeout defaults to 10 seconds). Includes a convenient withLock wrapper for automatic lock/unlock. Ships TypeScript declarations. Key differentiator: simple async/await interface and lock queue mechanism rather than requiring external lock servers.

storage

npm install cross-process-lock

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CROSS-PROCESS-LOCK

cross-process-lock

storagejavascriptv2.2.0

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 'cross-process-lock'

✗ const lock = require('cross-process-lock')

lock is a named export, not default. CommonJS should use const { lock } = require('cross-process-lock')

unlock

✓ import { unlock } from 'cross-process-lock'

✗ import unlock from 'cross-process-lock'

Also a named export. unlock is imported directly, not from lock return value.

withLock

✓ import { withLock } from 'cross-process-lock'

✗ const withLock = require('cross-process-lock').withLock

Named export, available in both ESM and CJS.

lockOptions

✓ import type { lockOptions } from 'cross-process-lock'

✗ import { lockOptions } from 'cross-process-lock'

lockOptions is a TypeScript type/interface, not a runtime value. Use import type for TypeScript.

Demonstrates acquiring a lock on a file, performing a write/read operation, and releasing the lock with error handling via try/finally.

import { lock, unlock } from 'cross-process-lock'; import { writeFileSync, readFileSync } from 'fs'; async function main() { const filePath = 'data.txt'; const release = await lock(filePath, { lockTimeout: 60000, waitTimeout: 5000 }); try { writeFileSync(filePath, 'Hello from process', 'utf8'); const content = readFileSync(filePath, 'utf8'); console.log('Content:', content); } finally { await release(); } } main().catch(console.error);

Debug

Known issues

breakingIn version 2.x, lock() returns a Promise<Function> (unlock function) instead of a lock object. In version 1.x, lock() returned a Lock instance with separate .release() method.

fix

Use const release = await lock(file); call release() to unlock. For 1.x, use lock(file).then(l => l.release()).

affects: >=2.0.0

deprecatedThe unlock function directly exported (import { unlock }) is deprecated in favor of using the unlock function returned by lock().

fix

Migrate to using the release function returned by lock().

affects: >=2.0.0

gotchaLock files are created on disk in the same directory as the target file. Ensure the directory is writable and that concurrent processes use the same file path.

fix

Use absolute paths for consistency across processes.

affects: all

gotchaThe lock timeout (lockTimeout) default is 20 minutes, not infinite. If a process crashes without releasing, the lock will auto-release after this timeout.

fix

Set lockTimeout to a higher value if needed, but be aware of stale locks.

affects: all

gotchawaitTimeout defaults to 10 seconds. If lock cannot be acquired within that time, the promise rejects. Do not set waitTimeout too low in high-concurrency scenarios.

fix

Adjust waitTimeout according to expected contention.

affects: all

Errors

Common errors & fixes

TypeError: lock is not a function

Importing default instead of named export (e.g., const lock = require('cross-process-lock') instead of const { lock } = require('cross-process-lock')).

fix

Use const { lock } = require('cross-process-lock') or import { lock } from 'cross-process-lock'.

Error: ENOENT: no such file or directory, open '/some/path/.lock'

The directory for the lock file does not exist or is not writable. The lock file is created in the same directory as the target file with a .lock extension.

fix

Ensure the directory exists and is writable, or use an absolute path for the target file.

TimeoutError: Could not acquire lock for 'file.txt' within 10000ms

Another process holds the lock and did not release within the waitTimeout (default 10 seconds).

fix

Increase waitTimeout, or check that the other process releases the lock promptly.

Error: lock file for 'file.txt' already exists

A stale lock file was left behind (e.g., after a crash). Only happens if a previous lock was not cleaned up.

fix

Manually delete the .lock file if you are sure no other process holds it.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

debugoptionalUsed for debug logging with namespace cross-process-lock:PID

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/szikszail/cross-process-lock ↗

packagecross-process-lock ↗

homepagehttps://github.com/szikszail/cross-process-lock#readme ↗