@lickle/lock 0.0.1-alpha.1 → 0.0.1-alpha.2

package/dist/esm/core/locking.d.ts

@@ -0,0 +1,23 @@
+import { type FileDescriptor, type Locker } from './types.js';
+/**
+ * Lifecycle hooks called when locks are acquired and released.
+ * Used by backends to track active locks for cleanup on exit or signals.
+ */
+export interface LockHooks {
+    /** Called after a lock is successfully acquired. */
+    register: (fd: FileDescriptor) => Promise<void>;
+    /** Called when a lock is released (even if unlock itself fails). */
+    unregister: (fd: FileDescriptor) => Promise<void>;
+}
+/**
+ * Create a {@link Locker} backed by native OS locks.
+ *
+ * Whole-file locks use `flock(2)` on Unix and `LockFileEx` on Windows.
+ * Range locks use `fcntl(2)` OFD locks on Linux, POSIX record locks on
+ * macOS/BSD, and ranged `LockFileEx` on Windows.
+ *
+ * If `hooks` are provided they are called after lock acquisition and on
+ * release, allowing backends to track active locks for cleanup.
+ */
+export declare const createLocker: (hooks?: LockHooks) => Locker;
+//# sourceMappingURL=locking.d.ts.map

package/dist/esm/core/locking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locking.d.ts","sourceRoot":"","sources":["../../../lib/core/locking.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,cAAc,EAAE,KAAK,MAAM,EAAmB,MAAM,YAAY,CAAA;AAGhH;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,QAAQ,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,oEAAoE;IACpE,UAAU,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAClD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,SAAS,KAAG,MAqC/C,CAAA"}

package/dist/esm/core/locking.js

@@ -0,0 +1,56 @@
+import { Lock, resolveFd } from './types.js';
+import * as native from '#native';
+/**
+ * Create a {@link Locker} backed by native OS locks.
+ *
+ * Whole-file locks use `flock(2)` on Unix and `LockFileEx` on Windows.
+ * Range locks use `fcntl(2)` OFD locks on Linux, POSIX record locks on
+ * macOS/BSD, and ranged `LockFileEx` on Windows.
+ *
+ * If `hooks` are provided they are called after lock acquisition and on
+ * release, allowing backends to track active locks for cleanup.
+ */
+export const createLocker = (hooks) => ({
+    async lock(fd, type, range, options) {
+        const d = resolveFd(fd);
+        await native.lock(d, toNativeLock(type), range, options);
+        try {
+            await hooks?.register(d);
+        }
+        catch (err) {
+            try {
+                native.lockSync(d, native.Lock.Unlock, range);
+            }
+            catch { }
+            throw err;
+        }
+    },
+    async tryLock(fd, type, range) {
+        const d = resolveFd(fd);
+        const locked = await native.tryLock(d, toNativeLock(type), range);
+        if (!locked)
+            return false;
+        try {
+            await hooks?.register(d);
+            return true;
+        }
+        catch (err) {
+            try {
+                native.lockSync(d, native.Lock.Unlock, range);
+            }
+            catch { }
+            throw err;
+        }
+    },
+    async unlock(fd, range) {
+        const d = resolveFd(fd);
+        try {
+            native.lockSync(d, native.Lock.Unlock, range);
+        }
+        finally {
+            await hooks?.unregister(d);
+        }
+    },
+});
+const toNativeLock = (type) => (type === Lock.Exclusive ? native.Lock.Exclusive : native.Lock.Shared);
+//# sourceMappingURL=locking.js.map

package/dist/esm/core/locking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locking.js","sourceRoot":"","sources":["../../../lib/core/locking.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsE,IAAI,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAChH,OAAO,KAAK,MAAM,MAAM,SAAS,CAAA;AAajC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAiB,EAAU,EAAE,CAAC,CAAC;IAC1D,KAAK,CAAC,IAAI,CAAC,EAAkB,EAAE,IAAU,EAAE,KAAiB,EAAE,OAAqB;QACjF,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAA;QACvB,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;QACxD,IAAI,CAAC;YACH,MAAM,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;QAC1B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;YAC/C,CAAC;YAAC,MAAM,CAAC,CAAA,CAAC;YACV,MAAM,GAAG,CAAA;QACX,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,EAAkB,EAAE,IAAU,EAAE,KAAiB;QAC7D,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAA;QACvB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAA;QACjE,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAA;QACzB,IAAI,CAAC;YACH,MAAM,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;YACxB,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;YAC/C,CAAC;YAAC,MAAM,CAAC,CAAA,CAAC;YACV,MAAM,GAAG,CAAA;QACX,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,EAAkB,EAAE,KAAiB;QAChD,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAA;QACvB,IAAI,CAAC;YACH,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;QAC/C,CAAC;gBAAS,CAAC;YACT,MAAM,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;QAC5B,CAAC;IACH,CAAC;CACF,CAAC,CAAA;AAEF,MAAM,YAAY,GAAG,CAAC,IAAU,EAAe,EAAE,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA"}

package/dist/esm/core/node.d.ts

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import { type Fs, FileDescriptor } from './types.js';
+import { type LockHooks } from './locking.js';
+/** Node.js file handle type alias. */
+export type NodeFileHandle = fs.promises.FileHandle;
+/** Create a Node.js filesystem that opens files with appropriate flags for the lock type. */
+export declare const createNodeFs: () => Fs<NodeFileHandle>;
+/**
+ * Track active locks by file descriptor and ensure they are released on process exit.
+ */
+export declare class NodeLockHooks implements LockHooks {
+    private _active;
+    register(fd: FileDescriptor): Promise<void>;
+    unregister(fd: FileDescriptor): Promise<void>;
+    private _listen;
+    private _unlisten;
+    private _onExit;
+}
+//# sourceMappingURL=node.d.ts.map

package/dist/esm/core/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../lib/core/node.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,SAAS,CAAA;AAExB,OAAO,EAAE,KAAK,EAAE,EAAQ,cAAc,EAAa,MAAM,YAAY,CAAA;AACrE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAE7C,sCAAsC;AACtC,MAAM,MAAM,cAAc,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAA;AAEnD,6FAA6F;AAC7F,eAAO,MAAM,YAAY,QAAO,EAAE,CAAC,cAAc,CAQhD,CAAA;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,SAAS;IAC7C,OAAO,CAAC,OAAO,CAA4B;IAErC,QAAQ,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3C,UAAU,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnD,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,OAAO,CASd;CACF"}

package/dist/esm/core/node.js

@@ -0,0 +1,61 @@
+import { isMainThread, parentPort } from 'node:worker_threads';
+import fs from 'node:fs';
+import { Lock, resolveFd } from './types.js';
+/** Create a Node.js filesystem that opens files with appropriate flags for the lock type. */
+export const createNodeFs = () => {
+    return {
+        async open(file, type) {
+            const flags = type === Lock.Exclusive ? fs.constants.O_CREAT | fs.constants.O_RDWR : fs.constants.O_RDONLY;
+            const handle = await fs.promises.open(file, flags);
+            return handle;
+        },
+    };
+};
+/**
+ * Track active locks by file descriptor and ensure they are released on process exit.
+ */
+export class NodeLockHooks {
+    _active = new Map();
+    async register(fd) {
+        if (this._active.size === 0)
+            this._listen();
+        const d = resolveFd(fd);
+        this._active.set(d, (this._active.get(d) ?? 0) + 1);
+    }
+    async unregister(fd) {
+        const d = resolveFd(fd);
+        const count = this._active.get(d);
+        if (count !== undefined) {
+            if (count <= 1)
+                this._active.delete(d);
+            else
+                this._active.set(d, count - 1);
+        }
+        if (this._active.size === 0)
+            this._unlisten();
+    }
+    _listen() {
+        if (isMainThread)
+            process.on('exit', this._onExit);
+        else
+            parentPort?.on('close', this._onExit);
+    }
+    _unlisten() {
+        if (isMainThread)
+            process.off('exit', this._onExit);
+        else
+            parentPort?.off('close', this._onExit);
+    }
+    _onExit = () => {
+        for (const fd of Array.from(this._active.keys()).reverse()) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // EBADF expected if already closed
+            }
+        }
+        this._active.clear();
+    };
+}
+//# sourceMappingURL=node.js.map

package/dist/esm/core/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../../lib/core/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,EAAE,MAAM,SAAS,CAAA;AAExB,OAAO,EAAW,IAAI,EAAkB,SAAS,EAAE,MAAM,YAAY,CAAA;AAMrE,6FAA6F;AAC7F,MAAM,CAAC,MAAM,YAAY,GAAG,GAAuB,EAAE;IACnD,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,IAAU;YACjC,MAAM,KAAK,GAAG,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAA;YAC1G,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;YAClD,OAAO,MAAM,CAAA;QACf,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED;;GAEG;AACH,MAAM,OAAO,aAAa;IAChB,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA;IAE3C,KAAK,CAAC,QAAQ,CAAC,EAAkB;QAC/B,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,IAAI,CAAC,OAAO,EAAE,CAAA;QAC3C,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAA;QACvB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IACrD,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,EAAkB;QACjC,MAAM,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAA;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,KAAK,IAAI,CAAC;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;;gBACjC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;QACrC,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,IAAI,CAAC,SAAS,EAAE,CAAA;IAC/C,CAAC;IAEO,OAAO;QACb,IAAI,YAAY;YAAE,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;;YAC7C,UAAU,EAAE,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;IAC5C,CAAC;IAEO,SAAS;QACf,IAAI,YAAY;YAAE,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;;YAC9C,UAAU,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;IAC7C,CAAC;IAEO,OAAO,GAAG,GAAS,EAAE;QAC3B,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YAC3D,IAAI,CAAC;gBACH,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAA;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,mCAAmC;YACrC,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC,CAAA;CACF"}

package/dist/esm/core/types.d.ts

@@ -0,0 +1,49 @@
+/** Filesystem abstraction for opening lock files. */
+export interface Fs<H extends FileHandle> {
+    /** Open (or create) the lock file and return a handle. */
+    open(file: string, type: Lock): Promise<H>;
+}
+/** Lock/unlock operations, separated from file opening for composability. */
+export interface Locker {
+    /** Acquire a lock, polling until available or timeout is reached. */
+    lock: (fd: FileDescriptor, type: Lock, range?: LockRange, options?: PollOptions) => Promise<void>;
+    /** Try to acquire a lock without waiting. Return true if acquired. */
+    tryLock: (fd: FileDescriptor, type: Lock, range?: LockRange) => Promise<boolean>;
+    /** Release a previously acquired lock. */
+    unlock: (fd: FileDescriptor, range?: LockRange) => Promise<void>;
+}
+/** Lock mode: exclusive (write) or shared (read). */
+export declare enum Lock {
+    Exclusive = 0,
+    Shared = 1
+}
+/** Options for polling lock acquisition. */
+export interface PollOptions {
+    /** Polling interval in milliseconds. */
+    pollMs?: number;
+    /** Maximum wait time in milliseconds. */
+    timeout?: number;
+    /** Multiplier applied to pollMs after each failed attempt (e.g. 2 = exponential backoff). */
+    backoff?: number;
+}
+/** Byte range within a file to lock. Used for range-level locking. */
+export interface LockRange {
+    /** Starting byte offset. */
+    offset: number;
+    /** Number of bytes to lock. */
+    length: number;
+}
+/** An open file handle with a descriptor and a close method. */
+export interface FileHandle {
+    /** The numeric file descriptor. */
+    fd: number;
+    /** Close the file handle. */
+    close: () => Promise<void>;
+}
+/** File descriptor or file descriptor object. */
+export type FileDescriptor = {
+    fd: number;
+} | number;
+/** @internal */
+export declare const resolveFd: (fd: FileDescriptor) => number;
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../lib/core/types.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,MAAM,WAAW,EAAE,CAAC,CAAC,SAAS,UAAU;IACtC,0DAA0D;IAC1D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CAC3C;AAED,6EAA6E;AAC7E,MAAM,WAAW,MAAM;IACrB,qEAAqE;IACrE,IAAI,EAAE,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACjG,sEAAsE;IACtE,OAAO,EAAE,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAChF,0CAA0C;IAC1C,MAAM,EAAE,CAAC,EAAE,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACjE;AAED,qDAAqD;AACrD,oBAAY,IAAI;IACd,SAAS,IAAA;IACT,MAAM,IAAA;CACP;AAED,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAA;CACf;AAED,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,6BAA6B;IAC7B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAA;AAEpD,gBAAgB;AAChB,eAAO,MAAM,SAAS,GAAI,IAAI,cAAc,KAAG,MAA+C,CAAA"}

package/dist/esm/core/types.js

@@ -0,0 +1,9 @@
+/** Lock mode: exclusive (write) or shared (read). */
+export var Lock;
+(function (Lock) {
+    Lock[Lock["Exclusive"] = 0] = "Exclusive";
+    Lock[Lock["Shared"] = 1] = "Shared";
+})(Lock || (Lock = {}));
+/** @internal */
+export const resolveFd = (fd) => (typeof fd === 'number' ? fd : fd.fd);
+//# sourceMappingURL=types.js.map

package/dist/esm/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../lib/core/types.ts"],"names":[],"mappings":"AAgBA,qDAAqD;AACrD,MAAM,CAAN,IAAY,IAGX;AAHD,WAAY,IAAI;IACd,yCAAS,CAAA;IACT,mCAAM,CAAA;AACR,CAAC,EAHW,IAAI,KAAJ,IAAI,QAGf;AA+BD,gBAAgB;AAChB,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,EAAkB,EAAU,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA"}

package/dist/esm/index.d.ts

@@ -1,54 +1,63 @@
-import { type Backend, type FileHandle, type NodeFileHandle, FileGuard } from './backend/index.js';
-export * from './backend/index.js';
+import { type NodeFileHandle, type LockRange, type PollOptions, type Lock, type FileHandle, type FileDescriptor, type Fs, type Locker, FileLockGuard, LockGuard } from './core/index.js';
+export * from './core/index.js';
+/** Options for specifying a custom locker and/or byte range. */
+export interface LockingOptions {
+    /** Custom locker implementation. Uses the default native locker if omitted. */
+    locking?: Locker;
+    /** Byte range to lock. Locks the entire file if omitted. */
+    range?: LockRange;
+}
 /**
- * Acquire an exclusive (write) lock on a file, polling until available.
- * Creates the file if it does not exist.
+ * Acquire a lock on an already-open file handle.
  *
  * @example
- * const guard = await exclusive('/tmp/my.lock')
- * try { /* critical section *\/ } finally { await guard.drop() }
+ * import fs from 'node:fs/promises'
+ * const handle = await fs.open('/tmp/my.lock', 'r+')
+ * await using guard = await lock(handle, Lock.Exclusive)
+ */
+export declare const lock: <H extends FileHandle = NodeFileHandle>(handle: H, type: Lock, options?: LockingOptions & PollOptions) => Promise<LockGuard<H>>;
+/**
+ * Try to acquire a lock on an already-open file handle without waiting.
  *
  * @example
- * await using guard = await exclusive('/tmp/my.lock', { timeout: 5000 })
+ * import fs from 'node:fs/promises'
+ * const handle = await fs.open('/tmp/my.lock', 'r+')
+ * const guard = await tryLock(handle, Lock.Exclusive)
+ * if (guard) { /* acquired *\/ }
  */
-export declare const exclusive: <H extends FileHandle = NodeFileHandle>(file: string, options?: {
-    backend?: Backend<H>;
-    pollMs?: number;
-    timeout?: number;
-}) => Promise<FileGuard<H>>;
+export declare const tryLock: <H extends FileDescriptor>(handle: H, type: Lock, options?: LockingOptions & PollOptions) => Promise<LockGuard<H> | undefined>;
 /**
- * Try to acquire an exclusive lock without waiting.
- * Return undefined if the lock is already held.
+ * Release a lock on a file descriptor or file handle.
  *
  * @example
- * const guard = await tryExclusive('/tmp/my.lock')
- * if (guard) { /* acquired *\/ }
+ * import fs from 'node:fs/promises'
+ * const handle = await fs.open('/tmp/my.lock', 'r+')
+ * await lock(handle, Lock.Exclusive)
+ * // ... critical section ...
+ * await unlock(handle)
  */
-export declare const tryExclusive: <H extends FileHandle = NodeFileHandle>(file: string, options?: {
-    backend?: Backend<H>;
-}) => Promise<FileGuard<H> | undefined>;
+export declare const unlock: <H extends FileDescriptor>(handle: H, options?: LockingOptions) => Promise<void>;
+/** Options for open-and-lock functions that manage the file lifecycle. */
+export interface OpenLockOptions<H extends FileHandle> extends LockingOptions {
+    /** Custom filesystem for opening files. Uses the default Node.js fs if omitted. */
+    fs?: Fs<H>;
+}
 /**
- * Acquire a shared (read) lock on a file, polling until available.
- * Multiple shared locks may be held concurrently.
- * Creates the file if it does not exist.
+ * Open a file and acquire a lock, polling until available. Closes the file on failure.
+ *
+ * @example
+ * await using guard = await openLock('/tmp/my.lock', Lock.Exclusive)
  *
  * @example
- * await using guard = await shared('/tmp/my.lock')
+ * await using guard = await openLock('/tmp/my.lock', Lock.Shared, { timeout: 5000 })
  */
-export declare const shared: <H extends FileHandle = NodeFileHandle>(file: string, options?: {
-    backend?: Backend<H>;
-    pollMs?: number;
-    timeout?: number;
-}) => Promise<FileGuard<H>>;
+export declare const openLock: <H extends FileHandle = NodeFileHandle>(file: string, type: Lock, options?: OpenLockOptions<H> & PollOptions) => Promise<FileLockGuard<H>>;
 /**
- * Try to acquire a shared lock without waiting.
- * Return undefined if an exclusive lock is already held.
+ * Open a file and try to acquire a lock without waiting. Closes the file if not acquired.
  *
  * @example
- * const guard = await tryShared('/tmp/my.lock')
+ * const guard = await tryOpenLock('/tmp/my.lock', Lock.Exclusive)
  * if (guard) { /* acquired *\/ }
  */
-export declare const tryShared: <H extends FileHandle = NodeFileHandle>(file: string, options?: {
-    backend?: Backend<H>;
-}) => Promise<FileGuard<H> | undefined>;
+export declare const tryOpenLock: <H extends FileHandle = NodeFileHandle>(file: string, type: Lock, options?: OpenLockOptions<H>) => Promise<FileLockGuard<H> | undefined>;
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,SAAS,EAAkB,MAAM,oBAAoB,CAAA;AAClH,cAAc,oBAAoB,CAAA;AAElC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,SAAS,UAAU,GAAG,cAAc,EACnE,MAAM,MAAM,EACZ,UAAU;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KACpE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAA4C,CAAA;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAU,CAAC,SAAS,UAAU,GAAG,cAAc,EACtE,MAAM,MAAM,EACZ,UAAU;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,KACjC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAA+C,CAAA;AAElF;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAU,CAAC,SAAS,UAAU,GAAG,cAAc,EAChE,MAAM,MAAM,EACZ,UAAU;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,KACpE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAyC,CAAA;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,SAAS,UAAU,GAAG,cAAc,EACnE,MAAM,MAAM,EACZ,UAAU;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,KACjC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAA4C,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,EAAE,EACP,KAAK,MAAM,EACX,aAAa,EACb,SAAS,EAGV,MAAM,iBAAiB,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAE/B,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,GAAU,CAAC,SAAS,UAAU,GAAG,cAAc,EAC9D,QAAQ,CAAC,EACT,MAAM,IAAI,EACV,UAAU,cAAc,GAAG,WAAW,KACrC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAItB,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAU,CAAC,SAAS,cAAc,EACpD,QAAQ,CAAC,EACT,MAAM,IAAI,EACV,UAAU,cAAc,GAAG,WAAW,KACrC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAKlC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,GAAU,CAAC,SAAS,cAAc,EAAE,QAAQ,CAAC,EAAE,UAAU,cAAc,KAAG,OAAO,CAAC,IAAI,CAGxG,CAAA;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,cAAc;IAC3E,mFAAmF;IACnF,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;CACX;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,SAAS,UAAU,GAAG,cAAc,EAClE,MAAM,MAAM,EACZ,MAAM,IAAI,EACV,UAAU,eAAe,CAAC,CAAC,CAAC,GAAG,WAAW,KACzC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAS1B,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,SAAS,UAAU,GAAG,cAAc,EACrE,MAAM,MAAM,EACZ,MAAM,IAAI,EACV,UAAU,eAAe,CAAC,CAAC,CAAC,KAC3B,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAYtC,CAAA"}

package/dist/esm/index.js

@@ -1,63 +1,82 @@
-import { FileGuard, defaultBackend } from './backend/index.js';
-export * from './backend/index.js';
+import { FileLockGuard, LockGuard, defaultFs, defaultLocking, } from './core/index.js';
+export * from './core/index.js';
 /**
- * Acquire an exclusive (write) lock on a file, polling until available.
- * Creates the file if it does not exist.
+ * Acquire a lock on an already-open file handle.
  *
  * @example
- * const guard = await exclusive('/tmp/my.lock')
- * try { /* critical section *\/ } finally { await guard.drop() }
- *
- * @example
- * await using guard = await exclusive('/tmp/my.lock', { timeout: 5000 })
+ * import fs from 'node:fs/promises'
+ * const handle = await fs.open('/tmp/my.lock', 'r+')
+ * await using guard = await lock(handle, Lock.Exclusive)
  */
-export const exclusive = async (file, options) => acquireLock(file, 'exclusive', options);
+export const lock = async (handle, type, options) => {
+    const { locking = defaultLocking() } = options ?? {};
+    await locking.lock(handle, type, options?.range, options);
+    return new LockGuard(locking, handle, options?.range);
+};
 /**
- * Try to acquire an exclusive lock without waiting.
- * Return undefined if the lock is already held.
+ * Try to acquire a lock on an already-open file handle without waiting.
  *
  * @example
- * const guard = await tryExclusive('/tmp/my.lock')
+ * import fs from 'node:fs/promises'
+ * const handle = await fs.open('/tmp/my.lock', 'r+')
+ * const guard = await tryLock(handle, Lock.Exclusive)
  * if (guard) { /* acquired *\/ }
  */
-export const tryExclusive = async (file, options) => tryAcquireLock(file, 'exclusive', options);
+export const tryLock = async (handle, type, options) => {
+    const { locking = defaultLocking() } = options ?? {};
+    const result = await locking.tryLock(handle, type, options?.range);
+    if (result)
+        return new LockGuard(locking, handle, options?.range);
+    return undefined;
+};
 /**
- * Acquire a shared (read) lock on a file, polling until available.
- * Multiple shared locks may be held concurrently.
- * Creates the file if it does not exist.
+ * Release a lock on a file descriptor or file handle.
  *
  * @example
- * await using guard = await shared('/tmp/my.lock')
+ * import fs from 'node:fs/promises'
+ * const handle = await fs.open('/tmp/my.lock', 'r+')
+ * await lock(handle, Lock.Exclusive)
+ * // ... critical section ...
+ * await unlock(handle)
  */
-export const shared = async (file, options) => acquireLock(file, 'shared', options);
+export const unlock = async (handle, options) => {
+    const { locking = defaultLocking() } = options ?? {};
+    await locking.unlock(handle, options?.range);
+};
 /**
- * Try to acquire a shared lock without waiting.
- * Return undefined if an exclusive lock is already held.
+ * Open a file and acquire a lock, polling until available. Closes the file on failure.
  *
  * @example
- * const guard = await tryShared('/tmp/my.lock')
- * if (guard) { /* acquired *\/ }
+ * await using guard = await openLock('/tmp/my.lock', Lock.Exclusive)
+ *
+ * @example
+ * await using guard = await openLock('/tmp/my.lock', Lock.Shared, { timeout: 5000 })
  */
-export const tryShared = async (file, options) => tryAcquireLock(file, 'shared', options);
-const acquireLock = async (file, mode, options) => {
-    const { backend = defaultBackend() } = options ?? {};
-    const handle = await backend.open(file);
+export const openLock = async (file, type, options) => {
+    const { fs = defaultFs() } = options ?? {};
+    const handle = await fs.open(file, type);
     try {
-        await backend.lock(handle, mode, options);
-        return new FileGuard(backend, handle);
+        return new FileLockGuard(await lock(handle, type, options), handle);
     }
     catch (error) {
         await handle.close();
         throw error;
     }
 };
-const tryAcquireLock = async (file, mode, options) => {
-    const { backend = defaultBackend() } = options ?? {};
-    const handle = await backend.open(file);
+/**
+ * Open a file and try to acquire a lock without waiting. Closes the file if not acquired.
+ *
+ * @example
+ * const guard = await tryOpenLock('/tmp/my.lock', Lock.Exclusive)
+ * if (guard) { /* acquired *\/ }
+ */
+export const tryOpenLock = async (file, type, options) => {
+    const { fs = defaultFs() } = options ?? {};
+    const handle = await fs.open(file, type);
     try {
-        const result = await backend.tryLock(handle, mode);
+        const result = await tryLock(handle, type, options);
         if (result)
-            return new FileGuard(backend, handle);
+            return new FileLockGuard(result, handle);
         await handle.close();
         return undefined;
     }

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsD,SAAS,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAClH,cAAc,oBAAoB,CAAA;AAElC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAC5B,IAAY,EACZ,OAAqE,EAC9C,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,CAAA;AAEnE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,IAAY,EACZ,OAAkC,EACC,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,CAAA;AAElF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,KAAK,EACzB,IAAY,EACZ,OAAqE,EAC9C,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;AAEhE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAC5B,IAAY,EACZ,OAAkC,EACC,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;AAE/E,MAAM,WAAW,GAAG,KAAK,EACvB,IAAY,EACZ,IAA4B,EAC5B,OAAqE,EAC9C,EAAE;IACzB,MAAM,EAAE,OAAO,GAAG,cAAc,EAA2B,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAC7E,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACvC,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;QACzC,OAAO,IAAI,SAAS,CAAI,OAAO,EAAE,MAAM,CAAC,CAAA;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED,MAAM,cAAc,GAAG,KAAK,EAC1B,IAAY,EACZ,IAA4B,EAC5B,OAAkC,EACC,EAAE;IACrC,MAAM,EAAE,OAAO,GAAG,cAAc,EAA2B,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAC7E,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAClD,IAAI,MAAM;YAAE,OAAO,IAAI,SAAS,CAAI,OAAO,EAAE,MAAM,CAAC,CAAA;QACpD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,OAAO,SAAS,CAAA;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,aAAa,EACb,SAAS,EACT,SAAS,EACT,cAAc,GACf,MAAM,iBAAiB,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAU/B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,KAAK,EACvB,MAAS,EACT,IAAU,EACV,OAAsC,EACf,EAAE;IACzB,MAAM,EAAE,OAAO,GAAG,cAAc,EAAE,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IACpD,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;IACzD,OAAO,IAAI,SAAS,CAAI,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;AAC1D,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,EAC1B,MAAS,EACT,IAAU,EACV,OAAsC,EACH,EAAE;IACrC,MAAM,EAAE,OAAO,GAAG,cAAc,EAAE,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IACpD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;IAClE,IAAI,MAAM;QAAE,OAAO,IAAI,SAAS,CAAI,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;IACpE,OAAO,SAAS,CAAA;AAClB,CAAC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,KAAK,EAA4B,MAAS,EAAE,OAAwB,EAAiB,EAAE;IAC3G,MAAM,EAAE,OAAO,GAAG,cAAc,EAAE,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IACpD,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;AAC9C,CAAC,CAAA;AAQD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAC3B,IAAY,EACZ,IAAU,EACV,OAA0C,EACf,EAAE;IAC7B,MAAM,EAAE,EAAE,GAAG,SAAS,EAAsB,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAC9D,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACxC,IAAI,CAAC;QACH,OAAO,IAAI,aAAa,CAAI,MAAM,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CAAA;IACxE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAC9B,IAAY,EACZ,IAAU,EACV,OAA4B,EACW,EAAE;IACzC,MAAM,EAAE,EAAE,GAAG,SAAS,EAAsB,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAC9D,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;QACnD,IAAI,MAAM;YAAE,OAAO,IAAI,aAAa,CAAI,MAAM,EAAE,MAAM,CAAC,CAAA;QACvD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,OAAO,SAAS,CAAA;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC,CAAA"}