URL state as a domain

A query string is an untyped, externally supplied, user-editable value that your application must treat as state. QueryWeave gives that value a domain vocabulary so each concern has exactly one home.

The vocabulary

Concept	Owns	Never does
QueryParam	One named value: its type, presence, default, and constraints	Read the environment
QueryCodec	Both directions of translation for one value	Navigate or touch globals
QueryModel	A complete query state composed from parameters	Know where the query came from
DecodeResult	Whether a decode produced a usable whole, plus issues	Throw
QueryRuntime	Transitions from current state to next state	Parse or validate
QueryAdapter	Reading, writing, and observing one environment	Decode, validate, apply defaults
QuerySource	Reading one request-scoped query	Navigate

The separation is the point. A codec that could navigate would put policy in a place that is supposed to be pure; an adapter that could decode would give you two sources of truth for what page=2 means.

The path a value takes

The path a query takes through the model, stage by stage.

1. Raw query — ?search=vue&page=2
2. decode()
3. Typed state — { search: "vue", page: 2 }
4. encode()
5. Canonical query — search=vue&page=2

Raw query → decode(). decode() → Typed state. Typed state → encode(). encode() → Canonical query.

Decoding and encoding are the same description read in two directions.

Written out:

1. Raw input arrives as a string, an iterable of entries, or a plain object.
2. The model decodes it by asking each parameter’s codec for a value, collecting issues.
3. Refinements run, if any, turning validator errors into QueryWeave issues.
4. A result is produced — either a complete typed value, or partial values plus issues.
5. A transition changes that state, in a runtime.
6. The model encodes it into canonical entries, omitting anything equal to its default.
7. An adapter writes the result to the environment and reports the change back.

Steps 1 to 4 and step 6 are pure. Steps 5 and 7 are the only ones that know about an environment.

Reading order

Query modelsComposing parameters into one typed state.ParametersThe seven families, and how presence works.CodecsBoth directions under one contract.Decoding and encodingResults, canonical form, and normalization.Defaults and absenceWhy an absent key and a default value are the same thing.Issues and recoveryWhat happens when the outside world sends nonsense.