Skip to content

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

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

yangshun wants to merge 7 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

With typedRoutes: true, an unknown route or a route called without its required options can produce a misleading argument-count error. This adds custom guidance for those cases and for unchecked string paths. Known routes with options retain TypeScript's native property and value errors, which show the required types directly.

Given /about and /users/[id], the relevant diagnostic excerpts change as follows:

Call Before After
routeUrl('/missing') Expected 2 arguments, but got 1. Unknown route: /missing. Use a registered route pattern.
routeUrl('/users/[id]') Expected 2 arguments, but got 1. Missing options for /users/[id]. Pass { params: { ... } } as the second argument.

Known-route option errors remain native. For example:

routeUrl('/blog/[category]/[slug]', { params: { category: 'typescript' } });
No overload matches this call.
  The last overload gave the following error.
    Property 'slug' is missing in type '{ category: string; }' but required in type '{ category: string | number; slug: string | number; }'.

The public routeUrl(path, options) API and valid-call contract are preserved, including callbacks for static routes, generic helpers, structural objects with extra fields, and specialized or unspecialized Parameters forwarding. Apps with dynamic routes still require options for paths typed as any. Parameters, .bind(), .call(), and .apply() keep the checked signature, and explicit route type arguments remain constrained to registered patterns. Route, option, and param autocomplete remain intact.

Generated URL declarations reference the installed SDK's canonical types through the stable void/_route-url-types export, including under Node16 CommonJS and legacy Node module resolution. This lets SDK type updates take effect without regenerating .void/routes.d.ts. The export's compatibility requirement is documented in the package maintainer guidance.

TypeScript's overload heading remains for calls with options. Generic path-only calls can still produce verbose conditional-type diagnostics. Raw URL diagnostics remain for a separate PR.

Detailed error examples

All 23 playground diagnostics

All 23 full compiler messages from TypeScript 7.0.2 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 '"/missing" & { readonly "Unknown route: /missing. Use a registered route pattern.": never; } & UrlErrorToken'. Type 'string' is not assignable to type '{ readonly "Unknown route: /missing. Use a registered route pattern.": never; }'.
Custom: unknown routes are explained even with options. routeUrl('/missing', { query: { page: 1 } }); TS2769 — No overload matches this call. The last overload gave the following error. Argument of type '"/missing"' is not assignable to parameter of type '"/missing" & { readonly "Unknown route: /missing. Use a registered route pattern.": never; } & UrlErrorToken'. Type 'string' is not assignable to type '{ readonly "Unknown route: /missing. Use a registered route pattern.": never; }'.
Custom: an unchecked string is too broad. routeUrl(uncheckedPath); TS2345 — Argument of type 'string' is not assignable to parameter of type 'string & { readonly "Expected a route pattern literal; string is too broad.": never; } & UrlErrorToken'. Type 'string' is not assignable to type '{ readonly "Expected a route pattern literal; string is too broad.": never; }'.
Custom: the required options argument is absent. routeUrl('/users/[id]'); TS2345 — Argument of type 'string' is not assignable to parameter of type '{ readonly "Missing options for /users/[id]. Pass { params: { ... } } as the second argument.": never; } & UrlErrorToken'. Type 'string' is not assignable to type '{ readonly "Missing options for /users/[id]. Pass { params: { ... } } as the second argument.": never; }'.
Native: options are present, but their required params are absent. routeUrl('/users/[id]', { query: { tab: 'activity' } }); TS2769 — No overload matches this call. The last overload gave the following error. 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: {} }); TS2769 — No overload matches this call. The last overload gave the following error. 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 } }); TS2769 — No overload matches this call. The last overload gave the following error. 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 } }); TS2769 — No overload matches this call. The last overload gave the following error. Type 'boolean' is not assignable to type 'string | number'.
Null cannot supply a required param. routeUrl('/users/[id]', { params: { id: null } }); TS2769 — No overload matches this call. The last overload gave the following error. 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' } }); TS2769 — No overload matches this call. The last overload gave the following error. 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 } }); TS2769 — No overload matches this call. The last overload gave the following error. Type '{ id: number; }' is not assignable to type 'undefined'.
Both params are required for this route. routeUrl('/blog/[category]/[slug]', { params: { category: 'typescript' } }); TS2769 — No overload matches this call. The last overload gave the following error. 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]'); TS2345 — Argument of type 'string' is not assignable to parameter of type '{ readonly "Missing options for /files/[...path]. Pass { params: { ... } } as the second argument.": never; } & UrlErrorToken'. Type 'string' is not assignable to type '{ readonly "Missing options for /files/[...path]. Pass { params: { ... } } as the second argument.": never; }'.
Catch-all params use strings or numbers too. routeUrl('/files/[...path]', { params: { path: false } }); TS2769 — No overload matches this call. The last overload gave the following error. Type 'boolean' is not assignable to type 'string | number'.
Params do not accept arrays. routeUrl('/users/[id]', { params: { id: [1, 2] } }); TS2769 — No overload matches this call. The last overload gave the following error. Type 'number[]' is not assignable to type 'string | number'.
Query values cannot be nested objects. routeUrl('/about', { query: { filter: { active: true } } }); TS2769 — No overload matches this call. The last overload gave the following error. 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' }] } }); TS2769 — No overload matches this call. The last overload gave the following error. Type '{ name: string; }' is not assignable to type 'RouteQueryValue'.
Hashes must be strings. routeUrl('/about', { hash: 123 }); TS2769 — No overload matches this call. The last overload gave the following error. Type 'number' is not assignable to type 'string'.
Unknown option names are checked. routeUrl('/about', { search: 'page=1' }); TS2769 — No overload matches this call. The last overload gave the following error. 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'); TS2769 — No overload matches this call. The last overload gave the following error. 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 }); TS2769 — No overload matches this call. The last overload gave the following error. 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 }); TS2769 — No overload matches this call. The last overload gave the following error. 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'.
Custom: generic paths may need an options argument. routeUrl(path); TS2769 — No overload matches this call. The last overload gave the following error. Argument of type 'P' is not assignable to parameter of type '[P] extends [RoutePath] ? UrlTypeError<`Missing options for ${RoutePathWithParams<NoInfer<P> & "/">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/about">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/blog/:category/:slug">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/blog/[category]/[slug]">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/files/:path{.+}">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/files/[...path]">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/users/:id">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/users/[id]">}. Pass { params: { ... } } as the second argument.`> & UrlErrorToken : P & UrlTypeError<UnknownRouteMessage<NoInfer<P>>> & UrlErrorToken'. Type 'RoutePath' is not assignable to type '[P] extends [RoutePath] ? UrlTypeError<`Missing options for ${RoutePathWithParams<NoInfer<P> & "/">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/about">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/blog/:category/:slug">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/blog/[category]/[slug]">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/files/:path{.+}">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/files/[...path]">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/users/:id">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/users/[id]">}. Pass { params: { ... } } as the second argument.`> & UrlErrorToken : P & UrlTypeError<UnknownRouteMessage<NoInfer<P>>> & UrlErrorToken'. Type '"/"' is not assignable to type '[P] extends [RoutePath] ? UrlTypeError<`Missing options for ${RoutePathWithParams<NoInfer<P> & "/">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/about">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/blog/:category/:slug">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/blog/[category]/[slug]">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/files/:path{.+}">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/files/[...path]">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/users/:id">}. Pass { params: { ... } } as the second argument.` | `Missing options for ${RoutePathWithParams<NoInfer<P> & "/users/[id]">}. Pass { params: { ... } } as the second argument.`> & UrlErrorToken : P & UrlTypeError<UnknownRouteMessage<NoInfer<P>>> & UrlErrorToken'.

Validation

  • 32 invalid-call diagnostic cases checked with TypeScript 6 and 7 through both generated and packaged declarations. Known-route errors are checked for native messages without custom diagnostic markers; the complete missing-slug diagnostic is checked on TypeScript 7.
  • Regressions cover static route callbacks, required options for any paths, generic params, structural extra fields, generic and unspecialized forwarding, function helpers, widened explicit route types, invalid query unions, numeric and symbol keys, exact optional properties, and attempts to pass diagnostic types as valid inputs.
  • Editor completion tests verify registered route patterns, exactly params/query/hash for options, and the correct param names.
  • Generated routes typecheck under Node16 CommonJS with skipLibCheck: false on TypeScript 6 and 7. Legacy Node resolution retains route checks with skipLibCheck on or off. Upgrade regressions change the installed SDK query contract and remove the old installation while keeping generated declarations unchanged.
  • Formatting, scoped lint, and all 35 package typecheck tasks pass.
  • Focused routing tests passed (85). The affected suites passed in 593 files with 1 skipped.
  • The full suite passed in 822 files with 1 skipped. 17,578 tests passed and 35 were skipped.

The ad-hoc diagnostics playground and its generated reports are gitignored and are not included in this PR.

@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.

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