@timber-js/app 0.2.0-alpha.166 → 0.2.0-alpha.168

package/src/cache/cache-api.ts

@@ -6,102 +6,102 @@ import { recordInvalidation } from './invalidation-epoch';
 import { writeTombstonesForTag } from '../server/prebuilt/overlay.js';
 import { getCdnPurgeHandler } from '../cdn/purge-store.js';
 
+const componentFallbackWarned = new WeakSet<object>();
+
 /**
- * Public caching API: `cache(fn, opts)`.
- *
- * Wraps an async function with cross-request caching. Uses the configured
- * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).
+ * Cache namespace — `cache.data`, `cache.component`, `cache.invalidate`.
  *
  * ```ts
  * import { cache } from '@timber-js/app/cache';
  *
- * const getUser = cache(
+ * const getUser = cache.data(
  *   async (id: string) => db.users.findUnique({ where: { id } }),
  *   { ttl: 60, tags: (id) => [`user:${id}`] }
  * );
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function cache<Fn extends (...args: any[]) => Promise<any>>(
-  fn: Fn,
-  opts: CacheOptions<Fn>,
-  stableId?: string
-): Fn {
-  // Pass the getter, not a resolved handler: the wrapper re-resolves it on
-  // every call, so module-scope wrappers created before the framework's boot
-  // wiring calls setCacheHandler() still pick up the configured handler
-  // instead of permanently binding the in-memory fallback (TIM-1029).
-  return createCache(fn, opts, getCacheHandler, stableId);
-}
+export const cache = {
+  /**
+   * Wrap an async function with cross-request caching.
+   *
+   * The configured cache handler (defaults to MemoryCacheHandler, overridable
+   * via timber.config.ts) is re-resolved on every call, so module-scope
+   * wrappers created before `setCacheHandler()` still pick up the configured
+   * handler (TIM-1029).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data<Fn extends (...args: any[]) => Promise<any>>(
+    fn: Fn,
+    opts: CacheOptions<Fn>,
+    stableId?: string
+  ): Fn {
+    return createCache(fn, opts, getCacheHandler, stableId);
+  },
 
-/**
- * Invalidate cache entries by tag or key.
- *
- * ```ts
- * cache.invalidate({ tag: 'products' });
- * cache.invalidate({ key: 'user:abc' });
- * ```
- */
-cache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {
-  // Record before the handler delete so a cached fn in flight skips its
-  // post-resolve set instead of resurrecting the invalidated value (TIM-1028).
-  recordInvalidation(opts);
-  await getCacheHandler().invalidate(opts);
-  // Write tombstones for build-seed entries carrying the tag (design/45
-  // §ISR mechanics). Runs AFTER handler.invalidate so the tombstone
-  // overwrites the cleared overlay slot. This covers ALL invalidation
-  // paths — actions, webhooks, route handlers — not just executeAction.
-  if (opts.tag) {
-    await writeTombstonesForTag(opts.tag);
-  }
-  // Trigger CDN purge if a handler is configured (design/25 §Layer 2).
-  // Purge is best-effort: a CDN API failure or timeout must not block
-  // cache invalidation. 10s ceiling prevents a hung CDN API from stalling
-  // the entire revalidateTag/action flow.
-  if (opts.tag) {
-    const purgeHandler = getCdnPurgeHandler();
-    if (purgeHandler) {
-      try {
-        await Promise.race([
-          purgeHandler.purgeTags([opts.tag]),
-          new Promise<void>((_, reject) =>
-            setTimeout(() => reject(new Error('CDN purge timed out (10s)')), 10_000)
-          ),
-        ]);
-      } catch (err) {
-        console.error('[timber] CDN purge failed for tag:', err);
+  /**
+   * Invalidate cache entries by tag or key.
+   *
+   * ```ts
+   * cache.invalidate({ tag: 'products' });
+   * cache.invalidate({ key: 'user:abc' });
+   * ```
+   */
+  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+    // Record before the handler delete so a cached fn in flight skips its
+    // post-resolve set instead of resurrecting the invalidated value (TIM-1028).
+    recordInvalidation(opts);
+    await getCacheHandler().invalidate(opts);
+    // Write tombstones for build-seed entries carrying the tag (design/45
+    // §ISR mechanics). Runs AFTER handler.invalidate so the tombstone
+    // overwrites the cleared overlay slot. This covers ALL invalidation
+    // paths — actions, webhooks, route handlers — not just executeAction.
+    if (opts.tag) {
+      await writeTombstonesForTag(opts.tag);
+    }
+    // Trigger CDN purge if a handler is configured (design/25 §Layer 2).
+    // Purge is best-effort: a CDN API failure or timeout must not block
+    // cache invalidation. 10s ceiling prevents a hung CDN API from stalling
+    // the entire revalidateTag/action flow.
+    if (opts.tag) {
+      const purgeHandler = getCdnPurgeHandler();
+      if (purgeHandler) {
+        try {
+          await Promise.race([
+            purgeHandler.purgeTags([opts.tag]),
+            new Promise<void>((_, reject) =>
+              setTimeout(() => reject(new Error('CDN purge timed out (10s)')), 10_000)
+            ),
+          ]);
+        } catch (err) {
+          console.error('[timber] CDN purge failed for tag:', err);
+        }
       }
     }
-  }
-};
-
-const componentFallbackWarned = new WeakSet<object>();
+  },
 
-/**
- * Runtime fallback for `cache.component(...)` callsites the timber-prebuilt
- * transform does not rewrite — nested/computed/argument-position forms (see
- * plugins/prebuilt.ts). Only module-scope `const X = cache.component(...)`
- * declarations are transformed and eligible for prebuilding; everything else
- * lands here, warns once per component, and renders dynamically. Same
- * safety-net pattern as the data cache's runtime fnId fallback (TIM-1054):
- * an untraceable callsite degrades in performance, never in correctness.
- *
- * The full public surface (types, docs, `timber` namespace) is TIM-1121;
- * design/45-cache-lifetimes.md specifies the options.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-cache.component = function component<C extends (props: any) => unknown>(
-  componentFn: C,
-  _options?: PrebuiltComponentOptions
-): C {
-  if (!componentFallbackWarned.has(componentFn)) {
-    componentFallbackWarned.add(componentFn);
-    const name = componentFn.name || 'anonymous component';
-    console.warn(
-      `[timber] cache.component: "${name}" was not transformed at build time — ` +
-        `rendering dynamically. Only module-scope declarations ` +
-        `(const X = cache.component(...)) are prebuilt.`
-    );
-  }
-  return componentFn;
+  /**
+   * Runtime fallback for `cache.component(...)` callsites the timber-prebuilt
+   * transform does not rewrite — nested/computed/argument-position forms (see
+   * plugins/prebuilt.ts). Only module-scope `const X = cache.component(...)`
+   * declarations are transformed and eligible for prebuilding; everything else
+   * lands here, warns once per component, and renders dynamically. Same
+   * safety-net pattern as the data cache's runtime fnId fallback (TIM-1054):
+   * an untraceable callsite degrades in performance, never in correctness.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  component<C extends (props: any) => unknown>(
+    componentFn: C,
+    _options?: PrebuiltComponentOptions
+  ): C {
+    if (!componentFallbackWarned.has(componentFn)) {
+      componentFallbackWarned.add(componentFn);
+      const name = componentFn.name || 'anonymous component';
+      console.warn(
+        `[timber] cache.component: "${name}" was not transformed at build time — ` +
+          `rendering dynamically. Only module-scope declarations ` +
+          `(const X = cache.component(...)) are prebuilt.`
+      );
+    }
+    return componentFn;
+  },
 };

package/src/cache/index.ts

@@ -167,7 +167,7 @@ export class MemoryCacheHandler implements CacheHandler {
 }
 
 export { RedisCacheHandler } from './redis-handler';
-export type { RedisClient } from './redis-handler';
+export type { RedisClient, RedisWriteOp } from './redis-handler';
 export { cache } from './cache-api';
 export { setCacheHandler, getCacheHandler } from './handler-store';
 export { setDefaultSingleflightTimeout } from './timber-cache';

package/src/cache/json-lossy-check.ts

@@ -0,0 +1,75 @@
+const LOSSY_TYPES = ['Date', 'Map', 'Set', 'BigInt'] as const;
+
+let hasWarned = false;
+
+/**
+ * Dev-mode warning when a cache value contains types that lose fidelity
+ * through JSON round-trip. Only runs in development — no-op in production.
+ *
+ * Detects: Date (→ ISO string), Map/Set (→ {}), BigInt (→ throws).
+ * Emits once per process to avoid log spam.
+ */
+export function warnLossyJsonValue(value: unknown, cacheKey: string): void {
+  if (hasWarned) return;
+  if (process.env.NODE_ENV === 'production') return;
+
+  const lossy = findLossyTypes(value, new Set(), 0);
+  if (lossy.size === 0) return;
+
+  hasWarned = true;
+  const types = [...lossy].join(', ');
+  console.warn(
+    `[timber] cache value for key "${cacheKey}" contains ${types} — ` +
+      'these types lose fidelity through JSON serialization in Redis/KV cache handlers. ' +
+      'Date becomes an ISO string, Map/Set become {}, BigInt throws. ' +
+      'The MemoryCacheHandler preserves them. Consider transforming values ' +
+      'to JSON-safe types before caching, or use MemoryCacheHandler for ' +
+      'values that require type preservation.'
+  );
+}
+
+function findLossyTypes(value: unknown, seen: Set<unknown>, depth: number): Set<string> {
+  const lossy = new Set<string>();
+  if (depth > 8 || value === null || value === undefined) return lossy;
+  if (typeof value === 'bigint') {
+    lossy.add('BigInt');
+    return lossy;
+  }
+  if (typeof value !== 'object' && typeof value !== 'function') return lossy;
+  if (seen.has(value)) return lossy;
+  seen.add(value);
+
+  if (value instanceof Date) {
+    lossy.add('Date');
+    return lossy;
+  }
+  if (value instanceof Map) {
+    lossy.add('Map');
+    return lossy;
+  }
+  if (value instanceof Set) {
+    lossy.add('Set');
+    return lossy;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      for (const t of findLossyTypes(item, seen, depth + 1)) lossy.add(t);
+      if (lossy.size === LOSSY_TYPES.length) return lossy;
+    }
+    return lossy;
+  }
+
+  for (const k of Object.keys(value as Record<string, unknown>)) {
+    for (const t of findLossyTypes((value as Record<string, unknown>)[k], seen, depth + 1)) {
+      lossy.add(t);
+    }
+    if (lossy.size === LOSSY_TYPES.length) return lossy;
+  }
+  return lossy;
+}
+
+/** Reset warning state — for tests only. */
+export function _resetLossyWarning(): void {
+  hasWarned = false;
+}

package/src/cache/redis-handler.ts

@@ -1,4 +1,5 @@
 import type { CacheHandler } from './index';
+import { warnLossyJsonValue } from './json-lossy-check.js';
 
 /**
  * Minimal Redis client contract for `RedisCacheHandler`.
@@ -27,6 +28,19 @@ import type { CacheHandler } from './index';
  *   srem: (k, ...m) => redis.srem(k, ...m),
  *   smembers: (k) => redis.smembers(k),
  *   ttl: (k) => redis.ttl(k),
+ *   execMulti: async (ops) => {
+ *     const p = redis.multi();
+ *     for (const op of ops) {
+ *       switch (op.op) {
+ *         case 'set': p.set(op.key, op.value, 'EX', op.ttlSeconds); break;
+ *         case 'sadd': p.sadd(op.key, ...op.members); break;
+ *         case 'expireNX': p.expire(op.key, op.seconds, 'NX'); break;
+ *         case 'expireGT': p.expire(op.key, op.seconds, 'GT'); break;
+ *         case 'del': p.del(op.key); break;
+ *       }
+ *     }
+ *     await p.exec();
+ *   },
  * };
  * ```
  *
@@ -67,6 +81,13 @@ import type { CacheHandler } from './index';
  * };
  * ```
  */
+export type RedisWriteOp =
+  | { op: 'set'; key: string; value: string; ttlSeconds: number }
+  | { op: 'sadd'; key: string; members: string[] }
+  | { op: 'expireNX'; key: string; seconds: number }
+  | { op: 'expireGT'; key: string; seconds: number }
+  | { op: 'del'; key: string };
+
 export interface RedisClient {
   /** `GET key` — the stored string, or null when absent. */
   get(key: string): Promise<string | null>;
@@ -99,6 +120,13 @@ export interface RedisClient {
    * not exist, -1 if the key exists but has no expiry.
    */
   ttl(key: string): Promise<number>;
+  /**
+   * Execute a batch of write operations atomically via `MULTI/EXEC`.
+   * When provided, `set()` uses this to make tag-index writes and the data
+   * write atomic — no `invalidate({tag})` can interleave. Optional: when
+   * absent, operations run sequentially (correct but not race-free).
+   */
+  execMulti?(ops: RedisWriteOp[]): Promise<void>;
 }
 
 const KEY_PREFIX = 'timber:cache:';
@@ -146,8 +174,12 @@ export class RedisCacheHandler implements CacheHandler {
     value: unknown,
     opts: { ttl: number; tags: string[]; generation?: number }
   ): Promise<void> {
+    warnLossyJsonValue(value, key);
     const ck = this.cacheKey(key);
     const expiresAt = Date.now() + opts.ttl * 1000;
+
+    // Serialize upfront so BigInt/non-serializable errors throw before any
+    // writes — prevents tag indexes pointing at stale data from a prior set().
     const payload = JSON.stringify({ value, expiresAt, tags: opts.tags });
 
     // Redis TTL with generous margin beyond the logical TTL to allow SWR reads
@@ -155,22 +187,41 @@ export class RedisCacheHandler implements CacheHandler {
     // We use 2x TTL + 60s as the Redis expiry so stale entries remain
     // available for SWR background refetches.
     const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
-    await this.client.set(ck, payload, redisTtlSeconds);
 
-    // Track key membership in each tag set, and expire the set so it doesn't
-    // outlive all its members. Only extend the TTL, never shorten — a short-TTL
-    // entry must not shrink a tag set that already contains long-TTL entries,
-    // otherwise invalidate({tag}) would miss the long-lived entries.
+    const writeOps: RedisWriteOp[] = [];
     for (const tag of opts.tags) {
-      await this.client.sadd(this.tagKey(tag), key);
-      // Two atomic EXPIRE calls cover both the initial-set and extend cases:
-      // - NX: sets the TTL only if the key has no expiry (new tag set from SADD)
-      // - GT: extends the TTL only if the new value is greater than current
-      // Together they close the race where concurrent workers could shrink the
-      // tag set lifetime (TIM-1093), while ensuring new tag sets always get an
-      // initial expiry (without NX, GT is a no-op on non-volatile keys).
-      await this.client.expireNX(this.tagKey(tag), redisTtlSeconds);
-      await this.client.expireGT(this.tagKey(tag), redisTtlSeconds);
+      writeOps.push({ op: 'sadd', key: this.tagKey(tag), members: [key] });
+      writeOps.push({ op: 'expireNX', key: this.tagKey(tag), seconds: redisTtlSeconds });
+      writeOps.push({ op: 'expireGT', key: this.tagKey(tag), seconds: redisTtlSeconds });
+    }
+    writeOps.push({ op: 'set', key: ck, value: payload, ttlSeconds: redisTtlSeconds });
+
+    if (this.client.execMulti) {
+      await this.client.execMulti(writeOps);
+    } else {
+      for (const op of writeOps) {
+        await this.execOp(op);
+      }
+    }
+  }
+
+  private async execOp(op: RedisWriteOp): Promise<void> {
+    switch (op.op) {
+      case 'set':
+        await this.client.set(op.key, op.value, op.ttlSeconds);
+        break;
+      case 'sadd':
+        await this.client.sadd(op.key, ...op.members);
+        break;
+      case 'expireNX':
+        await this.client.expireNX(op.key, op.seconds);
+        break;
+      case 'expireGT':
+        await this.client.expireGT(op.key, op.seconds);
+        break;
+      case 'del':
+        await this.client.del(op.key);
+        break;
     }
   }
 

package/src/cache/timber-cache.ts

@@ -7,7 +7,7 @@ import {
   wasInvalidatedSince,
 } from './invalidation-epoch';
 import { addSpanEventSync } from '../server/tracing.js';
-import { logSwrRefetchFailed } from '../server/logger.js';
+import { logSwrRefetchFailed, swallow } from '../server/logger.js';
 import { getWaitUntil } from '../server/waituntil-bridge.js';
 import { fnv1aHash } from './fast-hash.js';
 
@@ -189,7 +189,15 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       const generation = nextGeneration(key);
       const result = await fn(...args);
       if (!signal.aborted && !wasInvalidatedSince(startEpoch, key, tags)) {
-        await getHandler().set(key, result, { ttl: opts.ttl, tags, generation });
+        try {
+          await getHandler().set(key, result, { ttl: opts.ttl, tags, generation });
+        } catch (err) {
+          // Cache-write failure must not fail the request (TIM-1046).
+          // JSON-serializing handlers (Redis, KV) throw on BigInt; network
+          // errors can surface from any shared handler. The result is valid
+          // — serve it uncached rather than rejecting a successful fn().
+          swallow(err, `cache set failed for key "${key}"`);
+        }
       }
       return result;
     };

package/src/client/browser-entry/index.ts

@@ -76,6 +76,8 @@ function bootstrap(runtimeConfig: typeof config): void {
   // Step 3: Create router + Navigation API integration
   const { router, navApiController } = createTimberRouter({
     initialElement: rscResult?.element ?? undefined,
+    clientSegmentCache:
+      ((runtimeConfig as Record<string, unknown>).clientSegmentCache as boolean) ?? false,
   });
 
   // Step 4: Pre-hydration — set params + navigation state (MUST run after router init)

package/src/client/browser-entry/post-hydration.ts

@@ -38,9 +38,25 @@ export function setupPostHydration({
   // runPreHydration() — without them on the entry, the cached replay on
   // back-navigation would normalize params to {} and wipe every
   // useSegmentParams() consumer on the initial page (TIM-1037).
+  // Populate the segment cache from server-embedded segment metadata.
+  // This enables state tree diffing from the very first client navigation.
+  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+  const timberSegments = (self as unknown as Record<string, unknown>).__timber_segments;
+  const initialSegmentInfo = Array.isArray(timberSegments)
+    ? (timberSegments as import('../segment-cache').SegmentInfo[])
+    : null;
+  if (initialSegmentInfo) {
+    router.initSegmentCache(initialSegmentInfo);
+    delete (self as unknown as Record<string, unknown>).__timber_segments;
+  }
+
+  // Store the initial page in the history stack so back-button works
+  // after the first navigation. Include segmentInfo so the segment
+  // cache is restored correctly on popstate cached replay.
   router.historyStack.push(window.location.pathname + window.location.search, {
     payload: initialElement,
     params: getNavigationState().params,
+    segmentInfo: initialSegmentInfo,
   });
 
   // Initialize scroll state for the initial entry.
@@ -52,15 +68,6 @@ export function setupPostHydration({
     window.history.replaceState({ timber: true, scrollY: 0 }, '');
   }
 
-  // Populate the segment cache from server-embedded segment metadata.
-  // This enables state tree diffing from the very first client navigation.
-  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  const timberSegments = (self as unknown as Record<string, unknown>).__timber_segments;
-  if (Array.isArray(timberSegments)) {
-    router.initSegmentCache(timberSegments);
-    delete (self as unknown as Record<string, unknown>).__timber_segments;
-  }
-
   // Register popstate handler for back/forward navigation.
   // When Navigation API is active, the navigate event covers traversals —
   // popstate is a no-op. When unavailable, popstate handles back/forward.

package/src/client/browser-entry/router-init.ts

@@ -29,6 +29,7 @@ import { getScrollY, scrollToHashTarget } from './scroll.js';
 
 export interface RouterInitOptions {
   initialElement?: unknown;
+  clientSegmentCache?: boolean;
 }
 
 export interface RouterInitResult {
@@ -136,6 +137,7 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
   };
 
   const deps: RouterDeps = {
+    clientSegmentCache: options?.clientSegmentCache ?? false,
     fetch: (url, init) => window.fetch(url, init),
     pushState: (data, unused, url) => {
       gFlags[ROUTER_HISTORY_FLAG] = true;

package/src/client/history.ts

@@ -1,6 +1,8 @@
 // History Stack — stores RSC payloads by URL for instant back/forward navigation
 // See design/19-client-navigation.md § History Stack
 
+import type { SegmentInfo } from './segment-cache';
+
 // ─── Types ───────────────────────────────────────────────────────
 
 export interface HistoryEntry {
@@ -13,6 +15,15 @@ export interface HistoryEntry {
    * and revalidation overwrites preserve the current state (TIM-1037).
    */
   params?: Record<string, string | string[]> | null;
+  /**
+   * Segment metadata for this page's route. Restored into the segment cache
+   * on popstate cached replay so the next forward navigation computes a
+   * correct state tree. Without this, the segment cache retains the
+   * *previous* page's segments after back-button, causing the server to
+   * skip segments that aren't mounted — and the partial payload targets
+   * a non-existent outlet.
+   */
+  segmentInfo?: SegmentInfo[] | null;
 }
 
 // ─── History Stack ───────────────────────────────────────────────