Allow parseAsXLiteral parsers to return their inputs

[neefrehman]

I'm currently implementing a tabs-based interaction with parseAsStringLiteral, with a simple example follows:

const tabsParser = parseAsStringLiteral(['one', 'two', 'three'] as const);
const searchParams = { tabs: tabsParser };
const serializer = createSerializer(searchParams);

const Tabs = () => {
  const [currentTab] = useQueryState('tab', searchParams.tab);

  return (
    <Tabs selectedTab={currentTab}>
      <TabList>
        { /* I don't want to iterate over `tabs` here, as I'd like to be in control of the rendering with more specificity */ }
        <Tab id="one" href={serializer({ tab: "one" })}>One<Tab>
        <Tab id="two" href={serializer({ tab: "two" })}>Two<Tab>
        <Tab id="three" href={serializer({ tab: "three" })}>Three<Tab>
      </TabList>
      <TabPanel id="one"></TabPanel>
      <TabPanel id="two"></TabPanel>
      <TabPanel id="three"></TabPanel>
    </Tabs>
  )
}

This is quite a lot of string-based lookups, which I think could be made a little safer if we access to a typed object containing the values. (i.e. Record<T, T>), at which point we could do:

  return (
    <Tabs selectedTab={currentTab}>
      <TabList>
        <Tab id={tabsParser.one} href={serializer({ tab: tabsParser.one })}>One<Tab>
        <Tab id={tabsParser.two} href={serializer({ tab: tabsParser.two })}>Two<Tab>
        <Tab id={tabsParser.three}  href={serializer({ tab: tabsParser.three })}>Three<Tab>
      </TabList>
      <TabPanel id={tabsParser.one}></TabPanel>
      <TabPanel id={tabsParser.two}></TabPanel>
      <TabPanel id={tabsParser.three}></TabPanel>
    </Tabs>
  )

Obviously, this is a bit of a contrived example, and one that can be solved in userland with a function that returns Record<T, T> (which I'm doing right now!) But, once we start sharing this parser with other component that may be interested in it (for example in nested components withins a TabPanel), it becomes more useful for a single parser definition to be able to "bring along" it's options in a type-safe way. This could even include the list of options (T[]), if we do decide to iterate elsewhere.

Curious to hear if you think this would be a sensible addition to the library, or if there's another solution that could work.

[franky47]

This is quite a lot of string-based lookups, which I think could be made a little safer ...

That's the point of using string literals: you are using strings, but they are type-safe by only allowing the right options.

One alternative is using an Enum, where you could do:

enum Tabs = {
  one = 'one',
  two = 'two',
  three = 'three'
}

const tabsParser = parseAsStringEnum<Tabs>(Object.values(Tabs));
const searchParams = { tabs: tabsParser };
const serializer = createSerializer(searchParams);

const Tabs = () => {
  const [currentTab] = useQueryState('tab', searchParams.tab);

  return (
    <Tabs selectedTab={currentTab}>
      <TabList>
        <Tab id={tabsParser.one} href={serializer({ tab: Tabs.one })}>One<Tab>
        <Tab id={tabsParser.two} href={serializer({ tab: Tabs.two })}>Two<Tab>
        <Tab id={tabsParser.three}  href={serializer({ tab: Tabs.three })}>Three<Tab>
      </TabList>
      <TabPanel id={Tabs.one}></TabPanel>
      <TabPanel id={Tabs.two}></TabPanel>
      <TabPanel id={Tabs.three}></TabPanel>
    </Tabs>
  )
}

[neefrehman]

Thanks @franky47! I hadn't seen the enum method. I'm using it now and it works well. Though there is still the question of now having multiple objects to reason about when it comes to "sharing" these search params with the rest of the codebase. Right now things look like this:

enum TabOptions = {
  one = 'one',
  two = 'two',
  three = 'three'
}

// Needs renaming to avoid clashing with the `Tabs` component
const tabsParser = parseAsStringEnum<Tabs>(Object.values(TabOptions)).withDefault(
  TabOptions.one,
);
const searchParams = { tabs: tabsParser };
const serializer = createSerializer(searchParams);

const Tabs = () => {
  const searchParams = useSearchParams()
  const [currentTab] = useQueryState('tab', searchParams.tab);

  return (
    <Tabs selectedTab={currentTab}>
      <TabList>
        <Tab id={TabOptions.one} href={serializer(searchParams, { tab: TabOptions.one })}>One<Tab>
        <Tab id={TabOptions.two} href={serializer(searchParams, { tab: TabOptions.two })}>Two<Tab>
        <Tab id={TabOptions.three}  href={serializer(searchParams, { tab: TabOptions.three })}>Three<Tab>
      </TabList>
      <TabPanel id={TabOptions.one}></TabPanel>
      <TabPanel id={TabOptions.two}></TabPanel>
      <TabPanel id={TabOptions.three}></TabPanel>
    </Tabs>
  )
}

If we wanted to share these search params so that we can use them in other components, we would conditionally be importing (and maybe constructing new instances of) some mix of TabOptions, tabsParser, searchParams, or serializer, depending on the use case. I wonder if this is a signal that more thought could be put into making the parser itself the source of truth for working with the query state, and thus reducing the export surface area of these objects, simplifying the related decision tree around their usage. (I appreciate that I could place these into a single object and export that, which I think I will do, but I think the feedback still stands)

I'm also aware the in my use case we typically mix and match serializers with useQueryState(s) quite a bit, which contributes to this surface area bloat. But, we would like to keep things working as much as possible with hrefs. Zooming out a little, potentially there is also a broader change that could allow for client hooks to return functions that perform serialization of hrefs, if you see this as a common enough scenario? This could potentially have a co-benefit of reducing the boilerplate above that required to use Next's useSearchParams hook (and maybe even moving the configuration around defaulting the base of such a serializer to the parser builder itself?).

In any case, these are just some thoughts after having only recently started the journey of deploying nuqs in a codebase, so it could be the case that I need to get used to the libraries current flavour of composition :)