diff --git a/docs/guide/type-safety.md b/docs/guide/type-safety.md index 4f3de869e..17aa7937b 100644 --- a/docs/guide/type-safety.md +++ b/docs/guide/type-safety.md @@ -147,7 +147,7 @@ const url = routeUrl('/users/[id]', { // /users/42?tab=activity#details ``` -TypeScript checks the route and required parameter names. Patterns follow your filenames: `pages/users/[id].tsx`, `.vue`, or `.svelte` uses `/users/[id]`. +TypeScript checks the route, required parameter names, and the destination page's query schema. Patterns follow your filenames: `pages/users/[id].tsx`, `.vue`, or `.svelte` uses `/users/[id]`. Parameters accept strings or numbers and are URL-encoded for you. Query values can be strings, numbers, booleans, or arrays. Arrays become repeated keys; `null` and `undefined` values are omitted. @@ -241,6 +241,56 @@ import type { PageParams } from 'void/routes'; const { slug } = c.req.param() as PageParams<'/posts/[slug]'>; ``` +### Page query + +A loader can validate its query with `defineHandler.withValidator({ query })`. That schema types the page's links and its own reads. + +```ts +// pages/admin/payments.server.ts +import { defineHandler } from 'void'; +import { z } from 'zod'; + +const search = z.object({ + status: z.enum(['paid', 'pending']), + page: z.coerce.number().default(1), +}); + +export const loader = defineHandler.withValidator({ query: search })(async (c, { query }) => { + return { payments: await listPayments(query) }; +}); +``` + +`routeUrl()` checks its `query` against that schema. A key outside it, a value outside it, or a missing required key is a type error: + +```ts +import { routeUrl } from 'void/routes'; + +routeUrl('/admin/payments', { query: { status: 'paid' } }); +routeUrl('/admin/payments', { query: { statsu: 'paid' } }); // Type error: no such key +routeUrl('/admin/payments', { query: { status: 'void' } }); // Type error: not in the schema +routeUrl('/admin/payments'); // Type error: `status` is required +``` + +`router.visit()` takes the same destination object and applies the same checks. + +Read the values the loader validated with `useQuery()`. Pass the page pattern to type it. + +```ts +import { useQuery } from '@void/react'; // @void/vue, @void/svelte, @void/solid + +const query = useQuery<'/admin/payments'>(); +// { status: 'paid' | 'pending'; page: number } + +await router.visit({ + pathname: '/admin/payments', + query: { ...query, status: 'pending', page: 1 }, +}); +``` + +The result is typed by the schema's output, so a coerced `page` is a number here even though the URL only carries text. Spreading it into a navigation changes one filter and keeps the rest. + +A page without a query schema keeps accepting any `RouteQuery`, and `useQuery()` returns the request's query values as strings. Routes served by an HTTP handler are not checked, because one URL can serve several methods with different query schemas. + ### Prerender paths Annotate `getPrerenderPaths()` with `PageParams` to check that every path includes the page's required parameters: diff --git a/docs/reference/api/pages.md b/docs/reference/api/pages.md index 390670498..702b46695 100644 --- a/docs/reference/api/pages.md +++ b/docs/reference/api/pages.md @@ -103,6 +103,7 @@ Imported from `"@void/vue"`. | `Link` | Vue component for SPA navigation. Renders `` for GET, `