Branded URL parameters

[lensbart]

Branded types in TypeScript refer to a technique to get faux-nominal types in a language that is otherwise structurally typed. By defining a type as follows:

import { z } from "zod" 
type UserId = string & z.$brand<"userId"> // zod is not actually needed, this is just an example

You will get a type error when passing a non-userId-id to a function that expects a userId-id.

Both Drizzle and Zod support branded types natively. However, in order to make effective use of branded types in a web app, they would also have to be supported at the route level. If not, an excessive amount of type casts are needed to use route params in e.g. database where clauses.

For example, currently in React Router, it is necessary to cast params.userId as follows:

// currently
import { z } from "zod" 
const asUserId = (value: string) => value as string & z.$brand<"userId">

export const loader = ({ params }: Route.LoaderArgs) => {
  const users = await db.select().from(users).where(eq(users.id, asUserId(params.userId)))
  return { users }
}

This gets overly verbose rather quickly, and partially defeats the purpose of using branded types in the first place.

The most appropriate place to provide the type brands would probably be in the routes.ts file. For example, the CreateRouteOptions type could be extended with a brands property as follows:

import { z } from "zod" 
const asUserId = (value: string) => value as string & z.$brand<"userId">
const asOrganizationId = (value: string) => value as string & z.$brand<"organizationId">

export default [
  route(
    "organization/:organizationId",
    "some-file.ts",
    { brands: { organizationId: asOrganizationId } },
    [
      route("users/:userId", "some-other-file.ts", {
        brands: { userId: asUserId },
      }),
    ],
  ),
]