loqkit 0.0.0-stage → 0.0.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# loqkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Small typed locking primitives for JavaScript runtimes.
+
+```ts
+import { withLock } from "loqkit";
+
+await withLock(
+  { resource: "cache" },
+  async ({ resource, lock }) => {
+    console.log(`locked ${resource} with ${lock.type}`);
+  },
+  async ({ resource }) => resource === "cache",
+  { key: "cache-refresh" },
+);
+```
+
+The optional predicate runs once before waiting and again after acquisition. The action runs only when both checks pass.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "loqkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Small typed locking primitives for JavaScript runtimes.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./release/index.d.ts",
+      "import": "./release/index.js"
+    }
+  },
+  "types": "./release/index.d.ts",
+  "files": [
+    "release",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "bun run typecheck && bun test && bun run build",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "lock",
+    "mutex",
+    "concurrency",
+    "typescript"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "async-mutex": "^0.5.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/release/index.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export declare const lockOptionsSchema: z.ZodObject<{
+    key: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type LockOptions = z.input<typeof lockOptionsSchema>;
+export type LockState = "checking" | "acquired";
+export interface LockInfo {
+    readonly key: string;
+    readonly name: string;
+    readonly type: "memory";
+    readonly state: LockState;
+}
+export type LockContext<TContext extends object> = Readonly<Omit<TContext, "lock"> & {
+    readonly lock: Readonly<LockInfo>;
+}>;
+export type LockAction<TContext extends object, TResult> = (context: LockContext<TContext>) => TResult | PromiseLike<TResult>;
+export type LockPredicate<TContext extends object> = (context: LockContext<TContext>) => boolean | PromiseLike<boolean>;
+export type LockRunResult<TResult> = {
+    readonly executed: true;
+    readonly value: TResult;
+} | {
+    readonly executed: false;
+    readonly reason: "predicate-before" | "predicate-after";
+};
+/** Runs an action exclusively. A predicate is checked before and after acquisition. */
+export declare function withLock<TContext extends object, TResult>(context: TContext, action: LockAction<TContext, TResult>, predicate?: LockPredicate<TContext>, suppliedOptions?: LockOptions): Promise<LockRunResult<TResult>>;

package/release/index.js

@@ -0,0 +1,47 @@
+import { Mutex } from "async-mutex";
+import { z } from "zod";
+export const lockOptionsSchema = z
+    .object({
+    key: z.string().trim().min(1).optional(),
+    name: z.string().trim().min(1).optional(),
+})
+    .strict();
+const mutexes = new Map();
+function contextWithLock(context, lock) {
+    return Object.freeze({ ...context, lock });
+}
+function defaultKey(context) {
+    return JSON.stringify(context);
+}
+/** Runs an action exclusively. A predicate is checked before and after acquisition. */
+export async function withLock(context, action, predicate, suppliedOptions) {
+    const options = lockOptionsSchema.parse(suppliedOptions);
+    const key = options.key ?? defaultKey(context);
+    const name = options.name ?? key;
+    const checking = contextWithLock(context, {
+        key,
+        name,
+        type: "memory",
+        state: "checking",
+    });
+    if (predicate && !(await predicate(checking))) {
+        return { executed: false, reason: "predicate-before" };
+    }
+    let mutex = mutexes.get(key);
+    if (!mutex) {
+        mutex = new Mutex();
+        mutexes.set(key, mutex);
+    }
+    return mutex.runExclusive(async () => {
+        const acquired = contextWithLock(context, {
+            key,
+            name,
+            type: "memory",
+            state: "acquired",
+        });
+        if (predicate && !(await predicate(acquired))) {
+            return { executed: false, reason: "predicate-after" };
+        }
+        return { executed: true, value: await action(acquired) };
+    });
+}