Repository navigation
Conversation
A page whose loader validates `query` with `defineHandler.withValidator({ query })`
now types both directions. `routeUrl()` and `router.visit()` check the keys, the
values, and required keys against that schema, and the page reads the parsed
values with `useQuery()`, so defaults and coercions match what the loader saw.
`PageQueryMap` keeps the schema's input and output apart: what a link may pass
differs from what the page reads. The query option types stay outside
route-url.ts on purpose. A page server reaches that module through `void`, so
reading a loader's inferred type back into it makes every loader reference itself
and infer as `any`.
|
👁️🗨️ Review this pull request with grouped, summarized diffs at: raw result💭 analyzed by {
"headSha": "74fd40c0442ae51a2844033c3035c9680da65379",
"result": {
"overallSummary": "Pages whose loader validates its query with `defineHandler.withValidator({ query })` now type navigation: `routeUrl()` and `router.visit()` reject unknown keys, wrong values and a missing required key, and a new `useQuery()` hook exposes the loader's validated (coerced/defaulted) query to the page.\n\nThe change is split into a type-generation half (`PageQueryMap`, kept in a separate module to avoid a loader/`route-url.ts` type cycle), a runtime half (the validated query is carried on the page payload so pages can read it), and per-framework `useQuery()` plumbing. Pages without a query schema keep accepting any `RouteQuery`.",
"groups": [
{
"key": "typed-navigation",
"label": "Typed query for links and navigation",
"summary": "Adds `PageQueryMap` (input/output per page, generated from each loader's validators) plus `PageQueryInput`/`PageQuery`, and threads it into `routeUrl()` options and the router's destination type. `RouteUrlArgs` becomes conditional so a page with a required query key forces the options argument, and `routeUrl`/`visit` now read the destination page's schema.",
"category": "core",
"filePaths": [
"packages/void/src/codegen/route-types.ts",
"packages/void/src/routes-stub.ts",
"packages/void/src/runtime/routing/route-navigation.ts",
"packages/void/src/runtime/routing/route-url.ts"
],
"fileNotes": [
{
"path": "packages/void/src/runtime/routing/route-navigation.ts",
"text": "`RouteQueryOptions` here re-implements the same conditional the generator emits into `.void/routes.d.ts` for `routeUrl()`. Two copies now have to stay in sync; only the placement (client-only module, to keep loaders out of a type cycle) justifies the duplication."
}
],
"lineNotes": [
{
"path": "packages/void/src/codegen/route-types.ts",
"side": "additions",
"line": 262,
"text": "`RouteUrlArgs` is now pushed twice into the same generated module: the schema-aware version near the top (`RouteOptions & RouteQueryOptions`) and this plain `RouteOptions` one. Duplicate type-alias declarations are a compile error, which `skipLibCheck: true` in the typecheck test can hide — check which declaration the generated file actually ends up using.",
"critical": true
}
]
},
{
"key": "page-payload-query",
"label": "Validated query on the page payload",
"summary": "Adds `query` to `PageObject`: the loader reads back `__voidValidatedInput` (stashed by `withValidator`) so the page payload carries the schema's output, falling back to raw request query values. The client router keeps that query as route state and exposes it through `_pageQuery`, including on SSR proxies and page-level facades.",
"category": "api",
"filePaths": [
"packages/void/src/pages/protocol.ts",
"packages/void/src/runtime/handler/index.ts",
"packages/void/src/pages/client.ts"
],
"fileNotes": [
{
"path": "packages/void/src/pages/protocol.ts",
"text": "`query` is a required field on `PageObject`, so any renderer outside this repo (custom adapters, the platform server updated here) must supply it; a payload that omits it degrades to `{}` at runtime via `?? {}` rather than failing loudly.",
"critical": true
},
{
"path": "packages/void/src/pages/client.ts",
"text": "`_pageQuery` follows the rendered page, not the address bar: it is set from `pageData.query` on commit and restored from the committed page when a commit fails, matching how params already behave."
}
],
"lineNotes": [
{
"path": "packages/void/src/pages/protocol.ts",
"side": "additions",
"line": 349,
"text": "A schema whose output is not a plain object (array, Date, transformed scalar) silently falls through to the raw request values, so `useQuery()`'s declared type and its runtime value can disagree in that case."
},
{
"path": "packages/void/src/runtime/handler/index.ts",
"side": "additions",
"line": 360,
"text": "`__voidValidatedInput` is stored for every validated handler, not just page loaders, so it also becomes readable from later middleware/handlers on the same request."
}
]
},
{
"key": "use-query-hooks",
"label": "useQuery() across frameworks",
"summary": "One identical `useQuery()` hook per framework, reading the router's `_pageQuery`, plus the wiring each integration needs: `createSsrRouter()` takes the page query, and the reactive routers keep a per-page query store updated on commit so the hook re-renders. The platform admin server now supplies the payload's new `query` field.",
"category": "ui",
"filePaths": [
"packages/react/src/runtime/use-query.ts",
"packages/react/src/runtime/index.ts",
"packages/react/src/runtime/pages-client.ts",
"packages/vue/src/runtime/use-query.ts",
"packages/vue/src/runtime/index.ts",
"packages/vue/src/plugin-pages.ts",
"packages/svelte/src/runtime/use-query.ts",
"packages/svelte/src/runtime/index.ts",
"packages/svelte/src/plugin-pages.ts",
"packages/solid/src/runtime/use-query.ts",
"packages/solid/src/runtime/index.ts",
"packages/solid/src/plugin-pages.ts",
"platform/packages/api/src/admin/react/server.ts"
],
"fileNotes": [
{
"path": "packages/react/src/runtime/pages-client.ts",
"text": "The page-level facade overrides `_pageQuery` with this resource's `pageData.query`, so `useQuery()` reads the page being rendered rather than the committed one; `routeQuery` is in the memo deps, which is what makes the value refresh."
}
],
"lineNotes": [
{
"path": "platform/packages/api/src/admin/react/server.ts",
"side": "additions",
"line": 25,
"text": "Built from `URLSearchParams` directly, so repeated keys collapse to the last value — different from `requestQuery()`'s array fallback for the same URL shape."
}
]
},
{
"key": "void-tests",
"label": "Type and runtime tests",
"summary": "Covers the new types in both directions (accepted links, unknown key, wrong value, missing required key, no-schema fallback), the generated `PageQueryMap` including the `.dev`/`.prod` union, and the runtime path from a coercing loader to the page payload.",
"category": "tests",
"filePaths": [
"packages/void/test/integration/page-query-types-typecheck.test.ts",
"packages/void/test/unit/page-query-types.typecheck.ts",
"packages/void/test/unit/route-types.test.ts",
"packages/void/test/unit/pages-protocol.test.ts",
"packages/void/test/unit/pages-client.test.ts",
"packages/void/test/unit/action-result.test.ts"
],
"fileNotes": [
{
"path": "packages/void/test/integration/page-query-types-typecheck.test.ts",
"text": "Runs `tsrs` over generated types in a temp project with `skipLibCheck: true`, so it proves inference from the loader but would not catch duplicate or conflicting declarations inside the generated `.d.ts` itself."
}
]
},
{
"key": "adapter-test-fixtures",
"label": "Adapter test fixtures",
"summary": "Mechanical updates to existing tests for the widened `VoidRouter` (`_pageQuery` stub) and the required `PageObject.query` field. No behaviour change.",
"category": "tests",
"filePaths": [
"packages/react/test/unit/link-prefetch.test.ts",
"packages/react/test/unit/use-form.test.ts",
"packages/react/test/unit/pages-server.test.ts",
"platform/packages/api/test/unit/admin-navigation-fallback.test.ts"
],
"fileNotes": [
{
"path": "packages/react/test/unit/pages-server.test.ts",
"text": "Each `pageObj` fixture gains `query: {}` because the payload field is required; the assertions are unchanged."
}
]
},
{
"key": "docs",
"label": "Docs",
"summary": "Documents the page query flow: the schema on the loader, what `routeUrl()`/`visit()` now reject, `useQuery()` with its fallback for pages without a schema, and the new `PageQueryMap`/`PageQueryInput`/`PageQuery` types — including the note that HTTP-handler routes are not checked.",
"category": "docs",
"filePaths": [
"docs/guide/type-safety.md",
"docs/reference/api/pages.md",
"docs/reference/api/types.md"
]
}
],
"schemaVersion": 1,
"source": "llm",
"generatedAt": "2026-11-22T03:44:58.489Z",
"model": "openai-compatible/opencode-go/deepseek-v4.1-flash",
"locale": "en"
}
} |
yangshun
left a comment
There was a problem hiding this comment.
I had Claude do a pass on the PR.
There was a problem hiding this comment.
I recommend renaming to usePageQuery instead.
useQuery() is commonly understood as a data fetching hook (TanStack Query, urql, Apollo, etc. use that name).
| ); | ||
| lines.push(' : string;'); | ||
| lines.push(' export type RouteUrlInput = Href | URL | RouteDestination;'); | ||
| lines.push(' export type RouteUrlArgs<P extends RoutePath> = {} extends RouteOptions<P>'); |
There was a problem hiding this comment.
This second export type RouteUrlArgs lands in the same declare module "void/routes" block as the one at line 212. Projects that don't set skipLibCheck get TS2300: Duplicate identifier 'RouteUrlArgs' from .void/routes.d.ts; tsc's default is false, and only void init sets it. The first declaration wins, which is why the type tests pass. The new integration test sets skipLibCheck: true, which hides the error. Suggest deleting lines 262–264 and running one route-types typecheck with skipLibCheck: false.
| lines.push(' } & ([RoutePathMap[P]] extends [never]'); | ||
| lines.push(' ? { params?: never }'); | ||
| lines.push(' : { params: { [K in RoutePathMap[P] & string]: string | number } });'); | ||
| lines.push(' export type RouteUrlArgs<P extends RoutePath> ='); |
There was a problem hiding this comment.
Putting RouteQueryOptions<P> in routeUrl's signature brings back the cycle that route-navigation.ts describes, because server code imports routeUrl from void/routes. A loader that builds a link to its own page needs its own type to check that call:
export const loader = defineHandler.withValidator({ query })((c, { query }) => ({
next: routeUrl('/payments', { query: { status: query.status, page: query.page + 1 } }),
}));tsc reports TS7022 ('loader' implicitly has type 'any'…) and TS7024. Without noImplicitAny, the loader, its props and PageQueryMap['/payments'] silently become any. Could the schema type come from something that doesn't depend on the loader's inferred return type, or could routeUrl leave PageQueryMap out? A test with a self-linking loader would cover this.
| lines.push(' } & ([RoutePathMap[P]] extends [never]'); | ||
| lines.push(' ? { params?: never }'); | ||
| lines.push(' : { params: { [K in RoutePathMap[P] & string]: string | number } });'); | ||
| lines.push(' export type RouteUrlArgs<P extends RoutePath> ='); |
There was a problem hiding this comment.
Because query is typed as RouteQuery & Input, RouteQuery's string index signature turns off excess-property checks. With an all-optional schema such as { status?: 'paid' | 'pending'; page?: number }, both routeUrl('/payments', { query: { statsu: 'paid' } }) and { status: 'paid', pgae: 2 } compile. The docs' statsu example only fails because status is required. router.visit() has no RouteQuery in its intersection and reports TS2561 for the same typo, so the two APIs disagree. Typing query from the schema input alone, as route-navigation.ts does, would fix both.
| lines.push(' } & ([RoutePathMap[P]] extends [never]'); | ||
| lines.push(' ? { params?: never }'); | ||
| lines.push(' : { params: { [K in RoutePathMap[P] & string]: string | number } });'); | ||
| lines.push(' export type RouteUrlArgs<P extends RoutePath> ='); |
There was a problem hiding this comment.
When a schema's input type for a key isn't a URL primitive, no value compiles for that key. Zod 3's z.coerce.date() has input Date, and RouteQuery & { since: Date } rejects both '2024-01-01' (not a Date) and new Date() (not a RouteQueryValue). If the key is required, the page can't be linked without a cast. Maybe map each input value to what a URL can carry, falling back to RouteQueryValue.
| } | ||
| // Page renders read the validated slots back, so `useQuery()` receives | ||
| // the same values the loader did, defaults and coercions included. | ||
| c.set('__voidValidatedInput', result.input); |
There was a problem hiding this comment.
Every withValidator call writes this slot, so the page gets whichever handler ran last. On a mutation re-render, the action runs first. If the GET loader isn't a withValidator handler, or there's no loader, the action's input stays in the slot. An action validating { query: z.object({ coupon: z.string().transform(lookupCoupon) }) } then becomes the page's useQuery() value, while PageQuery<'/checkout'> says Record<string, string | string[]>. Recording the validated query only around the page loader (for example in runLoader, cleared before the loader runs) would scope it to the loader.
| const engine = await createPageNavigationEngine(config); | ||
| let routeUrl = currentUrl(); | ||
| let routeParams = engine.initialPageData.params ?? {}; | ||
| let routeQuery = engine.initialPageData.query ?? {}; |
There was a problem hiding this comment.
With prerendered pages and static page data, pageData.query is the build request's query ({}), not the one in the address bar. The client loads the static JSON for /docs?tab=api, and the React facade even keeps tab=api in url through staticVisitQuery. So useRouter().query.get('tab') is 'api', but useQuery().tab is undefined. The docs say pages without a schema get "the request's query values". Either derive the no-schema fallback from the current URL on the client, or document what prerendered pages get.
|
|
||
| Static routes accept optional `query` and `hash` options. Pass raw parameter values for URL encoding. Catch-all parameters preserve `/` separators between segments. Invalid or missing path parameters throw a `TypeError`. | ||
|
|
||
| `PageQueryInput<P>` is `RouteQuery` unless the page at `P` validates its query, in which case it is that schema's input type. It also carries the required keys, so `query` cannot be omitted when the schema has one. See [Page query](../../guide/type-safety.md#page-query). |
There was a problem hiding this comment.
This documents routeUrl's query as PageQueryInput<P>, but the exported RouteOptions<P> and RouteDestination<P> still type query as RouteQuery. The schema only appears in the private RouteQueryOptions intersection. So const opts: RouteOptions<'/admin/payments'> = { query: { status: 'paid' } }; routeUrl('/admin/payments', opts) now fails, because an optional RouteQuery isn't the required schema query. Meanwhile c.redirect({ pathname: '/admin/payments', query: { statsu: 'x' } }) still compiles. Either fold the schema into the exported types, or document that they don't carry it.
| component, | ||
| props, | ||
| params: {}, | ||
| query: Object.fromEntries(new URLSearchParams(search)), |
There was a problem hiding this comment.
Nit: Object.fromEntries(new URLSearchParams(search)) keeps only the last value of a repeated key (?tag=a&tag=b → { tag: 'b' }), while requestQuery and the PageQuery fallback type use arrays ({ tag: ['a', 'b'] }). Grouping repeated keys the same way would keep admin pages consistent with other Void pages.
| props: {}, | ||
| url: '/', | ||
| params: {}, | ||
| query: {}, |
There was a problem hiding this comment.
This test now passes query, but renderReactPage drops it. pages-server.ts:76 still calls createSsrRouter(pageObj.url || '/', pageObj.params ?? {}, requestUrl), while Vue, Svelte and Solid now pass pageObj.query as the 4th argument. So useQuery() is {} during React SSR. A page rendering q.page.toFixed() throws on the server, and {q.status} renders empty and then mismatches on hydration. Passing pageObj.query ?? {}, plus an SSR case here that renders useQuery(), would fix it.
Related to #883
Description
A page loader that validates its query with
defineHandler.withValidator({ query })now types navigation.routeUrl()androuter.visit()reject a key outside that schema, a value outside it, and a missing required key. The page reads the same schema's output through a newuseQuery()hook.PageQueryMapkeeps the input and output sides apart, because what a link may pass and what the page reads stop being the same type once defaults or coercions are involved.The query option types sit outside
route-url.tsfor a reason. A page server reaches that file throughvoid, so reading a loader's inferred type from it makes the loader refer to itself, and TypeScript falls back toanyfor the whole handler.Pages without a query schema behave as before. Any
RouteQuerystill compiles, anduseQuery()returns the raw request values. A.dev/.prodpair unions its two schemas, the way page action bodies already merge.Links that pass a key the page does not declare now fail type checking.
as RouteQueryopts out.Still open
The issue also asks to "Support a functional update against the previous query so changing a filter can preserve the other filters and reset pagination". With
useQuery()that edit is{ ...query, status: 'paid', page: 1 }. A callback form needs a decision on what "previous" means when the destination is a different page, which is easier to settle on its own.Test
New cases cover the type checks in both directions, the required key error, the no-schema fallback, and the page payload carrying validated values.
Generated route types, type-checked with
tsrsin a temporary project. The first call is accepted, the next three are the errors:One runtime case: a loader that coerces
pageto a number serves/users?page=2&q=ada, and the page payload carries{ page: 2, q: 'ada' }. Without a query schema the payload carries{ tag: ['a', 'b'], q: 'ada' }for?tag=a&tag=b&q=ada.useQuery()adds no test of its own. It returns the router's page query, and the pages-client case asserts that value.