@timber-js/app 0.1.0 → 0.1.2

package/src/server/error-formatter.ts

@@ -0,0 +1,184 @@
+/**
+ * Error Formatter — rewrites SSR/RSC error messages to surface user code.
+ *
+ * When React or Vite throw errors during SSR, stack traces reference
+ * vendored dependency paths (e.g. `.vite/deps_ssr/@vitejs_plugin-rsc_vendor_...`)
+ * and mangled export names (`__vite_ssr_export_default__`). This module
+ * rewrites error messages and stack traces to point at user code instead.
+ *
+ * Dev-only — in production, errors go through the structured logger
+ * without formatting.
+ */
+
+// ─── Stack Trace Rewriting ──────────────────────────────────────────────────
+
+/**
+ * Patterns that identify internal Vite/RSC vendor paths in stack traces.
+ * These are replaced with human-readable labels.
+ */
+const VENDOR_PATH_PATTERNS: Array<{ pattern: RegExp; replacement: string }> = [
+  {
+    pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor_react-server-dom[^\s)]+/g,
+    replacement: '<react-server-dom>',
+  },
+  {
+    pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor[^\s)]+/g,
+    replacement: '<rsc-vendor>',
+  },
+  {
+    pattern: /node_modules\/\.vite\/deps_ssr\/[^\s)]+/g,
+    replacement: '<vite-dep>',
+  },
+  {
+    pattern: /node_modules\/\.vite\/deps\/[^\s)]+/g,
+    replacement: '<vite-dep>',
+  },
+];
+
+/**
+ * Patterns that identify Vite-mangled export names in error messages.
+ */
+const MANGLED_NAME_PATTERNS: Array<{ pattern: RegExp; replacement: string }> = [
+  {
+    pattern: /__vite_ssr_export_default__/g,
+    replacement: '<default export>',
+  },
+  {
+    pattern: /__vite_ssr_export_(\w+)__/g,
+    replacement: '<export $1>',
+  },
+];
+
+/**
+ * Rewrite an error's message and stack to replace internal Vite paths
+ * and mangled names with human-readable labels.
+ */
+export function formatSsrError(error: unknown): string {
+  if (!(error instanceof Error)) {
+    return String(error);
+  }
+
+  let message = error.message;
+  let stack = error.stack ?? '';
+
+  // Rewrite mangled names in the message
+  for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) {
+    message = message.replace(pattern, replacement);
+  }
+
+  // Rewrite vendor paths in the stack
+  for (const { pattern, replacement } of VENDOR_PATH_PATTERNS) {
+    stack = stack.replace(pattern, replacement);
+  }
+
+  // Rewrite mangled names in the stack too
+  for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) {
+    stack = stack.replace(pattern, replacement);
+  }
+
+  // Extract hints from React-specific error patterns
+  const hint = extractErrorHint(error.message);
+
+  // Build formatted output: cleaned message, hint (if any), then cleaned stack
+  const parts: string[] = [];
+  parts.push(message);
+  if (hint) {
+    parts.push(`  → ${hint}`);
+  }
+
+  // Include only the user-code frames from the stack (skip the first line
+  // which is the message itself, and filter out vendor-only frames)
+  const userFrames = extractUserFrames(stack);
+  if (userFrames.length > 0) {
+    parts.push('');
+    parts.push('  User code in stack:');
+    for (const frame of userFrames) {
+      parts.push(`    ${frame}`);
+    }
+  }
+
+  return parts.join('\n');
+}
+
+// ─── Error Hint Extraction ──────────────────────────────────────────────────
+
+/**
+ * Extract a human-readable hint from common React/RSC error messages.
+ *
+ * React error messages contain useful information but the surrounding
+ * context (vendor paths, mangled names) obscures it. This extracts the
+ * actionable part as a one-line hint.
+ */
+function extractErrorHint(message: string): string | null {
+  // "Functions cannot be passed directly to Client Components"
+  // Extract the component and prop name from the JSX-like syntax in the message
+  const fnPassedMatch = message.match(/Functions cannot be passed directly to Client Components/);
+  if (fnPassedMatch) {
+    // Try to extract the prop name from the message
+    // React formats: <... propName={function ...} ...>
+    const propMatch = message.match(/<[^>]*?\s(\w+)=\{function/);
+    if (propMatch) {
+      return `Prop "${propMatch[1]}" is a function — mark it "use server" or call it before passing`;
+    }
+    return 'A function prop was passed to a Client Component — mark it "use server" or call it before passing';
+  }
+
+  // "Objects are not valid as a React child"
+  if (message.includes('Objects are not valid as a React child')) {
+    return 'An object was rendered as JSX children — convert to string or extract the value';
+  }
+
+  // "Cannot read properties of undefined/null"
+  const nullRefMatch = message.match(
+    /Cannot read propert(?:y|ies) of (undefined|null) \(reading '(\w+)'\)/
+  );
+  if (nullRefMatch) {
+    return `Accessed .${nullRefMatch[2]} on ${nullRefMatch[1]} — check that the value exists`;
+  }
+
+  // "X is not a function"
+  const notFnMatch = message.match(/(\w+) is not a function/);
+  if (notFnMatch) {
+    return `"${notFnMatch[1]}" is not a function — check imports and exports`;
+  }
+
+  // "Element type is invalid"
+  if (message.includes('Element type is invalid')) {
+    return 'A component resolved to undefined/null — check default exports and import paths';
+  }
+
+  return null;
+}
+
+// ─── Stack Frame Filtering ──────────────────────────────────────────────────
+
+/**
+ * Extract stack frames that reference user code (not node_modules,
+ * not framework internals).
+ *
+ * Returns at most 5 frames to keep output concise.
+ */
+function extractUserFrames(stack: string): string[] {
+  const lines = stack.split('\n');
+  const userFrames: string[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Skip non-frame lines
+    if (!trimmed.startsWith('at ')) continue;
+    // Skip node_modules, vendor, and internal frames
+    if (
+      trimmed.includes('node_modules') ||
+      trimmed.includes('<react-server-dom>') ||
+      trimmed.includes('<rsc-vendor>') ||
+      trimmed.includes('<vite-dep>') ||
+      trimmed.includes('node:internal')
+    ) {
+      continue;
+    }
+    userFrames.push(trimmed);
+    if (userFrames.length >= 5) break;
+  }
+
+  return userFrames;
+}

package/src/server/flush.ts

@@ -0,0 +1,182 @@
+/**
+ * Flush controller for timber.js rendering.
+ *
+ * Holds the response until `onShellReady` fires, then commits the HTTP status
+ * code and flushes the shell. Render-phase signals (deny, redirect, unhandled
+ * throws) caught before flush produce correct HTTP status codes.
+ *
+ * See design/02-rendering-pipeline.md §"The Flush Point" and §"The Hold Window"
+ */
+
+import { DenySignal, RedirectSignal, RenderError } from './primitives.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/** The readable stream from React's renderToReadableStream. */
+export interface ReactRenderStream {
+  /** The underlying ReadableStream of HTML bytes. */
+  readable: ReadableStream<Uint8Array>;
+  /** Resolves when the shell has finished rendering (all non-Suspense content). */
+  allReady?: Promise<void>;
+}
+
+/** Options for the flush controller. */
+export interface FlushOptions {
+  /** Response headers to include (from middleware.ts, proxy.ts, etc.). */
+  responseHeaders?: Headers;
+  /** Default status code when rendering succeeds. Default: 200. */
+  defaultStatus?: number;
+}
+
+/** Result of the flush process. */
+export interface FlushResult {
+  /** The final HTTP Response. */
+  response: Response;
+  /** The status code committed. */
+  status: number;
+  /** Whether the response was a redirect. */
+  isRedirect: boolean;
+  /** Whether the response was a denial. */
+  isDenial: boolean;
+}
+
+// ─── Render Function Type ────────────────────────────────────────────────────
+
+/**
+ * A function that performs the React render.
+ *
+ * The flush controller calls this, catches any signals thrown during the
+ * synchronous shell render (before onShellReady), and produces the
+ * correct HTTP response.
+ *
+ * Must return an object with:
+ * - `stream`: The ReadableStream from renderToReadableStream
+ * - `shellReady`: A Promise that resolves when onShellReady fires
+ */
+export interface RenderResult {
+  /** The HTML byte stream. */
+  stream: ReadableStream<Uint8Array>;
+  /** Resolves when the shell is ready (all non-Suspense content rendered). */
+  shellReady: Promise<void>;
+}
+
+export type RenderFn = () => RenderResult | Promise<RenderResult>;
+
+// ─── Flush Controller ────────────────────────────────────────────────────────
+
+/**
+ * Execute a render and hold the response until the shell is ready.
+ *
+ * The flush controller:
+ * 1. Calls the render function to start renderToReadableStream
+ * 2. Waits for shellReady (onShellReady)
+ * 3. If a render-phase signal was thrown (deny, redirect, error), produces
+ *    the correct HTTP status code
+ * 4. If the shell rendered successfully, commits the status and streams
+ *
+ * Render-phase signals caught before flush:
+ * - `DenySignal` → HTTP 4xx with appropriate status code
+ * - `RedirectSignal` → HTTP 3xx with Location header
+ * - `RenderError` → HTTP status from error (default 500)
+ * - Unhandled error → HTTP 500
+ *
+ * @param renderFn - Function that starts the React render.
+ * @param options - Flush configuration.
+ * @returns The committed HTTP Response.
+ */
+export async function flushResponse(
+  renderFn: RenderFn,
+  options: FlushOptions = {}
+): Promise<FlushResult> {
+  const { responseHeaders = new Headers(), defaultStatus = 200 } = options;
+
+  let renderResult: RenderResult;
+
+  // Phase 1: Start the render. The render function may throw synchronously
+  // if there's an immediate error before React even starts.
+  try {
+    renderResult = await renderFn();
+  } catch (error) {
+    return handleSignal(error, responseHeaders);
+  }
+
+  // Phase 2: Wait for onShellReady. Render-phase signals (deny, redirect,
+  // throws outside Suspense) are caught here.
+  try {
+    await renderResult.shellReady;
+  } catch (error) {
+    return handleSignal(error, responseHeaders);
+  }
+
+  // Phase 3: Shell rendered successfully. Commit status and stream.
+  responseHeaders.set('Content-Type', 'text/html; charset=utf-8');
+
+  return {
+    response: new Response(renderResult.stream, {
+      status: defaultStatus,
+      headers: responseHeaders,
+    }),
+    status: defaultStatus,
+    isRedirect: false,
+    isDenial: false,
+  };
+}
+
+// ─── Signal Handling ─────────────────────────────────────────────────────────
+
+/**
+ * Handle a render-phase signal and produce the correct HTTP response.
+ */
+function handleSignal(error: unknown, responseHeaders: Headers): FlushResult {
+  // Redirect signal → HTTP 3xx
+  if (error instanceof RedirectSignal) {
+    responseHeaders.set('Location', error.location);
+    return {
+      response: new Response(null, {
+        status: error.status,
+        headers: responseHeaders,
+      }),
+      status: error.status,
+      isRedirect: true,
+      isDenial: false,
+    };
+  }
+
+  // Deny signal → HTTP 4xx
+  if (error instanceof DenySignal) {
+    return {
+      response: new Response(null, {
+        status: error.status,
+        headers: responseHeaders,
+      }),
+      status: error.status,
+      isRedirect: false,
+      isDenial: true,
+    };
+  }
+
+  // RenderError → HTTP status from error
+  if (error instanceof RenderError) {
+    return {
+      response: new Response(null, {
+        status: error.status,
+        headers: responseHeaders,
+      }),
+      status: error.status,
+      isRedirect: false,
+      isDenial: false,
+    };
+  }
+
+  // Unknown error → HTTP 500
+  console.error('[timber] Unhandled render-phase error:', error);
+  return {
+    response: new Response(null, {
+      status: 500,
+      headers: responseHeaders,
+    }),
+    status: 500,
+    isRedirect: false,
+    isDenial: false,
+  };
+}

package/src/server/form-data.ts

@@ -0,0 +1,176 @@
+/**
+ * FormData preprocessing — schema-agnostic conversion of FormData to typed objects.
+ *
+ * FormData is all strings. Schema validation expects typed values. This module
+ * bridges the gap with intelligent coercion that runs *before* schema validation.
+ *
+ * Inspired by zod-form-data, but schema-agnostic — works with any Standard Schema
+ * library (Zod, Valibot, ArkType).
+ *
+ * See design/08-forms-and-actions.md §"parseFormData() and coerce helpers"
+ */
+
+// ─── parseFormData ───────────────────────────────────────────────────────
+
+/**
+ * Convert FormData into a plain object with intelligent coercion.
+ *
+ * Handles:
+ * - **Duplicate keys → arrays**: `tags=js&tags=ts` → `{ tags: ["js", "ts"] }`
+ * - **Nested dot-paths**: `user.name=Alice` → `{ user: { name: "Alice" } }`
+ * - **Empty strings → undefined**: Enables `.optional()` semantics in schemas
+ * - **Empty Files → undefined**: File inputs with no selection become `undefined`
+ * - **Strips `$ACTION_*` fields**: React's internal hidden fields are excluded
+ */
+export function parseFormData(formData: FormData): Record<string, unknown> {
+  const flat: Record<string, unknown> = {};
+
+  for (const key of new Set(formData.keys())) {
+    // Skip React internal fields
+    if (key.startsWith('$ACTION_')) continue;
+
+    const values = formData.getAll(key);
+    const processed = values.map(normalizeValue);
+
+    if (processed.length === 1) {
+      flat[key] = processed[0];
+    } else {
+      // Filter out undefined entries from multi-value fields
+      flat[key] = processed.filter((v) => v !== undefined);
+    }
+  }
+
+  // Expand dot-notation paths into nested objects
+  return expandDotPaths(flat);
+}
+
+/**
+ * Normalize a single FormData entry value.
+ * - Empty strings → undefined (enables .optional() semantics)
+ * - Empty File objects (no selection) → undefined
+ * - Everything else passes through as-is
+ */
+function normalizeValue(value: FormDataEntryValue): unknown {
+  if (typeof value === 'string') {
+    return value === '' ? undefined : value;
+  }
+
+  // File input with no selection: browsers submit a File with name="" and size=0
+  if (value instanceof File && value.size === 0 && value.name === '') {
+    return undefined;
+  }
+
+  return value;
+}
+
+/**
+ * Expand dot-notation keys into nested objects.
+ * `{ "user.name": "Alice", "user.age": "30" }` → `{ user: { name: "Alice", age: "30" } }`
+ *
+ * Keys without dots are left as-is. Bracket notation (e.g. `items[0]`) is NOT
+ * supported — use dot notation (`items.0`) instead.
+ */
+function expandDotPaths(flat: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  let hasDotPaths = false;
+
+  // First pass: check if any keys have dots
+  for (const key of Object.keys(flat)) {
+    if (key.includes('.')) {
+      hasDotPaths = true;
+      break;
+    }
+  }
+
+  // Fast path: no dot-notation keys, return as-is
+  if (!hasDotPaths) return flat;
+
+  for (const [key, value] of Object.entries(flat)) {
+    if (!key.includes('.')) {
+      result[key] = value;
+      continue;
+    }
+
+    const parts = key.split('.');
+    let current: Record<string, unknown> = result;
+
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      if (current[part] === undefined || current[part] === null) {
+        current[part] = {};
+      }
+      // If current[part] is not an object (e.g., a string from a non-dotted key),
+      // the dot-path takes precedence
+      if (typeof current[part] !== 'object' || current[part] instanceof File) {
+        current[part] = {};
+      }
+      current = current[part] as Record<string, unknown>;
+    }
+
+    current[parts[parts.length - 1]] = value;
+  }
+
+  return result;
+}
+
+// ─── Coercion Helpers ────────────────────────────────────────────────────
+
+/**
+ * Schema-agnostic coercion primitives for common FormData patterns.
+ *
+ * These are plain transform functions — they compose with any schema library's
+ * `transform`/`preprocess` pipeline:
+ *
+ * ```ts
+ * // Zod
+ * z.preprocess(coerce.number, z.number())
+ * // Valibot
+ * v.pipe(v.unknown(), v.transform(coerce.number), v.number())
+ * ```
+ */
+export const coerce = {
+  /**
+   * Coerce a string to a number.
+   * - `"42"` → `42`
+   * - `"3.14"` → `3.14`
+   * - `""` / `undefined` / `null` → `undefined`
+   * - Non-numeric strings → `undefined` (schema validation will catch this)
+   */
+  number(value: unknown): number | undefined {
+    if (value === undefined || value === null || value === '') return undefined;
+    if (typeof value === 'number') return value;
+    if (typeof value !== 'string') return undefined;
+    const num = Number(value);
+    if (Number.isNaN(num)) return undefined;
+    return num;
+  },
+
+  /**
+   * Coerce a checkbox value to a boolean.
+   * HTML checkboxes submit "on" when checked and are absent when unchecked.
+   * - `"on"` / any truthy string → `true`
+   * - `undefined` / `null` / `""` → `false`
+   */
+  checkbox(value: unknown): boolean {
+    if (value === undefined || value === null || value === '') return false;
+    if (typeof value === 'boolean') return value;
+    // Any non-empty string (typically "on") is true
+    return typeof value === 'string' && value.length > 0;
+  },
+
+  /**
+   * Parse a JSON string into an object.
+   * - Valid JSON string → parsed object
+   * - `""` / `undefined` / `null` → `undefined`
+   * - Invalid JSON → `undefined` (schema validation will catch this)
+   */
+  json(value: unknown): unknown {
+    if (value === undefined || value === null || value === '') return undefined;
+    if (typeof value !== 'string') return value;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return undefined;
+    }
+  },
+};

package/src/server/form-flash.ts

@@ -0,0 +1,93 @@
+/**
+ * Form Flash — ALS-based store for no-JS form action results.
+ *
+ * When a no-JS form action completes, the server re-renders the page with
+ * the action result injected via AsyncLocalStorage instead of redirecting
+ * (which would discard the result). Server components read the flash and
+ * pass it to client form components as the initial `useActionState` value.
+ *
+ * This follows the Remix/Rails pattern — the form component becomes the
+ * single source of truth for both with-JS (React state) and no-JS (flash).
+ *
+ * The flash data is server-side only — never serialized to cookies or headers.
+ *
+ * See design/08-forms-and-actions.md §"No-JS Error Round-Trip"
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { ValidationErrors } from './action-client.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+/**
+ * Flash data injected into the re-render after a no-JS form submission.
+ *
+ * This is the action result from the server action, stored in ALS so server
+ * components can read it and pass it to client form components as the initial
+ * state for `useActionState`. This makes the form component a single source
+ * of truth for both with-JS and no-JS paths.
+ *
+ * The shape matches `ActionResult<unknown>` — it's one of:
+ * - `{ data: ... }` — success
+ * - `{ validationErrors, submittedValues }` — validation failure
+ * - `{ serverError }` — server error
+ */
+export interface FormFlashData {
+  /** Success data from the action. */
+  data?: unknown;
+  /** Validation errors keyed by field name. `_root` for form-level errors. */
+  validationErrors?: ValidationErrors;
+  /** Raw submitted values for repopulating form fields. File objects are excluded. */
+  submittedValues?: Record<string, unknown>;
+  /** Server error if the action threw an ActionError. */
+  serverError?: { code: string; data?: Record<string, unknown> };
+}
+
+// ─── ALS Store ───────────────────────────────────────────────────────────
+
+const formFlashAls = new AsyncLocalStorage<FormFlashData>();
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Read the form flash data for the current request.
+ *
+ * Returns `null` if no flash data is present (i.e., this is a normal page
+ * render, not a re-render after a no-JS form submission).
+ *
+ * Pass the flash as the initial state to `useActionState` so the form
+ * component has a single source of truth for both with-JS and no-JS paths:
+ *
+ * ```tsx
+ * // app/contact/page.tsx (server component)
+ * import { getFormFlash } from '@timber/app/server'
+ *
+ * export default function ContactPage() {
+ *   const flash = getFormFlash()
+ *   return <ContactForm flash={flash} />
+ * }
+ *
+ * // app/contact/form.tsx (client component)
+ * export function ContactForm({ flash }) {
+ *   const [result, action, isPending] = useActionState(submitContact, flash)
+ *   // result is the single source of truth — flash seeds it on no-JS
+ * }
+ * ```
+ */
+export function getFormFlash(): FormFlashData | null {
+  return formFlashAls.getStore() ?? null;
+}
+
+// ─── Framework-Internal ──────────────────────────────────────────────────
+
+/**
+ * Run a callback with form flash data in scope.
+ *
+ * Used by the action handler to re-render the page with validation errors
+ * available via `getFormFlash()`. Not part of the public API.
+ *
+ * @internal
+ */
+export function runWithFormFlash<T>(data: FormFlashData, fn: () => T): T {
+  return formFlashAls.run(data, fn);
+}