zod-to-ts

Install the package via npm. Note that this package requires zod@4 and typescript@5 as peer dependencies.

npm install zod-to-ts

Use zodToTs to convert a Zod schema into a TypeScript AST node. The returned node represents the type but is not a full type declaration string. To create a full type declaration, use createTypeAlias. To convert the node to a string, use printNode.

import { z } from 'zod'
import { zodToTs, createTypeAlias, printNode } from 'zod-to-ts'

const UserSchema = z.object({
	username: z.string(),
	age: z.number(),
	inventory: z.object({
		name: z.string(),
		itemId: z.number(),
	}).array(),
})

const { node } = zodToTs(UserSchema)

// Create a type alias declaration
const typeAlias = createTypeAlias(node, 'User')

// Convert the node/alias to a string
const nodeString = printNode(typeAlias)
console.log(nodeString)

The zodToTs function accepts an optional configuration object as its second argument. Key options include:

• metadataRegistry: Used for extracting schema metadata (like description) into JSDoc comments. Defaults to the global registry.
• unrepresentable: Determines behavior when encountering non-statically analyzable APIs like z.transform() or z.custom(). Set to 'any' to return any instead of throwing an error.
• io: Specifies whether to extract the schema's 'input' or 'output' type. Defaults to 'output'.

zodToTs(schema, {
	metadataRegistry: myRegistry,
	unrepresentable: 'any',
	io: 'input'
})

If zod-to-ts cannot statically infer a type (for example, with z.instanceof(Date)), you can provide a manual override. Use TypeOverrideMap to map a Zod schema to a custom TypeScript AST node via a callback function.

import { z } from 'zod'
import { createAuxiliaryTypeStore, type TypeOverrideMap, zodToTs } from 'zod-to-ts'

const overrides: TypeOverrideMap = new Map()

// Manually define how DateSchema should be represented in TS
const DateSchema = z.instanceof(Date)
overrides.set(DateSchema, (ts) =>
	s.factory.createTypeReferenceNode(ts.factory.createIdentifier('Date')),
)

const ItemSchema = z.object({
	name: z.string(),
	date: DateSchema,
})

const auxiliaryTypeStore = createAuxiliaryTypeStore()
const { node } = zodToTs(ItemSchema, {
	auxiliaryTypeStore,
	overrides,
})

When calling zodToTs, you can provide a ZodToTsOptions object to control the output. Key configuration properties include:

• unrepresentable: Determines behavior when a type cannot be represented in TypeScript.
  • 'throw' (default): Throws an error.
  • 'any': Converts the type to {}.
• io: Determines whether to extract the input or output type (relevant for transforms, coerced primitives, etc.).
  • 'output' (default): Converts the output schema.
  • 'input': Converts the input schema.
• overrides: A TypeOverrideMap for specific schema overrides.
• overrideFunction: A fallback function for schema overrides.
• metadataRegistry: A registry used to look up metadata (like description) for each schema. Defaults to globalRegistry if not provided.

The handleUnrepresentable function manages how Zod schemas that cannot be directly mapped to TypeScript types are handled. If the unrepresentable option in ZodToTsOptions is set to 'any', it returns a TypeScript any keyword type node. Otherwise, it throws an error indicating that the specific schema type cannot be represented in TypeScript.

// Example of how the logic behaves based on configuration
// If unrepresentable: 'any'
// Result: ts.any

// If unrepresentable is not 'any'
// Result: Error: Schemas of type "<type>" cannot be represented in TypeScript

The createAuxiliaryTypeStore function initializes a new AuxiliaryTypeStore. This store is used to manage and track auxiliary type definitions (types generated during the conversion process that need to be referenced by name). It provides a nextId() method that generates unique identifiers (e.g., Auxiliary_0, Auxiliary_1) and a definitions Map to store the actual type definitions.

const store = createAuxiliaryTypeStore();
const id = store.nextId(); // "Auxiliary_0"
store.definitions.set(id, someTypeNode);

You can control how specific Zod schemas are converted by using the overrides option. This allows you to map a Zod schema to a specific TypeScript type (like a custom interface or a primitive) that doesn't match the default conversion logic.

overrides accepts a TypeOverrideMap, which maps a Zod schema to a TypeOverrideFunction.

import { zodToTs } from 'zod-to-ts';
import { z } from 'zod';
import ts from 'typescript';

const mySchema = z.string();

const { node } = zodToTs(mySchema, {
  overrides: new Map([
    [mySchema, (schema, ts) => ts.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword)]
  ])
});

The zodToTs function is the primary entry point for converting a Zod schema into a TypeScript Abstract Syntax Tree (AST) node. It accepts a Zod schema and an optional configuration object, returning an object containing the generated node (a ts.TypeNode).

To use this, you will need the typescript package installed, as the returned node is a native TypeScript AST node.

import { zodToTs } from 'zod-to-ts';
import { z } from 'zod';

const schema = z.object({
  name: z.string(),
  age: z.number().optional(),
});

const { node } = zodToTs(schema, {});
// 'node' is a ts.TypeNode representing { name: string; age?: number; }