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 generic or unspecialized argument tuples, and structural objects with additional fields. Parameters, .bind(), .call(), and .apply() retain the checked signature, while inferred invalid calls still receive the custom diagnostics. Explicit route type arguments stay constrained to registered patterns.

Generated URL declarations reference the SDK's canonical types through a stable internal types-only export, including under legacy Node module resolution, 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 27 diagnostic cases through both generated and packaged declarations, checked with TypeScript 6 and 7. These cover the original message examples, broad/optional param dictionaries, invalid query objects, and fallback diagnostics without UrlTypeError<never>.
  • Verified generic helpers, structural options, specialized and unspecialized Parameters forwarding, and valid/invalid .bind(), .call(), and .apply() calls. Widened explicit route types and invalid union, numeric, and symbol inputs remain rejected.
  • Legacy Node resolution retains route and raw URL checks with skipLibCheck on or off.
  • Upgrade regressions switch pnpm-style SDK versions, delete the old installation, and change the new SDK query contract while keeping generated declarations unchanged. The fixture copies only the required declaration graph.
  • All 35 typecheck tasks, scoped lint/format checks, and editor route/options/params completion checks pass.
  • Full local selection: 17,502 passed; 46 skipped, with deadline/performance failures in 11 unrelated files under heavy machine load. Those 11 files all pass with one worker and unchanged deadlines (303 tests), including the tests skipped by failed startup hooks in the full run.
  • All SDK and platform test jobs pass in CI, along with build/typecheck, lint, schema compatibility, and PostgreSQL concurrency. SDK run, platform run.
  • Before the rebase, full packed acceptance passed for React, Vue, Svelte, and Solid with both npm and pnpm in CI. The rebase includes main's Vite+ starter pairing fix; CI is rerunning on the updated branch.
  • After rebasing onto d6b8938ec, all 64 focused route/code-generation tests and all 35 typecheck tasks pass.

@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

Copy link
Copy Markdown
Collaborator Author

Still not ready for review yet. Might take a while more as I wanna be more thorough.

@yangshun
yangshun force-pushed the codex/improve-route-url-diagnostics branch from 371053e to 7e24fec Compare November 17, 2026 06:50

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