@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/dist/cache/index.js

@@ -1,284 +1,3 @@
-import "../_chunks/als-registry-k-AtAQ9R.js";
-import { t as addSpanEvent } from "../_chunks/tracing-DF0G3FB7.js";
-import { createHash } from "node:crypto";
-//#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/timber-cache.ts
-var singleflight$1 = createSingleflight();
-/**
-* Generate a SHA-256 cache key from function identity and serialized args.
-*/
-function defaultKeyGenerator(fnId, args) {
-	const raw = fnId + ":" + stableStringify(args);
-	return createHash("sha256").update(raw).digest("hex");
-}
-/**
-* 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) {
-			await addSpanEvent("timber.cache.hit", {
-				key,
-				duration_ms: Math.round(performance.now() - cacheStart)
-			});
-			return cached.value;
-		}
-		if (cached && cached.stale && opts.staleWhileRevalidate) {
-			await addSpanEvent("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
-		});
-		await addSpanEvent("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 SHA-256 cache key from a stable function ID and serialized args.
-*/
-function generateKey(id, args) {
-	const raw = id + ":" + stableStringify(args);
-	return createHash("sha256").update(raw).digest("hex");
-}
-/**
-* 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-ByagcC-J.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/json-lossy-check.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Dev-mode warning when a cache value contains types that lose fidelity
+ * through JSON round-trip. Only runs in development — no-op in production.
+ *
+ * Detects: Date (→ ISO string), Map/Set (→ {}), BigInt (→ throws).
+ * Emits once per process to avoid log spam.
+ */
+export declare function warnLossyJsonValue(value: unknown, cacheKey: string): void;
+/** Reset warning state — for tests only. */
+export declare function _resetLossyWarning(): void;
+//# sourceMappingURL=json-lossy-check.d.ts.map

package/dist/cache/json-lossy-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-lossy-check.d.ts","sourceRoot":"","sources":["../../src/cache/json-lossy-check.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAiBzE;AA2CD,4CAA4C;AAC5C,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

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

@@ -1,15 +1,144 @@
-import type { CacheHandler } from './index';
+import type { CacheHandler } from './index.ts';
 /**
- * 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),
+ *   execMulti: async (ops) => {
+ *     const p = redis.multi();
+ *     for (const op of ops) {
+ *       switch (op.op) {
+ *         case 'set': p.set(op.key, op.value, 'EX', op.ttlSeconds); break;
+ *         case 'sadd': p.sadd(op.key, ...op.members); break;
+ *         case 'expireNX': p.expire(op.key, op.seconds, 'NX'); break;
+ *         case 'expireGT': p.expire(op.key, op.seconds, 'GT'); break;
+ *         case 'del': p.del(op.key); break;
+ *       }
+ *     }
+ *     await p.exec();
+ *   },
+ * };
+ * ```
+ *
+ * @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 type RedisWriteOp = {
+    op: 'set';
+    key: string;
+    value: string;
+    ttlSeconds: number;
+} | {
+    op: 'sadd';
+    key: string;
+    members: string[];
+} | {
+    op: 'expireNX';
+    key: string;
+    seconds: number;
+} | {
+    op: 'expireGT';
+    key: string;
+    seconds: number;
+} | {
+    op: 'del';
+    key: string;
+};
 export interface RedisClient {
+    /** `GET key` — the stored string, or null when absent. */
     get(key: string): Promise<string | null>;
-    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>;
+    /**
+     * Execute a batch of write operations atomically via `MULTI/EXEC`.
+     * When provided, `set()` uses this to make tag-index writes and the data
+     * write atomic — no `invalidate({tag})` can interleave. Optional: when
+     * absent, operations run sequentially (correct but not race-free).
+     */
+    execMulti?(ops: RedisWriteOp[]): Promise<void>;
 }
 /**
  * Redis-backed CacheHandler for distributed caching.
@@ -18,8 +147,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;
@@ -36,7 +166,9 @@ export declare class RedisCacheHandler implements CacheHandler {
     set(key: string, value: unknown, opts: {
         ttl: number;
         tags: string[];
+        generation?: number;
     }): Promise<void>;
+    private execOp;
     invalidate(opts: {
         key?: string;
         tag?: string;

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":"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"}

package/dist/cache/singleflight.d.ts

@@ -3,9 +3,28 @@
  * 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>;
+    /** Return the in-flight promise for a key, or undefined if none. */
+    get(key: string): Promise<unknown> | undefined;
+}
+/**
+ * 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;IACxE,oEAAoE;IACpE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;CAChD;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,YAAY,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAGzC;CACF;AAED,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAqD3E"}

package/dist/cache/sizeof.d.ts

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

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

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

package/dist/cache/stable-stringify.d.ts

@@ -2,6 +2,15 @@
  * 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.
+ *
+ * Matches JSON.stringify semantics for toJSON: Date serializes to its ISO
+ * string, URL to its href, and class instances with a custom toJSON use it.
+ * Map and Set serialize their entries explicitly (insertion-order
+ * independent). Values that would serialize lossily — functions, symbols,
+ * and non-plain objects with no enumerable own state (RegExp, class
+ * instances holding data behind getters or internal slots) — throw instead:
+ * every such value would collapse to the same cache key, silently returning
+ * one argument's cached data for another (TIM-1020).
  */
 export declare function stableStringify(value: unknown): string;
 //# sourceMappingURL=stable-stringify.d.ts.map

package/dist/cache/stable-stringify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stable-stringify.d.ts","sourceRoot":"","sources":["../../src/cache/stable-stringify.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAetD"}
+{"version":3,"file":"stable-stringify.d.ts","sourceRoot":"","sources":["../../src/cache/stable-stringify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAqEtD"}

package/dist/cache/store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * CacheStore — the contract cache backends implement.
+ *
+ * Three tiers of tag capability, auto-detected by TagAwareCacheHandler:
+ *
+ * 1. **Native tags** (store implements setWithTags + invalidateTag): The store
+ *    handles tag indexing and invalidation internally. The handler delegates
+ *    directly. Examples: Vercel Runtime Cache, Durable Object–backed stores.
+ *
+ * 2. **Set primitives** (store implements sadd/smembers/srem/sdel): The handler
+ *    maintains an inverted index using the store's atomic set operations.
+ *    Eager invalidation — enumerate and delete. Example: Redis.
+ *
+ * 3. **Bare KV** (only get/set/del): The handler uses version-stamping. Entries
+ *    record tag versions at write time; reads validate against current versions.
+ *    Invalidation bumps a counter — O(1), race-free. Example: Cloudflare KV.
+ *
+ * Implementors pick their tier by which methods they provide. The handler
+ * selects the best available strategy automatically.
+ */
+export interface CacheStore {
+    /** Read a key. Returns null if absent or physically expired. */
+    get(key: string): Promise<string | null>;
+    /** Write a key with a physical TTL in seconds. Overwrites if exists. */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /** Delete a key. No-op if absent. */
+    del(key: string): Promise<void>;
+    /**
+     * Write a value with associated tags. The store handles tag indexing
+     * internally. If provided, the handler will call this instead of plain
+     * set() for tagged entries.
+     */
+    setWithTags?(key: string, value: string, ttlSeconds: number, tags: string[]): Promise<void>;
+    /**
+     * Invalidate all entries associated with a tag. The store handles
+     * the lookup and deletion/marking internally.
+     */
+    invalidateTag?(tag: string): Promise<void>;
+    /**
+     * Atomically add members to a named set and ensure the set has at least
+     * the given TTL.
+     */
+    sadd?(key: string, members: string[], ttlSeconds: number): Promise<void>;
+    /** Remove members from a named set. */
+    srem?(key: string, members: string[]): Promise<void>;
+    /** Return all members of a named set. */
+    smembers?(key: string): Promise<string[]>;
+    /** Delete a named set entirely. */
+    sdel?(key: string): Promise<void>;
+    /** Consistency model — used for framework build diagnostics. */
+    readonly consistency: 'strong' | 'eventual' | 'local';
+}
+//# sourceMappingURL=store.d.ts.map