proper-lockfile concurrent locking: working versions (tested 2026-10-16)

{
  "name": "proper-lockfile-concurrent",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --import tsx --test test/*.test.ts"
  },
  "dependencies": {
    "proper-lockfile": "4.1.2"
  },
  "devDependencies": {
    "@types/node": "26.6.5",
    "tsx": "4.23.15"
  }
}

import lockfile from "proper-lockfile";

export type Release = () => Promise<void>;

export interface AcquireOptions {
  retries?: number;
  stale?: number;
}

export function acquire(file: string, options: AcquireOptions = {}): Promise<Release> {
  return lockfile.lock(file, {
    retries: options.retries ?? 0,
    stale: options.stale ?? 10000,
  });
}

export function acquireWithRetry(file: string, retries = 100): Promise<Release> {
  return lockfile.lock(file, {
    stale: 10000,
    retries: { retries, factor: 1, minTimeout: 10, maxTimeout: 20 },
  });
}

export function acquireSync(file: string, stale = 10000): () => void {
  return lockfile.lockSync(file, { stale });
}

export async function isLocked(file: string, stale = 10000): Promise<boolean> {
  return lockfile.check(file, { stale });
}

declare module "proper-lockfile" {
  export interface RetryOptions {
    retries?: number;
    factor?: number;
    minTimeout?: number;
    maxTimeout?: number;
  }

  export interface LockOptions {
    stale?: number;
    update?: number;
    retries?: number | RetryOptions;
    realpath?: boolean;
    onCompromised?: (error: Error) => void;
  }

  export type Release = () => Promise<void>;

  export function lock(file: string, options?: LockOptions): Promise<Release>;
  export function lockSync(file: string, options?: LockOptions): () => void;
  export function check(file: string, options?: LockOptions): Promise<boolean>;
  export function unlock(file: string, options?: LockOptions): Promise<void>;

  const lockfile: {
    lock: typeof lock;
    lockSync: typeof lockSync;
    check: typeof check;
    unlock: typeof unlock;
  };

  export default lockfile;
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { mkdtemp, writeFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { acquire, acquireSync, acquireWithRetry, isLocked } from "../src/lock.ts";

async function makeTempFile(): Promise<{ dir: string; file: string }> {
  const dir = await mkdtemp(join(tmpdir(), "proper-lockfile-"));
  const file = join(dir, "data.txt");
  await writeFile(file, "payload");
  return { dir, file };
}

test("a second lock on the same file is rejected while the first is held", async () => {
  const { dir, file } = await makeTempFile();
  try {
    const release = await acquire(file);
    assert.equal(await isLocked(file), true);
    await assert.rejects(() => acquire(file));
    await release();
    assert.equal(await isLocked(file), false);
    const again = await acquire(file);
    await again();
  } finally {
    await rm(dir, { recursive: true, force: true });
  }
});

test("acquireWithRetry waits for the holder to release", async () => {
  const { dir, file } = await makeTempFile();
  try {
    const release = await acquire(file);
    let acquiredAt = 0;
    const pending = acquireWithRetry(file).then(async (rel) => {
      acquiredAt = Date.now();
      await rel();
    });
    await new Promise((resolve) => setTimeout(resolve, 40));
    assert.equal(acquiredAt, 0);
    await release();
    await pending;
    assert.ok(acquiredAt > 0);
  } finally {
    await rm(dir, { recursive: true, force: true });
  }
});

test("lockSync release and check reflect the lock state", async () => {
  const { dir, file } = await makeTempFile();
  try {
    const release = acquireSync(file);
    assert.equal(await isLocked(file), true);
    release();
    assert.equal(await isLocked(file), false);
  } finally {
    await rm(dir, { recursive: true, force: true });
  }
});