Branded helper

Instead of:

type Age = Branded<number, "Age">;

const Age = z
  .number()
  .min(0)
  .max(100)
  .refine((a: number): a is Age => true);

Zod can provide a simple helper:

const Age = z
  .number()
  .min(0)
  .max(100)
  .brand('Age');

What do you think?

---

This line:

.refine((a: number): a is Branded<number, "Age"> => true)

to this line:

.brand("Age").

I suppose it’s a tiny change but would improve DX a lot.

---

Or something like that?

const brand =
  <B extends string>(brand: B) =>
  <T extends string | number>(a: T): a is Branded<T, typeof brand> =>
    true;

.refine(brand("Age"))

---

OK, this is what I reiterated. Still, I suppose it should be part of the official Zod API.

export type Branded<T extends string | number, B extends string> = T & {
  readonly __brand: B;
};

export const branded =
  <B extends string, T extends string | number>(
    brand: B,
    predicate?: Predicate<T>
  ) =>
  (a: T): a is Branded<T, typeof brand> =>
    predicate ? predicate(a) : true;

[brudil]

We use branded types a fair bit, so I’m happy to chime in on how they can be used.

With TypeScript’s structural typing, we can’t utilise the type system to ensure zod is being used. Branded types are a way to create a unique type which can only be assigned by parsing with zod. This allows us to use the type system to ensure validation is happening.

As an example;

Defining a schema such as

const Age = z.number().min(18);

And we can use the inferred type from our schema within a param for example.

function save(data: z.infer<typeof Age> ) {}

TypeScript’s structural typing means there are no guarantees that input needs to have been parsed by zod first.

save(16) // perfectly valid and types.

Branded types allow us make a type ‘unique’.

export type Branded<T, B> = T & { __brand: B };

If we revisit the save function from above

function save(data: Branded<z.infer<typeof Age>, 'ageSchema'> ) {}

We’ve now ensured that this case is no longer possible

save(16)
// TS2345: Argument of type 'number' is not assignable to parameter of type 'Branded<number, "ageSchema">'.   Property '__brand' is missing in type 'number' but required in type '{ __brand: "ageSchema"; }'.

(Edited to a primitive)

[colinhacks]

I’ll I’ve been considering a dedicated API for branded types for a long time (#3) but I think the current approaches are more or less equivalent in terms of readability to a dedicated .brand API. If you want the result of .parse to be pretty (e.g. Age), you have to declare that type separately. At that point you might as well cast or use z.custom:

type Age = Branded<number, "Age">;

const ageSchema: z.ZodType<Age> = z.string().refine(...) as any;
const ageSchema = z.custom<Age>()

Open to be convinced though.