@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.61

package/src/cache/fast-hash.ts

@@ -0,0 +1,34 @@
+/**
+ * Fast non-cryptographic hash for cache keys.
+ *
+ * FNV-1a 64-bit produces a well-distributed hash with a collision
+ * probability of ~1 in 5 billion at 77k keys (birthday paradox).
+ * Not suitable for security, but ideal for cache key generation
+ * where we need speed over crypto strength.
+ *
+ * Uses BigInt for 64-bit arithmetic — supported in all modern runtimes
+ * including Cloudflare Workers. No node:crypto dependency.
+ *
+ * See TIM-370.
+ */
+
+// FNV-1a constants for 64-bit hash
+const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const MASK_64 = 0xffffffffffffffffn;
+
+/**
+ * Compute a 64-bit FNV-1a hash of a string, returned as a 16-char hex string.
+ *
+ * 64 bits gives ~5 billion keys before a 50% collision probability
+ * (birthday paradox), making accidental collisions effectively impossible
+ * for cache key use cases.
+ */
+export function fnv1aHash(input: string): string {
+  let hash = FNV_OFFSET_BASIS;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= BigInt(input.charCodeAt(i));
+    hash = (hash * FNV_PRIME) & MASK_64;
+  }
+  return hash.toString(16).padStart(16, '0');
+}

package/src/cache/index.ts

@@ -12,6 +12,9 @@ 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 {
@@ -87,5 +90,5 @@ 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 { createSingleflight, SingleflightTimeoutError } from './singleflight';
+export type { Singleflight, SingleflightOptions } from './singleflight';

package/src/cache/register-cached-function.ts

@@ -1,7 +1,7 @@
-import { createHash } from 'node:crypto';
 import type { CacheHandler } from './index';
 import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
+import { fnv1aHash } from './fast-hash.js';
 
 const singleflight = createSingleflight();
 
@@ -27,11 +27,15 @@ export interface RegisterCachedFunctionOptions<Fn extends (...args: any[]) => an
 }
 
 /**
- * Generate a SHA-256 cache key from a stable function ID and serialized args.
+ * Generate a cache key from a stable function ID and serialized args.
+ *
+ * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. The id prefix
+ * provides namespace isolation; the hash covers the args.
+ * See TIM-370.
  */
 function generateKey(id: string, args: unknown[]): string {
   const raw = id + ':' + stableStringify(args);
-  return createHash('sha256').update(raw).digest('hex');
+  return id + ':' + fnv1aHash(raw);
 }
 
 /**

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>;
 }
 
-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> {
       const existing = inflight.get(key);
       if (existing) return existing as Promise<T>;
 
-      const promise = fn().finally(() => {
+      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.
+        promise = new Promise<T>((resolve, reject) => {
+          const timer = setTimeout(
+            () => reject(new SingleflightTimeoutError(key, timeoutMs)),
+            timeoutMs
+          );
+          // Wrap in try/catch so a synchronous throw from fn()
+          // (e.g. argument validation) still clears the timer.
+          // Without this, the timer leaks until expiry.
+          try {
+            fn().then(
+              (value) => {
+                clearTimeout(timer);
+                resolve(value);
+              },
+              (err) => {
+                clearTimeout(timer);
+                reject(err);
+              }
+            );
+          } catch (err) {
+            clearTimeout(timer);
+            reject(err);
+          }
+        });
+      } else {
+        promise = fn();
+      }
+
+      const tracked = promise.finally(() => {
         inflight.delete(key);
       });
-      inflight.set(key, promise);
-      return promise;
+
+      inflight.set(key, tracked);
+      return tracked as Promise<T>;
     },
   };
 }

package/src/cache/timber-cache.ts

@@ -1,17 +1,23 @@
-import { createHash } from 'node:crypto';
 import type { CacheHandler, CacheOptions } from './index';
 import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
-import { addSpanEvent } from '#/server/tracing.js';
+import { addSpanEventSync } from '../server/tracing.js';
+import { fnv1aHash } from './fast-hash.js';
 
-const singleflight = createSingleflight();
+const defaultSingleflight = createSingleflight();
 
 /**
- * Generate a SHA-256 cache key from function identity and serialized args.
+ * Generate a cache key from function identity and serialized args.
+ *
+ * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't
+ * need collision resistance — they need speed. The fnId prefix provides
+ * namespace isolation; the hash covers the args.
+ *
+ * See TIM-370 for perf motivation.
  */
 function defaultKeyGenerator(fnId: string, args: unknown[]): string {
   const raw = fnId + ':' + stableStringify(args);
-  return createHash('sha256').update(raw).digest('hex');
+  return fnId + ':' + fnv1aHash(raw);
 }
 
 /**
@@ -47,18 +53,25 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
   fn: Fn,
   opts: CacheOptions<Fn>,
   handler: CacheHandler
-): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {
+): Fn {
   const fnId = `timber-cache:${fnIdCounter++}`;
+  const sf = opts.timeoutMs
+    ? createSingleflight({ timeoutMs: opts.timeoutMs })
+    : defaultSingleflight;
 
-  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
+  // Cast to Fn to preserve the original function's generic call signature.
+  // Without this, generic type parameters (e.g. <T> in apiFetch<T>) are
+  // erased and callers lose type safety on the return type.
+  return (async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
     const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);
 
     const cacheStart = performance.now();
     const cached = await handler.get(key);
 
     if (cached && !cached.stale) {
-      // Record as OTEL span event on enclosing span (not a child span)
-      await addSpanEvent('timber.cache.hit', {
+      // Record as OTEL span event on enclosing span (not a child span).
+      // Fire-and-forget — no microtask overhead on the cache hot path.
+      addSpanEventSync('timber.cache.hit', {
         key,
         duration_ms: Math.round(performance.now() - cacheStart),
       });
@@ -66,43 +79,41 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
     }
 
     if (cached && cached.stale && opts.staleWhileRevalidate) {
-      // Record stale cache hit as OTEL span event
-      await addSpanEvent('timber.cache.hit', {
+      // Record stale cache hit as OTEL span event (fire-and-forget).
+      addSpanEventSync('timber.cache.hit', {
         key,
         duration_ms: Math.round(performance.now() - cacheStart),
         stale: true,
       });
       // Serve stale immediately, trigger background refetch
-      singleflight
-        .do(`swr:${key}`, async () => {
-          try {
-            const fresh = await fn(...args);
-            const tags = resolveTags(opts, args);
-            await handler.set(key, fresh, { ttl: opts.ttl, tags });
-          } catch {
-            // Failed refetch — stale entry continues to be served.
-            // Error is swallowed per design doc: "Error is logged."
-          }
-        })
-        .catch(() => {
-          // Singleflight promise rejection handled — stale continues.
-        });
+      sf.do(`swr:${key}`, async () => {
+        try {
+          const fresh = await fn(...args);
+          const tags = resolveTags(opts, args);
+          await handler.set(key, fresh, { ttl: opts.ttl, tags });
+        } catch {
+          // Failed refetch — stale entry continues to be served.
+          // Error is swallowed per design doc: "Error is logged."
+        }
+      }).catch(() => {
+        // Singleflight promise rejection handled — stale continues.
+      });
       return cached.value as Awaited<ReturnType<Fn>>;
     }
 
     // Cache miss (or stale without SWR) — execute with singleflight
-    const result = await singleflight.do(key, () => fn(...args));
+    const result = await sf.do(key, () => fn(...args));
     const tags = resolveTags(opts, args);
     await handler.set(key, result, { ttl: opts.ttl, tags });
 
-    // Record cache miss as OTEL span event
-    await addSpanEvent('timber.cache.miss', {
+    // Record cache miss as OTEL span event (fire-and-forget).
+    addSpanEventSync('timber.cache.miss', {
       key,
       duration_ms: Math.round(performance.now() - cacheStart),
     });
 
     return result as Awaited<ReturnType<Fn>>;
-  };
+  }) as unknown as Fn;
 }
 
 /**