Allow serialize to return null

[wyozi]

Hey! There's some custom parsers that I'm working with, where sometimes the serializable value essentially is equal to null without being null (e.g. an empty array).

It would be nice if in those cases the serializer function could return null, meaning that nuqs removes the search parameter from the url completely.

[franky47]

Do you have a concrete example you can share?

[wyozi]

this is a bit different than the main use case, since in those I would pass an array as a value instead of a string, but this should still be a decent example

[franky47]

Could clearOnDefault help here (you'd have to define the eq function on your parser) ?

const [filter, setFilter] = useQueryState(
  'filter',
  parseAsStringFilter
    .withDefault({ operator: '=', value: null })
    .withOptions({ clearOnDefault: true })
)

setFilter({ operator: '=', value: null }) // clears the URL

One issue is that it wouldn't work on ?filter=neq.

[wyozi]

it's an interesting option, but yeah, unfortunately there are multiple combinations of operators and values that are effectively equal to null

[franky47]

I reproduced your use-case using a custom array parser that filters out null values in each filter before serialising them, it works in terms of removing "inactive" filters from the URL, but the internal state still contains those inactive filters, and so removing the last one doesn't clear the URL (as the state isn't equal to the default value of []).

Screen.Recording.2024-10-03.at.00.17.43.mov

That being said, if you were to reload the page, you'd lose any inactive filters, so if we consider the URL as the source of truth, they shouldn't be left in an inactive state in the first place, and be filtered from the array when updating the query state.

Here's the reproduction code, with a fork of `parseAsArrayOf`

'use client'

import { createParser, Parser, useQueryState } from 'nuqs'
import { Suspense } from 'react'

type Filter = { operator: '=' | '!='; value: string | null }

const parseAsStringFilter = createParser<Filter>({
  parse: v => {
    const split = v.split('.', 2)
    if (!split) {
      return null
    }

    if (split[0] === 'eq') {
      return { operator: '=', value: split[1] } as const
    } else if (split[0] === 'neq') {
      return { operator: '!=', value: split[1] } as const
    } else {
      return null
    }
  },
  serialize: v => `${v.operator === '=' ? 'eq' : 'neq'}.${v.value}`
})

function parseAsFilterArray(itemParser: Parser<Filter>, separator = ',') {
  const itemEq = itemParser.eq ?? ((a: Filter, b: Filter) => a === b)
  const encodedSeparator = encodeURIComponent(separator)
  // todo: Handle default item values and make return type non-nullable
  return createParser({
    parse: query => {
      if (query === '') {
        // Empty query should not go through the split/map/filter logic,
        // see https://github.com/47ng/nuqs/issues/329
        return [] as Filter[]
      }
      return query
        .split(separator)
        .map((item, index) =>
          safeParse(
            itemParser.parse,
            item.replaceAll(encodedSeparator, separator)
          )
        )
        .filter(value => value !== null && value !== undefined) as Filter[]
    },
    serialize: values =>
      values
        .filter(
          value => value !== null && value !== undefined && value.value !== null
        )
        .map<string>(value => {
          const str = itemParser.serialize
            ? itemParser.serialize(value)
            : String(value)
          return str.replaceAll(separator, encodedSeparator)
        })
        .join(separator),
    eq(a, b) {
      if (a === b) {
        return true // Referentially stable
      }
      if (a.length !== b.length) {
        return false
      }
      return a.every((value, index) => itemEq(value, b[index]!))
    }
  })
}

export default function Page() {
  return (
    <Suspense>
      <Client />
    </Suspense>
  )
}

function Client() {
  const [state, setState] = useQueryState(
    'state',
    parseAsFilterArray(parseAsStringFilter).withDefault([]).withOptions({
      clearOnDefault: true
    })
  )
  return (
    <>
      <pre>{JSON.stringify(state, null, 2)}</pre>
      <button
        onClick={() =>
          setState(old => [...old, { operator: '=', value: 'foo' }])
        }
      >
        eq foo
      </button>
      <button
        onClick={() =>
          setState(old => [...old, { operator: '!=', value: 'bar' }])
        }
      >
        neq bar
      </button>
      <button
        onClick={() =>
          setState(old => {
            const out = [...old]
            out[0].value = null
            return out
          })
        }
      >
        Set filter[0] to null
      </button>
      <button
        onClick={() =>
          setState(old => {
            const out = [...old]
            out[1].value = null
            return out
          })
        }
      >
        Set filter[1] to null
      </button>
      <button onClick={() => setState(old => old.slice(0, -1))}>Pop</button>
      <button onClick={() => setState(null)}>Clear</button>
    </>
  )
}

function safeParse<T>(parser: Parser<T>['parse'], value: string) {
  try {
    return parser(value)
  } catch (error) {
    return null
  }
}

[wyozi]

That's very cool! And that's a good point, ideally the filtering would be done beforehand. I'll have to think about this a bit