@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/cache/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,UAAU;IAGzB,gEAAgE;IAChE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEzC,wEAAwE;IACxE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE,qCAAqC;IACrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAKhC;;;;OAIG;IACH,WAAW,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5F;;;OAGG;IACH,aAAa,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAI3C;;;OAGG;IACH,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE,uCAAuC;IACvC,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD,yCAAyC;IACzC,QAAQ,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE1C,mCAAmC;IACnC,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAIlC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;CACvD"}

package/dist/cache/stores/cloudflare-kv.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cloudflare Workers KV CacheStore — eventually-consistent, no set operations.
+ *
+ * The TagAwareCacheHandler uses the lazy (version-stamp) strategy for this
+ * store: tag invalidation bumps a version counter (O(1) write), and reads
+ * validate stored tag versions against current. No enumeration, no
+ * read-modify-write races, correct under eventual consistency.
+ *
+ * Consistency: KV propagates writes in ~60s. A tag version bump propagates
+ * like any other write — during the window, some reads may still validate
+ * against the old version and serve stale data. This is acceptable for KV's
+ * consistency model (use short TTLs for security-critical invalidation).
+ */
+import type { CacheStore } from '../store.ts';
+export interface CloudflareKVNamespace {
+    get(key: string, options?: {
+        type?: string;
+    }): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export declare class CloudflareKVStore implements CacheStore {
+    private kv;
+    readonly consistency: 'eventual';
+    /**
+     * @param kv - Either a KVNamespace instance or a factory function that
+     * resolves it from the current request context (for Workers where bindings
+     * are per-request).
+     */
+    constructor(kv: CloudflareKVNamespace | (() => CloudflareKVNamespace));
+    private getKV;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<void>;
+}
+//# sourceMappingURL=cloudflare-kv.d.ts.map

package/dist/cache/stores/cloudflare-kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-kv.d.ts","sourceRoot":"","sources":["../../../src/cache/stores/cloudflare-kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,qBAAa,iBAAkB,YAAW,UAAU;IAClD,OAAO,CAAC,EAAE,CAAwD;IAClE,QAAQ,CAAC,WAAW,EAAG,UAAU,CAAU;IAE3C;;;;OAIG;IACH,YAAY,EAAE,EAAE,qBAAqB,GAAG,CAAC,MAAM,qBAAqB,CAAC,EAEpE;IAED,OAAO,CAAC,KAAK;IAIP,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE7C;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpC;CACF"}

package/dist/cache/stores/cloudflare-kv.js

@@ -0,0 +1,29 @@
+//#region src/cache/stores/cloudflare-kv.ts
+var CloudflareKVStore = class {
+	kv;
+	consistency = "eventual";
+	/**
+	* @param kv - Either a KVNamespace instance or a factory function that
+	* resolves it from the current request context (for Workers where bindings
+	* are per-request).
+	*/
+	constructor(kv) {
+		this.kv = kv;
+	}
+	getKV() {
+		return typeof this.kv === "function" ? this.kv() : this.kv;
+	}
+	async get(key) {
+		return this.getKV().get(key);
+	}
+	async set(key, value, ttlSeconds) {
+		await this.getKV().put(key, value, { expirationTtl: Math.max(ttlSeconds, 60) });
+	}
+	async del(key) {
+		await this.getKV().delete(key);
+	}
+};
+//#endregion
+export { CloudflareKVStore };
+
+//# sourceMappingURL=cloudflare-kv.js.map

package/dist/cache/stores/cloudflare-kv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-kv.js","names":[],"sources":["../../../src/cache/stores/cloudflare-kv.ts"],"sourcesContent":["/**\n * Cloudflare Workers KV CacheStore — eventually-consistent, no set operations.\n *\n * The TagAwareCacheHandler uses the lazy (version-stamp) strategy for this\n * store: tag invalidation bumps a version counter (O(1) write), and reads\n * validate stored tag versions against current. No enumeration, no\n * read-modify-write races, correct under eventual consistency.\n *\n * Consistency: KV propagates writes in ~60s. A tag version bump propagates\n * like any other write — during the window, some reads may still validate\n * against the old version and serve stale data. This is acceptable for KV's\n * consistency model (use short TTLs for security-critical invalidation).\n */\n\nimport type { CacheStore } from '../store.ts';\n\nexport interface CloudflareKVNamespace {\n  get(key: string, options?: { type?: string }): Promise<string | null>;\n  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\nexport class CloudflareKVStore implements CacheStore {\n  private kv: CloudflareKVNamespace | (() => CloudflareKVNamespace);\n  readonly consistency = 'eventual' as const;\n\n  /**\n   * @param kv - Either a KVNamespace instance or a factory function that\n   * resolves it from the current request context (for Workers where bindings\n   * are per-request).\n   */\n  constructor(kv: CloudflareKVNamespace | (() => CloudflareKVNamespace)) {\n    this.kv = kv;\n  }\n\n  private getKV(): CloudflareKVNamespace {\n    return typeof this.kv === 'function' ? this.kv() : this.kv;\n  }\n\n  async get(key: string): Promise<string | null> {\n    return this.getKV().get(key);\n  }\n\n  async set(key: string, value: string, ttlSeconds: number): Promise<void> {\n    // KV expirationTtl minimum is 60s\n    await this.getKV().put(key, value, { expirationTtl: Math.max(ttlSeconds, 60) });\n  }\n\n  async del(key: string): Promise<void> {\n    await this.getKV().delete(key);\n  }\n}\n"],"mappings":";AAsBA,IAAa,oBAAb,MAAqD;CACnD;CACA,cAAuB;;;;;;CAOvB,YAAY,IAA2D;EACrE,KAAK,KAAK;CACZ;CAEA,QAAuC;EACrC,OAAO,OAAO,KAAK,OAAO,aAAa,KAAK,GAAG,IAAI,KAAK;CAC1D;CAEA,MAAM,IAAI,KAAqC;EAC7C,OAAO,KAAK,MAAM,CAAC,CAAC,IAAI,GAAG;CAC7B;CAEA,MAAM,IAAI,KAAa,OAAe,YAAmC;EAEvE,MAAM,KAAK,MAAM,CAAC,CAAC,IAAI,KAAK,OAAO,EAAE,eAAe,KAAK,IAAI,YAAY,EAAE,EAAE,CAAC;CAChF;CAEA,MAAM,IAAI,KAA4B;EACpC,MAAM,KAAK,MAAM,CAAC,CAAC,OAAO,GAAG;CAC/B;AACF"}

package/dist/cache/stores/memory.d.ts

@@ -0,0 +1,42 @@
+/**
+ * In-memory CacheStore — local consistency only.
+ *
+ * LRU eviction by entry count and optional byte budget. The TagAwareCacheHandler
+ * uses the Set-based strategy here (we implement sadd/smembers/srem/sdel with
+ * plain Maps — atomic within a single process).
+ *
+ * Tag sets may accumulate stale memberships when data entries expire via TTL or
+ * LRU eviction (the store layer cannot know which sets reference a given key).
+ * This is harmless: TagAwareCacheHandler's eager invalidation path reads each
+ * member before deleting and prunes stale entries. The cost is proportional to
+ * set size on invalidation, not to memory — stale memberships are just strings.
+ */
+import type { CacheStore } from '../store.ts';
+export interface MemoryStoreOptions {
+    maxEntries?: number;
+    maxBytes?: number;
+    maxEntryBytes?: number;
+}
+export declare class MemoryCacheStore implements CacheStore {
+    private store;
+    private sets;
+    private maxEntries;
+    private maxBytes;
+    private maxEntryBytes;
+    private currentBytes;
+    private readonly trackBytes;
+    readonly consistency: 'local';
+    constructor(opts?: MemoryStoreOptions);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<void>;
+    sadd(key: string, members: string[], _ttlSeconds: number): Promise<void>;
+    srem(key: string, members: string[]): Promise<void>;
+    smembers(key: string): Promise<string[]>;
+    sdel(key: string): Promise<void>;
+    get size(): number;
+    get bytes(): number;
+    private removeEntry;
+    private evictOldest;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/cache/stores/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/cache/stores/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,KAAK,CAA6E;IAC1F,OAAO,CAAC,IAAI,CAAkC;IAC9C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,QAAQ,CAAC,WAAW,EAAG,OAAO,CAAU;IAExC,YAAY,IAAI,CAAC,EAAE,kBAAkB,EAKpC;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW7C;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBvE;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpC;IAIK,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7E;IAEK,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxD;IAEK,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAG7C;IAEK,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErC;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,WAAW;CAIpB"}

package/dist/cache/stores/memory.js

@@ -0,0 +1,90 @@
+import { t as estimateByteSize } from "../../_chunks/sizeof-BM1409x2.js";
+//#region src/cache/stores/memory.ts
+var MemoryCacheStore = class {
+	store = /* @__PURE__ */ new Map();
+	sets = /* @__PURE__ */ new Map();
+	maxEntries;
+	maxBytes;
+	maxEntryBytes;
+	currentBytes = 0;
+	trackBytes;
+	consistency = "local";
+	constructor(opts) {
+		this.maxEntries = Math.max(opts?.maxEntries ?? 1e3, 1);
+		this.maxBytes = opts?.maxBytes;
+		this.maxEntryBytes = opts?.maxEntryBytes;
+		this.trackBytes = this.maxBytes !== void 0 || this.maxEntryBytes !== void 0;
+	}
+	async get(key) {
+		const entry = this.store.get(key);
+		if (!entry) return null;
+		if (Date.now() > entry.expiresAt) {
+			this.removeEntry(key);
+			return null;
+		}
+		this.store.delete(key);
+		this.store.set(key, entry);
+		return entry.value;
+	}
+	async set(key, value, ttlSeconds) {
+		const byteSize = this.trackBytes ? estimateByteSize(value) : 0;
+		if (this.maxEntryBytes !== void 0 && byteSize > this.maxEntryBytes) return;
+		if (this.store.has(key)) this.removeEntry(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() + ttlSeconds * 1e3,
+			byteSize
+		});
+		this.currentBytes += byteSize;
+	}
+	async del(key) {
+		this.removeEntry(key);
+	}
+	async sadd(key, members, _ttlSeconds) {
+		let set = this.sets.get(key);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.sets.set(key, set);
+		}
+		for (const m of members) set.add(m);
+	}
+	async srem(key, members) {
+		const set = this.sets.get(key);
+		if (!set) return;
+		for (const m of members) set.delete(m);
+		if (set.size === 0) this.sets.delete(key);
+	}
+	async smembers(key) {
+		const set = this.sets.get(key);
+		return set ? [...set] : [];
+	}
+	async sdel(key) {
+		this.sets.delete(key);
+	}
+	get size() {
+		return this.store.size;
+	}
+	get bytes() {
+		return this.currentBytes;
+	}
+	removeEntry(key) {
+		const entry = this.store.get(key);
+		if (entry) {
+			this.currentBytes -= entry.byteSize;
+			this.store.delete(key);
+		}
+	}
+	evictOldest() {
+		const oldest = this.store.keys().next().value;
+		if (oldest !== void 0) this.removeEntry(oldest);
+	}
+};
+//#endregion
+export { MemoryCacheStore };
+
+//# sourceMappingURL=memory.js.map

package/dist/cache/stores/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","names":[],"sources":["../../../src/cache/stores/memory.ts"],"sourcesContent":["/**\n * In-memory CacheStore — local consistency only.\n *\n * LRU eviction by entry count and optional byte budget. The TagAwareCacheHandler\n * uses the Set-based strategy here (we implement sadd/smembers/srem/sdel with\n * plain Maps — atomic within a single process).\n *\n * Tag sets may accumulate stale memberships when data entries expire via TTL or\n * LRU eviction (the store layer cannot know which sets reference a given key).\n * This is harmless: TagAwareCacheHandler's eager invalidation path reads each\n * member before deleting and prunes stale entries. The cost is proportional to\n * set size on invalidation, not to memory — stale memberships are just strings.\n */\n\nimport type { CacheStore } from '../store.ts';\nimport { estimateByteSize } from '../sizeof.ts';\n\nexport interface MemoryStoreOptions {\n  maxEntries?: number;\n  maxBytes?: number;\n  maxEntryBytes?: number;\n}\n\nexport class MemoryCacheStore implements CacheStore {\n  private store = new Map<string, { value: string; expiresAt: number; byteSize: number }>();\n  private sets = new Map<string, Set<string>>();\n  private maxEntries: number;\n  private maxBytes: number | undefined;\n  private maxEntryBytes: number | undefined;\n  private currentBytes = 0;\n  private readonly trackBytes: boolean;\n  readonly consistency = 'local' as const;\n\n  constructor(opts?: MemoryStoreOptions) {\n    this.maxEntries = Math.max(opts?.maxEntries ?? 1000, 1);\n    this.maxBytes = opts?.maxBytes;\n    this.maxEntryBytes = opts?.maxEntryBytes;\n    this.trackBytes = this.maxBytes !== undefined || this.maxEntryBytes !== undefined;\n  }\n\n  async get(key: string): Promise<string | null> {\n    const entry = this.store.get(key);\n    if (!entry) return null;\n    if (Date.now() > entry.expiresAt) {\n      this.removeEntry(key);\n      return null;\n    }\n    // LRU: move to end\n    this.store.delete(key);\n    this.store.set(key, entry);\n    return entry.value;\n  }\n\n  async set(key: string, value: string, ttlSeconds: number): Promise<void> {\n    const byteSize = this.trackBytes ? estimateByteSize(value) : 0;\n\n    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) return;\n\n    if (this.store.has(key)) this.removeEntry(key);\n\n    while (this.store.size >= this.maxEntries) this.evictOldest();\n\n    if (this.maxBytes !== undefined) {\n      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {\n        this.evictOldest();\n      }\n      if (this.currentBytes + byteSize > this.maxBytes) return;\n    }\n\n    this.store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000, byteSize });\n    this.currentBytes += byteSize;\n  }\n\n  async del(key: string): Promise<void> {\n    this.removeEntry(key);\n  }\n\n  // Set operations — trivial in-process implementations.\n\n  async sadd(key: string, members: string[], _ttlSeconds: number): Promise<void> {\n    let set = this.sets.get(key);\n    if (!set) {\n      set = new Set();\n      this.sets.set(key, set);\n    }\n    for (const m of members) set.add(m);\n  }\n\n  async srem(key: string, members: string[]): Promise<void> {\n    const set = this.sets.get(key);\n    if (!set) return;\n    for (const m of members) set.delete(m);\n    if (set.size === 0) this.sets.delete(key);\n  }\n\n  async smembers(key: string): Promise<string[]> {\n    const set = this.sets.get(key);\n    return set ? [...set] : [];\n  }\n\n  async sdel(key: string): Promise<void> {\n    this.sets.delete(key);\n  }\n\n  get size(): number {\n    return this.store.size;\n  }\n\n  get bytes(): number {\n    return this.currentBytes;\n  }\n\n  private removeEntry(key: string): void {\n    const entry = this.store.get(key);\n    if (entry) {\n      this.currentBytes -= entry.byteSize;\n      this.store.delete(key);\n    }\n  }\n\n  private evictOldest(): void {\n    const oldest = this.store.keys().next().value;\n    if (oldest !== undefined) this.removeEntry(oldest);\n  }\n}\n"],"mappings":";;AAuBA,IAAa,mBAAb,MAAoD;CAClD,wBAAgB,IAAI,IAAoE;CACxF,uBAAe,IAAI,IAAyB;CAC5C;CACA;CACA;CACA,eAAuB;CACvB;CACA,cAAuB;CAEvB,YAAY,MAA2B;EACrC,KAAK,aAAa,KAAK,IAAI,MAAM,cAAc,KAAM,CAAC;EACtD,KAAK,WAAW,MAAM;EACtB,KAAK,gBAAgB,MAAM;EAC3B,KAAK,aAAa,KAAK,aAAa,KAAA,KAAa,KAAK,kBAAkB,KAAA;CAC1E;CAEA,MAAM,IAAI,KAAqC;EAC7C,MAAM,QAAQ,KAAK,MAAM,IAAI,GAAG;EAChC,IAAI,CAAC,OAAO,OAAO;EACnB,IAAI,KAAK,IAAI,IAAI,MAAM,WAAW;GAChC,KAAK,YAAY,GAAG;GACpB,OAAO;EACT;EAEA,KAAK,MAAM,OAAO,GAAG;EACrB,KAAK,MAAM,IAAI,KAAK,KAAK;EACzB,OAAO,MAAM;CACf;CAEA,MAAM,IAAI,KAAa,OAAe,YAAmC;EACvE,MAAM,WAAW,KAAK,aAAa,iBAAiB,KAAK,IAAI;EAE7D,IAAI,KAAK,kBAAkB,KAAA,KAAa,WAAW,KAAK,eAAe;EAEvE,IAAI,KAAK,MAAM,IAAI,GAAG,GAAG,KAAK,YAAY,GAAG;EAE7C,OAAO,KAAK,MAAM,QAAQ,KAAK,YAAY,KAAK,YAAY;EAE5D,IAAI,KAAK,aAAa,KAAA,GAAW;GAC/B,OAAO,KAAK,eAAe,WAAW,KAAK,YAAY,KAAK,MAAM,OAAO,GACvE,KAAK,YAAY;GAEnB,IAAI,KAAK,eAAe,WAAW,KAAK,UAAU;EACpD;EAEA,KAAK,MAAM,IAAI,KAAK;GAAE;GAAO,WAAW,KAAK,IAAI,IAAI,aAAa;GAAM;EAAS,CAAC;EAClF,KAAK,gBAAgB;CACvB;CAEA,MAAM,IAAI,KAA4B;EACpC,KAAK,YAAY,GAAG;CACtB;CAIA,MAAM,KAAK,KAAa,SAAmB,aAAoC;EAC7E,IAAI,MAAM,KAAK,KAAK,IAAI,GAAG;EAC3B,IAAI,CAAC,KAAK;GACR,sBAAM,IAAI,IAAI;GACd,KAAK,KAAK,IAAI,KAAK,GAAG;EACxB;EACA,KAAK,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC;CACpC;CAEA,MAAM,KAAK,KAAa,SAAkC;EACxD,MAAM,MAAM,KAAK,KAAK,IAAI,GAAG;EAC7B,IAAI,CAAC,KAAK;EACV,KAAK,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC;EACrC,IAAI,IAAI,SAAS,GAAG,KAAK,KAAK,OAAO,GAAG;CAC1C;CAEA,MAAM,SAAS,KAAgC;EAC7C,MAAM,MAAM,KAAK,KAAK,IAAI,GAAG;EAC7B,OAAO,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC;CAC3B;CAEA,MAAM,KAAK,KAA4B;EACrC,KAAK,KAAK,OAAO,GAAG;CACtB;CAEA,IAAI,OAAe;EACjB,OAAO,KAAK,MAAM;CACpB;CAEA,IAAI,QAAgB;EAClB,OAAO,KAAK;CACd;CAEA,YAAoB,KAAmB;EACrC,MAAM,QAAQ,KAAK,MAAM,IAAI,GAAG;EAChC,IAAI,OAAO;GACT,KAAK,gBAAgB,MAAM;GAC3B,KAAK,MAAM,OAAO,GAAG;EACvB;CACF;CAEA,cAA4B;EAC1B,MAAM,SAAS,KAAK,MAAM,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;EACxC,IAAI,WAAW,KAAA,GAAW,KAAK,YAAY,MAAM;CACnD;AACF"}

package/dist/cache/stores/redis.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Redis CacheStore — strongly-consistent, supports native Set operations.
+ *
+ * The TagAwareCacheHandler will use the Set-based strategy automatically
+ * because this store provides sadd/smembers/srem/sdel.
+ */
+import type { CacheStore } from '../store.ts';
+/**
+ * Minimal Redis client contract. Same philosophy as the old RedisClient
+ * interface — deliberately NOT the native shape of any library. TTL is a
+ * required positional argument so no adapter can forget it.
+ *
+ * @example ioredis
+ * ```ts
+ * import Redis from 'ioredis';
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const client: RedisStoreClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),
+ *   del: (k) => redis.del(k).then(() => {}),
+ *   sadd: (k, ...m) => redis.sadd(k, ...m).then(() => {}),
+ *   srem: (k, ...m) => redis.srem(k, ...m).then(() => {}),
+ *   smembers: (k) => redis.smembers(k),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX').then(() => {}),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT').then(() => {}),
+ * };
+ * ```
+ *
+ * @example @upstash/redis
+ * ```ts
+ * import { Redis } from '@upstash/redis';
+ * const redis = new Redis({ url, token, automaticDeserialization: false });
+ * const client: RedisStoreClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { ex: ttl }).then(() => {}),
+ *   del: (k) => redis.del(k).then(() => {}),
+ *   sadd: (k, ...m) => redis.sadd(k, ...m).then(() => {}),
+ *   srem: (k, ...m) => redis.srem(k, ...m).then(() => {}),
+ *   smembers: (k) => redis.smembers(k),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX').then(() => {}),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT').then(() => {}),
+ * };
+ * ```
+ */
+export interface RedisStoreClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+    sadd(key: string, ...members: string[]): Promise<unknown>;
+    srem(key: string, ...members: string[]): Promise<unknown>;
+    smembers(key: string): Promise<string[]>;
+    /** `EXPIRE key seconds NX` — set TTL only if the key has no existing expiry (Redis 7.0+). */
+    expireNX(key: string, seconds: number): Promise<unknown>;
+    /** `EXPIRE key seconds GT` — extend TTL only if new value is greater (Redis 7.0+). */
+    expireGT(key: string, seconds: number): Promise<unknown>;
+}
+export declare class RedisCacheStore implements CacheStore {
+    private client;
+    readonly consistency: 'strong';
+    constructor(client: RedisStoreClient);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<void>;
+    sadd(key: string, members: string[], ttlSeconds: number): Promise<void>;
+    srem(key: string, members: string[]): Promise<void>;
+    smembers(key: string): Promise<string[]>;
+    sdel(key: string): Promise<void>;
+}
+//# sourceMappingURL=redis.d.ts.map

package/dist/cache/stores/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../../src/cache/stores/redis.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,6FAA6F;IAC7F,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,sFAAsF;IACtF,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAED,qBAAa,eAAgB,YAAW,UAAU;IAChD,OAAO,CAAC,MAAM,CAAmB;IACjC,QAAQ,CAAC,WAAW,EAAG,QAAQ,CAAU;IAEzC,YAAY,MAAM,EAAE,gBAAgB,EAEnC;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE7C;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvE;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpC;IAEK,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI5E;IAEK,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAExD;IAEK,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAE7C;IAEK,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErC;CACF"}

package/dist/cache/stores/redis.js

@@ -0,0 +1,35 @@
+//#region src/cache/stores/redis.ts
+var RedisCacheStore = class {
+	client;
+	consistency = "strong";
+	constructor(client) {
+		this.client = client;
+	}
+	async get(key) {
+		return this.client.get(key);
+	}
+	async set(key, value, ttlSeconds) {
+		await this.client.set(key, value, ttlSeconds);
+	}
+	async del(key) {
+		await this.client.del(key);
+	}
+	async sadd(key, members, ttlSeconds) {
+		await this.client.sadd(key, ...members);
+		await this.client.expireNX(key, ttlSeconds);
+		await this.client.expireGT(key, ttlSeconds);
+	}
+	async srem(key, members) {
+		await this.client.srem(key, ...members);
+	}
+	async smembers(key) {
+		return this.client.smembers(key);
+	}
+	async sdel(key) {
+		await this.client.del(key);
+	}
+};
+//#endregion
+export { RedisCacheStore };
+
+//# sourceMappingURL=redis.js.map

package/dist/cache/stores/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.js","names":[],"sources":["../../../src/cache/stores/redis.ts"],"sourcesContent":["/**\n * Redis CacheStore — strongly-consistent, supports native Set operations.\n *\n * The TagAwareCacheHandler will use the Set-based strategy automatically\n * because this store provides sadd/smembers/srem/sdel.\n */\n\nimport type { CacheStore } from '../store.ts';\n\n/**\n * Minimal Redis client contract. Same philosophy as the old RedisClient\n * interface — deliberately NOT the native shape of any library. TTL is a\n * required positional argument so no adapter can forget it.\n *\n * @example ioredis\n * ```ts\n * import Redis from 'ioredis';\n * const redis = new Redis(process.env.REDIS_URL);\n * const client: RedisStoreClient = {\n *   get: (k) => redis.get(k),\n *   set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),\n *   del: (k) => redis.del(k).then(() => {}),\n *   sadd: (k, ...m) => redis.sadd(k, ...m).then(() => {}),\n *   srem: (k, ...m) => redis.srem(k, ...m).then(() => {}),\n *   smembers: (k) => redis.smembers(k),\n *   expireNX: (k, s) => redis.expire(k, s, 'NX').then(() => {}),\n *   expireGT: (k, s) => redis.expire(k, s, 'GT').then(() => {}),\n * };\n * ```\n *\n * @example @upstash/redis\n * ```ts\n * import { Redis } from '@upstash/redis';\n * const redis = new Redis({ url, token, automaticDeserialization: false });\n * const client: RedisStoreClient = {\n *   get: (k) => redis.get(k),\n *   set: (k, v, ttl) => redis.set(k, v, { ex: ttl }).then(() => {}),\n *   del: (k) => redis.del(k).then(() => {}),\n *   sadd: (k, ...m) => redis.sadd(k, ...m).then(() => {}),\n *   srem: (k, ...m) => redis.srem(k, ...m).then(() => {}),\n *   smembers: (k) => redis.smembers(k),\n *   expireNX: (k, s) => redis.expire(k, s, 'NX').then(() => {}),\n *   expireGT: (k, s) => redis.expire(k, s, 'GT').then(() => {}),\n * };\n * ```\n */\nexport interface RedisStoreClient {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string, ttlSeconds: number): Promise<unknown>;\n  del(key: string): Promise<unknown>;\n  sadd(key: string, ...members: string[]): Promise<unknown>;\n  srem(key: string, ...members: string[]): Promise<unknown>;\n  smembers(key: string): Promise<string[]>;\n  /** `EXPIRE key seconds NX` — set TTL only if the key has no existing expiry (Redis 7.0+). */\n  expireNX(key: string, seconds: number): Promise<unknown>;\n  /** `EXPIRE key seconds GT` — extend TTL only if new value is greater (Redis 7.0+). */\n  expireGT(key: string, seconds: number): Promise<unknown>;\n}\n\nexport class RedisCacheStore implements CacheStore {\n  private client: RedisStoreClient;\n  readonly consistency = 'strong' as const;\n\n  constructor(client: RedisStoreClient) {\n    this.client = client;\n  }\n\n  async get(key: string): Promise<string | null> {\n    return this.client.get(key);\n  }\n\n  async set(key: string, value: string, ttlSeconds: number): Promise<void> {\n    await this.client.set(key, value, ttlSeconds);\n  }\n\n  async del(key: string): Promise<void> {\n    await this.client.del(key);\n  }\n\n  async sadd(key: string, members: string[], ttlSeconds: number): Promise<void> {\n    await this.client.sadd(key, ...members);\n    await this.client.expireNX(key, ttlSeconds);\n    await this.client.expireGT(key, ttlSeconds);\n  }\n\n  async srem(key: string, members: string[]): Promise<void> {\n    await this.client.srem(key, ...members);\n  }\n\n  async smembers(key: string): Promise<string[]> {\n    return this.client.smembers(key);\n  }\n\n  async sdel(key: string): Promise<void> {\n    await this.client.del(key);\n  }\n}\n"],"mappings":";AA2DA,IAAa,kBAAb,MAAmD;CACjD;CACA,cAAuB;CAEvB,YAAY,QAA0B;EACpC,KAAK,SAAS;CAChB;CAEA,MAAM,IAAI,KAAqC;EAC7C,OAAO,KAAK,OAAO,IAAI,GAAG;CAC5B;CAEA,MAAM,IAAI,KAAa,OAAe,YAAmC;EACvE,MAAM,KAAK,OAAO,IAAI,KAAK,OAAO,UAAU;CAC9C;CAEA,MAAM,IAAI,KAA4B;EACpC,MAAM,KAAK,OAAO,IAAI,GAAG;CAC3B;CAEA,MAAM,KAAK,KAAa,SAAmB,YAAmC;EAC5E,MAAM,KAAK,OAAO,KAAK,KAAK,GAAG,OAAO;EACtC,MAAM,KAAK,OAAO,SAAS,KAAK,UAAU;EAC1C,MAAM,KAAK,OAAO,SAAS,KAAK,UAAU;CAC5C;CAEA,MAAM,KAAK,KAAa,SAAkC;EACxD,MAAM,KAAK,OAAO,KAAK,KAAK,GAAG,OAAO;CACxC;CAEA,MAAM,SAAS,KAAgC;EAC7C,OAAO,KAAK,OAAO,SAAS,GAAG;CACjC;CAEA,MAAM,KAAK,KAA4B;EACrC,MAAM,KAAK,OAAO,IAAI,GAAG;CAC3B;AACF"}

package/dist/cache/stores/vercel.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Vercel Runtime Cache CacheStore — native tag support.
+ *
+ * Delegates tag operations to Vercel's infrastructure via their Runtime Cache
+ * API (getCache/expireTag). The TagAwareCacheHandler detects setWithTags +
+ * invalidateTag and delegates entirely — no inverted index, no version stamps.
+ *
+ * Vercel handles tag purging across CDN, Runtime Cache, and Data Cache layers
+ * simultaneously. Available on all plans.
+ */
+import type { CacheStore } from '../store.ts';
+/**
+ * Vercel Runtime Cache contract — the subset we depend on.
+ * Resolved from `@vercel/functions` at runtime.
+ */
+export interface VercelCache {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, options: {
+        ttl: number;
+        tags?: string[];
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    expireTag(tag: string): Promise<void>;
+}
+export declare class VercelCacheStore implements CacheStore {
+    private cache;
+    readonly consistency: 'strong';
+    constructor(cache: VercelCache | (() => VercelCache));
+    private getCache;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    del(key: string): Promise<void>;
+    setWithTags(key: string, value: string, ttlSeconds: number, tags: string[]): Promise<void>;
+    invalidateTag(tag: string): Promise<void>;
+}
+//# sourceMappingURL=vercel.d.ts.map

package/dist/cache/stores/vercel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel.d.ts","sourceRoot":"","sources":["../../../src/cache/stores/vercel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,KAAK,CAAoC;IACjD,QAAQ,CAAC,WAAW,EAAG,QAAQ,CAAU;IAEzC,YAAY,KAAK,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,EAEnD;IAED,OAAO,CAAC,QAAQ;IAIV,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAG7C;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvE;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpC;IAIK,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F;IAEK,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9C;CACF"}

package/dist/cache/stores/vercel.js

@@ -0,0 +1,33 @@
+//#region src/cache/stores/vercel.ts
+var VercelCacheStore = class {
+	cache;
+	consistency = "strong";
+	constructor(cache) {
+		this.cache = cache;
+	}
+	getCache() {
+		return typeof this.cache === "function" ? this.cache() : this.cache;
+	}
+	async get(key) {
+		return await this.getCache().get(key) ?? null;
+	}
+	async set(key, value, ttlSeconds) {
+		await this.getCache().set(key, value, { ttl: ttlSeconds });
+	}
+	async del(key) {
+		await this.getCache().delete(key);
+	}
+	async setWithTags(key, value, ttlSeconds, tags) {
+		await this.getCache().set(key, value, {
+			ttl: ttlSeconds,
+			tags
+		});
+	}
+	async invalidateTag(tag) {
+		await this.getCache().expireTag(tag);
+	}
+};
+//#endregion
+export { VercelCacheStore };
+
+//# sourceMappingURL=vercel.js.map

package/dist/cache/stores/vercel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel.js","names":[],"sources":["../../../src/cache/stores/vercel.ts"],"sourcesContent":["/**\n * Vercel Runtime Cache CacheStore — native tag support.\n *\n * Delegates tag operations to Vercel's infrastructure via their Runtime Cache\n * API (getCache/expireTag). The TagAwareCacheHandler detects setWithTags +\n * invalidateTag and delegates entirely — no inverted index, no version stamps.\n *\n * Vercel handles tag purging across CDN, Runtime Cache, and Data Cache layers\n * simultaneously. Available on all plans.\n */\n\nimport type { CacheStore } from '../store.ts';\n\n/**\n * Vercel Runtime Cache contract — the subset we depend on.\n * Resolved from `@vercel/functions` at runtime.\n */\nexport interface VercelCache {\n  get(key: string): Promise<string | undefined>;\n  set(key: string, value: string, options: { ttl: number; tags?: string[] }): Promise<void>;\n  delete(key: string): Promise<void>;\n  expireTag(tag: string): Promise<void>;\n}\n\nexport class VercelCacheStore implements CacheStore {\n  private cache: VercelCache | (() => VercelCache);\n  readonly consistency = 'strong' as const;\n\n  constructor(cache: VercelCache | (() => VercelCache)) {\n    this.cache = cache;\n  }\n\n  private getCache(): VercelCache {\n    return typeof this.cache === 'function' ? this.cache() : this.cache;\n  }\n\n  async get(key: string): Promise<string | null> {\n    const result = await this.getCache().get(key);\n    return result ?? null;\n  }\n\n  async set(key: string, value: string, ttlSeconds: number): Promise<void> {\n    await this.getCache().set(key, value, { ttl: ttlSeconds });\n  }\n\n  async del(key: string): Promise<void> {\n    await this.getCache().delete(key);\n  }\n\n  // --- Native tag support ---\n\n  async setWithTags(key: string, value: string, ttlSeconds: number, tags: string[]): Promise<void> {\n    await this.getCache().set(key, value, { ttl: ttlSeconds, tags });\n  }\n\n  async invalidateTag(tag: string): Promise<void> {\n    await this.getCache().expireTag(tag);\n  }\n}\n"],"mappings":";AAwBA,IAAa,mBAAb,MAAoD;CAClD;CACA,cAAuB;CAEvB,YAAY,OAA0C;EACpD,KAAK,QAAQ;CACf;CAEA,WAAgC;EAC9B,OAAO,OAAO,KAAK,UAAU,aAAa,KAAK,MAAM,IAAI,KAAK;CAChE;CAEA,MAAM,IAAI,KAAqC;EAE7C,OAAO,MADc,KAAK,SAAS,CAAC,CAAC,IAAI,GAAG,KAC3B;CACnB;CAEA,MAAM,IAAI,KAAa,OAAe,YAAmC;EACvE,MAAM,KAAK,SAAS,CAAC,CAAC,IAAI,KAAK,OAAO,EAAE,KAAK,WAAW,CAAC;CAC3D;CAEA,MAAM,IAAI,KAA4B;EACpC,MAAM,KAAK,SAAS,CAAC,CAAC,OAAO,GAAG;CAClC;CAIA,MAAM,YAAY,KAAa,OAAe,YAAoB,MAA+B;EAC/F,MAAM,KAAK,SAAS,CAAC,CAAC,IAAI,KAAK,OAAO;GAAE,KAAK;GAAY;EAAK,CAAC;CACjE;CAEA,MAAM,cAAc,KAA4B;EAC9C,MAAM,KAAK,SAAS,CAAC,CAAC,UAAU,GAAG;CACrC;AACF"}

package/dist/cache/tag-aware-handler.d.ts

@@ -0,0 +1,52 @@
+/**
+ * TagAwareCacheHandler — wraps any CacheStore and adds tag-based invalidation.
+ *
+ * Three strategies, selected by store capabilities (best available wins):
+ *
+ * 1. **Native** (store has setWithTags + invalidateTag): Delegates entirely.
+ *    The store owns tag indexing. Used for Vercel Runtime Cache, DO-backed
+ *    stores, or any platform with first-class tag support.
+ *
+ * 2. **Eager** (store has sadd/smembers/srem/sdel): Maintains an inverted
+ *    index via atomic set operations. Invalidation enumerates the set and
+ *    deletes entries. Used for Redis.
+ *
+ * 3. **Lazy** (bare get/set/del only): Version-stamps entries with tag
+ *    counters. Invalidation bumps a counter (O(1)). Reads validate stored
+ *    versions against current. Race-free, correct under eventual consistency.
+ *    Used for Cloudflare KV.
+ *
+ * Implements the CacheHandler interface consumed by timber-cache.ts.
+ */
+import type { CacheHandler } from './index.ts';
+import type { CacheStore } from './store.ts';
+export declare class TagAwareCacheHandler implements CacheHandler {
+    private store;
+    private prefix;
+    private strategy;
+    constructor(store: CacheStore, opts?: {
+        prefix?: string;
+    });
+    get consistency(): 'strong' | 'eventual' | 'local';
+    private dataKey;
+    /** Namespace tags for native stores so prefix isolates shared stores. */
+    private prefixTags;
+    private tagSetKey;
+    private tagVersionKey;
+    get(key: string): Promise<{
+        value: unknown;
+        stale: boolean;
+    } | null>;
+    set(key: string, value: unknown, opts: {
+        ttl: number;
+        tags: string[];
+        generation?: number;
+    }): Promise<void>;
+    invalidate(opts: {
+        key?: string;
+        tag?: string;
+    }): Promise<void>;
+    private getTagVersions;
+    private bumpTagVersion;
+}
+//# sourceMappingURL=tag-aware-handler.d.ts.map

package/dist/cache/tag-aware-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-aware-handler.d.ts","sourceRoot":"","sources":["../../src/cache/tag-aware-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAiD7C,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAW;IAE3B,YAAY,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAIxD;IAED,IAAI,WAAW,IAAI,QAAQ,GAAG,UAAU,GAAG,OAAO,CAEjD;IAED,OAAO,CAAC,OAAO;IAIf,yEAAyE;IACzE,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;IAIf,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAsBzE;IAEK,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GACzD,OAAO,CAAC,IAAI,CAAC,CAgDf;IAEK,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CpE;YAIa,cAAc;YAWd,cAAc;CAe7B"}

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

@@ -1,21 +1,31 @@
-import type { CacheHandler, CacheOptions } from './index';
+import type { CacheHandler, CacheOptions } from './index.ts';
+/**
+ * Set the timeout for the module-level default singleflight.
+ * Called at framework boot with renderTimeoutMs from timber.config.ts so that
+ * cache calls without a per-call timeoutMs still get deadlock protection.
+ * See design/06-caching.md §"Singleflight Timeout — Deadlock Risk".
+ */
+export declare function setDefaultSingleflightTimeout(timeoutMs: number): void;
 /**
  * Creates a cached wrapper around an async function.
  *
- * - SHA-256 default keys with normalized JSON args
- * - Singleflight: concurrent misses → single execution
+ * - FNV-1a default keys with normalized JSON args
+ * - Singleflight: concurrent misses → single execution AND single
+ *   handler.set — the write happens inside the coalesced callback (TIM-1028)
+ * - Writes are skipped when the key/tags were invalidated while fn was in
+ *   flight, so explicit invalidation is never silently undone (TIM-1028)
  * - SWR: serve stale immediately, background refetch
  * - Tags as string[] or function of args
- * - No ALS dependency
+ * - The handler is resolved per invocation via `getHandler`, never captured
+ *   at wrapper-creation time — module-scope cache() wrappers created before
+ *   the framework's boot wiring calls setCacheHandler() still use the
+ *   configured handler once it arrives (TIM-1029)
+ * - No ALS dependency for correctness — cache() works outside a request
+ *   context. The waitUntil ALS bridge is read optionally so the SWR
+ *   background refetch survives handler return on Workers/Lambda.
  *
  * 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 namespace createCache {
-    var invalidate: (handler: CacheHandler, opts: {
-        key?: string;
-        tag?: string;
-    }) => Promise<void>;
-}
+export declare function createCache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, getHandler: () => CacheHandler, stableId?: string): Fn;
 //# sourceMappingURL=timber-cache.d.ts.map

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,YAAY,CAAC;AA+B7D;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAErE;AAoED;;;;;;;;;;;;;;;;;;;;GAoBG;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,UAAU,EAAE,MAAM,YAAY,EAC9B,QAAQ,CAAC,EAAE,MAAM,GAChB,EAAE,CAiHJ"}

package/dist/cdn/cloudflare-purge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cloudflare CDN purge handler — purges by cache tag via the Cloudflare API.
+ *
+ * Requires Cloudflare Enterprise for tag-based purging.
+ * See https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/
+ */
+import type { CdnPurgeHandler } from './purge-store.ts';
+export interface CloudflarePurgeOptions {
+    /** Cloudflare zone ID. */
+    zoneId: string;
+    /** API token with Cache Purge permission. */
+    apiToken: string;
+    /** Override fetch for testing. */
+    fetch?: typeof globalThis.fetch;
+}
+export declare class CloudflarePurge implements CdnPurgeHandler {
+    private readonly zoneId;
+    private readonly apiToken;
+    private readonly _fetch;
+    constructor(opts: CloudflarePurgeOptions);
+    purgeTags(tags: string[]): Promise<void>;
+}
+//# sourceMappingURL=cloudflare-purge.d.ts.map

package/dist/cdn/cloudflare-purge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-purge.d.ts","sourceRoot":"","sources":["../../src/cdn/cloudflare-purge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,qBAAa,eAAgB,YAAW,eAAe;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IAEjD,YAAY,IAAI,EAAE,sBAAsB,EAIvC;IAEK,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB7C;CACF"}