@zudojs/cache 0.0.1

package/dist/key-builder.js

@@ -0,0 +1,66 @@
+/**
+ * @zudojs/cache — Key Builder
+ *
+ * Builds fully qualified cache keys from key parts, namespaces,
+ * and prefixes. Ensures keys are well-formed and consistently formatted.
+ */
+import { CACHE_KEY_PATTERN, DEFAULT_PREFIX, DEFAULT_SEPARATOR, MAX_KEY_LENGTH, } from "./constants.js";
+import { cacheInvalidKeyError } from "./errors.js";
+/* -------------------------------------------------------------------------- */
+/* Default Key Builder                                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * Default implementation of the `CacheKeyBuilder` contract.
+ *
+ * Keys are built as: `[prefix:][namespace:]key`
+ */
+export class DefaultKeyBuilder {
+    globalPrefix;
+    globalSeparator;
+    currentNamespace;
+    constructor(options) {
+        this.globalPrefix = options?.prefix ?? DEFAULT_PREFIX;
+        this.globalSeparator = options?.separator ?? DEFAULT_SEPARATOR;
+        this.currentNamespace = options?.namespace;
+    }
+    build(key, options) {
+        const separator = options?.separator ?? this.globalSeparator;
+        const namespace = options?.namespace ?? this.currentNamespace;
+        const prefix = options?.prefix ?? this.globalPrefix;
+        const parts = [];
+        if (prefix) {
+            parts.push(prefix);
+        }
+        if (namespace) {
+            parts.push(namespace);
+        }
+        parts.push(key);
+        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;
+    }
+    namespace(namespace) {
+        return new DefaultKeyBuilder({
+            prefix: this.globalPrefix,
+            separator: this.globalSeparator,
+            namespace,
+        });
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Factory                                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * Creates a new `DefaultKeyBuilder` with the given options.
+ */
+export function createKeyBuilder(options) {
+    return new DefaultKeyBuilder(options);
+}
+/** Default key builder singleton. */
+export const defaultKeyBuilder = new DefaultKeyBuilder();
+//# sourceMappingURL=key-builder.js.map

package/dist/key-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-builder.js","sourceRoot":"","sources":["../src/key-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IACX,YAAY,CAAS;IACrB,eAAe,CAAS;IACxB,gBAAgB,CAAkB;IAEnD,YAAY,OAIX;QACC,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,MAAM,IAAI,cAAc,CAAC;QACtD,IAAI,CAAC,eAAe,GAAG,OAAO,EAAE,SAAS,IAAI,iBAAiB,CAAC;QAC/D,IAAI,CAAC,gBAAgB,GAAG,OAAO,EAAE,SAAS,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,OAAyB;QAC1C,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,IAAI,CAAC,eAAe,CAAC;QAC7D,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,IAAI,CAAC,gBAAgB,CAAC;QAC9D,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,IAAI,CAAC,YAAY,CAAC;QAEpD,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,IAAI,MAAM,EAAE,CAAC;YACX,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;QAED,IAAI,SAAS,EAAE,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxB,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEhB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAEtC,IAAI,OAAO,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;YACpC,MAAM,oBAAoB,CACxB,OAAO,EACP,uCAAuC,cAAc,cAAc,CACpE,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACrC,MAAM,oBAAoB,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,SAAS,CAAC,SAAyB;QACjC,OAAO,IAAI,iBAAiB,CAAC;YAC3B,MAAM,EAAE,IAAI,CAAC,YAAY;YACzB,SAAS,EAAE,IAAI,CAAC,eAAe;YAC/B,SAAS;SACV,CAAC,CAAC;IACL,CAAC;CACF;AAED,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAIhC;IACC,OAAO,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC;AAED,qCAAqC;AACrC,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,iBAAiB,EAAE,CAAC"}

package/dist/lock.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @zudojs/cache — Lock Manager
+ * Distributed lock manager for preventing concurrent cache operations.
+ */
+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>;
+    get size(): number;
+    clear(): void;
+}
+export declare class CacheLockManager {
+    private readonly store;
+    private readonly retryAttempts;
+    private readonly retryDelayMs;
+    constructor(options?: {
+        readonly store?: CacheLockStore;
+        readonly retryAttempts?: number;
+        readonly retryDelayMs?: number;
+    });
+    acquire(key: string, options?: CacheLockOptions): Promise<CacheLock | null>;
+    withLock<T>(key: string, fn: () => Promise<T>, options?: CacheLockOptions): Promise<T>;
+}
+export declare function createLockManager(options?: {
+    readonly store?: CacheLockStore;
+    readonly retryAttempts?: number;
+    readonly retryDelayMs?: number;
+}): CacheLockManager;
+export declare const defaultLockStore: InMemoryLockStore;
+//# sourceMappingURL=lock.d.ts.map

package/dist/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,cAAc,EAEf,MAAM,YAAY,CAAC;AAepB,qBAAa,iBAAkB,YAAW,cAAc;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGlB;IAEE,OAAO,CACX,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAgC3B;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IACD,KAAK,IAAI,IAAI,CAEZ;CACF;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,YAAY,OAAO,CAAC,EAAE;QACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;QAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;KAChC,EAIA;IAEK,OAAO,CACX,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAiB3B;IAEK,QAAQ,CAAC,CAAC,EACd,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,CAAC,CAAC,CAYZ;CACF;AAMD,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC,GAAG,gBAAgB,CAEnB;AAED,eAAO,MAAM,gBAAgB,mBAA0B,CAAC"}

package/dist/lock.js

@@ -0,0 +1,103 @@
+/**
+ * @zudojs/cache — Lock Manager
+ * Distributed lock manager for preventing concurrent cache operations.
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { DEFAULT_LOCK_RETRY_ATTEMPTS, DEFAULT_LOCK_RETRY_DELAY_MS, DEFAULT_LOCK_TTL_MS, } from "./constants.js";
+import { CacheError, CacheOperation } from "./errors.js";
+function generateToken() {
+    if (typeof randomUUID === "function") {
+        return randomUUID();
+    }
+    return randomBytes(16).toString("hex");
+}
+export class InMemoryLockStore {
+    locks = new Map();
+    async acquire(key, options) {
+        const ttl = options?.ttl ?? DEFAULT_LOCK_TTL_MS;
+        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))
+            return null;
+        this.locks.set(key, { token, expiresAt });
+        return {
+            key,
+            token,
+            acquiredAt: new Date(now),
+            expiresAt: new Date(expiresAt),
+            release: async () => {
+                const current = this.locks.get(key);
+                if (current && current.token === token) {
+                    this.locks.delete(key);
+                    return true;
+                }
+                return false;
+            },
+            extend: async (newTtl) => {
+                const current = this.locks.get(key);
+                if (current && current.token === token) {
+                    this.locks.set(key, { ...current, expiresAt: Date.now() + newTtl });
+                    return true;
+                }
+                return false;
+            },
+        };
+    }
+    get size() {
+        return this.locks.size;
+    }
+    clear() {
+        this.locks.clear();
+    }
+}
+export class CacheLockManager {
+    store;
+    retryAttempts;
+    retryDelayMs;
+    constructor(options) {
+        this.store = options?.store ?? new InMemoryLockStore();
+        this.retryAttempts = options?.retryAttempts ?? DEFAULT_LOCK_RETRY_ATTEMPTS;
+        this.retryDelayMs = options?.retryDelayMs ?? DEFAULT_LOCK_RETRY_DELAY_MS;
+    }
+    async acquire(key, options) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.retryAttempts; attempt++) {
+            try {
+                const lock = await this.store.acquire(key, options);
+                if (lock)
+                    return lock;
+            }
+            catch (error) {
+                lastError = error;
+            }
+            if (attempt < this.retryAttempts)
+                await sleep(this.retryDelayMs);
+        }
+        if (lastError)
+            throw new CacheError(`Failed to acquire lock "${key}" after ${this.retryAttempts} retries.`, { cause: lastError, operation: CacheOperation.LOCK_ACQUIRE, key });
+        return null;
+    }
+    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 });
+        try {
+            return await fn();
+        }
+        finally {
+            await lock.release();
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function createLockManager(options) {
+    return new CacheLockManager(options);
+}
+export const defaultLockStore = new InMemoryLockStore();
+//# sourceMappingURL=lock.js.map

package/dist/lock.js.map

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

package/dist/memory.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @zudojs/cache — Memory Adapter
+ * In-memory cache adapter using a Map. Suitable for development, testing, and single-process deployments.
+ */
+import type { CacheAdapter, CacheClearOptions, CacheClearResult, CacheDeleteResult, CacheGetResult, CacheKeysOptions, CacheSetManyOptions, CacheSetOptions, CacheSetResult, CacheTTL } from "./types.js";
+export declare class MemoryCacheAdapter implements CacheAdapter {
+    readonly name = "memory";
+    private readonly store;
+    private readonly maxEntries;
+    private readonly defaultTtl;
+    constructor(options?: {
+        readonly maxEntries?: number;
+        readonly defaultTtl?: CacheTTL;
+    });
+    get<TValue = unknown>(key: string): Promise<CacheGetResult<TValue>>;
+    set<TValue = unknown>(key: string, value: TValue, options?: CacheSetOptions): Promise<CacheSetResult>;
+    delete(key: string): Promise<CacheDeleteResult>;
+    has(key: string): Promise<boolean>;
+    clear(options?: CacheClearOptions): Promise<CacheClearResult>;
+    keys(options?: CacheKeysOptions): Promise<readonly string[]>;
+    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>;
+    expire(key: string, ttl: CacheTTL): Promise<boolean>;
+    private isExpired;
+    private evictIfNeeded;
+    private patternToRegex;
+}
+export declare function createMemoryCacheAdapter(options?: {
+    readonly maxEntries?: number;
+    readonly defaultTtl?: CacheTTL;
+}): MemoryCacheAdapter;
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAEhB,iBAAiB,EAGjB,cAAc,EAEd,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,QAAQ,EACT,MAAM,YAAY,CAAC;AAWpB,qBAAa,kBAAmB,YAAW,YAAY;IACrD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAW;IAEtC,YAAY,OAAO,CAAC,EAAE;QACpB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC;KAChC,EAGA;IAEK,GAAG,CAAC,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAQxE;IAEK,GAAG,CAAC,MAAM,GAAG,OAAO,EACxB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CAgBzB;IAEK,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAIpD;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvC;IAEK,KAAK,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAelE;IAEK,IAAI,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CASjE;IAEK,OAAO,CAAC,MAAM,GAAG,OAAO,EAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAItD;IAEK,OAAO,CAAC,MAAM,GAAG,OAAO,EAC5B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAKpC;IAEK,UAAU,CACd,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAWzE;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAK7C;IAEK,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAKzD;IAED,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,cAAc;CAKvB;AAED,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC;CAChC,GAAG,kBAAkB,CAErB"}

package/dist/memory.js

@@ -0,0 +1,140 @@
+/**
+ * @zudojs/cache — Memory Adapter
+ * In-memory cache adapter using a Map. Suitable for development, testing, and single-process deployments.
+ */
+import { DEFAULT_MAX_ENTRIES, DEFAULT_TTL_MS } from "./constants.js";
+export class MemoryCacheAdapter {
+    name = "memory";
+    store = new Map();
+    maxEntries;
+    defaultTtl;
+    constructor(options) {
+        this.maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.defaultTtl = options?.defaultTtl ?? DEFAULT_TTL_MS;
+    }
+    async get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return { hit: false, value: null };
+        if (this.isExpired(entry)) {
+            this.store.delete(key);
+            return { hit: false, value: null };
+        }
+        return { hit: true, value: entry.value };
+    }
+    async set(key, value, options) {
+        this.evictIfNeeded();
+        const ttl = options?.ttl ?? this.defaultTtl;
+        const now = Date.now();
+        this.store.set(key, {
+            value,
+            createdAt: now,
+            expiresAt: ttl !== null ? now + ttl : null,
+            tags: options?.tags ?? [],
+            metadata: options?.metadata ?? {},
+        });
+        return {
+            success: true,
+            key,
+            expiresAt: ttl !== null ? new Date(now + ttl) : null,
+        };
+    }
+    async delete(key) {
+        const existed = this.store.has(key);
+        this.store.delete(key);
+        return { deleted: existed, key };
+    }
+    async has(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return false;
+        if (this.isExpired(entry)) {
+            this.store.delete(key);
+            return false;
+        }
+        return true;
+    }
+    async clear(options) {
+        if (!options?.pattern) {
+            const size = this.store.size;
+            this.store.clear();
+            return { cleared: size };
+        }
+        let cleared = 0;
+        const regex = this.patternToRegex(options.pattern);
+        for (const key of [...this.store.keys()]) {
+            if (regex.test(key)) {
+                this.store.delete(key);
+                cleared++;
+            }
+        }
+        return { cleared };
+    }
+    async keys(options) {
+        let filtered = [...this.store.keys()];
+        if (options?.pattern) {
+            const regex = this.patternToRegex(options.pattern);
+            filtered = filtered.filter((k) => regex.test(k));
+        }
+        if (options?.limit !== undefined)
+            filtered = filtered.slice(0, options.limit);
+        return filtered;
+    }
+    async getMany(keys) {
+        const results = new Map();
+        for (const key of keys)
+            results.set(key, await this.get(key));
+        return results;
+    }
+    async setMany(entries, options) {
+        const results = [];
+        for (const [key, value] of entries)
+            results.push(await this.set(key, value, options));
+        return results;
+    }
+    async deleteMany(keys) {
+        let deleted = 0;
+        const deletedKeys = [];
+        for (const key of keys) {
+            const result = await this.delete(key);
+            if (result.deleted) {
+                deleted++;
+                deletedKeys.push(key);
+            }
+        }
+        return { deleted, keys: deletedKeys };
+    }
+    async ttl(key) {
+        const entry = this.store.get(key);
+        if (!entry || entry.expiresAt === null)
+            return null;
+        const remaining = entry.expiresAt - Date.now();
+        return remaining > 0 ? remaining : null;
+    }
+    async expire(key, ttl) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return false;
+        this.store.set(key, { ...entry, expiresAt: Date.now() + ttl });
+        return true;
+    }
+    isExpired(entry) {
+        return entry.expiresAt !== null && Date.now() > entry.expiresAt;
+    }
+    evictIfNeeded() {
+        if (this.store.size >= this.maxEntries) {
+            const firstKey = this.store.keys().next().value;
+            if (firstKey !== undefined)
+                this.store.delete(firstKey);
+        }
+    }
+    patternToRegex(pattern) {
+        const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const regexStr = escaped.replace(/\\\*/g, ".*").replace(/\\\?/g, ".");
+        return new RegExp(`^${regexStr}$`);
+    }
+}
+export function createMemoryCacheAdapter(options) {
+    return new MemoryCacheAdapter(options);
+}
+//# sourceMappingURL=memory.js.map

package/dist/memory.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @zudojs/cache — Metrics
+ * Tracks cache operation metrics including hit/miss ratios, latency histograms, and error counts.
+ */
+import type { CacheKey, CacheMetrics, CacheOperation, CacheStats } from "./types.js";
+export declare class InMemoryCacheMetrics implements CacheMetrics {
+    private hits;
+    private misses;
+    private sets;
+    private deletes;
+    private errors;
+    private readonly keyHits;
+    private readonly latencies;
+    incrementHit(key?: CacheKey): void;
+    incrementMiss(_key?: CacheKey): void;
+    incrementSet(_key?: CacheKey): void;
+    incrementDelete(_key?: CacheKey): void;
+    incrementError(_key?: CacheKey): void;
+    observeLatency(operation: CacheOperation, latencyMs: number): void;
+    getStats(): CacheStats;
+    getLatencyStats(operation: CacheOperation): {
+        readonly count: number;
+        readonly min: number;
+        readonly max: number;
+        readonly mean: number;
+        readonly p50: number;
+        readonly p95: number;
+        readonly p99: number;
+    };
+    getHotKeys(topN?: number): readonly {
+        readonly key: CacheKey;
+        readonly hits: number;
+    }[];
+    getLatencyHistogram(operation: CacheOperation): readonly {
+        readonly bucket: number;
+        readonly count: number;
+    }[];
+    reset(): void;
+}
+export declare function createCacheMetrics(): InMemoryCacheMetrics;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,UAAU,EACX,MAAM,YAAY,CAAC;AAGpB,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IAEjE,YAAY,CAAC,GAAG,CAAC,EAAE,QAAQ,GAAG,IAAI,CAGjC;IACD,aAAa,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAEnC;IACD,YAAY,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAElC;IACD,eAAe,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAErC;IACD,cAAc,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAEpC;IAED,cAAc,CAAC,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAMjE;IAED,QAAQ,IAAI,UAAU,CAUrB;IAED,eAAe,CAAC,SAAS,EAAE,cAAc,GAAG;QAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;KACtB,CAgBA;IAED,UAAU,CACR,IAAI,SAAK,GACR,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAK9D;IAED,mBAAmB,CACjB,SAAS,EAAE,cAAc,GACxB,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAMhE;IAED,KAAK,IAAI,IAAI,CAQZ;CACF;AAOD,wBAAgB,kBAAkB,IAAI,oBAAoB,CAEzD"}

package/dist/metrics.js

@@ -0,0 +1,96 @@
+/**
+ * @zudojs/cache — Metrics
+ * Tracks cache operation metrics including hit/miss ratios, latency histograms, and error counts.
+ */
+import { LATENCY_BUCKETS, MAX_LATENCY_SAMPLES } from "./constants.js";
+export class InMemoryCacheMetrics {
+    hits = 0;
+    misses = 0;
+    sets = 0;
+    deletes = 0;
+    errors = 0;
+    keyHits = new Map();
+    latencies = new Map();
+    incrementHit(key) {
+        this.hits++;
+        if (key)
+            this.keyHits.set(key, (this.keyHits.get(key) ?? 0) + 1);
+    }
+    incrementMiss(_key) {
+        this.misses++;
+    }
+    incrementSet(_key) {
+        this.sets++;
+    }
+    incrementDelete(_key) {
+        this.deletes++;
+    }
+    incrementError(_key) {
+        this.errors++;
+    }
+    observeLatency(operation, latencyMs) {
+        if (!this.latencies.has(operation))
+            this.latencies.set(operation, []);
+        const samples = this.latencies.get(operation);
+        samples.push(latencyMs);
+        if (samples.length > MAX_LATENCY_SAMPLES)
+            samples.splice(0, samples.length - MAX_LATENCY_SAMPLES);
+    }
+    getStats() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            sets: this.sets,
+            deletes: this.deletes,
+            errors: this.errors,
+            hitRate: total > 0 ? this.hits / total : 0,
+        };
+    }
+    getLatencyStats(operation) {
+        const samples = [...(this.latencies.get(operation) ?? [])].sort((a, b) => a - b);
+        if (samples.length === 0)
+            return { count: 0, min: 0, max: 0, mean: 0, p50: 0, p95: 0, p99: 0 };
+        const sum = samples.reduce((a, b) => a + b, 0);
+        return {
+            count: samples.length,
+            min: samples[0],
+            max: samples[samples.length - 1],
+            mean: sum / samples.length,
+            p50: percentile(samples, 50),
+            p95: percentile(samples, 95),
+            p99: percentile(samples, 99),
+        };
+    }
+    getHotKeys(topN = 10) {
+        return [...this.keyHits.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, topN)
+            .map(([key, hits]) => ({ key, hits }));
+    }
+    getLatencyHistogram(operation) {
+        const samples = this.latencies.get(operation) ?? [];
+        return LATENCY_BUCKETS.map((boundary) => ({
+            bucket: boundary,
+            count: samples.filter((s) => s <= boundary).length,
+        }));
+    }
+    reset() {
+        this.hits = 0;
+        this.misses = 0;
+        this.sets = 0;
+        this.deletes = 0;
+        this.errors = 0;
+        this.keyHits.clear();
+        this.latencies.clear();
+    }
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    return sorted[Math.max(0, Math.ceil((p / 100) * sorted.length) - 1)];
+}
+export function createCacheMetrics() {
+    return new InMemoryCacheMetrics();
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

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

package/dist/serializer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @zudojs/cache — Serializer
+ *
+ * Provides serializer implementations for converting cache values
+ * to and from storable representations. Delegates to @zudojs/serialization
+ * for the actual JSON serialization with type preservation.
+ */
+import type { CacheSerializer } from "./types.js";
+/**
+ * Serializes values to JSON strings and deserializes them back.
+ *
+ * Uses @zudojs/serialization's JSONSerializer for type preservation
+ * (Date, BigInt, Map, Set, Uint8Array) when configured.
+ */
+export declare class JsonCacheSerializer implements CacheSerializer<unknown, string> {
+    private readonly inner;
+    private readonly preserveTypes;
+    constructor(options?: {
+        readonly preserveTypes?: boolean;
+    });
+    serialize(value: unknown): string;
+    deserialize(value: string): unknown;
+}
+/**
+ * Pass-through serializer for values that are already in
+ * their storable form (e.g., strings, numbers).
+ */
+export declare class RawCacheSerializer implements CacheSerializer<unknown, unknown> {
+    serialize(value: unknown): unknown;
+    deserialize(value: unknown): unknown;
+}
+/** Default JSON serializer instance. */
+export declare const defaultSerializer: JsonCacheSerializer;
+/** Default raw (pass-through) serializer instance. */
+export declare const rawSerializer: RawCacheSerializer;
+/**
+ * Returns the appropriate serializer for the given value type.
+ *
+ * - Objects, arrays, dates → JSON serializer
+ * - Strings, numbers, booleans, null → raw serializer
+ */
+export declare function getSerializer(value: unknown): CacheSerializer<unknown, unknown>;
+//# sourceMappingURL=serializer.d.ts.map

package/dist/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAOlD;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IAExC,YAAY,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,EAGzD;IAED,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIhC;IAED,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIlC;CACF;AAMD;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1E,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEjC;IAED,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEnC;CACF;AAMD,wCAAwC;AACxC,eAAO,MAAM,iBAAiB,qBAA4B,CAAC;AAE3D,sDAAsD;AACtD,eAAO,MAAM,aAAa,oBAA2B,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,GACb,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAYnC"}