@zudojs/cache 0.0.1 → 1.0.0

package/dist/cache.js

@@ -1,14 +1,28 @@
 /**
  * @zudojs/cache — Cache Service
- * High-level cache service combining adapter, serializer, key builder, tags, invalidation, locking, and metrics.
+ * High-level cache service combining adapter, key builder, tags,
+ * invalidation, locking, metrics, middleware, events, and an optional
+ * serializer.
+ *
+ * Serialization: when `config.serializer` is provided, values are
+ * serialized on set and deserialized on get, so cached values are
+ * structural copies. Without a serializer the memory adapter stores
+ * values by reference — mutations of a cached object are visible to
+ * later readers.
+ *
+ * Scoping: keys, tags and locks are all namespace-scoped. A namespace is
+ * validated as an identity part everywhere it is used (including in glob
+ * patterns), so it can never widen an operation beyond its own tenant.
  */
-import { DEFAULT_TTL_MS } from "./constants.js";
+import { DEFAULT_LOCK_RETRY_DELAY_MS, DEFAULT_SEPARATOR, DEFAULT_TTL_MS, } from "./constants.js";
 import { DefaultKeyBuilder } from "./key-builder.js";
 import { createCacheStore, DefaultCacheStore } from "./store.js";
-import { createTagStore, InMemoryTagStore } from "./tags.js";
+import { assertValidTag, createTagStore, InMemoryTagStore } from "./tags.js";
 import { CacheInvalidationManager, createInvalidationManager, } from "./invalidation.js";
 import { CacheLockManager, createLockManager } from "./lock.js";
 import { createCacheMetrics, InMemoryCacheMetrics } from "./metrics.js";
+import { CacheError, cacheDeserializationError, cacheSerializationError, isCacheError, } from "./errors.js";
+import { createGlobMatcher } from "./utils.js";
 export class CacheService {
     store;
     keyBuilder;
@@ -16,93 +30,376 @@ export class CacheService {
     invalidation;
     lockManager;
     metrics;
+    serializer;
     defaultTtl;
     enabled;
+    failSilently;
+    /** Namespace configured for this service; the default scope for keys, tags and locks. */
+    namespace;
+    separator;
+    /** In-flight getOrSet computations, keyed by full key (stampede protection). */
+    inFlight = new Map();
     constructor(options) {
         this.enabled = options.config?.enabled ?? true;
-        this.defaultTtl = options.config?.defaultTtl ?? DEFAULT_TTL_MS;
+        this.failSilently = options.config?.failSilently ?? false;
+        this.defaultTtl =
+            options.config?.defaultTtl !== undefined
+                ? options.config.defaultTtl
+                : DEFAULT_TTL_MS;
+        this.serializer = options.config?.serializer ?? null;
+        this.namespace = options.config?.namespace;
+        this.separator = options.config?.separator ?? DEFAULT_SEPARATOR;
         this.metrics =
             options.config?.collectStats !== false ? createCacheMetrics() : null;
         this.store = createCacheStore({
             adapter: options.adapter,
-            metrics: this.metrics,
+            ...(this.metrics ? { metrics: this.metrics } : {}),
+            ...(options.config?.middlewares
+                ? { middlewares: options.config.middlewares }
+                : {}),
         });
         this.keyBuilder =
             options.keyBuilder ??
                 new DefaultKeyBuilder({
-                    prefix: options.config?.prefix,
-                    separator: options.config?.separator,
-                    namespace: options.config?.namespace,
+                    ...(options.config?.prefix !== undefined
+                        ? { prefix: options.config.prefix }
+                        : {}),
+                    ...(options.config?.separator !== undefined
+                        ? { separator: options.config.separator }
+                        : {}),
+                    ...(options.config?.namespace !== undefined
+                        ? { namespace: options.config.namespace }
+                        : {}),
                 });
         this.tagStore = createTagStore();
+        // Route invalidation through the instrumented store so metrics and
+        // events fire for invalidation-driven deletions too.
         this.invalidation = createInvalidationManager({
-            adapter: options.adapter,
+            adapter: this.store,
             tagStore: this.tagStore,
+            keyBuilder: this.keyBuilder,
         });
-        this.lockManager = createLockManager();
+        this.lockManager = createLockManager(options.config?.lockStore ? { store: options.config.lockStore } : {});
     }
     async get(key, options) {
         if (!this.enabled)
             return { hit: false, value: null };
-        return this.store.get(this.keyBuilder.build(key, options));
+        const fullKey = this.keyBuilder.build(key, options);
+        try {
+            const result = await this.store.get(fullKey);
+            if (!result.hit || !this.serializer)
+                return result;
+            const value = this.deserialize(result.value);
+            return {
+                ...result,
+                value,
+                ...(result.entry
+                    ? { entry: { ...result.entry, value } }
+                    : {}),
+            };
+        }
+        catch (error) {
+            if (this.failSilently)
+                return { hit: false, value: null };
+            throw error;
+        }
     }
     async set(key, value, options) {
         if (!this.enabled)
             return { success: false, key, expiresAt: null };
         const fullKey = this.keyBuilder.build(key, options);
-        const result = await this.store.set(fullKey, value, {
-            ttl: options?.ttl ?? this.defaultTtl,
-            ...options,
-        });
-        if (options?.tags && options.tags.length > 0)
-            await this.tagStore.add(fullKey, options.tags);
-        return result;
+        if (options?.tags)
+            for (const tag of options.tags)
+                assertValidTag(tag);
+        try {
+            const stored = this.serializer ? this.serialize(value) : value;
+            const result = await this.store.set(fullKey, stored, {
+                ttl: options?.ttl !== undefined ? options.ttl : this.defaultTtl,
+                ...(options?.tags !== undefined ? { tags: options.tags } : {}),
+                ...(options?.overwrite !== undefined
+                    ? { overwrite: options.overwrite }
+                    : {}),
+                ...(options?.metadata !== undefined
+                    ? { metadata: options.metadata }
+                    : {}),
+            });
+            if (result.success && options?.tags && options.tags.length > 0)
+                await this.tagStore.add(fullKey, options.tags, this.tagScope(options));
+            return result;
+        }
+        catch (error) {
+            if (this.failSilently)
+                return { success: false, key, expiresAt: null };
+            throw error;
+        }
     }
     async delete(key, options) {
         if (!this.enabled)
             return { deleted: false, key };
-        return this.store.delete(this.keyBuilder.build(key, options));
+        const fullKey = this.keyBuilder.build(key, options);
+        try {
+            const result = await this.store.delete(fullKey);
+            this.tagStore.removeKey(fullKey);
+            return result;
+        }
+        catch (error) {
+            if (this.failSilently)
+                return { deleted: false, key };
+            throw error;
+        }
     }
     async has(key, options) {
         if (!this.enabled)
             return false;
-        return this.store.has(this.keyBuilder.build(key, options));
+        const fullKey = this.keyBuilder.build(key, options);
+        try {
+            return await this.store.has(fullKey);
+        }
+        catch (error) {
+            if (this.failSilently)
+                return false;
+            throw error;
+        }
     }
+    /**
+     * Clears cache entries.
+     * - No options: clears everything (and flushes the tag store).
+     * - `namespace` and/or `pattern`: builds a fully-qualified pattern via
+     *   the key builder (prefix + namespace + pattern) so only matching
+     *   entries are removed. Both parts are validated: a `namespace` of `"*"`
+     *   is rejected rather than escaping its own scope.
+     */
     async clear(options) {
         if (!this.enabled)
             return { cleared: 0 };
-        return this.store.clear(options);
+        if (options?.pattern !== undefined || options?.namespace !== undefined) {
+            // Validation happens outside the failSilently guard: a malformed
+            // pattern is programmer error, not an adapter fault.
+            const pattern = this.qualifyPattern(options.pattern ?? "*", options.namespace);
+            try {
+                const result = await this.store.clear({ pattern });
+                this.purgeTagsMatching(pattern);
+                return result;
+            }
+            catch (error) {
+                if (this.failSilently)
+                    return { cleared: 0 };
+                throw error;
+            }
+        }
+        try {
+            const result = await this.store.clear();
+            this.tagStore.clear();
+            return result;
+        }
+        catch (error) {
+            if (this.failSilently)
+                return { cleared: 0 };
+            throw error;
+        }
+    }
+    /** Remaining TTL for a key (undefined = missing, null = never expires). */
+    async ttl(key, options) {
+        if (!this.enabled)
+            return undefined;
+        const fullKey = this.keyBuilder.build(key, options);
+        try {
+            return await this.store.ttl?.(fullKey);
+        }
+        catch (error) {
+            if (this.failSilently)
+                return undefined;
+            throw error;
+        }
+    }
+    /** Updates the TTL of an existing key. Returns false when unsupported or missing. */
+    async expire(key, ttl, options) {
+        if (!this.enabled)
+            return false;
+        const fullKey = this.keyBuilder.build(key, options);
+        try {
+            return (await this.store.expire?.(fullKey, ttl)) ?? false;
+        }
+        catch (error) {
+            if (this.failSilently)
+                return false;
+            throw error;
+        }
     }
     async getOrSet(key, fn, options) {
         if (!this.enabled)
             return { value: await fn(), cached: false };
+        const fullKey = this.keyBuilder.build(key, options);
         if (!options?.forceRefresh) {
             const cached = await this.get(key, options);
             if (cached.hit)
                 return { value: cached.value, cached: true };
+            // Stampede protection: concurrent misses share a single fn() call.
+            const pending = this.inFlight.get(fullKey);
+            if (pending)
+                return { value: (await pending), cached: false };
+        }
+        const promise = (async () => {
+            const value = await fn();
+            await this.set(key, value, options);
+            return value;
+        })();
+        this.inFlight.set(fullKey, promise);
+        try {
+            return { value: (await promise), cached: false };
+        }
+        finally {
+            if (this.inFlight.get(fullKey) === promise)
+                this.inFlight.delete(fullKey);
         }
-        const value = await fn();
-        await this.set(key, value, options);
-        return { value, cached: false };
     }
-    async invalidateByTag(tags) {
-        return this.invalidation.invalidateByTag(tags);
+    /**
+     * Invalidates every entry tagged with any of `tags`, within this
+     * service's namespace (or `options.namespace`). Tags registered under a
+     * different namespace are untouched.
+     */
+    async invalidateByTag(tags, options) {
+        if (!this.enabled)
+            return { cleared: 0 };
+        for (const tag of tags)
+            assertValidTag(tag);
+        try {
+            return await this.invalidation.invalidateByTag(tags, this.tagScope(options));
+        }
+        catch (error) {
+            if (this.failSilently)
+                return { cleared: 0 };
+            throw error;
+        }
     }
-    async invalidateByPattern(pattern) {
-        return this.invalidation.invalidateByPattern(pattern);
+    /**
+     * Invalidates entries matching a service-level glob pattern. The
+     * pattern is qualified with the key builder's prefix (and namespace,
+     * if configured), so `invalidateByPattern("user.*")` matches keys this
+     * service wrote via `set("user.1", ...)`.
+     *
+     * `*` never crosses the key separator, so a pattern cannot reach into a
+     * namespace the caller did not name. Use `**` as the pattern to span
+     * whole namespaces deliberately.
+     */
+    async invalidateByPattern(pattern, options) {
+        if (!this.enabled)
+            return { cleared: 0 };
+        const qualified = this.qualifyPattern(pattern, options?.namespace);
+        try {
+            const result = await this.invalidation.invalidateByPattern(qualified);
+            this.purgeTagsMatching(qualified);
+            return result;
+        }
+        catch (error) {
+            if (this.failSilently)
+                return { cleared: 0 };
+            throw error;
+        }
     }
+    /**
+     * Runs `fn` under a namespace-scoped, fully-qualified lock.
+     *
+     * The lock name goes through the key builder, so it is prefixed and
+     * namespaced exactly like a cache key and validated the same way — two
+     * tenants using the same lock name do not collide.
+     *
+     * The lease is renewed while `fn` runs and a lost lease throws (see
+     * `CacheLockManager.withLock`). `failSilently` deliberately does not apply:
+     * running a critical section without exclusion is never a safe
+     * degradation, and neither is running it while the cache is disabled.
+     */
     async withLock(key, fn, options) {
-        return this.lockManager.withLock(key, fn, {
-            ttl: options?.ttl,
-            retry: options?.retryAttempts
-                ? { attempts: options.retryAttempts, delay: 100 }
-                : undefined,
+        if (!this.enabled) {
+            const code = "CACHE_DISABLED";
+            throw new CacheError(`Cannot acquire lock "${key}": the cache is disabled.`, { code, statusCode: 503 });
+        }
+        const lockKey = this.keyBuilder.build(key, options?.namespace !== undefined
+            ? { namespace: options.namespace }
+            : undefined);
+        return this.lockManager.withLock(lockKey, fn, {
+            ...(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
+            // `retryAttempts: 0` is honored (single attempt, no retries).
+            ...(options?.retryAttempts !== undefined
+                ? {
+                    retry: {
+                        attempts: options.retryAttempts,
+                        delay: DEFAULT_LOCK_RETRY_DELAY_MS,
+                    },
+                }
+                : {}),
         });
     }
+    /**
+     * Applies a sequence of operations, one at a time, returning one result
+     * per operation in submission order. A failing operation does not stop
+     * the batch; its error is reported on its own result.
+     */
+    async batch(operations, options) {
+        const results = [];
+        for (const operation of operations) {
+            try {
+                const result = await this.applyBatchOperation(operation, options);
+                results.push({ operation, success: true, result });
+            }
+            catch (error) {
+                results.push({ operation, success: false, error });
+            }
+        }
+        return results;
+    }
+    /* ---- Observability ---- */
     getStats() {
         return this.metrics?.getStats() ?? null;
     }
+    /** Number of live entries, when the underlying adapter can report it. */
+    async size() {
+        if (!this.enabled)
+            return undefined;
+        try {
+            return await this.store.size();
+        }
+        catch (error) {
+            if (this.failSilently)
+                return undefined;
+            throw error;
+        }
+    }
+    /** Latency percentiles for one operation. */
+    getLatencyStats(operation) {
+        return this.metrics?.getLatencyStats(operation) ?? null;
+    }
+    /** Latency histogram for one operation. */
+    getLatencyHistogram(operation) {
+        return this.metrics?.getLatencyHistogram(operation) ?? null;
+    }
+    /** The most-read keys currently tracked, hottest first. */
+    getHotKeys(topN) {
+        return this.metrics?.getHotKeys(topN) ?? null;
+    }
+    /** Resets all collected metrics. */
+    resetStats() {
+        this.metrics?.reset();
+    }
+    /**
+     * Subscribes to cache events (`cache.hit`, `cache.miss`, `cache.set`,
+     * `cache.delete`, `cache.clear`, `cache.error`), or to `"*"` for all.
+     */
+    subscribe(eventType, handler) {
+        return this.store.subscribe(eventType, handler);
+    }
     async healthCheck() {
+        if (!this.enabled) {
+            // A disabled cache is not unhealthy — but the caller must be able to
+            // tell the two apart, so say so explicitly instead of probing an
+            // adapter the service has been told not to use.
+            return {
+                healthy: true,
+                adapter: this.store.name,
+                checkedAt: new Date(),
+                disabled: true,
+            };
+        }
         const start = performance.now();
         try {
             await this.store.has("__health__");
@@ -127,6 +424,69 @@ export class CacheService {
     }
     async disconnect() {
         await this.store.disconnect?.();
+        // Drop service-local state so a reconnect does not resurrect stale
+        // in-flight computations or tag mappings.
+        this.inFlight.clear();
+        this.tagStore.clear();
+    }
+    /* ---- Internals ---- */
+    async applyBatchOperation(operation, options) {
+        const scope = options?.namespace !== undefined
+            ? { namespace: options.namespace }
+            : undefined;
+        switch (operation.type) {
+            case "get":
+                return this.get(operation.key, scope);
+            case "set":
+                return this.set(operation.key, operation.value, {
+                    ...operation.options,
+                    ...(scope ?? {}),
+                });
+            case "delete":
+                return this.delete(operation.key, scope);
+            default: {
+                const code = "CACHE_OPERATION_FAILED";
+                throw new CacheError(`Unsupported batch operation type: ${String(operation.type)}.`, { code, key: operation.key, statusCode: 400, expose: true });
+            }
+        }
+    }
+    /** The namespace scope applied to tag registrations and lookups. */
+    tagScope(options) {
+        const namespace = options?.namespace ?? this.namespace;
+        return namespace !== undefined ? { namespace } : {};
+    }
+    qualifyPattern(pattern, namespace) {
+        if (this.keyBuilder.buildPattern) {
+            return this.keyBuilder.buildPattern(pattern, namespace !== undefined ? { namespace } : undefined);
+        }
+        return pattern;
+    }
+    purgeTagsMatching(pattern) {
+        const matches = createGlobMatcher(pattern, { separator: this.separator });
+        for (const key of this.tagStore.trackedKeys()) {
+            if (matches(key))
+                this.tagStore.removeKey(key);
+        }
+    }
+    serialize(value) {
+        try {
+            return this.serializer.serialize(value);
+        }
+        catch (error) {
+            if (isCacheError(error))
+                throw error;
+            throw cacheSerializationError(undefined, { cause: error });
+        }
+    }
+    deserialize(value) {
+        try {
+            return this.serializer.deserialize(value);
+        }
+        catch (error) {
+            if (isCacheError(error))
+                throw error;
+            throw cacheDeserializationError(undefined, { cause: error });
+        }
     }
 }
 export function createCacheService(options) {

package/dist/constants.d.ts

@@ -5,36 +5,70 @@
  */
 /** Default time-to-live in milliseconds (5 minutes). */
 export declare const DEFAULT_TTL_MS: number;
-/** Maximum supported TTL (24 hours). */
+/** Maximum supported TTL (24 hours). TTLs above this are rejected. */
 export declare const MAX_TTL_MS: number;
-/** Minimum TTL (1 second). */
-export declare const MIN_TTL_MS = 1000;
+/**
+ * Minimum TTL (1 millisecond). TTLs below this (zero or negative) are
+ * rejected; use `ttl: null` for entries that never expire.
+ */
+export declare const MIN_TTL_MS = 1;
 /** Default namespace separator. */
 export declare const DEFAULT_SEPARATOR = ":";
 /** Default key prefix. */
 export declare const DEFAULT_PREFIX = "zudojs";
 /** Maximum key length in characters. */
 export declare const MAX_KEY_LENGTH = 256;
-/** Pattern used to validate cache keys. */
+/**
+ * Pattern used to validate each individual cache key part (prefix,
+ * namespace, and raw key). Deliberately excludes the default separator
+ * (`:`) so callers cannot forge namespaced keys (e.g. `build("admin:x")`
+ * throws). Parts are additionally checked against the active separator.
+ */
 export declare const CACHE_KEY_PATTERN: RegExp;
+/**
+ * Pattern used to validate the caller-supplied *glob* segment of a key
+ * pattern. It is the key alphabet plus the two glob metacharacters `*` and
+ * `?` — nothing else has meaning for the matcher, so anything else is
+ * caller error. The separator is excluded so a pattern cannot escape the
+ * prefix/namespace scope it is composed into.
+ */
+export declare const CACHE_PATTERN_PART_PATTERN: RegExp;
+/** Maximum length of a cache tag. Tags are untrusted map keys. */
+export declare const MAX_TAG_LENGTH = 128;
 /** Default lock TTL in milliseconds (30 seconds). */
 export declare const DEFAULT_LOCK_TTL_MS = 30000;
 /** Default number of retry attempts for lock acquisition. */
 export declare const DEFAULT_LOCK_RETRY_ATTEMPTS = 3;
 /** Default delay between lock retry attempts in milliseconds. */
 export declare const DEFAULT_LOCK_RETRY_DELAY_MS = 100;
+/**
+ * Divisor applied to a lock's TTL to derive its heartbeat interval, so a
+ * lease is renewed roughly three times per TTL window while the critical
+ * section runs.
+ */
+export declare const LOCK_HEARTBEAT_DIVISOR = 3;
 /** Maximum number of latency samples to keep per operation. */
 export declare const MAX_LATENCY_SAMPLES = 1000;
-/** Bucket boundaries for latency histograms (ms). */
+/** Maximum number of distinct keys tracked for hot-key metrics. */
+export declare const MAX_TRACKED_KEYS = 1024;
+/** Bucket boundaries for latency histograms (ms). A +Infinity bucket is appended at query time. */
 export declare const LATENCY_BUCKETS: readonly [1, 5, 10, 25, 50, 100, 250, 500, 1000];
 /** Default maximum number of entries for the in-memory adapter. */
 export declare const DEFAULT_MAX_ENTRIES = 10000;
-/** Default maximum memory budget in bytes (50 MB). */
+/**
+ * Default maximum memory budget in bytes (50 MB) for the in-memory adapter.
+ * Entry sizes are estimated (see `MemoryCacheAdapter`), so the budget is
+ * approximate; it exists to bound worst-case retention, not to be exact.
+ */
 export declare const DEFAULT_MAX_MEMORY_BYTES: number;
-/** Maximum number of keys in a single batch operation. */
-export declare const MAX_BATCH_SIZE = 100;
-/** Glob pattern for matching all keys. */
-export declare const MATCH_ALL_PATTERN = "*";
-/** Regex pattern that matches valid namespace characters. */
-export declare const NAMESPACE_PATTERN: RegExp;
+/**
+ * How often (at most) the in-memory adapter opportunistically purges expired
+ * entries on the overwrite path, where no eviction is otherwise triggered.
+ */
+export declare const EXPIRED_PURGE_INTERVAL_MS = 30000;
+/**
+ * Maximum number of value nodes visited when estimating an entry's size.
+ * Keeps `set` O(1)-ish for large object graphs at the cost of accuracy.
+ */
+export declare const SIZE_ESTIMATE_NODE_BUDGET = 512;
 //# sourceMappingURL=constants.d.ts.map