@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

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/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;
+  }
+}

package/src/cache/timber-cache.ts

@@ -1,10 +1,11 @@
 import type { CacheHandler, CacheOptions } from './index';
 import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
-import { addSpanEventSync } from '#/server/tracing.js';
+import { addSpanEventSync } from '../server/tracing.js';
+import { logSwrRefetchFailed } from '../server/logger.js';
 import { fnv1aHash } from './fast-hash.js';
 
-const singleflight = createSingleflight();
+const defaultSingleflight = createSingleflight();
 
 /**
  * Generate a cache key from function identity and serialized args.
@@ -33,8 +34,8 @@ function resolveTags<Fn extends (...args: any[]) => any>(
   return opts.tags(...args);
 }
 
-// Counter for generating unique function IDs when no explicit key is provided.
-let fnIdCounter = 0;
+let unstableIdCounter = 0;
+let hasWarnedUnstableId = false;
 
 /**
  * Creates a cached wrapper around an async function.
@@ -52,11 +53,40 @@ let fnIdCounter = 0;
 export function createCache<Fn extends (...args: any[]) => Promise<any>>(
   fn: Fn,
   opts: CacheOptions<Fn>,
-  handler: CacheHandler
-): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {
-  const fnId = `timber-cache:${fnIdCounter++}`;
+  handler: CacheHandler,
+  stableId?: string
+): Fn {
+  let fnId: string;
+  if (stableId) {
+    fnId = stableId;
+  } else if (opts.key) {
+    // Explicit key function — fnId is only used for singleflight, not for
+    // cache keys, so a counter is acceptable here.
+    fnId = `timber-cache:${unstableIdCounter++}`;
+  } else {
+    fnId = `timber-cache:unstable:${unstableIdCounter++}`;
+    if (
+      !hasWarnedUnstableId &&
+      typeof process !== 'undefined' &&
+      process.env?.NODE_ENV !== 'test'
+    ) {
+      hasWarnedUnstableId = true;
+      console.warn(
+        '[timber] cache() called without a stable ID or explicit key function. ' +
+          'Cache keys will use a process-local counter which is unstable across ' +
+          'cold starts. Run through the timber Vite plugin or provide an explicit ' +
+          '`key` option to fix this.'
+      );
+    }
+  }
+  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();
@@ -80,25 +110,23 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
         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 (err) {
+          // Failed refetch — stale entry continues to be served.
+          logSwrRefetchFailed({ cacheKey: key, error: err });
+        }
+      }).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 });
 
@@ -109,7 +137,7 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
     });
 
     return result as Awaited<ReturnType<Fn>>;
-  };
+  }) as unknown as Fn;
 }
 
 /**

package/src/cli-schema-sync.ts

@@ -0,0 +1,295 @@
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, append
+ * missing entries with `codec.string` defaults, and remove stale entries
+ * whose segments no longer exist in the filesystem.
+ *
+ * Design doc: design/41-global-params.md §Auto-Scaffolding
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { scanRoutes } from './routing/scanner.js';
+import type { SegmentNode } from './routing/types.js';
+import { resolveAppDir } from './plugin-context.js';
+
+/**
+ * Collect all unique bracket-keyed dynamic segment names from the route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export function collectDynamicSegments(appDir: string): string[] {
+  const tree = scanRoutes(appDir);
+  const segments = new Set<string>();
+  walkSegments(tree.root, segments);
+  return [...segments].sort();
+}
+
+function walkSegments(node: SegmentNode, segments: Set<string>): void {
+  if (node.paramName) {
+    // Reconstruct bracket key from segmentName (already has brackets)
+    segments.add(node.segmentName);
+  }
+  for (const child of node.children) {
+    walkSegments(child, segments);
+  }
+  for (const slot of Object.values(node.slots)) {
+    walkSegments(slot, segments);
+  }
+}
+
+/**
+ * Parse existing bracket keys from an app/schema.ts file.
+ * Uses regex to find keys in segmentParams: { '[key]': ... } blocks.
+ */
+export function parseExistingSchemaKeys(content: string): string[] {
+  const keys: string[] = [];
+  // Match quoted bracket keys like '[artistSlug]', '[...slug]', '[[...topic]]'
+  const re = /['"](\[{1,2}(?:\.{3})?\w+\]{1,2})['"]\s*:/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(content)) !== null) {
+    keys.push(m[1]);
+  }
+  return keys;
+}
+
+/** Schema file extensions to check. */
+const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+/**
+ * Find the schema file path if it exists.
+ */
+export function findSchemaFile(appDir: string): string | undefined {
+  for (const ext of SCHEMA_EXTENSIONS) {
+    const p = join(appDir, `schema${ext}`);
+    if (existsSync(p)) return p;
+  }
+  return undefined;
+}
+
+export function defaultCodecForSegment(seg: string): string {
+  if (seg.startsWith('[[...')) return 'codec.optionalCatchAll(codec.string)';
+  if (seg.startsWith('[...')) return 'codec.stringArray';
+  return 'codec.string';
+}
+
+/**
+ * Generate the content for a new app/schema.ts with the given segment keys.
+ */
+function generateNewSchema(segments: string[]): string {
+  const lines: string[] = [];
+  lines.push("import { defineSchema } from '@timber-js/app/params';");
+  lines.push("import { codec } from '@timber-js/app/codec';");
+  lines.push('');
+  lines.push('export default defineSchema({');
+  lines.push('  segmentParams: {');
+  for (const seg of segments) {
+    lines.push(`    '${seg}': ${defaultCodecForSegment(seg)},`);
+  }
+  lines.push('  },');
+  lines.push('});');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Append missing segment entries to an existing schema file.
+ * Inserts new entries before the closing `}` of segmentParams.
+ */
+const CODEC_IMPORT = "import { codec } from '@timber-js/app/codec';";
+
+function hasCodecImport(content: string): boolean {
+  return /import\s+\{[^}]*\bcodec\b[^}]*\}\s+from\s+['"]@timber-js\/app\/codec['"]/.test(content);
+}
+
+function ensureCodecImport(content: string): string {
+  if (hasCodecImport(content)) return content;
+
+  // Insert after the last existing import statement
+  const lines = content.split('\n');
+  let lastImportIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*import\s/.test(lines[i])) lastImportIndex = i;
+  }
+
+  if (lastImportIndex === -1) {
+    return CODEC_IMPORT + '\n' + content;
+  }
+
+  lines.splice(lastImportIndex + 1, 0, CODEC_IMPORT);
+  return lines.join('\n');
+}
+
+function appendToSchema(content: string, newSegments: string[]): string {
+  content = ensureCodecImport(content);
+
+  // Find "segmentParams" key position
+  const spIndex = content.indexOf('segmentParams');
+  if (spIndex === -1) {
+    throw new Error(
+      '[timber] Could not find segmentParams in schema file. ' +
+        'Expected a defineSchema({ segmentParams: { ... } }) call.'
+    );
+  }
+
+  // Find the opening brace after segmentParams
+  const openBrace = content.indexOf('{', spIndex + 'segmentParams'.length);
+  if (openBrace === -1) {
+    throw new Error('[timber] Could not find opening brace for segmentParams.');
+  }
+
+  // Count braces to find the matching close
+  let depth = 1;
+  let i = openBrace + 1;
+  while (i < content.length && depth > 0) {
+    if (content[i] === '{') depth++;
+    else if (content[i] === '}') depth--;
+    i++;
+  }
+  // i now points to just after the closing brace
+  const closeBrace = i - 1;
+
+  // Detect indentation from existing entries
+  const existingLine = content.slice(openBrace, closeBrace).match(/^(\s+)['"]\[/m);
+  const indent = existingLine ? existingLine[1] : '    ';
+
+  // Build insertion text
+  const insertion = newSegments
+    .map((seg) => `${indent}'${seg}': ${defaultCodecForSegment(seg)},`)
+    .join('\n');
+
+  // Insert before the closing brace
+  const before = content.slice(0, closeBrace);
+  const after = content.slice(closeBrace);
+
+  // Add newline if the content before doesn't end with one
+  const separator = before.trimEnd().endsWith(',') ? '\n' : '\n';
+
+  return before + separator + insertion + '\n' + after;
+}
+
+/**
+ * Remove entries from the segmentParams block whose keys match `staleSegments`.
+ * Removes the entire line including trailing comma/whitespace.
+ */
+function removeFromSchema(content: string, staleSegments: string[]): string {
+  for (const seg of staleSegments) {
+    const escaped = seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const keyRe = new RegExp(`^[ \t]*['"]${escaped}['"][ \t]*:`, 'gm');
+    let m: RegExpExecArray | null;
+    while ((m = keyRe.exec(content)) !== null) {
+      const start = m.index;
+      let i = m.index + m[0].length;
+      let depth = 0;
+      let inString: string | null = null;
+
+      while (i < content.length) {
+        const ch = content[i];
+        if (inString) {
+          if (ch === '\\') {
+            i++;
+          } else if (ch === inString) {
+            inString = null;
+          }
+        } else if (ch === '"' || ch === "'" || ch === '`') {
+          inString = ch;
+        } else if (ch === '(' || ch === '{' || ch === '[') {
+          depth++;
+        } else if (ch === ')' || ch === '}' || ch === ']') {
+          depth--;
+        } else if (depth === 0 && ch === ',') {
+          i++;
+          break;
+        } else if (depth === 0 && (ch === '\n' || ch === '}')) {
+          break;
+        }
+        i++;
+      }
+
+      // Consume trailing newline
+      if (i < content.length && content[i] === '\n') i++;
+
+      content = content.slice(0, start) + content.slice(i);
+      keyRe.lastIndex = start;
+    }
+  }
+  return content;
+}
+
+export interface SchemaSyncResult {
+  /** Segments found in the filesystem. */
+  filesystemSegments: string[];
+  /** Segments already defined in app/schema.ts. */
+  existingSegments: string[];
+  /** Segments that were added. */
+  addedSegments: string[];
+  /** Segments that were removed (no longer in filesystem). */
+  removedSegments: string[];
+  /** Whether a new schema file was created. */
+  created: boolean;
+}
+
+/**
+ * Run the schema sync: scan filesystem, diff against schema, append missing.
+ */
+export function runSchemaSync(projectRoot: string): SchemaSyncResult {
+  const appDir = resolveAppDir(projectRoot);
+
+  const filesystemSegments = collectDynamicSegments(appDir);
+
+  const schemaPath = findSchemaFile(appDir);
+
+  if (filesystemSegments.length === 0 && !schemaPath) {
+    return {
+      filesystemSegments: [],
+      existingSegments: [],
+      addedSegments: [],
+      removedSegments: [],
+      created: false,
+    };
+  }
+
+  if (!schemaPath) {
+    // Create new schema file
+    const newPath = join(appDir, 'schema.ts');
+    writeFileSync(newPath, generateNewSchema(filesystemSegments), 'utf-8');
+    return {
+      filesystemSegments,
+      existingSegments: [],
+      addedSegments: filesystemSegments,
+      removedSegments: [],
+      created: true,
+    };
+  }
+
+  // Read existing schema and diff
+  const content = readFileSync(schemaPath, 'utf-8');
+  const existingSegments = parseExistingSchemaKeys(content);
+  const missing = filesystemSegments.filter((seg) => !existingSegments.includes(seg));
+  const stale = existingSegments.filter((seg) => !filesystemSegments.includes(seg));
+
+  if (missing.length === 0 && stale.length === 0) {
+    return {
+      filesystemSegments,
+      existingSegments,
+      addedSegments: [],
+      removedSegments: [],
+      created: false,
+    };
+  }
+
+  let updated = content;
+  if (stale.length > 0) {
+    updated = removeFromSchema(updated, stale);
+  }
+  if (missing.length > 0) {
+    updated = appendToSchema(updated, missing);
+  }
+  writeFileSync(schemaPath, updated, 'utf-8');
+
+  return {
+    filesystemSegments,
+    existingSegments,
+    addedSegments: missing,
+    removedSegments: stale,
+    created: false,
+  };
+}

package/src/cli.ts

@@ -11,7 +11,7 @@
 //   timber preview  — Serve the production build
 //   timber check    — Validate types + routes without building
 
-const COMMANDS = ['dev', 'build', 'preview', 'check'] as const;
+const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema'] as const;
 type Command = (typeof COMMANDS)[number];
 
 export interface ParsedArgs {
@@ -30,7 +30,7 @@ export interface CommandOptions {
 export function parseArgs(args: string[]): ParsedArgs {
   if (args.length === 0) {
     throw new Error(
-      'No command provided. Usage: timber <dev|build|preview|check> [--config <path>]'
+      'No command provided. Usage: timber <dev|build|preview|check|schema> [--config <path>]'
     );
   }
 
@@ -63,7 +63,12 @@ export interface ViteDeps {
 
 /**
  * Start the Vite dev server.
- * Middleware re-runs on file change via HMR wiring in timber-routing.
+ *
+ * The timber plugin binds the port immediately with a holding page
+ * (in rootSync's config hook) so browsers see a "starting..." page
+ * instead of ERR_CONNECTION_REFUSED during initialization.
+ *
+ * See design/21-dev-server.md, TIM-665.
  */
 export async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
   const createServer = _deps?.createServer ?? (await import('vite')).createServer;
@@ -105,9 +110,11 @@ export function resolvePreviewStrategy(
  * Returns the config object with adapter, output, etc.
  * Returns null if no config file is found.
  */
-async function loadTimberConfig(
-  root: string
-): Promise<{ adapter?: import('./adapters/types').TimberPlatformAdapter; output?: string } | null> {
+async function loadTimberConfig(root: string): Promise<{
+  adapter?: import('./adapters/types').TimberPlatformAdapter;
+  output?: string;
+  buildDir?: string;
+} | null> {
   const { existsSync } = await import('node:fs');
   const { join } = await import('node:path');
   const { pathToFileURL } = await import('node:url');
@@ -131,7 +138,7 @@ async function loadTimberConfig(
  * Otherwise falls back to Vite's built-in preview server.
  */
 export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
-  const { join } = await import('node:path');
+  const { join, resolve } = await import('node:path');
 
   // Try to load timber config for adapter-specific preview
   const root = process.cwd();
@@ -139,7 +146,10 @@ export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Pro
   const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;
 
   if (resolvePreviewStrategy(adapter) === 'adapter') {
-    const buildDir = join(root, 'dist');
+    // Resolve build directory: timber config > default .timber/dist
+    const buildDir = config?.buildDir
+      ? resolve(root, config.buildDir)
+      : join(root, '.timber', 'dist');
     const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };
     await adapter!.preview!(timberConfig, buildDir);
     return;
@@ -174,6 +184,61 @@ export async function runCheck(options: CommandOptions): Promise<void> {
   });
 }
 
+// ─── Schema Subcommand ───────────────────────────────────────────────────────
+
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, diff against
+ * app/schema.ts, and append missing entries with type-appropriate codec defaults.
+ *
+ * See design/41-global-params.md §Auto-Scaffolding
+ */
+export async function runSchema(args: string[]): Promise<void> {
+  const subcommand = args[0];
+
+  if (subcommand !== 'sync') {
+    throw new Error(
+      `Unknown schema subcommand: ${subcommand ?? '(none)'}. Usage: timber schema sync`
+    );
+  }
+
+  const { runSchemaSync, defaultCodecForSegment } = await import('./cli-schema-sync.js');
+  const result = runSchemaSync(process.cwd());
+
+  if (result.filesystemSegments.length === 0) {
+    console.log('[timber] No dynamic segments found in app/.');
+    return;
+  }
+
+  if (result.created) {
+    console.log(`[timber] Created app/schema.ts with ${result.addedSegments.length} segment(s):`);
+    for (const seg of result.addedSegments) {
+      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);
+    }
+    return;
+  }
+
+  if (result.addedSegments.length === 0 && result.removedSegments.length === 0) {
+    console.log('[timber] Schema is up to date — all segments are registered.');
+    return;
+  }
+
+  if (result.addedSegments.length > 0) {
+    console.log(`[timber] Added ${result.addedSegments.length} segment(s) to app/schema.ts:`);
+    for (const seg of result.addedSegments) {
+      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);
+    }
+  }
+
+  if (result.removedSegments.length > 0) {
+    console.log(
+      `[timber] Removed ${result.removedSegments.length} stale segment(s) from app/schema.ts:`
+    );
+    for (const seg of result.removedSegments) {
+      console.log(`  - ${seg}`);
+    }
+  }
+}
+
 // ─── Main Entry Point ────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
@@ -193,6 +258,9 @@ async function main(): Promise<void> {
     case 'check':
       await runCheck(options);
       break;
+    case 'schema':
+      await runSchema(process.argv.slice(3));
+      break;
   }
 }