runzod

A codemod to migrate from runtypes to zod.

Features

• Transforms imports/requires from runtypes to zod
• Converts type definitions to zod schemas
• Updates validation methods (check → parse, guard → safeParse)
• Converts Static to z.infer
• Works with TypeScript files
• Preserves code style and formatting

Installation

pnpm dlx runzod <path-to-your-code>

Usage

runzod <directory> [options]

Options

• --dry: Do not write to files, just show what would be changed
• --extensions: File extensions to process (default: ts,tsx)
• --help, -h: Show help message
• --verbose, -v: Show more information during processing

Examples

# Transform all TypeScript files in the src directory
pnpm dlx runzod ./src

# Dry run to see what would be changed
pnpm dlx runzod ./src --dry

# Transform only specific file extensions
pnpm dlx runzod ./src --extensions ts,tsx

# Show verbose output
pnpm dlx runzod ./src -v

Transformations

Runtypes	Zod
import { String } from 'runtypes'	import { z } from 'zod'
String	z.string()
Number	z.number()
Boolean	z.boolean()
BigInt	z.bigint()
Undefined	z.undefined()
Null	z.null()
Array(String)	z.array(z.string())
Tuple(String, Number)	z.tuple([z.string(), z.number()])
Object({...})	z.object({...})
Record(String, Number)	z.record(z.string(), z.number())
Union(A, B, C)	z.union([A, B, C])
Intersect(A, B)	z.intersection([A, B])
Literal(x)	z.literal(x)
Optional(String)	z.string().optional()
String.optional()	z.string().optional()
String.withConstraint(...)	z.string().refine(...)
String.withBrand("Brand")	z.string().brand("Brand")
Type.check(data)	Type.parse(data)
Type.guard(data)	Type.safeParse(data)
Static<typeof Type>	z.infer<typeof Type>

Examples

Basic Usage

// Before (runtypes)
import { String, Number, Boolean, Array, Object, type Static } from "runtypes";

const User = Object({
  name: String,
  age: Number,
  isActive: Boolean,
  tags: Array(String),
});

type User = Static<typeof User>;

if (User.guard(data)) {
  console.log(`User ${data.name} is ${data.age} years old`);
}

// After (zod)
import { z } from "zod";

const User = z.object({
  name: z.string(),
  age: z.number(),
  isActive: z.boolean(),
  tags: z.array(z.string()),
});

type User = z.infer<typeof User>;

const result = User.safeParse(data);
if (result.success) {
  console.log(`User ${result.data.name} is ${result.data.age} years old`);
}

Branded Types

// Before (runtypes)
import { String, withBrand, type Static } from "runtypes";

const UserId = String.withBrand("UserId");
type UserId = Static<typeof UserId>;

// After (zod)
import { z } from "zod";

const UserId = z.string().brand("UserId");
type UserId = z.infer<typeof UserId>;

Limitations

The codemod handles most common cases, but there are some limitations:

• Complex constraints may need manual adjustment
• The match pattern from runtypes needs manual conversion to zod patterns
• Recursive types may require adjustments
• Some method chaining might require manual fixes
• Branded type handling might require additional changes

Post-Migration Steps

After running the codemod:

1. Add "zod" to your dependencies if it's not already there
2. Review the transformed files manually
3. Update validation logic based on zod's patterns:
   • runtype.guard(data) becomes schema.safeParse(data) (but you'll need to access result.data when success is true)
   • Error handling differs between libraries
4. Run your tests to ensure everything still works

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Test on example files
npm run test:codemod

License

MIT