@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.

Tier: Individual

Installation

npm install @schemashift/zod-v3-v4

Usage

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 — CLI tool for running migrations
• @schemashift/core — Core analysis engine
• @schemashift/zod-valibot — Migrate further: Zod → Valibot

License

MIT