@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.91

package/dist/cache/index.js

@@ -1,5 +1,35 @@
-import "../_chunks/als-registry-B7DbZ2hS.js";
-import { n as addSpanEventSync } from "../_chunks/tracing-CemImE6h.js";
+import { f as getCacheHandler, n as addSpanEventSync, p as setCacheHandler } from "../_chunks/tracing-CCYbKn5n.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 {
+		return 0;
+	}
+}
+//#endregion
 //#region src/cache/redis-handler.ts
 var KEY_PREFIX = "timber:cache:";
 var TAG_PREFIX = "timber:tag:";
@@ -82,16 +112,44 @@ 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
@@ -129,7 +187,7 @@ function fnv1aHash(input) {
 }
 //#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,7 +204,7 @@ 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);
@@ -166,7 +224,8 @@ var fnIdCounter = 0;
 */
 function createCache(fn, opts, handler) {
 	const fnId = `timber-cache:${fnIdCounter++}`;
-	return async (...args) => {
+	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,10 +242,10 @@ 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
@@ -195,8 +254,8 @@ function createCache(fn, opts, handler) {
 			}).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 +265,7 @@ function createCache(fn, opts, handler) {
 			duration_ms: Math.round(performance.now() - cacheStart)
 		});
 		return result;
-	};
+	});
 }
 /**
 * Invalidate cache entries by tag or key.
@@ -215,75 +274,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) {
+	return createCache(fn, opts, getCacheHandler());
 }
 /**
-* 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 +329,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/fast-hash.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 {\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","/**\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 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\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): Fn {\n  const fnId = `timber-cache:${fnIdCounter++}`;\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 {\n          // Failed refetch — stale entry continues to be served.\n          // Error is swallowed per design doc: \"Error is logged.\"\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): Fn {\n  return createCache(fn, opts, getCacheHandler());\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,CASvD"}

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): 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;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,EAAE,CA6DJ;yBAjEe,WAAW;8BAuEhB,YAAY,QACf;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC"}

package/dist/cli.d.ts

@@ -21,7 +21,12 @@ export interface ViteDeps {
 }
 /**
  * Start the Vite dev server.
- * Middleware re-runs on file change via HMR wiring in timber-routing.
+ *
+ * The timber plugin binds the port immediately with a holding page
+ * (in rootSync's config hook) so browsers see a "starting..." page
+ * instead of ERR_CONNECTION_REFUSED during initialization.
+ *
+ * See design/21-dev-server.md, TIM-665.
  */
 export declare function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void>;
 /**

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAaA,QAAA,MAAM,QAAQ,+CAAgD,CAAC;AAC/D,KAAK,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuBpD;AAID,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,YAAY,CAAC,EAAE,cAAc,MAAM,EAAE,YAAY,CAAC;IAClD,aAAa,CAAC,EAAE,cAAc,MAAM,EAAE,aAAa,CAAC;IACpD,OAAO,CAAC,EAAE,cAAc,MAAM,EAAE,OAAO,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,SAAS,GACpE,SAAS,GAAG,MAAM,CAKpB;AA2BD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBzF;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAaA,QAAA,MAAM,QAAQ,+CAAgD,CAAC;AAC/D,KAAK,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuBpD;AAID,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,YAAY,CAAC,EAAE,cAAc,MAAM,EAAE,YAAY,CAAC;IAClD,aAAa,CAAC,EAAE,cAAc,MAAM,EAAE,aAAa,CAAC;IACpD,OAAO,CAAC,EAAE,cAAc,MAAM,EAAE,OAAO,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,SAAS,GACpE,SAAS,GAAG,MAAM,CAKpB;AA6BD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBzF;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE"}

package/dist/cli.js

@@ -26,7 +26,12 @@ function parseArgs(args) {
 }
 /**
 * Start the Vite dev server.
-* Middleware re-runs on file change via HMR wiring in timber-routing.
+*
+* The timber plugin binds the port immediately with a holding page
+* (in rootSync's config hook) so browsers see a "starting..." page
+* instead of ERR_CONNECTION_REFUSED during initialization.
+*
+* See design/21-dev-server.md, TIM-665.
 */
 async function runDev(options, _deps) {
 	const server = await (_deps?.createServer ?? (await import("vite")).createServer)({ configFile: options.config });
@@ -77,12 +82,12 @@ async function loadTimberConfig(root) {
 * Otherwise falls back to Vite's built-in preview server.
 */
 async function runPreview(options, _deps) {
-	const { join } = await import("node:path");
+	const { join, resolve } = await import("node:path");
 	const root = process.cwd();
 	const config = await loadTimberConfig(root).catch(() => null);
 	const adapter = config?.adapter;
 	if (resolvePreviewStrategy(adapter) === "adapter") {
-		const buildDir = join(root, "dist");
+		const buildDir = config?.buildDir ? resolve(root, config.buildDir) : join(root, ".timber", "dist");
 		const timberConfig = { output: config?.output ?? "server" };
 		await adapter.preview(timberConfig, buildDir);
 		return;

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n// timber.js CLI\n//\n// Wraps Vite commands with timber-specific behavior.\n// See design/18-build-system.md §\"CLI\".\n//\n// Commands:\n//   timber dev      — Start Vite dev server with HMR\n//   timber build    — Run multi-environment build via createBuilder/buildApp\n//   timber preview  — Serve the production build\n//   timber check    — Validate types + routes without building\n\nconst COMMANDS = ['dev', 'build', 'preview', 'check'] as const;\ntype Command = (typeof COMMANDS)[number];\n\nexport interface ParsedArgs {\n  command: Command;\n  config: string | undefined;\n}\n\nexport interface CommandOptions {\n  config?: string;\n}\n\n/**\n * Parse CLI arguments into a structured command + options.\n * Accepts: timber <command> [--config|-c <path>]\n */\nexport function parseArgs(args: string[]): ParsedArgs {\n  if (args.length === 0) {\n    throw new Error(\n      'No command provided. Usage: timber <dev|build|preview|check> [--config <path>]'\n    );\n  }\n\n  const command = args[0];\n  if (!COMMANDS.includes(command as Command)) {\n    throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(', ')}`);\n  }\n\n  let config: string | undefined;\n  for (let i = 1; i < args.length; i++) {\n    if (args[i] === '--config' || args[i] === '-c') {\n      config = args[++i];\n      if (!config) {\n        throw new Error('--config requires a path argument');\n      }\n    }\n  }\n\n  return { command: command as Command, config };\n}\n\n// ─── Command Implementations ─────────────────────────────────────────────────\n\n/** @internal Dependency injection for testing. */\nexport interface ViteDeps {\n  createServer?: typeof import('vite').createServer;\n  createBuilder?: typeof import('vite').createBuilder;\n  preview?: typeof import('vite').preview;\n}\n\n/**\n * Start the Vite dev server.\n * Middleware re-runs on file change via HMR wiring in timber-routing.\n */\nexport async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createServer = _deps?.createServer ?? (await import('vite')).createServer;\n  const server = await createServer({\n    configFile: options.config,\n  });\n  await server.listen();\n  server.printUrls();\n}\n\n/**\n * Run the production build using createBuilder + buildApp.\n * Direct build() calls do NOT trigger the RSC plugin's multi-environment\n * pipeline — createBuilder/buildApp is required.\n */\nexport async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createBuilder = _deps?.createBuilder ?? (await import('vite')).createBuilder;\n  const builder = await createBuilder({\n    configFile: options.config,\n  });\n  await builder.buildApp();\n}\n\n/**\n * Determine whether to use the adapter's preview or Vite's built-in preview.\n * Exported for testing — the actual runPreview function uses this internally.\n */\nexport function resolvePreviewStrategy(\n  adapter: import('./adapters/types').TimberPlatformAdapter | undefined\n): 'adapter' | 'vite' {\n  if (adapter && typeof adapter.preview === 'function') {\n    return 'adapter';\n  }\n  return 'vite';\n}\n\n/**\n * Load timber.config.ts from the project root.\n * Returns the config object with adapter, output, etc.\n * Returns null if no config file is found.\n */\nasync function loadTimberConfig(\n  root: string\n): Promise<{ adapter?: import('./adapters/types').TimberPlatformAdapter; output?: string } | null> {\n  const { existsSync } = await import('node:fs');\n  const { join } = await import('node:path');\n  const { pathToFileURL } = await import('node:url');\n\n  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];\n\n  for (const name of configNames) {\n    const configPath = join(root, name);\n    if (existsSync(configPath)) {\n      // Use Vite's built-in config loading to handle TypeScript\n      const mod = await import(pathToFileURL(configPath).href);\n      return mod.default ?? mod;\n    }\n  }\n  return null;\n}\n\n/**\n * Serve the production build for local testing.\n * If the adapter provides a preview() method, it takes priority.\n * Otherwise falls back to Vite's built-in preview server.\n */\nexport async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const { join } = await import('node:path');\n\n  // Try to load timber config for adapter-specific preview\n  const root = process.cwd();\n  const config = await loadTimberConfig(root).catch(() => null);\n  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;\n\n  if (resolvePreviewStrategy(adapter) === 'adapter') {\n    const buildDir = join(root, 'dist');\n    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };\n    await adapter!.preview!(timberConfig, buildDir);\n    return;\n  }\n\n  // Fallback: Vite's built-in preview server\n  const preview = _deps?.preview ?? (await import('vite')).preview;\n  const server = await preview({\n    configFile: options.config,\n  });\n  server.printUrls();\n}\n\n/**\n * Validate types and routes without producing build output.\n * Runs tsgo --noEmit for type checking.\n */\nexport async function runCheck(options: CommandOptions): Promise<void> {\n  const { execFile } = await import('node:child_process');\n\n  await new Promise<void>((resolve, reject) => {\n    const configArgs = options.config ? ['--project', options.config] : [];\n    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {\n      if (stdout) process.stdout.write(stdout);\n      if (stderr) process.stderr.write(stderr);\n      if (err) {\n        reject(new Error(`Type check failed with exit code ${err.code}`));\n      } else {\n        resolve();\n      }\n    });\n  });\n}\n\n// ─── Main Entry Point ────────────────────────────────────────────────────────\n\nasync function main(): Promise<void> {\n  const parsed = parseArgs(process.argv.slice(2));\n  const options: CommandOptions = { config: parsed.config };\n\n  switch (parsed.command) {\n    case 'dev':\n      await runDev(options);\n      break;\n    case 'build':\n      await runBuild(options);\n      break;\n    case 'preview':\n      await runPreview(options);\n      break;\n    case 'check':\n      await runCheck(options);\n      break;\n  }\n}\n\n// Run main when executed as a CLI (not imported in tests).\n// The bin shim (bin/timber.mjs) does `import '../dist/cli.js'`, so\n// process.argv[1] points to the shim, not this file. We check both:\n// direct execution AND being imported by the timber bin shim.\nconst isDirectExecution =\n  typeof process !== 'undefined' &&\n  process.argv[1] &&\n  (import.meta.url.endsWith(process.argv[1]) ||\n    process.argv[1].endsWith('bin/timber.mjs') ||\n    process.argv[1].endsWith('bin/timber'));\n\nif (isDirectExecution) {\n  main().catch((err) => {\n    console.error(err.message);\n    process.exit(1);\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n// timber.js CLI\n//\n// Wraps Vite commands with timber-specific behavior.\n// See design/18-build-system.md §\"CLI\".\n//\n// Commands:\n//   timber dev      — Start Vite dev server with HMR\n//   timber build    — Run multi-environment build via createBuilder/buildApp\n//   timber preview  — Serve the production build\n//   timber check    — Validate types + routes without building\n\nconst COMMANDS = ['dev', 'build', 'preview', 'check'] as const;\ntype Command = (typeof COMMANDS)[number];\n\nexport interface ParsedArgs {\n  command: Command;\n  config: string | undefined;\n}\n\nexport interface CommandOptions {\n  config?: string;\n}\n\n/**\n * Parse CLI arguments into a structured command + options.\n * Accepts: timber <command> [--config|-c <path>]\n */\nexport function parseArgs(args: string[]): ParsedArgs {\n  if (args.length === 0) {\n    throw new Error(\n      'No command provided. Usage: timber <dev|build|preview|check> [--config <path>]'\n    );\n  }\n\n  const command = args[0];\n  if (!COMMANDS.includes(command as Command)) {\n    throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(', ')}`);\n  }\n\n  let config: string | undefined;\n  for (let i = 1; i < args.length; i++) {\n    if (args[i] === '--config' || args[i] === '-c') {\n      config = args[++i];\n      if (!config) {\n        throw new Error('--config requires a path argument');\n      }\n    }\n  }\n\n  return { command: command as Command, config };\n}\n\n// ─── Command Implementations ─────────────────────────────────────────────────\n\n/** @internal Dependency injection for testing. */\nexport interface ViteDeps {\n  createServer?: typeof import('vite').createServer;\n  createBuilder?: typeof import('vite').createBuilder;\n  preview?: typeof import('vite').preview;\n}\n\n/**\n * Start the Vite dev server.\n *\n * The timber plugin binds the port immediately with a holding page\n * (in rootSync's config hook) so browsers see a \"starting...\" page\n * instead of ERR_CONNECTION_REFUSED during initialization.\n *\n * See design/21-dev-server.md, TIM-665.\n */\nexport async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createServer = _deps?.createServer ?? (await import('vite')).createServer;\n  const server = await createServer({\n    configFile: options.config,\n  });\n  await server.listen();\n  server.printUrls();\n}\n\n/**\n * Run the production build using createBuilder + buildApp.\n * Direct build() calls do NOT trigger the RSC plugin's multi-environment\n * pipeline — createBuilder/buildApp is required.\n */\nexport async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createBuilder = _deps?.createBuilder ?? (await import('vite')).createBuilder;\n  const builder = await createBuilder({\n    configFile: options.config,\n  });\n  await builder.buildApp();\n}\n\n/**\n * Determine whether to use the adapter's preview or Vite's built-in preview.\n * Exported for testing — the actual runPreview function uses this internally.\n */\nexport function resolvePreviewStrategy(\n  adapter: import('./adapters/types').TimberPlatformAdapter | undefined\n): 'adapter' | 'vite' {\n  if (adapter && typeof adapter.preview === 'function') {\n    return 'adapter';\n  }\n  return 'vite';\n}\n\n/**\n * Load timber.config.ts from the project root.\n * Returns the config object with adapter, output, etc.\n * Returns null if no config file is found.\n */\nasync function loadTimberConfig(root: string): Promise<{\n  adapter?: import('./adapters/types').TimberPlatformAdapter;\n  output?: string;\n  buildDir?: string;\n} | null> {\n  const { existsSync } = await import('node:fs');\n  const { join } = await import('node:path');\n  const { pathToFileURL } = await import('node:url');\n\n  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];\n\n  for (const name of configNames) {\n    const configPath = join(root, name);\n    if (existsSync(configPath)) {\n      // Use Vite's built-in config loading to handle TypeScript\n      const mod = await import(pathToFileURL(configPath).href);\n      return mod.default ?? mod;\n    }\n  }\n  return null;\n}\n\n/**\n * Serve the production build for local testing.\n * If the adapter provides a preview() method, it takes priority.\n * Otherwise falls back to Vite's built-in preview server.\n */\nexport async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const { join, resolve } = await import('node:path');\n\n  // Try to load timber config for adapter-specific preview\n  const root = process.cwd();\n  const config = await loadTimberConfig(root).catch(() => null);\n  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;\n\n  if (resolvePreviewStrategy(adapter) === 'adapter') {\n    // Resolve build directory: timber config > default .timber/dist\n    const buildDir = config?.buildDir\n      ? resolve(root, config.buildDir)\n      : join(root, '.timber', 'dist');\n    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };\n    await adapter!.preview!(timberConfig, buildDir);\n    return;\n  }\n\n  // Fallback: Vite's built-in preview server\n  const preview = _deps?.preview ?? (await import('vite')).preview;\n  const server = await preview({\n    configFile: options.config,\n  });\n  server.printUrls();\n}\n\n/**\n * Validate types and routes without producing build output.\n * Runs tsgo --noEmit for type checking.\n */\nexport async function runCheck(options: CommandOptions): Promise<void> {\n  const { execFile } = await import('node:child_process');\n\n  await new Promise<void>((resolve, reject) => {\n    const configArgs = options.config ? ['--project', options.config] : [];\n    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {\n      if (stdout) process.stdout.write(stdout);\n      if (stderr) process.stderr.write(stderr);\n      if (err) {\n        reject(new Error(`Type check failed with exit code ${err.code}`));\n      } else {\n        resolve();\n      }\n    });\n  });\n}\n\n// ─── Main Entry Point ────────────────────────────────────────────────────────\n\nasync function main(): Promise<void> {\n  const parsed = parseArgs(process.argv.slice(2));\n  const options: CommandOptions = { config: parsed.config };\n\n  switch (parsed.command) {\n    case 'dev':\n      await runDev(options);\n      break;\n    case 'build':\n      await runBuild(options);\n      break;\n    case 'preview':\n      await runPreview(options);\n      break;\n    case 'check':\n      await runCheck(options);\n      break;\n  }\n}\n\n// Run main when executed as a CLI (not imported in tests).\n// The bin shim (bin/timber.mjs) does `import '../dist/cli.js'`, so\n// process.argv[1] points to the shim, not this file. We check both:\n// direct execution AND being imported by the timber bin shim.\nconst isDirectExecution =\n  typeof process !== 'undefined' &&\n  process.argv[1] &&\n  (import.meta.url.endsWith(process.argv[1]) ||\n    process.argv[1].endsWith('bin/timber.mjs') ||\n    process.argv[1].endsWith('bin/timber'));\n\nif (isDirectExecution) {\n  main().catch((err) => {\n    console.error(err.message);\n    process.exit(1);\n  });\n}\n"],"mappings":"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"}