@zudojs/cache 0.1.0 → 1.0.0

package/dist/constants.js

@@ -8,10 +8,13 @@
 /* -------------------------------------------------------------------------- */
 /** Default time-to-live in milliseconds (5 minutes). */
 export const DEFAULT_TTL_MS = 5 * 60 * 1000;
-/** Maximum supported TTL (24 hours). */
+/** Maximum supported TTL (24 hours). TTLs above this are rejected. */
 export const MAX_TTL_MS = 24 * 60 * 60 * 1000;
-/** Minimum TTL (1 second). */
-export const MIN_TTL_MS = 1_000;
+/**
+ * Minimum TTL (1 millisecond). TTLs below this (zero or negative) are
+ * rejected; use `ttl: null` for entries that never expire.
+ */
+export const MIN_TTL_MS = 1;
 /* -------------------------------------------------------------------------- */
 /* Key Generation                                                             */
 /* -------------------------------------------------------------------------- */
@@ -21,8 +24,23 @@ export const DEFAULT_SEPARATOR = ":";
 export const DEFAULT_PREFIX = "zudojs";
 /** Maximum key length in characters. */
 export const MAX_KEY_LENGTH = 256;
-/** Pattern used to validate cache keys. */
-export const CACHE_KEY_PATTERN = /^[a-zA-Z0-9._\-:]+$/;
+/**
+ * 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 const CACHE_KEY_PATTERN = /^[a-zA-Z0-9._\-]+$/;
+/**
+ * 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 const CACHE_PATTERN_PART_PATTERN = /^[a-zA-Z0-9._\-*?]+$/;
+/** Maximum length of a cache tag. Tags are untrusted map keys. */
+export const MAX_TAG_LENGTH = 128;
 /* -------------------------------------------------------------------------- */
 /* Lock Defaults                                                              */
 /* -------------------------------------------------------------------------- */
@@ -32,30 +50,40 @@ export const DEFAULT_LOCK_TTL_MS = 30_000;
 export const DEFAULT_LOCK_RETRY_ATTEMPTS = 3;
 /** Default delay between lock retry attempts in milliseconds. */
 export 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 const LOCK_HEARTBEAT_DIVISOR = 3;
 /* -------------------------------------------------------------------------- */
 /* Metrics                                                                    */
 /* -------------------------------------------------------------------------- */
 /** Maximum number of latency samples to keep per operation. */
 export const MAX_LATENCY_SAMPLES = 1_000;
-/** Bucket boundaries for latency histograms (ms). */
+/** Maximum number of distinct keys tracked for hot-key metrics. */
+export const MAX_TRACKED_KEYS = 1_024;
+/** Bucket boundaries for latency histograms (ms). A +Infinity bucket is appended at query time. */
 export const LATENCY_BUCKETS = [1, 5, 10, 25, 50, 100, 250, 500, 1000];
 /* -------------------------------------------------------------------------- */
 /* Memory Adapter                                                             */
 /* -------------------------------------------------------------------------- */
 /** Default maximum number of entries for the in-memory adapter. */
 export const DEFAULT_MAX_ENTRIES = 10_000;
-/** 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 const DEFAULT_MAX_MEMORY_BYTES = 50 * 1024 * 1024;
-/* -------------------------------------------------------------------------- */
-/* Batch Operations                                                           */
-/* -------------------------------------------------------------------------- */
-/** Maximum number of keys in a single batch operation. */
-export const MAX_BATCH_SIZE = 100;
-/* -------------------------------------------------------------------------- */
-/* Patterns                                                                   */
-/* -------------------------------------------------------------------------- */
-/** Glob pattern for matching all keys. */
-export const MATCH_ALL_PATTERN = "*";
-/** Regex pattern that matches valid namespace characters. */
-export const NAMESPACE_PATTERN = /^[a-zA-Z0-9._\-]+$/;
+/**
+ * How often (at most) the in-memory adapter opportunistically purges expired
+ * entries on the overwrite path, where no eviction is otherwise triggered.
+ */
+export const EXPIRED_PURGE_INTERVAL_MS = 30_000;
+/**
+ * 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 const SIZE_ESTIMATE_NODE_BUDGET = 512;
 //# sourceMappingURL=constants.js.map

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * @zudojs/cache
  *
  * Cache abstraction layer with memory adapter, tag-based
- * invalidation, distributed locking, and metrics.
+ * invalidation, in-process locking, events, middleware, and metrics.
  *
  * @example
  * ```ts
@@ -13,21 +13,22 @@
  *   config: { defaultTtl: 60_000 },
  * });
  *
- * await cache.set("user:123", { name: "Alice" }, { tags: ["users"] });
- * const result = await cache.get("user:123");
+ * // Key parts must not contain the separator, so use "." inside a key.
+ * await cache.set("user.123", { name: "Alice" }, { tags: ["users"] });
+ * const { hit, value } = await cache.get<{ name: string }>("user.123");
  * ```
  */
-export type { CacheKey, CacheNamespace, CacheKeyParts, CacheKeyOptions, CacheValue, SerializableCacheValue, CacheTTL, CacheExpiration, CacheExpirationInfo, CacheSetOptions, CacheGetOptions, CacheDeleteOptions, CacheHasOptions, CacheClearOptions, CacheKeysOptions, CacheGetManyOptions, CacheSetManyOptions, CacheDeleteManyOptions, CacheEntry, CacheEntryMetadata, CacheGetResult, CacheSetResult, CacheDeleteResult, CacheDeleteManyResult, CacheClearResult, CacheStats, CacheAdapter, CacheStore, CacheAdapterFactory, CacheConfig, CacheEventType, CacheTag, CacheTagOptions, CacheTagStore, CacheLockOptions, CacheLock, CacheLockStore, CacheHealth, CacheHealthChecker, CacheSerializer, CacheMetrics, CacheOperation, CacheMiddlewareContext, CacheMiddleware, CacheSerializationOptions, CacheErrorCode, CacheOrComputeOptions, CacheOrComputeResult, CacheBatchOperation, CacheBatchResult, MaybePromise, CacheResult, } from "./types.js";
+export type { CacheKey, CacheNamespace, CacheKeyOptions, CacheTTL, CacheExpiration, CacheSetOptions, CacheClearOptions, CacheKeysOptions, CacheSetManyOptions, CacheEntry, CacheGetResult, CacheSetResult, CacheDeleteResult, CacheDeleteManyResult, CacheClearResult, CacheStats, CacheAdapter, CacheStore, CacheConfig, CacheEventType, CacheTag, CacheTagOptions, CacheTagStore, CacheLockOptions, CacheLock, CacheLockStore, CacheHealth, CacheHealthChecker, CacheSerializer, CacheMetrics, CacheMiddlewareContext, CacheMiddleware, CacheSerializationOptions, CacheErrorCode, CacheOrComputeOptions, CacheOrComputeResult, CacheBatchOperation, CacheBatchResult, MaybePromise, } from "./types.js";
 export type { BaseCacheEvent, CacheHitEvent, CacheMissEvent, CacheSetEvent, CacheDeleteEvent, CacheClearEvent, CacheErrorEvent, CacheEvent, CacheEventHandler, CacheEventSubscription, } from "./types-events.js";
 export type { CacheKeyBuilder } from "./types-keys.js";
-export { DEFAULT_TTL_MS, MAX_TTL_MS, MIN_TTL_MS, DEFAULT_SEPARATOR, DEFAULT_PREFIX, MAX_KEY_LENGTH, CACHE_KEY_PATTERN, DEFAULT_LOCK_TTL_MS, DEFAULT_LOCK_RETRY_ATTEMPTS, DEFAULT_LOCK_RETRY_DELAY_MS, MAX_LATENCY_SAMPLES, LATENCY_BUCKETS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_MEMORY_BYTES, MAX_BATCH_SIZE, MATCH_ALL_PATTERN, NAMESPACE_PATTERN, } from "./constants.js";
-export { CacheError, isCacheError, cacheConnectionError, cacheTimeoutError, cacheSerializationError, cacheDeserializationError, cacheInvalidKeyError, cacheAdapterNotConfiguredError, } from "./errors.js";
+export { DEFAULT_TTL_MS, MAX_TTL_MS, MIN_TTL_MS, DEFAULT_SEPARATOR, DEFAULT_PREFIX, MAX_KEY_LENGTH, CACHE_KEY_PATTERN, DEFAULT_LOCK_TTL_MS, DEFAULT_LOCK_RETRY_ATTEMPTS, DEFAULT_LOCK_RETRY_DELAY_MS, MAX_LATENCY_SAMPLES, MAX_TRACKED_KEYS, LATENCY_BUCKETS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_MEMORY_BYTES, EXPIRED_PURGE_INTERVAL_MS, CACHE_PATTERN_PART_PATTERN, MAX_TAG_LENGTH, } from "./constants.js";
+export { CacheError, isCacheError, cacheConnectionError, cacheTimeoutError, cacheSerializationError, cacheDeserializationError, cacheInvalidKeyError, cacheAdapterNotConfiguredError, CacheOperation, } from "./errors.js";
 export type { CacheErrorOptions } from "./errors.js";
-export { JsonCacheSerializer, RawCacheSerializer, defaultSerializer, rawSerializer, getSerializer, } from "./serializer.js";
+export { JsonCacheSerializer, RawCacheSerializer, defaultSerializer, rawSerializer, stripUnsafeKeys, } from "./serializer.js";
 export { DefaultKeyBuilder, createKeyBuilder, defaultKeyBuilder, } from "./key-builder.js";
 export { DefaultCacheStore, createCacheStore } from "./store.js";
-export { MemoryCacheAdapter, createMemoryCacheAdapter } from "./memory.js";
-export { InMemoryTagStore, createTagStore } from "./tags.js";
+export { MemoryCacheAdapter, createMemoryCacheAdapter, estimateValueBytes, } from "./memory.js";
+export { InMemoryTagStore, createTagStore, assertValidTag } from "./tags.js";
 export { CacheInvalidationManager, createInvalidationManager, } from "./invalidation.js";
 export { InMemoryLockStore, CacheLockManager, createLockManager, defaultLockStore, } from "./lock.js";
 export { InMemoryCacheMetrics, createCacheMetrics } from "./metrics.js";

package/dist/index.js

@@ -2,7 +2,7 @@
  * @zudojs/cache
  *
  * Cache abstraction layer with memory adapter, tag-based
- * invalidation, distributed locking, and metrics.
+ * invalidation, in-process locking, events, middleware, and metrics.
  *
  * @example
  * ```ts
@@ -13,24 +13,25 @@
  *   config: { defaultTtl: 60_000 },
  * });
  *
- * await cache.set("user:123", { name: "Alice" }, { tags: ["users"] });
- * const result = await cache.get("user:123");
+ * // Key parts must not contain the separator, so use "." inside a key.
+ * await cache.set("user.123", { name: "Alice" }, { tags: ["users"] });
+ * const { hit, value } = await cache.get<{ name: string }>("user.123");
  * ```
  */
 // Constants
-export { DEFAULT_TTL_MS, MAX_TTL_MS, MIN_TTL_MS, DEFAULT_SEPARATOR, DEFAULT_PREFIX, MAX_KEY_LENGTH, CACHE_KEY_PATTERN, DEFAULT_LOCK_TTL_MS, DEFAULT_LOCK_RETRY_ATTEMPTS, DEFAULT_LOCK_RETRY_DELAY_MS, MAX_LATENCY_SAMPLES, LATENCY_BUCKETS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_MEMORY_BYTES, MAX_BATCH_SIZE, MATCH_ALL_PATTERN, NAMESPACE_PATTERN, } from "./constants.js";
+export { DEFAULT_TTL_MS, MAX_TTL_MS, MIN_TTL_MS, DEFAULT_SEPARATOR, DEFAULT_PREFIX, MAX_KEY_LENGTH, CACHE_KEY_PATTERN, DEFAULT_LOCK_TTL_MS, DEFAULT_LOCK_RETRY_ATTEMPTS, DEFAULT_LOCK_RETRY_DELAY_MS, MAX_LATENCY_SAMPLES, MAX_TRACKED_KEYS, LATENCY_BUCKETS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_MEMORY_BYTES, EXPIRED_PURGE_INTERVAL_MS, CACHE_PATTERN_PART_PATTERN, MAX_TAG_LENGTH, } from "./constants.js";
 // Errors (re-exported from @zudojs/errors)
-export { CacheError, isCacheError, cacheConnectionError, cacheTimeoutError, cacheSerializationError, cacheDeserializationError, cacheInvalidKeyError, cacheAdapterNotConfiguredError, } from "./errors.js";
+export { CacheError, isCacheError, cacheConnectionError, cacheTimeoutError, cacheSerializationError, cacheDeserializationError, cacheInvalidKeyError, cacheAdapterNotConfiguredError, CacheOperation, } from "./errors.js";
 // Serializer
-export { JsonCacheSerializer, RawCacheSerializer, defaultSerializer, rawSerializer, getSerializer, } from "./serializer.js";
+export { JsonCacheSerializer, RawCacheSerializer, defaultSerializer, rawSerializer, stripUnsafeKeys, } from "./serializer.js";
 // Key Builder
 export { DefaultKeyBuilder, createKeyBuilder, defaultKeyBuilder, } from "./key-builder.js";
 // Store
 export { DefaultCacheStore, createCacheStore } from "./store.js";
 // Memory Adapter
-export { MemoryCacheAdapter, createMemoryCacheAdapter } from "./memory.js";
+export { MemoryCacheAdapter, createMemoryCacheAdapter, estimateValueBytes, } from "./memory.js";
 // Tags
-export { InMemoryTagStore, createTagStore } from "./tags.js";
+export { InMemoryTagStore, createTagStore, assertValidTag } from "./tags.js";
 // Invalidation
 export { CacheInvalidationManager, createInvalidationManager, } from "./invalidation.js";
 // Lock

package/dist/invalidation.d.ts

@@ -4,8 +4,14 @@
  * Coordinates cache invalidation across tags, patterns, and keys.
  * Works with both the tag store and the cache adapter to ensure
  * consistent invalidation.
+ *
+ * The adapter passed in may be an instrumented `CacheStore` (as done by
+ * `CacheService`), in which case deletions flow through metrics/events.
+ * Adapters operate on fully-qualified keys and glob patterns only;
+ * namespace scoping is translated into patterns via the key builder.
  */
-import type { CacheAdapter, CacheClearResult, CacheKey, CacheNamespace, CacheTag, CacheTagStore } from "./types.js";
+import type { CacheAdapter, CacheClearResult, CacheKey, CacheNamespace, CacheTag, CacheTagOptions, CacheTagStore } from "./types.js";
+import type { CacheKeyBuilder } from "./types-keys.js";
 /**
  * Coordinates cache invalidation across multiple strategies:
  * - Tag-based invalidation
@@ -15,41 +21,41 @@ import type { CacheAdapter, CacheClearResult, CacheKey, CacheNamespace, CacheTag
 export declare class CacheInvalidationManager {
     private readonly adapter;
     private readonly tagStore;
+    private readonly keyBuilder?;
     constructor(options: {
         readonly adapter: CacheAdapter;
         readonly tagStore: CacheTagStore;
+        /** Used to translate namespaces into fully-qualified key patterns. */
+        readonly keyBuilder?: CacheKeyBuilder;
     });
     /**
-     * Invalidates all cache entries associated with the given tags.
-     * Returns the number of keys that were affected.
+     * Invalidates all cache entries associated with the given tags, within
+     * the given tag scope (namespace). Keys are de-duplicated across tags and
+     * only actual successful deletions are counted; keys that already expired
+     * or were evicted (dead tag mappings) are tolerated and simply skipped.
      */
-    invalidateByTag(tags: readonly CacheTag[], options?: {
-        readonly namespace?: CacheNamespace;
-    }): Promise<CacheClearResult>;
+    invalidateByTag(tags: readonly CacheTag[], options?: CacheTagOptions): Promise<CacheClearResult>;
     /**
      * Invalidates all cache entries matching the given glob pattern.
+     * The pattern is matched against fully-qualified keys as-is; use
+     * `CacheService.invalidateByPattern` for prefix/namespace-aware patterns.
      */
-    invalidateByPattern(pattern: string, options?: {
-        readonly namespace?: CacheNamespace;
-    }): Promise<CacheClearResult>;
+    invalidateByPattern(pattern: string): Promise<CacheClearResult>;
     /**
-     * Invalidates all cache entries in the given namespace.
+     * Invalidates all cache entries in the given namespace by building a
+     * key pattern (`prefix:namespace:*`) instead of wiping the whole cache.
      */
     invalidateByNamespace(namespace: CacheNamespace): Promise<CacheClearResult>;
     /**
      * Invalidates a specific cache key.
      */
-    invalidateKey(key: CacheKey, options?: {
-        readonly namespace?: CacheNamespace;
-    }): Promise<{
+    invalidateKey(key: CacheKey): Promise<{
         readonly deleted: boolean;
     }>;
     /**
      * Invalidates multiple cache keys at once.
      */
-    invalidateKeys(keys: readonly CacheKey[], options?: {
-        readonly namespace?: CacheNamespace;
-    }): Promise<{
+    invalidateKeys(keys: readonly CacheKey[]): Promise<{
         readonly deleted: number;
         readonly keys: readonly CacheKey[];
     }>;
@@ -64,5 +70,6 @@ export declare class CacheInvalidationManager {
 export declare function createInvalidationManager(options: {
     readonly adapter: CacheAdapter;
     readonly tagStore: CacheTagStore;
+    readonly keyBuilder?: CacheKeyBuilder;
 }): CacheInvalidationManager;
 //# sourceMappingURL=invalidation.d.ts.map

package/dist/invalidation.js

@@ -4,7 +4,14 @@
  * Coordinates cache invalidation across tags, patterns, and keys.
  * Works with both the tag store and the cache adapter to ensure
  * consistent invalidation.
+ *
+ * The adapter passed in may be an instrumented `CacheStore` (as done by
+ * `CacheService`), in which case deletions flow through metrics/events.
+ * Adapters operate on fully-qualified keys and glob patterns only;
+ * namespace scoping is translated into patterns via the key builder.
  */
+import { DEFAULT_SEPARATOR } from "./constants.js";
+import { deleteManyViaDelete } from "./utils.js";
 /* -------------------------------------------------------------------------- */
 /* Invalidation Manager                                                       */
 /* -------------------------------------------------------------------------- */
@@ -17,67 +24,72 @@
 export class CacheInvalidationManager {
     adapter;
     tagStore;
+    keyBuilder;
     constructor(options) {
         this.adapter = options.adapter;
         this.tagStore = options.tagStore;
+        this.keyBuilder = options.keyBuilder;
     }
     /* ---- Tag Invalidation ---- */
     /**
-     * Invalidates all cache entries associated with the given tags.
-     * Returns the number of keys that were affected.
+     * Invalidates all cache entries associated with the given tags, within
+     * the given tag scope (namespace). Keys are de-duplicated across tags and
+     * only actual successful deletions are counted; keys that already expired
+     * or were evicted (dead tag mappings) are tolerated and simply skipped.
      */
     async invalidateByTag(tags, options) {
-        let totalCleared = 0;
+        const keys = new Set();
+        for (const tag of tags) {
+            for (const key of await this.tagStore.getKeys(tag, options))
+                keys.add(key);
+        }
+        let cleared = 0;
+        for (const key of keys) {
+            const result = await this.adapter.delete(key);
+            if (result.deleted)
+                cleared++;
+            // The key is gone from the cache, so every tag mapping it still has
+            // (in any scope) is dead too.
+            this.tagStore.removeKey?.(key);
+        }
         for (const tag of tags) {
-            const keys = await this.tagStore.getKeys(tag, options);
-            for (const key of keys) {
-                await this.adapter.delete(key, options);
-            }
-            const result = await this.tagStore.invalidate(tag, options);
-            totalCleared += result.cleared;
+            await this.tagStore.invalidate(tag, options);
         }
-        return { cleared: totalCleared };
+        return { cleared };
     }
     /* ---- Pattern Invalidation ---- */
     /**
      * Invalidates all cache entries matching the given glob pattern.
+     * The pattern is matched against fully-qualified keys as-is; use
+     * `CacheService.invalidateByPattern` for prefix/namespace-aware patterns.
      */
-    async invalidateByPattern(pattern, options) {
-        return this.adapter.clear({
-            ...options,
-            pattern,
-        });
+    async invalidateByPattern(pattern) {
+        return this.adapter.clear({ pattern });
     }
     /* ---- Namespace Invalidation ---- */
     /**
-     * Invalidates all cache entries in the given namespace.
+     * Invalidates all cache entries in the given namespace by building a
+     * key pattern (`prefix:namespace:*`) instead of wiping the whole cache.
      */
     async invalidateByNamespace(namespace) {
-        return this.adapter.clear({ namespace });
+        const pattern = this.keyBuilder?.buildPattern?.("*", { namespace }) ??
+            `${namespace}${DEFAULT_SEPARATOR}*`;
+        return this.adapter.clear({ pattern });
     }
     /* ---- Direct Key Invalidation ---- */
     /**
      * Invalidates a specific cache key.
      */
-    async invalidateKey(key, options) {
-        const result = await this.adapter.delete(key, options);
+    async invalidateKey(key) {
+        const result = await this.adapter.delete(key);
         return { deleted: result.deleted };
     }
     /* ---- Bulk Invalidation ---- */
     /**
      * Invalidates multiple cache keys at once.
      */
-    async invalidateKeys(keys, options) {
-        let deleted = 0;
-        const deletedKeys = [];
-        for (const key of keys) {
-            const result = await this.adapter.delete(key, options);
-            if (result.deleted) {
-                deleted++;
-                deletedKeys.push(key);
-            }
-        }
-        return { deleted, keys: deletedKeys };
+    async invalidateKeys(keys) {
+        return deleteManyViaDelete(keys, (key) => this.adapter.delete(key));
     }
     /* ---- Full Flush ---- */
     /**
@@ -85,9 +97,7 @@ export class CacheInvalidationManager {
      */
     async flushAll() {
         const result = await this.adapter.clear();
-        if (typeof this.tagStore.clear === "function") {
-            this.tagStore.clear();
-        }
+        this.tagStore.clear?.();
         return result;
     }
 }

package/dist/key-builder.d.ts

@@ -3,6 +3,10 @@
  *
  * Builds fully qualified cache keys from key parts, namespaces,
  * and prefixes. Ensures keys are well-formed and consistently formatted.
+ *
+ * Each part (prefix, namespace, raw key) is validated individually with a
+ * pattern that excludes the separator character, so raw keys cannot forge
+ * namespaced/prefixed keys (e.g. `build("admin:x")` throws).
  */
 import type { CacheKey, CacheKeyOptions, CacheNamespace } from "./types.js";
 import type { CacheKeyBuilder } from "./types-keys.js";
@@ -21,7 +25,18 @@ export declare class DefaultKeyBuilder implements CacheKeyBuilder {
         readonly namespace?: CacheNamespace;
     });
     build(key: string, options?: CacheKeyOptions): CacheKey;
+    /**
+     * Builds a fully-qualified glob pattern.
+     *
+     * Prefix and namespace are *identity* parts — they are the scope boundary
+     * a pattern operation must stay inside — so they are validated exactly as
+     * `build()` validates them. A namespace of `"*"` is rejected rather than
+     * silently widening the pattern to every namespace. Only the trailing
+     * pattern segment may contain `*` and `?`.
+     */
+    buildPattern(pattern: string, options?: CacheKeyOptions): string;
     namespace(namespace: CacheNamespace): CacheKeyBuilder;
+    private validatePart;
 }
 /**
  * Creates a new `DefaultKeyBuilder` with the given options.

package/dist/key-builder.js

@@ -3,9 +3,14 @@
  *
  * Builds fully qualified cache keys from key parts, namespaces,
  * and prefixes. Ensures keys are well-formed and consistently formatted.
+ *
+ * Each part (prefix, namespace, raw key) is validated individually with a
+ * pattern that excludes the separator character, so raw keys cannot forge
+ * namespaced/prefixed keys (e.g. `build("admin:x")` throws).
  */
 import { CACHE_KEY_PATTERN, DEFAULT_PREFIX, DEFAULT_SEPARATOR, MAX_KEY_LENGTH, } from "./constants.js";
 import { cacheInvalidKeyError } from "./errors.js";
+import { assertValidPatternPart } from "./utils.js";
 /* -------------------------------------------------------------------------- */
 /* Default Key Builder                                                        */
 /* -------------------------------------------------------------------------- */
@@ -27,6 +32,9 @@ export class DefaultKeyBuilder {
         const separator = options?.separator ?? this.globalSeparator;
         const namespace = options?.namespace ?? this.currentNamespace;
         const prefix = options?.prefix ?? this.globalPrefix;
+        if (key.length === 0) {
+            throw cacheInvalidKeyError(key, "Cache key must not be empty.");
+        }
         const parts = [];
         if (prefix) {
             parts.push(prefix);
@@ -35,15 +43,42 @@ export class DefaultKeyBuilder {
             parts.push(namespace);
         }
         parts.push(key);
+        for (const part of parts) {
+            this.validatePart(part, separator);
+        }
         const fullKey = parts.join(separator);
         if (fullKey.length > MAX_KEY_LENGTH) {
             throw cacheInvalidKeyError(fullKey, `Cache key exceeds maximum length of ${MAX_KEY_LENGTH} characters.`);
         }
-        if (!CACHE_KEY_PATTERN.test(fullKey)) {
-            throw cacheInvalidKeyError(fullKey);
-        }
         return fullKey;
     }
+    /**
+     * Builds a fully-qualified glob pattern.
+     *
+     * Prefix and namespace are *identity* parts — they are the scope boundary
+     * a pattern operation must stay inside — so they are validated exactly as
+     * `build()` validates them. A namespace of `"*"` is rejected rather than
+     * silently widening the pattern to every namespace. Only the trailing
+     * pattern segment may contain `*` and `?`.
+     */
+    buildPattern(pattern, options) {
+        const separator = options?.separator ?? this.globalSeparator;
+        const namespace = options?.namespace ?? this.currentNamespace;
+        const prefix = options?.prefix ?? this.globalPrefix;
+        const identityParts = [];
+        if (prefix)
+            identityParts.push(prefix);
+        if (namespace)
+            identityParts.push(namespace);
+        for (const part of identityParts)
+            this.validatePart(part, separator);
+        assertValidPatternPart(pattern, separator);
+        const fullPattern = [...identityParts, pattern].join(separator);
+        if (fullPattern.length > MAX_KEY_LENGTH) {
+            throw cacheInvalidKeyError(fullPattern, `Cache pattern exceeds maximum length of ${MAX_KEY_LENGTH} characters.`);
+        }
+        return fullPattern;
+    }
     namespace(namespace) {
         return new DefaultKeyBuilder({
             prefix: this.globalPrefix,
@@ -51,6 +86,11 @@ export class DefaultKeyBuilder {
             namespace,
         });
     }
+    validatePart(part, separator) {
+        if (part.includes(separator) || !CACHE_KEY_PATTERN.test(part)) {
+            throw cacheInvalidKeyError(part, `Invalid cache key part "${part}": parts must match ${String(CACHE_KEY_PATTERN)} and must not contain the separator "${separator}".`);
+        }
+    }
 }
 /* -------------------------------------------------------------------------- */
 /* Factory                                                                    */

package/dist/lock.d.ts

@@ -1,11 +1,24 @@
 /**
  * @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 type { CacheLock, CacheLockOptions, CacheLockStore } from "./types.js";
 export declare class InMemoryLockStore implements CacheLockStore {
     private readonly locks;
     acquire(key: string, options?: CacheLockOptions): Promise<CacheLock | null>;
+    /** Removes all expired locks. Called opportunistically on each acquire. */
+    sweepExpired(now?: number): void;
     get size(): number;
     clear(): void;
 }
@@ -18,13 +31,34 @@ export declare class CacheLockManager {
         readonly retryAttempts?: number;
         readonly retryDelayMs?: number;
     });
+    /**
+     * 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.
+     */
     acquire(key: string, options?: CacheLockOptions): Promise<CacheLock | null>;
-    withLock<T>(key: string, fn: () => Promise<T>, options?: CacheLockOptions): Promise<T>;
+    /**
+     * 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.
+     */
+    withLock<T>(key: string, fn: (signal: AbortSignal) => Promise<T>, options?: CacheLockOptions): Promise<T>;
 }
 export declare function createLockManager(options?: {
     readonly store?: CacheLockStore;
     readonly retryAttempts?: number;
     readonly retryDelayMs?: number;
 }): CacheLockManager;
+/**
+ * Process-wide lock store. Pass it as `CacheConfig.lockStore` when several
+ * `CacheService` instances in one process must share locks.
+ */
 export declare const defaultLockStore: InMemoryLockStore;
 //# sourceMappingURL=lock.d.ts.map