Skip to content
QueryWeaveQueryWeave
Runtime
Framework

Adapters

An adapter connects a runtime to one environment. It reads the current query, writes canonical output, and reports external changes. That is the whole job.

The responsibility boundary

Section titled “The responsibility boundary”

An adapter never decodes, validates, applies defaults, or re-implements model semantics. If it did, the meaning of page=2 would have two definitions that could disagree — which is exactly the problem QueryWeave exists to remove.

interface QueryAdapter extends QuerySource {
  read(): QueryInput;
  push(next: QueryOutput): void | Promise<void>;
  replace(next: QueryOutput): void | Promise<void>;
  subscribe(listener: QueryChangeListener): () => void;
}

Two shapes, not one

Section titled “Two shapes, not one”

Some environments can navigate. Some only hand you a query once and then end. QueryWeave models that difference in the type system rather than by giving request-scoped code a push method that throws.

Mutable environment — reads, navigates, and notifies

Mutable environment — reads, navigates, and notifies

  1. QueryModel (meaning)
  2. QueryRuntime (transitions)
  3. QueryAdapter (synchronization)
  4. Browser, router, memory (environment)

QueryModel → QueryRuntime. QueryRuntime → QueryAdapter. QueryAdapter → Browser, router, memory.

A mutable environment implements the full QueryAdapter contract.

Request-scoped source — reads once, never navigates

Request-scoped source — reads once, never navigates

  1. Request (incoming)
  2. QuerySource (read-only)
  3. QueryModel.decode() (typed result)

Request → QuerySource. QuerySource → QueryModel.decode().

A request-scoped environment implements QuerySource — read, and nothing else.

QuerySource has one method. QueryAdapter extends it with push, replace, and subscribe. The server and Node packages produce sources; the browser, Vue Router, and memory packages produce adapters.

Where each one sits

Section titled “Where each one sits”

QueryWeave package dependency map. Core is the shared foundation. Node builds on the server package. Nuxt builds on the Vue and Vue Router packages.

  1. Nuxt integration — @queryweave/nuxt (Combines Vue bindings with a router adapter for each app)
  2. Node request bridge — @queryweave/node (Turns a Node.js request into a URL and reuses server helpers)
  3. Vue bindings — @queryweave/vue (Makes runtime state reactive and exposes named updates)
  4. Vue Router adapter — @queryweave/vue-router (Reads and changes the query through the router)
  5. Web server helpers — @queryweave/server (Reads a Request or URL and decodes it with a model)
  6. Browser adapter — @queryweave/browser (Reads and changes the URL with the History API)
  7. Memory adapter — @queryweave/testing (Simulates query navigation in tests)
  8. Validation bridge — @queryweave/standard-schema (Connects Standard Schema validators without choosing a vendor)
  9. Core engine — @queryweave/core (Defines query rules and owns decoding, encoding, and state updates)

Node request bridge → Web server helpers. Nuxt integration → Vue bindings. Nuxt integration → Vue Router adapter.

The core is the shared foundation for every package. The arrows show the extra package relationships: Node reuses the server helpers, while Nuxt combines the Vue bindings and Vue Router adapter.

Choosing

Section titled “Choosing”

Browser

@queryweave/browser

History API synchronization with push, replace, and popstate.

Runs in
Browser
Needs
No framework
pnpm add @queryweave/core @queryweave/browser

Server

@queryweave/server

Web-standard `Request` and `URL` helpers for request-scoped decoding.

Runs in
Any web-standard server, edge, or worker runtime
Needs
No framework
pnpm add @queryweave/core @queryweave/server

Node.js

@queryweave/node

Node request primitives bridged into the server helpers.

Runs in
Node.js
Needs
No framework
pnpm add @queryweave/core @queryweave/server @queryweave/node

Testing

@queryweave/testing

A deterministic memory adapter with its own back and forward stack.

Runs in
Any ECMAScript runtime
Needs
No framework
pnpm add -D @queryweave/testing

What every adapter page answers

Section titled “What every adapter page answers”

Each of the pages below states, in the same order: where it runs, what it owns, what it does not own, which package installs it, and when to reach for it.