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()

[tmkx]

Hi Franky, I believe that using setState() is not allowed if we declare it as setState(value: string | undefined) instead of setState(value?: string)?

using undefined is more suitable for optional props in a React component; otherwise, we need to transform the value each time.

additionally, we can declare a default value in a more idiomatic JavaScript way:

const [hello = "world", setHello] = useQueryState("hello");
// vs
const [hello, setHello] = useQueryState("hello", parseAsString.withDefault("world"));

[franky47]

additionally, we can declare a default value in a more idiomatic JavaScript way:

The default value has meaning in multiple places, so you'll likely want to define it once at the parser level, and reuse that parser definition across your app (ideally tied to a key in a descriptor object passed to useQueryStates, createLoader etc).

undefined in the useQueryStates.setState case has a different meaning: it's a pass-through, keep this value as it is currently in the URL.