@zudojs/cache 0.1.0 → 1.0.0

package/dist/lock.js

@@ -1,52 +1,86 @@
 /**
  * @zudojs/cache — Lock Manager
- * Distributed lock manager for preventing concurrent cache operations.
+ *
+ * In-process lock manager with a pluggable `CacheLockStore`, for preventing
+ * concurrent cache operations. The bundled `InMemoryLockStore` holds leases
+ * in a single `Map` in a single process — it is NOT distributed. Pass a
+ * shared store (the exported `defaultLockStore` to share across services in
+ * one process, or a Redis-backed `CacheLockStore` to share across processes)
+ * via `CacheConfig.lockStore` when wider mutual exclusion is required.
+ *
+ * Leases are measured on a monotonic clock and are renewed by a heartbeat
+ * while the critical section runs, so a slow `fn()` does not silently lose
+ * its lock to expiry. If a lease is lost anyway, `withLock` aborts the
+ * signal it passed to `fn` and throws rather than reporting success.
  */
-import { randomBytes, randomUUID } from "node:crypto";
-import { DEFAULT_LOCK_RETRY_ATTEMPTS, DEFAULT_LOCK_RETRY_DELAY_MS, DEFAULT_LOCK_TTL_MS, } from "./constants.js";
+import { randomUUID } from "node:crypto";
+import { DEFAULT_LOCK_RETRY_ATTEMPTS, DEFAULT_LOCK_RETRY_DELAY_MS, DEFAULT_LOCK_TTL_MS, LOCK_HEARTBEAT_DIVISOR, } from "./constants.js";
 import { CacheError, CacheOperation } from "./errors.js";
+import { assertValidTtl, monotonicNow, wallClockFor } from "./utils.js";
 function generateToken() {
-    if (typeof randomUUID === "function") {
-        return randomUUID();
-    }
-    return randomBytes(16).toString("hex");
+    return randomUUID();
+}
+/** Separates the namespace from the lock name in the internal map key. */
+const LOCK_SCOPE_SEPARATOR = "\u0000";
+/**
+ * Composes the scoped lock name. Two callers holding the same lock name
+ * under different namespaces do not contend.
+ */
+function scopedLockKey(key, options) {
+    return options?.namespace !== undefined
+        ? `${options.namespace}${LOCK_SCOPE_SEPARATOR}${key}`
+        : key;
 }
 export class InMemoryLockStore {
     locks = new Map();
     async acquire(key, options) {
-        const ttl = options?.ttl ?? DEFAULT_LOCK_TTL_MS;
+        const ttl = options?.ttl !== undefined ? options.ttl : DEFAULT_LOCK_TTL_MS;
+        // A negative or zero TTL would mint an already-expired lease that the
+        // next sweep drops, giving no exclusion at all while appearing to work.
+        assertValidTtl(ttl);
         const token = generateToken();
-        const now = Date.now();
-        const expiresAt = now + ttl;
-        const existing = this.locks.get(key);
-        if (existing && existing.expiresAt !== null && now > existing.expiresAt)
-            this.locks.delete(key);
-        if (this.locks.has(key))
+        const now = monotonicNow();
+        const expiresAt = ttl !== null ? now + ttl : null;
+        const scoped = scopedLockKey(key, options);
+        this.sweepExpired(now);
+        if (this.locks.has(scoped))
             return null;
-        this.locks.set(key, { token, expiresAt });
+        this.locks.set(scoped, { token, expiresAt });
         return {
             key,
             token,
-            acquiredAt: new Date(now),
-            expiresAt: new Date(expiresAt),
+            acquiredAt: wallClockFor(now),
+            expiresAt: expiresAt !== null ? wallClockFor(expiresAt) : null,
             release: async () => {
-                const current = this.locks.get(key);
+                const current = this.locks.get(scoped);
                 if (current && current.token === token) {
-                    this.locks.delete(key);
+                    this.locks.delete(scoped);
                     return true;
                 }
                 return false;
             },
             extend: async (newTtl) => {
-                const current = this.locks.get(key);
+                assertValidTtl(newTtl);
+                const current = this.locks.get(scoped);
                 if (current && current.token === token) {
-                    this.locks.set(key, { ...current, expiresAt: Date.now() + newTtl });
+                    this.locks.set(scoped, {
+                        ...current,
+                        expiresAt: newTtl !== null ? monotonicNow() + newTtl : null,
+                    });
                     return true;
                 }
                 return false;
             },
         };
     }
+    /** Removes all expired locks. Called opportunistically on each acquire. */
+    sweepExpired(now = monotonicNow()) {
+        for (const [key, lock] of [...this.locks]) {
+            if (lock.expiresAt !== null && now >= lock.expiresAt) {
+                this.locks.delete(key);
+            }
+        }
+    }
     get size() {
         return this.locks.size;
     }
@@ -63,34 +97,126 @@ export class CacheLockManager {
         this.retryAttempts = options?.retryAttempts ?? DEFAULT_LOCK_RETRY_ATTEMPTS;
         this.retryDelayMs = options?.retryDelayMs ?? DEFAULT_LOCK_RETRY_DELAY_MS;
     }
+    /**
+     * Acquires a lock, retrying on contention.
+     *
+     * Returns `null` for ordinary contention (someone else holds it) and
+     * throws only when the *last* attempt failed with a store error — the two
+     * outcomes decide differently (retry vs. fail the request), so they are
+     * never conflated.
+     */
     async acquire(key, options) {
+        // Per-call retry options take precedence over manager defaults.
+        // `attempts: 0` is honored (single attempt, no retries).
+        const attempts = options?.retry?.attempts ?? this.retryAttempts;
+        const delay = options?.retry?.delay ?? this.retryDelayMs;
         let lastError;
-        for (let attempt = 0; attempt <= this.retryAttempts; attempt++) {
+        for (let attempt = 0; attempt <= attempts; attempt++) {
             try {
                 const lock = await this.store.acquire(key, options);
+                // An attempt that completed clears any earlier transient error:
+                // `lastError` must describe the final outcome, not a stale one.
+                lastError = undefined;
                 if (lock)
                     return lock;
             }
             catch (error) {
                 lastError = error;
             }
-            if (attempt < this.retryAttempts)
-                await sleep(this.retryDelayMs);
+            if (attempt < attempts)
+                await sleep(delay);
+        }
+        if (lastError) {
+            const code = "CACHE_LOCK_ACQUIRE_FAILED";
+            throw new CacheError(`Failed to acquire lock "${key}" after ${attempts} retries.`, {
+                code,
+                cause: lastError,
+                operation: CacheOperation.LOCK_ACQUIRE,
+                key,
+            });
         }
-        if (lastError)
-            throw new CacheError(`Failed to acquire lock "${key}" after ${this.retryAttempts} retries.`, { cause: lastError, operation: CacheOperation.LOCK_ACQUIRE, key });
         return null;
     }
+    /**
+     * Runs `fn` while holding the lock.
+     *
+     * The lease is renewed on an interval of roughly `ttl / 3` for as long as
+     * `fn` runs, so a critical section longer than the TTL does not silently
+     * lose mutual exclusion. If renewal or release reports that the lease is
+     * no longer ours, the `AbortSignal` passed to `fn` fires and the call
+     * throws — losing a lease is never reported as success.
+     */
     async withLock(key, fn, options) {
         const lock = await this.acquire(key, options);
-        if (!lock)
-            throw new CacheError(`Could not acquire lock "${key}" for exclusive operation.`, { operation: CacheOperation.LOCK_ACQUIRE, key, statusCode: 409 });
+        if (!lock) {
+            const code = "CACHE_LOCK_UNAVAILABLE";
+            throw new CacheError(`Could not acquire lock "${key}" for exclusive operation.`, {
+                code,
+                operation: CacheOperation.LOCK_ACQUIRE,
+                key,
+                statusCode: 409,
+            });
+        }
+        const ttl = options?.ttl !== undefined ? options.ttl : DEFAULT_LOCK_TTL_MS;
+        const controller = new AbortController();
+        let leaseLost = false;
+        let heartbeat;
+        if (ttl !== null) {
+            const interval = Math.max(1, Math.floor(ttl / LOCK_HEARTBEAT_DIVISOR));
+            heartbeat = setInterval(() => {
+                void (async () => {
+                    try {
+                        const extended = await lock.extend(ttl);
+                        if (extended)
+                            return;
+                    }
+                    catch {
+                        /* fall through — treat a failed renewal as a lost lease */
+                    }
+                    leaseLost = true;
+                    if (heartbeat !== undefined)
+                        clearInterval(heartbeat);
+                    controller.abort(new CacheError(`Lock "${key}" lease was lost during renewal.`, {
+                        code: "CACHE_LOCK_LOST",
+                        operation: CacheOperation.LOCK_ACQUIRE,
+                        key,
+                    }));
+                })();
+            }, interval);
+            // Never hold the event loop open on the cache's behalf.
+            heartbeat.unref?.();
+        }
+        let value;
+        let failure;
+        let failed = false;
         try {
-            return await fn();
+            value = await fn(controller.signal);
+        }
+        catch (error) {
+            failed = true;
+            failure = error;
         }
         finally {
-            await lock.release();
+            if (heartbeat !== undefined)
+                clearInterval(heartbeat);
         }
+        // `release()` returning false is the one signal that the lease expired or
+        // was taken over mid-critical-section. Surfacing it is the whole point of
+        // minting a fencing token. An error thrown by `fn` still wins, so the
+        // real cause is never masked.
+        const released = await lock.release();
+        if (failed)
+            throw failure;
+        if (!released || leaseLost) {
+            const code = "CACHE_LOCK_LOST";
+            throw new CacheError(`Lock "${key}" was lost before the critical section completed; its result cannot be trusted.`, {
+                code,
+                operation: CacheOperation.LOCK_RELEASE,
+                key,
+                statusCode: 409,
+            });
+        }
+        return value;
     }
 }
 function sleep(ms) {
@@ -99,5 +225,9 @@ function sleep(ms) {
 export function createLockManager(options) {
     return new CacheLockManager(options);
 }
+/**
+ * Process-wide lock store. Pass it as `CacheConfig.lockStore` when several
+ * `CacheService` instances in one process must share locks.
+ */
 export const defaultLockStore = new InMemoryLockStore();
 //# sourceMappingURL=lock.js.map

package/dist/memory.d.ts

@@ -1,16 +1,51 @@
 /**
  * @zudojs/cache — Memory Adapter
  * In-memory cache adapter using a Map. Suitable for development, testing, and single-process deployments.
+ *
+ * Receives fully-qualified keys; namespace resolution happens in CacheService.
+ *
+ * Bounds: the store is capped both by entry count (`maxEntries`) and by an
+ * approximate byte budget (`maxBytes`). Eviction is LRU — reads move an
+ * entry to the back of the queue, so the hottest keys survive.
+ *
+ * Expiry is measured on a monotonic clock, so an NTP step or a VM resume
+ * cannot extend (or collapse) an entry's lifetime. The wall-clock
+ * `expiresAt` returned to callers is derived from it for display only.
  */
-import type { CacheAdapter, CacheClearOptions, CacheClearResult, CacheDeleteResult, CacheGetResult, CacheKeysOptions, CacheSetManyOptions, CacheSetOptions, CacheSetResult, CacheTTL } from "./types.js";
+import type { CacheClearOptions, CacheClearResult, CacheDeleteManyResult, CacheDeleteResult, CacheGetResult, CacheKeysOptions, CacheSetManyOptions, CacheSetOptions, CacheSetResult, CacheTTL } from "./types.js";
+import type { CacheAdapter } from "./types.js";
+/**
+ * Approximates the retained size of a value in bytes.
+ *
+ * Deliberately bounded: at most `SIZE_ESTIMATE_NODE_BUDGET` nodes are
+ * visited, so `set` stays cheap for large object graphs. Beyond the budget
+ * the remainder is charged a flat per-node estimate, which keeps the number
+ * monotone in value size without walking the whole graph.
+ */
+export declare function estimateValueBytes(value: unknown): number;
 export declare class MemoryCacheAdapter implements CacheAdapter {
     readonly name = "memory";
     private readonly store;
     private readonly maxEntries;
+    private readonly maxBytes;
     private readonly defaultTtl;
+    private readonly separator;
+    private bytesUsed;
+    private lastPurgeAt;
     constructor(options?: {
         readonly maxEntries?: number;
+        /**
+         * Approximate memory budget in bytes. Entries are evicted (LRU) until
+         * the estimated total fits. Defaults to `DEFAULT_MAX_MEMORY_BYTES`.
+         */
+        readonly maxBytes?: number;
         readonly defaultTtl?: CacheTTL;
+        /**
+         * Key separator used when matching glob patterns. `*` never crosses it.
+         * Defaults to `DEFAULT_SEPARATOR`; set it to match a custom key-builder
+         * separator.
+         */
+        readonly separator?: string;
     });
     get<TValue = unknown>(key: string): Promise<CacheGetResult<TValue>>;
     set<TValue = unknown>(key: string, value: TValue, options?: CacheSetOptions): Promise<CacheSetResult>;
@@ -18,20 +53,41 @@ export declare class MemoryCacheAdapter implements CacheAdapter {
     has(key: string): Promise<boolean>;
     clear(options?: CacheClearOptions): Promise<CacheClearResult>;
     keys(options?: CacheKeysOptions): Promise<readonly string[]>;
+    /** Number of live entries currently held. */
+    size(): Promise<number>;
+    /** Estimated bytes currently retained by cached values. */
+    get estimatedBytes(): number;
     getMany<TValue = unknown>(keys: readonly string[]): Promise<ReadonlyMap<string, CacheGetResult<TValue>>>;
     setMany<TValue = unknown>(entries: ReadonlyMap<string, TValue>, options?: CacheSetManyOptions): Promise<readonly CacheSetResult[]>;
-    deleteMany(keys: readonly string[]): Promise<{
-        readonly deleted: number;
-        readonly keys: readonly string[];
-    }>;
-    ttl(key: string): Promise<number | null>;
+    deleteMany(keys: readonly string[]): Promise<CacheDeleteManyResult>;
+    /**
+     * Remaining TTL for a key in milliseconds.
+     * - `undefined` — the key does not exist (expired entries are deleted)
+     * - `null` — the key exists and never expires
+     * - `number` — remaining milliseconds until expiry
+     */
+    ttl(key: string): Promise<number | null | undefined>;
     expire(key: string, ttl: CacheTTL): Promise<boolean>;
+    private toCacheEntry;
+    /**
+     * An entry is dead *at* its deadline, not one millisecond after it, so
+     * `ttl(key) === 0` and "present" are never both true.
+     */
     private isExpired;
+    private remove;
+    private purgeExpired;
+    private maybePurgeExpired;
+    /**
+     * Makes room for an incoming entry of `incomingBytes`, honouring both the
+     * entry-count cap and the memory budget. Expired entries are purged before
+     * live ones are evicted; live eviction is least-recently-used.
+     */
     private evictIfNeeded;
-    private patternToRegex;
 }
 export declare function createMemoryCacheAdapter(options?: {
     readonly maxEntries?: number;
+    readonly maxBytes?: number;
     readonly defaultTtl?: CacheTTL;
+    readonly separator?: string;
 }): MemoryCacheAdapter;
 //# sourceMappingURL=memory.d.ts.map