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

package/dist/adapters/shared.d.ts

@@ -0,0 +1,16 @@
+/** Cache-Control value for hashed (immutable) assets. */
+export declare const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
+/** Cache-Control value for unhashed static assets. */
+export declare const STATIC_CACHE = "public, max-age=3600, must-revalidate";
+/**
+ * Generate a `_headers` file for static asset cache control.
+ *
+ * The `_headers` file is a platform convention supported by Cloudflare Workers
+ * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
+ * HTTP response headers.
+ *
+ * Vite places all hashed chunks under `/assets/` — these get immutable caching.
+ * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.
+ */
+export declare function generateHeadersFile(): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/adapters/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/adapters/shared.ts"],"names":[],"mappings":"AAaA,yDAAyD;AACzD,eAAO,MAAM,eAAe,wCAAwC,CAAC;AAErE,sDAAsD;AACtD,eAAO,MAAM,YAAY,0CAA0C,CAAC;AAEpE;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAU5C"}

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

@@ -0,0 +1,24 @@
+import type { CacheOptions } from './index';
+/**
+ * Public caching API: `cache(fn, opts)`.
+ *
+ * Wraps an async function with cross-request caching. Uses the configured
+ * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).
+ *
+ * ```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}`] }
+ * );
+ * ```
+ */
+export declare function cache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, stableId?: string): Fn;
+export declare namespace cache {
+    var invalidate: (opts: {
+        key?: string;
+        tag?: string;
+    }) => Promise<void>;
+}
+//# sourceMappingURL=cache-api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache-api.d.ts","sourceRoot":"","sources":["../../src/cache/cache-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5C;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,KAAK,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAC/D,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB,EAAE,CAEJ;yBANe,KAAK;2BAgB8B;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KAAG,OAAO,CAAC,IAAI,CAAC"}

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

@@ -0,0 +1,31 @@
+/**
+ * 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;
+/**
+ * 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;AAID,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAEzD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAOlD"}

package/dist/cache/index.d.ts

@@ -17,14 +17,29 @@ 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;
     constructor(opts?: MemoryCacheHandlerOptions);
     get(key: string): Promise<{
         value: unknown;
@@ -40,13 +55,14 @@ 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. */
+    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 { estimateByteSize } from './sizeof';
 //# 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;gBAEb,IAAI,CAAC,EAAE,yBAAyB;IAOtC,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,sDAAsD;IACtD,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;AAGnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC"}

package/dist/cache/index.js

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