support user provided custom serialization/deserialization

[ethanniser]

currently serialization/deserialization is hard coded in

there are many valid usecase for a user wanting a custom solution:

• working around existing search param use cases
• custom array / object notation
• support for dates/bigints (superjson)

maybe look at how trpc handles custom transformers?

To discuss:
What should the signature of the swappable serializer be?
How to handle differences between search param and route param serialization / deserialization?

[ethanniser]

This should be trivial with @effect/schema but requires a big breaking change

[TmLev]

If I can, I'd like to mention my use-case for custom serialisation of routeParams.

I have a route that looks like this: /foos/[fooHandle]. Now the fooHandle can be one of two things:

• A uuid like "523ae1d0-2645-469e-b52b-125cf71498ce"
• A short id formatted as id<NUMBER> (literal id followed by a number)

In Typescript it looks like so:

type FooHandle = 
  | { id: string } // uuid
  | { shortId: number } // without `id` prefix from URL

Currently, I do the following when declaring routeParams:

export const Route = {
  routeParams: z.object({
    fooHandle: z.string().transform((h) => parseFooHandle(h)),
  }),
} satisfies DynamicRoute;

This work perfectly for deserialising raw string from URL into a valid FooHandle.

However, when I need to create a path to this route, I have to serialise fooHandle manually:

$path({
  route: "/foos/[fooHandle]",
  routeParams: {
    fooHandle: serializeFooHandle(foo.handle),
  },
})

since routeParams.fooHandle expects a string, and foo.handle is of type FooHandle above.

Ideally, routeParams.fooHandle should be able to take an arbitrary input as long as it can be serialised into something appropriate for the route param of the $path function. And this serialisation should probably be declared in the const Route itself.

[ethanniser]

the options as I see them:

1. do nothing- users are forces to implement this on their own (most likely though the same way as above)

pros: no breaking changes
cons: not the best dx

2. add a global transformer (trpc-esce). Would require a $path builder. ie:

export $path = buildPath({ transformer })

pros: idk
cons: reexport is kind of annoying- leads to autocomplete conflicts if named the same
seems pretty common to me to have per route special serialization/deserialization logic which here is a bit tedious

3. add as a argument to $path

$path({ ... }, { transformer })

pros: non breaking change, still can be typesafe (I think)
cons:
requires you to remember to provide this

4. switch to @effect/schema
   pros: can basically do any two way transformation. very typesafe, composable
   cons: huge breaking change, requires schemas to be rewritten

---

Just thinking now though that even if we switch to schema, I think we would need to code gen a file with all of the schemas. Because right now $path at runtime doesnt actually depend on them at all- its pure. However I think we would need to create basically a runtime version of the AppRouter thing and have it lookup the right schema to encode at runtime

---

anyways open to thoughts

[ethanniser]

maybe use nuqs?
https://x.com/nuqs47ng/status/1952413035965845934

[TmLev]

That's deserialization only, right? It would be nice to have serialization as well

[franky47]

Here is the serialisation counterpart to generate hrefs (using the same search params declaration object as a source):

https://nuqs.47ng.com/docs/utilities#serializer-helper

import {
  createSerializer,
  parseAsInteger,
  parseAsIsoDateTime,
  parseAsString,
  parseAsStringLiteral
} from 'nuqs/server' // can also be imported from 'nuqs' in client code
 
const searchParams = {
  search: parseAsString,
  limit: parseAsInteger,
  from: parseAsIsoDateTime,
  to: parseAsIsoDateTime,
  sortBy: parseAsStringLiteral(['asc', 'desc'] as const)
}
 
// Create a serializer function by passing the description of the search params to accept
const serialize = createSerializer(searchParams)
 
// Then later, pass it some values (a subset) and render them to a query string
serialize({
  search: 'foo bar',
  limit: 10,
  from: new Date('2024-01-01'),
  // here, we omit `to`, which won't be added
  sortBy: null // null values are also not rendered
})
// ?search=foo+bar&limit=10&from=2024-01-01T00:00:00.000Z

[ethanniser]

working on this tonight or tomorrow
very exciting actually