Typed URL state for the browser, the server and tests.

The problem

URL state shows up in the browser, on the server, in tests and in shared links. Most codebases describe it more than once: a client parser, a server parser, a serializer, and defaults repeated in each. Those copies drift apart.

One model, synced through adapters

QueryWeave defines query state once, as a model, and syncs it through adapters. Every environment runs the same pipeline: the query string is decoded, validated into typed state, updated, and written back in a canonical encoding.

import { createQueryRuntime, defineQueryModel, param } from '@queryweave/core'

const productFilters = defineQueryModel({
  search: param.text().optional(),
  page: param.integer({ min: 1 }).default(1),
  archived: param.boolean().default(false),
  sort: param.choice(['name', 'created_at', 'price']).default('created_at'),
  tags: param.list(param.text()).default([]),
})

const runtime = createQueryRuntime({ model: productFilters, adapter })

runtime.read().values.page // 1

await runtime.update({ search: 'vue', page: 1 })
await runtime.update({ page: 2 }, { navigation: 'replace' })

await runtime.transaction((draft) => {
  draft.search = 'vue'
  draft.page = 1
})

A broken link does not crash the page. ?page=abc decodes to page 1, and the result carries an issue explaining why, so the application can recover and tell the user.

Vue bindings

const filters = useQueryModel(productFilters)

filters.values.page // readonly reactive state
await filters.update({ page: 2 }) // explicit operation

const search = filters.field('search', { navigation: 'replace' }) // v-model target

There is no hook per key, no tuple setter, and no direct mutation as the primary API. Vue and Nuxt are the first frontend integrations, but neither shapes the core.

Nine packages

The budgets are enforced: pnpm bundle:size:check fails when a package grows past its limit.

Testing

The full gate runs every Vitest project, including Vitest Browser Mode and type-level assertions, real-browser tests in Chromium, Firefox and WebKit, and Playwright against the playground. Boundary checks cover sources, manifests and the dependency graph; artifact checks cover the built output and declaration resolution; and the packed archives are installed into clean consumer projects before a release.

The project is experimental and pre-1.0: the public API may change between minor versions, and every breaking change is recorded in an architecture decision record and a changeset.