@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/server/flush.ts

@@ -1,182 +0,0 @@
-/**
- * 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/manifest-status-resolver.ts

@@ -1,215 +0,0 @@
-/**
- * Manifest-compatible status-code file resolver.
- *
- * The existing status-code-resolver.ts works with SegmentNode (Map-based).
- * This module works with ManifestSegmentNode (object-based) for use at
- * runtime in the RSC/SSR entries, where the route manifest provides
- * plain objects instead of Maps.
- *
- * Supports two format families:
- * - 'component' (default): .tsx/.jsx/.mdx status files → React rendering pipeline
- * - 'json': .json status files → raw JSON response, no React
- *
- * Follows the same fallback chains as status-code-resolver.ts:
- *
- * **Component chain (4xx):**
- *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
- *   Pass 4 — framework default (returns null)
- *
- * **JSON chain (4xx):**
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
- *   Pass 2 — framework default JSON (returns null, caller provides bare JSON)
- *
- * See design/10-error-handling.md §"Status-Code Files"
- */
-
-import type { ManifestSegmentNode } from './route-matcher.js';
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-/** A file reference in the manifest (lazy import + path). */
-interface ManifestFile {
-  load: () => Promise<unknown>;
-  filePath: string;
-}
-
-/** How the status-code file was matched. */
-export type ManifestStatusFileKind =
-  | 'exact' // e.g. 403.tsx matched status 403
-  | 'category' // e.g. 4xx.tsx matched status 403
-  | 'legacy' // e.g. not-found.tsx matched status 404
-  | 'error'; // error.tsx as last resort
-
-/** Response format family for status-code resolution. */
-export type ManifestStatusFileFormat = 'component' | 'json';
-
-/** Result of resolving a status-code file from manifest segments. */
-export interface ManifestStatusFileResolution {
-  /** The matched manifest file (has load() and filePath). */
-  file: ManifestFile;
-  /** The HTTP status code (always the original status, not the file's code). */
-  status: number;
-  /** How the file was matched. */
-  kind: ManifestStatusFileKind;
-  /** Index into the segments array where the file was found. */
-  segmentIndex: number;
-}
-
-// ─── Legacy Compat Mapping ───────────────────────────────────────────────────
-
-const LEGACY_FILE_TO_STATUS: Record<string, number> = {
-  'not-found': 404,
-  'forbidden': 403,
-  'unauthorized': 401,
-};
-
-// ─── Resolver ────────────────────────────────────────────────────────────────
-
-/**
- * Resolve the status-code file to render for a given HTTP status code,
- * using manifest segment nodes (plain objects, not Maps).
- *
- * @param status - The HTTP status code (4xx or 5xx).
- * @param segments - The matched segment chain from root (index 0) to leaf (last).
- * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
- */
-export function resolveManifestStatusFile(
-  status: number,
-  segments: ReadonlyArray<ManifestSegmentNode>,
-  format: ManifestStatusFileFormat = 'component'
-): ManifestStatusFileResolution | null {
-  if (status < 400 || status > 599) {
-    return null;
-  }
-
-  if (format === 'json') {
-    return resolveJson(status, segments);
-  }
-
-  if (status <= 499) {
-    return resolve4xx(status, segments);
-  }
-
-  return resolve5xx(status, segments);
-}
-
-/**
- * 4xx component fallback chain (three separate passes):
- *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
- */
-function resolve4xx(
-  status: number,
-  segments: ReadonlyArray<ManifestSegmentNode>
-): ManifestStatusFileResolution | null {
-  const statusStr = String(status);
-
-  // Pass 1: status files across all segments (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.statusFiles) continue;
-
-    // Exact match first
-    const exact = segment.statusFiles[statusStr];
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    // Category catch-all
-    const category = segment.statusFiles['4xx'];
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
-  }
-
-  // Pass 2: legacy compat files (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.legacyStatusFiles) continue;
-
-    for (const [name, legacyStatus] of Object.entries(LEGACY_FILE_TO_STATUS)) {
-      if (legacyStatus === status) {
-        const file = segment.legacyStatusFiles[name];
-        if (file) {
-          return { file, status, kind: 'legacy', segmentIndex: i };
-        }
-      }
-    }
-  }
-
-  // Pass 3: error.tsx (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    if (segments[i].error) {
-      return { file: segments[i].error!, status, kind: 'error', segmentIndex: i };
-    }
-  }
-
-  return null;
-}
-
-/**
- * 5xx component fallback chain (single pass, per-segment):
- *   At each segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
- */
-function resolve5xx(
-  status: number,
-  segments: ReadonlyArray<ManifestSegmentNode>
-): ManifestStatusFileResolution | null {
-  const statusStr = String(status);
-
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-
-    if (segment.statusFiles) {
-      const exact = segment.statusFiles[statusStr];
-      if (exact) {
-        return { file: exact, status, kind: 'exact', segmentIndex: i };
-      }
-
-      const categoryKey = '5xx';
-      const category = segment.statusFiles[categoryKey];
-      if (category) {
-        return { file: category, status, kind: 'category', segmentIndex: i };
-      }
-    }
-
-    if (segment.error) {
-      return { file: segment.error, status, kind: 'error', segmentIndex: i };
-    }
-  }
-
-  return null;
-}
-
-/**
- * JSON fallback chain (for both 4xx and 5xx):
- *   At each segment (leaf → root): {status}.json → {category}.json
- *   No legacy compat, no error.tsx — JSON chain terminates at category catch-all.
- */
-function resolveJson(
-  status: number,
-  segments: ReadonlyArray<ManifestSegmentNode>
-): ManifestStatusFileResolution | null {
-  const statusStr = String(status);
-  const categoryKey = status >= 500 ? '5xx' : '4xx';
-
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.jsonStatusFiles) continue;
-
-    const exact = segment.jsonStatusFiles[statusStr];
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    const category = segment.jsonStatusFiles[categoryKey];
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
-  }
-
-  return null;
-}

package/src/server/prerender.ts

@@ -1,139 +0,0 @@
-/**
- * Pre-rendering types and utilities.
- *
- * A `prerender.ts` file in a route segment signals the framework to
- * pre-render the route's shell at build time. This module defines the
- * types that a user exports from `prerender.ts` and utilities for
- * loading and validating those exports.
- *
- * Design doc: design/15-future-prerendering.md
- */
-
-import { parseCacheLife } from '#/plugins/cache-transform.js';
-
-// ---------------------------------------------------------------------------
-// Types — user-facing exports from prerender.ts
-// ---------------------------------------------------------------------------
-
-/**
- * The shape of a prerender.ts module's exports.
- *
- * ```ts
- * // app/docs/[slug]/prerender.ts
- * export async function generateParams() {
- *   return docs.map(d => ({ slug: d.slug }))
- * }
- * export const ttl = '1h'
- * export const tags = ['docs']
- * ```
- */
-export interface PrerenderConfig {
-  /**
-   * Generate the set of params to pre-render at build time.
-   * Required for dynamic segments (`[param]`).
-   * Optional for static segments (the single URL is pre-rendered automatically).
-   */
-  generateParams?: () => Promise<Record<string, string>[]> | Record<string, string>[];
-
-  /**
-   * How long the pre-rendered shell is considered fresh.
-   * Accepts duration strings ('30s', '5m', '1h', '2d', '1w') or seconds as a number.
-   * Default: Infinity (cache until explicit invalidation).
-   */
-  ttl?: string | number;
-
-  /**
-   * Invalidation tags. Calling `revalidateTag('docs')` purges all
-   * pre-rendered shells with that tag.
-   */
-  tags?: string[];
-
-  /**
-   * Fallback strategy for dynamic routes without `generateParams`.
-   * Only valid in `output: 'static'` mode.
-   * - `'shell'`: emit a single pre-rendered shell that serves as client-side fallback
-   */
-  fallback?: 'shell';
-}
-
-// ---------------------------------------------------------------------------
-// Parsed prerender config — framework-internal, with TTL resolved to seconds
-// ---------------------------------------------------------------------------
-
-export interface ResolvedPrerenderConfig {
-  /** TTL in seconds. Infinity if not set. */
-  ttlSeconds: number;
-  /** Invalidation tags */
-  tags: string[];
-  /** The generateParams function, if provided */
-  generateParams?: () => Promise<Record<string, string>[]> | Record<string, string>[];
-  /** Fallback strategy */
-  fallback?: 'shell';
-}
-
-/**
- * Resolve raw prerender.ts exports into a normalized config.
- *
- * Validates:
- * - `ttl` is a valid duration string or number
- * - `tags` is an array of strings
- * - `fallback` is 'shell' or undefined
- */
-export function resolvePrerenderConfig(raw: PrerenderConfig): ResolvedPrerenderConfig {
-  const ttlSeconds = raw.ttl != null ? parseCacheLife(raw.ttl) : Infinity;
-
-  const tags = raw.tags ?? [];
-  if (!Array.isArray(tags) || tags.some((t) => typeof t !== 'string')) {
-    throw new Error(
-      `prerender.ts: tags must be an array of strings. Got: ${JSON.stringify(raw.tags)}`
-    );
-  }
-
-  if (raw.fallback != null && raw.fallback !== 'shell') {
-    throw new Error(
-      `prerender.ts: fallback must be 'shell' or omitted. Got: ${JSON.stringify(raw.fallback)}`
-    );
-  }
-
-  return {
-    ttlSeconds,
-    tags,
-    generateParams: raw.generateParams,
-    fallback: raw.fallback,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Build diagnostics
-// ---------------------------------------------------------------------------
-
-export interface PrerenderDiagnostic {
-  type: 'DYNAMIC_SEGMENT_NO_PARAMS';
-  segmentPath: string;
-  message: string;
-}
-
-/**
- * Check if a dynamic segment has `generateParams` when prerender.ts is present.
- * If not, emit a diagnostic — the route falls back to SSR.
- */
-export function checkDynamicSegmentParams(
-  segmentPath: string,
-  isDynamic: boolean,
-  hasGenerateParams: boolean,
-  fallback?: 'shell'
-): PrerenderDiagnostic | null {
-  if (!isDynamic) return null;
-  if (hasGenerateParams) return null;
-  if (fallback === 'shell') return null;
-
-  return {
-    type: 'DYNAMIC_SEGMENT_NO_PARAMS',
-    segmentPath,
-    message:
-      `Dynamic segment "${segmentPath}" has prerender.ts but no generateParams(). ` +
-      `The route will fall back to SSR at request time. ` +
-      `Add generateParams() to pre-render specific param values, ` +
-      `or set fallback: 'shell' (static mode only) for a client-side fallback shell.`,
-  };
-}