meta.ts

import * as z from "zod";

const mySchema = z.string();

// there is a global schema registry
z.globalRegistry; // => ZodRegistry<unknown, z.ZodType>

// add schema to registry w/ associated metadata
z.globalRegistry.add(mySchema, { name: "foo", description: "bar" });
// equivalent convenience method (returns mySchema)
mySchema.meta({ name: "foo", whatever: "bar" });

// global registry is untyped (accepts any object as metadata)
z.globalRegistry.add(z.string(), { a: "hello" });
z.globalRegistry.add(z.string(), { b: 1234 });

// to retrive metadata from global registry
z.globalRegistry.get(mySchema); // returns metadata (type is `unknown`)
// equivalent convenience method
mySchema.meta();

// for typed custom metadata, use a custom registry
const regA = z.registry<{ name: string; description: string }>();

// register typed metadata
regA.add(mySchema, { name: "foo", description: "bar" });
// equivalent convenience method (returns mySchema)
mySchema.register(regA, { name: "foo", description: "bar" });
// you can register your metadata "inline" with full typesafety
const _ = z.object({
  name: z.string().register(regA, {
    name: "name",
    description: "The name of the user",
  }),
  age: z.number().register(regA, {
    name: "age",
    description: "The age of the user",
  }),
});

// retrive typed metadata
regA.get(mySchema);
// => { name: string; description: string } | undefined

// coupling metadata to inferred types
// INPUT/OUTPUT is a special symbol that can be used to reference the output type of a schema
// it gets replaces with the actual output type when the registry is used
type B = { title: string; examples: z.OUTPUT[] };
const regB = z.registry<B>();
regB.add(z.string(), { title: "Name", examples: ["Alice", "Bob"] });
regB.add(z.number(), { title: "Ages", examples: [20, 99] });

// constraining registries by schema type
const regC = z.core.registry<object, z.ZodObject>();
regC.add(z.object({}), { title: "Name" });
regC.add(z.number(), { title: "Ages" });
//       ^ ERROR: not assignable

/** Internally registries use a weakmap to prevent memory leaks */