parseAsDateTime and other parsers fail on null/undefined when used with parseAsArrayOf

[AfeefRazick]

Context

What's your version of nuqs?

"nuqs": "^2.4.3"

What framework are you using?

✅ React SPA (no router)
✅ React Router

Which version of your framework are you using?

"react": "19.0.0"
"react-dom": "19.0.0"
"react-router": "7.1.5"

Description

When using parseAsDateTime on a singular field, null works fine — calling setState(null) bypasses the serializer, so no errors occur (as in the docs examples).

However, when wrapping parseAsDateTime in parseAsArrayOf (e.g., for date ranges), the serializer fails if any array element is null or undefined. This happens because the serializer calls .toISOString() on a nullish value.

Example:

parseAsArrayOf(parseAsDateTime)
// Intended to handle: [Date, undefined]

Instead, it throws because undefined (or null) is passed to .toISOString().

Relevant parser code (parseAsIsoDateTime):

export const parseAsIsoDateTime: ParserBuilder<Date> = createParser({
  parse: v => {
    const date = new Date(v)
    if (Number.isNaN(date.valueOf())) {
      return null
    }
    return date
  },
  serialize: (v: Date) => v.toISOString(),
  eq: compareDates
})

Why it fails:

In array contexts, each element is run through serialize without checking for null/undefined. Standalone parseAsDateTime works fine because null never hits the serializer.

Suggested fix:

serialize: (v: Date | null | undefined) => (v === null || v === undefined ? '' : v.toISOString()),

This ensures that nullish values inside arrays are handled consistently.

Note:
This issue is likely not limited to parseAsDateTime. Other built-in parsers without nullish checks in serialize may behave the same when used inside parseAsArrayOf.

Reproduction

Steps to reproduce:

Create a state with useQueryStates using parseAsArrayOf(parseAsDateTime).

Set the value to [new Date(), undefined] or [new Date(), null].

Observe that .toISOString() is called on the nullish value, causing an error.

Minimal example:

const [dateRange, setDateRange] = useQueryStates({
  range: parseAsArrayOf(parseAsDateTime)
});

// This will throw
setDateRange({ range: [new Date(), undefined] });

[franky47]

Thanks for this, it feels like the fix would be better located in parseAsArrayOf, to filter out nullish values before calling serialize on them, as the serialize signature always expects a valid (non-null, non-undefined) input, and always expects a string output (for the moment at least).

That being said, that the type system allows setting states with Array<T | null | undefined> seems like the real source of the issue here. I guess I can see where this comes from (the item parser does not have a default value, so its type would be T | null), but really it should only accept values of a non-nullish T.

[franky47]

I did a reproduction component, and I do have type errors with either useQueryState or useQueryStates when trying to push either undefined or null into a Date[] state, as returned by parseAsArrayOf(parseAsIsoDateTime), as expected:

import {
  parseAsArrayOf,
  parseAsIsoDateTime,
  useQueryState,
  useQueryStates
} from 'nuqs'

export default function Page() {
  return (
    <>
      <UseQueryState />
      <hr />
      <UseQueryStates />
    </>
  )
}

function UseQueryState() {
  const [state, setState] = useQueryState(
    'test',
    parseAsArrayOf(parseAsIsoDateTime).withDefault([])
  )
  return (
    <>
      <button onClick={() => setState(null)}>Clear</button>
      <button
        onClick={() => {
          setState(prev => [...prev, new Date()])
        }}
      >
        Add Date
      </button>
      <button
        onClick={() => {
          setState(prev => [...prev, undefined]) // TypeError: ... Type 'undefined' is not assignable to type 'Date'. ts(2345)
        }}
      >
        Add undefined
      </button>
      <button
        onClick={() => {
          setState(prev => [...prev, null]) // TypeError: ... Type 'null' is not assignable to type 'Date'. ts(2345)
        }}
      >
        Add null
      </button>
      <pre>{JSON.stringify(state, null, 2)}</pre>
    </>
  )
}

function UseQueryStates() {
  const [state, setState] = useQueryStates({
    test: parseAsArrayOf(parseAsIsoDateTime).withDefault([])
  })
  return (
    <>
      <button onClick={() => setState(null)}>Clear</button>
      <button
        onClick={() => {
          setState(prev => ({ test: [...prev.test, new Date()] }))
        }}
      >
        Add Date
      </button>
      <button
        onClick={() => {
          setState(prev => ({ test: [...prev.test, undefined] })) // TypeError: ... Type 'undefined' is not assignable to type 'Date'. ts(2345)
        }}
      >
        Add undefined
      </button>
      <button
        onClick={() => {
          setState(prev => ({ test: [...prev.test, null] })) // TypeError: ... Type 'null' is not assignable to type 'Date'. ts(2345)
        }}
      >
        Add null
      </button>
      <pre>{JSON.stringify(state, null, 2)}</pre>
    </>
  )
}

One thing I noticed though is if I turn strictNullChecks to false in my tsconfig.json, the type errors disappear, could it be that this setting (or strict: false) was set as such in your project?

nuqs works best with TypeScript set to maximum strictness, otherwise a lot of the type-safety guards we've put in place are for nothing.

[AfeefRazick]

My project does have strict typing on, it seems by reproduction was not accurate, let me show you what I'm actually doing. I am connecting react table with nuqs where I created multiple hooks to essentially be drop in replacements for usestate holding react table state.

Below is the example I faced this issue with, I assume I don't get type warnings because the values are being inferred implicitley as any, perhaps due to the tranformations being performed in this hook or because react-table column filter values being unknown normally (I don't use any explicitely pretty much anywhere in this codebase).

type UseColumnFiltersQueryStateArg = {
  keyMap?: Parameters<typeof useQueryStates>[0];
  options?: Parameters<typeof useQueryStates>[1];
};

export function useColumnFiltersQueryState(arg?: UseColumnFiltersQueryStateArg) {
  const { keyMap = {}, options } = arg ?? {};

  const [queryState, setQueryState] = useQueryStates(keyMap, options);

  const columnFilters: ColumnFiltersState = Object.entries(queryState)
    .filter(([_, value]) => value !== undefined && value !== null)
    .map(([id, value]) => ({
      id,
      value,
    }));

  const setColumnFilters: OnChangeFn<ColumnFiltersState> = (updater) => {
    setQueryState((prev) => {
      const newFilters =
        typeof updater === 'function'
          ? updater(
              Object.entries(keyMap).flatMap(([id]) =>
                prev[id] !== undefined && prev[id] !== null ? [{ id, value: prev[id] }] : [],
              ),
            )
          : updater;

      const filtersMap = new Map(newFilters.map((f) => [f.id, f.value]));

      return Object.fromEntries(
        Object.entries(keyMap).map(([id]) => [id, filtersMap.has(id) ? filtersMap.get(id) : null]),
      );
    });
  };
  return [columnFilters, setColumnFilters] as [ColumnFiltersState, OnChangeFn<ColumnFiltersState>];
}

// usage

    const [columnFilters, setColumnFilters] = useColumnFiltersQueryState({
      keyMap: {
        createdAt: parseAsArrayOf(parseAsIsoDate),
      },
      options: {
        urlKeys: {
          createdAt: 'created-at',
        },
      },
    });

However the type issues is not what I was trying to convery by this issue. The problem that I have is with the fact that parseAsArrayOf combined with another parser does not work in scenarios where my array has null/undefined values.

This can be handled by

1. making many of the parsers to be able to handle nullish values on serialization
2. by ensuring the parseAsArrayOf does not run the parser serialization function if value is nullish. (better option imo)

My reasoning here is that since individual values (ex: parseAsIsoDate) can be nullish, when they are in arrays the array parser should also be able to handle that case. I feel it is more convenient as otherwise the user of the hook has to keep removing nullish values before passing into nuqs which can be handled by the parser itself. This is mainly the case when using datepicker libaries etc where values are set as [date1,null] as a valid value. Having to map from nuqs to valid value is a bit tedious.

However as I write this I'm realising that for my date picker debacle option 2 solution doesn't work as the parser will read as [date1] instead of [date1, null] which may not be a valid value for the date picker. The point may still stand for other use cases.

Bottom line is that this is the solution I went with to solve my issue.
This way I don't have to keep filtering nullish values every time i use the datepicker with nuqs.

export const parseAsOptionalIsoDateTime: ParserBuilder<Date> = createParser({
  parse: (v) => {
    const date = new Date(v);
    if (Number.isNaN(date.valueOf())) {
      return null;
    }
    return date;
  },
  serialize: (v: Date | null | undefined) => (v === null || v === undefined ? '' : v.toISOString()),
  eq: compareDates,
});

If you feel there is no problem here or this breaks some other more important use cases we'll close this. Just let me know if you think my solution above is a good way to go about this.

[AfeefRazick]

My bad I accidentally closed the issue and cannot reopen now 💀

[franky47]

We can add a filter on nullish items in parseAsArrayOf.serialize, it seems like a good compromise.

For cases where you do need a [T | null, T | null], a custom parser can be a better solution. Especially if, in the case of a date picker, you have a fixed size tuple (see #1019, #1022, and #1036 for a related discussions & proposals).

[franky47]

My reasoning here is that since individual values (ex: parseAsIsoDate) can be nullish

This is not the case though, as values come from two places:

1. The URL (on read), and parseAsArrayOf.parse already filters out nullish values from the array before returning the state.
2. A value you set (on write), in which case feeding it an any type bypasses the type-safety constraints that the hook expects.

If you have a custom hook that works for your use-case I'd suggest using that, but I don't think any change is necessary here, as the runtime behaviour matches what the types describe.