View-state query codec
State: open/verified · Kind: module · Audience: system
Summary
Section titled “Summary”- Diffs a view-state object against its defaults and encodes only what differs into a short, readable, dependency-free query string, reusable across host apps.
- The defaults object doubles as the schema, so callers declare no separate shape for their view state.
Statement
Section titled “Statement”spec-query gives an app with many view options — filters, layout toggles, search terms — one input (its defaults) and a codec derived from it, instead of a hand-written encoder/parser per option. diff/merge work at the value level so only the difference from defaults is stored or shared. encodeEntries/decodeEntries flatten that diff to raw key/value pairs for a host (e.g. a router) that owns its own percent-encoding. encode/decode escape those pairs into one query string, using only encodeURIComponent/decodeURIComponent so it runs in a browser, bun, or node with no DOM dependency.
What it provides
Section titled “What it provides”- diff/merge — recursive minimal diff against a defaults object and its inverse
- encodeEntries/decodeEntries — diff as raw query pairs for a router that owns escaping
- encode/decode — diff as one escaped, hand-editable query string; decode never throws
- specQueryKeys — the dotted keys the codec owns, to split a host’s query into codec- and host-owned halves
Underlying implementation
Section titled “Underlying implementation”- packages/ts/spec-query/index.ts
- consumed by solutions/ontological/experiences/system-graph/app/lib/view-query.ts and saved-view.ts (System page shareable-view links)
- consumed by solutions/determined/apps/vault-graph/lib/spec-io.ts
Locations
Section titled “Locations”packages/ts/spec-query/