Skip to content

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

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

yangshun wants to merge 6 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 generic helpers, structural objects with extra fields, and specialized or unspecialized Parameters forwarding. 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 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.

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 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.
  • 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 route tests: 70 passed. Affected tests: 592 files passed, 1 skipped.
  • Full suite: 822 files passed, 1 skipped; 17,576 tests passed, 35 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

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