@universal-lock/memory 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,72 @@
+# @universal-lock/memory
+
+In-memory backend for [`universal-lock`](https://github.com/lucasrainett/universal-lock). Stores locks in a plain JavaScript object using timestamps for stale detection.
+
+## Installation
+
+```bash
+npm install universal-lock @universal-lock/memory
+```
+
+## Usage
+
+### 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
+
+### `createBackend()`
+
+Creates an in-memory backend instance. No arguments required.
+
+```typescript
+import { createBackend } from "@universal-lock/memory";
+
+const backend = createBackend();
+```
+
+## When to Use
+
+- Development and testing
+- Single-process Node.js applications
+- Prototyping before switching to a distributed backend
+
+## Limitations
+
+- Locks are **not** shared across processes or servers. For distributed locking, use [`@universal-lock/redis`](https://www.npmjs.com/package/@universal-lock/redis).
+
+## License
+
+[MIT](https://github.com/lucasrainett/universal-lock/blob/master/LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { BackendFactory } from '@universal-lock/types';
+
+declare const createBackend: BackendFactory;
+
+export { createBackend };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { BackendFactory } from '@universal-lock/types';
+
+declare const createBackend: BackendFactory;
+
+export { createBackend };

package/dist/index.global.js

@@ -0,0 +1,63 @@
+"use strict";
+var UniversalLockMemory = (() => {
+  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 createBackend = () => {
+    const locks = {};
+    const setup = async () => {
+    };
+    const acquire = async (lockName, stale, lockId) => {
+      const now = Date.now();
+      const existing = locks[lockName];
+      const lockExpired = existing && existing.timestamp + stale <= now;
+      if (!existing || lockExpired) {
+        locks[lockName] = { lockId, timestamp: now };
+      } else {
+        throw new Error(`${lockName} already locked`);
+      }
+    };
+    const renew = async (lockName, lockId) => {
+      const existing = locks[lockName];
+      if (!existing) throw new Error(`${lockName} not locked`);
+      if (existing.lockId !== lockId)
+        throw new Error(`${lockName} not owned by caller`);
+      existing.timestamp = Date.now();
+    };
+    const release = async (lockName, lockId) => {
+      const existing = locks[lockName];
+      if (!existing) throw new Error(`${lockName} not locked`);
+      if (existing.lockId !== lockId)
+        throw new Error(`${lockName} not owned by caller`);
+      delete locks[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\tBackendFactory,\n\tBackendReleaseFunction,\n\tBackendRenewFunction,\n\tBackendSetupFunction,\n\tTimestampLockEntry,\n} from \"@universal-lock/types\";\n\nexport const createBackend: BackendFactory = (): Backend => {\n\tconst locks: Record<string, TimestampLockEntry> = {};\n\n\tconst setup: BackendSetupFunction = async () => {};\n\n\tconst acquire: BackendAcquireFunction = async (lockName, stale, lockId) => {\n\t\tconst now = Date.now();\n\t\tconst existing = locks[lockName];\n\t\t// A lock is considered expired if its timestamp + stale duration has passed,\n\t\t// allowing takeover of locks from crashed processes that never released\n\t\tconst lockExpired = existing && existing.timestamp + stale <= now;\n\t\tif (!existing || lockExpired) {\n\t\t\tlocks[lockName] = { lockId, timestamp: now };\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 = locks[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\texisting.timestamp = Date.now();\n\t};\n\n\tconst release: BackendReleaseFunction = async (lockName, lockId) => {\n\t\tconst existing = locks[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\tdelete locks[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;AAUO,MAAM,gBAAgC,MAAe;AAC3D,UAAM,QAA4C,CAAC;AAEnD,UAAM,QAA8B,YAAY;AAAA,IAAC;AAEjD,UAAM,UAAkC,OAAO,UAAU,OAAO,WAAW;AAC1E,YAAM,MAAM,KAAK,IAAI;AACrB,YAAM,WAAW,MAAM,QAAQ;AAG/B,YAAM,cAAc,YAAY,SAAS,YAAY,SAAS;AAC9D,UAAI,CAAC,YAAY,aAAa;AAC7B,cAAM,QAAQ,IAAI,EAAE,QAAQ,WAAW,IAAI;AAAA,MAC5C,OAAO;AACN,cAAM,IAAI,MAAM,GAAG,QAAQ,iBAAiB;AAAA,MAC7C;AAAA,IACD;AAEA,UAAM,QAA8B,OAAO,UAAU,WAAW;AAC/D,YAAM,WAAW,MAAM,QAAQ;AAC/B,UAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,UAAI,SAAS,WAAW;AACvB,cAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,eAAS,YAAY,KAAK,IAAI;AAAA,IAC/B;AAEA,UAAM,UAAkC,OAAO,UAAU,WAAW;AACnE,YAAM,WAAW,MAAM,QAAQ;AAC/B,UAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,UAAI,SAAS,WAAW;AACvB,cAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,aAAO,MAAM,QAAQ;AAAA,IACtB;AAEA,WAAO;AAAA,MACN;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACD;AAAA,EACD;","names":[]}

package/dist/index.js

@@ -0,0 +1,65 @@
+"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 createBackend = () => {
+  const locks = {};
+  const setup = async () => {
+  };
+  const acquire = async (lockName, stale, lockId) => {
+    const now = Date.now();
+    const existing = locks[lockName];
+    const lockExpired = existing && existing.timestamp + stale <= now;
+    if (!existing || lockExpired) {
+      locks[lockName] = { lockId, timestamp: now };
+    } else {
+      throw new Error(`${lockName} already locked`);
+    }
+  };
+  const renew = async (lockName, lockId) => {
+    const existing = locks[lockName];
+    if (!existing) throw new Error(`${lockName} not locked`);
+    if (existing.lockId !== lockId)
+      throw new Error(`${lockName} not owned by caller`);
+    existing.timestamp = Date.now();
+  };
+  const release = async (lockName, lockId) => {
+    const existing = locks[lockName];
+    if (!existing) throw new Error(`${lockName} not locked`);
+    if (existing.lockId !== lockId)
+      throw new Error(`${lockName} not owned by caller`);
+    delete locks[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\tBackendFactory,\n\tBackendReleaseFunction,\n\tBackendRenewFunction,\n\tBackendSetupFunction,\n\tTimestampLockEntry,\n} from \"@universal-lock/types\";\n\nexport const createBackend: BackendFactory = (): Backend => {\n\tconst locks: Record<string, TimestampLockEntry> = {};\n\n\tconst setup: BackendSetupFunction = async () => {};\n\n\tconst acquire: BackendAcquireFunction = async (lockName, stale, lockId) => {\n\t\tconst now = Date.now();\n\t\tconst existing = locks[lockName];\n\t\t// A lock is considered expired if its timestamp + stale duration has passed,\n\t\t// allowing takeover of locks from crashed processes that never released\n\t\tconst lockExpired = existing && existing.timestamp + stale <= now;\n\t\tif (!existing || lockExpired) {\n\t\t\tlocks[lockName] = { lockId, timestamp: now };\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 = locks[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\texisting.timestamp = Date.now();\n\t};\n\n\tconst release: BackendReleaseFunction = async (lockName, lockId) => {\n\t\tconst existing = locks[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\tdelete locks[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;AAUO,IAAM,gBAAgC,MAAe;AAC3D,QAAM,QAA4C,CAAC;AAEnD,QAAM,QAA8B,YAAY;AAAA,EAAC;AAEjD,QAAM,UAAkC,OAAO,UAAU,OAAO,WAAW;AAC1E,UAAM,MAAM,KAAK,IAAI;AACrB,UAAM,WAAW,MAAM,QAAQ;AAG/B,UAAM,cAAc,YAAY,SAAS,YAAY,SAAS;AAC9D,QAAI,CAAC,YAAY,aAAa;AAC7B,YAAM,QAAQ,IAAI,EAAE,QAAQ,WAAW,IAAI;AAAA,IAC5C,OAAO;AACN,YAAM,IAAI,MAAM,GAAG,QAAQ,iBAAiB;AAAA,IAC7C;AAAA,EACD;AAEA,QAAM,QAA8B,OAAO,UAAU,WAAW;AAC/D,UAAM,WAAW,MAAM,QAAQ;AAC/B,QAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,QAAI,SAAS,WAAW;AACvB,YAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,aAAS,YAAY,KAAK,IAAI;AAAA,EAC/B;AAEA,QAAM,UAAkC,OAAO,UAAU,WAAW;AACnE,UAAM,WAAW,MAAM,QAAQ;AAC/B,QAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,QAAI,SAAS,WAAW;AACvB,YAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,WAAO,MAAM,QAAQ;AAAA,EACtB;AAEA,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACD;AACD;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,40 @@
+// src/index.ts
+var createBackend = () => {
+  const locks = {};
+  const setup = async () => {
+  };
+  const acquire = async (lockName, stale, lockId) => {
+    const now = Date.now();
+    const existing = locks[lockName];
+    const lockExpired = existing && existing.timestamp + stale <= now;
+    if (!existing || lockExpired) {
+      locks[lockName] = { lockId, timestamp: now };
+    } else {
+      throw new Error(`${lockName} already locked`);
+    }
+  };
+  const renew = async (lockName, lockId) => {
+    const existing = locks[lockName];
+    if (!existing) throw new Error(`${lockName} not locked`);
+    if (existing.lockId !== lockId)
+      throw new Error(`${lockName} not owned by caller`);
+    existing.timestamp = Date.now();
+  };
+  const release = async (lockName, lockId) => {
+    const existing = locks[lockName];
+    if (!existing) throw new Error(`${lockName} not locked`);
+    if (existing.lockId !== lockId)
+      throw new Error(`${lockName} not owned by caller`);
+    delete locks[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\tBackendFactory,\n\tBackendReleaseFunction,\n\tBackendRenewFunction,\n\tBackendSetupFunction,\n\tTimestampLockEntry,\n} from \"@universal-lock/types\";\n\nexport const createBackend: BackendFactory = (): Backend => {\n\tconst locks: Record<string, TimestampLockEntry> = {};\n\n\tconst setup: BackendSetupFunction = async () => {};\n\n\tconst acquire: BackendAcquireFunction = async (lockName, stale, lockId) => {\n\t\tconst now = Date.now();\n\t\tconst existing = locks[lockName];\n\t\t// A lock is considered expired if its timestamp + stale duration has passed,\n\t\t// allowing takeover of locks from crashed processes that never released\n\t\tconst lockExpired = existing && existing.timestamp + stale <= now;\n\t\tif (!existing || lockExpired) {\n\t\t\tlocks[lockName] = { lockId, timestamp: now };\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 = locks[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\texisting.timestamp = Date.now();\n\t};\n\n\tconst release: BackendReleaseFunction = async (lockName, lockId) => {\n\t\tconst existing = locks[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\tdelete locks[lockName];\n\t};\n\n\treturn {\n\t\tsetup,\n\t\tacquire,\n\t\trenew,\n\t\trelease,\n\t};\n};\n"],"mappings":";AAUO,IAAM,gBAAgC,MAAe;AAC3D,QAAM,QAA4C,CAAC;AAEnD,QAAM,QAA8B,YAAY;AAAA,EAAC;AAEjD,QAAM,UAAkC,OAAO,UAAU,OAAO,WAAW;AAC1E,UAAM,MAAM,KAAK,IAAI;AACrB,UAAM,WAAW,MAAM,QAAQ;AAG/B,UAAM,cAAc,YAAY,SAAS,YAAY,SAAS;AAC9D,QAAI,CAAC,YAAY,aAAa;AAC7B,YAAM,QAAQ,IAAI,EAAE,QAAQ,WAAW,IAAI;AAAA,IAC5C,OAAO;AACN,YAAM,IAAI,MAAM,GAAG,QAAQ,iBAAiB;AAAA,IAC7C;AAAA,EACD;AAEA,QAAM,QAA8B,OAAO,UAAU,WAAW;AAC/D,UAAM,WAAW,MAAM,QAAQ;AAC/B,QAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,QAAI,SAAS,WAAW;AACvB,YAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,aAAS,YAAY,KAAK,IAAI;AAAA,EAC/B;AAEA,QAAM,UAAkC,OAAO,UAAU,WAAW;AACnE,UAAM,WAAW,MAAM,QAAQ;AAC/B,QAAI,CAAC,SAAU,OAAM,IAAI,MAAM,GAAG,QAAQ,aAAa;AACvD,QAAI,SAAS,WAAW;AACvB,YAAM,IAAI,MAAM,GAAG,QAAQ,sBAAsB;AAClD,WAAO,MAAM,QAAQ;AAAA,EACtB;AAEA,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACD;AACD;","names":[]}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@universal-lock/memory",
+  "version": "1.0.0",
+  "description": "In-memory backend for universal-lock",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16"
+  },
+  "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/memory"
+  },
+  "keywords": [
+    "universal-lock",
+    "lock",
+    "mutex",
+    "memory",
+    "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"
+  }
+}