Skip to content

fix(routes): improve routeUrl TypeScript diagnostics - #861

Draft
yangshun wants to merge 13 commits into
voidzero-dev:mainfrom
yangshun:codex/improve-route-url-diagnostics
Draft

yangshun wants to merge 13 commits into
voidzero-dev:mainfrom
yangshun:codex/improve-route-url-diagnostics

Conversation

@yangshun

@yangshun yangshun commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Problem and behavior

When an app has static and dynamic routes, routeUrl('/missing') can report an argument-count error. Unknown route literals now get a diagnostic on the path argument that names the unregistered pattern.

Call Before After
routeUrl('/missing') Expected 2 arguments, but got 1. Argument of type '"/missing"' is not assignable to parameter of type '"Unknown route: /missing. Use a registered route pattern." & UrlErrorToken'.
routeUrl('/missing', {}) Argument of type '"/missing"' is not assignable to parameter of type 'RoutePath'. Argument of type '"/missing"' is not assignable to parameter of type '"Unknown route: /missing. Use a registered route pattern." & UrlErrorToken'.

Known routes use TypeScript's native diagnostics. Calling routeUrl('/users/[id]') without options reports “Expected 2 arguments, but got 1.” A params object missing slug reports the required property directly.

routeUrl('/blog/[category]/[slug]', { params: { category: 'typescript' } });
Property 'slug' is missing in type '{ category: string; }' but required in type '{ category: string | number; slug: string | number; }'.

A single signature with a positional path preserves inference for generic wrappers and currying helpers, including helpers whose path is typed P & RoutePath or P | '/about'. Forwarding with Parameters, passing structural options, and using .bind(), .call(), and .apply() keep their checks. Unknown routes are also rejected where TypeScript compares parameters bivariantly: method signatures, implements, and projects without strictFunctionTypes. As on the base branch, TypeScript allows assigning the unspecialized builder to a one-argument callback type for a dynamic route. Direct calls and a builder specialized as routeUrl<'/users/[id]'> require options.

Functions written to match typeof routeUrl, such as mocks, test doubles, and class members, still compile when they type the path as RoutePath, string, or a generic P extends RoutePath. The URL helper types that generated declarations exported from void/routes on main, such as TypedRoutes and RoutePathUrl, remain importable.

The path check stays within TypeScript's union-size and relation-complexity limits (TS2590 and TS2859), which earlier revisions of this PR exceeded in apps with ~316 and ~1,400 route keys. An app with about 1,800 route keys type-checks in under 0.2 s with tsrs and TypeScript 7.0.2, and in about 0.4 s with TypeScript 6.0.3.

Generated URL declarations reference the installed SDK's canonical types through the stable void/_route-url-types export. SDK type updates take effect without regenerating .void/routes.d.ts, including in apps using Node16 CommonJS or legacy Node module resolution. The maintainer guidance documents the export's compatibility requirement.

Differences from main

The compatibility audit found four intended differences:

  • In an app with no routes, every path is unknown. Assigning routeUrl to a method or function type whose parameter is a path literal now fails. On main it compiled because TypeScript compared the method's parameters bivariantly.
  • routeUrl has a second type parameter, so routeUrl<'/about', '/about'>(...) now compiles. Calls with one type argument behave as before.
  • Packaged declarations now give the same results as generated declarations. On main, package-mode imports saw both routeUrl declarations.
  • A generic function assigned to typeof routeUrl that types its options as RouteOptions<P> with its own P, as in <P extends RoutePath>(path: P, options?: RouteOptions<P>) => ..., no longer compiles. routeUrl derives its options from the path as written, so an unknown route gets the path error, and that type differs from the path parameter's. Implementations with other option types, including RouteOptions<RoutePath>, and contextually typed ones such as (path, ...options) => routeUrl(path, ...options) still compile.

Detailed error examples

All 23 playground diagnostics

All 23 full compiler messages from tsrs 7.1.0-beta.tsrs2 and TypeScript 7.0.2 (identical) with --noErrorTruncation. Line breaks are folded into spaces for the table.

What it tests Call Full error message
Custom: an unknown route gets route-pattern guidance. routeUrl('/missing'); TS2345 — Argument of type '"/missing"' is not assignable to parameter of type '"Unknown route: /missing. Use a registered route pattern." & UrlErrorToken'. Type '"/missing"' is not assignable to type '"Unknown route: /missing. Use a registered route pattern."'.
Custom: unknown routes are explained even with options. routeUrl('/missing', { query: { page: 1 } }); TS2345 — Argument of type '"/missing"' is not assignable to parameter of type '"Unknown route: /missing. Use a registered route pattern." & UrlErrorToken'. Type '"/missing"' is not assignable to type '"Unknown route: /missing. Use a registered route pattern."'.
Native: an unchecked string is too broad. routeUrl(uncheckedPath, {}); TS2345 — Argument of type 'string' is not assignable to parameter of type 'RoutePath'.
Native: the required options argument is absent. routeUrl('/users/[id]'); TS2554 — Expected 2 arguments, but got 1.
Native: options are present, but their required params are absent. routeUrl('/users/[id]', { query: { tab: 'activity' } }); TS2345 — Argument of type '{ query: { tab: string; }; }' is not assignable to parameter of type 'RouteOptions<"/users/[id]">'. Property 'params' is missing in type '{ query: { tab: string; }; }' but required in type '{ params: { id: string | number; }; }'.
The params object is missing id. routeUrl('/users/[id]', { params: {} }); TS2741 — Property 'id' is missing in type '{}' but required in type '{ id: string | number; }'.
Native: the params object has an unknown property. routeUrl('/users/[id]', { params: { userId: 42 } }); TS2353 — Object literal may only specify known properties, and 'userId' does not exist in type '{ id: string | number; }'.
Boolean params are rejected. routeUrl('/users/[id]', { params: { id: true } }); TS2322 — Type 'boolean' is not assignable to type 'string | number'.
Null cannot supply a required param. routeUrl('/users/[id]', { params: { id: null } }); TS2322 — Type 'null' is not assignable to type 'string | number'.
Extra fields on a fresh params literal are checked. routeUrl('/users/[id]', { params: { id: 42, extra: 'x' } }); TS2353 — Object literal may only specify known properties, and 'extra' does not exist in type '{ id: string | number; }'.
Static routes have no path params. routeUrl('/about', { params: { id: 42 } }); TS2322 — Type '{ id: number; }' is not assignable to type 'undefined'.
Both params are required for this route. routeUrl('/blog/[category]/[slug]', { params: { category: 'typescript' } }); TS2741 — Property 'slug' is missing in type '{ category: string; }' but required in type '{ category: string | number; slug: string | number; }'.
Catch-all routes also require their param. routeUrl('/files/[...path]'); TS2554 — Expected 2 arguments, but got 1.
Catch-all params use strings or numbers too. routeUrl('/files/[...path]', { params: { path: false } }); TS2322 — Type 'boolean' is not assignable to type 'string | number'.
Params do not accept arrays. routeUrl('/users/[id]', { params: { id: [1, 2] } }); TS2322 — Type 'number[]' is not assignable to type 'string | number'.
Query values cannot be nested objects. routeUrl('/about', { query: { filter: { active: true } } }); TS2353 — Object literal may only specify known properties, and 'active' does not exist in type 'readonly RouteQueryValue[]'.
Query arrays cannot contain objects. routeUrl('/about', { query: { tags: [{ name: 'typescript' }] } }); TS2322 — Type '{ name: string; }' is not assignable to type 'RouteQueryValue'.
Hashes must be strings. routeUrl('/about', { hash: 123 }); TS2322 — Type 'number' is not assignable to type 'string'.
Unknown option names are checked. routeUrl('/about', { search: 'page=1' }); TS2353 — Object literal may only specify known properties, and 'search' does not exist in type 'RouteOptions<"/about">'.
Options must be an object. routeUrl('/about', 'page=1'); TS2559 — Type '"page=1"' has no properties in common with type 'RouteOptions<"/about">'.
A broad params record does not guarantee that id exists. routeUrl('/users/[id]', { params: uncheckedParams }); TS2741 — Property 'id' is missing in type 'Record<string, string>' but required in type '{ id: string | number; }'.
Every member of a query union must be valid. routeUrl('/about', { query }); TS2322 — Type '{ page: number; } | { filter: { active: boolean; }; }' is not assignable to type 'RouteQuery | undefined'. Type '{ filter: { active: boolean; }; }' is not assignable to type 'RouteQuery'. Property 'filter' is incompatible with index signature. Type '{ active: boolean; }' is not assignable to type 'readonly RouteQueryValue[] | RouteQueryValue'.
A generic path can include routes that need options. return routeUrl(path); TS2345 — Argument of type '[]' is not assignable to parameter of type '[RoutePathMap[NoInfer<P>]] extends [never] ? [options?: RouteOptions<P> | undefined] : [options: RouteOptions<P>]'.

Validation

  • Regression tests run with tsrs 7.1.0-beta.tsrs2 (the repository's compiler), TypeScript 7.0.2, and TypeScript 6.0.3, against both generated and packaged declarations. They cover functions implementing typeof routeUrl (mocks, class members, satisfies, and default parameters), importing the URL helper types from void/routes, generic options subtypes, wrapper and curry inference, generic P & RoutePath and P | '/about' paths, bivariant method and callback assignments with and without strictFunctionTypes, an app with about 1,800 route keys, declaration emit and consumption, static-only function helpers, and explicit type arguments.
  • Diagnostic tests check that unknown-route errors quote the path the caller wrote, and that known routes keep native option errors. Editor completion tests check paths, option names, and route-specific params.
  • The compatibility audit compared 869 call, assignment, implementation, helper-type, and declaration-emit cases with main across 208 TypeScript 7 and 6 configurations and 100 tsrs configurations, including two large generated apps. Differences are limited to the ones listed above. tsrs and TypeScript 7.0.2 agree on pass or fail and on error codes for all 77,520 case results. The URL builder emits the same JavaScript as main.
  • Generated route tests cover Node16 CommonJS, legacy Node resolution with skipLibCheck on and off, and an SDK upgrade with existing generated declarations.
  • vpr test:all after merging main passed formatting, lint, tsrs type checks across the workspace, and the platform and unit test groups (16,657 tests). In the integration group, 1,357 tests passed and the Astro PostgreSQL suite timed out waiting for its dev server on a loaded machine; rerunning that file passed all 8 tests. The 107 focused routing tests pass with all three compilers.

The diagnostics playground and reports are local and gitignored.

🤖 Generated with Claude Code

@cpojer cpojer left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Holy shit this is sick!

@cpojer cpojer left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Three issues, here is some slop:

  • Generic helpers stop compiling. A helper whose id is T extends string | number can no longer call routeUrl('/users/[id]', { params: { id } }). Forwarding typed options also breaks. Preserve the valid-call signature while adding diagnostic fallbacks. Signature
  • Valid objects with additional fields are rejected. Passing const user = { id: 42, name: 'Alice' } as params now errors on name; passing a RouteDestination as options also fails. These previously compiled and work at runtime. Preserve structural assignability. Validation
  • Invalid inputs can now bypass validation. A query typed { q: string } | { filter: { id: number } } compiles and serializes the object as [object Object]. Numeric param keys can also hide a missing required id, producing a runtime exception. Validate every union branch and avoid dropping numeric keys. Error calculation

@yangshun

Copy link
Copy Markdown
Collaborator Author

Thanks I'll look into them.

@yangshun
yangshun marked this pull request as draft November 17, 2026 03:14
@yangshun
yangshun marked this pull request as ready for review November 17, 2026 04:18
@yangshun
yangshun requested a review from a team as a code owner November 17, 2026 04:18
@yangshun
yangshun requested a review from cpojer November 17, 2026 04:18
@yangshun
yangshun marked this pull request as draft November 17, 2026 04:40
@cpojer

cpojer commented Nov 17, 2026

Copy link
Copy Markdown
Member

Some more issues as these calls compile now but throw at runtime:

const userUrl = routeUrl.bind(undefined, '/users/[id]');
userUrl();                        // Missing required id
userUrl({ params: { id: true } }); // Invalid id type

.call() and .apply() have the same gap. forwarding Parameters<typeof routeUrl> also stops compiling:

function forward(...args: Parameters<typeof routeUrl>) {
  return routeUrl(...args);
}

@yangshun

Copy link
Copy Markdown
Collaborator Author

Thanks, doing more rounds of reviews and need to do more thorough testing

@yangshun
yangshun force-pushed the codex/improve-route-url-diagnostics branch from 371053e to 7e24fec Compare November 17, 2026 06:50
@yangshun
yangshun marked this pull request as ready for review November 17, 2026 10:47
@yangshun

yangshun commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator Author

EDIT: Not yet ready. Overzealous AI went to mark it as ready and anyhow wrote a bunch of comments.

@yangshun
yangshun marked this pull request as draft November 17, 2026 11:01
Preserve required options for paths typed as any. Keep routeUrl diagnostics and function helper types while making generated route types compatible with Node16 CommonJS projects.
@yangshun
yangshun marked this pull request as ready for review November 18, 2026 09:06
@yangshun

Copy link
Copy Markdown
Collaborator Author

Ready for review. Please see the "Detailed error examples" section for examples of how the errors will look like now.

I think there's a limit to how short the error messages can be, I tried to balance length and usefulness.

@cpojer

cpojer commented Nov 18, 2026

Copy link
Copy Markdown
Member

One more issue: A generic wrapper loses per-route inference when you pass routeUrl through a logging helper that forwards (...args: A) => R. On main both wrapped('/about') and wrapped('/users/[id]', { params: { id: 42 } }) compile. The new overload in this PR makes it so the static route reuqires options and the user route requires params from unrelated routes.

@yangshun
yangshun marked this pull request as draft November 19, 2026 03:54
yangshun and others added 4 commits November 19, 2026 11:54
Infer P and Candidate from the whole path argument so generic helpers such as `P & RoutePath` keep compiling. Keep the unknown-route marker from being a subtype of the path, so method signatures and code without strictFunctionTypes still reject unknown routes. Bound Candidate by plain string to avoid TS2590 in apps with more than ~316 route keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Infer the route candidate through a template literal, so only string literals produce one and generic paths such as `P & RoutePath` resolve like a plain parameter. This avoids TS2859 in apps with more than ~1,400 route keys. Keep P whole when every candidate is a known route, so paths such as `P | '/about'` still compile.

Spell the unknown-route marker as a string literal. TypeScript then prints the argument as the path the caller wrote instead of `string`, and the marker still rejects unknown routes in bivariant parameter checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Main type-checks test fixtures with tsrs. Keep the routeUrl tests' compiler matrix and add tsrs as its default entry, alongside TypeScript 7 and 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The diagnostics test parses `file(line,col): error` lines. Under FORCE_COLOR, which `vp run` sets for tests, TypeScript 7 and tsrs print pretty diagnostics even when tsconfig sets `pretty: false`, so pass `--pretty false` on the command line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Functions written to match `typeof routeUrl` with a `RoutePath` or generic
path parameter, such as mocks and class members, stopped compiling: TypeScript
could not show that the unknown-route marker is a route. Distribute the marker
over the written path so its constraint reduces to `P`.

Generated route declarations on main also exported the URL helper types
(`TypedRoutes`, `RoutePathUrl` and others) from `void/routes`. Re-export them
from the SDK.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants