Validation
A URL is user input: people edit links, old links outlive your code, and anyone can paste anything. Every key goes through its codec's rules before your code sees it.
Rules on a key
Each codec takes the rules that make sense for its type, next to its default:
const filters = useQueryStates({
schema: {
search: stringCodec({ trim: true, maxLength: 80 }),
page: numberCodec({ default: 1, int: true, min: 1 }),
pageSize: numberCodec({
default: 20,
int: true,
min: 10,
max: 100,
outOfRange: 'clamp',
}),
salary: numberCodec({ min: 0, validate: (amount) => amount % 1000 === 0 }),
from: dateCodec({ format: 'date', min: new Date('2020-01-01') }),
status: arrayCodec(enumCodec(['open', 'closed', 'draft']), {
default: [],
invalidItems: 'drop',
}),
},
})
| Codec | Rules |
|---|---|
stringCodec | trim, minLength, maxLength, pattern |
numberCodec | int, min, max, outOfRange |
dateCodec | min, max, outOfRange |
enumCodec | the list of values |
arrayCodec | the item codec's rules, minItems, maxItems, unique, invalidItems |
every codec except schemaCodec | validate: (value) => boolean for a one-off rule |
What happens to a bad value
| The URL holds | The ref holds |
|---|---|
| No key | The default, or undefined without one |
A value in the wrong format (?page=abc) | The default |
A value that breaks a rule (?page=0 with min: 1) | The default |
A value out of range with outOfRange: 'clamp' (?pageSize=500) | The nearest bound (100) |
A list with one bad item (?status=open,bogus) | The default, or the valid items with invalidItems: 'drop' |
The URL is never rewritten on read. ?page=0 stays in the address bar until the next write to that key. Rewriting on read would turn a page load into a navigation, add or replace a history entry, and race with the user's own changes. The next write cleans the key anyway.
Writes follow the same rules. page.value = 0 stores 1 and removes the key; pageSize.value = 500 stores 100. The ref never holds a value a reload would reject.
Cross-field rules
Some rules span keys: a minimum below a maximum, a start date before an end date. Declare them on useQueryStates with a name, the keys they read, and the keys they reject:
const filters = useQueryStates({
schema: {
salaryMin: numberCodec({ min: 0 }),
salaryMax: numberCodec({ min: 0 }),
from: dateCodec({ format: 'date' }),
to: dateCodec({ format: 'date' }),
},
rules: {
salaryRange: {
keys: ['salaryMin', 'salaryMax'],
check: ({ salaryMin, salaryMax }) => salaryMin <= salaryMax,
reject: ['salaryMax'],
message: 'The maximum salary is below the minimum',
},
period: {
keys: ['from', 'to'],
check: ({ from, to }) => from <= to,
reject: ['to'],
},
},
})
// ?salaryMin=50000&salaryMax=40000 → salaryMin: 50000, salaryMax: undefined
checkgets typed values, neverundefined: a rule is skipped until every key it reads has a value.- When
checkreturnsfalse, only the keys inrejectfall back to their defaults. The others keep their values. - Rules run in the order they are declared.
- Rules run when the URL is read: on page load, on reload, on Back, and on a shared link. A write from your code is kept as it is, so a form never clears a field while the user is typing. Show the conflict from
issuesinstead.
See what a link got wrong
The client keeps a reactive map of every key whose URL value was rejected or only partly used, with the raw value, the reason, and partial: true when part of the value was kept (a list that dropped an item):
const client = useQueryStateClient()
// { raw: '40000', reason: 'group', rule: 'salaryRange', message: '...' }
client.issues.get('salaryMax')
const invalidFilters = computed(() => [...client.issues.keys()])
Use it to show "this link had invalid filters", or to point at the field. In development, each bad value is also logged once in the console.
reason | Meaning |
|---|---|
format | Not a number, a date, a list member, or JSON. |
option | A built-in rule rejected it (min, int, maxLength...). |
validate | The codec's validate returned false, or a schemaCodec schema reported issues. |
group | A cross-field rule rejected it. rule holds its name. |