@timber-js/app 0.2.0-alpha.10 → 0.2.0-alpha.100

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.`,
-  };
-}