@justscale/core 0.1.0

package/dist/features/lock/lock-service.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Distributed lock service with pluggable backend (Redis, Postgres, in-memory, etc.)
+ */
+import { Logger } from '../../core/index.js';
+import type { LockProvider, LockService } from './types.js';
+declare const AbstractLockProvider_base: import("../../core/service.js").AbstractClass<LockProvider>;
+export declare abstract class AbstractLockProvider extends AbstractLockProvider_base {
+}
+/**
+ * Run a function with lock tracking enabled.
+ * Any locks acquired inside will be tracked and checked for double-lock.
+ */
+export declare function runWithLockTracking<T>(fn: () => T): T;
+/**
+ * Get the set of currently held lock keys in this async context.
+ * Returns undefined if lock tracking is not active.
+ */
+export declare function getHeldLocks(): ReadonlySet<string> | undefined;
+/**
+ * Internal: register that a lock key was acquired in this async context.
+ * Used by Repository.lock() implementations to participate in
+ * `runWithLockTracking` re-entry detection. No-op outside a tracking
+ * context. Not part of the public API.
+ *
+ * @internal
+ */
+export declare function _registerHeldLock(key: string): void;
+/**
+ * Internal: clear a held-lock entry on release. Mirror of
+ * `_registerHeldLock`. No-op outside a tracking context.
+ *
+ * @internal
+ */
+export declare function _unregisterHeldLock(key: string): void;
+export declare class LockAcquisitionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when code tries to acquire a lock already held in the same async context.
+ */
+export declare class DoubleLockError extends Error {
+    readonly lockKey: string;
+    constructor(key: string);
+}
+/**
+ * Thrown when a mutator (`Repository.update`, `delete`, `save`) is called
+ * with a `Lock<T>` whose `__active` is false — i.e. the lock has already
+ * been released via `Symbol.dispose` / `Symbol.asyncDispose`.
+ *
+ * This is the use-after-dispose guard: storing a `Locked<T>` in an outer
+ * scope and using it after the `using` block exits is a footgun the
+ * type system doesn't catch (the `__active` field can't be narrowed
+ * statically), so it surfaces at runtime here.
+ */
+export declare class LockReleasedError extends Error {
+    readonly lockKey: string | undefined;
+    constructor(key?: string);
+}
+/**
+ * Thrown when a lock key is empty or whitespace-only. Empty keys would
+ * collide every locked resource into one global bucket, so they are
+ * rejected at the API boundary.
+ */
+export declare class InvalidLockKeyError extends Error {
+    constructor(key: string);
+}
+declare const LockServiceDef_base: import("../../core/service.js").Service<LockService<unknown>, {
+    readonly provider: typeof AbstractLockProvider;
+    readonly logger: typeof Logger;
+}>;
+export declare class LockServiceDef extends LockServiceDef_base {
+}
+export {};
+//# sourceMappingURL=lock-service.d.ts.map

package/dist/features/lock/lock-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-service.d.ts","sourceRoot":"","sources":["../../../src/features/lock/lock-service.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAiC,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAIV,YAAY,EACZ,WAAW,EACZ,MAAM,YAAY,CAAC;;AAKpB,8BAAsB,oBAAqB,SAAQ,yBAAoD;CAAG;AAe1G;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAErD;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAErD;AAsHD,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBACb,GAAG,EAAE,MAAM;CAKxB;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;gBACzB,GAAG,CAAC,EAAE,MAAM;CASzB;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,GAAG,EAAE,MAAM;CAQxB;;;;;AAED,qBAAa,cAAe,SAAQ,mBAOlC;CAAG"}

package/dist/features/lock/lock-service.js

@@ -0,0 +1,210 @@
+/**
+ * Distributed lock service with pluggable backend (Redis, Postgres, in-memory, etc.)
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { defineAbstract, defineService, Logger } from '../../core/index.js';
+const DEFAULT_TTL = 30_000;
+const DEFAULT_TIMEOUT = 5_000;
+export class AbstractLockProvider extends defineAbstract('AbstractLockProvider') {
+}
+function generateInstanceId() {
+    return `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+function deriveLockKey(obj) {
+    const typeName = obj?.constructor?.name ?? 'Object';
+    const id = obj?.id ?? 'unknown';
+    return `lock:${typeName}:${String(id)}`;
+}
+const heldLocks = new AsyncLocalStorage();
+/**
+ * Run a function with lock tracking enabled.
+ * Any locks acquired inside will be tracked and checked for double-lock.
+ */
+export function runWithLockTracking(fn) {
+    return heldLocks.run(new Set(), fn);
+}
+/**
+ * Get the set of currently held lock keys in this async context.
+ * Returns undefined if lock tracking is not active.
+ */
+export function getHeldLocks() {
+    return heldLocks.getStore();
+}
+/**
+ * Internal: register that a lock key was acquired in this async context.
+ * Used by Repository.lock() implementations to participate in
+ * `runWithLockTracking` re-entry detection. No-op outside a tracking
+ * context. Not part of the public API.
+ *
+ * @internal
+ */
+export function _registerHeldLock(key) {
+    heldLocks.getStore()?.add(key);
+}
+/**
+ * Internal: clear a held-lock entry on release. Mirror of
+ * `_registerHeldLock`. No-op outside a tracking context.
+ *
+ * @internal
+ */
+export function _unregisterHeldLock(key) {
+    heldLocks.getStore()?.delete(key);
+}
+class LockServiceImpl {
+    provider;
+    logger;
+    instanceId = generateInstanceId();
+    constructor(provider, logger) {
+        this.provider = provider;
+        this.logger = logger;
+    }
+    async acquire(objOrPromise, options) {
+        // Await if promise
+        const obj = await objOrPromise;
+        // Handle null case
+        if (obj === null) {
+            return null;
+        }
+        const ttl = options?.ttl ?? DEFAULT_TTL;
+        const opts = {
+            ttl,
+            timeout: options?.timeout ?? DEFAULT_TIMEOUT,
+            key: options?.key ?? deriveLockKey(obj),
+            heartbeat: options?.heartbeat ?? false,
+            heartbeatInterval: options?.heartbeatInterval ?? Math.floor(ttl / 3),
+        };
+        if (opts.key.trim() === '') {
+            throw new InvalidLockKeyError(opts.key);
+        }
+        // Double-lock detection: throw if this key is already held in this async context
+        const held = heldLocks.getStore();
+        if (held?.has(opts.key)) {
+            throw new DoubleLockError(opts.key);
+        }
+        const metadata = await this.provider.acquire(opts.key, opts, this.instanceId);
+        // Track the held lock
+        held?.add(opts.key);
+        this.logger.debug('Lock acquired', {
+            key: opts.key,
+            instanceId: this.instanceId,
+            ttl: opts.ttl,
+        });
+        return this.createLockedObject(obj, metadata, opts.key);
+    }
+    createLockedObject(obj, metadata, key) {
+        const provider = this.provider;
+        const instanceId = this.instanceId;
+        const logger = this.logger;
+        let active = true;
+        const locked = Object.create(obj, {
+            __lock: {
+                value: metadata,
+                writable: false,
+                enumerable: false,
+                configurable: false,
+            },
+            __active: {
+                get: () => active,
+                enumerable: false,
+                configurable: false,
+            },
+            [Symbol.dispose]: {
+                value: function () {
+                    if (!active)
+                        return;
+                    active = false;
+                    heldLocks.getStore()?.delete(key);
+                    provider.release(key, instanceId).catch((err) => {
+                        logger.warn('Lock release failed, will expire via TTL', {
+                            key,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    });
+                },
+                writable: false,
+                enumerable: false,
+                configurable: false,
+            },
+            [Symbol.asyncDispose]: {
+                value: async function () {
+                    if (!active)
+                        return;
+                    active = false;
+                    heldLocks.getStore()?.delete(key);
+                    try {
+                        await provider.release(key, instanceId);
+                    }
+                    catch (err) {
+                        logger.warn('Lock release failed, will expire via TTL', {
+                            key,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                },
+                writable: false,
+                enumerable: false,
+                configurable: false,
+            },
+        });
+        return locked;
+    }
+}
+export class LockAcquisitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LockAcquisitionError';
+    }
+}
+/**
+ * Thrown when code tries to acquire a lock already held in the same async context.
+ */
+export class DoubleLockError extends Error {
+    lockKey;
+    constructor(key) {
+        super(`Cannot acquire lock "${key}" - already held in this async context. Release the existing lock before acquiring a new one.`);
+        this.name = 'DoubleLockError';
+        this.lockKey = key;
+    }
+}
+/**
+ * Thrown when a mutator (`Repository.update`, `delete`, `save`) is called
+ * with a `Lock<T>` whose `__active` is false — i.e. the lock has already
+ * been released via `Symbol.dispose` / `Symbol.asyncDispose`.
+ *
+ * This is the use-after-dispose guard: storing a `Locked<T>` in an outer
+ * scope and using it after the `using` block exits is a footgun the
+ * type system doesn't catch (the `__active` field can't be narrowed
+ * statically), so it surfaces at runtime here.
+ */
+export class LockReleasedError extends Error {
+    lockKey;
+    constructor(key) {
+        super(key
+            ? `Lock "${key}" was used after release. Acquire a fresh lock before mutating.`
+            : 'Lock was used after release. Acquire a fresh lock before mutating.');
+        this.name = 'LockReleasedError';
+        this.lockKey = key;
+    }
+}
+/**
+ * Thrown when a lock key is empty or whitespace-only. Empty keys would
+ * collide every locked resource into one global bucket, so they are
+ * rejected at the API boundary.
+ */
+export class InvalidLockKeyError extends Error {
+    constructor(key) {
+        super(`Lock key must be a non-empty string; received ${JSON.stringify(key)}. ` +
+            'Empty keys would collide every locked resource into one bucket. ' +
+            'Omit \'key\' to derive it from the locked object, or pass a meaningful identifier.');
+        this.name = 'InvalidLockKeyError';
+    }
+}
+export class LockServiceDef extends defineService({
+    inject: {
+        provider: AbstractLockProvider,
+        logger: Logger,
+    },
+    factory: ({ provider, logger }) => new LockServiceImpl(provider, logger),
+}) {
+}
+//# sourceMappingURL=lock-service.js.map

package/dist/features/lock/lock-service.js.map

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

package/dist/features/lock/memory.d.ts

@@ -0,0 +1,60 @@
+/**
+ * In-Memory Lock Provider
+ *
+ * A simple Map-based lock provider that works within a single process.
+ * Suitable for:
+ * - Single-instance applications
+ * - Development and testing
+ * - Applications that don't need distributed locking
+ *
+ * For distributed locking across multiple instances, use Redis or Postgres adapters.
+ */
+import type { LockProvider } from './types.js';
+/** Return type for createInMemoryLockProvider */
+export type InMemoryLockProviderInstance = LockProvider & {
+    /** Clear all locks - useful for test cleanup */
+    clear(): void;
+    /** Check if a key is locked - useful for debugging */
+    isLocked(key: string): boolean;
+    /** Get the instance ID that holds a lock */
+    getLockedBy(key: string): string | null;
+    /** Get the number of active locks */
+    readonly size: number;
+};
+/**
+ * Create an in-memory lock provider instance.
+ *
+ * Use this function for testing or when you need a direct instance.
+ * For DI, use `InMemoryLockProvider` service instead.
+ *
+ * @example
+ * ```typescript
+ * // Direct instantiation for testing
+ * const locks = createInMemoryLockProvider()
+ * await locks.acquire('key', options, instanceId)
+ * locks.clear()
+ * ```
+ */
+export declare function createInMemoryLockProvider(): InMemoryLockProviderInstance;
+declare const InMemoryLockProvider_base: import("../../core/service.js").Service<InMemoryLockProviderInstance, {}>;
+/**
+ * In-memory lock provider service for DI.
+ *
+ * @example
+ * ```typescript
+ * import { InMemoryLockProvider } from '@justscale/core';
+ *
+ * // For DI - auto-provides AbstractLockProvider
+ * JustScale()
+ *   .add(InMemoryLockProvider)
+ *   .add(LockServiceDef)
+ *   .build()
+ *
+ * // For testing - use createInMemoryLockProvider() instead
+ * const locks = createInMemoryLockProvider()
+ * ```
+ */
+export declare class InMemoryLockProvider extends InMemoryLockProvider_base {
+}
+export {};
+//# sourceMappingURL=memory.d.ts.map

package/dist/features/lock/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/features/lock/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAA6B,YAAY,EAAE,MAAM,YAAY,CAAC;AAY1E,iDAAiD;AACjD,MAAM,MAAM,4BAA4B,GAAG,YAAY,GAAG;IACxD,gDAAgD;IAChD,KAAK,IAAI,IAAI,CAAA;IACb,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IAC9B,4CAA4C;IAC5C,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACvC,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,IAAI,4BAA4B,CA6KzE;;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oBAAqB,SAAQ,yBAIxC;CAAG"}

package/dist/features/lock/memory.js

@@ -0,0 +1,194 @@
+/**
+ * In-Memory Lock Provider
+ *
+ * A simple Map-based lock provider that works within a single process.
+ * Suitable for:
+ * - Single-instance applications
+ * - Development and testing
+ * - Applications that don't need distributed locking
+ *
+ * For distributed locking across multiple instances, use Redis or Postgres adapters.
+ */
+import { defineService } from '../../core/service.js';
+import { AbstractLockProvider } from './lock-service.js';
+/**
+ * Create an in-memory lock provider instance.
+ *
+ * Use this function for testing or when you need a direct instance.
+ * For DI, use `InMemoryLockProvider` service instead.
+ *
+ * @example
+ * ```typescript
+ * // Direct instantiation for testing
+ * const locks = createInMemoryLockProvider()
+ * await locks.acquire('key', options, instanceId)
+ * locks.clear()
+ * ```
+ */
+export function createInMemoryLockProvider() {
+    const locks = new Map();
+    const waiters = new Map();
+    function waitForRelease(key) {
+        return new Promise((resolve) => {
+            let waitersForKey = waiters.get(key);
+            if (!waitersForKey) {
+                waitersForKey = new Set();
+                waiters.set(key, waitersForKey);
+            }
+            waitersForKey.add({ resolve });
+        });
+    }
+    function notifyWaiters(key) {
+        const waitersForKey = waiters.get(key);
+        if (!waitersForKey || waitersForKey.size === 0)
+            return;
+        // Convert to array and shuffle for randomness
+        const waitersArray = Array.from(waitersForKey);
+        shuffleArray(waitersArray);
+        // Notify all (they'll race)
+        for (const waiter of waitersArray) {
+            waiter.resolve();
+        }
+        // Clear waiters
+        waiters.delete(key);
+    }
+    function shuffleArray(array) {
+        for (let i = array.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [array[i], array[j]] = [array[j], array[i]];
+        }
+    }
+    return {
+        async acquire(key, options, instanceId) {
+            // Keep trying until we get the lock
+            while (true) {
+                const existing = locks.get(key);
+                // Check if lock exists and is still valid
+                if (existing) {
+                    if (existing.metadata.expiresAt >= new Date()) {
+                        // Lock is held - wait for release notification
+                        await waitForRelease(key);
+                        // After being notified, loop and try again (race with other waiters)
+                        continue;
+                    }
+                    // Lock expired, clean it up
+                    clearTimeout(existing.timer);
+                    locks.delete(key);
+                    // Notify waiters that lock is available
+                    notifyWaiters(key);
+                }
+                // Try to acquire the lock (race condition possible with other waiters)
+                // Use synchronous check-and-set to avoid race
+                const nowCheck = locks.get(key);
+                if (nowCheck && nowCheck.metadata.expiresAt >= new Date()) {
+                    // Someone else got it first, wait again
+                    continue;
+                }
+                // Acquire the lock
+                const now = new Date();
+                const metadata = {
+                    lockedAt: now,
+                    expiresAt: new Date(now.getTime() + options.ttl),
+                    lockedBy: instanceId,
+                };
+                // Set up auto-expiration
+                const timer = setTimeout(() => {
+                    const entry = locks.get(key);
+                    if (entry && entry.instanceId === instanceId) {
+                        locks.delete(key);
+                        // Notify waiters on expiration
+                        notifyWaiters(key);
+                    }
+                }, options.ttl);
+                locks.set(key, { metadata, instanceId, timer });
+                return metadata;
+            }
+        },
+        async release(key, instanceId) {
+            const entry = locks.get(key);
+            if (entry && entry.instanceId === instanceId) {
+                clearTimeout(entry.timer);
+                locks.delete(key);
+                // Notify waiters that lock is available
+                notifyWaiters(key);
+            }
+            // Silently ignore if lock doesn't exist or is owned by someone else
+        },
+        async extend(key, instanceId, ttl) {
+            const entry = locks.get(key);
+            if (!entry || entry.instanceId !== instanceId) {
+                return false;
+            }
+            // Clear old timer
+            clearTimeout(entry.timer);
+            // Update expiration
+            const now = new Date();
+            entry.metadata = {
+                ...entry.metadata,
+                expiresAt: new Date(now.getTime() + ttl),
+            };
+            // Set new timer
+            entry.timer = setTimeout(() => {
+                const current = locks.get(key);
+                if (current && current.instanceId === instanceId) {
+                    locks.delete(key);
+                    notifyWaiters(key);
+                }
+            }, ttl);
+            return true;
+        },
+        clear() {
+            // Get keys before clearing for notifying waiters
+            const keys = Array.from(locks.keys());
+            for (const entry of locks.values()) {
+                clearTimeout(entry.timer);
+            }
+            locks.clear();
+            // Notify all waiters
+            for (const key of keys) {
+                notifyWaiters(key);
+            }
+        },
+        async close() {
+            this.clear();
+        },
+        isLocked(key) {
+            const entry = locks.get(key);
+            return entry !== undefined && entry.metadata.expiresAt >= new Date();
+        },
+        getLockedBy(key) {
+            const entry = locks.get(key);
+            if (entry && entry.metadata.expiresAt >= new Date()) {
+                return entry.instanceId;
+            }
+            return null;
+        },
+        get size() {
+            return locks.size;
+        },
+    };
+}
+/**
+ * In-memory lock provider service for DI.
+ *
+ * @example
+ * ```typescript
+ * import { InMemoryLockProvider } from '@justscale/core';
+ *
+ * // For DI - auto-provides AbstractLockProvider
+ * JustScale()
+ *   .add(InMemoryLockProvider)
+ *   .add(LockServiceDef)
+ *   .build()
+ *
+ * // For testing - use createInMemoryLockProvider() instead
+ * const locks = createInMemoryLockProvider()
+ * ```
+ */
+export class InMemoryLockProvider extends defineService({
+    inject: {},
+    provides: [AbstractLockProvider],
+    factory: createInMemoryLockProvider,
+}) {
+}
+//# sourceMappingURL=memory.js.map

package/dist/features/lock/memory.js.map

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