universal-lock 0.0.2 → 1.0.0

package/README.md

@@ -1 +1,171 @@
-# UniversalLock
+# universal-lock
+
+Lightweight, isomorphic universal locking library with pluggable backends. Works in Node.js and browsers.
+
+Part of the [`universal-lock`](https://github.com/lucasrainett/universal-lock) monorepo.
+
+## Installation
+
+```bash
+npm install universal-lock
+```
+
+You also need a backend package:
+
+```bash
+npm install @universal-lock/memory      # single-process
+npm install @universal-lock/redis        # distributed (cross-process/server)
+npm install @universal-lock/web-locks    # browser (cross-tab, modern)
+npm install @universal-lock/local-storage # browser (cross-tab, older)
+```
+
+## Quick Start
+
+### ESM
+
+```typescript
+import { lockFactory } from "universal-lock";
+import { createBackend } from "@universal-lock/memory";
+
+const lock = lockFactory(createBackend());
+
+const release = await lock.acquire("my-resource");
+try {
+	// critical section
+} finally {
+	await release();
+}
+```
+
+### CommonJS
+
+```javascript
+const { lockFactory } = require("universal-lock");
+const { createBackend } = require("@universal-lock/memory");
+
+const lock = lockFactory(createBackend());
+```
+
+### Browser (IIFE)
+
+```html
+<script src="https://unpkg.com/@universal-lock/memory/dist/index.global.js"></script>
+<script src="https://unpkg.com/universal-lock/dist/index.global.js"></script>
+<script>
+	const lock = UniversalLock.lockFactory(UniversalLockMemory.createBackend());
+</script>
+```
+
+## API
+
+### `lockFactory(backend, config?)`
+
+Creates a lock instance with the given backend and optional configuration. Returns a `Lock` object.
+
+```typescript
+const lock = lockFactory(backend, {
+	acquireInterval: 250, // retry interval in ms (default: 250)
+	acquireFailTimeout: 5000, // max wait before failing acquisition (default: 5000)
+	stale: 1000, // ignore locks older than this in ms (default: 1000)
+	renewInterval: 250, // lock renewal interval in ms (default: 250)
+	maxHoldTime: 2000, // auto-release after this duration in ms (default: 2000)
+	onLockLost: (name, reason) => {}, // called when lock is lost (optional)
+	onEvent: (event) => {}, // lifecycle events (optional)
+});
+```
+
+### `lock.acquire(lockName)`
+
+Acquires a named lock. Returns a `release` function with a `.signal: AbortSignal` property. Rejects if the lock cannot be acquired within `acquireFailTimeout`.
+
+### `lockDecoratorFactory(lock)`
+
+Creates a decorator that wraps async functions with automatic lock acquire/release.
+
+The first argument is either a lock name string or an options object. When a string is passed, the wrapped function keeps its original signature. Pass `{ lockName, signal: true }` to inject an `AbortSignal` as the first argument so the function can react to lock loss.
+
+```typescript
+import { lockFactory, lockDecoratorFactory } from "universal-lock";
+import { createBackend } from "@universal-lock/memory";
+
+const lock = lockFactory(createBackend());
+const withLock = lockDecoratorFactory(lock);
+
+// Simple usage — no signal injection
+const processOrder = withLock("orders", async (orderId: string) => {
+	return await handleOrder(orderId);
+});
+
+await processOrder("order-123");
+
+// With signal injection for lock loss detection
+const processOrderSafe = withLock({ lockName: "orders", signal: true }, async (signal: AbortSignal, orderId: string) => {
+	if (signal.aborted) return;
+	return await handleOrder(orderId);
+});
+
+await processOrderSafe("order-123");
+```
+
+## Lock Loss Detection
+
+### AbortSignal
+
+Every `release` function has a `.signal` property that is aborted when the lock is lost:
+
+```typescript
+const release = await lock.acquire("my-resource");
+
+release.signal.addEventListener("abort", () => {
+	console.log("Lock lost! Stop critical work.");
+});
+
+await release();
+```
+
+### onLockLost callback
+
+```typescript
+const lock = lockFactory(backend, {
+	onLockLost: (lockName, reason) => {
+		// reason: "renewFailed" | "timeout"
+		console.error(`Lock "${lockName}" lost: ${reason}`);
+	},
+});
+```
+
+### Lifecycle events
+
+```typescript
+const lock = lockFactory(backend, {
+	onEvent: (event) => {
+		// event.type: "acquired" | "renewed" | "renewFailed" | "lockLost" | "released" | "acquireTimeout"
+		console.log(event.type, event.lockName);
+	},
+});
+```
+
+## Custom Backends
+
+Implement the `Backend` interface to use any storage:
+
+```typescript
+import type { Backend } from "universal-lock";
+
+const myBackend: Backend = {
+	setup: async () => {},
+	acquire: async (lockName, stale, lockId) => {
+		// set lock or throw if already held
+	},
+	renew: async (lockName, lockId) => {
+		// extend lock TTL, verify ownership via lockId
+	},
+	release: async (lockName, lockId) => {
+		// delete lock, verify ownership via lockId
+	},
+};
+```
+
+## License
+
+[MIT](https://github.com/lucasrainett/universal-lock/blob/master/LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,26 @@
+import { Lock, Backend, LockConfiguration } from '@universal-lock/types';
+export { AsyncFunction, Backend, BackendAcquireFunction, BackendFactory, BackendReleaseFunction, BackendRenewFunction, BackendSetupFunction, CallbackLockEntry, Lock, LockAcquireFunction, LockConfiguration, LockEvent, LockReleaseFunction, TimestampLockEntry } from '@universal-lock/types';
+
+declare function lockFactory({ setup, acquire, renew, release }: Backend, configuration?: Partial<LockConfiguration>): Lock;
+/**
+ * Creates a decorator that wraps an async function with automatic lock
+ * acquisition and release. The lock is always released in the finally
+ * block, even if fn throws.
+ *
+ * First argument is either a lock name string or an options object.
+ * Pass `{ lockName, signal: true }` to inject an AbortSignal as the
+ * first argument so the function can react to lock loss during execution.
+ */
+declare function lockDecoratorFactory(lock: Lock): {
+    <A extends unknown[], R>(lockName: string, fn: (...args: A) => Promise<R>): (...args: A) => Promise<R>;
+    <A extends unknown[], R>(options: {
+        lockName: string;
+        signal: true;
+    }, fn: (signal: AbortSignal, ...args: A) => Promise<R>): (...args: A) => Promise<R>;
+    <A extends unknown[], R>(options: {
+        lockName: string;
+        signal?: false;
+    }, fn: (...args: A) => Promise<R>): (...args: A) => Promise<R>;
+};
+
+export { lockDecoratorFactory, lockFactory };

package/dist/index.d.ts

@@ -1,3 +1,26 @@
-import { lockFactory, lockDecoratoryFactory } from "./lock";
-import { memoryBackendFactory } from "./backends/MemoryBackend";
-export { memoryBackendFactory, lockFactory, lockDecoratoryFactory, };
+import { Lock, Backend, LockConfiguration } from '@universal-lock/types';
+export { AsyncFunction, Backend, BackendAcquireFunction, BackendFactory, BackendReleaseFunction, BackendRenewFunction, BackendSetupFunction, CallbackLockEntry, Lock, LockAcquireFunction, LockConfiguration, LockEvent, LockReleaseFunction, TimestampLockEntry } from '@universal-lock/types';
+
+declare function lockFactory({ setup, acquire, renew, release }: Backend, configuration?: Partial<LockConfiguration>): Lock;
+/**
+ * Creates a decorator that wraps an async function with automatic lock
+ * acquisition and release. The lock is always released in the finally
+ * block, even if fn throws.
+ *
+ * First argument is either a lock name string or an options object.
+ * Pass `{ lockName, signal: true }` to inject an AbortSignal as the
+ * first argument so the function can react to lock loss during execution.
+ */
+declare function lockDecoratorFactory(lock: Lock): {
+    <A extends unknown[], R>(lockName: string, fn: (...args: A) => Promise<R>): (...args: A) => Promise<R>;
+    <A extends unknown[], R>(options: {
+        lockName: string;
+        signal: true;
+    }, fn: (signal: AbortSignal, ...args: A) => Promise<R>): (...args: A) => Promise<R>;
+    <A extends unknown[], R>(options: {
+        lockName: string;
+        signal?: false;
+    }, fn: (...args: A) => Promise<R>): (...args: A) => Promise<R>;
+};
+
+export { lockDecoratorFactory, lockFactory };

package/dist/index.global.js

@@ -0,0 +1,175 @@
+"use strict";
+var UniversalLock = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/index.ts
+  var index_exports = {};
+  __export(index_exports, {
+    lockDecoratorFactory: () => lockDecoratorFactory,
+    lockFactory: () => lockFactory
+  });
+
+  // src/util.ts
+  var generateId = () => Array.from(
+    { length: 4 },
+    () => Math.floor(Math.random() * 4294967296).toString(16).padStart(8, "0")
+  ).join("");
+  var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  var asyncInterval = (handler, timeout) => {
+    let running = true;
+    const loop = (async () => {
+      while (running) {
+        await handler();
+        if (!running) break;
+        await sleep(timeout);
+      }
+    })();
+    return async () => {
+      running = false;
+      await loop;
+    };
+  };
+
+  // src/lock.ts
+  var noop = () => {
+  };
+  var defaultConfiguration = {
+    acquireInterval: 250,
+    acquireFailTimeout: 5e3,
+    stale: 1e3,
+    renewInterval: 250,
+    maxHoldTime: 2e3,
+    onLockLost: noop,
+    onEvent: noop
+  };
+  function lockFactory({ setup, acquire, renew, release }, configuration = {}) {
+    const {
+      acquireInterval,
+      acquireFailTimeout,
+      stale,
+      renewInterval,
+      maxHoldTime,
+      onLockLost,
+      onEvent
+    } = { ...defaultConfiguration, ...configuration };
+    const setupPromise = setup();
+    return {
+      async acquire(lockName) {
+        await setupPromise;
+        return new Promise((resolve, reject) => {
+          const lockId = generateId();
+          const abortController = new AbortController();
+          const acquireTimeout = setTimeout(async () => {
+            await stopAcquireInterval();
+            onEvent({ type: "acquireTimeout", lockName });
+            reject(
+              new Error(
+                `Failed to acquire lock "${lockName}" within ${acquireFailTimeout}ms`
+              )
+            );
+          }, acquireFailTimeout);
+          const stopAcquireInterval = asyncInterval(async () => {
+            try {
+              await acquire(lockName, stale, lockId);
+            } catch {
+              return;
+            }
+            clearTimeout(acquireTimeout);
+            stopAcquireInterval();
+            let maxHoldTimer = null;
+            let released = false;
+            const doRelease = async () => {
+              if (released) return;
+              released = true;
+              if (maxHoldTimer) clearTimeout(maxHoldTimer);
+              await release(lockName, lockId);
+              onEvent({ type: "released", lockName });
+            };
+            const releaseLock = async () => {
+              if (released) return;
+              await stopRenewInterval();
+              await doRelease();
+            };
+            const stopRenewInterval = asyncInterval(async () => {
+              try {
+                await renew(lockName, lockId);
+                onEvent({ type: "renewed", lockName });
+              } catch (error) {
+                onEvent({
+                  type: "renewFailed",
+                  lockName,
+                  error
+                });
+                onEvent({
+                  type: "lockLost",
+                  lockName,
+                  reason: "renewFailed"
+                });
+                onLockLost(lockName, "renewFailed");
+                abortController.abort();
+                stopRenewInterval();
+                await doRelease();
+              }
+            }, renewInterval);
+            maxHoldTimer = setTimeout(async () => {
+              onEvent({
+                type: "lockLost",
+                lockName,
+                reason: "timeout"
+              });
+              onLockLost(lockName, "timeout");
+              abortController.abort();
+              await releaseLock();
+            }, maxHoldTime);
+            onEvent({ type: "acquired", lockName });
+            const releaseFn = Object.assign(releaseLock, {
+              signal: abortController.signal
+            });
+            resolve(releaseFn);
+          }, acquireInterval);
+        });
+      }
+    };
+  }
+  function lockDecoratorFactory(lock) {
+    function decorator(lockNameOrOptions, fn) {
+      const { lockName, signal: injectSignal } = typeof lockNameOrOptions === "string" ? { lockName: lockNameOrOptions, signal: false } : lockNameOrOptions;
+      return async (...args) => {
+        const release = await lock.acquire(lockName);
+        let released = false;
+        const safeRelease = async () => {
+          if (released) return;
+          released = true;
+          await release();
+        };
+        try {
+          if (injectSignal) {
+            return await fn(release.signal, ...args);
+          }
+          return await fn(...args);
+        } finally {
+          await safeRelease();
+        }
+      };
+    }
+    return decorator;
+  }
+  return __toCommonJS(index_exports);
+})();
+//# sourceMappingURL=index.global.js.map

package/dist/index.global.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/util.ts","../src/lock.ts"],"sourcesContent":["import { lockFactory, lockDecoratorFactory } from \"./lock\";\n\nexport { lockFactory, lockDecoratorFactory };\n\nexport type {\n\tAsyncFunction,\n\tBackend,\n\tBackendFactory,\n\tBackendSetupFunction,\n\tBackendAcquireFunction,\n\tBackendRenewFunction,\n\tBackendReleaseFunction,\n\tLock,\n\tLockConfiguration,\n\tLockAcquireFunction,\n\tLockReleaseFunction,\n\tTimestampLockEntry,\n\tCallbackLockEntry,\n\tLockEvent,\n} from \"@universal-lock/types\";\n","import type { AsyncFunction } from \"@universal-lock/types\";\n\n// Generates a 32-character hex string (4 segments x 8 hex chars) used as a unique lock ownership ID\nexport const generateId = () =>\n\tArray.from({ length: 4 }, () =>\n\t\tMath.floor(Math.random() * 0x100000000)\n\t\t\t.toString(16)\n\t\t\t.padStart(8, \"0\"),\n\t).join(\"\");\n\nexport const sleep = async (ms: number) =>\n\tnew Promise((resolve) => setTimeout(resolve, ms));\n\n/**\n * Like setInterval but awaits each async handler before scheduling the next.\n * Returns a stop function that sets the running flag to false and waits for the\n * current iteration to finish, ensuring no handler runs after stop() resolves.\n * The double check on `running` (before and after sleep) allows the loop to\n * exit promptly when stopped mid-sleep.\n */\nexport const asyncInterval = <H extends AsyncFunction<void, []>>(\n\thandler: H,\n\ttimeout: number,\n) => {\n\tlet running = true;\n\tconst loop = (async () => {\n\t\twhile (running) {\n\t\t\tawait handler();\n\t\t\tif (!running) break;\n\t\t\tawait sleep(timeout);\n\t\t}\n\t})();\n\treturn async () => {\n\t\trunning = false;\n\t\tawait loop;\n\t};\n};\n","import type {\n\tLock,\n\tBackend,\n\tLockConfiguration,\n\tLockReleaseFunction,\n} from \"@universal-lock/types\";\nimport { asyncInterval, generateId } from \"./util\";\n\nconst noop = () => {};\n\nconst defaultConfiguration: LockConfiguration = {\n\tacquireInterval: 250,\n\tacquireFailTimeout: 5000,\n\tstale: 1000,\n\trenewInterval: 250,\n\tmaxHoldTime: 2000,\n\tonLockLost: noop,\n\tonEvent: noop,\n};\n\nexport function lockFactory(\n\t{ setup, acquire, renew, release }: Backend,\n\tconfiguration: Partial<LockConfiguration> = {},\n): Lock {\n\tconst {\n\t\tacquireInterval,\n\t\tacquireFailTimeout,\n\t\tstale,\n\t\trenewInterval,\n\t\tmaxHoldTime,\n\t\tonLockLost,\n\t\tonEvent,\n\t}: LockConfiguration = { ...defaultConfiguration, ...configuration };\n\t// Eagerly invoke backend setup so it runs once, not per-acquire\n\tconst setupPromise = setup();\n\n\treturn {\n\t\tasync acquire(lockName: string) {\n\t\t\tawait setupPromise;\n\t\t\treturn new Promise<LockReleaseFunction>((resolve, reject) => {\n\t\t\t\tconst lockId = generateId();\n\t\t\t\t// AbortController lets consumers detect lock loss via release.signal\n\t\t\t\tconst abortController = new AbortController();\n\n\t\t\t\t// Reject the acquire promise if the lock isn't obtained within the timeout\n\t\t\t\tconst acquireTimeout = setTimeout(async () => {\n\t\t\t\t\tawait stopAcquireInterval();\n\t\t\t\t\tonEvent({ type: \"acquireTimeout\", lockName });\n\t\t\t\t\treject(\n\t\t\t\t\t\tnew Error(\n\t\t\t\t\t\t\t`Failed to acquire lock \"${lockName}\" within ${acquireFailTimeout}ms`,\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t}, acquireFailTimeout);\n\n\t\t\t\t// Retry acquisition at a fixed interval until success or timeout\n\t\t\t\tconst stopAcquireInterval = asyncInterval(async () => {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tawait acquire(lockName, stale, lockId);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Acquire failed (lock held by another owner) — silently retry on next interval\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\n\t\t\t\t\t// Lock acquired — stop retrying and cancel the timeout\n\t\t\t\t\tclearTimeout(acquireTimeout);\n\t\t\t\t\tstopAcquireInterval();\n\n\t\t\t\t\tlet maxHoldTimer: ReturnType<typeof setTimeout> | null =\n\t\t\t\t\t\tnull;\n\t\t\t\t\t// Guards against double-release from concurrent timeout and manual release\n\t\t\t\t\tlet released = false;\n\n\t\t\t\t\t// Low-level release: idempotent, clears the running timer, notifies the backend\n\t\t\t\t\tconst doRelease = async () => {\n\t\t\t\t\t\tif (released) return;\n\t\t\t\t\t\treleased = true;\n\t\t\t\t\t\t/* v8 ignore next */\n\t\t\t\t\t\tif (maxHoldTimer) clearTimeout(maxHoldTimer);\n\t\t\t\t\t\tawait release(lockName, lockId);\n\t\t\t\t\t\tonEvent({ type: \"released\", lockName });\n\t\t\t\t\t};\n\n\t\t\t\t\t// High-level release: stops renewals first, then releases the lock\n\t\t\t\t\tconst releaseLock = async () => {\n\t\t\t\t\t\tif (released) return;\n\t\t\t\t\t\tawait stopRenewInterval();\n\t\t\t\t\t\tawait doRelease();\n\t\t\t\t\t};\n\n\t\t\t\t\t// Periodically renew the lock to prevent it from going stale\n\t\t\t\t\tconst stopRenewInterval = asyncInterval(async () => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tawait renew(lockName, lockId);\n\t\t\t\t\t\t\tonEvent({ type: \"renewed\", lockName });\n\t\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\t\tonEvent({\n\t\t\t\t\t\t\t\ttype: \"renewFailed\",\n\t\t\t\t\t\t\t\tlockName,\n\t\t\t\t\t\t\t\terror,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tonEvent({\n\t\t\t\t\t\t\t\ttype: \"lockLost\",\n\t\t\t\t\t\t\t\tlockName,\n\t\t\t\t\t\t\t\treason: \"renewFailed\",\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tonLockLost(lockName, \"renewFailed\");\n\t\t\t\t\t\t\t// Signal consumers that the lock is no longer held\n\t\t\t\t\t\t\tabortController.abort();\n\t\t\t\t\t\t\t// Don't await stopRenewInterval here — we're inside it\n\t\t\t\t\t\t\tstopRenewInterval();\n\t\t\t\t\t\t\tawait doRelease();\n\t\t\t\t\t\t}\n\t\t\t\t\t}, renewInterval);\n\n\t\t\t\t\t// Safety net: auto-release if the caller holds the lock too long\n\t\t\t\t\tmaxHoldTimer = setTimeout(async () => {\n\t\t\t\t\t\tonEvent({\n\t\t\t\t\t\t\ttype: \"lockLost\",\n\t\t\t\t\t\t\tlockName,\n\t\t\t\t\t\t\treason: \"timeout\",\n\t\t\t\t\t\t});\n\t\t\t\t\t\tonLockLost(lockName, \"timeout\");\n\t\t\t\t\t\tabortController.abort();\n\t\t\t\t\t\tawait releaseLock();\n\t\t\t\t\t}, maxHoldTime);\n\n\t\t\t\t\tonEvent({ type: \"acquired\", lockName });\n\n\t\t\t\t\t// Attach the abort signal to the release function so callers can\n\t\t\t\t\t// detect lock loss (e.g. via release.signal.aborted or addEventListener)\n\t\t\t\t\tconst releaseFn = Object.assign(releaseLock, {\n\t\t\t\t\t\tsignal: abortController.signal,\n\t\t\t\t\t}) as LockReleaseFunction;\n\t\t\t\t\tresolve(releaseFn);\n\t\t\t\t}, acquireInterval);\n\t\t\t});\n\t\t},\n\t};\n}\n\n/**\n * Creates a decorator that wraps an async function with automatic lock\n * acquisition and release. The lock is always released in the finally\n * block, even if fn throws.\n *\n * First argument is either a lock name string or an options object.\n * Pass `{ lockName, signal: true }` to inject an AbortSignal as the\n * first argument so the function can react to lock loss during execution.\n */\nexport function lockDecoratorFactory(lock: Lock) {\n\t// Overload: string lock name — fn keeps its original signature\n\tfunction decorator<A extends unknown[], R>(\n\t\tlockName: string,\n\t\tfn: (...args: A) => Promise<R>,\n\t): (...args: A) => Promise<R>;\n\n\t// Overload: options object with signal — fn receives AbortSignal as first arg\n\tfunction decorator<A extends unknown[], R>(\n\t\toptions: { lockName: string; signal: true },\n\t\tfn: (signal: AbortSignal, ...args: A) => Promise<R>,\n\t): (...args: A) => Promise<R>;\n\n\t// Overload: options object without signal — fn keeps its original signature\n\tfunction decorator<A extends unknown[], R>(\n\t\toptions: { lockName: string; signal?: false },\n\t\tfn: (...args: A) => Promise<R>,\n\t): (...args: A) => Promise<R>;\n\n\tfunction decorator<A extends unknown[], R>(\n\t\tlockNameOrOptions: string | { lockName: string; signal?: boolean },\n\t\tfn:\n\t\t\t| ((...args: A) => Promise<R>)\n\t\t\t| ((signal: AbortSignal, ...args: A) => Promise<R>),\n\t) {\n\t\tconst { lockName, signal: injectSignal } =\n\t\t\ttypeof lockNameOrOptions === \"string\"\n\t\t\t\t? { lockName: lockNameOrOptions, signal: false }\n\t\t\t\t: lockNameOrOptions;\n\n\t\treturn async (...args: A): Promise<R> => {\n\t\t\tconst release = await lock.acquire(lockName);\n\t\t\tlet released = false;\n\t\t\tconst safeRelease = async () => {\n\t\t\t\t/* v8 ignore next */\n\t\t\t\tif (released) return;\n\t\t\t\treleased = true;\n\t\t\t\tawait release();\n\t\t\t};\n\t\t\ttry {\n\t\t\t\t// Only inject the AbortSignal when the caller opted in\n\t\t\t\tif (injectSignal) {\n\t\t\t\t\treturn await (\n\t\t\t\t\t\tfn as (signal: AbortSignal, ...args: A) => Promise<R>\n\t\t\t\t\t)(release.signal, ...args);\n\t\t\t\t}\n\t\t\t\treturn await (fn as (...args: A) => Promise<R>)(...args);\n\t\t\t} finally {\n\t\t\t\tawait safeRelease();\n\t\t\t}\n\t\t};\n\t}\n\n\treturn decorator;\n}\n"],"mappings":"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","names":[]}

package/dist/index.js

@@ -0,0 +1,178 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  lockDecoratorFactory: () => lockDecoratorFactory,
+  lockFactory: () => lockFactory
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/util.ts
+var generateId = () => Array.from(
+  { length: 4 },
+  () => Math.floor(Math.random() * 4294967296).toString(16).padStart(8, "0")
+).join("");
+var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var asyncInterval = (handler, timeout) => {
+  let running = true;
+  const loop = (async () => {
+    while (running) {
+      await handler();
+      if (!running) break;
+      await sleep(timeout);
+    }
+  })();
+  return async () => {
+    running = false;
+    await loop;
+  };
+};
+
+// src/lock.ts
+var noop = () => {
+};
+var defaultConfiguration = {
+  acquireInterval: 250,
+  acquireFailTimeout: 5e3,
+  stale: 1e3,
+  renewInterval: 250,
+  maxHoldTime: 2e3,
+  onLockLost: noop,
+  onEvent: noop
+};
+function lockFactory({ setup, acquire, renew, release }, configuration = {}) {
+  const {
+    acquireInterval,
+    acquireFailTimeout,
+    stale,
+    renewInterval,
+    maxHoldTime,
+    onLockLost,
+    onEvent
+  } = { ...defaultConfiguration, ...configuration };
+  const setupPromise = setup();
+  return {
+    async acquire(lockName) {
+      await setupPromise;
+      return new Promise((resolve, reject) => {
+        const lockId = generateId();
+        const abortController = new AbortController();
+        const acquireTimeout = setTimeout(async () => {
+          await stopAcquireInterval();
+          onEvent({ type: "acquireTimeout", lockName });
+          reject(
+            new Error(
+              `Failed to acquire lock "${lockName}" within ${acquireFailTimeout}ms`
+            )
+          );
+        }, acquireFailTimeout);
+        const stopAcquireInterval = asyncInterval(async () => {
+          try {
+            await acquire(lockName, stale, lockId);
+          } catch {
+            return;
+          }
+          clearTimeout(acquireTimeout);
+          stopAcquireInterval();
+          let maxHoldTimer = null;
+          let released = false;
+          const doRelease = async () => {
+            if (released) return;
+            released = true;
+            if (maxHoldTimer) clearTimeout(maxHoldTimer);
+            await release(lockName, lockId);
+            onEvent({ type: "released", lockName });
+          };
+          const releaseLock = async () => {
+            if (released) return;
+            await stopRenewInterval();
+            await doRelease();
+          };
+          const stopRenewInterval = asyncInterval(async () => {
+            try {
+              await renew(lockName, lockId);
+              onEvent({ type: "renewed", lockName });
+            } catch (error) {
+              onEvent({
+                type: "renewFailed",
+                lockName,
+                error
+              });
+              onEvent({
+                type: "lockLost",
+                lockName,
+                reason: "renewFailed"
+              });
+              onLockLost(lockName, "renewFailed");
+              abortController.abort();
+              stopRenewInterval();
+              await doRelease();
+            }
+          }, renewInterval);
+          maxHoldTimer = setTimeout(async () => {
+            onEvent({
+              type: "lockLost",
+              lockName,
+              reason: "timeout"
+            });
+            onLockLost(lockName, "timeout");
+            abortController.abort();
+            await releaseLock();
+          }, maxHoldTime);
+          onEvent({ type: "acquired", lockName });
+          const releaseFn = Object.assign(releaseLock, {
+            signal: abortController.signal
+          });
+          resolve(releaseFn);
+        }, acquireInterval);
+      });
+    }
+  };
+}
+function lockDecoratorFactory(lock) {
+  function decorator(lockNameOrOptions, fn) {
+    const { lockName, signal: injectSignal } = typeof lockNameOrOptions === "string" ? { lockName: lockNameOrOptions, signal: false } : lockNameOrOptions;
+    return async (...args) => {
+      const release = await lock.acquire(lockName);
+      let released = false;
+      const safeRelease = async () => {
+        if (released) return;
+        released = true;
+        await release();
+      };
+      try {
+        if (injectSignal) {
+          return await fn(release.signal, ...args);
+        }
+        return await fn(...args);
+      } finally {
+        await safeRelease();
+      }
+    };
+  }
+  return decorator;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  lockDecoratorFactory,
+  lockFactory
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/util.ts","../src/lock.ts"],"sourcesContent":["import { lockFactory, lockDecoratorFactory } from \"./lock\";\n\nexport { lockFactory, lockDecoratorFactory };\n\nexport type {\n\tAsyncFunction,\n\tBackend,\n\tBackendFactory,\n\tBackendSetupFunction,\n\tBackendAcquireFunction,\n\tBackendRenewFunction,\n\tBackendReleaseFunction,\n\tLock,\n\tLockConfiguration,\n\tLockAcquireFunction,\n\tLockReleaseFunction,\n\tTimestampLockEntry,\n\tCallbackLockEntry,\n\tLockEvent,\n} from \"@universal-lock/types\";\n","import type { AsyncFunction } from \"@universal-lock/types\";\n\n// Generates a 32-character hex string (4 segments x 8 hex chars) used as a unique lock ownership ID\nexport const generateId = () =>\n\tArray.from({ length: 4 }, () =>\n\t\tMath.floor(Math.random() * 0x100000000)\n\t\t\t.toString(16)\n\t\t\t.padStart(8, \"0\"),\n\t).join(\"\");\n\nexport const sleep = async (ms: number) =>\n\tnew Promise((resolve) => setTimeout(resolve, ms));\n\n/**\n * Like setInterval but awaits each async handler before scheduling the next.\n * Returns a stop function that sets the running flag to false and waits for the\n * current iteration to finish, ensuring no handler runs after stop() resolves.\n * The double check on `running` (before and after sleep) allows the loop to\n * exit promptly when stopped mid-sleep.\n */\nexport const asyncInterval = <H extends AsyncFunction<void, []>>(\n\thandler: H,\n\ttimeout: number,\n) => {\n\tlet running = true;\n\tconst loop = (async () => {\n\t\twhile (running) {\n\t\t\tawait handler();\n\t\t\tif (!running) break;\n\t\t\tawait sleep(timeout);\n\t\t}\n\t})();\n\treturn async () => {\n\t\trunning = false;\n\t\tawait loop;\n\t};\n};\n","import type {\n\tLock,\n\tBackend,\n\tLockConfiguration,\n\tLockReleaseFunction,\n} from \"@universal-lock/types\";\nimport { asyncInterval, generateId } from \"./util\";\n\nconst noop = () => {};\n\nconst defaultConfiguration: LockConfiguration = {\n\tacquireInterval: 250,\n\tacquireFailTimeout: 5000,\n\tstale: 1000,\n\trenewInterval: 250,\n\tmaxHoldTime: 2000,\n\tonLockLost: noop,\n\tonEvent: noop,\n};\n\nexport function lockFactory(\n\t{ setup, acquire, renew, release }: Backend,\n\tconfiguration: Partial<LockConfiguration> = {},\n): Lock {\n\tconst {\n\t\tacquireInterval,\n\t\tacquireFailTimeout,\n\t\tstale,\n\t\trenewInterval,\n\t\tmaxHoldTime,\n\t\tonLockLost,\n\t\tonEvent,\n\t}: LockConfiguration = { ...defaultConfiguration, ...configuration };\n\t// Eagerly invoke backend setup so it runs once, not per-acquire\n\tconst setupPromise = setup();\n\n\treturn {\n\t\tasync acquire(lockName: string) {\n\t\t\tawait setupPromise;\n\t\t\treturn new Promise<LockReleaseFunction>((resolve, reject) => {\n\t\t\t\tconst lockId = generateId();\n\t\t\t\t// AbortController lets consumers detect lock loss via release.signal\n\t\t\t\tconst abortController = new AbortController();\n\n\t\t\t\t// Reject the acquire promise if the lock isn't obtained within the timeout\n\t\t\t\tconst acquireTimeout = setTimeout(async () => {\n\t\t\t\t\tawait stopAcquireInterval();\n\t\t\t\t\tonEvent({ type: \"acquireTimeout\", lockName });\n\t\t\t\t\treject(\n\t\t\t\t\t\tnew Error(\n\t\t\t\t\t\t\t`Failed to acquire lock \"${lockName}\" within ${acquireFailTimeout}ms`,\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t}, acquireFailTimeout);\n\n\t\t\t\t// Retry acquisition at a fixed interval until success or timeout\n\t\t\t\tconst stopAcquireInterval = asyncInterval(async () => {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tawait acquire(lockName, stale, lockId);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Acquire failed (lock held by another owner) — silently retry on next interval\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\n\t\t\t\t\t// Lock acquired — stop retrying and cancel the timeout\n\t\t\t\t\tclearTimeout(acquireTimeout);\n\t\t\t\t\tstopAcquireInterval();\n\n\t\t\t\t\tlet maxHoldTimer: ReturnType<typeof setTimeout> | null =\n\t\t\t\t\t\tnull;\n\t\t\t\t\t// Guards against double-release from concurrent timeout and manual release\n\t\t\t\t\tlet released = false;\n\n\t\t\t\t\t// Low-level release: idempotent, clears the running timer, notifies the backend\n\t\t\t\t\tconst doRelease = async () => {\n\t\t\t\t\t\tif (released) return;\n\t\t\t\t\t\treleased = true;\n\t\t\t\t\t\t/* v8 ignore next */\n\t\t\t\t\t\tif (maxHoldTimer) clearTimeout(maxHoldTimer);\n\t\t\t\t\t\tawait release(lockName, lockId);\n\t\t\t\t\t\tonEvent({ type: \"released\", lockName });\n\t\t\t\t\t};\n\n\t\t\t\t\t// High-level release: stops renewals first, then releases the lock\n\t\t\t\t\tconst releaseLock = async () => {\n\t\t\t\t\t\tif (released) return;\n\t\t\t\t\t\tawait stopRenewInterval();\n\t\t\t\t\t\tawait doRelease();\n\t\t\t\t\t};\n\n\t\t\t\t\t// Periodically renew the lock to prevent it from going stale\n\t\t\t\t\tconst stopRenewInterval = asyncInterval(async () => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tawait renew(lockName, lockId);\n\t\t\t\t\t\t\tonEvent({ type: \"renewed\", lockName });\n\t\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\t\tonEvent({\n\t\t\t\t\t\t\t\ttype: \"renewFailed\",\n\t\t\t\t\t\t\t\tlockName,\n\t\t\t\t\t\t\t\terror,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tonEvent({\n\t\t\t\t\t\t\t\ttype: \"lockLost\",\n\t\t\t\t\t\t\t\tlockName,\n\t\t\t\t\t\t\t\treason: \"renewFailed\",\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tonLockLost(lockName, \"renewFailed\");\n\t\t\t\t\t\t\t// Signal consumers that the lock is no longer held\n\t\t\t\t\t\t\tabortController.abort();\n\t\t\t\t\t\t\t// Don't await stopRenewInterval here — we're inside it\n\t\t\t\t\t\t\tstopRenewInterval();\n\t\t\t\t\t\t\tawait doRelease();\n\t\t\t\t\t\t}\n\t\t\t\t\t}, renewInterval);\n\n\t\t\t\t\t// Safety net: auto-release if the caller holds the lock too long\n\t\t\t\t\tmaxHoldTimer = setTimeout(async () => {\n\t\t\t\t\t\tonEvent({\n\t\t\t\t\t\t\ttype: \"lockLost\",\n\t\t\t\t\t\t\tlockName,\n\t\t\t\t\t\t\treason: \"timeout\",\n\t\t\t\t\t\t});\n\t\t\t\t\t\tonLockLost(lockName, \"timeout\");\n\t\t\t\t\t\tabortController.abort();\n\t\t\t\t\t\tawait releaseLock();\n\t\t\t\t\t}, maxHoldTime);\n\n\t\t\t\t\tonEvent({ type: \"acquired\", lockName });\n\n\t\t\t\t\t// Attach the abort signal to the release function so callers can\n\t\t\t\t\t// detect lock loss (e.g. via release.signal.aborted or addEventListener)\n\t\t\t\t\tconst releaseFn = Object.assign(releaseLock, {\n\t\t\t\t\t\tsignal: abortController.signal,\n\t\t\t\t\t}) as LockReleaseFunction;\n\t\t\t\t\tresolve(releaseFn);\n\t\t\t\t}, acquireInterval);\n\t\t\t});\n\t\t},\n\t};\n}\n\n/**\n * Creates a decorator that wraps an async function with automatic lock\n * acquisition and release. The lock is always released in the finally\n * block, even if fn throws.\n *\n * First argument is either a lock name string or an options object.\n * Pass `{ lockName, signal: true }` to inject an AbortSignal as the\n * first argument so the function can react to lock loss during execution.\n */\nexport function lockDecoratorFactory(lock: Lock) {\n\t// Overload: string lock name — fn keeps its original signature\n\tfunction decorator<A extends unknown[], R>(\n\t\tlockName: string,\n\t\tfn: (...args: A) => Promise<R>,\n\t): (...args: A) => Promise<R>;\n\n\t// Overload: options object with signal — fn receives AbortSignal as first arg\n\tfunction decorator<A extends unknown[], R>(\n\t\toptions: { lockName: string; signal: true },\n\t\tfn: (signal: AbortSignal, ...args: A) => Promise<R>,\n\t): (...args: A) => Promise<R>;\n\n\t// Overload: options object without signal — fn keeps its original signature\n\tfunction decorator<A extends unknown[], R>(\n\t\toptions: { lockName: string; signal?: false },\n\t\tfn: (...args: A) => Promise<R>,\n\t): (...args: A) => Promise<R>;\n\n\tfunction decorator<A extends unknown[], R>(\n\t\tlockNameOrOptions: string | { lockName: string; signal?: boolean },\n\t\tfn:\n\t\t\t| ((...args: A) => Promise<R>)\n\t\t\t| ((signal: AbortSignal, ...args: A) => Promise<R>),\n\t) {\n\t\tconst { lockName, signal: injectSignal } =\n\t\t\ttypeof lockNameOrOptions === \"string\"\n\t\t\t\t? { lockName: lockNameOrOptions, signal: false }\n\t\t\t\t: lockNameOrOptions;\n\n\t\treturn async (...args: A): Promise<R> => {\n\t\t\tconst release = await lock.acquire(lockName);\n\t\t\tlet released = false;\n\t\t\tconst safeRelease = async () => {\n\t\t\t\t/* v8 ignore next */\n\t\t\t\tif (released) return;\n\t\t\t\treleased = true;\n\t\t\t\tawait release();\n\t\t\t};\n\t\t\ttry {\n\t\t\t\t// Only inject the AbortSignal when the caller opted in\n\t\t\t\tif (injectSignal) {\n\t\t\t\t\treturn await (\n\t\t\t\t\t\tfn as (signal: AbortSignal, ...args: A) => Promise<R>\n\t\t\t\t\t)(release.signal, ...args);\n\t\t\t\t}\n\t\t\t\treturn await (fn as (...args: A) => Promise<R>)(...args);\n\t\t\t} finally {\n\t\t\t\tawait safeRelease();\n\t\t\t}\n\t\t};\n\t}\n\n\treturn decorator;\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,150 @@
+// src/util.ts
+var generateId = () => Array.from(
+  { length: 4 },
+  () => Math.floor(Math.random() * 4294967296).toString(16).padStart(8, "0")
+).join("");
+var sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var asyncInterval = (handler, timeout) => {
+  let running = true;
+  const loop = (async () => {
+    while (running) {
+      await handler();
+      if (!running) break;
+      await sleep(timeout);
+    }
+  })();
+  return async () => {
+    running = false;
+    await loop;
+  };
+};
+
+// src/lock.ts
+var noop = () => {
+};
+var defaultConfiguration = {
+  acquireInterval: 250,
+  acquireFailTimeout: 5e3,
+  stale: 1e3,
+  renewInterval: 250,
+  maxHoldTime: 2e3,
+  onLockLost: noop,
+  onEvent: noop
+};
+function lockFactory({ setup, acquire, renew, release }, configuration = {}) {
+  const {
+    acquireInterval,
+    acquireFailTimeout,
+    stale,
+    renewInterval,
+    maxHoldTime,
+    onLockLost,
+    onEvent
+  } = { ...defaultConfiguration, ...configuration };
+  const setupPromise = setup();
+  return {
+    async acquire(lockName) {
+      await setupPromise;
+      return new Promise((resolve, reject) => {
+        const lockId = generateId();
+        const abortController = new AbortController();
+        const acquireTimeout = setTimeout(async () => {
+          await stopAcquireInterval();
+          onEvent({ type: "acquireTimeout", lockName });
+          reject(
+            new Error(
+              `Failed to acquire lock "${lockName}" within ${acquireFailTimeout}ms`
+            )
+          );
+        }, acquireFailTimeout);
+        const stopAcquireInterval = asyncInterval(async () => {
+          try {
+            await acquire(lockName, stale, lockId);
+          } catch {
+            return;
+          }
+          clearTimeout(acquireTimeout);
+          stopAcquireInterval();
+          let maxHoldTimer = null;
+          let released = false;
+          const doRelease = async () => {
+            if (released) return;
+            released = true;
+            if (maxHoldTimer) clearTimeout(maxHoldTimer);
+            await release(lockName, lockId);
+            onEvent({ type: "released", lockName });
+          };
+          const releaseLock = async () => {
+            if (released) return;
+            await stopRenewInterval();
+            await doRelease();
+          };
+          const stopRenewInterval = asyncInterval(async () => {
+            try {
+              await renew(lockName, lockId);
+              onEvent({ type: "renewed", lockName });
+            } catch (error) {
+              onEvent({
+                type: "renewFailed",
+                lockName,
+                error
+              });
+              onEvent({
+                type: "lockLost",
+                lockName,
+                reason: "renewFailed"
+              });
+              onLockLost(lockName, "renewFailed");
+              abortController.abort();
+              stopRenewInterval();
+              await doRelease();
+            }
+          }, renewInterval);
+          maxHoldTimer = setTimeout(async () => {
+            onEvent({
+              type: "lockLost",
+              lockName,
+              reason: "timeout"
+            });
+            onLockLost(lockName, "timeout");
+            abortController.abort();
+            await releaseLock();
+          }, maxHoldTime);
+          onEvent({ type: "acquired", lockName });
+          const releaseFn = Object.assign(releaseLock, {
+            signal: abortController.signal
+          });
+          resolve(releaseFn);
+        }, acquireInterval);
+      });
+    }
+  };
+}
+function lockDecoratorFactory(lock) {
+  function decorator(lockNameOrOptions, fn) {
+    const { lockName, signal: injectSignal } = typeof lockNameOrOptions === "string" ? { lockName: lockNameOrOptions, signal: false } : lockNameOrOptions;
+    return async (...args) => {
+      const release = await lock.acquire(lockName);
+      let released = false;
+      const safeRelease = async () => {
+        if (released) return;
+        released = true;
+        await release();
+      };
+      try {
+        if (injectSignal) {
+          return await fn(release.signal, ...args);
+        }
+        return await fn(...args);
+      } finally {
+        await safeRelease();
+      }
+    };
+  }
+  return decorator;
+}
+export {
+  lockDecoratorFactory,
+  lockFactory
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/util.ts","../src/lock.ts"],"sourcesContent":["import type { AsyncFunction } from \"@universal-lock/types\";\n\n// Generates a 32-character hex string (4 segments x 8 hex chars) used as a unique lock ownership ID\nexport const generateId = () =>\n\tArray.from({ length: 4 }, () =>\n\t\tMath.floor(Math.random() * 0x100000000)\n\t\t\t.toString(16)\n\t\t\t.padStart(8, \"0\"),\n\t).join(\"\");\n\nexport const sleep = async (ms: number) =>\n\tnew Promise((resolve) => setTimeout(resolve, ms));\n\n/**\n * Like setInterval but awaits each async handler before scheduling the next.\n * Returns a stop function that sets the running flag to false and waits for the\n * current iteration to finish, ensuring no handler runs after stop() resolves.\n * The double check on `running` (before and after sleep) allows the loop to\n * exit promptly when stopped mid-sleep.\n */\nexport const asyncInterval = <H extends AsyncFunction<void, []>>(\n\thandler: H,\n\ttimeout: number,\n) => {\n\tlet running = true;\n\tconst loop = (async () => {\n\t\twhile (running) {\n\t\t\tawait handler();\n\t\t\tif (!running) break;\n\t\t\tawait sleep(timeout);\n\t\t}\n\t})();\n\treturn async () => {\n\t\trunning = false;\n\t\tawait loop;\n\t};\n};\n","import type {\n\tLock,\n\tBackend,\n\tLockConfiguration,\n\tLockReleaseFunction,\n} from \"@universal-lock/types\";\nimport { asyncInterval, generateId } from \"./util\";\n\nconst noop = () => {};\n\nconst defaultConfiguration: LockConfiguration = {\n\tacquireInterval: 250,\n\tacquireFailTimeout: 5000,\n\tstale: 1000,\n\trenewInterval: 250,\n\tmaxHoldTime: 2000,\n\tonLockLost: noop,\n\tonEvent: noop,\n};\n\nexport function lockFactory(\n\t{ setup, acquire, renew, release }: Backend,\n\tconfiguration: Partial<LockConfiguration> = {},\n): Lock {\n\tconst {\n\t\tacquireInterval,\n\t\tacquireFailTimeout,\n\t\tstale,\n\t\trenewInterval,\n\t\tmaxHoldTime,\n\t\tonLockLost,\n\t\tonEvent,\n\t}: LockConfiguration = { ...defaultConfiguration, ...configuration };\n\t// Eagerly invoke backend setup so it runs once, not per-acquire\n\tconst setupPromise = setup();\n\n\treturn {\n\t\tasync acquire(lockName: string) {\n\t\t\tawait setupPromise;\n\t\t\treturn new Promise<LockReleaseFunction>((resolve, reject) => {\n\t\t\t\tconst lockId = generateId();\n\t\t\t\t// AbortController lets consumers detect lock loss via release.signal\n\t\t\t\tconst abortController = new AbortController();\n\n\t\t\t\t// Reject the acquire promise if the lock isn't obtained within the timeout\n\t\t\t\tconst acquireTimeout = setTimeout(async () => {\n\t\t\t\t\tawait stopAcquireInterval();\n\t\t\t\t\tonEvent({ type: \"acquireTimeout\", lockName });\n\t\t\t\t\treject(\n\t\t\t\t\t\tnew Error(\n\t\t\t\t\t\t\t`Failed to acquire lock \"${lockName}\" within ${acquireFailTimeout}ms`,\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t}, acquireFailTimeout);\n\n\t\t\t\t// Retry acquisition at a fixed interval until success or timeout\n\t\t\t\tconst stopAcquireInterval = asyncInterval(async () => {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tawait acquire(lockName, stale, lockId);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Acquire failed (lock held by another owner) — silently retry on next interval\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\n\t\t\t\t\t// Lock acquired — stop retrying and cancel the timeout\n\t\t\t\t\tclearTimeout(acquireTimeout);\n\t\t\t\t\tstopAcquireInterval();\n\n\t\t\t\t\tlet maxHoldTimer: ReturnType<typeof setTimeout> | null =\n\t\t\t\t\t\tnull;\n\t\t\t\t\t// Guards against double-release from concurrent timeout and manual release\n\t\t\t\t\tlet released = false;\n\n\t\t\t\t\t// Low-level release: idempotent, clears the running timer, notifies the backend\n\t\t\t\t\tconst doRelease = async () => {\n\t\t\t\t\t\tif (released) return;\n\t\t\t\t\t\treleased = true;\n\t\t\t\t\t\t/* v8 ignore next */\n\t\t\t\t\t\tif (maxHoldTimer) clearTimeout(maxHoldTimer);\n\t\t\t\t\t\tawait release(lockName, lockId);\n\t\t\t\t\t\tonEvent({ type: \"released\", lockName });\n\t\t\t\t\t};\n\n\t\t\t\t\t// High-level release: stops renewals first, then releases the lock\n\t\t\t\t\tconst releaseLock = async () => {\n\t\t\t\t\t\tif (released) return;\n\t\t\t\t\t\tawait stopRenewInterval();\n\t\t\t\t\t\tawait doRelease();\n\t\t\t\t\t};\n\n\t\t\t\t\t// Periodically renew the lock to prevent it from going stale\n\t\t\t\t\tconst stopRenewInterval = asyncInterval(async () => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tawait renew(lockName, lockId);\n\t\t\t\t\t\t\tonEvent({ type: \"renewed\", lockName });\n\t\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\t\tonEvent({\n\t\t\t\t\t\t\t\ttype: \"renewFailed\",\n\t\t\t\t\t\t\t\tlockName,\n\t\t\t\t\t\t\t\terror,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tonEvent({\n\t\t\t\t\t\t\t\ttype: \"lockLost\",\n\t\t\t\t\t\t\t\tlockName,\n\t\t\t\t\t\t\t\treason: \"renewFailed\",\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tonLockLost(lockName, \"renewFailed\");\n\t\t\t\t\t\t\t// Signal consumers that the lock is no longer held\n\t\t\t\t\t\t\tabortController.abort();\n\t\t\t\t\t\t\t// Don't await stopRenewInterval here — we're inside it\n\t\t\t\t\t\t\tstopRenewInterval();\n\t\t\t\t\t\t\tawait doRelease();\n\t\t\t\t\t\t}\n\t\t\t\t\t}, renewInterval);\n\n\t\t\t\t\t// Safety net: auto-release if the caller holds the lock too long\n\t\t\t\t\tmaxHoldTimer = setTimeout(async () => {\n\t\t\t\t\t\tonEvent({\n\t\t\t\t\t\t\ttype: \"lockLost\",\n\t\t\t\t\t\t\tlockName,\n\t\t\t\t\t\t\treason: \"timeout\",\n\t\t\t\t\t\t});\n\t\t\t\t\t\tonLockLost(lockName, \"timeout\");\n\t\t\t\t\t\tabortController.abort();\n\t\t\t\t\t\tawait releaseLock();\n\t\t\t\t\t}, maxHoldTime);\n\n\t\t\t\t\tonEvent({ type: \"acquired\", lockName });\n\n\t\t\t\t\t// Attach the abort signal to the release function so callers can\n\t\t\t\t\t// detect lock loss (e.g. via release.signal.aborted or addEventListener)\n\t\t\t\t\tconst releaseFn = Object.assign(releaseLock, {\n\t\t\t\t\t\tsignal: abortController.signal,\n\t\t\t\t\t}) as LockReleaseFunction;\n\t\t\t\t\tresolve(releaseFn);\n\t\t\t\t}, acquireInterval);\n\t\t\t});\n\t\t},\n\t};\n}\n\n/**\n * Creates a decorator that wraps an async function with automatic lock\n * acquisition and release. The lock is always released in the finally\n * block, even if fn throws.\n *\n * First argument is either a lock name string or an options object.\n * Pass `{ lockName, signal: true }` to inject an AbortSignal as the\n * first argument so the function can react to lock loss during execution.\n */\nexport function lockDecoratorFactory(lock: Lock) {\n\t// Overload: string lock name — fn keeps its original signature\n\tfunction decorator<A extends unknown[], R>(\n\t\tlockName: string,\n\t\tfn: (...args: A) => Promise<R>,\n\t): (...args: A) => Promise<R>;\n\n\t// Overload: options object with signal — fn receives AbortSignal as first arg\n\tfunction decorator<A extends unknown[], R>(\n\t\toptions: { lockName: string; signal: true },\n\t\tfn: (signal: AbortSignal, ...args: A) => Promise<R>,\n\t): (...args: A) => Promise<R>;\n\n\t// Overload: options object without signal — fn keeps its original signature\n\tfunction decorator<A extends unknown[], R>(\n\t\toptions: { lockName: string; signal?: false },\n\t\tfn: (...args: A) => Promise<R>,\n\t): (...args: A) => Promise<R>;\n\n\tfunction decorator<A extends unknown[], R>(\n\t\tlockNameOrOptions: string | { lockName: string; signal?: boolean },\n\t\tfn:\n\t\t\t| ((...args: A) => Promise<R>)\n\t\t\t| ((signal: AbortSignal, ...args: A) => Promise<R>),\n\t) {\n\t\tconst { lockName, signal: injectSignal } =\n\t\t\ttypeof lockNameOrOptions === \"string\"\n\t\t\t\t? { lockName: lockNameOrOptions, signal: false }\n\t\t\t\t: lockNameOrOptions;\n\n\t\treturn async (...args: A): Promise<R> => {\n\t\t\tconst release = await lock.acquire(lockName);\n\t\t\tlet released = false;\n\t\t\tconst safeRelease = async () => {\n\t\t\t\t/* v8 ignore next */\n\t\t\t\tif (released) return;\n\t\t\t\treleased = true;\n\t\t\t\tawait release();\n\t\t\t};\n\t\t\ttry {\n\t\t\t\t// Only inject the AbortSignal when the caller opted in\n\t\t\t\tif (injectSignal) {\n\t\t\t\t\treturn await (\n\t\t\t\t\t\tfn as (signal: AbortSignal, ...args: A) => Promise<R>\n\t\t\t\t\t)(release.signal, ...args);\n\t\t\t\t}\n\t\t\t\treturn await (fn as (...args: A) => Promise<R>)(...args);\n\t\t\t} finally {\n\t\t\t\tawait safeRelease();\n\t\t\t}\n\t\t};\n\t}\n\n\treturn decorator;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,28 +1,43 @@
 {
   "name": "universal-lock",
-  "version": "0.0.2",
-  "description": "UniversalLock",
-  "main": "dist/index.umd.js",
+  "version": "1.0.0",
+  "description": "Lightweight, isomorphic universal locking library with pluggable backends",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "browser": "dist/index.global.js",
   "types": "dist/index.d.ts",
-  "type": "commonjs",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
   "files": [
     "/dist"
   ],
-  "scripts": {
-    "build": "webpack",
-    "clean": "rm -rf dist",
-    "format": "prettier --write --ignore-unknown .",
-    "test": "jest --coverage",
-    "prepare": "husky"
-  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/lucasrainett/universal-lock"
+    "url": "https://github.com/lucasrainett/universal-lock",
+    "directory": "packages/core"
   },
   "keywords": [
-    "UniversalLock",
-    "Database",
-    "nosql"
+    "lock",
+    "mutex",
+    "distributed-lock",
+    "locking",
+    "concurrency",
+    "semaphore",
+    "isomorphic"
   ],
   "author": {
     "name": "Lucas Rainett",
@@ -30,21 +45,11 @@
     "url": "https://github.com/lucasrainett"
   },
   "license": "MIT",
-  "packageManager": "pnpm@10.11.1",
-  "devDependencies": {
-    "@types/jest": "^29.5.14",
-    "husky": "^9.1.7",
-    "jest": "^29.7.0",
-    "lint-staged": "^16.1.0",
-    "prettier": "^3.5.3",
-    "ts-jest": "^29.3.4",
-    "ts-loader": "^9.5.2",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.8.3",
-    "webpack": "^5.99.9",
-    "webpack-cli": "^6.0.1"
-  },
   "dependencies": {
-    "rimraf": "^6.0.1"
+    "@universal-lock/types": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist"
   }
-}
+}

package/dist/backends/FileBackend.d.ts

@@ -1,2 +0,0 @@
-import { Backend } from "../types";
-export declare const fileBackendFactory: (lockFolderPath: string) => Backend;

package/dist/backends/MemoryBackend.d.ts

@@ -1,2 +0,0 @@
-import { BackendFactory } from "../types";
-export declare const memoryBackendFactory: BackendFactory;

package/dist/index.umd.js

@@ -1,182 +0,0 @@
-(function webpackUniversalModuleDefinition(root, factory) {
-	if(typeof exports === 'object' && typeof module === 'object')
-		module.exports = factory();
-	else if(typeof define === 'function' && define.amd)
-		define([], factory);
-	else if(typeof exports === 'object')
-		exports["UniversalLock"] = factory();
-	else
-		root["UniversalLock"] = factory();
-})(this, function() {
-return /******/ (function() { // webpackBootstrap
-/******/ 	"use strict";
-/******/ 	var __webpack_modules__ = ({
-
-/***/ 112:
-/***/ (function(__unused_webpack_module, exports) {
-
-
-Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.memoryBackendFactory = void 0;
-exports.memoryBackendFactory = ((locks = {}) => {
-    const setup = async () => { };
-    const acquire = async (lockName, stale) => {
-        const now = Date.now();
-        const lockExists = !!locks[lockName];
-        const lockExpired = lockExists && locks[lockName] + stale < now;
-        if (!lockExists || lockExpired) {
-            locks[lockName] = now;
-        }
-        else {
-            throw new Error(`${lockName} already locked`);
-        }
-    };
-    const renew = async (lockName) => {
-        locks[lockName] = Date.now();
-    };
-    const release = async (lockName) => {
-        delete locks[lockName];
-    };
-    return {
-        setup,
-        acquire,
-        renew,
-        release,
-    };
-});
-
-
-/***/ }),
-
-/***/ 340:
-/***/ (function(__unused_webpack_module, exports, __webpack_require__) {
-
-
-Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.lockFactory = lockFactory;
-exports.lockDecoratoryFactory = lockDecoratoryFactory;
-const util_1 = __webpack_require__(639);
-const defaultConfiguration = {
-    acquireInterval: 250,
-    acquireFailTimeout: 5000,
-    stale: 1000,
-    renewInterval: 250,
-    runningTimeout: 2000,
-};
-function lockFactory({ setup, acquire, renew, release }, configuration = {}) {
-    const { acquireInterval, acquireFailTimeout, stale, renewInterval, runningTimeout, } = Object.assign(Object.assign({}, defaultConfiguration), configuration);
-    const setupPromise = setup();
-    return {
-        async acquire(lockName) {
-            await setupPromise;
-            return new Promise((resolve) => {
-                const stopAcquireInterval = (0, util_1.asyncInterval)(async () => {
-                    try {
-                        await acquire(lockName, stale);
-                        const stopRenewInterval = (0, util_1.asyncInterval)(async () => {
-                            await renew(lockName);
-                        }, renewInterval);
-                        const releaseLock = async () => {
-                            await stopRenewInterval();
-                            await release(lockName);
-                        };
-                        stopAcquireInterval().then(() => {
-                            resolve(releaseLock);
-                        });
-                    }
-                    catch (e) { }
-                }, acquireInterval);
-            });
-        }
-    };
-}
-function lockDecoratoryFactory(lock) {
-    return (lockName, fn) => {
-        return async (...args) => {
-            const release = await lock.acquire(lockName);
-            try {
-                return await fn(...args);
-            }
-            finally {
-                await release();
-            }
-        };
-    };
-}
-
-
-/***/ }),
-
-/***/ 639:
-/***/ (function(__unused_webpack_module, exports) {
-
-
-Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.asyncInterval = exports.sleep = void 0;
-const sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-exports.sleep = sleep;
-const asyncInterval = (handler, timeout) => {
-    let running = true;
-    (async () => {
-        while (running) {
-            await handler();
-            if (!running)
-                break;
-            await (0, exports.sleep)(timeout);
-        }
-    })();
-    return async () => {
-        running = false;
-    };
-};
-exports.asyncInterval = asyncInterval;
-
-
-/***/ })
-
-/******/ 	});
-/************************************************************************/
-/******/ 	// The module cache
-/******/ 	var __webpack_module_cache__ = {};
-/******/ 	
-/******/ 	// The require function
-/******/ 	function __webpack_require__(moduleId) {
-/******/ 		// Check if module is in cache
-/******/ 		var cachedModule = __webpack_module_cache__[moduleId];
-/******/ 		if (cachedModule !== undefined) {
-/******/ 			return cachedModule.exports;
-/******/ 		}
-/******/ 		// Create a new module (and put it into the cache)
-/******/ 		var module = __webpack_module_cache__[moduleId] = {
-/******/ 			// no module.id needed
-/******/ 			// no module.loaded needed
-/******/ 			exports: {}
-/******/ 		};
-/******/ 	
-/******/ 		// Execute the module function
-/******/ 		__webpack_modules__[moduleId](module, module.exports, __webpack_require__);
-/******/ 	
-/******/ 		// Return the exports of the module
-/******/ 		return module.exports;
-/******/ 	}
-/******/ 	
-/************************************************************************/
-var __webpack_exports__ = {};
-// This entry needs to be wrapped in an IIFE because it uses a non-standard name for the exports (exports).
-!function() {
-var exports = __webpack_exports__;
-
-Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.lockDecoratoryFactory = exports.lockFactory = exports.memoryBackendFactory = void 0;
-const lock_1 = __webpack_require__(340);
-Object.defineProperty(exports, "lockFactory", ({ enumerable: true, get: function () { return lock_1.lockFactory; } }));
-Object.defineProperty(exports, "lockDecoratoryFactory", ({ enumerable: true, get: function () { return lock_1.lockDecoratoryFactory; } }));
-const MemoryBackend_1 = __webpack_require__(112);
-Object.defineProperty(exports, "memoryBackendFactory", ({ enumerable: true, get: function () { return MemoryBackend_1.memoryBackendFactory; } }));
-
-}();
-/******/ 	return __webpack_exports__;
-/******/ })()
-;
-});
-//# sourceMappingURL=index.umd.js.map

package/dist/index.umd.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.umd.js","mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;;;;;;ACVA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;;;;;;;AC5BA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;;;;;;;ACnDA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;;;;;;ACnBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;;;;;ACvBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA","sources":["webpack://UniversalLock/webpack/universalModuleDefinition","webpack://UniversalLock/./src/backends/MemoryBackend.ts","webpack://UniversalLock/./src/lock.ts","webpack://UniversalLock/./src/util.ts","webpack://UniversalLock/webpack/bootstrap","webpack://UniversalLock/./src/index.ts"],"sourcesContent":["(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory();\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine([], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"UniversalLock\"] = factory();\n\telse\n\t\troot[\"UniversalLock\"] = factory();\n})(this, function() {\nreturn ","\"use strict\";\nObject.defineProperty(exports, \"__esModule\", { value: true });\nexports.memoryBackendFactory = void 0;\nexports.memoryBackendFactory = ((locks = {}) => {\n    const setup = async () => { };\n    const acquire = async (lockName, stale) => {\n        const now = Date.now();\n        const lockExists = !!locks[lockName];\n        const lockExpired = lockExists && locks[lockName] + stale < now;\n        if (!lockExists || lockExpired) {\n            locks[lockName] = now;\n        }\n        else {\n            throw new Error(`${lockName} already locked`);\n        }\n    };\n    const renew = async (lockName) => {\n        locks[lockName] = Date.now();\n    };\n    const release = async (lockName) => {\n        delete locks[lockName];\n    };\n    return {\n        setup,\n        acquire,\n        renew,\n        release,\n    };\n});\n","\"use strict\";\nObject.defineProperty(exports, \"__esModule\", { value: true });\nexports.lockFactory = lockFactory;\nexports.lockDecoratoryFactory = lockDecoratoryFactory;\nconst util_1 = require(\"./util\");\nconst defaultConfiguration = {\n    acquireInterval: 250,\n    acquireFailTimeout: 5000,\n    stale: 1000,\n    renewInterval: 250,\n    runningTimeout: 2000,\n};\nfunction lockFactory({ setup, acquire, renew, release }, configuration = {}) {\n    const { acquireInterval, acquireFailTimeout, stale, renewInterval, runningTimeout, } = Object.assign(Object.assign({}, defaultConfiguration), configuration);\n    const setupPromise = setup();\n    return {\n        async acquire(lockName) {\n            await setupPromise;\n            return new Promise((resolve) => {\n                const stopAcquireInterval = (0, util_1.asyncInterval)(async () => {\n                    try {\n                        await acquire(lockName, stale);\n                        const stopRenewInterval = (0, util_1.asyncInterval)(async () => {\n                            await renew(lockName);\n                        }, renewInterval);\n                        const releaseLock = async () => {\n                            await stopRenewInterval();\n                            await release(lockName);\n                        };\n                        stopAcquireInterval().then(() => {\n                            resolve(releaseLock);\n                        });\n                    }\n                    catch (e) { }\n                }, acquireInterval);\n            });\n        }\n    };\n}\nfunction lockDecoratoryFactory(lock) {\n    return (lockName, fn) => {\n        return async (...args) => {\n            const release = await lock.acquire(lockName);\n            try {\n                return await fn(...args);\n            }\n            finally {\n                await release();\n            }\n        };\n    };\n}\n","\"use strict\";\nObject.defineProperty(exports, \"__esModule\", { value: true });\nexports.asyncInterval = exports.sleep = void 0;\nconst sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));\nexports.sleep = sleep;\nconst asyncInterval = (handler, timeout) => {\n    let running = true;\n    (async () => {\n        while (running) {\n            await handler();\n            if (!running)\n                break;\n            await (0, exports.sleep)(timeout);\n        }\n    })();\n    return async () => {\n        running = false;\n    };\n};\nexports.asyncInterval = asyncInterval;\n","// The module cache\nvar __webpack_module_cache__ = {};\n\n// The require function\nfunction __webpack_require__(moduleId) {\n\t// Check if module is in cache\n\tvar cachedModule = __webpack_module_cache__[moduleId];\n\tif (cachedModule !== undefined) {\n\t\treturn cachedModule.exports;\n\t}\n\t// Create a new module (and put it into the cache)\n\tvar module = __webpack_module_cache__[moduleId] = {\n\t\t// no module.id needed\n\t\t// no module.loaded needed\n\t\texports: {}\n\t};\n\n\t// Execute the module function\n\t__webpack_modules__[moduleId](module, module.exports, __webpack_require__);\n\n\t// Return the exports of the module\n\treturn module.exports;\n}\n\n","\"use strict\";\nObject.defineProperty(exports, \"__esModule\", { value: true });\nexports.lockDecoratoryFactory = exports.lockFactory = exports.memoryBackendFactory = void 0;\nconst lock_1 = require(\"./lock\");\nObject.defineProperty(exports, \"lockFactory\", { enumerable: true, get: function () { return lock_1.lockFactory; } });\nObject.defineProperty(exports, \"lockDecoratoryFactory\", { enumerable: true, get: function () { return lock_1.lockDecoratoryFactory; } });\nconst MemoryBackend_1 = require(\"./backends/MemoryBackend\");\nObject.defineProperty(exports, \"memoryBackendFactory\", { enumerable: true, get: function () { return MemoryBackend_1.memoryBackendFactory; } });\n"],"names":[],"sourceRoot":""}

package/dist/lock.d.ts

@@ -1,3 +0,0 @@
-import { AsyncFunction, Lock, Backend, LockConfiguration } from "./types";
-export declare function lockFactory({ setup, acquire, renew, release }: Backend, configuration?: Partial<LockConfiguration>): Lock;
-export declare function lockDecoratoryFactory(lock: Lock): <F extends AsyncFunction>(lockName: string, fn: F) => (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;

package/dist/types.d.ts

@@ -1,24 +0,0 @@
-export type AsyncFunction<R extends any = any, P extends any[] = any[]> = (...args: P) => Promise<R>;
-export type BackendSetupFunction = () => Promise<void>;
-export type BackendAcquireFunction = (lockName: string, stale: number) => Promise<void>;
-export type BackendRenewFunction = (lockName: string) => Promise<void>;
-export type BackendReleaseFunction = (lockName: string) => Promise<void>;
-export type Backend = {
-    setup: BackendSetupFunction;
-    acquire: BackendAcquireFunction;
-    renew: BackendRenewFunction;
-    release: BackendReleaseFunction;
-};
-export type BackendFactory = (...args: any[]) => Backend;
-export type LockConfiguration = {
-    acquireInterval: number;
-    acquireFailTimeout: number;
-    stale: number;
-    renewInterval: number;
-    runningTimeout: number;
-};
-export type LockReleaseFunction = () => Promise<void>;
-export type LockAcquireFunction = (lockName: string) => Promise<LockReleaseFunction>;
-export type Lock = {
-    acquire: LockAcquireFunction;
-};

package/dist/util.d.ts

@@ -1,3 +0,0 @@
-import { AsyncFunction } from "./types";
-export declare const sleep: (ms: number) => Promise<unknown>;
-export declare const asyncInterval: <H extends AsyncFunction<void, []>>(handler: H, timeout: number) => () => Promise<void>;