mattchine / ts-to-zod

Generate zod schemas from typescript types/interfaces

ts-to-zod

Generate Zod schemas (v3) from Typescript types/interfaces.

Usage

$ yarn add --dev ts-to-zod
$ yarn ts-to-zod src/iDontTrustThisApi.ts src/nowIcanValidateEverything.ts

That's it, go to src/nowIcanValidateEverything.ts file, you should have all the exported interface and type as Zod schemas with the following name pattern: ${originalType}Schema.

Embedded validation

To make sure the generated zod schemas are 100% compatible with your original types, this tool is internally comparing z.infer<generatedSchema> and your original type. If you are running on those validation, please open an issue 😀

Notes:

• Only exported types/interface are tested (so you can have some private types/interface and just exports the composed type)
• Even if this is not recommanded, you can skip this validation step with --skipValidation. (At your own risk!)

Validators

This tool supports some JSDoc tags inspired from openapi to generate zod validator.

List of supported keywords:

JSDoc keyword	JSDoc Example	Generated Zod validator
@minimum {number}	@minimum 42	z.number().min(42)
@maximum {number}	@maximum 42	z.number().max(42)
@minLength {number}	@minLength 42	z.string().min(42)
@maxLength {number}	@maxLength 42	z.string().min(42)
@format {"email"|"uuid"|"url"}	@format email	z.string().email()
@pattern {regex}	@pattern ^hello	z.string().regex(/^hello/)

Those JSDoc tags can also be combined:

// source.ts
export interface HeroContact {
  /**
   * The email of the hero.
   *
   * @format email
   */
  email: string;

  /**
   * The name of the hero.
   *
   * @minLength 2
   * @maxLength 50
   */
  name: string;

  /**
   * The phone number of the hero.
   *
   * @pattern ^([+]?d{1,2}[-s]?|)d{3}[-s]?d{3}[-s]?d{4}$
   */
  phoneNumber: string;

  /**
   * Does the hero has super power?
   *
   * @default true
   */
  hasSuperPower?: boolean;

  /**
   * The age of the hero
   *
   * @minimum 0
   * @maximum 500
   */
  age: number;
}

// output.ts
export const heroContactSchema = z.object({
  /**
   * The email of the hero.
   *
   * @format email
   */
  email: z.string().email(),

  /**
   * The name of the hero.
   *
   * @minLength 2
   * @maxLength 50
   */
  name: z.string().min(2).max(50),

  /**
   * The phone number of the hero.
   *
   * @pattern ^([+]?d{1,2}[-s]?|)d{3}[-s]?d{3}[-s]?d{4}$
   */
  phoneNumber: z.string().regex(/^([+]?d{1,2}[-s]?|)d{3}[-s]?d{3}[-s]?d{4}$/),

  /**
   * Does the hero has super power?
   *
   * @default true
   */
  hasSuperPower: z.boolean().default(true),

  /**
   * The age of the hero
   *
   * @minimum 0
   * @maximum 500
   */
  age: z.number().min(0).max(500),
});

Advanced configuration

If you want to customized the schema name or restrict the exported schemas, you can do this by adding a ts-to-zod.config.js at the root of your project.

Just run yarn ts-to-zod --init and you will have a ready to use configuration file (with a bit of typesafety).

You have two ways to restrict the scope of ts-to-zod:

• nameFilter will filter by interface/type name
• jsDocTagFilter will filter on jsDocTag

Example:

// ts-to-zod.config.js
/**
 * ts-to-zod configuration.
 *
 * @type {import("./src/config").TsToZodConfig}
 */
module.exports = [
  {
    name: "example",
    input: "example/heros.ts",
    output: "example/heros.zod.ts",
    jsDocTagFilter: (tags) => tags.map(tag => tag.name).includes("toExtract")) // <= rule here
  },
];

// example/heros.ts
/**
 * Will not be part of `example/heros.zod.ts`
 */
export interface Enemy {
  name: string;
  powers: string[];
  inPrison: boolean;
}

/**
 * Will be part of `example/heros.zod.ts`
 * @toExtract
 */
export interface Superman {
  name: "superman" | "clark kent" | "kal-l";
  enemies: Record<string, Enemy>;
  age: number;
  underKryptonite?: boolean;
}

/!\ Please note: if your exported interface/type have a reference to a non-exported interface/type, ts-to-zod will not be able to generate anything (a circular dependency will be report due to the missing reference).

Limitation

Since we are generating Zod schemas, we are limited by what Zod actually supports:

• No type generics
• No complex circular dependencies (you will be warn if you have some in your types)
• No Record<number, …>
• …

To resume, you can use all the primitive types and some the following typescript helpers:

• Record<string, …>
• Pick<>
• Omit<>
• Partial<>
• Required<>
• Array<>
• Promise<>

This utils is design to work with one file only, and will reference types from the same file:

// source.ts
export type Id = string;
export interface Hero {
  id: Id;
  name: string;
}

// output.ts
export const idSchema = z.string();
export const heroSchema = z.object({
  id: idSchema,
  name: z.string(),
});

Programmatic API

You need more than one file? Want even more power? No problem, just use the tool as a library.

High-level function:

• generate take a sourceText and generate two file getters

Please have a look to src/core/generate.test.ts for more examples.

Low-level functions:

• generateZodSchema help you to generate export const ${varName} = ${zodImportValue}.object(…)
• generateZodInferredType help you to generate export type ${aliasName} = ${zodImportValue}.infer<typeof ${zodConstName}>
• generateIntegrationTests help you to generate a file comparing the original types & zod types

To learn more about thoses functions or their usages, src/core/generate.ts is a good starting point.

Local development

$ git clone
$ cd ts-to-zod
$ yarn
$ ./bin/run
USAGE
  $ ts-to-zod [input] [output]
  ...

You also have plenty of unit tests to play safely:

$ yarn test --watch

And a playground inside example, buildable with the following command:

$ yarn gen:example

Last note, if you are updating src/config.ts, you need to run yarn gen:config to have generate the schemas of the config (src/config.zod.ts) (Yes, we are using the tool to build itself #inception)

Have fun!