Do parsers support async values?

[nikitayutanov]

Hi! I have a question about how useQueryState/ useQueryStates behave when the allowed values of a parser depend on async data.

Consider the case where I receive some value from the URL (e.g. ?service=swap), but the list of valid values (['swap', 'transfer', ...]) is only known after some async API call resolves. For example:

const data = useAsyncData();
const values = data ?? [];

const [state, setState] = useQueryState(
  "service",
  parseAsStringEnum(values).withDefault("")
);

In such situations the received state always represents the default value. It seems that the workaround is to use a non-validating parser initially and perform the validation myself once the async data becomes available:

const data = useAsyncData();
const values = data ?? [];

const [state, setState] = useQueryState(
  "service",
  parseAsString.withDefault("")
);

const validState = data.includes(state) ? state : "";

Is it the preferred approach or am I missing something?

[franky47]

What should happen if a user clicked on a link that said ?service=swap, before the set of valid values is known? Or what should happen if they click on an invalid link ?service=banana?

One way would be to feed the promise to use and let the component suspend while it's pending, then you'd get the set of values to feed to the parser.

Parsers should be pure functions, side-effect free, and synchronous. Moreover, all useQueryState(s) hooks should have the same parser for a given key, see https://nuqs.dev/docs/troubleshooting#different-parsers-on-the-same-key.

[nikitayutanov]

What should happen if a user clicked on a link that said ?service=swap, before the set of valid values is known? Or what should happen if they click on an invalid link ?service=banana?

Fallback to a default value? I mean, if the set of values is not known yet or can change at runtime, I naturally expect those changes to be reflected on.

Maybe it’s just me, but this feels intuitive. We already deal with similar patterns in forms where validation depends on values that are not known at initialization time. If you’re familiar with react-hook-form, it’s sometimes useful to provide a placeholder schema until the real schema becomes available:

const data = useAsyncData();

const fieldSchema = data
  ? z.string().refine(value => format(value, data))
  : z.string();

const schema = z.object({ fieldName: fieldSchema });

const form = useForm({
  ...,
  resolver: zodResolver(schema),
});

The UI is always in a loading state during that phase - the user never really interacts with placeholder values.

One way would be to feed the promise to use and let the component suspend while it's pending, then you'd get the set of values to feed to the parser.

Sadly it's not currently possible in the current context of things as I'm dealing with nasty bloated legacy component.

Parsers should be pure functions, side-effect free, and synchronous. Moreover, all useQueryState(s) hooks should have the same parser for a given key, see https://nuqs.dev/docs/troubleshooting#different-parsers-on-the-same-key.

Ah, that actually makes sense. I see that from this point of view my provided example is not the expected way to deal with things, just my concern is that some components are inherently reactive - UI often depend on data/feature flag/app context that is unknown at the runtime.

[franky47]

One thing that puzzles me with this kind of approach is: how do you statically analyse this with TypeScript?

If the set of values (for parseAsStringLiteral/parseAsStringEnum) or schema (for your form example) is fetched at runtime, it can resolve to anything, and therefore the type-safety from there on is not guaranteed. The runtime safety is, from a validation standpoint, but there is no way to tell in the rest of the application what the expected values can be ahead of time (the type would have to be any or unknown).

In which case, the parseAsString approach (to accept all possible values) with a runtime filter based on async options seems the best approach.