@timber-js/app 0.2.0-alpha.186 → 0.2.0-alpha.188

package/src/plugins/static-build.ts

@@ -401,6 +401,55 @@ interface StaticGenerateModule {
   ) => Promise<StaticGenerationSummary>;
 }
 
+/**
+ * A port as Node actually hands it over: `unref()` is a Node addition the DOM
+ * lib type does not declare. Optional rather than asserted, so a runtime whose
+ * `MessageChannel` has no such method is simply skipped instead of throwing.
+ */
+type ReleasablePort = MessagePort & { unref?: () => void };
+
+/**
+ * Run `fn` with `MessageChannel` instrumented, then stop every channel opened
+ * while it ran from holding the process open.
+ *
+ * Static generation is the only build pass that renders **HTML** in the build
+ * process: it imports the built app bundle and drives the full SSR pipeline
+ * through it. React's scheduler opens a `MessageChannel` at module scope in
+ * that bundle (`scheduler`'s DOM build) and never closes it, and a ref'd
+ * `MessagePort` keeps Node's event loop alive on its own — so `timber build`
+ * finished the site, printed its summary, and then hung forever. Server-mode
+ * builds are unaffected because nothing there renders through react-dom.
+ *
+ * `unref()` is the whole fix: it leaves the port working and only drops the
+ * "keep the process alive" property. It is applied **after** `fn` resolves, so
+ * a render in flight can never be cut short by the process exiting under it —
+ * an unref'd port would let Node exit while the scheduler still had a
+ * continuation queued, which is a silently truncated page rather than a hang.
+ *
+ * Nothing renders after this pass. If that ever changes, the release has to
+ * move to the end of whatever renders last.
+ *
+ * @internal Exported for testing.
+ */
+export async function withSchedulerPortsReleased<T>(fn: () => Promise<T>): Promise<T> {
+  const opened: ReleasablePort[] = [];
+  const OriginalMessageChannel = globalThis.MessageChannel;
+
+  globalThis.MessageChannel = class extends OriginalMessageChannel {
+    constructor() {
+      super();
+      opened.push(this.port1, this.port2);
+    }
+  };
+
+  try {
+    return await fn();
+  } finally {
+    globalThis.MessageChannel = OriginalMessageChannel;
+    for (const port of opened) port.unref?.();
+  }
+}
+
 /**
  * Load the built RSC entry and run the static generation pass.
  *
@@ -435,26 +484,6 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
 
   console.log('[timber] Static generation: building site…');
 
-  let mod: StaticGenerateModule;
-  try {
-    const entryUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`;
-    mod = (await import(/* @vite-ignore */ entryUrl)) as StaticGenerateModule;
-  } catch (error) {
-    throw new Error(
-      `[timber] Static generation: failed to load the built RSC entry (${entryPath}). ` +
-        `The full request handler must initialize for static rendering.`,
-      { cause: error }
-    );
-  }
-
-  const generate = mod.__timber_generateStaticSite;
-  if (typeof generate !== 'function') {
-    throw new Error(
-      `[timber] Static generation: built RSC entry does not export ` +
-        `__timber_generateStaticSite — rebuild from a clean build directory`
-    );
-  }
-
   const staticDir = join(ctx.buildDir, 'static-pages');
   await cleanConditionalArtifacts(staticDir);
   await mkdir(staticDir, { recursive: true });
@@ -470,10 +499,35 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
   // now inside the payload itself — a field on its root row — so the `.rsc`
   // file carries them and there is nothing to lift (TIM-1294).
 
-  const summary = await generate({
-    autoSitemapEnabled,
-    renderTimeoutMs: ctx.config.renderTimeoutMs,
-    onEntry: (entry: StaticPageEntry) => writer.write(entry),
+  // The app bundle is imported and rendered inside this wrapper, and only
+  // inside it: everything it opens to schedule React work is released on the
+  // way out so the build process can exit.
+  const summary = await withSchedulerPortsReleased(async () => {
+    let mod: StaticGenerateModule;
+    try {
+      const entryUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`;
+      mod = (await import(/* @vite-ignore */ entryUrl)) as StaticGenerateModule;
+    } catch (error) {
+      throw new Error(
+        `[timber] Static generation: failed to load the built RSC entry (${entryPath}). ` +
+          `The full request handler must initialize for static rendering.`,
+        { cause: error }
+      );
+    }
+
+    const generate = mod.__timber_generateStaticSite;
+    if (typeof generate !== 'function') {
+      throw new Error(
+        `[timber] Static generation: built RSC entry does not export ` +
+          `__timber_generateStaticSite — rebuild from a clean build directory`
+      );
+    }
+
+    return generate({
+      autoSitemapEnabled,
+      renderTimeoutMs: ctx.config.renderTimeoutMs,
+      onEntry: (entry: StaticPageEntry) => writer.write(entry),
+    });
   });
 
   const totalUrls = summary.rendered + summary.errors.length;

package/src/routing/codegen-shared.ts

@@ -1,13 +1,13 @@
 /**
- * Shared codegen helpers — import-path computation, codec chain type
- * builder, and searchParams type formatter.
+ * Shared codegen helpers — import-path computation and codec chain type
+ * builders.
  *
  * Extracted from `codegen.ts` so `link-codegen.ts` can use the same
  * helpers without a cyclic import.
  */
 
 import { relative, posix } from 'node:path';
-import type { ParamEntry, RouteEntry } from './codegen-types.js';
+import type { ParamEntry } from './codegen-types.js';
 
 /**
  * Compute a relative import specifier for a codec/page file, stripping
@@ -21,65 +21,6 @@ export function codecImportPath(codecFilePath: string, importBase: string | unde
   return './' + posix.basename(absPath);
 }
 
-/** Name of the shared helper type emitted at the top of the .d.ts. */
-export const RESOLVE_SEGMENT_FIELD_TYPE_NAME = '_TimberResolveSegmentField';
-
-/**
- * Helper type emitted once at the top of the generated `.d.ts` and
- * referenced by every codec-chain conditional. Without this shared
- * helper, the inline expansion would duplicate the fallback branch on
- * every step and grow O(2^N) in chain depth (a single deep nested route
- * could blow up the file size and TS performance). With the helper,
- * each step reuses the named type and growth is O(N).
- *
- * The helper is a 2-arg conditional: given a typeof import expression
- * (`Def`), a key (`K`), and a fallback (`F`), it returns `T[K]` if
- * `Def extends ParamsDefinition<T>` and `K extends keyof T`, otherwise
- * `F`. The codec chain composes calls to this helper.
- */
-export function emitResolveSegmentFieldHelper(): string {
-  return [
-    `type ${RESOLVE_SEGMENT_FIELD_TYPE_NAME}<Def, K extends string, F> =`,
-    `  Def extends import('@timber-js/app/segment-params').ParamsDefinition<infer T>`,
-    `    ? K extends keyof T ? T[K] : F`,
-    `    : F;`,
-  ].join('\n');
-}
-
-/**
- * Build a TypeScript type expression that resolves a single param's
- * codec by walking a chain of params.ts files in priority order.
- *
- * Each entry in the chain emits one application of the shared
- * `_TimberResolveSegmentField` helper type. Composing N applications
- * grows linearly with chain depth (O(N) characters), unlike an inline
- * conditional that would duplicate the fallback in each branch and
- * grow O(2^N).
- *
- * The closest match (position 0 in the chain) is checked first; if its
- * `segmentParams` definition declares the key, its inferred type wins.
- * Otherwise we fall through to the next entry, and finally to the
- * provided fallback. See TIM-834.
- */
-export function buildCodecChainType(
-  p: ParamEntry,
-  importBase: string | undefined,
-  fallback: string
-): string {
-  const files = p.codecFilePaths;
-  if (!files || files.length === 0) return fallback;
-  const key = JSON.stringify(p.name);
-  // Compose helper applications inside-out so the closest entry
-  // (files[0]) ends up as the OUTERMOST application. Each application
-  // adds a constant-size wrapper around the running fallback.
-  let inner = fallback;
-  for (let i = files.length - 1; i >= 0; i--) {
-    const importPath = codecImportPath(files[i], importBase);
-    inner = `${RESOLVE_SEGMENT_FIELD_TYPE_NAME}<(typeof import('${importPath}'))['segmentParams'], ${key}, ${inner}>`;
-  }
-  return inner;
-}
-
 /**
  * Build a TypeScript type expression for a single param using the global
  * schema's InferCodecType. Falls back to the param's base type when
@@ -96,20 +37,3 @@ export function buildSchemaParamType(p: ParamEntry, fallback?: string): string {
   const fb = fallback ?? p.type;
   return `typeof schema['segmentParams'] extends Record<${key}, infer V> ? InferCodecType<V> : ${fb}`;
 }
-
-/**
- * Format the searchParams type for a route entry.
- *
- * When a page.tsx (or params.ts) exports searchParams, we reference its
- * inferred type via an import type. The import path is relative to
- * `importBase` (the directory where the .d.ts will be written). When
- * importBase is undefined, falls back to a bare relative path.
- */
-export function formatSearchParamsType(route: RouteEntry, importBase?: string): string {
-  if (route.hasSearchParams && route.searchParamsPagePath) {
-    const importPath = codecImportPath(route.searchParamsPagePath, importBase);
-    // Extract the type from the named 'searchParams' export of the page module.
-    return `(typeof import('${importPath}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
-  }
-  return '{}';
-}

package/src/routing/codegen-types.ts

@@ -15,12 +15,18 @@ export interface RouteEntry {
   segmentPath: string;
   /** Accumulated params from all ancestor dynamic segments */
   params: ParamEntry[];
-  /** Whether the page.tsx exports searchParams */
-  hasSearchParams: boolean;
-  /** Absolute path to the page file that exports searchParams (for import paths) */
-  searchParamsPagePath?: string;
   /** Whether this is an API route (route.ts) vs page route */
   isApiRoute: boolean;
+  /**
+   * Whether a request can reach this segment — it has a `page` or `route`.
+   *
+   * False for a segment that only hosts a layout/middleware/access above the
+   * leaf. Those still need typed `getSegmentParams(SEGMENT_PATH)` overloads
+   * (they have a `$segment` module), but must NOT appear in urlPath-keyed
+   * emissions — the `Routes` interface and `<Link>` — because their urlPath
+   * is not an addressable route. See TIM-1342.
+   */
+  isRoutable: boolean;
   /** Whether this entry lives inside a parallel slot (@name). Slot entries
    *  share their parent's urlPath — urlPath-keyed emissions dedupe them,
    *  preferring the non-slot entry. segmentPath-keyed emissions keep all. */
@@ -53,31 +59,4 @@ export interface ParamEntry {
    *  e.g. '[id]', '[...slug]', '[[...slug]]' */
   bracketName: string;
   type: 'string' | 'string[]' | 'string[] | undefined';
-  /**
-   * Ordered list of params.ts files in the route chain that may declare
-   * a codec for this param, in priority order — **closest-to-leaf
-   * first**. The generated type emits a chain that picks the first
-   * entry whose `segmentParams` definition declares this param key.
-   *
-   * This array is the SAME for every param in a given route entry
-   * (it is the route's full ancestry of params.ts files in leaf-first
-   * order); the type-level conditional in `buildCodecChainType`
-   * narrows per-key. Sharing the array matches the runtime semantics
-   * of `coerceSegmentParams`, which walks segments top-down and lets
-   * later (deeper) coercions overwrite earlier ones — closest-to-leaf
-   * wins for both types and runtime.
-   *
-   * See TIM-834.
-   */
-  codecFilePaths?: string[];
-  /**
-   * Per-segment legacy fallback: a layout.tsx or page.tsx that exports
-   * `segmentParams` directly (pre-TIM-508 convention). Used only when
-   * the chain has no params.ts files at all. Does NOT participate in
-   * inheritance — a layout/page export is per-segment only.
-   *
-   * @internal Set during `collectRoutes`; consumed at leaf time when
-   *   building the final `codecFilePaths`.
-   */
-  legacyCodecFilePath?: string;
 }

package/src/routing/codegen-write.ts

@@ -0,0 +1,139 @@
+/**
+ * Route-map codegen writer.
+ *
+ * Materializes the generated route types on disk: `.timber/timber-routes.d.ts`,
+ * `.timber/segment-types.d.ts` (via `writeSegmentTypes`), and the root
+ * `timber-env.d.ts` that references them.
+ *
+ * Lives outside `plugins/routing.ts` because it has two callers with two
+ * different failure policies: the dev/build plugin starts the write off the hot
+ * path and logs failures, while `timber check` awaits it and treats a failure as
+ * fatal — a type check run against absent or stale route types reports errors
+ * about code that is fine. One implementation, two policies, so the bytes on
+ * disk cannot drift between the two commands.
+ *
+ * Design docs: 09-typescript.md §"Typed Routes", 18-build-system.md
+ */
+
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { generateRouteMap } from './codegen.js';
+import { writeSegmentTypes } from './segment-codegen.js';
+import type { RouteTree } from './types.js';
+
+/**
+ * Path (relative to the project root) of the generated route map declaration
+ * file, and the name of the root file that `/// <reference>`s it.
+ *
+ * Exported because `timber check` has to answer whether the user's tsconfig
+ * pulls these into the program — a question about these exact paths. It derives
+ * them from here rather than restating them, so a rename cannot leave the check
+ * looking for a file nothing writes.
+ */
+export const CODEGEN_OUTPUT = '.timber/timber-routes.d.ts';
+
+/** Root-level file that references the generated declarations. */
+export const ENV_DTS_FILENAME = 'timber-env.d.ts';
+
+/**
+ * Content of the timber-env.d.ts file written to the project root.
+ *
+ * Uses a triple-slash reference so TypeScript auto-discovers the generated
+ * route map without the user needing to edit tsconfig.json — same pattern
+ * as Next.js's next-env.d.ts.
+ *
+ * Also references `vite/client` so side-effect imports like
+ * `import './globals.css'` type-check without ts(2882), and so
+ * `import.meta.env`, `import.meta.hot`, `import.meta.glob`, asset
+ * imports (`*.png`, `*.svg`, …), CSS modules, and `?url`/`?raw`/
+ * `?inline` query variants all resolve without the user editing
+ * tsconfig.json themselves. Next.js's next-env.d.ts plays the same
+ * role via `next/types/global`.
+ *
+ * `vite` is a peer dep of `@timber-js/app`, so the reference always
+ * resolves in a correctly-installed project.
+ */
+const TIMBER_ENV_DTS = [
+  '// This file is auto-generated by timber.js. Do not edit.',
+  '// It ensures TypeScript picks up the generated route types and',
+  '// Vite-provided ambient types (CSS, assets, import.meta.env, HMR).',
+  '/* eslint-disable @typescript-eslint/triple-slash-reference */',
+  '/// <reference path=".timber/timber-routes.d.ts" />',
+  '/// <reference types="vite/client" />',
+  '',
+].join('\n');
+
+/**
+ * Codegen writes that have been started but have not yet landed on disk.
+ *
+ * `writeRouteCodegen` is deliberately unawaited on the dev/build hot path,
+ * which leaves that caller no way to know the files exist yet. Anything that
+ * tears down the project root — a build process exiting, a test removing its
+ * temp root — then races the writes: `rmSync` empties a directory that a
+ * pending `mkdir` immediately recreates, and the removal fails with ENOTEMPTY.
+ *
+ * Every started write registers here and deregisters when it settles, so
+ * `flushCodegenWrites()` can await them instead of guessing at a delay.
+ */
+const pendingCodegenWrites = new Set<Promise<void>>();
+
+/**
+ * Resolve once every codegen write started so far has landed on disk.
+ *
+ * Safe to call at any time and from anywhere — writes are tracked per process,
+ * not per plugin instance, so a caller does not need a handle on the plugin
+ * that started them. Never rejects: the tracked copy of each write has its
+ * rejection swallowed, so a failing write cannot turn a teardown barrier into
+ * an unhandled rejection. Callers that care about failure await the promise
+ * `writeRouteCodegen` returned instead.
+ */
+export async function flushCodegenWrites(): Promise<void> {
+  // Loop rather than a single Promise.all: a write started while we were
+  // awaiting would otherwise be missed, and the set would still be non-empty
+  // on return.
+  //
+  // Each round drops what it awaited rather than trusting the per-write
+  // `finally` to have run, so the two removal paths are independent — a
+  // deregistration that stopped firing would leak memory in dev, but it can
+  // never turn this into a spin.
+  while (pendingCodegenWrites.size > 0) {
+    const inFlight = [...pendingCodegenWrites];
+    await Promise.all(inFlight);
+    for (const write of inFlight) pendingCodegenWrites.delete(write);
+  }
+}
+
+/**
+ * Write the generated route map, segment types, and the timber-env.d.ts
+ * reference file for `tree`.
+ *
+ * Returns a promise that **rejects** if any write fails. The dev/build plugin
+ * does not await it (types are a developer convenience there, not a runtime
+ * dependency) and logs instead; `timber check` awaits it and fails the command.
+ * Either way the write is registered with `flushCodegenWrites()`.
+ */
+export function writeRouteCodegen(tree: RouteTree, appDir: string, root: string): Promise<void> {
+  const timberDir = join(root, '.timber');
+  const content = generateRouteMap(tree, { appDir, outputDir: timberDir });
+  const routesPath = join(root, CODEGEN_OUTPUT);
+  const envPath = join(root, ENV_DTS_FILENAME);
+
+  const done = mkdir(timberDir, { recursive: true })
+    .then(() =>
+      Promise.all([
+        writeFile(routesPath, content, 'utf-8'),
+        writeFile(envPath, TIMBER_ENV_DTS, 'utf-8'),
+        writeSegmentTypes(tree, appDir, root),
+      ])
+    )
+    .then(() => undefined);
+
+  // The tracked copy swallows rejection so `flushCodegenWrites` — a teardown
+  // barrier — never rejects and never leaves an unhandled rejection behind.
+  // The returned promise keeps its rejection for callers that want it.
+  const tracked = done.catch(() => undefined);
+  pendingCodegenWrites.add(tracked);
+  void tracked.finally(() => pendingCodegenWrites.delete(tracked));
+
+  return done;
+}