@mantajs/adapter-locking-neon 0.2.0-beta.0

package/dist/adapter.d.ts

@@ -0,0 +1,28 @@
+import type { ILockingPort } from '@mantajs/core';
+type RawSqlFn = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<Array<Record<string, unknown>>>;
+export interface NeonLockingOptions {
+    rawSql?: RawSqlFn;
+}
+export declare class NeonLockingAdapter implements ILockingPort {
+    private _rawSql;
+    private _owners;
+    private _expireTimers;
+    constructor(rawSql: RawSqlFn);
+    execute<T>(keys: string[], job: () => Promise<T>, options?: {
+        timeout?: number;
+    }): Promise<T>;
+    acquire(keys: string | string[], options?: {
+        ownerId?: string;
+        expire?: number;
+    }): Promise<boolean>;
+    release(keys: string | string[], options?: {
+        ownerId?: string;
+    }): Promise<void>;
+    releaseAll(options?: {
+        ownerId?: string;
+    }): Promise<void>;
+    private _unlockKey;
+    _reset(): void;
+}
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAIjD,KAAK,QAAQ,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;AAEhH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,QAAQ,CAAA;CAClB;AAED,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,aAAa,CAAmD;gBAE5D,MAAM,EAAE,QAAQ;IAUtB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAe7F,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAiDnG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB/E,UAAU,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAwBjD,UAAU;IAKxB,MAAM;CAOP"}

package/dist/adapter.js

@@ -0,0 +1,128 @@
+// SPEC-066 — NeonLockingAdapter implements ILockingPort
+// Uses PostgreSQL advisory locks via raw SQL. Advisory locks are session-scoped —
+// in serverless, the connection closes and locks auto-release.
+import { MantaError } from '@mantajs/core';
+import { stringToAdvisoryLockKey } from './hash';
+export class NeonLockingAdapter {
+    _rawSql;
+    _owners = new Map();
+    _expireTimers = new Map();
+    constructor(rawSql) {
+        if (!rawSql) {
+            throw new MantaError('INVALID_STATE', 'NeonLockingAdapter requires a rawSql function from IDatabasePort.getPool()');
+        }
+        this._rawSql = rawSql;
+    }
+    async execute(keys, job, options) {
+        const ownerId = crypto.randomUUID();
+        const acquired = await this.acquire(keys, { ownerId, expire: options?.timeout });
+        if (!acquired) {
+            throw new MantaError('CONFLICT', `Failed to acquire locks for keys: ${keys.join(', ')}`);
+        }
+        try {
+            return await job();
+        }
+        finally {
+            await this.release(keys, { ownerId });
+        }
+    }
+    async acquire(keys, options) {
+        const keyArray = Array.isArray(keys) ? keys : [keys];
+        const ownerId = options?.ownerId ?? crypto.randomUUID();
+        const acquiredKeys = [];
+        // Try to acquire all locks atomically (L-06)
+        for (const key of keyArray) {
+            const lockKey = stringToAdvisoryLockKey(key);
+            const result = await this._rawSql `SELECT pg_try_advisory_lock(${lockKey}::bigint) AS acquired`;
+            const acquired = result[0]?.acquired === true;
+            if (!acquired) {
+                // Rollback: release all previously acquired locks
+                for (const acquiredKey of acquiredKeys) {
+                    const releaseKey = stringToAdvisoryLockKey(acquiredKey);
+                    await this._rawSql `SELECT pg_advisory_unlock(${releaseKey}::bigint)`;
+                }
+                return false;
+            }
+            acquiredKeys.push(key);
+        }
+        // Track ownership
+        if (!this._owners.has(ownerId)) {
+            this._owners.set(ownerId, new Set());
+        }
+        for (const key of keyArray) {
+            this._owners.get(ownerId).add(key);
+        }
+        // Set expire timer if requested
+        if (options?.expire) {
+            for (const key of keyArray) {
+                const timer = setTimeout(async () => {
+                    await this._unlockKey(key);
+                    this._expireTimers.delete(key);
+                    // Remove from owner tracking
+                    for (const [_oid, keySet] of this._owners) {
+                        keySet.delete(key);
+                    }
+                }, options.expire);
+                this._expireTimers.set(key, timer);
+            }
+        }
+        return true;
+    }
+    async release(keys, options) {
+        const keyArray = Array.isArray(keys) ? keys : [keys];
+        for (const key of keyArray) {
+            await this._unlockKey(key);
+            // Clear expire timer
+            const timer = this._expireTimers.get(key);
+            if (timer) {
+                clearTimeout(timer);
+                this._expireTimers.delete(key);
+            }
+            // Remove from owner tracking
+            if (options?.ownerId) {
+                this._owners.get(options.ownerId)?.delete(key);
+            }
+            else {
+                for (const [_oid, keySet] of this._owners) {
+                    keySet.delete(key);
+                }
+            }
+        }
+    }
+    async releaseAll(options) {
+        if (options?.ownerId) {
+            const keys = this._owners.get(options.ownerId);
+            if (keys) {
+                for (const key of keys) {
+                    await this._unlockKey(key);
+                    const timer = this._expireTimers.get(key);
+                    if (timer) {
+                        clearTimeout(timer);
+                        this._expireTimers.delete(key);
+                    }
+                }
+                this._owners.delete(options.ownerId);
+            }
+        }
+        else {
+            await this._rawSql `SELECT pg_advisory_unlock_all()`;
+            for (const timer of this._expireTimers.values()) {
+                clearTimeout(timer);
+            }
+            this._expireTimers.clear();
+            this._owners.clear();
+        }
+    }
+    async _unlockKey(key) {
+        const lockKey = stringToAdvisoryLockKey(key);
+        await this._rawSql `SELECT pg_advisory_unlock(${lockKey}::bigint)`;
+    }
+    _reset() {
+        for (const timer of this._expireTimers.values()) {
+            clearTimeout(timer);
+        }
+        this._expireTimers.clear();
+        this._owners.clear();
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/hash.d.ts

@@ -0,0 +1,2 @@
+export declare function stringToAdvisoryLockKey(key: string): bigint;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAQA,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAW3D"}

package/dist/hash.js

@@ -0,0 +1,19 @@
+// FNV-1a 64-bit hash — converts string key to bigint for pg_advisory_lock()
+// PG advisory locks require a bigint key. We hash the string key to a signed 64-bit integer.
+const FNV_OFFSET_BASIS = 14695981039346656037n;
+const FNV_PRIME = 1099511628211n;
+const MAX_SIGNED_64 = (1n << 63n) - 1n;
+const MOD = 1n << 64n;
+export function stringToAdvisoryLockKey(key) {
+    let hash = FNV_OFFSET_BASIS;
+    for (let i = 0; i < key.length; i++) {
+        hash ^= BigInt(key.charCodeAt(i));
+        hash = (hash * FNV_PRIME) % MOD;
+    }
+    // Convert to signed 64-bit range for PG
+    if (hash > MAX_SIGNED_64) {
+        hash = hash - MOD;
+    }
+    return hash;
+}
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,6FAA6F;AAE7F,MAAM,gBAAgB,GAAG,qBAAqB,CAAA;AAC9C,MAAM,SAAS,GAAG,cAAc,CAAA;AAChC,MAAM,aAAa,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,EAAE,CAAA;AACtC,MAAM,GAAG,GAAG,EAAE,IAAI,GAAG,CAAA;AAErB,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,IAAI,IAAI,GAAG,gBAAgB,CAAA;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,IAAI,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;QACjC,IAAI,GAAG,CAAC,IAAI,GAAG,SAAS,CAAC,GAAG,GAAG,CAAA;IACjC,CAAC;IACD,wCAAwC;IACxC,IAAI,IAAI,GAAG,aAAa,EAAE,CAAC;QACzB,IAAI,GAAG,IAAI,GAAG,GAAG,CAAA;IACnB,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { NeonLockingAdapter } from './adapter';
+export { stringToAdvisoryLockKey } from './hash';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// SPEC-066 — @mantajs/adapter-locking-neon barrel export
+export { NeonLockingAdapter } from './adapter';
+export { stringToAdvisoryLockKey } from './hash';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yDAAyD;AAEzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAA"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@mantajs/adapter-locking-neon",
+  "version": "0.2.0-beta.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "postgres": "^3.4.0"
+  },
+  "peerDependencies": {
+    "@mantajs/core": "0.2.0-beta.0"
+  },
+  "files": [
+    "dist"
+  ]
+}