@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/src/adapters/nitro.ts

@@ -149,6 +149,23 @@ export interface NitroAdapterOptions {
    */
   preset?: NitroPreset;
 
+  /**
+   * Enable application-level gzip compression for HTML and RSC responses.
+   *
+   * When `true` (default), the origin compresses responses using the Web
+   * `CompressionStream` API. This is useful for self-hosted deployments
+   * where no reverse proxy or CDN handles compression.
+   *
+   * Set to `false` when deploying behind a reverse proxy (nginx, caddy)
+   * or CDN (Cloudflare, Fastly, Vercel) that compresses at the edge.
+   * Disabling origin compression saves CPU on the Node.js event loop —
+   * compressing 1MB+ streaming HTML responses takes 10-15ms of main
+   * thread time per request, directly reducing throughput under load.
+   *
+   * @default true
+   */
+  compress?: boolean;
+
   /**
    * Additional Nitro configuration to merge into the generated config.
    * Overrides default values for the selected preset.
@@ -176,6 +193,7 @@ export interface NitroAdapterOptions {
  */
 export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter {
   const preset = options.preset ?? 'node-server';
+  const compress = options.compress ?? true;
   const presetConfig = PRESET_CONFIGS[preset];
   const pendingPromises: Promise<unknown>[] = [];
 
@@ -229,7 +247,7 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       }
 
       // Generate the Nitro entry point (imports from ./rsc/ within nitro dir)
-      const entry = generateNitroEntry(buildDir, outDir, preset);
+      const entry = generateNitroEntry(buildDir, outDir, preset, compress);
       await writeFile(join(outDir, 'entry.ts'), entry);
 
       // Run the Nitro build to produce a production-ready server bundle.
@@ -273,6 +291,7 @@ export function generateNitroEntry(
   buildDir: string,
   outDir: string,
   preset: NitroPreset,
+  compress = true,
   hasManifestInit = false
 ): string {
   // The RSC entry is the main request handler — it exports the fetch handler as default.
@@ -338,12 +357,14 @@ export function generateNitroEntry(
   // Import runWithWaitUntil only when the preset supports it.
   const waitUntilImport = supportsWaitUntil ? ', runWithWaitUntil' : '';
 
+  const compressImport = compress ? "import { compressResponse } from './_compress.mjs'\n" : '';
+  const compressCall = compress ? 'compressResponse(webRequest, webResponse)' : 'webResponse';
+
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
 ${manifestImport}import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
-import { compressResponse } from './_compress.mjs'
-
+${compressImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
 process.env.TIMBER_RUNTIME = '${runtimeName}'
@@ -357,7 +378,7 @@ export default async function timberHandler(event) {
   // h3 v2: event.req is the Web Request
   const webRequest = event.req
 ${handlerCall}
-  return compressResponse(webRequest, webResponse)
+  return ${compressCall}
 }
 `;
 }
@@ -544,14 +565,37 @@ const server = createServer(async (req, res) => {
 
     if (webResponse.body) {
       const reader = webResponse.body.getReader();
-      const pump = async () => {
+
+      // Cancel the reader when the client disconnects. This causes any
+      // pending reader.read() to reject, breaking the pump loop. Critical
+      // for SSE and other infinite streams — without this, disconnected
+      // clients leak readers.
+      let clientDisconnected = false;
+      const onClose = () => {
+        clientDisconnected = true;
+        reader.cancel('Client disconnected').catch(() => {});
+      };
+      res.on('close', onClose);
+
+      try {
         while (true) {
           const { done, value } = await reader.read();
-          if (done) { res.end(); return; }
+          if (done) break;
           res.write(value);
         }
-      };
-      await pump();
+      } catch (err) {
+        // reader.cancel() from the close handler causes read() to reject.
+        // This is expected on client disconnect — not an error.
+        if (!clientDisconnected) {
+          throw err;
+        }
+      } finally {
+        res.off('close', onClose);
+        reader.releaseLock();
+        if (!res.writableEnded) {
+          res.end();
+        }
+      }
     } else {
       res.end();
     }
@@ -611,7 +655,12 @@ async function runNitroBuild(
   userConfig?: Record<string, unknown>
 ): Promise<void> {
   const presetConfig = PRESET_CONFIGS[preset];
-  const { createNitro, build: nitroBuild, prepare, copyPublicAssets } = await import('nitro/builder');
+  const {
+    createNitro,
+    build: nitroBuild,
+    prepare,
+    copyPublicAssets,
+  } = await import('nitro/builder');
 
   const nitro = await createNitro({
     rootDir: nitroDir,

package/src/adapters/wrangler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type stub for the optional `wrangler` peer dependency.
+ * Prevents TS2307 during declaration emit when wrangler is not installed.
+ */
+declare module 'wrangler' {
+  export function getPlatformProxy(opts?: any): Promise<any>;
+}

package/src/cache/cache-api.ts

@@ -0,0 +1,38 @@
+import type { CacheOptions } from './index';
+import { createCache } from './timber-cache';
+import { getCacheHandler } from './handler-store';
+
+/**
+ * Public caching API: `cache(fn, opts)`.
+ *
+ * Wraps an async function with cross-request caching. Uses the configured
+ * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).
+ *
+ * ```ts
+ * import { cache } from '@timber-js/app/cache';
+ *
+ * const getUser = cache(
+ *   async (id: string) => db.users.findUnique({ where: { id } }),
+ *   { ttl: 60, tags: (id) => [`user:${id}`] }
+ * );
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function cache<Fn extends (...args: any[]) => Promise<any>>(
+  fn: Fn,
+  opts: CacheOptions<Fn>
+): Fn {
+  return createCache(fn, opts, getCacheHandler());
+}
+
+/**
+ * Invalidate cache entries by tag or key.
+ *
+ * ```ts
+ * cache.invalidate({ tag: 'products' });
+ * cache.invalidate({ key: 'user:abc' });
+ * ```
+ */
+cache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+  await getCacheHandler().invalidate(opts);
+};

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/handler-store.ts

@@ -0,0 +1,68 @@
+/**
+ * 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;
+
+/** Replace the active cache handler. Called by the framework at boot. */
+export function setCacheHandler(h: CacheHandlerLike): void {
+  handler = h;
+}
+
+/**
+ * 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 maxSize = 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 >= maxSize) {
+        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

@@ -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 {
@@ -83,9 +86,10 @@ export class MemoryCacheHandler implements CacheHandler {
 
 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 { cache } from './cache-api';
+export { setCacheHandler, getCacheHandler } from './handler-store';
+// NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.
+// Future feature pending design doc. See design/06-caching.md.
 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/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;
 }
 
 /**