Migration
v1 to v2
Move from useRouteQuery and Zod schemas to codecs, useQueryState, and useQueryStates.
v2 is a new API. useRouteQuery and its Zod schemas are replaced by codecs that carry their own rules, and writes are batched across the whole app.
What changed
| v1 | v2 |
|---|---|
useRouteQuery({ key, schema: z.enum([...]), default }) | useQueryState(key, enumCodec([...], { default })) |
useRouteQuery({ schema: { a, b }, default: { a, b } }) | useQueryStates({ schema: { a: codec({ default }), b: codec({ default }) } }) |
key as a prefix for object schemas | prefix |
mode: 'push' | historyMode: 'push' in the codec options, or on the group |
Zod rules such as z.number().int().min(1) | Codec options: numberCodec({ int: true, min: 1 }) |
| A Zod object stored in one key | schemaCodec(z.object({ ... })), with any Standard Schema library |
Nested objects flattened as a.b.c | One level per group; use a prefix, or schemaCodec for a nested object |
nullable: true | Leave default out: the value can be undefined |
enabled, debug | Removed. Bad values are logged in development and listed in client.issues. |
| Writes from separate calls navigate separately | Every write in a tick is one navigation |
One value
- import { useRouteQuery } from '@chronicstone/vue-route-query'
- import { z } from 'zod'
+ import { enumCodec, useQueryState } from '@chronicstone/vue-route-query'
- const layout = useRouteQuery({
- key: 'layout',
- schema: z.enum(['table', 'grid']),
- default: 'table',
- })
+ const layout = useQueryState('layout', enumCodec(['table', 'grid'], { default: 'table' }))
An object
- const filters = useRouteQuery({
- key: 'filters',
- schema: { search: z.string(), status: z.array(z.string()) },
- default: { search: '', status: [] },
- })
+ const filters = useQueryStates({
+ prefix: 'filters',
+ schema: {
+ search: stringCodec({ default: '' }),
+ status: arrayCodec(stringCodec(), { default: [] }),
+ },
+ })
Array values change format. v1 wrote them as JSON, ?filters.status=["open","closed"], and arrayCodec writes ?filters.status=open,closed. If old links must keep working, keep the JSON format with a small codec:
const jsonListCodec = defineCodec<string[]>({
parse(raw) {
try {
const value: unknown = JSON.parse(raw)
if (Array.isArray(value)) {
return { ok: true, value: value.map(String) }
}
} catch {}
return { ok: false, issue: { reason: 'format', message: 'not a JSON list' } }
},
serialize: (value) => (value.length ? JSON.stringify(value) : null),
})
const status = jsonListCodec({ default: [] })
Install
npm install @chronicstone/vue-route-query@2
zod is no longer a peer dependency. Keep it only if you use schemaCodec with Zod, or for the rest of your app.