@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.160

package/dist/cache/handler-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Module-level cache handler singleton.
+ *
+ * Lazily initialized to MemoryCacheHandler on first access. The framework
+ * replaces this at boot from timber.config.ts via setCacheHandler().
+ *
+ * This module avoids importing from ./index to prevent circular dependencies.
+ */
+interface CacheHandlerLike {
+    get(key: string): Promise<{
+        value: unknown;
+        stale: boolean;
+    } | null>;
+    set(key: string, value: unknown, opts: {
+        ttl: number;
+        tags: string[];
+    }): Promise<void>;
+    invalidate(opts: {
+        key?: string;
+        tag?: string;
+    }): Promise<void>;
+}
+/** Replace the active cache handler. Called by the framework at boot. */
+export declare function setCacheHandler(h: CacheHandlerLike): void;
+/** Whether the handler was explicitly configured (vs the default in-memory fallback). */
+export declare function isCacheHandlerConfigured(): boolean;
+/**
+ * Get the active cache handler. Creates a default MemoryCacheHandler on
+ * first access if none has been set via setCacheHandler().
+ */
+export declare function getCacheHandler(): CacheHandlerLike;
+export {};
+//# sourceMappingURL=handler-store.d.ts.map

package/dist/cache/handler-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-store.d.ts","sourceRoot":"","sources":["../../src/cache/handler-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,UAAU,gBAAgB;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAMD,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAGzD;AAED,yFAAyF;AACzF,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAOlD"}

package/dist/cache/index.d.ts

@@ -17,14 +17,30 @@ export interface CacheOptions<Fn extends (...args: any[]) => any> {
     key?: (...args: Parameters<Fn>) => string;
     staleWhileRevalidate?: boolean;
     tags?: string[] | ((...args: Parameters<Fn>) => string[]);
+    /** Timeout (ms) for singleflight-coalesced calls. Prevents hung fn() from
+     *  permanently blocking all future callers for the same cache key. See TIM-518. */
+    timeoutMs?: number;
 }
 export interface MemoryCacheHandlerOptions {
     /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */
+    maxEntries?: number;
+    /**
+     * @deprecated Use `maxEntries` instead. Will be removed in a future release.
+     * Alias for `maxEntries` — maximum number of entries (not bytes).
+     */
     maxSize?: number;
+    /** Maximum total byte budget for all cached values. Oldest entries are evicted when exceeded. Default: no limit. */
+    maxBytes?: number;
+    /** Maximum byte size for a single cache entry. Entries exceeding this are silently dropped. Default: no limit. */
+    maxEntryBytes?: number;
 }
 export declare class MemoryCacheHandler implements CacheHandler {
     private store;
-    private maxSize;
+    private maxEntries;
+    private maxBytes;
+    private maxEntryBytes;
+    private currentBytes;
+    private readonly _trackBytes;
     constructor(opts?: MemoryCacheHandlerOptions);
     get(key: string): Promise<{
         value: unknown;
@@ -40,13 +56,17 @@ export declare class MemoryCacheHandler implements CacheHandler {
     }): Promise<void>;
     /** Number of entries currently in the cache. */
     get size(): number;
+    /** Estimated total byte size of all cached values. Only tracked when maxBytes or maxEntryBytes is configured; returns 0 otherwise. */
+    get bytes(): number;
+    /** Evict the oldest entry (front of Map). */
+    private evictOldest;
 }
 export { RedisCacheHandler } from './redis-handler';
 export type { RedisClient } from './redis-handler';
-export { createCache } from './timber-cache';
-export { registerCachedFunction } from './register-cached-function';
-export type { RegisterCachedFunctionOptions } from './register-cached-function';
-export { stableStringify } from './stable-stringify';
-export { createSingleflight } from './singleflight';
-export type { Singleflight } from './singleflight';
+export { cache } from './cache-api';
+export { setCacheHandler, getCacheHandler } from './handler-store';
+export { setDefaultSingleflightTimeout } from './timber-cache';
+export { estimateByteSize } from './sizeof';
+export { TagAwareCacheHandler } from './tag-aware-handler';
+export type { CacheStore } from './store';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAGD,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IAC1C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,yBAAyB;IACxC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,KAAK,CAA4E;IACzF,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,CAAC,EAAE,yBAAyB;IAItC,GAAG,CAAC,GAAG,EAAE,MAAM;;;;IAYf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE;IAuBtE,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAarD,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,YAAY,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAGD,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IAC1C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IAC1D;uFACmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oHAAoH;IACpH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kHAAkH;IAClH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,KAAK,CAGT;IACJ,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;gBAE1B,IAAI,CAAC,EAAE,yBAAyB;IAQtC,GAAG,CAAC,GAAG,EAAE,MAAM;;;;IAYf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE;IAwCtE,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAkBrD,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,sIAAsI;IACtI,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,6CAA6C;IAC7C,OAAO,CAAC,WAAW;CAQpB;AAED,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAG/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}

package/dist/cache/index.js

@@ -1,326 +1,3 @@
-import "../_chunks/als-registry-B7DbZ2hS.js";
-import { n as addSpanEventSync } from "../_chunks/tracing-CemImE6h.js";
-//#region src/cache/redis-handler.ts
-var KEY_PREFIX = "timber:cache:";
-var TAG_PREFIX = "timber:tag:";
-/**
-* Redis-backed CacheHandler for distributed caching.
-*
-* All instances sharing the same Redis see each other's cache entries and
-* invalidations. Tag-based invalidation uses Redis Sets to track which keys
-* belong to which tags.
-*
-* Bring your own Redis client — any client implementing the RedisClient
-* interface works (ioredis, node-redis, @upstash/redis, etc.).
-*/
-var RedisCacheHandler = class {
-	client;
-	prefix;
-	constructor(client, opts) {
-		this.client = client;
-		this.prefix = opts?.prefix ?? "";
-	}
-	cacheKey(key) {
-		return `${this.prefix}${KEY_PREFIX}${key}`;
-	}
-	tagKey(tag) {
-		return `${this.prefix}${TAG_PREFIX}${tag}`;
-	}
-	async get(key) {
-		const raw = await this.client.get(this.cacheKey(key));
-		if (raw === null) return null;
-		const entry = JSON.parse(raw);
-		const stale = Date.now() > entry.expiresAt;
-		return {
-			value: entry.value,
-			stale
-		};
-	}
-	async set(key, value, opts) {
-		const ck = this.cacheKey(key);
-		const expiresAt = Date.now() + opts.ttl * 1e3;
-		const payload = JSON.stringify({
-			value,
-			expiresAt
-		});
-		const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
-		await this.client.set(ck, payload, "EX", redisTtlSeconds);
-		for (const tag of opts.tags) await this.client.sadd(this.tagKey(tag), key);
-	}
-	async invalidate(opts) {
-		if (opts.key) await this.client.del(this.cacheKey(opts.key));
-		if (opts.tag) {
-			const tk = this.tagKey(opts.tag);
-			const keys = await this.client.smembers(tk);
-			if (keys.length > 0) {
-				const cacheKeys = keys.map((k) => this.cacheKey(k));
-				await this.client.del(cacheKeys);
-			}
-			await this.client.del(tk);
-		}
-	}
-};
-//#endregion
-//#region src/cache/stable-stringify.ts
-/**
-* Deterministic JSON serialization with sorted object keys.
-* Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }
-* produce the same string.
-*/
-function stableStringify(value) {
-	if (value === null || value === void 0) return JSON.stringify(value);
-	if (typeof value !== "object") return JSON.stringify(value);
-	if (Array.isArray(value)) return "[" + value.map((item) => stableStringify(item)).join(",") + "]";
-	const obj = value;
-	const keys = Object.keys(obj).sort();
-	const pairs = [];
-	for (const key of keys) {
-		if (obj[key] === void 0) continue;
-		pairs.push(JSON.stringify(key) + ":" + stableStringify(obj[key]));
-	}
-	return "{" + pairs.join(",") + "}";
-}
-//#endregion
-//#region src/cache/singleflight.ts
-function createSingleflight() {
-	const inflight = /* @__PURE__ */ new Map();
-	return { do(key, fn) {
-		const existing = inflight.get(key);
-		if (existing) return existing;
-		const promise = fn().finally(() => {
-			inflight.delete(key);
-		});
-		inflight.set(key, promise);
-		return promise;
-	} };
-}
-//#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();
-/**
-* Generate a cache key from function identity and serialized args.
-*
-* Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't
-* need collision resistance — they need speed. The fnId prefix provides
-* namespace isolation; the hash covers the args.
-*
-* See TIM-370 for perf motivation.
-*/
-function defaultKeyGenerator(fnId, args) {
-	const raw = fnId + ":" + stableStringify(args);
-	return fnId + ":" + fnv1aHash(raw);
-}
-/**
-* Resolve tags from the options — supports static array or function form.
-*/
-function resolveTags$1(opts, args) {
-	if (!opts.tags) return [];
-	if (Array.isArray(opts.tags)) return opts.tags;
-	return opts.tags(...args);
-}
-var fnIdCounter = 0;
-/**
-* Creates a cached wrapper around an async function.
-*
-* - SHA-256 default keys with normalized JSON args
-* - Singleflight: concurrent misses → single execution
-* - SWR: serve stale immediately, background refetch
-* - Tags as string[] or function of args
-* - No ALS dependency
-*
-* 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) => {
-		const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);
-		const cacheStart = performance.now();
-		const cached = await handler.get(key);
-		if (cached && !cached.stale) {
-			addSpanEventSync("timber.cache.hit", {
-				key,
-				duration_ms: Math.round(performance.now() - cacheStart)
-			});
-			return cached.value;
-		}
-		if (cached && cached.stale && opts.staleWhileRevalidate) {
-			addSpanEventSync("timber.cache.hit", {
-				key,
-				duration_ms: Math.round(performance.now() - cacheStart),
-				stale: true
-			});
-			singleflight$1.do(`swr:${key}`, async () => {
-				try {
-					const fresh = await fn(...args);
-					const tags = resolveTags$1(opts, args);
-					await handler.set(key, fresh, {
-						ttl: opts.ttl,
-						tags
-					});
-				} catch {}
-			}).catch(() => {});
-			return cached.value;
-		}
-		const result = await singleflight$1.do(key, () => fn(...args));
-		const tags = resolveTags$1(opts, args);
-		await handler.set(key, result, {
-			ttl: opts.ttl,
-			tags
-		});
-		addSpanEventSync("timber.cache.miss", {
-			key,
-			duration_ms: Math.round(performance.now() - cacheStart)
-		});
-		return result;
-	};
-}
-/**
-* Invalidate cache entries by tag or key.
-*/
-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"
-]);
-/**
-* Generate a cache key from a stable function ID and serialized args.
-*
-* 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'.
-*/
-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".`);
-}
-/**
-* Runtime for the "use cache" directive transform. Wraps an async function
-* with caching using the same cache handler as timber.cache.
-*
-* 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.
-*/
-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;
-	};
-}
-//#endregion
-//#region src/cache/index.ts
-var MemoryCacheHandler = class {
-	store = /* @__PURE__ */ new Map();
-	maxSize;
-	constructor(opts) {
-		this.maxSize = opts?.maxSize ?? 1e3;
-	}
-	async get(key) {
-		const entry = this.store.get(key);
-		if (!entry) return null;
-		this.store.delete(key);
-		this.store.set(key, entry);
-		const stale = Date.now() > entry.expiresAt;
-		return {
-			value: entry.value,
-			stale
-		};
-	}
-	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;
-		}
-		this.store.set(key, {
-			value,
-			expiresAt: Date.now() + opts.ttl * 1e3,
-			tags: opts.tags
-		});
-	}
-	async invalidate(opts) {
-		if (opts.key) 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);
-		}
-	}
-	/** Number of entries currently in the cache. */
-	get size() {
-		return this.store.size;
-	}
-};
-//#endregion
-export { MemoryCacheHandler, RedisCacheHandler, createCache, createSingleflight, registerCachedFunction, stableStringify };
-
-//# sourceMappingURL=index.js.map
+import { _ as setDefaultSingleflightTimeout, f as MemoryCacheHandler, g as setCacheHandler, h as getCacheHandler, m as RedisCacheHandler, p as TagAwareCacheHandler, t as cache } from "../_chunks/cache-api-swbefQ6F.js";
+import { t as estimateByteSize } from "../_chunks/sizeof-lXffQ1Vr.js";
+export { MemoryCacheHandler, RedisCacheHandler, TagAwareCacheHandler, cache, estimateByteSize, getCacheHandler, setCacheHandler, setDefaultSingleflightTimeout };

package/dist/cache/invalidation-epoch.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Per-process invalidation epoch tracking for timber.cache (TIM-1028).
+ *
+ * handler.set for a cache miss runs after `fn()` resolves. An explicit
+ * `cache.invalidate({ tag })` / `revalidateTag` that lands while fn is in
+ * flight would otherwise be silently undone — the just-invalidated value
+ * re-stored as fresh for the full TTL, resurrecting pre-mutation data.
+ *
+ * Every invalidation bumps a monotonic epoch and records it against the
+ * invalidated key/tag. Before storing a result, the cache wrapper checks
+ * whether its key or any of its tags were invalidated after fn started and
+ * skips the write if so. Skipping is always safe: the only cost is one
+ * extra cache miss on the next call.
+ *
+ * Scope: per-process, like the singleflight map. An invalidation issued by
+ * another instance against a shared handler (Redis/KV) during fn flight is
+ * not observable here — closing that window fully would require store-level
+ * versioning, which no CacheHandler backend offers.
+ */
+/** The current epoch. Capture before running fn(), pass to wasInvalidatedSince. */
+export declare function currentInvalidationEpoch(): number;
+/**
+ * Record an invalidation. Call BEFORE handler.invalidate() so an execution
+ * whose set-check races the invalidation errs toward skipping the write.
+ */
+export declare function recordInvalidation(opts: {
+    key?: string;
+    tag?: string;
+}): void;
+/**
+ * Whether the key or any tag was invalidated after `startEpoch` (the epoch
+ * captured when fn started executing).
+ */
+export declare function wasInvalidatedSince(startEpoch: number, key: string, tags: string[]): boolean;
+/**
+ * The highest epoch at which the key or any of the tags was invalidated
+ * (0 if never). Used to scope the singleflight key: callers arriving after
+ * an invalidation must not coalesce onto a flight that started before it —
+ * they would receive the pre-invalidation result the invalidation was
+ * issued to discard.
+ */
+export declare function lastInvalidationEpochFor(key: string, tags: string[]): number;
+//# sourceMappingURL=invalidation-epoch.d.ts.map

package/dist/cache/invalidation-epoch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidation-epoch.d.ts","sourceRoot":"","sources":["../../src/cache/invalidation-epoch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAwBH,mFAAmF;AACnF,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAI7E;AAaD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAE5F;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAS5E"}

package/dist/cache/redis-handler.d.ts

@@ -1,15 +1,103 @@
 import type { CacheHandler } from './index';
 /**
- * Minimal Redis client interface — compatible with ioredis, node-redis, and
- * Cloudflare Workers Redis bindings. We depend on the interface, not the
- * implementation, so users bring their own Redis client.
+ * Minimal Redis client contract for `RedisCacheHandler`.
+ *
+ * This is deliberately NOT the native shape of any client library. ioredis,
+ * node-redis v4, and @upstash/redis all disagree on TTL argument shapes
+ * (positional `'EX'` vs `{ EX }` vs `{ ex }`), method casing (`sadd` vs
+ * `sAdd`), and array handling in `del` — a contract that pattern-matches one
+ * client lets another silently drop the expiry (TIM-1030: node-redis ignored
+ * the positional `'EX'` and wrote keys with no TTL). Instead, TTL semantics
+ * are explicit in the signature and you adapt your client with a thin
+ * wrapper, so a mismatch is a type error rather than silent unbounded
+ * keyspace growth.
+ *
+ * @example ioredis
+ * ```ts
+ * import Redis from 'ioredis';
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sadd(k, ...m),
+ *   srem: (k, ...m) => redis.srem(k, ...m),
+ *   smembers: (k) => redis.smembers(k),
+ *   ttl: (k) => redis.ttl(k),
+ * };
+ * ```
+ *
+ * @example node-redis v4
+ * ```ts
+ * import { createClient } from 'redis';
+ * const redis = createClient({ url: process.env.REDIS_URL });
+ * await redis.connect();
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { EX: ttl }),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sAdd(k, m),
+ *   srem: (k, ...m) => redis.sRem(k, m),
+ *   smembers: (k) => redis.sMembers(k),
+ *   ttl: (k) => redis.ttl(k),
+ * };
+ * ```
+ *
+ * @example @upstash/redis
+ * ```ts
+ * import { Redis } from '@upstash/redis';
+ * // automaticDeserialization must be off: the handler stores JSON strings
+ * // and parses them itself — auto-parsing would hand back objects.
+ * const redis = new Redis({ url, token, automaticDeserialization: false });
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { ex: ttl }),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sadd(k, m[0], ...m.slice(1)),
+ *   srem: (k, ...m) => redis.srem(k, m[0], ...m.slice(1)),
+ *   smembers: (k) => redis.smembers(k),
+ *   ttl: (k) => redis.ttl(k),
+ * };
+ * ```
  */
 export interface RedisClient {
+    /** `GET key` — the stored string, or null when absent. */
     get(key: string): Promise<string | null>;
-    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
-    del(key: string | string[]): Promise<number>;
-    sadd(key: string, ...members: string[]): Promise<number>;
+    /**
+     * `SET key value EX ttlSeconds` — store with an expiry. The TTL is a
+     * required positional argument so no adapter can forget it.
+     */
+    set(key: string, value: string, ttlSeconds: number): Promise<unknown>;
+    /**
+     * `EXPIRE key seconds NX` — set the TTL only if the key has no existing
+     * expiry (Redis 7.0+). Used to set the initial TTL on new tag sets.
+     */
+    expireNX(key: string, seconds: number): Promise<unknown>;
+    /**
+     * `EXPIRE key seconds GT` — update the TTL only if the new value is greater
+     * than the current one (Redis 7.0+). Used to extend tag set TTLs without
+     * allowing a short-TTL writer to shrink them.
+     */
+    expireGT(key: string, seconds: number): Promise<unknown>;
+    /** `DEL key` — delete a single key. Multi-key deletes loop per key. */
+    del(key: string): Promise<unknown>;
+    /** `SADD key member [member ...]` — add members to a set. */
+    sadd(key: string, ...members: string[]): Promise<unknown>;
+    /** `SREM key member [member ...]` — remove members from a set. */
+    srem(key: string, ...members: string[]): Promise<unknown>;
+    /** `SMEMBERS key` — all members of a set. */
     smembers(key: string): Promise<string[]>;
+    /**
+     * `TTL key` — remaining time-to-live in seconds. Returns -2 if the key does
+     * not exist, -1 if the key exists but has no expiry.
+     */
+    ttl(key: string): Promise<number>;
 }
 /**
  * Redis-backed CacheHandler for distributed caching.
@@ -18,8 +106,9 @@ export interface RedisClient {
  * invalidations. Tag-based invalidation uses Redis Sets to track which keys
  * belong to which tags.
  *
- * Bring your own Redis client — any client implementing the RedisClient
- * interface works (ioredis, node-redis, @upstash/redis, etc.).
+ * Bring your own Redis client wrapped to the {@link RedisClient} contract —
+ * see the adapter examples on the interface for ioredis, node-redis v4, and
+ * @upstash/redis.
  */
 export declare class RedisCacheHandler implements CacheHandler {
     private client;

package/dist/cache/redis-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redis-handler.d.ts","sourceRoot":"","sources":["../../src/cache/redis-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC1C;AAKD;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAK3D,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,MAAM;IAIR,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IASpE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBtF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAkBtE"}
+{"version":3,"file":"redis-handler.d.ts","sourceRoot":"","sources":["../../src/cache/redis-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,6DAA6D;IAC7D,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,kEAAkE;IAClE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC;AAKD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAK3D,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,MAAM;IAIR,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IASpE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BtF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAyBtE"}

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>;
+    do<T>(key: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+}
+/**
+ * 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(): Singleflight;
+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,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACzE;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