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

package/src/cache/handler-store.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+
+// Inline the interface to avoid circular import with index.ts
+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>;
+}
+
+let handler: CacheHandlerLike | null = null;
+
+let explicitlyConfigured = false;
+
+/** Replace the active cache handler. Called by the framework at boot. */
+export function setCacheHandler(h: CacheHandlerLike): void {
+  handler = h;
+  explicitlyConfigured = true;
+}
+
+/** Whether the handler was explicitly configured (vs the default in-memory fallback). */
+export function isCacheHandlerConfigured(): boolean {
+  return explicitlyConfigured;
+}
+
+/**
+ * Get the active cache handler. Creates a default MemoryCacheHandler on
+ * first access if none has been set via setCacheHandler().
+ */
+export function getCacheHandler(): CacheHandlerLike {
+  if (!handler) {
+    // Inline a minimal LRU cache to avoid circular dep with index.ts.
+    // In production, the framework always calls setCacheHandler() at boot.
+    handler = createDefaultHandler();
+  }
+  return handler;
+}
+
+function createDefaultHandler(): CacheHandlerLike {
+  const store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();
+  const maxEntries = 1000;
+
+  return {
+    async get(key) {
+      const entry = store.get(key);
+      if (!entry) return null;
+      store.delete(key);
+      store.set(key, entry);
+      const stale = Date.now() > entry.expiresAt;
+      return { value: entry.value, stale };
+    },
+    async set(key, value, opts) {
+      if (store.has(key)) store.delete(key);
+      while (store.size >= maxEntries) {
+        const oldest = store.keys().next().value;
+        if (oldest !== undefined) store.delete(oldest);
+        else break;
+      }
+      store.set(key, { value, expiresAt: Date.now() + opts.ttl * 1000, tags: opts.tags });
+    },
+    async invalidate(opts) {
+      if (opts.key) store.delete(opts.key);
+      if (opts.tag) {
+        for (const [key, entry] of store) {
+          if (entry.tags.includes(opts.tag)) store.delete(key);
+        }
+      }
+    },
+  };
+}

package/src/cache/index.ts

@@ -1,5 +1,7 @@
 // @timber-js/app/cache — Caching primitives
 
+import { estimateByteSize } from './sizeof.js';
+
 export interface CacheHandler {
   get(key: string): Promise<{ value: unknown; stale: boolean } | null>;
   set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;
@@ -12,19 +14,42 @@ 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 class MemoryCacheHandler implements CacheHandler {
-  private store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();
-  private maxSize: number;
+  private store = new Map<
+    string,
+    { value: unknown; expiresAt: number; tags: string[]; byteSize: number }
+  >();
+  private maxEntries: number;
+  private maxBytes: number | undefined;
+  private maxEntryBytes: number | undefined;
+  private currentBytes = 0;
+  private readonly _trackBytes: boolean;
 
   constructor(opts?: MemoryCacheHandlerOptions) {
-    this.maxSize = opts?.maxSize ?? 1000;
+    // maxEntries takes precedence over deprecated maxSize
+    this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1000;
+    this.maxBytes = opts?.maxBytes;
+    this.maxEntryBytes = opts?.maxEntryBytes;
+    this._trackBytes = this.maxBytes !== undefined || this.maxEntryBytes !== undefined;
   }
 
   async get(key: string) {
@@ -40,18 +65,33 @@ export class MemoryCacheHandler implements CacheHandler {
   }
 
   async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {
-    // If key already exists, delete first to refresh insertion order
+    const byteSize = this._trackBytes ? estimateByteSize(value) : 0;
+
+    // Reject entries exceeding per-entry byte limit
+    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) {
+      return;
+    }
+
+    // If key already exists, delete first to refresh insertion order and reclaim bytes
     if (this.store.has(key)) {
+      const existing = this.store.get(key)!;
+      this.currentBytes -= existing.byteSize;
       this.store.delete(key);
     }
 
-    // Evict oldest entries (front of Map) if at capacity
-    while (this.store.size >= this.maxSize) {
-      const oldest = this.store.keys().next().value;
-      if (oldest !== undefined) {
-        this.store.delete(oldest);
-      } else {
-        break;
+    // Evict oldest entries (front of Map) if at entry count capacity
+    while (this.store.size >= this.maxEntries) {
+      this.evictOldest();
+    }
+
+    // Evict oldest entries if byte budget would be exceeded
+    if (this.maxBytes !== undefined) {
+      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {
+        this.evictOldest();
+      }
+      // If the single entry exceeds the total byte budget, don't store it
+      if (this.currentBytes + byteSize > this.maxBytes) {
+        return;
       }
     }
 
@@ -59,16 +99,23 @@ export class MemoryCacheHandler implements CacheHandler {
       value,
       expiresAt: Date.now() + opts.ttl * 1000,
       tags: opts.tags,
+      byteSize,
     });
+    this.currentBytes += byteSize;
   }
 
   async invalidate(opts: { key?: string; tag?: string }) {
     if (opts.key) {
-      this.store.delete(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.currentBytes -= entry.byteSize;
           this.store.delete(key);
         }
       }
@@ -79,13 +126,36 @@ export class MemoryCacheHandler implements CacheHandler {
   get size(): number {
     return this.store.size;
   }
+
+  /** Estimated total byte size of all cached values. Only tracked when maxBytes or maxEntryBytes is configured; returns 0 otherwise. */
+  get bytes(): number {
+    return this.currentBytes;
+  }
+
+  /** Evict the oldest entry (front of Map). */
+  private evictOldest(): void {
+    const oldest = this.store.keys().next().value;
+    if (oldest !== undefined) {
+      const entry = this.store.get(oldest)!;
+      this.currentBytes -= entry.byteSize;
+      this.store.delete(oldest);
+    }
+  }
 }
 
 export { RedisCacheHandler } from './redis-handler';
 export type { RedisClient } from './redis-handler';
-export { createCache } from './timber-cache';
-export { registerCachedFunction } from './register-cached-function';
-export type { RegisterCachedFunctionOptions } from './register-cached-function';
-export { stableStringify } from './stable-stringify';
-export { createSingleflight } from './singleflight';
-export type { Singleflight } from './singleflight';
+export { cache } from './cache-api';
+export { setCacheHandler, getCacheHandler } from './handler-store';
+export { setDefaultSingleflightTimeout } from './timber-cache';
+// NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.
+// Future feature pending design doc. See design/06-caching.md.
+export { estimateByteSize } from './sizeof';
+
+// --- Cache Store layering (design/46) ---
+export { TagAwareCacheHandler } from './tag-aware-handler';
+export type { CacheStore } from './store';
+// stableStringify, createSingleflight, and SingleflightTimeoutError are
+// internal utilities used by the cache implementation. They are not
+// re-exported here — import directly from the source files if needed
+// within the package. See TIM-720.

package/src/cache/invalidation-epoch.ts

@@ -0,0 +1,93 @@
+/**
+ * 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.
+ */
+
+let epoch = 0;
+
+/**
+ * Last-invalidated epoch per `key:<k>` / `tag:<t>` entry. Insertion order is
+ * epoch order (entries are re-inserted on update), so the oldest entry is
+ * always first — pruning evicts lowest epochs.
+ */
+const lastInvalidated = new Map<string, number>();
+
+/**
+ * Bound on tracked entries so high-cardinality tag invalidation (e.g.
+ * per-user tags) cannot grow this map without limit.
+ */
+const MAX_TRACKED_ENTRIES = 10_000;
+
+/**
+ * Highest epoch evicted from the map. Any execution that started at or
+ * before this epoch conservatively counts as invalidated — history was
+ * truncated, so we can no longer prove it wasn't.
+ */
+let evictedEpochFloor = 0;
+
+/** The current epoch. Capture before running fn(), pass to wasInvalidatedSince. */
+export function currentInvalidationEpoch(): number {
+  return epoch;
+}
+
+/**
+ * Record an invalidation. Call BEFORE handler.invalidate() so an execution
+ * whose set-check races the invalidation errs toward skipping the write.
+ */
+export function recordInvalidation(opts: { key?: string; tag?: string }): void {
+  epoch++;
+  if (opts.key) track(`key:${opts.key}`);
+  if (opts.tag) track(`tag:${opts.tag}`);
+}
+
+function track(entry: string): void {
+  lastInvalidated.delete(entry);
+  lastInvalidated.set(entry, epoch);
+  while (lastInvalidated.size > MAX_TRACKED_ENTRIES) {
+    const oldest = lastInvalidated.entries().next().value;
+    if (oldest === undefined) break;
+    evictedEpochFloor = Math.max(evictedEpochFloor, oldest[1]);
+    lastInvalidated.delete(oldest[0]);
+  }
+}
+
+/**
+ * Whether the key or any tag was invalidated after `startEpoch` (the epoch
+ * captured when fn started executing).
+ */
+export function wasInvalidatedSince(startEpoch: number, key: string, tags: string[]): boolean {
+  return lastInvalidationEpochFor(key, tags) > startEpoch;
+}
+
+/**
+ * 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 function lastInvalidationEpochFor(key: string, tags: string[]): number {
+  let last = evictedEpochFloor;
+  const keyEpoch = lastInvalidated.get(`key:${key}`);
+  if (keyEpoch !== undefined && keyEpoch > last) last = keyEpoch;
+  for (const tag of tags) {
+    const tagEpoch = lastInvalidated.get(`tag:${tag}`);
+    if (tagEpoch !== undefined && tagEpoch > last) last = tagEpoch;
+  }
+  return last;
+}

package/src/cache/redis-handler.ts

@@ -1,16 +1,104 @@
 import type { CacheHandler } from './index';
 
 /**
- * Minimal Redis client interface — compatible with ioredis, node-redis, and
- * Cloudflare Workers Redis bindings. We depend on the interface, not the
- * implementation, so users bring their own Redis client.
+ * Minimal Redis client contract for `RedisCacheHandler`.
+ *
+ * This is deliberately NOT the native shape of any client library. ioredis,
+ * node-redis v4, and @upstash/redis all disagree on TTL argument shapes
+ * (positional `'EX'` vs `{ EX }` vs `{ ex }`), method casing (`sadd` vs
+ * `sAdd`), and array handling in `del` — a contract that pattern-matches one
+ * client lets another silently drop the expiry (TIM-1030: node-redis ignored
+ * the positional `'EX'` and wrote keys with no TTL). Instead, TTL semantics
+ * are explicit in the signature and you adapt your client with a thin
+ * wrapper, so a mismatch is a type error rather than silent unbounded
+ * keyspace growth.
+ *
+ * @example ioredis
+ * ```ts
+ * import Redis from 'ioredis';
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sadd(k, ...m),
+ *   srem: (k, ...m) => redis.srem(k, ...m),
+ *   smembers: (k) => redis.smembers(k),
+ *   ttl: (k) => redis.ttl(k),
+ * };
+ * ```
+ *
+ * @example node-redis v4
+ * ```ts
+ * import { createClient } from 'redis';
+ * const redis = createClient({ url: process.env.REDIS_URL });
+ * await redis.connect();
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { EX: ttl }),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sAdd(k, m),
+ *   srem: (k, ...m) => redis.sRem(k, m),
+ *   smembers: (k) => redis.sMembers(k),
+ *   ttl: (k) => redis.ttl(k),
+ * };
+ * ```
+ *
+ * @example @upstash/redis
+ * ```ts
+ * import { Redis } from '@upstash/redis';
+ * // automaticDeserialization must be off: the handler stores JSON strings
+ * // and parses them itself — auto-parsing would hand back objects.
+ * const redis = new Redis({ url, token, automaticDeserialization: false });
+ * const client: RedisClient = {
+ *   get: (k) => redis.get(k),
+ *   set: (k, v, ttl) => redis.set(k, v, { ex: ttl }),
+ *   expireNX: (k, s) => redis.expire(k, s, 'NX'),
+ *   expireGT: (k, s) => redis.expire(k, s, 'GT'),
+ *   del: (k) => redis.del(k),
+ *   sadd: (k, ...m) => redis.sadd(k, m[0], ...m.slice(1)),
+ *   srem: (k, ...m) => redis.srem(k, m[0], ...m.slice(1)),
+ *   smembers: (k) => redis.smembers(k),
+ *   ttl: (k) => redis.ttl(k),
+ * };
+ * ```
  */
 export interface RedisClient {
+  /** `GET key` — the stored string, or null when absent. */
   get(key: string): Promise<string | null>;
-  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
-  del(key: string | string[]): Promise<number>;
-  sadd(key: string, ...members: string[]): Promise<number>;
+  /**
+   * `SET key value EX ttlSeconds` — store with an expiry. The TTL is a
+   * required positional argument so no adapter can forget it.
+   */
+  set(key: string, value: string, ttlSeconds: number): Promise<unknown>;
+  /**
+   * `EXPIRE key seconds NX` — set the TTL only if the key has no existing
+   * expiry (Redis 7.0+). Used to set the initial TTL on new tag sets.
+   */
+  expireNX(key: string, seconds: number): Promise<unknown>;
+  /**
+   * `EXPIRE key seconds GT` — update the TTL only if the new value is greater
+   * than the current one (Redis 7.0+). Used to extend tag set TTLs without
+   * allowing a short-TTL writer to shrink them.
+   */
+  expireGT(key: string, seconds: number): Promise<unknown>;
+  /** `DEL key` — delete a single key. Multi-key deletes loop per key. */
+  del(key: string): Promise<unknown>;
+  /** `SADD key member [member ...]` — add members to a set. */
+  sadd(key: string, ...members: string[]): Promise<unknown>;
+  /** `SREM key member [member ...]` — remove members from a set. */
+  srem(key: string, ...members: string[]): Promise<unknown>;
+  /** `SMEMBERS key` — all members of a set. */
   smembers(key: string): Promise<string[]>;
+  /**
+   * `TTL key` — remaining time-to-live in seconds. Returns -2 if the key does
+   * not exist, -1 if the key exists but has no expiry.
+   */
+  ttl(key: string): Promise<number>;
 }
 
 const KEY_PREFIX = 'timber:cache:';
@@ -23,8 +111,9 @@ const TAG_PREFIX = 'timber:tag:';
  * 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 class RedisCacheHandler implements CacheHandler {
   private client: RedisClient;
@@ -55,23 +144,41 @@ export class RedisCacheHandler implements CacheHandler {
   async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
     const ck = this.cacheKey(key);
     const expiresAt = Date.now() + opts.ttl * 1000;
-    const payload = JSON.stringify({ value, expiresAt });
+    const payload = JSON.stringify({ value, expiresAt, tags: opts.tags });
 
     // Redis TTL with generous margin beyond the logical TTL to allow SWR reads
     // on stale entries. The logical staleness is determined by expiresAt.
     // We use 2x TTL + 60s as the Redis expiry so stale entries remain
     // available for SWR background refetches.
     const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
-    await this.client.set(ck, payload, 'EX', redisTtlSeconds);
+    await this.client.set(ck, payload, redisTtlSeconds);
 
-    // Track key membership in each tag set
+    // Track key membership in each tag set, and expire the set so it doesn't
+    // outlive all its members. Only extend the TTL, never shorten — a short-TTL
+    // entry must not shrink a tag set that already contains long-TTL entries,
+    // otherwise invalidate({tag}) would miss the long-lived entries.
     for (const tag of opts.tags) {
       await this.client.sadd(this.tagKey(tag), key);
+      // Two atomic EXPIRE calls cover both the initial-set and extend cases:
+      // - NX: sets the TTL only if the key has no expiry (new tag set from SADD)
+      // - GT: extends the TTL only if the new value is greater than current
+      // Together they close the race where concurrent workers could shrink the
+      // tag set lifetime (TIM-1093), while ensuring new tag sets always get an
+      // initial expiry (without NX, GT is a no-op on non-volatile keys).
+      await this.client.expireNX(this.tagKey(tag), redisTtlSeconds);
+      await this.client.expireGT(this.tagKey(tag), redisTtlSeconds);
     }
   }
 
   async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
     if (opts.key) {
+      const raw = await this.client.get(this.cacheKey(opts.key));
+      if (raw !== null) {
+        const entry = JSON.parse(raw) as { tags?: string[] };
+        if (entry.tags) {
+          await Promise.all(entry.tags.map((tag) => this.client.srem(this.tagKey(tag), opts.key!)));
+        }
+      }
       await this.client.del(this.cacheKey(opts.key));
     }
 
@@ -79,10 +186,10 @@ export class RedisCacheHandler implements CacheHandler {
       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);
-      }
+      // One del per key: the only multi-key shape every client accepts.
+      // ioredis takes del(...keys), node-redis takes del(key | key[]), and
+      // @upstash/redis takes del(...keys) but breaks on an array argument.
+      await Promise.all(keys.map((k) => this.client.del(this.cacheKey(k))));
 
       // Clean up the tag set itself
       await this.client.del(tk);

package/src/cache/singleflight.ts

@@ -3,24 +3,82 @@
  * 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>;
 }
 
-export function createSingleflight(): Singleflight {
+/**
+ * Error thrown when a singleflight call exceeds `timeoutMs`.
+ * Exported so callers can distinguish timeout from other errors.
+ */
+export class SingleflightTimeoutError extends Error {
+  constructor(key: string, timeoutMs: number) {
+    super(`Singleflight timeout: key "${key}" exceeded ${timeoutMs}ms`);
+    this.name = 'SingleflightTimeoutError';
+  }
+}
+
+export function createSingleflight(opts?: SingleflightOptions): Singleflight {
   const inflight = new Map<string, Promise<unknown>>();
+  const timeoutMs = opts?.timeoutMs;
 
   return {
-    do<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    do<T>(key: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T> {
       const existing = inflight.get(key);
       if (existing) return existing as Promise<T>;
 
-      const promise = fn().finally(() => {
+      const ac = new AbortController();
+      let promise: Promise<T>;
+
+      if (timeoutMs != null && timeoutMs > 0) {
+        // Race fn() against a timeout to prevent hung calls from
+        // permanently blocking the key. See TIM-518.
+        // Abort the signal on timeout so the callback can skip
+        // side effects (e.g. cache writes). See TIM-1092.
+        promise = new Promise<T>((resolve, reject) => {
+          const timer = setTimeout(() => {
+            ac.abort();
+            reject(new SingleflightTimeoutError(key, timeoutMs));
+          }, timeoutMs);
+          try {
+            fn(ac.signal).then(
+              (value) => {
+                clearTimeout(timer);
+                resolve(value);
+              },
+              (err) => {
+                clearTimeout(timer);
+                reject(err);
+              }
+            );
+          } catch (err) {
+            clearTimeout(timer);
+            reject(err);
+          }
+        });
+      } else {
+        promise = fn(ac.signal);
+      }
+
+      const tracked = promise.finally(() => {
         inflight.delete(key);
       });
-      inflight.set(key, promise);
-      return promise;
+
+      inflight.set(key, tracked);
+      return tracked as Promise<T>;
     },
   };
 }

package/src/cache/sizeof.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 function estimateByteSize(value: unknown): number {
+  try {
+    const json = JSON.stringify(value);
+    if (json === undefined) return 0;
+    // Each JS string character is 2 bytes (UTF-16)
+    return json.length * 2;
+  } catch (e) {
+    // Circular reference or non-serializable value
+    console.debug('[timber] sizeof estimation failed:', e instanceof Error ? e.message : e);
+    return 0;
+  }
+}