How do you serialize a screen's filters, sort and page into an address so a reload rebuilds the same view?

## The property to aim at The goal is a **faithful round trip in both directions**. Serialize the screen's state, reload, parse what the address says, and the user is looking at the same view; and serializing that parsed state again produces an identical address. When both hold, a reload, a bookmark, a copied link and a Back navigation all rebuild one screen, and the address is usable as a cache key or a metrics dimension. When either fails you get drifting links that look different but mean the same thing, or one link meaning two things on two days. ## Choosing a spelling per type An address is text, so every value needs an encoding decision made once and applied everywhere. | Value | Spelling that holds up | Why | |---|---|---| | Number, page | plain digits, e.g. `page=3` | shortest, obvious, trivially parsed | | Boolean toggle | an explicit word, e.g. `archived=true` | a bare key is ambiguous once a third state appears | | One choice from a small set | the option's stable name, not its index | readable in the link, and reordering the options later does not change meaning | | Several choices | the key repeated, e.g. `tag=new&tag=sale` | standard parsing returns them all, with no delimiter to escape inside values | | Date or timestamp | one fixed unambiguous format | locale-dependent formats are re-read differently by different readers | | Range | two keys, a low and a high | either end can be omitted independently | | Free text | the value, correctly escaped | reserved characters must survive being pasted | Two things to avoid: encoding a **derived** value the other parameters already imply, and encoding the screen's internal state object wholesale - that couples the address to a data shape which will change while the links do not. ## Defaults: omit them Every parameter needs a declared default, and the serializer should **write nothing when the current value equals it**. Three benefits arrive together: the shortest form of the address is the canonical view, links stay short enough to read and paste, and two users who never touched the filters generate one address instead of two long equivalent ones. The parser is the mirror image: a missing key yields the default, never an error. The subtle part is **absent versus present-but-empty**, and it has to be decided rather than discovered: - *Absent* means "the default applies". - *Present but empty* means "the user explicitly cleared this" - which matters whenever a default is non-empty, for example a status filter that defaults to open and that the user wants to widen to everything. - If a parameter has no non-empty default, collapse the two and always omit, so no address carries a value-less key. ## Canonical form Beyond omitting defaults, pin down the rest of the spelling so one state has exactly one generated address: - **Fixed key order** on output, so the string is stable and comparable. - **Fixed value order** inside a repeated key, usually sorted, so selecting two tags in either sequence yields one address. - **Consistent escaping** of reserved characters, applied by one shared helper rather than at each call site. - **Case and vocabulary settled** - one spelling per option name, chosen once, because users now see it. ## Reading is the other half Everything in the address arrives from outside: an old link, a hand-edited parameter, a stranger's paste buffer. So parsing needs a defined outcome for missing, unknown, malformed and out-of-range values - typically the default, and for a value the screen cannot interpret, the default plus a visible indication that the requested view was not fully reproducible. Never let an unparsable parameter render a screen that silently ignores what the link asked for while looking authoritative. ## Practical limits - **Length.** Browsers, servers and intermediaries each impose their own practical ceilings, so a growing set of selections eventually belongs behind a short reference rather than in the address itself. - **Churn.** Writing the address on every keystroke of a search box produces a stream of near-identical addresses; commit on a debounce or on submit instead. - **Stability.** Parameter names and option spellings are a contract, because links already sent cannot be edited. Choose names you can live with, and when one must change, keep reading the old spelling while writing only the new one. ## A test worth writing One property test covers most of this: take a representative state, serialize it, parse it, serialize it again, and assert both the state and the string match. Then add cases for an empty address, an address with defaults written out explicitly, an unknown key, and one malformed value. Those five assertions catch nearly every serialization defect before a user ever pastes a link.