Inter-Process Lockfile Utility

Common errors

• Error: Lock file is already being held

  cause Another process currently holds the lock, and the current attempt to acquire it did not succeed within the configured retries/timeout.
  fix Handle the `ELOCKED` error code (if available) or the general error by implementing retry logic with exponential backoff or waiting for the lock to be released. Configure the `retries` option for `lock()`.

• Error: Lock was already compromised

  cause The lockfile's integrity check failed during a background update, or it was manually removed, indicating the lock is no longer reliably held by this process. This error can be thrown by the `onCompromised` callback or when `release()` is called on a compromised lock.
  fix Implement robust error handling in the `onCompromised` callback and for the `release()` promise. This usually indicates a critical state requiring process termination or immediate re-evaluation of resource access.

• Error: ENOENT: no such file or directory, lstat 'path/to/file.txt.lock'

  cause The base file (e.g., 'path/to/file.txt') did not exist when `lock()` or `check()` was called, and `realpath` option is true (default). `proper-lockfile` expects the target file to exist to resolve its real path and create the `.lock` file alongside it.
  fix Ensure the target file you intend to lock exists before calling `lock()` or `check()`. Use `fs.promises.writeFile(filePath, '', { flag: 'a+' })` to create it if it doesn't exist.

Warnings

• gotcha Using different `stale` or `update` option values for the same file across different processes can lead to race conditions and multiple processes acquiring what they believe is an exclusive lock.
  Fix: Ensure consistent `stale` and `update` options are used for a given lockable file across all processes accessing it. Store these values in a shared configuration.
• gotcha Manual removal of a lockfile by an external process or user can lead to the lock being compromised. `proper-lockfile` detects certain compromises (failed updates) but cannot detect external, arbitrary deletions which would allow another process to acquire a lock immediately after.
  Fix: Avoid direct manipulation of `.lock` files. Always use the library's `release()` or `unlock()` functions. Implement robust error handling for `onCompromised` callbacks.
• gotcha The `release()` function returned by `lock()` can reject its promise if the lock has been compromised (e.g., updates failed, or it became stale). Consumers must handle this rejection to prevent unhandled promise rejections or misinterpretations of lock status.
  Fix: Always `await` or `.catch()` the promise returned by the `release()` function and implement appropriate error recovery or logging.
• gotcha The default `stale` option is 10 seconds (10000ms), with a minimum of 5 seconds (5000ms). Setting `stale` too low for long-running operations or processes with high latency can cause locks to be considered stale prematurely.
  Fix: Adjust the `stale` option according to the expected maximum duration of the critical section and the network/filesystem characteristics. The `update` interval (default `stale/2`) should also be considered.

Install

• npm install proper-lockfile npm
• yarn add proper-lockfile yarn
• pnpm add proper-lockfile pnpm

Imports

• lock
  wrong:

  const lock = require('proper-lockfile').lock;

  correct:

  import { lock } from 'proper-lockfile';

  The default export from 'proper-lockfile' is also the `lock` function, so `import lock from 'proper-lockfile';` is also common. Named imports are preferred for clarity.
• unlock
  wrong:

  const unlock = require('proper-lockfile').unlock;

  correct:

  import { unlock } from 'proper-lockfile';

  While `lock` returns a `release` function, `unlock` provides a direct API to remove a lock if the `release` function reference is lost or cannot be used.
• check
  wrong:

  const check = require('proper-lockfile').check;

  correct:

  import { check } from 'proper-lockfile';

  Used to synchronously or asynchronously check if a file is currently locked and not stale.

Quickstart

Demonstrates how to acquire, use, and release an inter-process lock on a file using asynchronous functions, including error handling and retry options. It also shows basic file system interaction.

import { lock, unlock } from 'proper-lockfile';
import { promises as fs } from 'fs';
import path from 'path';

const filePath = path.join(process.cwd(), 'my-resource.txt');
const lockFileOptions = {
  stale: 15000, // Consider lock stale after 15 seconds
  update: 5000, // Update mtime every 5 seconds
  retries: {
    retries: 5,
    factor: 2,
    minTimeout: 1000,
    maxTimeout: 10000,
    randomize: true,
  },
  onCompromised: (err) => {
    console.error('Lock was compromised:', err.message);
    // Implement critical error handling here, e.g., exit process
    process.exit(1);
  },
};

async function accessResourceWithLock() {
  let release;
  try {
    // Ensure the target file exists before trying to lock it
    await fs.writeFile(filePath, 'Initial content.', { flag: 'a+' });

    console.log('Attempting to acquire lock...');
    release = await lock(filePath, lockFileOptions);
    console.log('Lock acquired. Performing sensitive operation...');

    // Simulate work
    await new Promise(resolve => setTimeout(resolve, Math.random() * 3000 + 1000));
    await fs.appendFile(filePath, `\nAccessed at ${new Date().toISOString()} by process ${process.pid}`);

    console.log('Sensitive operation complete. Releasing lock...');
  } catch (error) {
    console.error('Failed to acquire or release lock:', error.message);
    if (error.code === 'ELOCKED') {
      console.warn('File is already locked by another process.');
    }
  } finally {
    if (release) {
      try {
        await release();
        console.log('Lock released successfully.');
      } catch (error) {
        console.error('Error releasing lock:', error.message);
      }
    } else {
        // If lock was never acquired, or release failed (e.g. compromised), ensure cleanup.
        // In a real scenario, you might also attempt `unlock(filePath)` here if `release` failed
        // but only if you are confident it's safe to force-unlock.
        console.log('No release function available or lock acquisition failed. No explicit release needed/possible.');
    }
  }
}

accessResourceWithLock();