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

package/src/react-canary.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="react/canary" />
+/// <reference types="react-dom/canary" />

package/src/routing/codegen-shared.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 } from './codegen-types.ts';
+
+/**
+ * Compute a relative import specifier for a codec/page file, stripping
+ * the .ts/.tsx extension and resolving against the codegen output dir.
+ */
+export function codecImportPath(codecFilePath: string, importBase: string | undefined): string {
+  const absPath = codecFilePath.replace(/\.(ts|tsx)$/, '');
+  if (importBase) {
+    return './' + relative(importBase, absPath).replace(/\\/g, '/');
+  }
+  return './' + posix.basename(absPath);
+}
+
+/**
+ * Build a TypeScript type expression for a single param using the global
+ * schema's InferCodecType. Falls back to the param's base type when
+ * schema doesn't declare this param (schemas are opt-in per key).
+ *
+ * Uses `infer` to extract the codec value rather than direct indexing
+ * because TypeScript doesn't narrow index validity inside a conditional
+ * type's true branch — `typeof schema.segmentParams[K]` produces TS2538
+ * even when the condition proves K is a valid key. In .d.ts files that
+ * error is suppressed and the type silently becomes `any`.
+ */
+export function buildSchemaParamType(p: ParamEntry, fallback?: string): string {
+  const key = JSON.stringify(p.bracketName);
+  const fb = fallback ?? p.type;
+  return `typeof schema['segmentParams'] extends Record<${key}, infer V> ? InferCodecType<V> : ${fb}`;
+}

package/src/routing/codegen-types.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared types for route codegen modules.
+ *
+ * Lives in its own file so `link-codegen.ts` and `codegen.ts` can import
+ * the same `RouteEntry` / `ParamEntry` shapes without a cyclic
+ * dependency between the two.
+ */
+
+/** A single route entry extracted from the segment tree. */
+export interface RouteEntry {
+  /** URL path pattern (e.g. "/products/[id]") */
+  urlPath: string;
+  /** Full tree path including groups and slots (e.g. "/(browse)/[artistSlug]/@shows/[year]").
+   *  Uniquely identifies a segment — unlike urlPath which strips groups/slots. */
+  segmentPath: string;
+  /** Accumulated params from all ancestor dynamic segments */
+  params: ParamEntry[];
+  /** 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. */
+  isSlotRoute?: boolean;
+  /**
+   * Whether this entry lives inside an intercepting subtree.
+   *
+   * Such an entry has **no URL of its own**. Interception adds no URL depth,
+   * so the scanner's `urlPath` for the subtree is the owner's path with the
+   * descendants' names appended — `(browse)/(...)[artistSlug]/[year]` computes
+   * `/[year]`, which is not the route it renders at (that is
+   * `/[artistSlug]/[year]`) and is not reachable by any request. It is also
+   * soft-navigation-only.
+   *
+   * So these entries are dropped from every urlPath-keyed emission (`Routes`,
+   * `useQueryStates`, typed `<Link>`) rather than deduped against the
+   * canonical route: dedupe only helps where the paths happen to collide, and
+   * a non-colliding computed path would be published as a real route.
+   * segmentPath-keyed emissions keep them, so the intercepting page's own
+   * params stay typed.
+   */
+  isInterceptingRoute?: boolean;
+  /** Whether a global schema (app/schema.ts) exists for this app */
+  hasSchema?: boolean;
+}
+
+export interface ParamEntry {
+  name: string;
+  /** Bracket-wrapped segment name as it appears in the filesystem and schema.
+   *  e.g. '[id]', '[...slug]', '[[...slug]]' */
+  bracketName: string;
+  type: 'string' | 'string[]' | 'string[] | undefined';
+}

package/src/routing/codegen-write.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { generateRouteMap } from './codegen.ts';
+import { writeSegmentTypes } from './segment-codegen.ts';
+import { writeFileAtomic } from '../utils/write-file-atomic.ts';
+import type { RouteTree } from './types.ts';
+
+/**
+ * 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" />',
+  '/// <reference types="react/canary" />',
+  '/// <reference types="react-dom/canary" />',
+  '',
+].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()`.
+ */
+/**
+ * Write `timber-env.d.ts` only when its content differs.
+ *
+ * Its content is constant per timber version, so almost every call is a no-op
+ * — and a file that is not rewritten cannot be read half-written. It is not
+ * replaced atomically because it lives in the user's project root, often
+ * committed: a rename would turn a symlink into a regular file, reset its
+ * permissions, and a process killed mid-write would leave a temp file next to
+ * their source. The in-place write happens only on first run or a timber
+ * upgrade.
+ */
+async function writeEnvDts(envPath: string): Promise<void> {
+  const existing = await readFile(envPath, 'utf-8').catch(() => null);
+  if (existing !== TIMBER_ENV_DTS) await writeFile(envPath, TIMBER_ENV_DTS, 'utf-8');
+}
+
+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(() =>
+      // The type checker can read these while they are being rewritten — an
+      // editor's TS server during `timber dev`, a `tsgo` run during `vite
+      // build`. A truncating write shows it an empty route map for the length
+      // of the write, and every typed route degrades to `any` (TIM-1562).
+      // The generated files under `.timber/` are replaced atomically.
+      Promise.all([
+        writeFileAtomic(routesPath, content),
+        writeEnvDts(envPath),
+        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;
+}