zinfer

A tool to extract TypeScript input/output types from Zod schemas.

Features

• Extract z.input<T> / z.output<T> types as text from Zod schemas
• Accurate type analysis using TypeScript Compiler API (ts-morph)
• Non-invasive: does not modify original source files
• Supports both CLI and library API
• Handles circular references (z.lazy, getter patterns)
• Outputs .describe() as TSDoc comments
• Supports branded types via .brand()
• Configuration file support (zinfer.config.ts, package.json)

Schema API compatibility

Verified against Zod 4.6.5, including string formats, codecs, compile/withParser, input/output, deepPartial, exactPartial, toZod, getDiscriminatedOption, iban, and currencyCode. z.instanceof(...).properties(...) is always supported as a schema. Standalone z.properties(...) is detected either way: as a schema on Zod 4.6.0-4.6.2, and as a check (not a schema) on 4.6.3+. Recursive json() types remain recursive, including inside other schemas. For exported schemas with symbol keys, generated types reference the source schema's inferred input/output type to preserve the original symbol identity; keep that source module available to TypeScript. This also applies to explicit type annotations: input and output are resolved independently, including Zod 4's default unknown input for z.ZodType<T>.

Installation

npm install zinfer

Quick Start

CLI

# Extract all schemas from a single file
zinfer src/schemas/user.ts

# Process multiple files with glob patterns
zinfer "src/**/*.schema.ts"

# Output to files
zinfer src/schemas.ts --outDir ./types

# Merge into a single type when input/output are identical
zinfer src/schemas.ts --merge-same --suffix Schema

Library API

import { extractZodTypes, extractAllSchemas, extractAndFormat } from "zinfer";

// Extract a single schema
const { input, output } = extractZodTypes("./schemas.ts", "UserSchema");
console.log(input); // { id: string; name: string; }
console.log(output); // { id: string; name: string; }

// Get formatted output
const formatted = extractAndFormat("./schemas.ts", "UserSchema");
console.log(formatted);

// Extract all schemas from a file
const results = extractAllSchemas("./schemas.ts");
for (const result of results) {
  console.log(`${result.schemaName}: ${result.input}`);
}

CLI Options

Usage: zinfer [options] [files...]

Arguments:
  files                      File paths or glob patterns

Options:
  -c, --config <path>               Path to config file
  -p, --project <path>              Path to tsconfig.json
  --schemas <names>                 Comma-separated schema names to extract
  --input-only                      Output only input types
  --output-only                     Output only output types
  --merge-same                      Single type if input===output
  --suffix <suffix>                 Remove suffix from schema names (e.g., 'Schema')
  --input-suffix <suffix>           Suffix for input type names (default: 'Input')
  --output-suffix <suffix>          Suffix for output type names (default: 'Output')
  --map <mappings>                  Custom name mappings (e.g., 'UserSchema:User')
  --outDir <dir>                    Output directory for generated files
  --outFile <file>                  Single output file for all types
  --outPattern <pattern>            Output file naming pattern (e.g., '[name].types.ts')
  -d, --declaration                 Generate .d.ts files
  --dry-run                         Preview without writing files
  --with-descriptions               Include Zod .describe() as TSDoc comments
  --generate-tests                  Generate vitest type equality tests alongside type files
  --inline-type-references [scope]  Inline a plain type an explicit z.ZodType<T> annotation reaches: "project" (default when the flag is set) or "all" (also dependency-declared types)
  --brand-strategy <strategy>       How to represent a .brand() marker in the generated output (default: zod-import)
  -V, --version                     Output the version number
  -h, --help                        Display help

Configuration File

zinfer.config.ts

import { defineConfig } from "zinfer";

export default defineConfig({
  // Target files
  include: ["src/**/*.schema.ts"],

  // Exclude patterns
  exclude: ["**/*.test.ts"],

  // Path to tsconfig.json
  project: "./tsconfig.json",

  // Schema names to extract (all if not specified)
  schemas: ["UserSchema", "PostSchema"],

  // Output options
  outDir: "./types",
  outFile: "./types/index.ts",
  outPattern: "[name].types.ts",
  declaration: true,

  // Type output options
  inputOnly: false, // Output only input types
  outputOnly: false, // Output only output types
  mergeSame: true, // Merge into single type when input === output

  // Type name options
  suffix: "Schema", // Suffix to remove from schema names
  inputSuffix: "Input", // Suffix for input types
  outputSuffix: "Output", // Suffix for output types

  // Custom mappings
  map: {
    UserSchema: "User",
    PostSchema: "Article",
  },

  // Output .describe() as TSDoc
  withDescriptions: true,

  // Inline a plain type an explicit annotation reaches instead of leaving
  // it as a reference: "project" follows a reference within this project,
  // "all" also follows one into a dependency package. Not set here (the
  // default) leaves every such reference as printed.
  // inlineTypeReferences: "project",

  // How to represent a .brand() marker: "zod-import" (default) imports
  // BRAND from zod; "local-symbol" emits a self-contained unique symbol
  // marker instead, so the generated output never imports zod.
  brandStrategy: "zod-import",
});

package.json

{
  "zinfer": {
    "include": ["src/**/*.schema.ts"],
    "outDir": "./types",
    "mergeSame": true,
    "suffix": "Schema"
  }
}

Config file resolution order:

1. zinfer.config.ts
2. zinfer.config.mts
3. zinfer.config.js
4. zinfer.config.mjs
5. zinfer field in package.json

CLI options take precedence over config file settings.

Output Examples

Basic Output

Input schema:

export const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  age: z.number().optional(),
});

Output (default):

export type UserSchemaInput = {
  id: string;
  name: string;
  age?: number | undefined;
};

export type UserSchemaOutput = {
  id: string;
  name: string;
  age?: number | undefined;
};

Output (--merge-same --suffix Schema):

export type User = {
  id: string;
  name: string;
  age?: number | undefined;
};

With Transforms

Input schema:

export const DateSchema = z.object({
  createdAt: z.string().transform((s) => new Date(s)),
  count: z.string().transform(Number),
});

Output:

export type DateSchemaInput = {
  createdAt: string;
  count: string;
};

export type DateSchemaOutput = {
  createdAt: Date;
  count: number;
};

With TSDoc Comments (--with-descriptions)

Input schema:

export const UserSchema = z
  .object({
    id: z.string().uuid().describe("Unique user identifier"),
    name: z.string().describe("User's display name"),
    email: z.string().email().describe("Email address"),
  })
  .describe("User account information");

Output:

/**
 * User account information
 */
export type UserSchemaInput = {
  /** Unique user identifier */
  id: string;
  /** User's display name */
  name: string;
  /** Email address */
  email: string;
};

Branded Types

Input schema:

export const UserIdSchema = z.string().brand<"UserId">();

export const UserSchema = z.object({
  id: z.string().brand<"UserId">(),
  name: z.string(),
});

Output:

import type { BRAND } from "zod";

export type UserIdSchemaInput = string;

export type UserIdSchemaOutput = string & BRAND<"UserId">;

export type UserSchemaInput = {
  id: string;
  name: string;
};

export type UserSchemaOutput = {
  id: string & BRAND<"UserId">;
  name: string;
};

Branded types are applied only to output types. Input types do not include brands.

By default (--brand-strategy zod-import), a branded type imports BRAND from zod, as shown above. Pass --brand-strategy local-symbol when the generated output must never import zod - for example, when the generated files are re-exported through a public package API and consumers should never need zod in their own type-check graph. It emits a self-contained unique symbol marker instead:

export declare const __brand: unique symbol;

export type UserIdSchemaInput = string;

export type UserIdSchemaOutput = string & { readonly [__brand]: "UserId" };

export type UserSchemaInput = {
  id: string;
  name: string;
};

export type UserSchemaOutput = {
  id: string & { readonly [__brand]: "UserId" };
  name: string;
};

The __brand symbol is declared once per generated file, exported, and reused by every branded type in it - two brands stay nominally distinct because their tag ("UserId" above) differs, not because of the symbol's identity, the same way zod's own BRAND marker works.

--brand-strategy local-symbol works with --generate-tests too. A local-symbol marker is intentionally a different shape from zod's own BRAND<Tag> (and zinfer's is readonly, zod's is not), so a branded schema's output test can't use the plain toEqualTypeOf<z.output<typeof Schema>>() assertion the way an unbranded one does; instead the generated companion test canonicalizes both sides' brand-marker property - whichever unique symbol keys it, whether the tag is a bare literal or zod's own { [Tag]: true } encoding, and regardless of the readonly mismatch - down to a common shape and tag before comparing, recursively, so a brand nested at any depth (inside an array, a record, or a self-referential schema) is still verified against the real inferred type.

Circular Reference Support

Getter Pattern (Recommended)

interface Category {
  name: string;
  subcategories: Category[];
}

const CategoryBaseSchema = z.object({
  name: z.string(),
  get subcategories() {
    return CategorySchema.array();
  },
});

export const CategorySchema: z.ZodType<Category> = CategoryBaseSchema;

z.lazy Pattern

export type JsonValue =
  string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };

export const JsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
  z.union([
    z.string(),
    z.number(),
    z.boolean(),
    z.null(),
    z.array(JsonValueSchema),
    z.record(JsonValueSchema),
  ]),
);

When an explicit type annotation (z.ZodType<T>) is present, that type name is used in the output.

Annotating the getter itself lets TypeScript unfold one whole copy of the schema before it reaches the recursion. That copy is collapsed away, so the generated type holds the self-reference directly rather than an extra level of the same shape.

Recursive Schemas Across Files

A recursive type has no faithful inline form, so a recursive schema imported from another file is referenced by name and imported from the file that declares its types:

// out/tree.generated.ts
import type { Node } from "./node.generated";

export type Tree = {
  root: Node;
  index: {
    [x: string]: Node;
  };
};

This needs the declaring file to be part of the same run and to get an output file of its own (--outDir / --outPattern, or --outFile, which puts both declarations in the one file and needs no import). A local import alias (import { Node as N }) makes no difference - the reference and import still use the declaring file's own export name, since that is the only name its generated file actually declares. --schemas only turns this off for a schema the filter itself excludes, since that schema's own declaration wouldn't be generated either; an output pattern that maps two schema files onto one path turns it off too, for the same reason. Whenever a reference cannot be made, the schema is inlined as far as it can be, with the recursion point kept as the index signature or array the getter describes instead of collapsing to a bare any.

Recursive Schemas Through a Non-Generated Intermediate

A schema that is not exported gets no generated type of its own, so a reference to it is inlined. Its own references to schemas that ARE generated still resolve by name, even when the reference to the recursive schema is nested inside that inlined copy:

export const NodeSchema = z.object({
  name: z.string(),
  get children() {
    return z.record(z.string(), NodeSchema);
  },
});

// Not exported - no type is generated for it
const GroupSchema = z.object({
  members: z.array(NodeSchema),
});

export const TreeSchema = z.object({
  direct: NodeSchema,
  viaGroup: GroupSchema,
});

export type Tree = {
  direct: Node;
  viaGroup: {
    members: Node[];
  };
};

No import is needed here, since Node is generated in this same file - unlike the cross-file case above, this works regardless of whether the intermediate's own file is part of the run.

Non-Exported, Self-Recursive Schemas

A non-exported schema that is itself recursive still needs a name for its own recursion point - and every other reference to it - to point at, so it gets its own local declaration in the output file too, without the export keyword an exported schema's declaration gets:

type NodeOutput = {
  value: string;
  children?: Record<string, NodeOutput>;
};

// Not exported, but self-recursive - still gets its own local declaration
const NodeSchema: z.ZodType<NodeOutput> = z.lazy(() =>
  z.object({
    value: z.string(),
    children: z.record(z.string(), NodeSchema).optional(),
  }),
);

export const ContainerSchema = z.object({
  name: z.string(),
  root: NodeSchema,
});

type Node = {
  value: string;
  children?: Record<string, Node>;
};

export type Container = {
  name: string;
  root: Node;
};

Two promoted locals whose names would otherwise collide are disambiguated with a numeric suffix. This only applies within the same file - a non-exported, self-recursive schema whose explicit annotation reaches a type declared in another file still widens its recursion point to any, as described above.

Library API

extractZodTypes

Extracts types from a single schema.

import { extractZodTypes } from "zinfer";

const { input, output } = extractZodTypes(
  "./schemas.ts",
  "UserSchema",
  "./tsconfig.json", // optional
);

extractAllSchemas

Extracts all schemas from a file.

import { extractAllSchemas } from "zinfer";

const results = extractAllSchemas("./schemas.ts");
// results: ExtractResult[]

extractAndFormat

Extracts types and returns them as a formatted string.

import { extractAndFormat } from "zinfer";

const formatted = extractAndFormat("./schemas.ts", "UserSchema");
console.log(formatted);
// Output:
// // input
// { id: string; name: string; }
//
// // output
// { id: string; name: string; }

generateTypeDeclarations

Generates TypeScript type declarations from extraction results.

import { extractAllSchemas, generateTypeDeclarations } from "zinfer";

const results = extractAllSchemas("./schemas.ts");
const declarations = generateTypeDeclarations(results, {
  nameMapping: {
    removeSuffix: "Schema",
    inputSuffix: "Input",
    outputSuffix: "Output",
  },
  declaration: {
    mergeSame: true,
  },
});

console.log(declarations);

ZodTypeExtractor Class

For more fine-grained control:

import { ZodTypeExtractor } from "zinfer";

const extractor = new ZodTypeExtractor("./tsconfig.json");

// Single schema
const result = extractor.extract({
  filePath: "./schemas.ts",
  schemaName: "UserSchema",
});

// All schemas
const allResults = extractor.extractAll("./schemas.ts");

// Multiple specific schemas
const selectedResults = extractor.extractMultiple("./schemas.ts", ["UserSchema", "PostSchema"]);

// Extract by file (includes file path)
const fileResult = extractor.extractFile("./schemas.ts");
// fileResult: { filePath: string; schemas: ExtractResult[] }

// List schema names
const schemaNames = extractor.getSchemaNames("./schemas.ts");

Type Test Generation

zinfer can automatically generate vitest tests that verify the generated types match z.input<typeof Schema> / z.output<typeof Schema>.

Usage

# Generate type definitions and tests simultaneously
zinfer "src/schemas/*.ts" --outDir ./types --generate-tests --suffix Schema
# -> ./types/user.ts (type definitions)
# -> ./types/user.test.ts (tests)

# When outputting to a single file
zinfer "src/schemas/*.ts" --outFile ./types.ts --generate-tests --suffix Schema
# -> ./types.ts (type definitions)
# -> ./types.test.ts (tests)

# Run the tests
vitest run

Example Generated Test

import { describe, it, expectTypeOf } from "vitest";
import type { z } from "zod";

import { UserSchema } from "../schemas/user";
import type { UserInput, UserOutput } from "./user";

describe("Type equality tests", () => {
  describe("user", () => {
    it("UserSchema input matches z.input", () => {
      expectTypeOf<UserInput>().toEqualTypeOf<z.input<typeof UserSchema>>();
    });

    it("UserSchema output matches z.output", () => {
      expectTypeOf<UserOutput>().toEqualTypeOf<z.output<typeof UserSchema>>();
    });
  });
});

Re-run with --generate-tests after modifying schemas to continuously verify type correctness.

Supported Zod Features

• Primitives: z.string(), z.number(), z.boolean(), z.date(), etc.
• Objects: z.object()
• Arrays: z.array()
• Union: z.union(), z.discriminatedUnion()
• Intersection: z.intersection(), .and(), .merge()
• Enum: z.enum(), z.nativeEnum()
• Optional/Nullable: .optional(), .nullable()
• Transform: .transform()
• Refine: .refine(), .superRefine()
• Utilities: .partial(), .pick(), .omit(), .extend()
• Circular references: z.lazy(), getter patterns
• Descriptions: .describe()
• Branded types: .brand()
• Imported schemas: relative imports and subpath imports (package.json imports field, including the #/* form)

Inlining Type References (--inline-type-references)

When a schema carries an explicit z.ZodType<T> annotation and T reaches a plain (non-Zod) type/interface/enum declared in another file, TypeScript prints an import("...").Name reference to it rather than expanding it - there is nothing else visible to print from that location. By default zinfer keeps that reference (rewritten to resolve correctly from wherever the output is written). Setting --inline-type-references replaces it with the referenced type's own structure instead, recursively, so the generated output carries no dependency on the original file layout - useful when generated files are moved, published, or read outside the project that declares those types.

The flag takes a scope, defaulting to project when given with no value:

• --inline-type-references / --inline-type-references=project - follows a reference into another file of this project.
• --inline-type-references=all - also follows a reference into a plain type declared in a dependency package, resolved through TypeScript's own module resolution (not filesystem probing).

// field.types.ts
export type FieldType = "uuid" | "string" | "number" | "boolean";
export type FieldOutput = { type: FieldType; fields?: Record<string, FieldOutput> };

// field.schema.ts
import { z } from "zod";
import type { FieldOutput } from "./field.types";

export const FieldSchema: z.ZodType<FieldOutput> = z.lazy(() =>
  z.object({
    type: z.enum(["uuid", "string", "number", "boolean"]),
    fields: z.record(z.string(), FieldSchema).optional(),
  }),
);

Without the flag, FieldType is referenced:

export type FieldOutput = {
  type: import("./field.types").FieldType;
  fields?: Record<string, FieldOutput>;
};

With --inline-type-references, it's expanded in place:

export type FieldOutput = {
  type: "uuid" | "string" | "number" | "boolean";
  fields?: Record<string, FieldOutput>;
};

The expansion follows references across as many files as needed. A reference that would recurse into itself - directly, or by cycling back through another file - is left as an import(...) at the point it would repeat; everything outside the cycle is still fully expanded. A same-file type that isn't exported has no importable name to fall back to, so a cycle through one is left as a bare (unresolved) identifier - the same known limitation nonexported-explicit-type-schema.ts documents for a local explicit annotation. Namespace imports (import * as ns), default-imported types, and generic instantiations (import("...").Foo<Bar>) aren't expanded either; each is left as the reference zinfer would otherwise print.

A reference through a bare package specifier (import("some-lib").Foo, as opposed to a relative path within the project) is left as a reference under project scope, same as any other unexpanded case above - but expanded under all scope, as long as it actually resolves to a file (a declare module "some-lib" { ... } ambient module with no backing file does not, and is left as a reference under either scope). This is what lets a type declared in a devDependency be inlined: without it, the generated output keeps import("some-lib").Foo, which resolves inside this project but not for a consumer who installs the published package without that dev-only dependency. all scope exposes that dependency's own type structure in the generated output, so weigh that against the output-size and encapsulation cost before turning it on for a published package. Resolution is identity-based - "does this specifier resolve to a real file" - not name-based, so a package typed via a separate @types/* package is expanded the same as one that ships its own types; only an ambient module with no backing file at all is exempt.

This only applies to a plain type reached through an explicit z.ZodType<T> annotation - a Zod schema imported from another file is unaffected, and continues to be referenced by its own generated type name or inlined as already described elsewhere in this document.

Subpath Imports

Schemas imported via the package.json imports field are resolved automatically, including the #/* wildcard form supported by TypeScript 6 / Node 26.

// package.json
{
  "imports": {
    "#/*": "./src/*"
  }
}

// src/user.ts
import { z } from "zod";
import { AddressSchema } from "#/address.js";

export const UserSchema = z.object({
  name: z.string(),
  address: AddressSchema,
});

The imported AddressSchema is resolved through the nearest package.json imports map (wildcard, exact, and conditional targets are all supported) so that its type is inlined into the generated output.

License

MIT

Upstream API compatibility checks

Contributors can run pnpm test:api from the monorepo root to detect upstream API additions and removals during dependency updates. See the API review gate for the review, fixture, and baseline-update procedure.