Why does QueryStatus return null for parser keys without default values?

[Best-Sardar]

I am working with a set of parsers, and I noticed that QueryStatus returns null for keys that don’t have default values. Here’s an example of my parsers object:

parsers: {
  search: parseAsString.withDefault("nuqs"),
  phoneNumber: parseAsString,
  status: parseAsString
}

Expected output:

{
  search: "nuqs",
}

Current output:

{
  search: "nuqs",
  phoneNumber: null,
  status: null,
}

However, for keys without default values, the result is null. Based on my understanding:

undefined means a variable has been declared but not yet assigned a value.
null is an explicit assignment representing "no value."

Why you placed null instead of undefined?

[franky47]

This is outlined in the docs: https://nuqs.47ng.com/docs/basic-usage#default-values

The main reason is, as you said, that null means no value. It's returned to indicate the absence of the search params key in the URL, or if the parser can't give you a meaningful value back (eg: using parseAsInteger, but the URL is ?foo=not-a-number).

null is also used to clear the search param from the URL on updates, a case where undefined would have been awkward:

const [state, setState] = useQueryState('foo')

// null clears the URL
setState(null)

// Using undefined would allow this, which is ambiguous:
setState()