●Change8

v4.1.0

Breaking Changes
📦 zodView on GitHub →
⚠ 1 breaking✨ 6 features🐛 1 fixes🔧 10 symbols

Summary

Zod 4.1 introduces Codecs for bi-directional data transformation and .safeExtend() for type-safe object extensions that preserve refinements. It also adds a new z.hash() validator and strongly-typed decode/encode methods.

⚠️ Breaking Changes

  • Refinements on base schemas are no longer silently dropped when using .extend(). In Zod 4.1, attempting to extend a refined object now throws an error to prevent unexpected behavior, directing users toward .safeExtend() instead.

Migration Steps

  1. Replace .extend() with .safeExtend() if you need to preserve refinements from the base object schema.
  2. Use z.decode(schema, data) instead of schema.decode(data) if using Zod Mini to keep bundle sizes optimized.
  3. Update any manual bi-directional logic to use the new z.codec() API for better type safety and consistency.

✨ New Features

  • Introduced Codecs: A new API for bi-directional transformations (decoding and encoding).
  • Added .decode() and .encode() methods to schemas for strongly-typed forward and backward data processing.
  • Added top-level z.decode() and z.encode() functions for use with Zod Mini to maintain small bundle sizes.
  • Added async and safe variants for codecs: .decodeAsync(), .safeDecode(), .safeDecodeAsync(), .encodeAsync(), .safeEncode(), and .safeEncodeAsync().
  • Introduced .safeExtend(): A new method for objects that statically enforces that new properties conform to existing ones (true TypeScript extension).
  • Added z.hash(): A new top-level string format validator for common hash algorithms (e.g., md5, sha256).

🐛 Bug Fixes

  • Fixed an issue where refinements attached to a base schema were silently dropped when using .extend().

🔧 Affected Symbols

z.codecz.decodez.encodez.hashZodObject.safeExtendZodObject.extendZodSchema.decodeZodSchema.encodeZodSchema.safeDecodeZodSchema.safeEncode