ReviewOS

stacks/stx

useSearchParams mutators always pushState — no way to consume a one-shot param (Back replays the OAuth callback)

#1825
Closed glennmichael123 opened this 22 days ago · 1 comment
22 days ago

Following #1807 — useSearchParams() now has delete/setAll/data, which covers the read/write gap. But every mutator commits through the same helper:

const commit = (url: URL) => {
  window.history.pushState({}, '', url)
  sync()
}

use-router.ts:181-184, used by set, delete, and setAll alike. There is no way to replace the current entry instead of pushing a new one.

Why that blocks the common case

The canonical reason to delete a search param is to consume a one-shot value — an OAuth callback result, a ?checkout=success, a flash token. The whole point is that it must not survive a refresh or a Back press.

With pushState, deleting the param leaves the pre-delete URL — the one with the param — as the previous history entry. Pressing Back replays the callback: the page re-reads the param and re-runs whatever consuming it triggered (re-showing a success toast at best, re-submitting at worst).

So the composable can express "remove this param from the URL" but not "remove this param so it's gone", which is the reason the API gets reached for.

Concrete case

Postline's accounts page consumes four OAuth provider callbacks. Each one reads its param, then strips it:

window.history.replaceState({}, '', `${route.path}${query ? `?${query}` : ''}`)

I went to replace that with useSearchParams().delete(provider) as part of removing vanilla window.* from views, and had to keep the raw call — swapping it in would introduce the Back-replay bug above. That's the one remaining window.history use in the app.

Suggested fix

An options bag on the mutators, defaulting to today's behaviour:

delete: (key: string, options?: { replace?: boolean }) => void
set:    (key: string, value: string, options?: { replace?: boolean }) => void
setAll: (obj: Record<string, string>, options?: { replace?: boolean }) => void

with commit choosing replaceState vs pushState accordingly. Non-breaking, and it lines up with navigate(), which already takes { replace } after #1808 — right now the two halves of the routing API disagree on whether replacing is expressible.

Docs point worth pairing with it: the current doc comments say "and push to history" on each mutator, which is accurate but reads as incidental. Whichever way it lands, it's worth stating that consuming a one-shot param needs replace semantics.

22 days ago

Fixed in 40f9215b22.

set, delete and setAll now take an optional { replace?: boolean }, exactly as proposed. Default unchanged, so nothing that works today changes.

All three surfaces moved together — the client runtime (signals.ts), the module export (composables/use-router.ts, including its own non-delegating path), and the ambient declaration (stx.d.ts) — since those have drifted apart before.

The guard is stricter than it looks, on purpose

An adversarial review of my first attempt caught two real bugs in it, both worth recording:

A truthy property read is wrong here. options && options.replace asks whether the value has a replace property — and every string carries String.prototype.replace. So delete('code', 'push') replaced, the exact opposite of what it reads as.

Optional chaining diverged between the two implementations. options?.replace only short-circuits on null/undefined, so for options === '' the module hit String.prototype.replace and replaced while the runtime short-circuited and pushed. Same call, two entry points, opposite history semantics — in a change whose whole contract is that the implementations agree.

Both now use !!(options && typeof options === 'object' && options.replace), identically.

Verified in a browser, not just in tests

Arriving at /login?code=abc123 and consuming the param, against the rebuilt dist:

callBack lands on
delete('code')?code=abc123replayed — the bug
delete('code', { replace: true })(no query)not replayed
delete('code', 'push')?code=abc123pushes, as it reads
delete('code', true)?code=abc123ignored; the contract is an options object

Tests extend the existing parity suite, which already runs every case against all three implementations. The fake history gained replaceState so a test can distinguish "the URL changed" from "the URL changed and the old one is still reachable with Back", plus a truth table over the argument shapes above. 67 pass; the replace-specific ones fail without the change. Full suite 10754 pass / 1 fail, that one pre-existing (crosswind-arbitrary-values) and confirmed identical before the change.

Docs that were teaching the regression

The guide's canonical RIGHT (c) example is this exact scenario — consume a one-shot ?project=, then rewrite the URL — and it prescribed params.setAll({ project: undefined }). That pushes, so the guide taught the very thing this issue is about. It also does not delete: setAll runs searchParams.set per entry, so it yields ?project=undefined. Now params.delete('project', { replace: true }).

Also updated: the PROHIBITED_DOM_PATTERNS row mapping history.replaceState → useSearchParams().set/setAll, which silently converted a replace into a push; rule 9.7; and API.md, api/router.md, api/composables-ref.md, which documented only get/set/setAll with "(pushes history)" and no opt-out — and named a type, SearchParamsHandle, that exists nowhere in the code.

For Postline

window.history.replaceState({}, '', …) on the accounts page can become:

useSearchParams().delete(provider, { replace: true })

which should clear the last window.history use you mentioned.

Sign in to comment on this issue.