npm package: @schemashift/zod-v3-v4
Description: Zod v3 to v4 upgrade transformer for SchemaShift — handles 17+ breaking changes with auto-transforms and runtime warnings
Author: Joseph May
Latest version: 0.14.0

# @schemashift/zod-v3-v4

Zod v3 → v4 upgrade transformer for SchemaShift. Handles 20+ breaking changes between Zod v3 and v4 with auto-transforms and runtime behavior warnings.

[![npm version](https://img.shields.io/npm/v/@schemashift/zod-v3-v4.svg)](https://www.npmjs.com/package/@schemashift/zod-v3-v4)
[![npm downloads](https://img.shields.io/npm/dm/@schemashift/zod-v3-v4.svg)](https://www.npmjs.com/package/@schemashift/zod-v3-v4)
[![CI](https://github.com/jdmay2/schemashift/actions/workflows/ci.yml/badge.svg)](https://github.com/jdmay2/schemashift/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**Tier:** Individual

## Installation

```bash
npm install @schemashift/zod-v3-v4
```

## Usage

```typescript
import { createZodV3ToV4Handler } from '@schemashift/zod-v3-v4';
import { TransformEngine } from '@schemashift/core';

const engine = new TransformEngine();
engine.registerHandler('zod-v3', 'v4', createZodV3ToV4Handler());
```

## Breaking Changes Handled

### Auto-Transforms

These changes are automatically applied to your code:

| v3 Pattern | v4 Pattern | Notes |
|-----------|-----------|-------|
| `z.record(valueSchema)` | `z.record(z.string(), valueSchema)` | Explicit key type required |
| `schemaA.merge(schemaB)` | `schemaA.extend(schemaB.shape)` | `.merge()` deprecated |
| `z.nativeEnum(MyEnum)` | `z.enum(MyEnum)` | `nativeEnum` renamed |
| `.superRefine(fn)` | `.check(fn)` | Callback signature identical |
| `error.errors` | `error.issues` | Property renamed |
| `{ invalid_type_error: 'msg' }` | `{ error: 'msg' }` | Unified error param |
| `{ required_error: 'msg' }` | `{ error: 'msg' }` | Unified error param |
| Both error params | `{ error: (issue) => ... }` | Function-based error |

### Deprecation Warnings

These methods still work but are deprecated in v4:

| Method | Replacement | Warning |
|--------|-------------|---------|
| `.superRefine()` | `.check()` | Auto-renamed, warning emitted |
| `.strict()` | `z.strictObject()` | Structural change, review needed |
| `.passthrough()` | `z.looseObject()` | Structural change, review needed |

### Runtime Behavior Warnings

These changes do not cause compile-time errors but silently change runtime behavior:

| Pattern | Issue |
|---------|-------|
| `instanceof Error` on ZodError | `ZodError` no longer extends `Error` in v4 |
| `.refine()` followed by `.transform()` | `.transform()` now runs even when `.refine()` fails |
| `.default()` + `.optional()` | `.default()` always provides a value, making `.optional()` a no-op |
| `.pipe()` | Stricter type checking, may need explicit type annotations |

### Other Detected Changes

| Pattern | Warning |
|---------|---------|
| `.flatten()` | Removed in v4, use `.format()` instead |
| `z.function()` | Input/output parameter changes |
| `.uuid()` | Stricter RFC 4122 validation |
| `z.discriminatedUnion()` | Stricter discriminator requirements |

## Mappings Reference

### Behavior Changes Set

Methods with changed behavior in v4: `default`, `uuid`, `record`, `discriminatedUnion`, `function`, `pipe`.

### Deprecated Methods Set

Methods deprecated in v4: `merge`, `superRefine`, `strict`, `passthrough`.

### Auto-Transformable Methods

Methods that are automatically renamed: `superRefine` → `.check()`.

### Error Property Renames

| v3 | v4 |
|----|----|
| `.errors` | `.issues` |
| `.formErrors` | `.formErrors` (unchanged) |
| `.fieldErrors` | `.fieldErrors` (unchanged) |

### Error Parameter Changes

v3 accepted `invalid_type_error` and `required_error` as separate properties. v4 unifies these under a single `error` property (string or function).

## Related Packages

- [schemashift-cli](https://www.npmjs.com/package/schemashift-cli) — CLI tool for running migrations
- [@schemashift/core](https://www.npmjs.com/package/@schemashift/core) — Core analysis engine
- [@schemashift/zod-valibot](https://www.npmjs.com/package/@schemashift/zod-valibot) — Migrate further: Zod → Valibot

## License

MIT