QueryWeaveDocs
A type-safe URL state engineExperimental beta v0.1.0-beta.5

Give your URL
a type system.

Turn query strings into state you can trust. Define your model once. Decode, recover, and encode wherever your app runs.

Enter the URL lab View on GitHub
pnpm add @queryweave/core
From a messy URL to meaningful state
Raw query?search=vue&page=abc
defineQueryModel()decode · validate · recover
Typed state
{
  search: "vue",
  page: 1
}
string | undefined · number
Recovered with 1 issuepage=abc is invalid. Using 1.
Framework-independent by design.Follow the thread
The model

One definition.
No drift.

Your URL is part of your application’s state. Give it the same care as the rest of your types.

Meet the query model
model.tsTypeScript
import { defineQueryModel, param } from "@queryweave/core";

const model = defineQueryModel({
  search: param.text().optional(),
  page: param.integer({ min: 1 }).default(1),
});

const result = model.decode("?search=vue&page=abc");
result.ok === trueRecovered, with an issue.
Decode
Query strings become typed values. "2" becomes the number 2.
Recover
page=abc falls back to 1. The result includes an issue explaining why.
Encode
Defaults stay out of the URL. The recovered state becomes ?search=vue.
The URL lab

Go on. Break the query.

Change a value. Try a broken link. See exactly what the model keeps, recovers, and writes back.

Live input
Try a query

This model accepts search and page. A page must be an integer of at least 1.

Typed state

Recovered
{
  search: "vue",
  page: 1
}

Types from your model. Ready for your application.

1 issue reported

  • page · invalid"page" must be an integer.

Canonical query

?search=vue

Defaults are omitted. Only this model’s keys are encoded.

Running on @queryweave/core Same model. Actual results.

State moves.
The model stays.

Read a URL, change a value, write a link. The same definition keeps every step connected.

  1. 01

    Decode

    ?search=vue&page=abc

    Recover the invalid page to its default.

    {
  search: "vue",
  page: 1
}
  2. 02

    Update

    await runtime.update({ page: 2 })

    Apply a typed change through the runtime.

    {
  search: "vue",
  page: 2
}
  3. 03

    Encode

    ?search=vue&page=2

    The adapter handles navigation. The model handles the values.

    Explore the runtime
The ecosystem

One model.
Your environment.

Start with the core. Add the packages your application needs. Each integration shares the same model semantics.

Explore the architecture
@queryweave/coreOwns the domain vocabulary: parameters, codecs, models, decode results, issues, and the runtime.@queryweave/browserSynchronizes a runtime with the History API and reports popstate changes.@queryweave/serverDecodes and builds queries from web-standard Request and URL values.@queryweave/nodeResolves an absolute URL from a Node request and delegates decoding.@queryweave/standard-schemaTurns any Standard Schema validator into a QueryWeave refinement.@queryweave/vueBinds one model to Vue reactivity with readonly values and explicit operations.@queryweave/vue-routerTurns a Vue Router instance into an adapter, preserving path and hash.@queryweave/nuxtRegisters a request-scoped runtime plugin and the Vue auto-imports.@queryweave/testingProvides the memory adapter every other package is tested against.

Make your next link
a little smarter.

Start with a model. Let the URL carry the state.

Start weaving Explore the source

Experimental beta · v0.1.0-beta.5QueryWeave is pre-1.0 and is not production ready. Its API may change between minor versions. Read the stability policy.