@zudojs/cache 0.1.0 → 1.0.0

package/dist/memory.js

@@ -1,47 +1,154 @@
 /**
  * @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 { DEFAULT_MAX_ENTRIES, DEFAULT_TTL_MS } from "./constants.js";
+import { DEFAULT_MAX_ENTRIES, DEFAULT_MAX_MEMORY_BYTES, DEFAULT_SEPARATOR, DEFAULT_TTL_MS, EXPIRED_PURGE_INTERVAL_MS, SIZE_ESTIMATE_NODE_BUDGET, } from "./constants.js";
+import { assertValidTtl, createGlobMatcher, deleteManyViaDelete, monotonicNow, wallClockFor, } from "./utils.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 function estimateValueBytes(value) {
+    let budget = SIZE_ESTIMATE_NODE_BUDGET;
+    const seen = new Set();
+    const walk = (node) => {
+        if (budget <= 0)
+            return 16;
+        budget--;
+        switch (typeof node) {
+            case "string":
+                return 16 + node.length * 2;
+            case "number":
+                return 8;
+            case "boolean":
+                return 4;
+            case "bigint":
+                return 16;
+            case "undefined":
+                return 0;
+            case "function":
+                return 32;
+            default:
+                break;
+        }
+        if (node === null)
+            return 0;
+        const obj = node;
+        if (seen.has(obj))
+            return 0;
+        seen.add(obj);
+        if (ArrayBuffer.isView(obj))
+            return 16 + obj.byteLength;
+        if (obj instanceof ArrayBuffer)
+            return 16 + obj.byteLength;
+        if (obj instanceof Date)
+            return 16;
+        if (Array.isArray(obj)) {
+            let total = 16;
+            for (const item of obj)
+                total += walk(item);
+            return total;
+        }
+        if (obj instanceof Map) {
+            let total = 16;
+            for (const [k, v] of obj)
+                total += walk(k) + walk(v);
+            return total;
+        }
+        if (obj instanceof Set) {
+            let total = 16;
+            for (const item of obj)
+                total += walk(item);
+            return total;
+        }
+        let total = 16;
+        for (const [k, v] of Object.entries(obj))
+            total += 16 + k.length * 2 + walk(v);
+        return total;
+    };
+    return walk(value);
+}
 export class MemoryCacheAdapter {
     name = "memory";
     store = new Map();
     maxEntries;
+    maxBytes;
     defaultTtl;
+    separator;
+    bytesUsed = 0;
+    lastPurgeAt = monotonicNow();
     constructor(options) {
         this.maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.maxBytes = options?.maxBytes ?? DEFAULT_MAX_MEMORY_BYTES;
         this.defaultTtl = options?.defaultTtl ?? DEFAULT_TTL_MS;
+        this.separator = options?.separator ?? DEFAULT_SEPARATOR;
     }
     async get(key) {
         const entry = this.store.get(key);
         if (!entry)
             return { hit: false, value: null };
         if (this.isExpired(entry)) {
-            this.store.delete(key);
+            this.remove(key);
             return { hit: false, value: null };
         }
-        return { hit: true, value: entry.value };
+        // LRU: a read moves the entry to the back of the eviction queue, so the
+        // hottest key is not evicted merely for being the oldest write.
+        this.store.delete(key);
+        this.store.set(key, entry);
+        return {
+            hit: true,
+            value: entry.value,
+            entry: this.toCacheEntry(key, entry),
+        };
     }
     async set(key, value, options) {
-        this.evictIfNeeded();
-        const ttl = options?.ttl ?? this.defaultTtl;
-        const now = Date.now();
+        const ttl = options?.ttl !== undefined ? options.ttl : this.defaultTtl;
+        assertValidTtl(ttl);
+        if (options?.overwrite === false && (await this.has(key))) {
+            return { success: false, key, expiresAt: null, skipped: true };
+        }
+        const now = monotonicNow();
+        const bytes = estimateValueBytes(value) + key.length * 2;
+        // The opportunistic purge runs on the overwrite path too — time-gated,
+        // so re-setting hot keys stays cheap while dead entries elsewhere in the
+        // store still get collected. Overwriting releases the old entry's budget
+        // first, so it never counts twice.
+        this.maybePurgeExpired(now);
+        if (this.store.has(key))
+            this.remove(key);
+        this.evictIfNeeded(bytes);
         this.store.set(key, {
             value,
             createdAt: now,
             expiresAt: ttl !== null ? now + ttl : null,
             tags: options?.tags ?? [],
             metadata: options?.metadata ?? {},
+            bytes,
         });
+        this.bytesUsed += bytes;
         return {
             success: true,
             key,
-            expiresAt: ttl !== null ? new Date(now + ttl) : null,
+            expiresAt: ttl !== null ? wallClockFor(now + ttl) : null,
         };
     }
     async delete(key) {
         const existed = this.store.has(key);
-        this.store.delete(key);
+        this.remove(key);
         return { deleted: existed, key };
     }
     async has(key) {
@@ -49,7 +156,7 @@ export class MemoryCacheAdapter {
         if (!entry)
             return false;
         if (this.isExpired(entry)) {
-            this.store.delete(key);
+            this.remove(key);
             return false;
         }
         return true;
@@ -58,28 +165,49 @@ export class MemoryCacheAdapter {
         if (!options?.pattern) {
             const size = this.store.size;
             this.store.clear();
+            this.bytesUsed = 0;
             return { cleared: size };
         }
         let cleared = 0;
-        const regex = this.patternToRegex(options.pattern);
+        const matches = createGlobMatcher(options.pattern, {
+            separator: this.separator,
+        });
         for (const key of [...this.store.keys()]) {
-            if (regex.test(key)) {
-                this.store.delete(key);
+            if (matches(key)) {
+                this.remove(key);
                 cleared++;
             }
         }
         return { cleared };
     }
     async keys(options) {
-        let filtered = [...this.store.keys()];
+        let filtered = [];
+        for (const [key, entry] of [...this.store]) {
+            if (this.isExpired(entry)) {
+                this.remove(key);
+                continue;
+            }
+            filtered.push(key);
+        }
         if (options?.pattern) {
-            const regex = this.patternToRegex(options.pattern);
-            filtered = filtered.filter((k) => regex.test(k));
+            const matches = createGlobMatcher(options.pattern, {
+                separator: this.separator,
+            });
+            filtered = filtered.filter(matches);
         }
         if (options?.limit !== undefined)
             filtered = filtered.slice(0, options.limit);
         return filtered;
     }
+    /** Number of live entries currently held. */
+    async size() {
+        this.purgeExpired();
+        return this.store.size;
+    }
+    /** Estimated bytes currently retained by cached values. */
+    get estimatedBytes() {
+        return this.bytesUsed;
+    }
     async getMany(keys) {
         const results = new Map();
         for (const key of keys)
@@ -93,45 +221,101 @@ export class MemoryCacheAdapter {
         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 };
+        return deleteManyViaDelete(keys, (key) => this.delete(key));
     }
+    /**
+     * 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
+     */
     async ttl(key) {
         const entry = this.store.get(key);
-        if (!entry || entry.expiresAt === null)
+        if (!entry)
+            return undefined;
+        if (this.isExpired(entry)) {
+            this.remove(key);
+            return undefined;
+        }
+        if (entry.expiresAt === null)
             return null;
-        const remaining = entry.expiresAt - Date.now();
-        return remaining > 0 ? remaining : null;
+        return entry.expiresAt - monotonicNow();
     }
     async expire(key, ttl) {
+        assertValidTtl(ttl);
         const entry = this.store.get(key);
         if (!entry)
             return false;
-        this.store.set(key, { ...entry, expiresAt: Date.now() + ttl });
+        if (this.isExpired(entry)) {
+            this.remove(key);
+            return false;
+        }
+        entry.expiresAt = ttl !== null ? monotonicNow() + ttl : null;
         return true;
     }
+    /* ---- Internals ---- */
+    toCacheEntry(key, entry) {
+        return {
+            key,
+            value: entry.value,
+            createdAt: wallClockFor(entry.createdAt),
+            expiresAt: entry.expiresAt !== null ? wallClockFor(entry.expiresAt) : null,
+            tags: entry.tags,
+            metadata: entry.metadata,
+        };
+    }
+    /**
+     * An entry is dead *at* its deadline, not one millisecond after it, so
+     * `ttl(key) === 0` and "present" are never both true.
+     */
     isExpired(entry) {
-        return entry.expiresAt !== null && Date.now() > entry.expiresAt;
+        return entry.expiresAt !== null && monotonicNow() >= entry.expiresAt;
     }
-    evictIfNeeded() {
-        if (this.store.size >= this.maxEntries) {
-            const firstKey = this.store.keys().next().value;
-            if (firstKey !== undefined)
-                this.store.delete(firstKey);
+    remove(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return;
+        this.store.delete(key);
+        this.bytesUsed -= entry.bytes;
+        if (this.bytesUsed < 0)
+            this.bytesUsed = 0;
+    }
+    purgeExpired() {
+        for (const [key, entry] of [...this.store]) {
+            if (this.isExpired(entry))
+                this.remove(key);
         }
+        this.lastPurgeAt = monotonicNow();
+    }
+    maybePurgeExpired(now) {
+        if (now - this.lastPurgeAt < EXPIRED_PURGE_INTERVAL_MS)
+            return;
+        this.purgeExpired();
     }
-    patternToRegex(pattern) {
-        const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        const regexStr = escaped.replace(/\\\*/g, ".*").replace(/\\\?/g, ".");
-        return new RegExp(`^${regexStr}$`);
+    /**
+     * 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.
+     */
+    evictIfNeeded(incomingBytes) {
+        const overCount = this.store.size >= this.maxEntries;
+        const overBytes = this.bytesUsed + incomingBytes > this.maxBytes;
+        if (!overCount && !overBytes)
+            return;
+        this.purgeExpired();
+        while (this.store.size >= this.maxEntries) {
+            const lru = this.store.keys().next().value;
+            if (lru === undefined)
+                break;
+            this.remove(lru);
+        }
+        while (this.bytesUsed + incomingBytes > this.maxBytes &&
+            this.store.size > 0) {
+            const lru = this.store.keys().next().value;
+            if (lru === undefined)
+                break;
+            this.remove(lru);
+        }
     }
 }
 export function createMemoryCacheAdapter(options) {

package/dist/metrics.d.ts

@@ -12,6 +12,11 @@ export declare class InMemoryCacheMetrics implements CacheMetrics {
     private readonly keyHits;
     private readonly latencies;
     incrementHit(key?: CacheKey): void;
+    /**
+     * Removes the least-hit tracked key and returns its count. Ties are
+     * broken by insertion order, so the oldest of the coldest goes first.
+     */
+    private evictColdestKey;
     incrementMiss(_key?: CacheKey): void;
     incrementSet(_key?: CacheKey): void;
     incrementDelete(_key?: CacheKey): void;
@@ -27,6 +32,11 @@ export declare class InMemoryCacheMetrics implements CacheMetrics {
         readonly p95: number;
         readonly p99: number;
     };
+    /**
+     * The most-read keys currently tracked, hottest first. The tracked set is
+     * bounded by MAX_TRACKED_KEYS and evicts its coldest member, so the
+     * ranking follows the live workload rather than freezing at start-up.
+     */
     getHotKeys(topN?: number): readonly {
         readonly key: CacheKey;
         readonly hits: number;

package/dist/metrics.js

@@ -2,7 +2,7 @@
  * @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";
+import { LATENCY_BUCKETS, MAX_LATENCY_SAMPLES, MAX_TRACKED_KEYS, } from "./constants.js";
 export class InMemoryCacheMetrics {
     hits = 0;
     misses = 0;
@@ -13,8 +13,43 @@ export class InMemoryCacheMetrics {
     latencies = new Map();
     incrementHit(key) {
         this.hits++;
-        if (key)
-            this.keyHits.set(key, (this.keyHits.get(key) ?? 0) + 1);
+        if (!key)
+            return;
+        const current = this.keyHits.get(key);
+        if (current !== undefined) {
+            this.keyHits.set(key, current + 1);
+            return;
+        }
+        // The tracked-key cap is an eviction policy, not a wall. A hard stop
+        // would freeze `getHotKeys()` on the first MAX_TRACKED_KEYS keys the
+        // process ever saw, so it would answer "what was hot at start-up" while
+        // looking live. Instead the coldest tracked key is evicted, and the new
+        // key inherits its count so it is not immediately evicted in turn and
+        // can climb the ranking if it really is hot.
+        if (this.keyHits.size >= MAX_TRACKED_KEYS) {
+            const coldest = this.evictColdestKey();
+            this.keyHits.set(key, coldest + 1);
+            return;
+        }
+        this.keyHits.set(key, 1);
+    }
+    /**
+     * Removes the least-hit tracked key and returns its count. Ties are
+     * broken by insertion order, so the oldest of the coldest goes first.
+     */
+    evictColdestKey() {
+        let coldestKey;
+        let coldestHits = Number.POSITIVE_INFINITY;
+        for (const [key, hits] of this.keyHits) {
+            if (hits < coldestHits) {
+                coldestHits = hits;
+                coldestKey = key;
+            }
+        }
+        if (coldestKey === undefined)
+            return 0;
+        this.keyHits.delete(coldestKey);
+        return coldestHits;
     }
     incrementMiss(_key) {
         this.misses++;
@@ -62,6 +97,11 @@ export class InMemoryCacheMetrics {
             p99: percentile(samples, 99),
         };
     }
+    /**
+     * The most-read keys currently tracked, hottest first. The tracked set is
+     * bounded by MAX_TRACKED_KEYS and evicts its coldest member, so the
+     * ranking follows the live workload rather than freezing at start-up.
+     */
     getHotKeys(topN = 10) {
         return [...this.keyHits.entries()]
             .sort((a, b) => b[1] - a[1])
@@ -70,7 +110,12 @@ export class InMemoryCacheMetrics {
     }
     getLatencyHistogram(operation) {
         const samples = this.latencies.get(operation) ?? [];
-        return LATENCY_BUCKETS.map((boundary) => ({
+        // A +Infinity bucket captures samples above the largest finite boundary.
+        const boundaries = [
+            ...LATENCY_BUCKETS,
+            Number.POSITIVE_INFINITY,
+        ];
+        return boundaries.map((boundary) => ({
             bucket: boundary,
             count: samples.filter((s) => s <= boundary).length,
         }));

package/dist/serializer.d.ts

@@ -6,11 +6,27 @@
  * for the actual JSON serialization with type preservation.
  */
 import type { CacheSerializer } from "./types.js";
+/**
+ * Strips prototype-polluting own keys from a freshly deserialized value.
+ *
+ * This is defence in depth at the trust boundary: a cached payload can come
+ * from a shared backing store, a restored backup, or another writer, so the
+ * bytes are not necessarily ones this process serialized. `@zudojs/errors`'
+ * sibling `@zudojs/serialization` accepts an `allowUnsafeKeys` option but
+ * the published build does not implement it, and `JSON.parse` leaves
+ * `__proto__` as a genuine own property — which re-triggers the setter on
+ * any later spread or `Object.assign`. Both routes are closed here.
+ */
+export declare function stripUnsafeKeys<T>(value: T): T;
 /**
  * Serializes values to JSON strings and deserializes them back.
  *
- * Uses @zudojs/serialization's JSONSerializer for type preservation
- * (Date, BigInt, Map, Set, Uint8Array) when configured.
+ * Preserves special types (Date, BigInt, Map, Set, Uint8Array) by default —
+ * round-trip fidelity is the point of a cache, and a silently lossy default
+ * turns `set(k, { at: new Date() })` into a string on the way back out. Pass
+ * `{ preserveTypes: false }` for plain JSON semantics.
+ *
+ * Deserialization is hardened against prototype-polluting keys.
  */
 export declare class JsonCacheSerializer implements CacheSerializer<unknown, string> {
     private readonly inner;
@@ -29,15 +45,8 @@ export declare class RawCacheSerializer implements CacheSerializer<unknown, unkn
     serialize(value: unknown): unknown;
     deserialize(value: unknown): unknown;
 }
-/** Default JSON serializer instance. */
+/** Default JSON serializer instance (type-preserving). */
 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.js

@@ -7,19 +7,97 @@
  */
 import { JSONSerializer } from "@zudojs/serialization";
 /* -------------------------------------------------------------------------- */
+/* Prototype-pollution hardening                                              */
+/* -------------------------------------------------------------------------- */
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Strips prototype-polluting own keys from a freshly deserialized value.
+ *
+ * This is defence in depth at the trust boundary: a cached payload can come
+ * from a shared backing store, a restored backup, or another writer, so the
+ * bytes are not necessarily ones this process serialized. `@zudojs/errors`'
+ * sibling `@zudojs/serialization` accepts an `allowUnsafeKeys` option but
+ * the published build does not implement it, and `JSON.parse` leaves
+ * `__proto__` as a genuine own property — which re-triggers the setter on
+ * any later spread or `Object.assign`. Both routes are closed here.
+ */
+export function stripUnsafeKeys(value) {
+    const seen = new Set();
+    const walk = (node) => {
+        if (node === null || typeof node !== "object")
+            return;
+        const obj = node;
+        if (seen.has(obj))
+            return;
+        seen.add(obj);
+        if (Array.isArray(obj)) {
+            for (const item of obj)
+                walk(item);
+            return;
+        }
+        if (obj instanceof Map) {
+            for (const entry of obj.values())
+                walk(entry);
+            return;
+        }
+        if (obj instanceof Set) {
+            for (const entry of obj)
+                walk(entry);
+            return;
+        }
+        for (const key of Object.getOwnPropertyNames(obj)) {
+            if (UNSAFE_KEYS.has(key)) {
+                Reflect.deleteProperty(obj, key);
+                continue;
+            }
+            walk(obj[key]);
+        }
+        // A hijacked prototype survives key deletion, so reset it too.
+        if (Object.getPrototypeOf(obj) !== Object.prototype && isPlainish(obj)) {
+            Object.setPrototypeOf(obj, Object.prototype);
+        }
+    };
+    walk(value);
+    return value;
+}
+/**
+ * True when an object is a plain data container whose prototype should be
+ * `Object.prototype` — i.e. not a Date/Map/Set/typed array/class instance we
+ * deliberately reconstructed.
+ */
+function isPlainish(obj) {
+    if (obj instanceof Date ||
+        obj instanceof Map ||
+        obj instanceof Set ||
+        obj instanceof RegExp ||
+        obj instanceof Error ||
+        ArrayBuffer.isView(obj) ||
+        obj instanceof ArrayBuffer) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(obj);
+    // Only a null prototype or a foreign literal object indicates tampering;
+    // anything with a real constructor is left alone.
+    return proto === null || proto.constructor === Object;
+}
+/* -------------------------------------------------------------------------- */
 /* JSON Serializer                                                            */
 /* -------------------------------------------------------------------------- */
 /**
  * Serializes values to JSON strings and deserializes them back.
  *
- * Uses @zudojs/serialization's JSONSerializer for type preservation
- * (Date, BigInt, Map, Set, Uint8Array) when configured.
+ * Preserves special types (Date, BigInt, Map, Set, Uint8Array) by default —
+ * round-trip fidelity is the point of a cache, and a silently lossy default
+ * turns `set(k, { at: new Date() })` into a string on the way back out. Pass
+ * `{ preserveTypes: false }` for plain JSON semantics.
+ *
+ * Deserialization is hardened against prototype-polluting keys.
  */
 export class JsonCacheSerializer {
     inner;
     preserveTypes;
     constructor(options) {
-        this.preserveTypes = options?.preserveTypes ?? false;
+        this.preserveTypes = options?.preserveTypes ?? true;
         this.inner = new JSONSerializer();
     }
     serialize(value) {
@@ -28,9 +106,14 @@ export class JsonCacheSerializer {
         });
     }
     deserialize(value) {
-        return this.inner.deserialize(value, {
+        const parsed = this.inner.deserialize(value, {
             preserveTypes: this.preserveTypes,
+            // Stated at the call site even though the published sibling build
+            // ignores them; `stripUnsafeKeys` enforces the intent regardless.
+            strict: true,
+            allowUnsafeKeys: false,
         });
+        return stripUnsafeKeys(parsed);
     }
 }
 /* -------------------------------------------------------------------------- */
@@ -51,24 +134,8 @@ export class RawCacheSerializer {
 /* -------------------------------------------------------------------------- */
 /* Default Singleton                                                          */
 /* -------------------------------------------------------------------------- */
-/** Default JSON serializer instance. */
+/** Default JSON serializer instance (type-preserving). */
 export const defaultSerializer = new JsonCacheSerializer();
 /** Default raw (pass-through) serializer instance. */
 export const rawSerializer = new RawCacheSerializer();
-/**
- * Returns the appropriate serializer for the given value type.
- *
- * - Objects, arrays, dates → JSON serializer
- * - Strings, numbers, booleans, null → raw serializer
- */
-export function getSerializer(value) {
-    if (value === null ||
-        value === undefined ||
-        typeof value === "string" ||
-        typeof value === "number" ||
-        typeof value === "boolean") {
-        return rawSerializer;
-    }
-    return defaultSerializer;
-}
 //# sourceMappingURL=serializer.js.map