@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

package/dist/cache/index.js

@@ -1,5 +1,39 @@
-import "../_chunks/als-registry-B7DbZ2hS.js";
-import { n as addSpanEventSync } from "../_chunks/tracing-CemImE6h.js";
+import { n as addSpanEventSync } from "../_chunks/tracing-M_zKubhk.js";
+import { d as logSwrRefetchFailed } from "../_chunks/logger-Dt-jQaBO.js";
+import { t as fnv1aHash } from "../_chunks/fast-hash-D6hIVt1Y.js";
+import { n as setCacheHandler, t as getCacheHandler } from "../_chunks/handler-store-DjISKYEB.js";
+//#region src/cache/sizeof.ts
+/**
+* Lightweight byte-size estimation for cache entries.
+*
+* Estimates the in-memory byte cost of a JavaScript value using
+* JSON.stringify().length * 2 (UTF-16 char width). This is a rough
+* approximation — it doesn't account for V8 object overhead, Map
+* metadata, or non-serializable values — but it's fast and good
+* enough for cache budget enforcement.
+*
+* Values that fail JSON serialization (circular references, BigInt,
+* etc.) return 0, allowing the entry to be cached without counting
+* toward the byte budget. This is a conservative choice: it's better
+* to cache and undercount than to reject the entry.
+*/
+/**
+* Estimate the byte size of a value.
+*
+* Uses `JSON.stringify(value).length * 2` to approximate UTF-16
+* in-memory size. Returns 0 if the value is not serializable.
+*/
+function estimateByteSize(value) {
+	try {
+		const json = JSON.stringify(value);
+		if (json === void 0) return 0;
+		return json.length * 2;
+	} catch (e) {
+		console.debug("[timber] sizeof estimation failed:", e instanceof Error ? e.message : e);
+		return 0;
+	}
+}
+//#endregion
 //#region src/cache/redis-handler.ts
 var KEY_PREFIX = "timber:cache:";
 var TAG_PREFIX = "timber:tag:";
@@ -82,54 +116,49 @@ function stableStringify(value) {
 }
 //#endregion
 //#region src/cache/singleflight.ts
-function createSingleflight() {
+/**
+* Error thrown when a singleflight call exceeds `timeoutMs`.
+* Exported so callers can distinguish timeout from other errors.
+*/
+var SingleflightTimeoutError = class extends Error {
+	constructor(key, timeoutMs) {
+		super(`Singleflight timeout: key "${key}" exceeded ${timeoutMs}ms`);
+		this.name = "SingleflightTimeoutError";
+	}
+};
+function createSingleflight(opts) {
 	const inflight = /* @__PURE__ */ new Map();
+	const timeoutMs = opts?.timeoutMs;
 	return { do(key, fn) {
 		const existing = inflight.get(key);
 		if (existing) return existing;
-		const promise = fn().finally(() => {
+		let promise;
+		if (timeoutMs != null && timeoutMs > 0) promise = new Promise((resolve, reject) => {
+			const timer = setTimeout(() => reject(new SingleflightTimeoutError(key, timeoutMs)), timeoutMs);
+			try {
+				fn().then((value) => {
+					clearTimeout(timer);
+					resolve(value);
+				}, (err) => {
+					clearTimeout(timer);
+					reject(err);
+				});
+			} catch (err) {
+				clearTimeout(timer);
+				reject(err);
+			}
+		});
+		else promise = fn();
+		const tracked = promise.finally(() => {
 			inflight.delete(key);
 		});
-		inflight.set(key, promise);
-		return promise;
+		inflight.set(key, tracked);
+		return tracked;
 	} };
 }
 //#endregion
-//#region src/cache/fast-hash.ts
-/**
-* Fast non-cryptographic hash for cache keys.
-*
-* FNV-1a 64-bit produces a well-distributed hash with a collision
-* probability of ~1 in 5 billion at 77k keys (birthday paradox).
-* Not suitable for security, but ideal for cache key generation
-* where we need speed over crypto strength.
-*
-* Uses BigInt for 64-bit arithmetic — supported in all modern runtimes
-* including Cloudflare Workers. No node:crypto dependency.
-*
-* See TIM-370.
-*/
-var FNV_OFFSET_BASIS = 14695981039346656037n;
-var FNV_PRIME = 1099511628211n;
-var MASK_64 = 18446744073709551615n;
-/**
-* Compute a 64-bit FNV-1a hash of a string, returned as a 16-char hex string.
-*
-* 64 bits gives ~5 billion keys before a 50% collision probability
-* (birthday paradox), making accidental collisions effectively impossible
-* for cache key use cases.
-*/
-function fnv1aHash(input) {
-	let hash = FNV_OFFSET_BASIS;
-	for (let i = 0; i < input.length; i++) {
-		hash ^= BigInt(input.charCodeAt(i));
-		hash = hash * FNV_PRIME & MASK_64;
-	}
-	return hash.toString(16).padStart(16, "0");
-}
-//#endregion
 //#region src/cache/timber-cache.ts
-var singleflight$1 = createSingleflight();
+var defaultSingleflight = createSingleflight();
 /**
 * Generate a cache key from function identity and serialized args.
 *
@@ -146,12 +175,13 @@ function defaultKeyGenerator(fnId, args) {
 /**
 * Resolve tags from the options — supports static array or function form.
 */
-function resolveTags$1(opts, args) {
+function resolveTags(opts, args) {
 	if (!opts.tags) return [];
 	if (Array.isArray(opts.tags)) return opts.tags;
 	return opts.tags(...args);
 }
-var fnIdCounter = 0;
+var unstableIdCounter = 0;
+var hasWarnedUnstableId = false;
 /**
 * Creates a cached wrapper around an async function.
 *
@@ -164,9 +194,19 @@ var fnIdCounter = 0;
 * Cache hits/misses are recorded as OTEL span events on the enclosing
 * span (not child spans). The DevSpanProcessor reads these for dev log output.
 */
-function createCache(fn, opts, handler) {
-	const fnId = `timber-cache:${fnIdCounter++}`;
-	return async (...args) => {
+function createCache(fn, opts, handler, stableId) {
+	let fnId;
+	if (stableId) fnId = stableId;
+	else if (opts.key) fnId = `timber-cache:${unstableIdCounter++}`;
+	else {
+		fnId = `timber-cache:unstable:${unstableIdCounter++}`;
+		if (!hasWarnedUnstableId && typeof process !== "undefined" && process.env.NODE_ENV !== "test") {
+			hasWarnedUnstableId = true;
+			console.warn("[timber] cache() called without a stable ID or explicit key function. Cache keys will use a process-local counter which is unstable across cold starts. Run through the timber Vite plugin or provide an explicit `key` option to fix this.");
+		}
+	}
+	const sf = opts.timeoutMs ? createSingleflight({ timeoutMs: opts.timeoutMs }) : defaultSingleflight;
+	return (async (...args) => {
 		const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);
 		const cacheStart = performance.now();
 		const cached = await handler.get(key);
@@ -183,20 +223,25 @@ function createCache(fn, opts, handler) {
 				duration_ms: Math.round(performance.now() - cacheStart),
 				stale: true
 			});
-			singleflight$1.do(`swr:${key}`, async () => {
+			sf.do(`swr:${key}`, async () => {
 				try {
 					const fresh = await fn(...args);
-					const tags = resolveTags$1(opts, args);
+					const tags = resolveTags(opts, args);
 					await handler.set(key, fresh, {
 						ttl: opts.ttl,
 						tags
 					});
-				} catch {}
+				} catch (err) {
+					logSwrRefetchFailed({
+						cacheKey: key,
+						error: err
+					});
+				}
 			}).catch(() => {});
 			return cached.value;
 		}
-		const result = await singleflight$1.do(key, () => fn(...args));
-		const tags = resolveTags$1(opts, args);
+		const result = await sf.do(key, () => fn(...args));
+		const tags = resolveTags(opts, args);
 		await handler.set(key, result, {
 			ttl: opts.ttl,
 			tags
@@ -206,7 +251,7 @@ function createCache(fn, opts, handler) {
 			duration_ms: Math.round(performance.now() - cacheStart)
 		});
 		return result;
-	};
+	});
 }
 /**
 * Invalidate cache entries by tag or key.
@@ -215,75 +260,48 @@ createCache.invalidate = async function invalidate(handler, opts) {
 	await handler.invalidate(opts);
 };
 //#endregion
-//#region src/cache/register-cached-function.ts
-var singleflight = createSingleflight();
-var REQUEST_SPECIFIC_PROPS = new Set([
-	"cookies",
-	"cookie",
-	"session",
-	"sessionId",
-	"token",
-	"authorization",
-	"auth",
-	"headers"
-]);
+//#region src/cache/cache-api.ts
 /**
-* Generate a cache key from a stable function ID and serialized args.
+* Public caching API: `cache(fn, opts)`.
 *
-* Uses FNV-1a (fast non-crypto hash) instead of SHA-256. The id prefix
-* provides namespace isolation; the hash covers the args.
-* See TIM-370.
-*/
-function generateKey(id, args) {
-	const raw = id + ":" + stableStringify(args);
-	return id + ":" + fnv1aHash(raw);
-}
-/**
-* Resolve tags from options — supports static array or function form.
-*/
-function resolveTags(opts, args) {
-	if (!opts.tags) return [];
-	if (Array.isArray(opts.tags)) return opts.tags;
-	return opts.tags(...args);
-}
-/**
-* Checks if component props contain request-specific keys and emits a dev warning.
-* Only runs when process.env.NODE_ENV !== 'production'.
+* Wraps an async function with cross-request caching. Uses the configured
+* cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).
+*
+* ```ts
+* import { cache } from '@timber-js/app/cache';
+*
+* const getUser = cache(
+*   async (id: string) => db.users.findUnique({ where: { id } }),
+*   { ttl: 60, tags: (id) => [`user:${id}`] }
+* );
+* ```
 */
-function warnRequestSpecificProps(id, props) {
-	if (typeof props !== "object" || props === null) return;
-	const suspicious = Object.keys(props).filter((k) => REQUEST_SPECIFIC_PROPS.has(k.toLowerCase()));
-	if (suspicious.length > 0) console.warn(`[timber] "use cache" component ${id} received request-specific props: ${suspicious.join(", ")}. This may serve one user's cached render to another user. Remove request-specific data from props or remove "use cache".`);
+function cache(fn, opts, stableId) {
+	return createCache(fn, opts, getCacheHandler(), stableId);
 }
 /**
-* Runtime for the "use cache" directive transform. Wraps an async function
-* with caching using the same cache handler as timber.cache.
+* Invalidate cache entries by tag or key.
 *
-* The stable `id` (file path + function name) ensures cache keys are consistent
-* across builds. Args/props are hashed with SHA-256 for the per-call key.
+* ```ts
+* cache.invalidate({ tag: 'products' });
+* cache.invalidate({ key: 'user:abc' });
+* ```
 */
-function registerCachedFunction(fn, opts, handler) {
-	return async (...args) => {
-		if (opts.isComponent && process.env.NODE_ENV !== "production" && args.length > 0) warnRequestSpecificProps(opts.id, args[0]);
-		const key = generateKey(opts.id, args);
-		const cached = await handler.get(key);
-		if (cached && !cached.stale) return cached.value;
-		const result = await singleflight.do(key, () => fn(...args));
-		const tags = resolveTags(opts, args);
-		await handler.set(key, result, {
-			ttl: opts.ttl,
-			tags
-		});
-		return result;
-	};
-}
+cache.invalidate = async function invalidate(opts) {
+	await getCacheHandler().invalidate(opts);
+};
 //#endregion
 //#region src/cache/index.ts
 var MemoryCacheHandler = class {
 	store = /* @__PURE__ */ new Map();
-	maxSize;
+	maxEntries;
+	maxBytes;
+	maxEntryBytes;
+	currentBytes = 0;
 	constructor(opts) {
-		this.maxSize = opts?.maxSize ?? 1e3;
+		this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1e3;
+		this.maxBytes = opts?.maxBytes;
+		this.maxEntryBytes = opts?.maxEntryBytes;
 	}
 	async get(key) {
 		const entry = this.store.get(key);
@@ -297,30 +315,60 @@ var MemoryCacheHandler = class {
 		};
 	}
 	async set(key, value, opts) {
-		if (this.store.has(key)) this.store.delete(key);
-		while (this.store.size >= this.maxSize) {
-			const oldest = this.store.keys().next().value;
-			if (oldest !== void 0) this.store.delete(oldest);
-			else break;
+		const byteSize = estimateByteSize(value);
+		if (this.maxEntryBytes !== void 0 && byteSize > this.maxEntryBytes) return;
+		if (this.store.has(key)) {
+			const existing = this.store.get(key);
+			this.currentBytes -= existing.byteSize;
+			this.store.delete(key);
+		}
+		while (this.store.size >= this.maxEntries) this.evictOldest();
+		if (this.maxBytes !== void 0) {
+			while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) this.evictOldest();
+			if (this.currentBytes + byteSize > this.maxBytes) return;
 		}
 		this.store.set(key, {
 			value,
 			expiresAt: Date.now() + opts.ttl * 1e3,
-			tags: opts.tags
+			tags: opts.tags,
+			byteSize
 		});
+		this.currentBytes += byteSize;
 	}
 	async invalidate(opts) {
-		if (opts.key) this.store.delete(opts.key);
+		if (opts.key) {
+			const entry = this.store.get(opts.key);
+			if (entry) {
+				this.currentBytes -= entry.byteSize;
+				this.store.delete(opts.key);
+			}
+		}
 		if (opts.tag) {
-			for (const [key, entry] of this.store) if (entry.tags.includes(opts.tag)) this.store.delete(key);
+			for (const [key, entry] of this.store) if (entry.tags.includes(opts.tag)) {
+				this.currentBytes -= entry.byteSize;
+				this.store.delete(key);
+			}
 		}
 	}
 	/** Number of entries currently in the cache. */
 	get size() {
 		return this.store.size;
 	}
+	/** Estimated total byte size of all cached values. */
+	get bytes() {
+		return this.currentBytes;
+	}
+	/** Evict the oldest entry (front of Map). */
+	evictOldest() {
+		const oldest = this.store.keys().next().value;
+		if (oldest !== void 0) {
+			const entry = this.store.get(oldest);
+			this.currentBytes -= entry.byteSize;
+			this.store.delete(oldest);
+		}
+	}
 };
 //#endregion
-export { MemoryCacheHandler, RedisCacheHandler, createCache, createSingleflight, registerCachedFunction, stableStringify };
+export { MemoryCacheHandler, RedisCacheHandler, cache, estimateByteSize, getCacheHandler, setCacheHandler };
 
 //# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/cache/redis-handler.ts","../../src/cache/stable-stringify.ts","../../src/cache/singleflight.ts","../../src/cache/fast-hash.ts","../../src/cache/timber-cache.ts","../../src/cache/register-cached-function.ts","../../src/cache/index.ts"],"sourcesContent":["import type { CacheHandler } from './index';\n\n/**\n * Minimal Redis client interface — compatible with ioredis, node-redis, and\n * Cloudflare Workers Redis bindings. We depend on the interface, not the\n * implementation, so users bring their own Redis client.\n */\nexport interface RedisClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;\n  del(key: string | string[]): Promise<number>;\n  sadd(key: string, ...members: string[]): Promise<number>;\n  smembers(key: string): Promise<string[]>;\n}\n\nconst KEY_PREFIX = 'timber:cache:';\nconst TAG_PREFIX = 'timber:tag:';\n\n/**\n * Redis-backed CacheHandler for distributed caching.\n *\n * All instances sharing the same Redis see each other's cache entries and\n * invalidations. Tag-based invalidation uses Redis Sets to track which keys\n * belong to which tags.\n *\n * Bring your own Redis client — any client implementing the RedisClient\n * interface works (ioredis, node-redis, @upstash/redis, etc.).\n */\nexport class RedisCacheHandler implements CacheHandler {\n  private client: RedisClient;\n  private prefix: string;\n\n  constructor(client: RedisClient, opts?: { prefix?: string }) {\n    this.client = client;\n    this.prefix = opts?.prefix ?? '';\n  }\n\n  private cacheKey(key: string): string {\n    return `${this.prefix}${KEY_PREFIX}${key}`;\n  }\n\n  private tagKey(tag: string): string {\n    return `${this.prefix}${TAG_PREFIX}${tag}`;\n  }\n\n  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {\n    const raw = await this.client.get(this.cacheKey(key));\n    if (raw === null) return null;\n\n    const entry = JSON.parse(raw) as { value: unknown; expiresAt: number };\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {\n    const ck = this.cacheKey(key);\n    const expiresAt = Date.now() + opts.ttl * 1000;\n    const payload = JSON.stringify({ value, expiresAt });\n\n    // Redis TTL with generous margin beyond the logical TTL to allow SWR reads\n    // on stale entries. The logical staleness is determined by expiresAt.\n    // We use 2x TTL + 60s as the Redis expiry so stale entries remain\n    // available for SWR background refetches.\n    const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);\n    await this.client.set(ck, payload, 'EX', redisTtlSeconds);\n\n    // Track key membership in each tag set\n    for (const tag of opts.tags) {\n      await this.client.sadd(this.tagKey(tag), key);\n    }\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n    if (opts.key) {\n      await this.client.del(this.cacheKey(opts.key));\n    }\n\n    if (opts.tag) {\n      const tk = this.tagKey(opts.tag);\n      const keys = await this.client.smembers(tk);\n\n      if (keys.length > 0) {\n        const cacheKeys = keys.map((k) => this.cacheKey(k));\n        await this.client.del(cacheKeys);\n      }\n\n      // Clean up the tag set itself\n      await this.client.del(tk);\n    }\n  }\n}\n","/**\n * Deterministic JSON serialization with sorted object keys.\n * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }\n * produce the same string.\n */\nexport function stableStringify(value: unknown): string {\n  if (value === null || value === undefined) return JSON.stringify(value);\n  if (typeof value !== 'object') return JSON.stringify(value);\n  if (Array.isArray(value)) {\n    return '[' + value.map((item) => stableStringify(item)).join(',') + ']';\n  }\n\n  const obj = value as Record<string, unknown>;\n  const keys = Object.keys(obj).sort();\n  const pairs: string[] = [];\n  for (const key of keys) {\n    if (obj[key] === undefined) continue;\n    pairs.push(JSON.stringify(key) + ':' + stableStringify(obj[key]));\n  }\n  return '{' + pairs.join(',') + '}';\n}\n","/**\n * Singleflight coalesces concurrent calls with the same key into a single\n * execution. All callers receive the same result (or error).\n *\n * Per-process, in-memory. Each process coalesces independently.\n */\nexport interface Singleflight {\n  do<T>(key: string, fn: () => Promise<T>): Promise<T>;\n}\n\nexport function createSingleflight(): Singleflight {\n  const inflight = new Map<string, Promise<unknown>>();\n\n  return {\n    do<T>(key: string, fn: () => Promise<T>): Promise<T> {\n      const existing = inflight.get(key);\n      if (existing) return existing as Promise<T>;\n\n      const promise = fn().finally(() => {\n        inflight.delete(key);\n      });\n      inflight.set(key, promise);\n      return promise;\n    },\n  };\n}\n","/**\n * Fast non-cryptographic hash for cache keys.\n *\n * FNV-1a 64-bit produces a well-distributed hash with a collision\n * probability of ~1 in 5 billion at 77k keys (birthday paradox).\n * Not suitable for security, but ideal for cache key generation\n * where we need speed over crypto strength.\n *\n * Uses BigInt for 64-bit arithmetic — supported in all modern runtimes\n * including Cloudflare Workers. No node:crypto dependency.\n *\n * See TIM-370.\n */\n\n// FNV-1a constants for 64-bit hash\nconst FNV_OFFSET_BASIS = 0xcbf29ce484222325n;\nconst FNV_PRIME = 0x100000001b3n;\nconst MASK_64 = 0xffffffffffffffffn;\n\n/**\n * Compute a 64-bit FNV-1a hash of a string, returned as a 16-char hex string.\n *\n * 64 bits gives ~5 billion keys before a 50% collision probability\n * (birthday paradox), making accidental collisions effectively impossible\n * for cache key use cases.\n */\nexport function fnv1aHash(input: string): string {\n  let hash = FNV_OFFSET_BASIS;\n  for (let i = 0; i < input.length; i++) {\n    hash ^= BigInt(input.charCodeAt(i));\n    hash = (hash * FNV_PRIME) & MASK_64;\n  }\n  return hash.toString(16).padStart(16, '0');\n}\n","import type { CacheHandler, CacheOptions } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { addSpanEventSync } from '#/server/tracing.js';\nimport { fnv1aHash } from './fast-hash.js';\n\nconst singleflight = createSingleflight();\n\n/**\n * Generate a cache key from function identity and serialized args.\n *\n * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't\n * need collision resistance — they need speed. The fnId prefix provides\n * namespace isolation; the hash covers the args.\n *\n * See TIM-370 for perf motivation.\n */\nfunction defaultKeyGenerator(fnId: string, args: unknown[]): string {\n  const raw = fnId + ':' + stableStringify(args);\n  return fnId + ':' + fnv1aHash(raw);\n}\n\n/**\n * Resolve tags from the options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: CacheOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\n// Counter for generating unique function IDs when no explicit key is provided.\nlet fnIdCounter = 0;\n\n/**\n * Creates a cached wrapper around an async function.\n *\n * - SHA-256 default keys with normalized JSON args\n * - Singleflight: concurrent misses → single execution\n * - SWR: serve stale immediately, background refetch\n * - Tags as string[] or function of args\n * - No ALS dependency\n *\n * Cache hits/misses are recorded as OTEL span events on the enclosing\n * span (not child spans). The DevSpanProcessor reads these for dev log output.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function createCache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>,\n  handler: CacheHandler\n): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {\n  const fnId = `timber-cache:${fnIdCounter++}`;\n\n  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);\n\n    const cacheStart = performance.now();\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      // Record as OTEL span event on enclosing span (not a child span).\n      // Fire-and-forget — no microtask overhead on the cache hot path.\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    if (cached && cached.stale && opts.staleWhileRevalidate) {\n      // Record stale cache hit as OTEL span event (fire-and-forget).\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n        stale: true,\n      });\n      // Serve stale immediately, trigger background refetch\n      singleflight\n        .do(`swr:${key}`, async () => {\n          try {\n            const fresh = await fn(...args);\n            const tags = resolveTags(opts, args);\n            await handler.set(key, fresh, { ttl: opts.ttl, tags });\n          } catch {\n            // Failed refetch — stale entry continues to be served.\n            // Error is swallowed per design doc: \"Error is logged.\"\n          }\n        })\n        .catch(() => {\n          // Singleflight promise rejection handled — stale continues.\n        });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss (or stale without SWR) — execute with singleflight\n    const result = await singleflight.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n\n    // Record cache miss as OTEL span event (fire-and-forget).\n    addSpanEventSync('timber.cache.miss', {\n      key,\n      duration_ms: Math.round(performance.now() - cacheStart),\n    });\n\n    return result as Awaited<ReturnType<Fn>>;\n  };\n}\n\n/**\n * Invalidate cache entries by tag or key.\n */\ncreateCache.invalidate = async function invalidate(\n  handler: CacheHandler,\n  opts: { key?: string; tag?: string }\n): Promise<void> {\n  await handler.invalidate(opts);\n};\n","import type { CacheHandler } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { fnv1aHash } from './fast-hash.js';\n\nconst singleflight = createSingleflight();\n\n// Prop names that suggest request-specific data — triggers dev warning for \"use cache\" components.\nconst REQUEST_SPECIFIC_PROPS = new Set([\n  'cookies',\n  'cookie',\n  'session',\n  'sessionId',\n  'token',\n  'authorization',\n  'auth',\n  'headers',\n]);\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface RegisterCachedFunctionOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  id: string;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** True when the cached function is a React component (PascalCase name). */\n  isComponent?: boolean;\n}\n\n/**\n * Generate a cache key from a stable function ID and serialized args.\n *\n * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. The id prefix\n * provides namespace isolation; the hash covers the args.\n * See TIM-370.\n */\nfunction generateKey(id: string, args: unknown[]): string {\n  const raw = id + ':' + stableStringify(args);\n  return id + ':' + fnv1aHash(raw);\n}\n\n/**\n * Resolve tags from options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: RegisterCachedFunctionOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\n/**\n * Checks if component props contain request-specific keys and emits a dev warning.\n * Only runs when process.env.NODE_ENV !== 'production'.\n */\nfunction warnRequestSpecificProps(id: string, props: unknown): void {\n  if (typeof props !== 'object' || props === null) return;\n  const keys = Object.keys(props);\n  const suspicious = keys.filter((k) => REQUEST_SPECIFIC_PROPS.has(k.toLowerCase()));\n  if (suspicious.length > 0) {\n    console.warn(\n      `[timber] \"use cache\" component ${id} received request-specific props: ${suspicious.join(', ')}. ` +\n        `This may serve one user's cached render to another user. ` +\n        `Remove request-specific data from props or remove \"use cache\".`\n    );\n  }\n}\n\n/**\n * Runtime for the \"use cache\" directive transform. Wraps an async function\n * with caching using the same cache handler as timber.cache.\n *\n * The stable `id` (file path + function name) ensures cache keys are consistent\n * across builds. Args/props are hashed with SHA-256 for the per-call key.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerCachedFunction<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: RegisterCachedFunctionOptions<Fn>,\n  handler: CacheHandler\n): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {\n  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    // Dev-mode warning for components with request-specific props\n    if (opts.isComponent && process.env.NODE_ENV !== 'production' && args.length > 0) {\n      warnRequestSpecificProps(opts.id, args[0]);\n    }\n\n    const key = generateKey(opts.id, args);\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss or stale — execute with singleflight\n    const result = await singleflight.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n    return result as Awaited<ReturnType<Fn>>;\n  };\n}\n","// @timber-js/app/cache — Caching primitives\n\nexport interface CacheHandler {\n  get(key: string): Promise<{ value: unknown; stale: boolean } | null>;\n  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;\n  invalidate(opts: { key?: string; tag?: string }): Promise<void>;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface CacheOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  key?: (...args: Parameters<Fn>) => string;\n  staleWhileRevalidate?: boolean;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n}\n\nexport interface MemoryCacheHandlerOptions {\n  /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */\n  maxSize?: number;\n}\n\nexport class MemoryCacheHandler implements CacheHandler {\n  private store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();\n  private maxSize: number;\n\n  constructor(opts?: MemoryCacheHandlerOptions) {\n    this.maxSize = opts?.maxSize ?? 1000;\n  }\n\n  async get(key: string) {\n    const entry = this.store.get(key);\n    if (!entry) return null;\n\n    // Move to end of Map (most recently used) for LRU ordering\n    this.store.delete(key);\n    this.store.set(key, entry);\n\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {\n    // If key already exists, delete first to refresh insertion order\n    if (this.store.has(key)) {\n      this.store.delete(key);\n    }\n\n    // Evict oldest entries (front of Map) if at capacity\n    while (this.store.size >= this.maxSize) {\n      const oldest = this.store.keys().next().value;\n      if (oldest !== undefined) {\n        this.store.delete(oldest);\n      } else {\n        break;\n      }\n    }\n\n    this.store.set(key, {\n      value,\n      expiresAt: Date.now() + opts.ttl * 1000,\n      tags: opts.tags,\n    });\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }) {\n    if (opts.key) {\n      this.store.delete(opts.key);\n    }\n    if (opts.tag) {\n      for (const [key, entry] of this.store) {\n        if (entry.tags.includes(opts.tag)) {\n          this.store.delete(key);\n        }\n      }\n    }\n  }\n\n  /** Number of entries currently in the cache. */\n  get size(): number {\n    return this.store.size;\n  }\n}\n\nexport { RedisCacheHandler } from './redis-handler';\nexport type { RedisClient } from './redis-handler';\nexport { createCache } from './timber-cache';\nexport { registerCachedFunction } from './register-cached-function';\nexport type { RegisterCachedFunctionOptions } from './register-cached-function';\nexport { stableStringify } from './stable-stringify';\nexport { createSingleflight } from './singleflight';\nexport type { Singleflight } from './singleflight';\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/cache/sizeof.ts","../../src/cache/redis-handler.ts","../../src/cache/stable-stringify.ts","../../src/cache/singleflight.ts","../../src/cache/timber-cache.ts","../../src/cache/cache-api.ts","../../src/cache/index.ts"],"sourcesContent":["/**\n * Lightweight byte-size estimation for cache entries.\n *\n * Estimates the in-memory byte cost of a JavaScript value using\n * JSON.stringify().length * 2 (UTF-16 char width). This is a rough\n * approximation — it doesn't account for V8 object overhead, Map\n * metadata, or non-serializable values — but it's fast and good\n * enough for cache budget enforcement.\n *\n * Values that fail JSON serialization (circular references, BigInt,\n * etc.) return 0, allowing the entry to be cached without counting\n * toward the byte budget. This is a conservative choice: it's better\n * to cache and undercount than to reject the entry.\n */\n\n/**\n * Estimate the byte size of a value.\n *\n * Uses `JSON.stringify(value).length * 2` to approximate UTF-16\n * in-memory size. Returns 0 if the value is not serializable.\n */\nexport function estimateByteSize(value: unknown): number {\n  try {\n    const json = JSON.stringify(value);\n    if (json === undefined) return 0;\n    // Each JS string character is 2 bytes (UTF-16)\n    return json.length * 2;\n  } catch (e) {\n    // Circular reference or non-serializable value\n    console.debug('[timber] sizeof estimation failed:', e instanceof Error ? e.message : e);\n    return 0;\n  }\n}\n","import type { CacheHandler } from './index';\n\n/**\n * Minimal Redis client interface — compatible with ioredis, node-redis, and\n * Cloudflare Workers Redis bindings. We depend on the interface, not the\n * implementation, so users bring their own Redis client.\n */\nexport interface RedisClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;\n  del(key: string | string[]): Promise<number>;\n  sadd(key: string, ...members: string[]): Promise<number>;\n  smembers(key: string): Promise<string[]>;\n}\n\nconst KEY_PREFIX = 'timber:cache:';\nconst TAG_PREFIX = 'timber:tag:';\n\n/**\n * Redis-backed CacheHandler for distributed caching.\n *\n * All instances sharing the same Redis see each other's cache entries and\n * invalidations. Tag-based invalidation uses Redis Sets to track which keys\n * belong to which tags.\n *\n * Bring your own Redis client — any client implementing the RedisClient\n * interface works (ioredis, node-redis, @upstash/redis, etc.).\n */\nexport class RedisCacheHandler implements CacheHandler {\n  private client: RedisClient;\n  private prefix: string;\n\n  constructor(client: RedisClient, opts?: { prefix?: string }) {\n    this.client = client;\n    this.prefix = opts?.prefix ?? '';\n  }\n\n  private cacheKey(key: string): string {\n    return `${this.prefix}${KEY_PREFIX}${key}`;\n  }\n\n  private tagKey(tag: string): string {\n    return `${this.prefix}${TAG_PREFIX}${tag}`;\n  }\n\n  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {\n    const raw = await this.client.get(this.cacheKey(key));\n    if (raw === null) return null;\n\n    const entry = JSON.parse(raw) as { value: unknown; expiresAt: number };\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {\n    const ck = this.cacheKey(key);\n    const expiresAt = Date.now() + opts.ttl * 1000;\n    const payload = JSON.stringify({ value, expiresAt });\n\n    // Redis TTL with generous margin beyond the logical TTL to allow SWR reads\n    // on stale entries. The logical staleness is determined by expiresAt.\n    // We use 2x TTL + 60s as the Redis expiry so stale entries remain\n    // available for SWR background refetches.\n    const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);\n    await this.client.set(ck, payload, 'EX', redisTtlSeconds);\n\n    // Track key membership in each tag set\n    for (const tag of opts.tags) {\n      await this.client.sadd(this.tagKey(tag), key);\n    }\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n    if (opts.key) {\n      await this.client.del(this.cacheKey(opts.key));\n    }\n\n    if (opts.tag) {\n      const tk = this.tagKey(opts.tag);\n      const keys = await this.client.smembers(tk);\n\n      if (keys.length > 0) {\n        const cacheKeys = keys.map((k) => this.cacheKey(k));\n        await this.client.del(cacheKeys);\n      }\n\n      // Clean up the tag set itself\n      await this.client.del(tk);\n    }\n  }\n}\n","/**\n * Deterministic JSON serialization with sorted object keys.\n * Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }\n * produce the same string.\n */\nexport function stableStringify(value: unknown): string {\n  if (value === null || value === undefined) return JSON.stringify(value);\n  if (typeof value !== 'object') return JSON.stringify(value);\n  if (Array.isArray(value)) {\n    return '[' + value.map((item) => stableStringify(item)).join(',') + ']';\n  }\n\n  const obj = value as Record<string, unknown>;\n  const keys = Object.keys(obj).sort();\n  const pairs: string[] = [];\n  for (const key of keys) {\n    if (obj[key] === undefined) continue;\n    pairs.push(JSON.stringify(key) + ':' + stableStringify(obj[key]));\n  }\n  return '{' + pairs.join(',') + '}';\n}\n","/**\n * Singleflight coalesces concurrent calls with the same key into a single\n * execution. All callers receive the same result (or error).\n *\n * Per-process, in-memory. Each process coalesces independently.\n *\n * An optional `timeoutMs` prevents hung `fn()` calls from permanently\n * blocking all future callers for that key. When set, `fn()` is raced\n * against a timeout — if the timeout fires first, the promise rejects\n * with `SingleflightTimeoutError`, `finally` cleans up the key, and\n * subsequent callers can retry. See TIM-518.\n */\n\nexport interface SingleflightOptions {\n  /** Maximum time (ms) a coalesced call may run before being rejected. */\n  timeoutMs?: number;\n}\n\nexport interface Singleflight {\n  do<T>(key: string, fn: () => Promise<T>): Promise<T>;\n}\n\n/**\n * Error thrown when a singleflight call exceeds `timeoutMs`.\n * Exported so callers can distinguish timeout from other errors.\n */\nexport class SingleflightTimeoutError extends Error {\n  constructor(key: string, timeoutMs: number) {\n    super(`Singleflight timeout: key \"${key}\" exceeded ${timeoutMs}ms`);\n    this.name = 'SingleflightTimeoutError';\n  }\n}\n\nexport function createSingleflight(opts?: SingleflightOptions): Singleflight {\n  const inflight = new Map<string, Promise<unknown>>();\n  const timeoutMs = opts?.timeoutMs;\n\n  return {\n    do<T>(key: string, fn: () => Promise<T>): Promise<T> {\n      const existing = inflight.get(key);\n      if (existing) return existing as Promise<T>;\n\n      let promise: Promise<T>;\n\n      if (timeoutMs != null && timeoutMs > 0) {\n        // Race fn() against a timeout to prevent hung calls from\n        // permanently blocking the key. See TIM-518.\n        promise = new Promise<T>((resolve, reject) => {\n          const timer = setTimeout(\n            () => reject(new SingleflightTimeoutError(key, timeoutMs)),\n            timeoutMs\n          );\n          // Wrap in try/catch so a synchronous throw from fn()\n          // (e.g. argument validation) still clears the timer.\n          // Without this, the timer leaks until expiry.\n          try {\n            fn().then(\n              (value) => {\n                clearTimeout(timer);\n                resolve(value);\n              },\n              (err) => {\n                clearTimeout(timer);\n                reject(err);\n              }\n            );\n          } catch (err) {\n            clearTimeout(timer);\n            reject(err);\n          }\n        });\n      } else {\n        promise = fn();\n      }\n\n      const tracked = promise.finally(() => {\n        inflight.delete(key);\n      });\n\n      inflight.set(key, tracked);\n      return tracked as Promise<T>;\n    },\n  };\n}\n","import type { CacheHandler, CacheOptions } from './index';\nimport { stableStringify } from './stable-stringify';\nimport { createSingleflight } from './singleflight';\nimport { addSpanEventSync } from '../server/tracing.js';\nimport { logSwrRefetchFailed } from '../server/logger.js';\nimport { fnv1aHash } from './fast-hash.js';\n\nconst defaultSingleflight = createSingleflight();\n\n/**\n * Generate a cache key from function identity and serialized args.\n *\n * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't\n * need collision resistance — they need speed. The fnId prefix provides\n * namespace isolation; the hash covers the args.\n *\n * See TIM-370 for perf motivation.\n */\nfunction defaultKeyGenerator(fnId: string, args: unknown[]): string {\n  const raw = fnId + ':' + stableStringify(args);\n  return fnId + ':' + fnv1aHash(raw);\n}\n\n/**\n * Resolve tags from the options — supports static array or function form.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction resolveTags<Fn extends (...args: any[]) => any>(\n  opts: CacheOptions<Fn>,\n  args: Parameters<Fn>\n): string[] {\n  if (!opts.tags) return [];\n  if (Array.isArray(opts.tags)) return opts.tags;\n  return opts.tags(...args);\n}\n\nlet unstableIdCounter = 0;\nlet hasWarnedUnstableId = false;\n\n/**\n * Creates a cached wrapper around an async function.\n *\n * - SHA-256 default keys with normalized JSON args\n * - Singleflight: concurrent misses → single execution\n * - SWR: serve stale immediately, background refetch\n * - Tags as string[] or function of args\n * - No ALS dependency\n *\n * Cache hits/misses are recorded as OTEL span events on the enclosing\n * span (not child spans). The DevSpanProcessor reads these for dev log output.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function createCache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>,\n  handler: CacheHandler,\n  stableId?: string\n): Fn {\n  let fnId: string;\n  if (stableId) {\n    fnId = stableId;\n  } else if (opts.key) {\n    // Explicit key function — fnId is only used for singleflight, not for\n    // cache keys, so a counter is acceptable here.\n    fnId = `timber-cache:${unstableIdCounter++}`;\n  } else {\n    fnId = `timber-cache:unstable:${unstableIdCounter++}`;\n    if (\n      !hasWarnedUnstableId &&\n      typeof process !== 'undefined' &&\n      process.env?.NODE_ENV !== 'test'\n    ) {\n      hasWarnedUnstableId = true;\n      console.warn(\n        '[timber] cache() called without a stable ID or explicit key function. ' +\n          'Cache keys will use a process-local counter which is unstable across ' +\n          'cold starts. Run through the timber Vite plugin or provide an explicit ' +\n          '`key` option to fix this.'\n      );\n    }\n  }\n  const sf = opts.timeoutMs\n    ? createSingleflight({ timeoutMs: opts.timeoutMs })\n    : defaultSingleflight;\n\n  // Cast to Fn to preserve the original function's generic call signature.\n  // Without this, generic type parameters (e.g. <T> in apiFetch<T>) are\n  // erased and callers lose type safety on the return type.\n  return (async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {\n    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);\n\n    const cacheStart = performance.now();\n    const cached = await handler.get(key);\n\n    if (cached && !cached.stale) {\n      // Record as OTEL span event on enclosing span (not a child span).\n      // Fire-and-forget — no microtask overhead on the cache hot path.\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    if (cached && cached.stale && opts.staleWhileRevalidate) {\n      // Record stale cache hit as OTEL span event (fire-and-forget).\n      addSpanEventSync('timber.cache.hit', {\n        key,\n        duration_ms: Math.round(performance.now() - cacheStart),\n        stale: true,\n      });\n      // Serve stale immediately, trigger background refetch\n      sf.do(`swr:${key}`, async () => {\n        try {\n          const fresh = await fn(...args);\n          const tags = resolveTags(opts, args);\n          await handler.set(key, fresh, { ttl: opts.ttl, tags });\n        } catch (err) {\n          // Failed refetch — stale entry continues to be served.\n          logSwrRefetchFailed({ cacheKey: key, error: err });\n        }\n      }).catch(() => {\n        // Singleflight promise rejection handled — stale continues.\n      });\n      return cached.value as Awaited<ReturnType<Fn>>;\n    }\n\n    // Cache miss (or stale without SWR) — execute with singleflight\n    const result = await sf.do(key, () => fn(...args));\n    const tags = resolveTags(opts, args);\n    await handler.set(key, result, { ttl: opts.ttl, tags });\n\n    // Record cache miss as OTEL span event (fire-and-forget).\n    addSpanEventSync('timber.cache.miss', {\n      key,\n      duration_ms: Math.round(performance.now() - cacheStart),\n    });\n\n    return result as Awaited<ReturnType<Fn>>;\n  }) as unknown as Fn;\n}\n\n/**\n * Invalidate cache entries by tag or key.\n */\ncreateCache.invalidate = async function invalidate(\n  handler: CacheHandler,\n  opts: { key?: string; tag?: string }\n): Promise<void> {\n  await handler.invalidate(opts);\n};\n","import type { CacheOptions } from './index';\nimport { createCache } from './timber-cache';\nimport { getCacheHandler } from './handler-store';\n\n/**\n * Public caching API: `cache(fn, opts)`.\n *\n * Wraps an async function with cross-request caching. Uses the configured\n * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).\n *\n * ```ts\n * import { cache } from '@timber-js/app/cache';\n *\n * const getUser = cache(\n *   async (id: string) => db.users.findUnique({ where: { id } }),\n *   { ttl: 60, tags: (id) => [`user:${id}`] }\n * );\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function cache<Fn extends (...args: any[]) => Promise<any>>(\n  fn: Fn,\n  opts: CacheOptions<Fn>,\n  stableId?: string\n): Fn {\n  return createCache(fn, opts, getCacheHandler(), stableId);\n}\n\n/**\n * Invalidate cache entries by tag or key.\n *\n * ```ts\n * cache.invalidate({ tag: 'products' });\n * cache.invalidate({ key: 'user:abc' });\n * ```\n */\ncache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n  await getCacheHandler().invalidate(opts);\n};\n","// @timber-js/app/cache — Caching primitives\n\nimport { estimateByteSize } from './sizeof.js';\n\nexport interface CacheHandler {\n  get(key: string): Promise<{ value: unknown; stale: boolean } | null>;\n  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;\n  invalidate(opts: { key?: string; tag?: string }): Promise<void>;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface CacheOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  key?: (...args: Parameters<Fn>) => string;\n  staleWhileRevalidate?: boolean;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** Timeout (ms) for singleflight-coalesced calls. Prevents hung fn() from\n   *  permanently blocking all future callers for the same cache key. See TIM-518. */\n  timeoutMs?: number;\n}\n\nexport interface MemoryCacheHandlerOptions {\n  /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */\n  maxEntries?: number;\n  /**\n   * @deprecated Use `maxEntries` instead. Will be removed in a future release.\n   * Alias for `maxEntries` — maximum number of entries (not bytes).\n   */\n  maxSize?: number;\n  /** Maximum total byte budget for all cached values. Oldest entries are evicted when exceeded. Default: no limit. */\n  maxBytes?: number;\n  /** Maximum byte size for a single cache entry. Entries exceeding this are silently dropped. Default: no limit. */\n  maxEntryBytes?: number;\n}\n\nexport class MemoryCacheHandler implements CacheHandler {\n  private store = new Map<\n    string,\n    { value: unknown; expiresAt: number; tags: string[]; byteSize: number }\n  >();\n  private maxEntries: number;\n  private maxBytes: number | undefined;\n  private maxEntryBytes: number | undefined;\n  private currentBytes = 0;\n\n  constructor(opts?: MemoryCacheHandlerOptions) {\n    // maxEntries takes precedence over deprecated maxSize\n    this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1000;\n    this.maxBytes = opts?.maxBytes;\n    this.maxEntryBytes = opts?.maxEntryBytes;\n  }\n\n  async get(key: string) {\n    const entry = this.store.get(key);\n    if (!entry) return null;\n\n    // Move to end of Map (most recently used) for LRU ordering\n    this.store.delete(key);\n    this.store.set(key, entry);\n\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {\n    const byteSize = estimateByteSize(value);\n\n    // Reject entries exceeding per-entry byte limit\n    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) {\n      return;\n    }\n\n    // If key already exists, delete first to refresh insertion order and reclaim bytes\n    if (this.store.has(key)) {\n      const existing = this.store.get(key)!;\n      this.currentBytes -= existing.byteSize;\n      this.store.delete(key);\n    }\n\n    // Evict oldest entries (front of Map) if at entry count capacity\n    while (this.store.size >= this.maxEntries) {\n      this.evictOldest();\n    }\n\n    // Evict oldest entries if byte budget would be exceeded\n    if (this.maxBytes !== undefined) {\n      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {\n        this.evictOldest();\n      }\n      // If the single entry exceeds the total byte budget, don't store it\n      if (this.currentBytes + byteSize > this.maxBytes) {\n        return;\n      }\n    }\n\n    this.store.set(key, {\n      value,\n      expiresAt: Date.now() + opts.ttl * 1000,\n      tags: opts.tags,\n      byteSize,\n    });\n    this.currentBytes += byteSize;\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }) {\n    if (opts.key) {\n      const entry = this.store.get(opts.key);\n      if (entry) {\n        this.currentBytes -= entry.byteSize;\n        this.store.delete(opts.key);\n      }\n    }\n    if (opts.tag) {\n      for (const [key, entry] of this.store) {\n        if (entry.tags.includes(opts.tag)) {\n          this.currentBytes -= entry.byteSize;\n          this.store.delete(key);\n        }\n      }\n    }\n  }\n\n  /** Number of entries currently in the cache. */\n  get size(): number {\n    return this.store.size;\n  }\n\n  /** Estimated total byte size of all cached values. */\n  get bytes(): number {\n    return this.currentBytes;\n  }\n\n  /** Evict the oldest entry (front of Map). */\n  private evictOldest(): void {\n    const oldest = this.store.keys().next().value;\n    if (oldest !== undefined) {\n      const entry = this.store.get(oldest)!;\n      this.currentBytes -= entry.byteSize;\n      this.store.delete(oldest);\n    }\n  }\n}\n\nexport { RedisCacheHandler } from './redis-handler';\nexport type { RedisClient } from './redis-handler';\nexport { cache } from './cache-api';\nexport { setCacheHandler, getCacheHandler } from './handler-store';\n// NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.\n// Future feature pending design doc. See design/06-caching.md.\nexport { estimateByteSize } from './sizeof';\n// stableStringify, createSingleflight, and SingleflightTimeoutError are\n// internal utilities used by the cache implementation. They are not\n// re-exported here — import directly from the source files if needed\n// within the package. See TIM-720.\n"],"mappings":"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"}

package/dist/cache/singleflight.d.ts

@@ -3,9 +3,26 @@
  * execution. All callers receive the same result (or error).
  *
  * Per-process, in-memory. Each process coalesces independently.
+ *
+ * An optional `timeoutMs` prevents hung `fn()` calls from permanently
+ * blocking all future callers for that key. When set, `fn()` is raced
+ * against a timeout — if the timeout fires first, the promise rejects
+ * with `SingleflightTimeoutError`, `finally` cleans up the key, and
+ * subsequent callers can retry. See TIM-518.
  */
+export interface SingleflightOptions {
+    /** Maximum time (ms) a coalesced call may run before being rejected. */
+    timeoutMs?: number;
+}
 export interface Singleflight {
     do<T>(key: string, fn: () => Promise<T>): Promise<T>;
 }
-export declare function createSingleflight(): Singleflight;
+/**
+ * Error thrown when a singleflight call exceeds `timeoutMs`.
+ * Exported so callers can distinguish timeout from other errors.
+ */
+export declare class SingleflightTimeoutError extends Error {
+    constructor(key: string, timeoutMs: number);
+}
+export declare function createSingleflight(opts?: SingleflightOptions): Singleflight;
 //# sourceMappingURL=singleflight.d.ts.map

package/dist/cache/singleflight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"singleflight.d.ts","sourceRoot":"","sources":["../../src/cache/singleflight.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACtD;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAejD"}
+{"version":3,"file":"singleflight.d.ts","sourceRoot":"","sources":["../../src/cache/singleflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACtD;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAI3C;AAED,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAkD3E"}

package/dist/cache/sizeof.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Lightweight byte-size estimation for cache entries.
+ *
+ * Estimates the in-memory byte cost of a JavaScript value using
+ * JSON.stringify().length * 2 (UTF-16 char width). This is a rough
+ * approximation — it doesn't account for V8 object overhead, Map
+ * metadata, or non-serializable values — but it's fast and good
+ * enough for cache budget enforcement.
+ *
+ * Values that fail JSON serialization (circular references, BigInt,
+ * etc.) return 0, allowing the entry to be cached without counting
+ * toward the byte budget. This is a conservative choice: it's better
+ * to cache and undercount than to reject the entry.
+ */
+/**
+ * Estimate the byte size of a value.
+ *
+ * Uses `JSON.stringify(value).length * 2` to approximate UTF-16
+ * in-memory size. Returns 0 if the value is not serializable.
+ */
+export declare function estimateByteSize(value: unknown): number;
+//# sourceMappingURL=sizeof.d.ts.map

package/dist/cache/sizeof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sizeof.d.ts","sourceRoot":"","sources":["../../src/cache/sizeof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWvD"}

package/dist/cache/timber-cache.d.ts

@@ -11,7 +11,7 @@ import type { CacheHandler, CacheOptions } from './index';
  * Cache hits/misses are recorded as OTEL span events on the enclosing
  * span (not child spans). The DevSpanProcessor reads these for dev log output.
  */
-export declare function createCache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, handler: CacheHandler): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>>;
+export declare function createCache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, handler: CacheHandler, stableId?: string): Fn;
 export declare namespace createCache {
     var invalidate: (handler: CacheHandler, opts: {
         key?: string;

package/dist/cache/timber-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timber-cache.d.ts","sourceRoot":"","sources":["../../src/cache/timber-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAsC1D;;;;;;;;;;;GAWG;AAEH,wBAAgB,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACrE,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EACtB,OAAO,EAAE,YAAY,GACpB,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAyD/D;yBA7De,WAAW;8BAmEhB,YAAY,QACf;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC"}
+{"version":3,"file":"timber-cache.d.ts","sourceRoot":"","sources":["../../src/cache/timber-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAuC1D;;;;;;;;;;;GAWG;AAEH,wBAAgB,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACrE,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EACtB,OAAO,EAAE,YAAY,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,EAAE,CAmFJ;yBAxFe,WAAW;8BA8FhB,YAAY,QACf;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC"}

package/dist/cli-schema-sync.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, append
+ * missing entries with `codec.string` defaults, and remove stale entries
+ * whose segments no longer exist in the filesystem.
+ *
+ * Design doc: design/41-global-params.md §Auto-Scaffolding
+ */
+/**
+ * Collect all unique bracket-keyed dynamic segment names from the route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export declare function collectDynamicSegments(appDir: string): string[];
+/**
+ * Parse existing bracket keys from an app/schema.ts file.
+ * Uses regex to find keys in segmentParams: { '[key]': ... } blocks.
+ */
+export declare function parseExistingSchemaKeys(content: string): string[];
+/**
+ * Find the schema file path if it exists.
+ */
+export declare function findSchemaFile(appDir: string): string | undefined;
+export declare function defaultCodecForSegment(seg: string): string;
+export interface SchemaSyncResult {
+    /** Segments found in the filesystem. */
+    filesystemSegments: string[];
+    /** Segments already defined in app/schema.ts. */
+    existingSegments: string[];
+    /** Segments that were added. */
+    addedSegments: string[];
+    /** Segments that were removed (no longer in filesystem). */
+    removedSegments: string[];
+    /** Whether a new schema file was created. */
+    created: boolean;
+}
+/**
+ * Run the schema sync: scan filesystem, diff against schema, append missing.
+ */
+export declare function runSchemaSync(projectRoot: string): SchemaSyncResult;
+//# sourceMappingURL=cli-schema-sync.d.ts.map

package/dist/cli-schema-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-schema-sync.d.ts","sourceRoot":"","sources":["../src/cli-schema-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/D;AAeD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CASjE;AAKD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMjE;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAiJD,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gCAAgC;IAChC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4DAA4D;IAC5D,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CA8DnE"}