Skip to content

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

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

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

Conversation

@yangshun

@yangshun yangshun commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Issue

While using typedRoutes: true, I found that invalid routeUrl() produced non-helpful messages, like misleading argument-count errors or generic type mismatches.

This change adds diagnostics that identify the route, explain the problem, and suggest a correction.

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. Pass a registered route pattern as the first argument.
routeUrl('/users/[id]') Expected 2 arguments, but got 1. Missing param id for route /users/[id]. Pass it in { params: { ... } }.
routeUrl('/users/[id]', { params: { userId: 42 } }) Object literal may only specify known properties, and 'userId' does not exist in type… Unknown param userId for route /users/[id]. Use the parameter names in the route pattern.
routeUrl('/users/[id]', { params: { id: true } }) Type 'boolean' is not assignable to type 'string | number'. Param id for route /users/[id] must be a string or number.
routeUrl('/about', { params: { id: 42 } }) Type '{ id: number; }' is not assignable to type 'undefined'. Route /about has no path params. Remove params.

Also adds explanations for invalid query values, hash values, unknown options, and unchecked strings. Both generated and packaged declarations use the improved diagnostics, while preserving route/parameter autocomplete and required-parameter checks.

Valid calls retain the original argument types, including generic helpers, forwarding with a generic route path, and structural objects with additional fields. Generated URL declarations reference the SDK's canonical types through a stable internal types-only export, so SDK upgrades preserve route checking without regenerating .void/routes.d.ts. Reusable diagnostic helpers live in a private module. This prepares the shared types for a separate PR improving raw URL diagnostics.

Validation:

  • Added 20 diagnostic regression cases through both declaration paths.
  • Verified generic helpers, typed option/destination forwarding, structural objects, and typed argument wrappers, including Parameters<typeof routeUrl<P>> for generic route paths. All 30 invalid-call probes remain rejected in TypeScript 6 and 7 through both declaration paths.
  • Added regressions that switch pnpm-style SDK versions, remove the old version, and verify route checks with unchanged generated declarations and skipLibCheck: true.
  • Typechecking, lint, formatting, and editor autocomplete checks pass.
  • Full run: 17,509 tests passed; 35 skipped. Two Cloudflare cases hit an inspector-port collision; their file passed all 9 tests when rerun in isolation.
  • Full packed acceptance passes for React, Vue, Svelte, and Solid with both npm and pnpm.
  • CI passes all four pnpm framework apps, but its separate Vite+ fixture currently fails before typechecking: the CLI expects @voidzero-dev/vite-plus-core@8.3.8000 while the unchanged scaffold installs 1.6.0. Failed job.

@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

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