@universal-lock/local-storage 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,81 @@
+# @universal-lock/local-storage
+
+LocalStorage backend for [`universal-lock`](https://github.com/lucasrainett/universal-lock). Provides cross-tab locking in browsers using `localStorage`.
+
+## Installation
+
+```bash
+npm install universal-lock @universal-lock/local-storage
+```
+
+## Usage
+
+### ESM
+
+```typescript
+import { lockFactory } from "universal-lock";
+import { createBackend } from "@universal-lock/local-storage";
+
+const lock = lockFactory(createBackend());
+
+const release = await lock.acquire("my-resource");
+try {
+	// critical section — safe across browser tabs
+} finally {
+	await release();
+}
+```
+
+### CommonJS
+
+```javascript
+const { lockFactory } = require("universal-lock");
+const { createBackend } = require("@universal-lock/local-storage");
+
+const lock = lockFactory(createBackend());
+```
+
+### Browser (IIFE)
+
+```html
+<script src="https://unpkg.com/@universal-lock/local-storage/dist/index.global.js"></script>
+<script src="https://unpkg.com/universal-lock/dist/index.global.js"></script>
+<script>
+	const lock = UniversalLock.lockFactory(UniversalLockLocalStorage.createBackend());
+</script>
+```
+
+## API
+
+### `createBackend(prefix?)`
+
+Creates a localStorage backend instance.
+
+```typescript
+import { createBackend } from "@universal-lock/local-storage";
+
+const backend = createBackend(); // default prefix "universal-lock:"
+const backend = createBackend("my-app:"); // custom prefix
+```
+
+| Parameter | Type     | Default             | Description                       |
+| --------- | -------- | ------------------- | --------------------------------- |
+| `prefix`  | `string` | `"universal-lock:"` | Prefix for localStorage key names |
+
+## How It Works
+
+Locks are stored as JSON in `localStorage` with a timestamp. A compare-and-swap (CAS) pattern is used: after writing a lock entry, it is immediately read back to verify the write succeeded. This significantly reduces race conditions between tabs.
+
+## When to Use
+
+- Cross-tab locking in browsers that **don't** support the Web Locks API
+- Fallback for older browser environments
+
+## Limitations
+
+- `localStorage` is **not** truly atomic. The CAS verification reduces but does not eliminate race conditions. For stronger cross-tab guarantees, use [`@universal-lock/web-locks`](https://www.npmjs.com/package/@universal-lock/web-locks).
+- Throws during `setup` if `localStorage` is unavailable (e.g., private browsing in some browsers, server-side rendering).
+
+## License
+
+[MIT](https://github.com/lucasrainett/universal-lock/blob/master/LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { Backend } from '@universal-lock/types';
+
+declare const createBackend: (prefix?: string) => Backend;
+
+export { createBackend };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { Backend } from '@universal-lock/types';
+
+declare const createBackend: (prefix?: string) => Backend;
+
+export { createBackend };

package/dist/index.global.js

@@ -0,0 +1,81 @@
+"use strict";
+var UniversalLockLocalStorage = (() => {
+  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, {
+    createBackend: () => createBackend
+  });
+  var DEFAULT_PREFIX = "universal-lock:";
+  var createBackend = (prefix = DEFAULT_PREFIX) => {
+    const setup = async () => {
+      if (typeof localStorage === "undefined") {
+        throw new Error("localStorage is not available");
+      }
+    };
+    const read = (lockName) => {
+      const raw = localStorage.getItem(prefix + lockName);
+      if (!raw) return null;
+      return JSON.parse(raw);
+    };
+    const write = (lockName, entry) => {
+      localStorage.setItem(prefix + lockName, JSON.stringify(entry));
+    };
+    const remove = (lockName) => {
+      localStorage.removeItem(prefix + lockName);
+    };
+    const acquire = async (lockName, stale, lockId) => {
+      const now = Date.now();
+      const existing = read(lockName);
+      const lockExpired = existing && existing.timestamp + stale <= now;
+      if (!existing || lockExpired) {
+        write(lockName, { lockId, timestamp: now });
+        const verification = read(lockName);
+        if (!verification || verification.lockId !== lockId) {
+          throw new Error(`${lockName} already locked`);
+        }
+      } else {
+        throw new Error(`${lockName} already locked`);
+      }
+    };
+    const renew = async (lockName, lockId) => {
+      const existing = read(lockName);
+      if (!existing) throw new Error(`${lockName} not locked`);
+      if (existing.lockId !== lockId)
+        throw new Error(`${lockName} not owned by caller`);
+      write(lockName, { lockId, timestamp: Date.now() });
+    };
+    const release = async (lockName, lockId) => {
+      const existing = read(lockName);
+      if (!existing) throw new Error(`${lockName} not locked`);
+      if (existing.lockId !== lockId)
+        throw new Error(`${lockName} not owned by caller`);
+      remove(lockName);
+    };
+    return {
+      setup,
+      acquire,
+      renew,
+      release
+    };
+  };
+  return __toCommonJS(index_exports);
+})();
+//# sourceMappingURL=index.global.js.map

package/dist/index.global.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n\tBackend,\n\tBackendAcquireFunction,\n\tBackendReleaseFunction,\n\tBackendRenewFunction,\n\tBackendSetupFunction,\n\tTimestampLockEntry,\n} from \"@universal-lock/types\";\n\nconst DEFAULT_PREFIX = \"universal-lock:\";\n\nexport const createBackend = (prefix: string = DEFAULT_PREFIX): Backend => {\n\tconst setup: BackendSetupFunction = async () => {\n\t\tif (typeof localStorage === \"undefined\") {\n\t\t\tthrow new Error(\"localStorage is not available\");\n\t\t}\n\t};\n\n\tconst read = (lockName: string): TimestampLockEntry | null => {\n\t\tconst raw = localStorage.getItem(prefix + lockName);\n\t\tif (!raw) return null;\n\t\treturn JSON.parse(raw) as TimestampLockEntry;\n\t};\n\n\tconst write = (lockName: string, entry: TimestampLockEntry): void => {\n\t\tlocalStorage.setItem(prefix + lockName, JSON.stringify(entry));\n\t};\n\n\tconst remove = (lockName: string): void => {\n\t\tlocalStorage.removeItem(prefix + lockName);\n\t};\n\n\t/**\n\t * Acquires a lock using a compare-and-swap pattern.\n\t * Note: localStorage does not support true atomic operations.\n\t * The CAS verification significantly reduces the race window but\n\t * cannot eliminate it entirely. For stronger cross-tab guarantees,\n\t * use the Web Locks API backend instead.\n\t */\n\tconst acquire: BackendAcquireFunction = async (lockName, stale, lockId) => {\n\t\tconst now = Date.now();\n\t\tconst existing = read(lockName);\n\t\tconst lockExpired = existing && existing.timestamp + stale <= now;\n\t\tif (!existing || lockExpired) {\n\t\t\twrite(lockName, { lockId, timestamp: now });\n\t\t\t// Read-back verification: if another tab wrote between our write and read,\n\t\t\t// we'll see their lockId here and know we lost the race\n\t\t\tconst verification = read(lockName);\n\t\t\tif (!verification || verification.lockId !== lockId) {\n\t\t\t\tthrow new Error(`${lockName} already locked`);\n\t\t\t}\n\t\t} else {\n\t\t\tthrow new Error(`${lockName} already locked`);\n\t\t}\n\t};\n\n\tconst renew: BackendRenewFunction = async (lockName, lockId) => {\n\t\tconst existing = read(lockName);\n\t\tif (!existing) throw new Error(`${lockName} not locked`);\n\t\tif (existing.lockId !== lockId)\n\t\t\tthrow new Error(`${lockName} not owned by caller`);\n\t\twrite(lockName, { lockId, timestamp: Date.now() });\n\t};\n\n\tconst release: BackendReleaseFunction = async (lockName, lockId) => {\n\t\tconst existing = read(lockName);\n\t\tif (!existing) throw new Error(`${lockName} not locked`);\n\t\tif (existing.lockId !== lockId)\n\t\t\tthrow new Error(`${lockName} not owned by caller`);\n\t\tremove(lockName);\n\t};\n\n\treturn {\n\t\tsetup,\n\t\tacquire,\n\t\trenew,\n\t\trelease,\n\t};\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AASA,MAAM,iBAAiB;AAEhB,MAAM,gBAAgB,CAAC,SAAiB,mBAA4B;AAC1E,UAAM,QAA8B,YAAY;AAC/C,UAAI,OAAO,iBAAiB,aAAa;AACxC,cAAM,IAAI,MAAM,+BAA+B;AAAA,MAChD;AAAA,IACD;AAEA,UAAM,OAAO,CAAC,aAAgD;AAC7D,YAAM,MAAM,aAAa,QAAQ,SAAS,QAAQ;AAClD,UAAI,CAAC,IAAK,QAAO;AACjB,aAAO,KAAK,MAAM,GAAG;AAAA,IACtB;AAEA,UAAM,QAAQ,CAAC,UAAkB,UAAoC;AACpE,mBAAa,QAAQ,SAAS,UAAU,KAAK,UAAU,KAAK,CAAC;AAAA,IAC9D;AAEA,UAAM,SAAS,CAAC,aAA2B;AAC1C,mBAAa,WAAW,SAAS,QAAQ;AAAA,IAC1C;AASA,UAAM,UAAkC,OAAO,UAAU,OAAO,WAAW;AAC1E,YAAM,MAAM,KAAK,IAAI;AACrB,YAAM,WAAW,KAAK,QAAQ;AAC9B,YAAM,cAAc,YAAY,SAAS,YAAY,SAAS;AAC9D,UAAI,CAAC,YAAY,aAAa;AAC7B,cAAM,UAAU,EAAE,QAAQ,WAAW,IAAI,CAAC;AAG1C,cAAM,eAAe,KAAK,QAAQ;AAClC,YAAI,CAAC,gBAAgB,aAAa,WAAW,QAAQ;AACpD,gBAAM,IAAI,MAAM,GAAG,QAAQ,iBAAiB;AAAA,QAC7C;AAAA,MACD,OAAO;AACN,cAAM,IAAI,MAAM,GAAG,QAAQ,iBAAiB;AAAA,MAC7C;AAAA,IACD;AAEA,UAAM,QAA8B,OAAO,UAAU,WAAW;AAC/D,YAAM,WAAW,KAAK,QAAQ;AAC9B,UAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,UAAI,SAAS,WAAW;AACvB,cAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,YAAM,UAAU,EAAE,QAAQ,WAAW,KAAK,IAAI,EAAE,CAAC;AAAA,IAClD;AAEA,UAAM,UAAkC,OAAO,UAAU,WAAW;AACnE,YAAM,WAAW,KAAK,QAAQ;AAC9B,UAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,UAAI,SAAS,WAAW;AACvB,cAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,aAAO,QAAQ;AAAA,IAChB;AAEA,WAAO;AAAA,MACN;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACD;AAAA,EACD;","names":[]}

package/dist/index.js

@@ -0,0 +1,83 @@
+"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, {
+  createBackend: () => createBackend
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_PREFIX = "universal-lock:";
+var createBackend = (prefix = DEFAULT_PREFIX) => {
+  const setup = async () => {
+    if (typeof localStorage === "undefined") {
+      throw new Error("localStorage is not available");
+    }
+  };
+  const read = (lockName) => {
+    const raw = localStorage.getItem(prefix + lockName);
+    if (!raw) return null;
+    return JSON.parse(raw);
+  };
+  const write = (lockName, entry) => {
+    localStorage.setItem(prefix + lockName, JSON.stringify(entry));
+  };
+  const remove = (lockName) => {
+    localStorage.removeItem(prefix + lockName);
+  };
+  const acquire = async (lockName, stale, lockId) => {
+    const now = Date.now();
+    const existing = read(lockName);
+    const lockExpired = existing && existing.timestamp + stale <= now;
+    if (!existing || lockExpired) {
+      write(lockName, { lockId, timestamp: now });
+      const verification = read(lockName);
+      if (!verification || verification.lockId !== lockId) {
+        throw new Error(`${lockName} already locked`);
+      }
+    } else {
+      throw new Error(`${lockName} already locked`);
+    }
+  };
+  const renew = async (lockName, lockId) => {
+    const existing = read(lockName);
+    if (!existing) throw new Error(`${lockName} not locked`);
+    if (existing.lockId !== lockId)
+      throw new Error(`${lockName} not owned by caller`);
+    write(lockName, { lockId, timestamp: Date.now() });
+  };
+  const release = async (lockName, lockId) => {
+    const existing = read(lockName);
+    if (!existing) throw new Error(`${lockName} not locked`);
+    if (existing.lockId !== lockId)
+      throw new Error(`${lockName} not owned by caller`);
+    remove(lockName);
+  };
+  return {
+    setup,
+    acquire,
+    renew,
+    release
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createBackend
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n\tBackend,\n\tBackendAcquireFunction,\n\tBackendReleaseFunction,\n\tBackendRenewFunction,\n\tBackendSetupFunction,\n\tTimestampLockEntry,\n} from \"@universal-lock/types\";\n\nconst DEFAULT_PREFIX = \"universal-lock:\";\n\nexport const createBackend = (prefix: string = DEFAULT_PREFIX): Backend => {\n\tconst setup: BackendSetupFunction = async () => {\n\t\tif (typeof localStorage === \"undefined\") {\n\t\t\tthrow new Error(\"localStorage is not available\");\n\t\t}\n\t};\n\n\tconst read = (lockName: string): TimestampLockEntry | null => {\n\t\tconst raw = localStorage.getItem(prefix + lockName);\n\t\tif (!raw) return null;\n\t\treturn JSON.parse(raw) as TimestampLockEntry;\n\t};\n\n\tconst write = (lockName: string, entry: TimestampLockEntry): void => {\n\t\tlocalStorage.setItem(prefix + lockName, JSON.stringify(entry));\n\t};\n\n\tconst remove = (lockName: string): void => {\n\t\tlocalStorage.removeItem(prefix + lockName);\n\t};\n\n\t/**\n\t * Acquires a lock using a compare-and-swap pattern.\n\t * Note: localStorage does not support true atomic operations.\n\t * The CAS verification significantly reduces the race window but\n\t * cannot eliminate it entirely. For stronger cross-tab guarantees,\n\t * use the Web Locks API backend instead.\n\t */\n\tconst acquire: BackendAcquireFunction = async (lockName, stale, lockId) => {\n\t\tconst now = Date.now();\n\t\tconst existing = read(lockName);\n\t\tconst lockExpired = existing && existing.timestamp + stale <= now;\n\t\tif (!existing || lockExpired) {\n\t\t\twrite(lockName, { lockId, timestamp: now });\n\t\t\t// Read-back verification: if another tab wrote between our write and read,\n\t\t\t// we'll see their lockId here and know we lost the race\n\t\t\tconst verification = read(lockName);\n\t\t\tif (!verification || verification.lockId !== lockId) {\n\t\t\t\tthrow new Error(`${lockName} already locked`);\n\t\t\t}\n\t\t} else {\n\t\t\tthrow new Error(`${lockName} already locked`);\n\t\t}\n\t};\n\n\tconst renew: BackendRenewFunction = async (lockName, lockId) => {\n\t\tconst existing = read(lockName);\n\t\tif (!existing) throw new Error(`${lockName} not locked`);\n\t\tif (existing.lockId !== lockId)\n\t\t\tthrow new Error(`${lockName} not owned by caller`);\n\t\twrite(lockName, { lockId, timestamp: Date.now() });\n\t};\n\n\tconst release: BackendReleaseFunction = async (lockName, lockId) => {\n\t\tconst existing = read(lockName);\n\t\tif (!existing) throw new Error(`${lockName} not locked`);\n\t\tif (existing.lockId !== lockId)\n\t\t\tthrow new Error(`${lockName} not owned by caller`);\n\t\tremove(lockName);\n\t};\n\n\treturn {\n\t\tsetup,\n\t\tacquire,\n\t\trenew,\n\t\trelease,\n\t};\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AASA,IAAM,iBAAiB;AAEhB,IAAM,gBAAgB,CAAC,SAAiB,mBAA4B;AAC1E,QAAM,QAA8B,YAAY;AAC/C,QAAI,OAAO,iBAAiB,aAAa;AACxC,YAAM,IAAI,MAAM,+BAA+B;AAAA,IAChD;AAAA,EACD;AAEA,QAAM,OAAO,CAAC,aAAgD;AAC7D,UAAM,MAAM,aAAa,QAAQ,SAAS,QAAQ;AAClD,QAAI,CAAC,IAAK,QAAO;AACjB,WAAO,KAAK,MAAM,GAAG;AAAA,EACtB;AAEA,QAAM,QAAQ,CAAC,UAAkB,UAAoC;AACpE,iBAAa,QAAQ,SAAS,UAAU,KAAK,UAAU,KAAK,CAAC;AAAA,EAC9D;AAEA,QAAM,SAAS,CAAC,aAA2B;AAC1C,iBAAa,WAAW,SAAS,QAAQ;AAAA,EAC1C;AASA,QAAM,UAAkC,OAAO,UAAU,OAAO,WAAW;AAC1E,UAAM,MAAM,KAAK,IAAI;AACrB,UAAM,WAAW,KAAK,QAAQ;AAC9B,UAAM,cAAc,YAAY,SAAS,YAAY,SAAS;AAC9D,QAAI,CAAC,YAAY,aAAa;AAC7B,YAAM,UAAU,EAAE,QAAQ,WAAW,IAAI,CAAC;AAG1C,YAAM,eAAe,KAAK,QAAQ;AAClC,UAAI,CAAC,gBAAgB,aAAa,WAAW,QAAQ;AACpD,cAAM,IAAI,MAAM,GAAG,QAAQ,iBAAiB;AAAA,MAC7C;AAAA,IACD,OAAO;AACN,YAAM,IAAI,MAAM,GAAG,QAAQ,iBAAiB;AAAA,IAC7C;AAAA,EACD;AAEA,QAAM,QAA8B,OAAO,UAAU,WAAW;AAC/D,UAAM,WAAW,KAAK,QAAQ;AAC9B,QAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,QAAI,SAAS,WAAW;AACvB,YAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,UAAM,UAAU,EAAE,QAAQ,WAAW,KAAK,IAAI,EAAE,CAAC;AAAA,EAClD;AAEA,QAAM,UAAkC,OAAO,UAAU,WAAW;AACnE,UAAM,WAAW,KAAK,QAAQ;AAC9B,QAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,QAAI,SAAS,WAAW;AACvB,YAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,WAAO,QAAQ;AAAA,EAChB;AAEA,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACD;AACD;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,58 @@
+// src/index.ts
+var DEFAULT_PREFIX = "universal-lock:";
+var createBackend = (prefix = DEFAULT_PREFIX) => {
+  const setup = async () => {
+    if (typeof localStorage === "undefined") {
+      throw new Error("localStorage is not available");
+    }
+  };
+  const read = (lockName) => {
+    const raw = localStorage.getItem(prefix + lockName);
+    if (!raw) return null;
+    return JSON.parse(raw);
+  };
+  const write = (lockName, entry) => {
+    localStorage.setItem(prefix + lockName, JSON.stringify(entry));
+  };
+  const remove = (lockName) => {
+    localStorage.removeItem(prefix + lockName);
+  };
+  const acquire = async (lockName, stale, lockId) => {
+    const now = Date.now();
+    const existing = read(lockName);
+    const lockExpired = existing && existing.timestamp + stale <= now;
+    if (!existing || lockExpired) {
+      write(lockName, { lockId, timestamp: now });
+      const verification = read(lockName);
+      if (!verification || verification.lockId !== lockId) {
+        throw new Error(`${lockName} already locked`);
+      }
+    } else {
+      throw new Error(`${lockName} already locked`);
+    }
+  };
+  const renew = async (lockName, lockId) => {
+    const existing = read(lockName);
+    if (!existing) throw new Error(`${lockName} not locked`);
+    if (existing.lockId !== lockId)
+      throw new Error(`${lockName} not owned by caller`);
+    write(lockName, { lockId, timestamp: Date.now() });
+  };
+  const release = async (lockName, lockId) => {
+    const existing = read(lockName);
+    if (!existing) throw new Error(`${lockName} not locked`);
+    if (existing.lockId !== lockId)
+      throw new Error(`${lockName} not owned by caller`);
+    remove(lockName);
+  };
+  return {
+    setup,
+    acquire,
+    renew,
+    release
+  };
+};
+export {
+  createBackend
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n\tBackend,\n\tBackendAcquireFunction,\n\tBackendReleaseFunction,\n\tBackendRenewFunction,\n\tBackendSetupFunction,\n\tTimestampLockEntry,\n} from \"@universal-lock/types\";\n\nconst DEFAULT_PREFIX = \"universal-lock:\";\n\nexport const createBackend = (prefix: string = DEFAULT_PREFIX): Backend => {\n\tconst setup: BackendSetupFunction = async () => {\n\t\tif (typeof localStorage === \"undefined\") {\n\t\t\tthrow new Error(\"localStorage is not available\");\n\t\t}\n\t};\n\n\tconst read = (lockName: string): TimestampLockEntry | null => {\n\t\tconst raw = localStorage.getItem(prefix + lockName);\n\t\tif (!raw) return null;\n\t\treturn JSON.parse(raw) as TimestampLockEntry;\n\t};\n\n\tconst write = (lockName: string, entry: TimestampLockEntry): void => {\n\t\tlocalStorage.setItem(prefix + lockName, JSON.stringify(entry));\n\t};\n\n\tconst remove = (lockName: string): void => {\n\t\tlocalStorage.removeItem(prefix + lockName);\n\t};\n\n\t/**\n\t * Acquires a lock using a compare-and-swap pattern.\n\t * Note: localStorage does not support true atomic operations.\n\t * The CAS verification significantly reduces the race window but\n\t * cannot eliminate it entirely. For stronger cross-tab guarantees,\n\t * use the Web Locks API backend instead.\n\t */\n\tconst acquire: BackendAcquireFunction = async (lockName, stale, lockId) => {\n\t\tconst now = Date.now();\n\t\tconst existing = read(lockName);\n\t\tconst lockExpired = existing && existing.timestamp + stale <= now;\n\t\tif (!existing || lockExpired) {\n\t\t\twrite(lockName, { lockId, timestamp: now });\n\t\t\t// Read-back verification: if another tab wrote between our write and read,\n\t\t\t// we'll see their lockId here and know we lost the race\n\t\t\tconst verification = read(lockName);\n\t\t\tif (!verification || verification.lockId !== lockId) {\n\t\t\t\tthrow new Error(`${lockName} already locked`);\n\t\t\t}\n\t\t} else {\n\t\t\tthrow new Error(`${lockName} already locked`);\n\t\t}\n\t};\n\n\tconst renew: BackendRenewFunction = async (lockName, lockId) => {\n\t\tconst existing = read(lockName);\n\t\tif (!existing) throw new Error(`${lockName} not locked`);\n\t\tif (existing.lockId !== lockId)\n\t\t\tthrow new Error(`${lockName} not owned by caller`);\n\t\twrite(lockName, { lockId, timestamp: Date.now() });\n\t};\n\n\tconst release: BackendReleaseFunction = async (lockName, lockId) => {\n\t\tconst existing = read(lockName);\n\t\tif (!existing) throw new Error(`${lockName} not locked`);\n\t\tif (existing.lockId !== lockId)\n\t\t\tthrow new Error(`${lockName} not owned by caller`);\n\t\tremove(lockName);\n\t};\n\n\treturn {\n\t\tsetup,\n\t\tacquire,\n\t\trenew,\n\t\trelease,\n\t};\n};\n"],"mappings":";AASA,IAAM,iBAAiB;AAEhB,IAAM,gBAAgB,CAAC,SAAiB,mBAA4B;AAC1E,QAAM,QAA8B,YAAY;AAC/C,QAAI,OAAO,iBAAiB,aAAa;AACxC,YAAM,IAAI,MAAM,+BAA+B;AAAA,IAChD;AAAA,EACD;AAEA,QAAM,OAAO,CAAC,aAAgD;AAC7D,UAAM,MAAM,aAAa,QAAQ,SAAS,QAAQ;AAClD,QAAI,CAAC,IAAK,QAAO;AACjB,WAAO,KAAK,MAAM,GAAG;AAAA,EACtB;AAEA,QAAM,QAAQ,CAAC,UAAkB,UAAoC;AACpE,iBAAa,QAAQ,SAAS,UAAU,KAAK,UAAU,KAAK,CAAC;AAAA,EAC9D;AAEA,QAAM,SAAS,CAAC,aAA2B;AAC1C,iBAAa,WAAW,SAAS,QAAQ;AAAA,EAC1C;AASA,QAAM,UAAkC,OAAO,UAAU,OAAO,WAAW;AAC1E,UAAM,MAAM,KAAK,IAAI;AACrB,UAAM,WAAW,KAAK,QAAQ;AAC9B,UAAM,cAAc,YAAY,SAAS,YAAY,SAAS;AAC9D,QAAI,CAAC,YAAY,aAAa;AAC7B,YAAM,UAAU,EAAE,QAAQ,WAAW,IAAI,CAAC;AAG1C,YAAM,eAAe,KAAK,QAAQ;AAClC,UAAI,CAAC,gBAAgB,aAAa,WAAW,QAAQ;AACpD,cAAM,IAAI,MAAM,GAAG,QAAQ,iBAAiB;AAAA,MAC7C;AAAA,IACD,OAAO;AACN,YAAM,IAAI,MAAM,GAAG,QAAQ,iBAAiB;AAAA,IAC7C;AAAA,EACD;AAEA,QAAM,QAA8B,OAAO,UAAU,WAAW;AAC/D,UAAM,WAAW,KAAK,QAAQ;AAC9B,QAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,QAAI,SAAS,WAAW;AACvB,YAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,UAAM,UAAU,EAAE,QAAQ,WAAW,KAAK,IAAI,EAAE,CAAC;AAAA,EAClD;AAEA,QAAM,UAAkC,OAAO,UAAU,WAAW;AACnE,UAAM,WAAW,KAAK,QAAQ;AAC9B,QAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,QAAI,SAAS,WAAW;AACvB,YAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,WAAO,QAAQ;AAAA,EAChB;AAEA,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACD;AACD;","names":[]}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@universal-lock/local-storage",
+  "version": "1.0.0",
+  "description": "LocalStorage backend for universal-lock",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "browser": "dist/index.global.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "/dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lucasrainett/universal-lock",
+    "directory": "packages/local-storage"
+  },
+  "keywords": [
+    "universal-lock",
+    "lock",
+    "mutex",
+    "localstorage",
+    "browser",
+    "backend"
+  ],
+  "author": {
+    "name": "Lucas Rainett",
+    "email": "lucas@rainett.dev",
+    "url": "https://github.com/lucasrainett"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@universal-lock/types": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist"
+  }
+}