@ultimat3/cache 25.0.0 → 25.2.0

package/CLAUDE.md

@@ -95,6 +95,10 @@ Tier 1. Tagged caching + THE invalidation graph.
   collection bust and `t:{entity}:<id>` + `t:{entity}` for a row one. A row bust still `SREM`s what
   it deleted from the index (`sweepBucketsFor`). Pinned by `tier-parity.test.ts` and
   `redis.live.test.ts`.
+- **Every tier stores codec TEXT, never the caller's object** (`value-codec.ts`: JSON + tagged
+  `Date`/`bigint`/`Map`/`Set`, app `$x` keys escaped). One shape whichever tier hit, no shared
+  mutable reference; a cycle, depth > 512 or a bigint > 4096 chars is `X_CACHE_VALUE_UNENCODABLE`
+  at the write. Only `x1:`-marked text is revived; unmarked (pre-codec) is plain `JSON.parse`.
 - **`CacheTier.set` REJECTS, never throws synchronously** — `lruTier`/`memoTier` are
   `async` for that alone.
 - **`redis.ts`'s script deletes NOTHING — it reads.** It returns the members; the tier `DEL`s them
@@ -156,6 +160,7 @@ Tier 1. Tagged caching + THE invalidation graph.
 | `tier-failures.ts` | `bestEffort()`, and the bounded log of refusals it absorbs |
 | `memo.ts` | request memo over the ALS ctx (WeakMap, no lifecycle) |
 | `lru.ts` | byte-budgeted LRU (linked list + map + tag index) |
+| `value-codec.ts` | the one value encoding every tier stores and decodes |
 | `redis.ts` | `Bun.redis` tier, build-namespaced keys, hash-tagged buckets, one script call per tag |
 | `cdn.ts` | `Cache-Control`/`Surrogate-Key` emission, `surrogateKeys`, the purge key list, the `PurgeDriver` seam |
 | `purge-http.ts` | the HTTP half both remote drivers share: one POST, batching, key guard, and core's retryable table re-exported |

package/README.md

@@ -46,6 +46,22 @@ const feed = await stack.read('feed:org-1', () => db.posts.recent(), {
 });
 ```
 
+**Cached values: JSON + `Date` + `bigint` + `Map` + `Set` — the same shape from every tier.**
+Every tier (the memo and the LRU included) stores the value as text through one codec
+(`value-codec.ts`) and decodes a fresh copy on each hit, so:
+
+| You write | Every tier answers |
+|---|---|
+| a `Date`, a `bigint`, a `Map`, a `Set` (at any depth) | the same type back |
+| a plain object, array, string, number, boolean, `null` | JSON semantics: `NaN`/`Infinity` → `null`, `undefined` members dropped |
+| a class instance | a plain object — its prototype is not stored |
+| a cycle, a `toJSON` that throws, nesting past `MAX_CACHE_VALUE_DEPTH` (512), a `bigint` past `MAX_CACHE_BIGINT_DIGITS` (4096 chars) | `X_CACHE_VALUE_UNENCODABLE`, at the write — a value is stored and readable, or refused |
+
+A hit is never the object that was written, nor the one another reader got: mutating it changes
+nothing in the cache. An app key spelled `$x` (or `$$x`…) is escaped on the way in. The stored text
+is `x1:` + JSON; only marked text is revived, so a Redis entry written as plain JSON before the
+codec reads back exactly as stored — never revived, never renamed.
+
 **`ttlMs` is positive and finite, in every tier.** Omit it for the tier's default; anything else
 is `X_CACHE_TTL_INVALID`. There is no "never expires" and no "do not cache" — `0` used to mean the
 first in the LRU tier and one second in the Redis tier, so a stack holding both answered
@@ -399,6 +415,7 @@ cache).
 | `X_CACHE_TAG_UNKNOWN` | a tag no entity declared — usually a typo |
 | `X_CACHE_TOO_LARGE` | one entry exceeds a tier's whole byte budget |
 | `X_CACHE_TTL_INVALID` | a `ttlMs` that is not a positive, finite number of milliseconds |
+| `X_CACHE_VALUE_UNENCODABLE` | a value with a cycle, a throwing `toJSON`, nesting past 512 levels or a `bigint` past 4096 digits, written to any tier |
 
 ### Error classes
 
@@ -414,6 +431,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `CacheTagUnknownError` | `X_CACHE_TAG_UNKNOWN` | `src/errors.ts` |
 | `CacheTooLargeError` | `X_CACHE_TOO_LARGE` | `src/errors.ts` |
 | `CacheTtlInvalidError` | `X_CACHE_TTL_INVALID` | `src/errors.ts` |
+| `CacheValueUnencodableError` | `X_CACHE_VALUE_UNENCODABLE` | `src/errors.ts` |
 
 ## Boundary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "25.0.0",
+  "version": "25.2.0",
   "description": "Tagged caching: request memo, LRU, Redis, CDN — one invalidation graph",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "25.0.0"
+    "@ultimat3/core": "25.2.0"
   }
 }

package/src/errors.ts

@@ -11,6 +11,7 @@ export const CACHE_OWNED_ERROR_CODES = [
   'X_CACHE_TAG_UNKNOWN',
   'X_CACHE_TOO_LARGE',
   'X_CACHE_TTL_INVALID',
+  'X_CACHE_VALUE_UNENCODABLE',
 ] as const;
 
 /** Every code cache can throw. It borrows none: every remote driver here is implemented. */
@@ -27,6 +28,7 @@ export const CACHE_ERROR_TITLES: Readonly<Record<CacheOwnedErrorCode, string>> =
   X_CACHE_TAG_UNKNOWN: 'a tag no entity declared',
   X_CACHE_TOO_LARGE: "one entry exceeds the tier's byte budget",
   X_CACHE_TTL_INVALID: 'a cache TTL that is not a positive number of milliseconds',
+  X_CACHE_VALUE_UNENCODABLE: 'a cached value the cache codec cannot encode',
 };
 
 // One unconditional call, so a second package claiming one of cache's codes throws
@@ -73,6 +75,23 @@ export class CacheTooLargeError extends UltimateError {
   }
 }
 
+/**
+ * A value the cache codec (`value-codec.ts`) cannot write: a cycle, a `toJSON` that throws, nesting
+ * past `MAX_CACHE_VALUE_DEPTH`, or a `bigint` past `MAX_CACHE_BIGINT_DIGITS`. Refused at the WRITE, in every tier alike — the LRU used to hold it by reference while Redis
+ * threw a bare `TypeError`, so the same `set` worked on one rung and failed on the next. `reason`
+ * is `renderThrowable` output, never the value: a cached value is application data.
+ */
+export class CacheValueUnencodableError extends UltimateError {
+  constructor(input: { key: string; tier: string; reason: string }) {
+    super({
+      code: 'X_CACHE_VALUE_UNENCODABLE',
+      cause: `entry "${input.key}" cannot be written to the ${input.tier} tier: ${input.reason}. A cache tier holds JSON plus Date, bigint, Map and Set, the same shape on every tier`,
+      fix: 'load: () => rows.map(({ parent, ...row }) => row) — cache a projection the codec reads back: plain objects, no back-references, nesting under 512 levels, a bigint past 4096 digits stored as a string',
+      meta: { key: input.key, tier: input.tier },
+    });
+  }
+}
+
 /**
  * A LIMIT this package runs on that is not one — a tier's byte budget, its entry ceiling, the
  * similarity floor the semantic tier decides "same question" with, or a purge driver's request

package/src/index.ts

@@ -19,6 +19,7 @@ export {
   CacheTagUnknownError,
   CacheTooLargeError,
   CacheTtlInvalidError,
+  CacheValueUnencodableError,
 } from './errors';
 export type { CacheFence, FenceScope } from './fence';
 export { FENCE_MEMORY, markInvalidated, sampleFence } from './fence';

package/src/lru.ts

@@ -17,6 +17,7 @@ import type {
   TtlJitter,
 } from './tiers';
 import { assertFiniteCapacity, assertFiniteDurationMs, assertTtl, nowMs } from './tiers';
+import { decodeCacheValue, encodeCacheValue } from './value-codec';
 
 export interface LruOptions {
   /** Byte budget for the whole tier. Default 64 MiB. */
@@ -32,7 +33,12 @@ export interface LruOptions {
 
 interface LruNode {
   key: string;
-  value: unknown;
+  /**
+   * `{ v }` as `value-codec.ts` text, never the caller's object: held by reference, a hit was the
+   * writer's live object — mutated by one reader for every later one — and a `Date` here was an
+   * ISO string on the pod that read the same entry back out of Redis.
+   */
+  text: string;
   bytes: number;
   /** Epoch ms. Always finite: `assertTtl` refuses the `0` that used to mean "never expires". */
   expiresAt: number;
@@ -141,11 +147,15 @@ export class LruCache {
     }
     this.touch(node);
     this.hits += 1;
-    return { value: node.value as T, tags: node.tags, expiresAt: node.expiresAt };
+    const { v } = decodeCacheValue(node.text) as { readonly v: T };
+    return { value: v, tags: node.tags, expiresAt: node.expiresAt };
   }
 
   set<T>(key: string, value: T, options: CacheSetOptions = {}): void {
-    const bytes = estimateBytes(value) + encoder.encode(key).byteLength;
+    // Encoded first: the budget is then the exact bytes held, and an unencodable value is refused
+    // before anything is evicted for it.
+    const text = encodeCacheValue({ v: value }, { key, tier: 'lru' });
+    const bytes = estimateBytes(text) + encoder.encode(key).byteLength;
     if (bytes > this.maxBytes) {
       throw new CacheTooLargeError({ key, bytes, maxBytes: this.maxBytes, tier: 'lru' });
     }
@@ -158,7 +168,7 @@ export class LruCache {
 
     const node: LruNode = {
       key,
-      value,
+      text,
       bytes,
       expiresAt: nowMs(this.clock) + ttl,
       tags: options.tags ?? [],

package/src/memo.ts

@@ -10,8 +10,18 @@ import type { CacheTag } from './tags';
 import { tagsIntersect } from './tags';
 import type { CacheEntry, CacheSetOptions, CacheTier, TierInvalidation } from './tiers';
 import { assertTtl } from './tiers';
+import { decodeCacheValue, encodeCacheValue } from './value-codec';
 
-type MemoStore = Map<string, CacheEntry<unknown>>;
+/**
+ * Codec text, as in every other tier: two callers in one request reading one key must not share
+ * one mutable object, and a hit here must be the shape the LRU or Redis would have answered.
+ */
+interface MemoEntry {
+  readonly text: string;
+  readonly tags: readonly CacheTag[];
+}
+
+type MemoStore = Map<string, MemoEntry>;
 
 const stores = new WeakMap<object, MemoStore>();
 
@@ -53,7 +63,9 @@ export function memoTier(): CacheTier {
     get<T>(key: string): Promise<CacheEntry<T> | undefined> {
       const entry = storeFor(false)?.get(key);
       // No TTL check: a request is shorter than any meaningful TTL.
-      return Promise.resolve(entry as CacheEntry<T> | undefined);
+      if (entry === undefined) return Promise.resolve(undefined);
+      const { v } = decodeCacheValue(entry.text) as { readonly v: T };
+      return Promise.resolve({ value: v, tags: entry.tags });
     },
 
     /**
@@ -75,7 +87,8 @@ export function memoTier(): CacheTier {
       if (options?.ttlMs !== undefined) {
         assertTtl(key, options.ttlMs, 'request-memo', { jitterFraction: 0 });
       }
-      storeFor(true)?.set(key, { value, tags: options?.tags ?? [] });
+      const text = encodeCacheValue({ v: value }, { key, tier: 'request-memo' });
+      storeFor(true)?.set(key, { text, tags: options?.tags ?? [] });
     },
 
     del(key: string): Promise<void> {

package/src/redis.ts

@@ -19,6 +19,7 @@ import type {
   TtlJitter,
 } from './tiers';
 import { assertFiniteDurationMs, assertTtl, nowMs } from './tiers';
+import { decodeCacheValue, encodeCacheValue } from './value-codec';
 
 /** The slice of Bun's Redis client this tier uses. Narrow on purpose: easy to fake in tests. */
 export interface RedisLike {
@@ -285,7 +286,9 @@ export function redisTier(options: RedisTierOptions = {}): CacheTier {
       // death handed a fresh five minutes, one tier closer to the request.
       if ('kind' in lease && lease.kind === 'reaped') return undefined;
       try {
-        const parsed = JSON.parse(raw) as StoredEntry;
+        // `decodeCacheValue`, not `JSON.parse`: the LRU decodes with the same codec, so a `Date`
+        // promoted out of here is a `Date` there too. Plain JSON written before the codec reads as-is.
+        const parsed = decodeCacheValue(raw) as StoredEntry;
         return {
           value: parsed.v as T,
           tags: parsed.t.map(parseTag),
@@ -314,6 +317,8 @@ export function redisTier(options: RedisTierOptions = {}): CacheTier {
       const tags = setOptions?.tags ?? [];
       const ttlMs = assertTtl(key, setOptions?.ttlMs ?? defaultTtlMs, 'redis', jitter);
       const payload: StoredEntry = { v: value, t: tags.map(serializeTag) };
+      // Before any bucket is joined: an unencodable value is refused with nothing left behind.
+      const text = encodeCacheValue(payload, { key, tier: 'redis' });
       const stored = valueKey(key);
       // `PX`, not `EX`: the value's lease is spent in the milliseconds it was validated and
       // jittered in. `Math.ceil(ttlMs / 1000)` honoured a 1,001ms lease as 2s — rounding toward
@@ -329,7 +334,7 @@ export function redisTier(options: RedisTierOptions = {}): CacheTier {
           conn().send('EVAL', [TAG_MEMBER_SCRIPT, '1', bucket, stored, bucketTtlSeconds]),
         ),
       );
-      await conn().send('SET', [stored, JSON.stringify(payload), 'PX', String(Math.ceil(ttlMs))]);
+      await conn().send('SET', [stored, text, 'PX', String(Math.ceil(ttlMs))]);
       if (buckets.length === 0) return;
       const membership = await Promise.all(
         buckets.map((bucket) => conn().send('SISMEMBER', [bucket, stored])),

package/src/value-codec.ts

@@ -0,0 +1,167 @@
+// The ONE encoding every cache tier stores a value in: JSON, plus tagged `Date`, `bigint`, `Map`
+// and `Set`. One codec is what makes a hit the same shape whichever rung answered it — and since
+// every tier stores TEXT, no two readers ever share one mutable object. Lives here, not in
+// `@ultimat3/query`'s cursor codec: query is tier 3, and this package is tier 1.
+
+import { renderThrowable } from '@ultimat3/core';
+import { CacheValueUnencodableError } from './errors';
+
+/** The member that marks a tagged value. Only this codec writes it; an app's own is escaped. */
+const TAG = '$x';
+/** `$x`, `$$x`, `$$$x`…: an app key that could be read as a tag, written with one more `$`. */
+const ESCAPABLE = /^\$+x$/;
+/** What an escaped app key looks like on the way back: two or more `$`. */
+const ESCAPED = /^\$\$+x$/;
+const DIGITS = /^-?\d+$/;
+
+/**
+ * The deepest a cached value may nest. `JSON.parse` with a reviver recurses, and overflows the
+ * stack somewhere between 5k and 20k levels that `JSON.stringify` wrote without complaint — so a
+ * deeper value was stored and then unreadable on every hit until its TTL. Refused at the write.
+ */
+export const MAX_CACHE_VALUE_DEPTH = 512;
+
+/**
+ * The longest `bigint` a cached value may hold, in characters. `BigInt(text)` is super-linear: a
+ * million digits throws a `RangeError`, 300k take over a second. 4096 is far past any column type
+ * (`numeric` aside) and costs microseconds.
+ */
+export const MAX_CACHE_BIGINT_DIGITS = 4096;
+
+/**
+ * Prefixed to every text this codec writes. No JSON text starts with `x`, so an unmarked entry —
+ * a Redis value written by a pod from before the codec — is read with plain `JSON.parse`, and app
+ * data that happens to look like a tag (`{"$x":"bigint","v":"12"}`) or an escape (`$$x`) is
+ * handed back exactly as it was stored, never revived or renamed.
+ */
+export const CACHE_CODEC_MARK = 'x1:';
+
+type Tagged = { readonly [TAG]: 'date' | 'bigint' | 'map' | 'set'; readonly v: unknown };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** A copy with every tag-shaped key given one more `$`, or the object itself when it has none. */
+const escapeKeys = (value: Record<string, unknown>): Record<string, unknown> => {
+  const keys = Object.keys(value);
+  if (!keys.some((key) => ESCAPABLE.test(key))) return value;
+  return Object.fromEntries(keys.map((key) => [ESCAPABLE.test(key) ? `$${key}` : key, value[key]]));
+};
+
+const unescapeKeys = (value: Record<string, unknown>): Record<string, unknown> => {
+  const keys = Object.keys(value);
+  if (!keys.some((key) => ESCAPED.test(key))) return value;
+  return Object.fromEntries(
+    keys.map((key) => [ESCAPED.test(key) ? key.slice(1) : key, value[key]]),
+  );
+};
+
+/**
+ * `this[key]`, not `value`: `JSON.stringify` calls `Date#toJSON` BEFORE the replacer sees it, so
+ * the argument is already a string — the holder still has the `Date`.
+ */
+function transform(holder: unknown, key: string, value: unknown): unknown {
+  const raw =
+    isRecord(holder) || Array.isArray(holder) ? (holder as Record<string, unknown>)[key] : value;
+  if (raw instanceof Date) {
+    return { [TAG]: 'date', v: Number.isNaN(raw.getTime()) ? null : raw.toISOString() };
+  }
+  if (typeof raw === 'bigint') {
+    const digits = raw.toString();
+    if (digits.length > MAX_CACHE_BIGINT_DIGITS) {
+      throw new CacheCodecLimit(
+        `a bigint of ${digits.length} characters, over the ${MAX_CACHE_BIGINT_DIGITS} a cache holds`,
+      );
+    }
+    return { [TAG]: 'bigint', v: digits };
+  }
+  if (raw instanceof Map) return { [TAG]: 'map', v: [...raw.entries()] };
+  if (raw instanceof Set) return { [TAG]: 'set', v: [...raw] };
+  return isRecord(value) ? escapeKeys(value) : value;
+}
+
+/** A limit this codec refuses at, carried out of `JSON.stringify` to `encodeCacheValue`. */
+class CacheCodecLimit {
+  constructor(readonly reason: string) {}
+}
+
+/**
+ * A replacer that knows how deep it is: every container it hands back is filed under its depth,
+ * and `JSON.stringify` calls it with that container as `this` for each member — one map lookup
+ * per node, no second walk. A cycle never reaches the cap: `JSON.stringify` refuses it first.
+ */
+const replacerWithDepth = (): ((this: unknown, key: string, value: unknown) => unknown) => {
+  const depths = new WeakMap<object, number>();
+  return function replace(this: unknown, key: string, value: unknown): unknown {
+    const out = transform(this, key, value);
+    if (typeof out !== 'object' || out === null) return out;
+    const depth = (typeof this === 'object' && this !== null ? (depths.get(this) ?? 0) : 0) + 1;
+    if (depth > MAX_CACHE_VALUE_DEPTH) {
+      throw new CacheCodecLimit(
+        `nested deeper than the ${MAX_CACHE_VALUE_DEPTH} levels a cache reads back`,
+      );
+    }
+    depths.set(out, depth);
+    return out;
+  };
+};
+
+const isEntryList = (value: unknown): value is [unknown, unknown][] =>
+  Array.isArray(value) && value.every((entry) => Array.isArray(entry) && entry.length === 2);
+
+/** The tagged value back, or `undefined` when `value` is not one this codec wrote. */
+const untag = (value: Record<string, unknown>): { readonly revived: unknown } | undefined => {
+  const keys = Object.keys(value);
+  if (keys.length !== 2 || !Object.hasOwn(value, TAG) || !Object.hasOwn(value, 'v')) return;
+  const { v } = value as Tagged;
+  switch (value[TAG]) {
+    case 'date':
+      return v === null || typeof v === 'string'
+        ? { revived: new Date(v ?? Number.NaN) }
+        : undefined;
+    case 'bigint':
+      // Length first: text past the cap was not written by `encodeCacheValue`, and `BigInt` on it
+      // is the expensive call.
+      return typeof v === 'string' && v.length <= MAX_CACHE_BIGINT_DIGITS && DIGITS.test(v)
+        ? { revived: BigInt(v) }
+        : undefined;
+    case 'map':
+      return isEntryList(v) ? { revived: new Map(v) } : undefined;
+    case 'set':
+      return Array.isArray(v) ? { revived: new Set(v) } : undefined;
+    default:
+      return undefined;
+  }
+};
+
+/** Bottom-up, so a tagged value's members are already revived when the tag itself is read. */
+const revive = (_key: string, value: unknown): unknown => {
+  if (!isRecord(value)) return value;
+  const tagged = untag(value);
+  return tagged === undefined ? unescapeKeys(value) : tagged.revived;
+};
+
+/**
+ * `payload` as the text a tier stores, marked with `CACHE_CODEC_MARK`. A cycle, a throwing
+ * `toJSON`, nesting past `MAX_CACHE_VALUE_DEPTH` or a bigint past `MAX_CACHE_BIGINT_DIGITS` is
+ * `X_CACHE_VALUE_UNENCODABLE`, naming the key and the tier: what is written is always readable.
+ */
+export function encodeCacheValue(payload: unknown, at: { key: string; tier: string }): string {
+  try {
+    // `?? 'null'`: a top-level `undefined` or function is no JSON text at all.
+    return `${CACHE_CODEC_MARK}${JSON.stringify(payload, replacerWithDepth()) ?? 'null'}`;
+  } catch (error) {
+    const reason = error instanceof CacheCodecLimit ? error.reason : renderThrowable(error);
+    throw new CacheValueUnencodableError({ ...at, reason });
+  }
+}
+
+/**
+ * The inverse. Marked text is revived — only an object of exactly `{ $x, v }` with a tag this
+ * codec knows. Unmarked text predates the codec and is plain `JSON.parse`. Throws what
+ * `JSON.parse` throws; a tier reading text it did not write decides what a corrupt entry means.
+ */
+export function decodeCacheValue(text: string): unknown {
+  if (!text.startsWith(CACHE_CODEC_MARK)) return JSON.parse(text);
+  return JSON.parse(text.slice(CACHE_CODEC_MARK.length), revive);
+}