loqkit 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reggie Brooks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# loqkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed memoization and layered locking for JavaScript runtimes.
+
+## Locking
+
+```ts
+import { withLock } from "loqkit";
+
+const result = await withLock(
+  { resource: "cache" },
+  async ({ resource, lock }) => {
+    console.log(`locked ${resource} with ${lock.backends.length} layers`);
+  },
+  {
+    key: "cache-refresh",
+    predicate: async ({ resource, state }) => {
+      return state === "predicate-after"
+        ? await stillNeedsRefresh(resource)
+        : true;
+    },
+    onCheckFailed: async ({ resource, state }) => {
+      console.log(`${resource} skipped in ${state}`);
+    },
+  },
+);
+
+console.log(result.value, result.context.state, result.context.lock.waitedMs);
+```
+
+By default, `withLock` acquires memory, worker-thread, and file locks for the same key. The argument after the action can be a predicate function or an options object containing `predicate`. The predicate runs once before waiting and again after all three layers are held. The action runs only when both checks pass.
+
+Every callback receives `ctx.state`: `"predicate-before"` for the first check, `"predicate-after"` for the check after acquisition, and `"executed"` for the action. `ctx.acquired` is the corresponding convenience boolean. When either check fails, `onCheckFailed(ctx)` runs after any acquired layers have been released. It can inspect `ctx.state`, log, reread data, or start other lock work without holding this lock. For this hook, `acquired` describes the context snapshot; it does not mean the hook currently holds the lock.
+
+`withLock` returns `{ value, context }`. `value` is the action's result, or `undefined` when the action did not run. The returned context has the same fields and state values as a callback context, with `"timeout"` added because a non-throwing timeout can only be observed in the result. Lock metadata, including wait time, is available on `result.context.lock`.
+
+Omitting `timeout` waits indefinitely. A numeric timeout throws `LockTimeoutError` when it expires. Use the object form to return a timeout result instead. A zero timeout makes one non-blocking acquisition attempt and never sleeps or polls a second time:
+
+```ts
+const attempt = await withLock(context, action, {
+  timeout: { ms: 0, error: false },
+});
+
+if (attempt.context.state === "timeout") {
+  console.log("Lock is busy");
+}
+```
+
+Use a narrower scope only when you deliberately need one boundary:
+
+```ts
+await withLock(context, action, { scope: "memory" });
+await withLock(context, action, { scope: ["memory", "file"] });
+```
+
+`scope` accepts one backend or a non-empty array. Omit it to acquire all three. Selected layers always run in `memory`, `worker`, `file` order regardless of the array's input order.
+
+## Memoization
+
+`memoize` turns a zero-argument factory into a getter that computes once and reuses its successful result. A synchronous factory stays synchronous. An asynchronous or thenable factory returns a native promise, and concurrent callers share the same in-flight work.
+
+```ts
+import { memoize } from "loqkit";
+
+const getConfig = memoize(() => ({ region: "us-east-1" }));
+const config = getConfig();
+
+const getCatalog = memoize(async () => {
+  const response = await fetch("https://example.com/catalog.json");
+  return response.json();
+});
+
+const catalog = await getCatalog();
+```
+
+Successful results remain cached for the lifetime of the memoized getter. Thrown errors and rejected promises are not cached, so the next call retries. There is no TTL or expiration behavior.
+
+```mermaid
+flowchart TD
+    call["Call memoized getter"] --> cached{"Successful result cached?"}
+    cached -- "Yes" --> reuse["Return cached value or promise"]
+    cached -- "No" --> factory["Run factory"]
+    factory --> kind{"Thenable result?"}
+    kind -- "No" --> storeValue["Cache and return value"]
+    kind -- "Yes" --> storePromise["Cache and return in-flight promise"]
+    storePromise --> outcome{"Promise outcome"}
+    outcome -- "Resolved" --> keep["Keep successful promise"]
+    outcome -- "Rejected" --> evict["Evict so the next call retries"]
+```
+
+## How locking works
+
+`withLock` is a key-scoped lock. Calls with the same namespace and key run one at a time; calls with different keys can run concurrently. If no key is supplied, loqkit hashes the context into a stable key.
+
+When `scope` is omitted, loqkit acquires these layers in order and releases them in reverse:
+
+1. An in-memory [`async-mutex`](https://github.com/DirtyHairy/async-mutex) lock serializes callers in the current JavaScript isolate.
+2. Node's worker lock manager coordinates worker threads when the runtime provides it. In the default layered mode, the file layer still preserves coordination when that API is unavailable; an explicit worker-only lock reports `LockUnavailableError` instead.
+3. A file lock coordinates processes on the same host. On macOS and Linux, `fileStrategy: "auto"` prefers the optional native [`fs-ext`](https://github.com/baudehlo/node-fs-ext) `flock` implementation. If native locking is unavailable or acquisition fails—for example, because a network filesystem does not support `flock`—loqkit transparently falls back to [`proper-lockfile`](https://github.com/moxystudio/node-proper-lockfile) polling.
+
+`fileStrategy: "auto"` is the default and the only mode that falls back from native `flock` to portable polling. Set `fileStrategy: "flock"` to require native locking; it throws `LockUnavailableError` when native support is unavailable or acquisition fails. Set `fileStrategy: "poll"` to skip native locking entirely. A contention response stays on `flock`; switching protocols while another caller holds a native lock would break exclusivity. Filesystems that incorrectly report a successful native lock cannot be detected, so configure `"poll"` for a network mount known to have unreliable `flock` semantics. `lockDirectory` or `LOQKIT_LOCK_DIR` controls where file locks are stored.
+
+```mermaid
+flowchart TD
+    call["Call withLock"] --> options["Validate options and choose a key"]
+    options --> checking["Create predicate-before context"]
+    checking --> before{"Predicate passes before waiting?"}
+    before -- "No" --> failedBefore["Run onCheckFailed without a lock"]
+    failedBefore --> skippedBefore["Return predicate-before context"]
+    before -- "Yes or absent" --> memory["Acquire memory lock"]
+    memory --> worker["Acquire worker-thread lock"]
+    worker --> file["Acquire native flock or polling file lock"]
+    memory -. "Timeout" .-> timeout{"timeout.error?"}
+    worker -. "Timeout" .-> timeout
+    file -. "Timeout" .-> timeout
+    timeout -- "Yes" --> timeoutError["Throw LockTimeoutError"]
+    timeout -- "No" --> timeoutResult["Return timeout context"]
+    file --> acquired["Create predicate-after context with all layers acquired"]
+    acquired --> after{"Predicate still passes?"}
+    after -- "No" --> releaseFailed["Release all layers"]
+    releaseFailed --> failedAfter["Run onCheckFailed without a lock"]
+    failedAfter --> skippedAfter["Return predicate-after context"]
+    after -- "Yes or absent" --> action["Run action with executed context"]
+    action --> release["Release file, worker, then memory"]
+    release --> result["Return value and executed context"]
+```
+
+The second predicate check matters when another caller changes the underlying state while this caller is waiting:
+
+```mermaid
+sequenceDiagram
+    participant A as Caller A
+    participant B as Caller B
+    participant L as Layered lock for one key
+
+    A->>L: Acquire memory, worker, file
+    L-->>A: Granted
+    B->>B: Check predicate
+    B->>L: Acquire same layers
+    Note over B,L: Caller B waits
+    A->>A: Run action
+    A-->>L: Release all layers
+    L-->>B: Granted
+    B->>B: Check predicate again
+    B->>B: Run action if still needed
+    B-->>L: Release all layers
+```
+
+The default file directory is local to the host. Containers coordinate only when they share the configured lock directory, and separate hosts still need a shared lock service or database-backed lock.
+
+## Releasing
+
+Run `bun run release` from a clean, synchronized `main` branch. Patch is the default increment; `minor`, `major`, and `--dry-run` are also supported. The existing untagged npm `0.0.1` requires the one-time bootstrap form `bun run release -- --initial`.
+
+The local command verifies the Git identity, derives the next version from remote GitHub tags, runs the full suite, and audits the package archive before atomically pushing the release commit and tag. [The tag workflow](.github/workflows/publish.yml) repeats verification because release tags are not protected, then publishes the exact audited archive through npm Trusted Publishing with provenance. It does not use an npm token.

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "loqkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Typed memoization and layered memory, worker-thread, and file locks for JavaScript runtimes.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/regbo/loqkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/regbo/loqkit/issues"
+  },
+  "homepage": "https://github.com/regbo/loqkit#readme",
+  "type": "module",
+  "packageManager": "bun@1.4.4",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./release/index.d.ts",
+      "import": "./release/index.js"
+    }
+  },
+  "types": "./release/index.d.ts",
+  "files": [
+    "release",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "bun run typecheck && bun test && bun run build",
+    "prepack": "bun scripts/prepack.ts",
+    "release": "bun scripts/release.ts",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "lock",
+    "mutex",
+    "concurrency",
+    "flock",
+    "lockfile",
+    "worker-threads",
+    "memoization",
+    "memoize",
+    "typescript"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "async-mutex": "^0.5.0",
+    "ohash": "^2.0.12",
+    "proper-lockfile": "^4.1.2",
+    "read-package-up": "^12.0.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/fs-ext": "^2.0.3",
+    "@types/node": "^26.6.6",
+    "@types/proper-lockfile": "^4.1.4",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "fs-ext": "^2.1.1"
+  }
+}

package/release/backends/file.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedLockOptionsData } from "../schemas.js";
+import type { LockInfo } from "../types.js";
+import type { PreparedBackend } from "./types.js";
+interface FsExt {
+    flock(fileDescriptor: number, flags: "exnb" | "un", callback: (error?: NodeJS.ErrnoException | null) => void): void;
+}
+interface FileBackendDependencies {
+    readonly loadFsExt: () => Promise<FsExt | undefined>;
+}
+export declare function prepareFileBackend(info: Readonly<LockInfo>, options: ResolvedLockOptionsData, fileBase: string, dependencies?: FileBackendDependencies): Promise<PreparedBackend>;
+export {};

package/release/backends/file.js

@@ -0,0 +1,142 @@
+import { mkdir, open } from "node:fs/promises";
+import { dirname } from "node:path";
+import lockfile from "proper-lockfile";
+import { LockUnavailableError } from "../errors.js";
+import { throwIfAborted, waitForRetry } from "../waiting.js";
+async function loadFsExt() {
+    if (process.platform === "win32")
+        return undefined;
+    try {
+        const imported = (await import("fs-ext"));
+        const candidate = imported.flock
+            ? { flock: imported.flock }
+            : imported.default;
+        return candidate && typeof candidate.flock === "function"
+            ? candidate
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function callFlock(fsExt, fileDescriptor, flags) {
+    return new Promise((resolve, reject) => {
+        fsExt.flock(fileDescriptor, flags, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+function isBusy(error) {
+    const code = error?.code;
+    return code === "EAGAIN" || code === "EWOULDBLOCK" || code === "EACCES";
+}
+function isPollingContention(error) {
+    return error?.code === "ELOCKED";
+}
+function preparePollingBackend(info, options, file, fallback) {
+    const target = `${file}.target`;
+    const details = {
+        scope: "file",
+        type: "poll",
+        file,
+        ...(fallback ? { fallback } : {}),
+    };
+    return {
+        initial: details,
+        async run(callback) {
+            await mkdir(dirname(file), { recursive: true });
+            const targetHandle = await open(target, "a");
+            await targetHandle.close();
+            const startedAt = Date.now();
+            while (true) {
+                throwIfAborted(options.signal, info);
+                let release;
+                try {
+                    release = await lockfile.lock(target, {
+                        lockfilePath: file,
+                        realpath: false,
+                        retries: 0,
+                        stale: options.staleMs,
+                    });
+                }
+                catch (error) {
+                    if (!isPollingContention(error))
+                        throw error;
+                    await waitForRetry(startedAt, options.timeout?.ms, options.pollIntervalMs, options.signal, info);
+                    continue;
+                }
+                try {
+                    return await callback(details);
+                }
+                finally {
+                    await release();
+                }
+            }
+        },
+    };
+}
+function prepareFlockBackend(fsExt, info, options, file, pollingFallback) {
+    const details = {
+        scope: "file",
+        type: "flock",
+        file,
+    };
+    return {
+        initial: details,
+        async run(callback) {
+            await mkdir(dirname(file), { recursive: true });
+            const handle = await open(file, "a+");
+            const startedAt = Date.now();
+            try {
+                while (true) {
+                    throwIfAborted(options.signal, info);
+                    try {
+                        await callFlock(fsExt, handle.fd, "exnb");
+                        break;
+                    }
+                    catch (error) {
+                        if (isBusy(error)) {
+                            await waitForRetry(startedAt, options.timeout?.ms, options.pollIntervalMs, options.signal, info);
+                            continue;
+                        }
+                        // Never switch protocols for contention: a proper-lockfile lock
+                        // would not see the flock already held by another caller.
+                        if (pollingFallback) {
+                            await handle.close();
+                            return pollingFallback.run(callback);
+                        }
+                        throw new LockUnavailableError(info, "native flock acquisition failed", error);
+                    }
+                }
+                try {
+                    return await callback(details);
+                }
+                finally {
+                    await callFlock(fsExt, handle.fd, "un");
+                }
+            }
+            finally {
+                await handle.close().catch(() => undefined);
+            }
+        },
+    };
+}
+export async function prepareFileBackend(info, options, fileBase, dependencies = { loadFsExt }) {
+    const pollFile = `${fileBase}.poll.lock`;
+    const polling = preparePollingBackend(info, options, pollFile);
+    if (options.fileStrategy === "poll")
+        return polling;
+    const fsExt = await dependencies.loadFsExt();
+    if (!fsExt) {
+        if (options.fileStrategy === "flock") {
+            throw new LockUnavailableError(info, "native flock is unavailable on this platform");
+        }
+        return preparePollingBackend(info, options, pollFile, "native-flock-unavailable");
+    }
+    const flockFile = `${fileBase}.flock`;
+    const fallback = preparePollingBackend(info, options, pollFile, "native-flock-failed");
+    return prepareFlockBackend(fsExt, info, options, flockFile, options.fileStrategy === "auto" ? fallback : undefined);
+}

package/release/backends/memory.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedLockOptionsData } from "../schemas.js";
+import type { LockBackendInfo, LockInfo } from "../types.js";
+import type { PreparedBackend } from "./types.js";
+export declare function prepareMemoryBackend(info: Readonly<LockInfo>, options: ResolvedLockOptionsData, details?: Readonly<LockBackendInfo>): PreparedBackend;

package/release/backends/memory.js

@@ -0,0 +1,45 @@
+import { Mutex } from "async-mutex";
+import { acquireWithLimits } from "../waiting.js";
+const mutexes = new Map();
+function retainMutex(id) {
+    let entry = mutexes.get(id);
+    if (!entry) {
+        entry = { mutex: new Mutex(), users: 0 };
+        mutexes.set(id, entry);
+    }
+    entry.users += 1;
+    return entry;
+}
+function releaseMutexReference(id, entry) {
+    entry.users -= 1;
+    deleteUnusedMutex(id, entry);
+}
+function deleteUnusedMutex(id, entry) {
+    if (entry.users === 0 && !entry.mutex.isLocked()) {
+        mutexes.delete(id);
+    }
+}
+export function prepareMemoryBackend(info, options, details = {
+    scope: "memory",
+    type: "memory",
+}) {
+    return {
+        initial: details,
+        async run(callback) {
+            const entry = retainMutex(info.id);
+            const acquisition = entry.mutex.acquire();
+            let release;
+            try {
+                release = await acquireWithLimits(acquisition, options.timeout?.ms, options.signal, info, (lateRelease) => {
+                    lateRelease();
+                    deleteUnusedMutex(info.id, entry);
+                });
+                return await callback(details);
+            }
+            finally {
+                release?.();
+                releaseMutexReference(info.id, entry);
+            }
+        },
+    };
+}

package/release/backends/types.d.ts

@@ -0,0 +1,5 @@
+import type { LockBackendInfo } from "../types.js";
+export interface PreparedBackend {
+    readonly initial: Readonly<LockBackendInfo>;
+    run<TResult>(callback: (details: Readonly<LockBackendInfo>) => Promise<TResult>): Promise<TResult>;
+}

package/release/backends/types.js

@@ -0,0 +1 @@
+export {};

package/release/backends/worker.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedLockOptionsData } from "../schemas.js";
+import type { LockInfo } from "../types.js";
+import type { PreparedBackend } from "./types.js";
+export declare function prepareWorkerBackend(info: Readonly<LockInfo>, options: ResolvedLockOptionsData, fileLayerSelected?: boolean): PreparedBackend;

package/release/backends/worker.js

@@ -0,0 +1,87 @@
+import * as workerThreads from "node:worker_threads";
+import { LockAbortedError, LockTimeoutError, LockUnavailableError, } from "../errors.js";
+function getWorkerLocks() {
+    const candidate = workerThreads
+        .locks;
+    return candidate && typeof candidate.request === "function"
+        ? candidate
+        : undefined;
+}
+function passThroughBackend(details) {
+    return {
+        initial: details,
+        async run(callback) {
+            return callback(details);
+        },
+    };
+}
+export function prepareWorkerBackend(info, options, fileLayerSelected = false) {
+    const locks = getWorkerLocks();
+    if (!locks) {
+        const fallback = {
+            scope: "worker",
+            type: "skipped",
+            fallback: "worker-locks-unavailable-file-layer-selected",
+        };
+        if (fileLayerSelected)
+            return passThroughBackend(fallback);
+        throw new LockUnavailableError(info, "the runtime does not provide worker_threads.locks");
+    }
+    const details = {
+        scope: "worker",
+        type: "worker",
+    };
+    return {
+        initial: details,
+        async run(callback) {
+            const controller = new AbortController();
+            let acquired = false;
+            let timedOut = false;
+            let timer;
+            const abortFromCaller = () => controller.abort(options.signal?.reason);
+            if (options.signal?.aborted) {
+                throw new LockAbortedError(info, options.signal.reason);
+            }
+            options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+            const stopWaiting = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                options.signal?.removeEventListener("abort", abortFromCaller);
+            };
+            if (options.timeout && options.timeout.ms > 0) {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    controller.abort();
+                }, options.timeout.ms);
+                timer.unref?.();
+            }
+            try {
+                return await locks.request(info.id, {
+                    mode: "exclusive",
+                    ifAvailable: options.timeout?.ms === 0,
+                    signal: controller.signal,
+                }, async (lock) => {
+                    if (!lock)
+                        throw new LockTimeoutError(info, options.timeout.ms);
+                    acquired = true;
+                    stopWaiting();
+                    return callback(details);
+                });
+            }
+            catch (error) {
+                if (!acquired && timedOut) {
+                    throw new LockTimeoutError(info, options.timeout.ms);
+                }
+                if (!acquired && options.signal?.aborted) {
+                    throw new LockAbortedError(info, options.signal.reason);
+                }
+                throw error;
+            }
+            finally {
+                stopWaiting();
+            }
+        },
+    };
+}

package/release/errors.d.ts

@@ -0,0 +1,19 @@
+import type { LockInfo } from "./types.js";
+declare abstract class LoqkitError extends Error {
+    readonly lock: Readonly<LockInfo>;
+    abstract readonly code: string;
+    constructor(message: string, lock: Readonly<LockInfo>, options?: ErrorOptions);
+}
+export declare class LockTimeoutError extends LoqkitError {
+    readonly code = "LOQKIT_TIMEOUT";
+    constructor(lock: Readonly<LockInfo>, timeoutMs: number);
+}
+export declare class LockAbortedError extends LoqkitError {
+    readonly code = "LOQKIT_ABORTED";
+    constructor(lock: Readonly<LockInfo>, cause?: unknown);
+}
+export declare class LockUnavailableError extends LoqkitError {
+    readonly code = "LOQKIT_UNAVAILABLE";
+    constructor(lock: Readonly<LockInfo>, detail: string, cause?: unknown);
+}
+export {};

package/release/errors.js

@@ -0,0 +1,26 @@
+class LoqkitError extends Error {
+    lock;
+    constructor(message, lock, options) {
+        super(message, options);
+        this.lock = lock;
+        this.name = new.target.name;
+    }
+}
+export class LockTimeoutError extends LoqkitError {
+    code = "LOQKIT_TIMEOUT";
+    constructor(lock, timeoutMs) {
+        super(`Timed out after ${timeoutMs}ms waiting for lock "${lock.name}"`, lock);
+    }
+}
+export class LockAbortedError extends LoqkitError {
+    code = "LOQKIT_ABORTED";
+    constructor(lock, cause) {
+        super(`Waiting for lock "${lock.name}" was aborted`, lock, { cause });
+    }
+}
+export class LockUnavailableError extends LoqkitError {
+    code = "LOQKIT_UNAVAILABLE";
+    constructor(lock, detail, cause) {
+        super(`Lock "${lock.name}" is unavailable: ${detail}`, lock, { cause });
+    }
+}

package/release/identity.d.ts

@@ -0,0 +1,9 @@
+import type { ResolvedLockOptionsData } from "./schemas.js";
+export declare function resolveNamespace(options: ResolvedLockOptionsData): Promise<string>;
+export declare function resolveLockDirectory(options: ResolvedLockOptionsData): string;
+export declare function createLockIdentity(context: object, options: ResolvedLockOptionsData): Promise<{
+    id: string;
+    name: string;
+    namespace: string;
+    fileBase: string;
+}>;

package/release/identity.js

@@ -0,0 +1,41 @@
+import { tmpdir } from "node:os";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import { hash } from "ohash";
+import { readPackageUp } from "read-package-up";
+const namespaceCache = new Map();
+async function discoverNamespace(cwd) {
+    const packageResult = await readPackageUp({ cwd });
+    const packageName = packageResult?.packageJson.name;
+    if (typeof packageName === "string" && packageName.length > 0) {
+        return packageName;
+    }
+    return basename(resolve(cwd)) || "default";
+}
+export async function resolveNamespace(options) {
+    if (options.namespace)
+        return options.namespace;
+    const environmentNamespace = process.env.LOQKIT_NAMESPACE?.trim();
+    if (environmentNamespace)
+        return environmentNamespace;
+    const cwd = resolve(options.cwd);
+    let pending = namespaceCache.get(cwd);
+    if (!pending) {
+        pending = discoverNamespace(cwd);
+        namespaceCache.set(cwd, pending);
+    }
+    return pending;
+}
+export function resolveLockDirectory(options) {
+    const configured = options.lockDirectory ??
+        process.env.LOQKIT_LOCK_DIR?.trim() ??
+        join(tmpdir(), "loqkit");
+    return isAbsolute(configured) ? configured : resolve(options.cwd, configured);
+}
+export async function createLockIdentity(context, options) {
+    const namespace = await resolveNamespace(options);
+    const id = hash({ namespace, key: options.key ?? context });
+    const name = options.name ?? id.slice(0, 12);
+    const namespaceDirectory = hash(namespace).slice(0, 12);
+    const fileBase = join(resolveLockDirectory(options), namespaceDirectory, id);
+    return { id, name, namespace, fileBase };
+}

package/release/index.d.ts

@@ -0,0 +1,16 @@
+import type { WithLock } from "./types.js";
+/**
+ * Runs an action with exclusive access to a deterministic lock.
+ *
+ * By default, memory, worker-thread, and cross-process file layers are held in
+ * that order. When supplied, the predicate runs before waiting and again after
+ * every requested layer has been acquired. Callbacks distinguish those phases
+ * through context.state; context.acquired is the corresponding convenience
+ * boolean.
+ */
+export declare const withLock: WithLock;
+export { LockAbortedError, LockTimeoutError, LockUnavailableError } from "./errors.js";
+export { memoize } from "./memoize.js";
+export { fileLockStrategySchema, lockBackendScopeSchema, lockOptionsSchema, lockScopeSchema, lockTimeoutSchema, } from "./schemas.js";
+export type { FileLockStrategy, LockTimeout, LockScope, ResolvedLockScope, ResolvedLockTimeout, } from "./schemas.js";
+export type { LockAction, LockBackendInfo, LockBackendScope, LockCallbackState, LockCheckFailedHandler, LockContext, LockInfo, LockOptions, LockPredicate, LockResult, LockResultContext, ResolvedLockOptions, LockState, LockType, ResolvedLockType, } from "./types.js";

package/release/index.js

@@ -0,0 +1,217 @@
+import { performance } from "node:perf_hooks";
+import { prepareFileBackend } from "./backends/file.js";
+import { prepareMemoryBackend } from "./backends/memory.js";
+import { prepareWorkerBackend } from "./backends/worker.js";
+import { LockAbortedError, LockTimeoutError } from "./errors.js";
+import { createLockIdentity } from "./identity.js";
+import { lockOptionsSchema, } from "./schemas.js";
+function createContext(context, lock, state) {
+    const acquired = state !== "predicate-before";
+    return Object.freeze({ ...context, state, acquired, lock });
+}
+function freezeBackends(backends) {
+    return Object.freeze(backends.map((backend) => Object.freeze({ ...backend })));
+}
+function createInfo(base, details, acquired = false, waitedMs = 0) {
+    const backends = freezeBackends(details);
+    return Object.freeze({
+        ...base,
+        type: backends.length === 1 ? backends[0].type : "composite",
+        backends,
+        waitedMs,
+        ...(acquired ? { acquiredAt: new Date().toISOString() } : {}),
+    });
+}
+function createResult(value, context) {
+    return Object.freeze({ value, context });
+}
+function createTimeoutContext(context, lock) {
+    return Object.freeze({
+        ...context,
+        state: "timeout",
+        acquired: false,
+        lock,
+    });
+}
+function singleBackend(backend) {
+    return {
+        initial: [backend.initial],
+        async run(callback) {
+            return backend.run((details) => callback([details]));
+        },
+    };
+}
+function layeredBackends(info, options, controller, backends) {
+    return {
+        initial: backends.map((backend) => backend.initial),
+        async run(callback) {
+            let timer;
+            let timedOut = false;
+            const abortFromCaller = () => controller.abort(options.signal?.reason);
+            const stopWaiting = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                options.signal?.removeEventListener("abort", abortFromCaller);
+            };
+            if (options.signal?.aborted) {
+                throw new LockAbortedError(info, options.signal.reason);
+            }
+            options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+            if (options.timeout && options.timeout.ms > 0) {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    controller.abort();
+                }, options.timeout.ms);
+                timer.unref?.();
+            }
+            const acquired = [];
+            const acquireAt = async (index) => {
+                const backend = backends[index];
+                if (!backend) {
+                    stopWaiting();
+                    if (timedOut)
+                        throw new LockTimeoutError(info, options.timeout.ms);
+                    if (options.signal?.aborted) {
+                        throw new LockAbortedError(info, options.signal.reason);
+                    }
+                    return callback(acquired);
+                }
+                return backend.run(async (details) => {
+                    acquired.push(details);
+                    return acquireAt(index + 1);
+                });
+            };
+            try {
+                return await acquireAt(0);
+            }
+            catch (error) {
+                if (timedOut)
+                    throw new LockTimeoutError(info, options.timeout.ms);
+                throw error;
+            }
+            finally {
+                stopWaiting();
+            }
+        },
+    };
+}
+async function prepareLock(info, options, fileBase) {
+    const controller = new AbortController();
+    const isLayered = options.scope.length > 1;
+    const effectiveOptions = isLayered
+        ? { ...options, signal: controller.signal }
+        : options;
+    const fileLayerSelected = options.scope.includes("file");
+    const backends = [];
+    for (const scope of options.scope) {
+        switch (scope) {
+            case "memory":
+                backends.push(prepareMemoryBackend(info, effectiveOptions));
+                break;
+            case "worker":
+                backends.push(prepareWorkerBackend(info, effectiveOptions, fileLayerSelected));
+                break;
+            case "file":
+                backends.push(await prepareFileBackend(info, effectiveOptions, fileBase));
+                break;
+        }
+    }
+    if (backends.length === 1)
+        return singleBackend(backends[0]);
+    return layeredBackends(info, options, controller, backends);
+}
+function provisionalBackends(options) {
+    const fileType = options.fileStrategy === "poll" ? "poll" : "flock";
+    return options.scope.map((scope) => {
+        switch (scope) {
+            case "memory":
+                return { scope, type: "memory" };
+            case "worker":
+                return { scope, type: "worker" };
+            case "file":
+                return { scope, type: fileType };
+        }
+    });
+}
+const withLockImplementation = async (context, action, predicateOrOptions, suppliedOptions) => {
+    const options = lockOptionsSchema.parse(typeof predicateOrOptions === "function"
+        ? suppliedOptions
+        : predicateOrOptions);
+    const positionalPredicate = typeof predicateOrOptions === "function" ? predicateOrOptions : undefined;
+    const optionPredicate = options.predicate;
+    if (positionalPredicate && optionPredicate) {
+        throw new TypeError("Pass the predicate either positionally or as options.predicate, not both");
+    }
+    const predicate = positionalPredicate ?? optionPredicate;
+    const onCheckFailed = options.onCheckFailed;
+    const identity = await createLockIdentity(context, options);
+    const baseInfo = {
+        id: identity.id,
+        name: identity.name,
+        namespace: identity.namespace,
+        scope: options.scope,
+        ...(options.scope.includes("file")
+            ? { strategy: options.fileStrategy }
+            : {}),
+    };
+    const provisionalInfo = createInfo(baseInfo, provisionalBackends(options));
+    const prepared = await prepareLock(provisionalInfo, options, identity.fileBase);
+    const checkingInfo = createInfo(baseInfo, prepared.initial);
+    const beforeContext = createContext(context, checkingInfo, "predicate-before");
+    if (predicate && !(await predicate(beforeContext))) {
+        await onCheckFailed?.(beforeContext);
+        return createResult(undefined, beforeContext);
+    }
+    const startedAt = performance.now();
+    let fullyAcquired = false;
+    let result;
+    try {
+        result = await prepared.run(async (details) => {
+            fullyAcquired = true;
+            const acquiredInfo = createInfo(baseInfo, details, true, Math.max(0, performance.now() - startedAt));
+            const predicateContext = createContext(context, acquiredInfo, "predicate-after");
+            if (predicate && !(await predicate(predicateContext))) {
+                return {
+                    state: "predicate-after",
+                    context: predicateContext,
+                };
+            }
+            const actionContext = createContext(context, acquiredInfo, "executed");
+            const value = await action(actionContext);
+            return {
+                state: "executed",
+                value,
+                context: actionContext,
+            };
+        });
+    }
+    catch (error) {
+        if (error instanceof LockTimeoutError &&
+            !fullyAcquired &&
+            options.timeout?.error === false) {
+            const waitingInfo = createInfo(baseInfo, prepared.initial, false, Math.max(0, performance.now() - startedAt));
+            return createResult(undefined, createTimeoutContext(context, waitingInfo));
+        }
+        throw error;
+    }
+    if (result.state === "predicate-after") {
+        await onCheckFailed?.(result.context);
+        return createResult(undefined, result.context);
+    }
+    return createResult(result.value, result.context);
+};
+/**
+ * Runs an action with exclusive access to a deterministic lock.
+ *
+ * By default, memory, worker-thread, and cross-process file layers are held in
+ * that order. When supplied, the predicate runs before waiting and again after
+ * every requested layer has been acquired. Callbacks distinguish those phases
+ * through context.state; context.acquired is the corresponding convenience
+ * boolean.
+ */
+export const withLock = withLockImplementation;
+export { LockAbortedError, LockTimeoutError, LockUnavailableError } from "./errors.js";
+export { memoize } from "./memoize.js";
+export { fileLockStrategySchema, lockBackendScopeSchema, lockOptionsSchema, lockScopeSchema, lockTimeoutSchema, } from "./schemas.js";

package/release/memoize.d.ts

@@ -0,0 +1,4 @@
+/** Runs a zero-argument factory once and reuses its successful result. */
+export declare function memoize<T>(factory: () => PromiseLike<T>): () => Promise<T>;
+export declare function memoize<T>(factory: () => T): () => T;
+export declare function memoize<T>(factory: () => T | PromiseLike<T>): () => T | Promise<T>;

package/release/memoize.js

@@ -0,0 +1,28 @@
+export function memoize(factory) {
+    let cache;
+    return () => {
+        if (!cache) {
+            const result = factory();
+            if (isThenable(result)) {
+                const pending = Promise.resolve(result);
+                const entry = { value: pending };
+                cache = entry;
+                // A failed computation is retryable; only successful results stay memoized.
+                void pending.then(undefined, () => {
+                    if (cache === entry)
+                        cache = undefined;
+                });
+            }
+            else {
+                cache = { value: result };
+            }
+        }
+        return cache.value;
+    };
+}
+function isThenable(value) {
+    return Boolean(value !== null &&
+        typeof value === "object" &&
+        "then" in value &&
+        typeof value.then === "function");
+}

package/release/schemas.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+export declare const lockBackendScopeSchema: z.ZodEnum<{
+    worker: "worker";
+    file: "file";
+    memory: "memory";
+}>;
+export declare const lockScopeSchema: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+    worker: "worker";
+    file: "file";
+    memory: "memory";
+}>, z.ZodArray<z.ZodEnum<{
+    worker: "worker";
+    file: "file";
+    memory: "memory";
+}>>]>>, z.ZodTransform<readonly ("worker" | "file" | "memory")[], "worker" | "file" | "memory" | ("worker" | "file" | "memory")[]>>;
+export declare const fileLockStrategySchema: z.ZodEnum<{
+    auto: "auto";
+    flock: "flock";
+    poll: "poll";
+}>;
+export declare const lockTimeoutSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+    ms: z.ZodNumber;
+    error: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>]>, z.ZodTransform<{
+    ms: number;
+    error: boolean;
+}, number | {
+    ms: number;
+    error: boolean;
+}>>;
+/** Runtime-validated options accepted by {@link withLock}. */
+export declare const lockOptionsSchema: z.ZodObject<{
+    key: z.ZodOptional<z.ZodUnknown>;
+    name: z.ZodOptional<z.ZodString>;
+    namespace: z.ZodOptional<z.ZodString>;
+    scope: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+        worker: "worker";
+        file: "file";
+        memory: "memory";
+    }>, z.ZodArray<z.ZodEnum<{
+        worker: "worker";
+        file: "file";
+        memory: "memory";
+    }>>]>>, z.ZodTransform<readonly ("worker" | "file" | "memory")[], "worker" | "file" | "memory" | ("worker" | "file" | "memory")[]>>;
+    fileStrategy: z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        flock: "flock";
+        poll: "poll";
+    }>>;
+    timeout: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+        ms: z.ZodNumber;
+        error: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>]>, z.ZodTransform<{
+        ms: number;
+        error: boolean;
+    }, number | {
+        ms: number;
+        error: boolean;
+    }>>>;
+    pollIntervalMs: z.ZodDefault<z.ZodNumber>;
+    staleMs: z.ZodDefault<z.ZodNumber>;
+    lockDirectory: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodDefault<z.ZodString>;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    predicate: z.ZodOptional<z.ZodCustom<(...args: never[]) => unknown, (...args: never[]) => unknown>>;
+    onCheckFailed: z.ZodOptional<z.ZodCustom<(...args: never[]) => unknown, (...args: never[]) => unknown>>;
+}, z.core.$strict>;
+export type LockBackendScope = z.infer<typeof lockBackendScopeSchema>;
+export type LockScope = LockBackendScope | readonly LockBackendScope[];
+export type ResolvedLockScope = z.output<typeof lockScopeSchema>;
+export type FileLockStrategy = z.infer<typeof fileLockStrategySchema>;
+export type LockTimeout = z.input<typeof lockTimeoutSchema>;
+export type ResolvedLockTimeout = z.output<typeof lockTimeoutSchema>;
+export type LockOptionsInput = z.input<typeof lockOptionsSchema>;
+export type ResolvedLockOptionsData = z.output<typeof lockOptionsSchema>;

package/release/schemas.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+export const lockBackendScopeSchema = z.enum(["memory", "worker", "file"]);
+const allBackendScopes = ["memory", "worker", "file"];
+const lockScopeListSchema = z
+    .array(lockBackendScopeSchema)
+    .min(1)
+    .max(allBackendScopes.length)
+    .refine((scopes) => new Set(scopes).size === scopes.length, {
+    message: "Lock scopes must be unique",
+});
+export const lockScopeSchema = z
+    .union([lockBackendScopeSchema, lockScopeListSchema])
+    .default([...allBackendScopes])
+    .transform((scope) => {
+    const requested = new Set(Array.isArray(scope) ? scope : [scope]);
+    return Object.freeze(allBackendScopes.filter((item) => requested.has(item)));
+});
+export const fileLockStrategySchema = z.enum(["auto", "flock", "poll"]);
+const timeoutMsSchema = z.number().int().min(0).max(2_147_483_647);
+export const lockTimeoutSchema = z
+    .union([
+    timeoutMsSchema,
+    z
+        .object({
+        ms: timeoutMsSchema,
+        error: z.boolean().default(true),
+    })
+        .strict(),
+])
+    .transform((timeout) => typeof timeout === "number" ? { ms: timeout, error: true } : timeout);
+const abortSignalSchema = z.custom((value) => typeof AbortSignal !== "undefined" && value instanceof AbortSignal, "Expected an AbortSignal");
+const callbackSchema = z.custom((value) => typeof value === "function", "Expected a function");
+/** Runtime-validated options accepted by {@link withLock}. */
+export const lockOptionsSchema = z
+    .object({
+    /** Stable input used to derive the lock id. Defaults to the supplied context. */
+    key: z.unknown().optional(),
+    /** Human-readable label used in diagnostics. */
+    name: z.string().trim().min(1).max(200).optional(),
+    /** Overrides namespace discovery from the consuming package. */
+    namespace: z.string().trim().min(1).max(214).optional(),
+    /** One or more lock boundaries. Omission acquires every layer. */
+    scope: lockScopeSchema,
+    /** Auto falls back to polling; flock requires native support; poll skips it. */
+    fileStrategy: fileLockStrategySchema.default("auto"),
+    /** Optional wait limit. A number throws; object form can return a result. */
+    timeout: lockTimeoutSchema.optional(),
+    /** Delay between polling-file lock attempts. */
+    pollIntervalMs: z.number().int().min(1).max(60_000).default(100),
+    /** Age after which an abandoned polling lock can be reclaimed. */
+    staleMs: z.number().int().min(5_000).max(2_147_483_647).default(30_000),
+    /** Overrides LOQKIT_LOCK_DIR and the operating-system temporary directory. */
+    lockDirectory: z.string().trim().min(1).optional(),
+    /** Starting directory for consuming-package discovery. */
+    cwd: z
+        .string()
+        .trim()
+        .min(1)
+        .default(() => process.cwd()),
+    /** Cancels only while waiting; an acquired action is not interrupted. */
+    signal: abortSignalSchema.optional(),
+    /** Runs before waiting and again after acquisition. */
+    predicate: callbackSchema.optional(),
+    /** Runs without a held lock after either predicate check fails. */
+    onCheckFailed: callbackSchema.optional(),
+})
+    .strict();

package/release/types.d.ts

@@ -0,0 +1,63 @@
+import type { FileLockStrategy, LockBackendScope as SchemaLockBackendScope, LockOptionsInput, LockScope, ResolvedLockScope, ResolvedLockOptionsData } from "./schemas.js";
+export type LockBackendScope = SchemaLockBackendScope;
+export type ResolvedLockType = "memory" | "worker" | "flock" | "poll" | "skipped";
+export type LockType = ResolvedLockType | "composite";
+export type LockCallbackState = "predicate-before" | "predicate-after" | "executed";
+export type LockState = LockCallbackState | "timeout";
+type LockAcquired<TState extends LockState> = TState extends "predicate-before" | "timeout" ? false : true;
+/** One requested lock layer and the implementation that satisfied it. */
+export interface LockBackendInfo {
+    readonly scope: LockBackendScope;
+    readonly type: ResolvedLockType;
+    readonly file?: string;
+    readonly fallback?: string;
+}
+/** Details about the resource and implementations used for a lock. */
+export interface LockInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly namespace: string;
+    readonly scope: ResolvedLockScope;
+    readonly type: LockType;
+    readonly backends: readonly Readonly<LockBackendInfo>[];
+    readonly strategy?: FileLockStrategy;
+    readonly waitedMs: number;
+    readonly acquiredAt?: string;
+}
+/** The caller context plus immutable information about the current lock. */
+export type LockContext<TContext extends object, TState extends LockCallbackState = LockCallbackState> = Readonly<Omit<TContext, "acquired" | "lock" | "state"> & {
+    /** Which branch of the lock attempt is invoking this callback. */
+    readonly state: TState;
+    /** Whether this context snapshot was created after lock acquisition. */
+    readonly acquired: LockAcquired<TState>;
+    readonly lock: Readonly<LockInfo>;
+}>;
+export type LockAction<TContext extends object, TResult> = (context: LockContext<TContext, "executed">) => TResult | PromiseLike<TResult>;
+export type LockPredicate<TContext extends object> = (context: LockContext<TContext, "predicate-before" | "predicate-after">) => boolean | PromiseLike<boolean>;
+export type LockCheckFailedHandler<TContext extends object> = (context: LockContext<TContext, "predicate-before" | "predicate-after">) => void | PromiseLike<void>;
+interface LockCallbacks<TContext extends object> {
+    readonly predicate?: LockPredicate<TContext>;
+    readonly onCheckFailed?: LockCheckFailedHandler<TContext>;
+}
+/** Lock configuration with callbacks typed to the supplied context. */
+export type LockOptions<TContext extends object = object> = Omit<LockOptionsInput, "onCheckFailed" | "predicate" | "scope"> & {
+    readonly scope?: LockScope;
+} & LockCallbacks<TContext>;
+/** Runtime-resolved lock configuration with context-aware callbacks. */
+export type ResolvedLockOptions<TContext extends object = object> = Omit<ResolvedLockOptionsData, "onCheckFailed" | "predicate" | "scope"> & {
+    readonly scope: ResolvedLockScope;
+} & LockCallbacks<TContext>;
+/** A callback context widened with the timeout state only results can observe. */
+export type LockResultContext<TContext extends object> = Readonly<Omit<LockContext<TContext>, "state"> & {
+    readonly state: LockState;
+}>;
+/** The action value and terminal context for one withLock attempt. */
+export interface LockResult<TContext extends object, TResult> {
+    readonly value: TResult | undefined;
+    readonly context: LockResultContext<TContext>;
+}
+export interface WithLock {
+    <TContext extends object, TResult>(context: TContext, action: LockAction<TContext, TResult>, options?: LockOptions<TContext>): Promise<LockResult<TContext, TResult>>;
+    <TContext extends object, TResult>(context: TContext, action: LockAction<TContext, TResult>, predicate: LockPredicate<TContext>, options?: LockOptions<TContext>): Promise<LockResult<TContext, TResult>>;
+}
+export {};

package/release/types.js

@@ -0,0 +1 @@
+export {};

package/release/waiting.d.ts

@@ -0,0 +1,5 @@
+import type { LockInfo } from "./types.js";
+export declare function throwIfAborted(signal: AbortSignal | undefined, info: Readonly<LockInfo>): void;
+export declare function throwIfTimedOut(startedAt: number, timeoutMs: number | undefined, info: Readonly<LockInfo>): void;
+export declare function waitForRetry(startedAt: number, timeoutMs: number | undefined, pollIntervalMs: number, signal: AbortSignal | undefined, info: Readonly<LockInfo>): Promise<void>;
+export declare function acquireWithLimits<T>(acquisition: Promise<T>, timeoutMs: number | undefined, signal: AbortSignal | undefined, info: Readonly<LockInfo>, releaseLateAcquisition: (value: T) => void): Promise<T>;

package/release/waiting.js

@@ -0,0 +1,60 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { LockAbortedError, LockTimeoutError } from "./errors.js";
+export function throwIfAborted(signal, info) {
+    if (signal?.aborted) {
+        throw new LockAbortedError(info, signal.reason);
+    }
+}
+export function throwIfTimedOut(startedAt, timeoutMs, info) {
+    if (timeoutMs !== undefined && Date.now() - startedAt >= timeoutMs) {
+        throw new LockTimeoutError(info, timeoutMs);
+    }
+}
+export async function waitForRetry(startedAt, timeoutMs, pollIntervalMs, signal, info) {
+    throwIfAborted(signal, info);
+    throwIfTimedOut(startedAt, timeoutMs, info);
+    const waitMs = timeoutMs === undefined
+        ? pollIntervalMs
+        : Math.max(1, Math.min(pollIntervalMs, timeoutMs - (Date.now() - startedAt)));
+    try {
+        await delay(waitMs, undefined, { signal });
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw new LockAbortedError(info, signal.reason);
+        }
+        throw error;
+    }
+}
+export async function acquireWithLimits(acquisition, timeoutMs, signal, info, releaseLateAcquisition) {
+    throwIfAborted(signal, info);
+    let timer;
+    let abortListener;
+    const contenders = [acquisition];
+    if (timeoutMs !== undefined) {
+        contenders.push(new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new LockTimeoutError(info, timeoutMs)), timeoutMs);
+            timer.unref?.();
+        }));
+    }
+    if (signal) {
+        contenders.push(new Promise((_resolve, reject) => {
+            abortListener = () => reject(new LockAbortedError(info, signal.reason));
+            signal.addEventListener("abort", abortListener, { once: true });
+        }));
+    }
+    try {
+        return await Promise.race(contenders);
+    }
+    catch (error) {
+        void acquisition.then(releaseLateAcquisition, () => undefined);
+        throw error;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (signal && abortListener) {
+            signal.removeEventListener("abort", abortListener);
+        }
+    }
+}