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

package/src/routing/codegen.ts

@@ -247,10 +247,18 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
 
     // Typed Link overloads — per-route with DIRECT types (no conditionals).
     // Direct types preserve TypeScript's excess property checking.
-    // The catch-all overload (segmentParams?: never) lives in link.tsx.
-    // See TIM-624.
+    //
+    // TIM-832: per-route and catch-all are emitted as TWO separate
+    // augmentation blocks. Per TS's merging rule "later overload sets
+    // ordered first", the catch-all block (declared SECOND in this file)
+    // ends up FIRST in the merged call-signature list at resolution time,
+    // which puts the per-route block LAST — so its error message is the
+    // one TypeScript reports when no overload matches. This gives users a
+    // clear prop-mismatch error (e.g. "'string | undefined' is not
+    // assignable to 'string | number' on id") instead of the old
+    // confusing "Type 'string' is not assignable to type 'never'" cascade.
     if (pageRoutes.length > 0) {
-      lines.push('  // Typed Link overloads per route');
+      lines.push('  // Typed Link overloads — per-route (block 1 / emitted first)');
       lines.push(...formatTypedLinkOverloads(pageRoutes, importBase));
       lines.push('');
     }
@@ -259,6 +267,17 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
     lines.push('');
   }
 
+  // TIM-832: catch-all block — emitted as a SEPARATE `declare module`
+  // augmentation so TS's "later overload set first" rule orders it ahead
+  // of the per-route block above at resolution time, leaving per-route as
+  // the "last overload" whose error TypeScript reports.
+  lines.push("declare module '@timber-js/app/client' {");
+  lines.push("  import type { SearchParamsDefinition } from '@timber-js/app/search-params'");
+  lines.push('');
+  lines.push(...formatLinkCatchAllOverloads());
+  lines.push('}');
+  lines.push('');
+
   return lines.join('\n');
 }
 
@@ -400,21 +419,90 @@ function buildResolvedPattern(route: RouteEntry): string | null {
   return templateParts.join('/');
 }
 
+/** Shared Link base-props type literal used in every emitted call signature. */
+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 }";
+
+/**
+ * TIM-832: 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.
+ */
+function formatLinkCatchAllOverloads(): string[] {
+  const lines: string[] = [];
+  const baseProps = LINK_BASE_PROPS_TYPE;
+
+  // TIM-830: the catch-all signatures accept EITHER the legacy
+  // `{ definition, values }` wrapper OR a flat `Record<string, unknown>`
+  // values object. External/computed hrefs can't be looked up in the
+  // runtime registry, so the wrapped form is still the reliable path;
+  // the flat form is kept permissive for callers migrating from typed-
+  // route hrefs to computed strings. `resolveHref` discriminates at
+  // runtime via the presence of a `definition` key.
+  const catchAllSearchParams =
+    '{ definition: SearchParamsDefinition<Record<string, unknown>>; values: Record<string, unknown> } | Record<string, unknown>';
+
+  // ExternalHref inlined here rather than referenced as an exported
+  // alias so the generated .d.ts stands alone without source imports.
+  const externalHref =
+    '`http://${string}` | `https://${string}` | `mailto:${string}` | `tel:${string}` | `ftp://${string}` | `//${string}` | `#${string}` | `?${string}`';
+
+  lines.push('  // Typed Link overloads — catch-all (block 2 / emitted second)');
+  lines.push('  interface LinkFunction {');
+
+  // (1) External/literal-protocol hrefs.
+  lines.push(`    (props: ${baseProps} & {`);
+  lines.push(`      href: ${externalHref}`);
+  lines.push(`      segmentParams?: never`);
+  lines.push(`      searchParams?: ${catchAllSearchParams}`);
+  lines.push(`    }): import('react').JSX.Element`);
+
+  // (2) Computed/variable href — non-literal `string` only.
+  // `string extends H` is true only when H is the wide `string` type,
+  // not a specific literal. Literal internal paths (typos) that don't
+  // match any per-route signature collapse to `never` here, but since
+  // this block is NOT the "last overload" at resolution time, TS
+  // instead reports the error from the per-route block — which now
+  // says `Type '"/typo"' is not assignable to type '"/products/[id]"'`
+  // or similar per-route-specific guidance.
+  lines.push(`    <H extends string>(`);
+  lines.push(`      props: string extends H`);
+  lines.push(`        ? ${baseProps} & {`);
+  lines.push(`            href: H`);
+  lines.push(`            segmentParams?: Record<string, string | number | string[]>`);
+  lines.push(`            searchParams?: ${catchAllSearchParams}`);
+  lines.push(`          }`);
+  lines.push(`        : never`);
+  lines.push(`    ): import('react').JSX.Element`);
+
+  lines.push('  }');
+  return lines;
+}
+
 /**
- * Generate typed Link call signatures via LinkFunction interface merging.
+ * Generate typed per-route Link call signatures via LinkFunction
+ * interface merging.
  *
  * Each call signature uses DIRECT types (not conditional types) for
  * segmentParams, preserving TypeScript's excess property checking.
  * Interface merging is the only reliable way to add "overloads" via
  * module augmentation — function overloads can't be augmented.
  *
- * The catch-all call signature (external protocols + computed strings)
- * lives in link.tsx. See TIM-624.
+ * TIM-832: this function emits ONLY the per-route block. The catch-all
+ * block is emitted separately by `formatLinkCatchAllOverloads` inside a
+ * second `declare module` so TS overload ordering reports per-route
+ * errors (see `formatDeclarationFile`).
  */
 function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): string[] {
   const lines: string[] = [];
-  const baseProps =
-    "Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }";
+  const baseProps = LINK_BASE_PROPS_TYPE;
 
   lines.push('  interface LinkFunction {');
   for (const route of routes) {
@@ -426,29 +514,49 @@ function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): st
     const searchParamsType = route.hasSearchParams
       ? formatSearchParamsType(route, importBase)
       : null;
-    const searchParamsProp = searchParamsType
-      ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
+    // TIM-830: the per-route pattern signature (href: '/products/[id]')
+    // uses a FLAT `Partial<T>` shape — the registry is keyed by the
+    // un-interpolated pattern, which matches `href` here exactly.
+    const patternSearchParamsProp = searchParamsType
+      ? `searchParams?: Partial<${searchParamsType}>`
       : 'searchParams?: never';
 
-    lines.push(`    (props: ${baseProps} & {`);
-    lines.push(`      href: '${route.urlPath}'`);
-    lines.push(`      ${paramsProp}`);
-    lines.push(`      ${searchParamsProp}`);
-    lines.push(`    }): import('react').JSX.Element`);
-
-    // For dynamic routes, also emit a resolved-pattern signature.
-    // This accepts template literal hrefs like `/products/${id}` without
-    // segmentParams — the params are already interpolated into the URL.
+    // TIM-832: For dynamic routes, emit the resolved-template signature
+    // FIRST and the pattern signature SECOND. The TS overload resolution
+    // order is top-to-bottom, and TS reports the error from the LAST
+    // overload tried on a failed call. For a user who passes the literal
+    // pattern href (`href="/products/[id]"`) and mistyped segmentParams,
+    // we want the PATTERN signature's error (which names the specific
+    // `segmentParams` shape like `{ id: string | number }`) to be the one
+    // TS reports — so the pattern must come LAST.
+    //
+    // TIM-830: the resolved-template signature keeps the legacy WRAPPED
+    // `{ definition, values }` shape. The runtime registry is keyed by
+    // the un-interpolated pattern (e.g. '/products/[id]'), so a flat
+    // lookup for an already-interpolated href like '/products/42' would
+    // fail. Flat values only work on the pattern signature below where
+    // `href` is the pattern itself. Callers using a resolved-template
+    // href must pass the definition inline, same as the external/
+    // computed catch-all signature.
     if (hasDynamicParams) {
       const templatePattern = buildResolvedPattern(route);
       if (templatePattern) {
+        const resolvedSearchParamsProp = searchParamsType
+          ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
+          : 'searchParams?: never';
         lines.push(`    (props: ${baseProps} & {`);
         lines.push(`      href: \`${templatePattern}\``);
         lines.push(`      segmentParams?: never`);
-        lines.push(`      ${searchParamsProp}`);
+        lines.push(`      ${resolvedSearchParamsProp}`);
         lines.push(`    }): import('react').JSX.Element`);
       }
     }
+
+    lines.push(`    (props: ${baseProps} & {`);
+    lines.push(`      href: '${route.urlPath}'`);
+    lines.push(`      ${paramsProp}`);
+    lines.push(`      ${patternSearchParamsProp}`);
+    lines.push(`    }): import('react').JSX.Element`);
   }
   lines.push('  }');
 

package/src/server/rsc-entry/index.ts

@@ -17,6 +17,11 @@
 
 // @ts-expect-error — virtual module provided by timber-routing plugin
 import routeManifest from 'virtual:timber-route-manifest';
+// TIM-830: Populate the search-params registry eagerly so <Link> can
+// serialize flat `Partial<T>` values synchronously in RSC renders.
+// The module has side effects only — no exports consumed here.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import 'virtual:timber-search-params-registry';
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
 // @ts-expect-error — virtual module provided by timber-build-manifest plugin

package/src/server/ssr-entry.ts

@@ -14,6 +14,10 @@
 
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
+// TIM-830: Populate the search-params registry eagerly so <Link> rendered
+// during SSR can serialize flat `Partial<T>` values via registry lookup.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import 'virtual:timber-search-params-registry';
 import {
   createFromReadableStream,
   createFromNodeStream,

package/LICENSE

@@ -1,8 +0,0 @@
-DONTFUCKINGUSE LICENSE
-
-Copyright (c) 2025 Daniel Saewitz
-
-This software may not be used, copied, modified, merged, published,
-distributed, sublicensed, or sold by anyone other than the copyright holder.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.