fix: Ensure referential stability for values

franky47 commented 2 months ago

Before this PR, any update of a search param (via nuqs or otherwise) would trigger all the parsers to run, causing unstable references for non-primitive states (objects, arrays, maybe even Dates?).

This caused effects to re-run needlessly, and it is wasteful: we already have the values, and other search params which haven't changed don't need to be parsed again.

This PR implements a cache of the serialized query string value along with the cache of the internal state (using React refs), and checks for a change before calling the parsers if needed.

Caveats

This is an edge case, but having two different parsers on the same key (eg: parseAsInteger and parseAsFloat) will result in the latest updated value being propagated to all the hooks registered on the same key.

Example: if setting foo to 1.234 via parseAsFloat, a hook listening to foo with parseAsInteger will have a state of 1.234, not 1. Before this PR, the state would flash first with 1.234, then the parser would run and correct it to 1.

Anyway, this is not a recommended use of the library (one key, one parser, then derive state if needed).