@timber-js/app 0.2.0-alpha.90 → 0.2.0-alpha.91

package/dist/routing/codegen-shared.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared codegen helpers — import-path computation, codec chain type
+ * builder, and searchParams type formatter.
+ *
+ * Extracted from `codegen.ts` so `link-codegen.ts` can use the same
+ * helpers without a cyclic import.
+ */
+import type { ParamEntry, RouteEntry } from './codegen-types.js';
+/**
+ * Compute a relative import specifier for a codec/page file, stripping
+ * the .ts/.tsx extension and resolving against the codegen output dir.
+ */
+export declare function codecImportPath(codecFilePath: string, importBase: string | undefined): string;
+/**
+ * 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 a conditional:
+ *   `(typeof import(file))['segmentParams'] extends ParamsDefinition<infer T>
+ *     ? K extends keyof T ? T[K] : <next>
+ *     : <next>`
+ *
+ * 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 ancestor, and finally to the
+ * provided fallback. See TIM-834.
+ */
+export declare function buildCodecChainType(p: ParamEntry, importBase: string | undefined, fallback: string): string;
+/**
+ * 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 declare function formatSearchParamsType(route: RouteEntry, importBase?: string): string;
+//# sourceMappingURL=codegen-shared.d.ts.map

package/dist/routing/codegen-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen-shared.d.ts","sourceRoot":"","sources":["../../src/routing/codegen-shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,UAAU,EACb,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GACf,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAOrF"}

package/dist/routing/codegen-types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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;
+    /** 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;
+}
+export interface ParamEntry {
+    name: string;
+    type: 'string' | 'string[]' | 'string[] | undefined';
+    /**
+     * Ordered list of params.ts (or layout/page) files that may declare a
+     * codec for this param, in priority order — closest match first.
+     *
+     * Position 0 is the segment's own params.ts (if present and exporting
+     * `segmentParams`); subsequent entries are ancestor params.ts files
+     * walking from closest ancestor up to the route root. The first entry
+     * in the chain whose `segmentParams` definition declares this param key
+     * wins. See TIM-834.
+     */
+    codecFilePaths?: string[];
+}
+//# sourceMappingURL=codegen-types.d.ts.map

package/dist/routing/codegen-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen-types.d.ts","sourceRoot":"","sources":["../../src/routing/codegen-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,gDAAgD;IAChD,eAAe,EAAE,OAAO,CAAC;IACzB,kFAAkF;IAClF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,sBAAsB,CAAC;IACrD;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B"}

package/dist/routing/codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/routing/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAuBzD,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CAWtF"}
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/routing/codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAKzD,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CAWtF"}

package/dist/routing/index.js

@@ -1,3 +1,3 @@
 import { t as classifyUrlSegment } from "../_chunks/segment-classify-BDNn6EzD.js";
-import { a as DEFAULT_PAGE_EXTENSIONS, i as scanRoutes, n as generateRouteMap, o as INTERCEPTION_MARKERS, r as classifySegment, t as collectInterceptionRewrites } from "../_chunks/interception-DRlhJWbu.js";
+import { a as DEFAULT_PAGE_EXTENSIONS, i as scanRoutes, n as generateRouteMap, o as INTERCEPTION_MARKERS, r as classifySegment, t as collectInterceptionRewrites } from "../_chunks/interception-ErnB33JX.js";
 export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS, classifySegment, classifyUrlSegment, collectInterceptionRewrites, generateRouteMap, scanRoutes };

package/dist/routing/link-codegen.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Typed `<Link>` codegen — interface augmentation generation.
+ *
+ * Extracted from `codegen.ts` to keep that file under the project's
+ * 500-line cap. This module owns everything that emits the
+ * `interface LinkFunction { ... }` augmentation blocks in the generated
+ * `.timber/timber-routes.d.ts`.
+ *
+ * Two augmentation blocks are emitted:
+ *
+ * 1. **Per-route discriminated union** (`formatTypedLinkOverloads`) —
+ *    one call signature whose props is a union keyed on `href`. TS
+ *    narrows by literal href and reports prop errors against the
+ *    matched variant. See TIM-835 and `design/09-typescript.md`.
+ *
+ * 2. **Catch-all overloads** (`formatLinkCatchAllOverloads`) — external
+ *    href literals (`http://`, `mailto:`, etc.) and a computed-string
+ *    `<H extends string>` signature for runtime-computed paths.
+ *
+ * Block ordering is critical for error UX: per-route is emitted FIRST
+ * so that, after TS's "later overload set ordered first" merge rule,
+ * the discriminated union ends up LAST in resolution order — the
+ * overload TS reports against on failure.
+ */
+import type { ParamEntry, RouteEntry } from './codegen-types.js';
+/** Shared Link base-props type literal used in every emitted call signature. */
+export declare const LINK_BASE_PROPS_TYPE = "Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }";
+/**
+ * Build a TypeScript template literal pattern for a dynamic route.
+ * e.g. '/products/[id]'        → '/products/${string}'
+ *      '/blog/[...slug]'       → '/blog/${string}'
+ *      '/docs/[[...path]]'     → '/docs/${string}' (also matches /docs)
+ *      '/[org]/[repo]'         → '/${string}/${string}'
+ */
+export declare function buildResolvedPattern(route: RouteEntry): string | null;
+/**
+ * Format the segmentParams type for Link overloads.
+ *
+ * Link params accept `string | number` for single dynamic segments
+ * (convenience — values are stringified at runtime). Catch-all and
+ * optional catch-all remain `string[]` / `string[] | undefined`.
+ *
+ * When the segment's params chain (TIM-834) declares a typed codec, the
+ * inferred type from the codec wins via a nested conditional.
+ */
+export declare function formatLinkParamsType(params: ParamEntry[], importBase?: string): string;
+/**
+ * Catch-all call signatures for `<Link>` — external hrefs and computed
+ * `string` variables. Emitted from codegen in a SEPARATE
+ * `declare module` block (declared AFTER the per-route block) so the TS
+ * "later overload set ordered first" rule places these catch-all
+ * signatures ahead of per-route in resolution order, leaving per-route
+ * as the final overload whose error message is reported on failure.
+ *
+ * The conditional `string extends H ? ... : never` protection preserves
+ * TIM-624's guarantee that unknown internal path literals don't match
+ * the catch-all — typos like `<Link href="/typo" />` still error.
+ */
+export declare function formatLinkCatchAllOverloads(): string[];
+/**
+ * Generate typed per-route Link call signatures via LinkFunction
+ * interface merging.
+ *
+ * TIM-835: This emits a SINGLE call signature whose props is a
+ * discriminated union keyed on `href`. TypeScript narrows the union by
+ * the literal `href` at the call site, then checks the rest of the
+ * props against the matched variant. When `segmentParams` or
+ * `searchParams` is wrong, TS reports the error against the matched
+ * variant — naming the user's actual `href` and the offending field.
+ *
+ * Before TIM-835, this function emitted N separate per-route overloads
+ * (one per route, sometimes two for dynamic routes). When ALL overloads
+ * failed, TS would pick an arbitrary failed overload (heuristically the
+ * "last tried") to render the diagnostic, often pointing at a route
+ * completely unrelated to the one the user wrote. The discriminated
+ * union sidesteps overload-resolution heuristics entirely.
+ *
+ * Open property shapes (`Record<string, unknown>` instead of `never`)
+ * for `segmentParams` on routes that don't declare them keep generic
+ * `LinkProps`-spreading wrappers compiling. (Aligned with TIM-833.)
+ *
+ * TIM-832: this function still emits the per-route block FIRST and the
+ * catch-all block follows, so per-route remains the LAST overload set in
+ * resolution order — the one TS reports against on failure. With a
+ * discriminated union there is only one call signature in this block,
+ * so the resolved-template-vs-pattern ordering reduces to placing the
+ * pattern variant before the resolved-template variant inside the union.
+ */
+export declare function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): string[];
+//# sourceMappingURL=link-codegen.d.ts.map

package/dist/routing/link-codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-codegen.d.ts","sourceRoot":"","sources":["../../src/routing/link-codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGjE,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,8PAC4N,CAAC;AAE9P;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAkBrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAWtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,EAAE,CAiDtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAuF5F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.90",
+  "version": "0.2.0-alpha.91",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/routing/codegen-shared.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared codegen helpers — import-path computation, codec chain type
+ * builder, and searchParams type formatter.
+ *
+ * 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';
+
+/**
+ * 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 that resolves a single param's
+ * codec by walking a chain of params.ts files in priority order.
+ *
+ * Each entry in the chain emits a conditional:
+ *   `(typeof import(file))['segmentParams'] extends ParamsDefinition<infer T>
+ *     ? K extends keyof T ? T[K] : <next>
+ *     : <next>`
+ *
+ * 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 ancestor, 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);
+  // Build the nested conditional from the inside out so the closest
+  // entry (files[0]) ends up as the OUTERMOST check.
+  let inner = fallback;
+  for (let i = files.length - 1; i >= 0; i--) {
+    const importPath = codecImportPath(files[i], importBase);
+    inner =
+      `((typeof import('${importPath}'))['segmentParams'] extends ` +
+      `import('@timber-js/app/segment-params').ParamsDefinition<infer T> ` +
+      `? (${key} extends keyof T ? T[${key}] : ${inner}) : ${inner})`;
+  }
+  return inner;
+}
+
+/**
+ * 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

@@ -0,0 +1,37 @@
+/**
+ * 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;
+  /** 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;
+}
+
+export interface ParamEntry {
+  name: string;
+  type: 'string' | 'string[]' | 'string[] | undefined';
+  /**
+   * Ordered list of params.ts (or layout/page) files that may declare a
+   * codec for this param, in priority order — closest match first.
+   *
+   * Position 0 is the segment's own params.ts (if present and exporting
+   * `segmentParams`); subsequent entries are ancestor params.ts files
+   * walking from closest ancestor up to the route root. The first entry
+   * in the chain whose `segmentParams` definition declares this param key
+   * wins. See TIM-834.
+   */
+  codecFilePaths?: string[];
+}