Skip to content

Update zod 4.0.14 → 4.1.5 (minor) #231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
depfu wants to merge 1 commit into from
Closed

Update zod 4.0.14 → 4.1.5 (minor) #231

depfu wants to merge 1 commit into from

Conversation

@depfu
Copy link
Contributor

@depfu depfu bot commented Aug 29, 2025

Here is everything you need to know about this update. Please take a good look at what changed and the test results before merging this pull request.

What changed?

✳️ zod (4.0.14 → 4.1.5) · Repo · Changelog

Release Notes

4.1.5

Commits:

4.1.4

Commits:

  • 3291c61 fix(v4): toJSONSchema - wrong tuple with null output when targeting openapi-3.0 (#5156)
  • 23f41c7 test(v4): toJSONSchema - use validateOpenAPI30Schema in all relevant scenarios (#5163)
  • 0a09fd2 Update installation instructions
  • 4ea5fec 4.1.4

4.1.3

Commits:

  • 98ff675 Drop stringToBoolean
  • a410616 Fix typo
  • 0cf4589 fix(v4): toJSONSchema - add missing oneOf inside items in tuple conversion (#5146)
  • 8bf0c16 fix(v4): toJSONSchema tuple path handling for draft-7 with metadata IDs (#5152)
  • 5c5fa90 fix(v4): toJSONSchema - wrong record output when targeting openapi-3.0 (#5141)
  • 87b97cc docs(codecs): update example to use payloadSchema (#5150)
  • 309f358 fix(v4): toJSONSchema - output numbers with exclusive range correctly when targeting openapi-3.0 (#5139)
  • 1e71ca9 docs: fix refine fn to encode works properly (#5148)
  • a85ec3c fix(docs): correct example to use LooseDog instead of Dog (#5136)
  • 3e98274 4.1.3

4.1.2

Commits:

  • e45e61b Improve codec docs
  • 25a4c37 fix(v4): toJSONSchema - wrong record tuple output when targeting openapi-3.0 (#5145)
  • 0fa4f46 Use method form in codecs.mdx
  • 940383d Update JSON codec and docs
  • 3009fa8 4.1.2

4.1.1

Commits:

4.1.0

The first minor version since the introduction of Zod 4 back in May. This version contains a number of features that barely missed the cut for the 4.0 release. With Zod 4 stable and widely adopted, there's more time to resume feature development.

Codecs

This is the flagship feature of this release. Codecs are a new API & schema type that encapsulates a bi-directional transformation. It's a huge missing piece in Zod that's finally filled, and it unlocks some totally new ways to use Zod.

const stringToDate = z.codec(
  z.iso.datetime(),  // input schema: ISO date string
  z.date(),          // output schema: Date object
  {
    decode: (isoString) => new Date(isoString), 
    encode: (date) => date.toISOString(),
  }
);

New top-level functions are added for processing inputs in the forward direction ("decoding") and backward direction ("encoding").

stringToDate.decode("2025-08-21T20:59:45.500Z")
// => Date

stringToDate.encode(new Date())

// => "2025-08-21T20:59:45.500Z"

Note — For bundle size reasons, these new methods have not added to Zod Mini schemas. Instead, this functionality is available via equivalent top-level functions.

// equivalent at runtime
z.decode(stringToDate, "2024-01-15T10:30:00.000Z");
z.encode(stringToDate, new Date());

.parse() vs .decode()

Both .parse() and decode() process data in the "forward" direction. They behave identically at runtime.

stringToDate.parse("2025-08-21T20:59:45.500Z");
stringToDate.decode("2025-08-21T20:59:45.500Z");

There is an important difference however. While .parse() accepts any input, .decode() expects a strongly typed input. That is, it expects an input of type string, whereas .parse() accepts unknown.

stringToDate.parse(Symbol('not-a-string'));
// => fails at runtime, but no TypeScript error

stringToDate.decode(Symbol("not-a-string"));

//                     ^ ❌ Argument of type 'symbol' is not assignable to parameter of type 'Date'. ts(2345)

This is a highly requested feature unto itself:

Encoding

You can use any Zod schema with .encode(). The vast majority of Zod schemas are non-transforming (the input and output types are identical) so .decode() and .encode() behave identically. Only certain schema types change their behavior:

  • Codecs — runs from B->A and executes the encode transform during encoding
  • Pipes — these execute B->A instead of A->B
  • Defaults and prefaults — Only applied in the forward direction
  • Catch — Only applied in the forward direction

Note — To avoid increasing bundle size unnecessarily, these new methods are not available on Zod Mini schemas. For those schemas, equivalent top-level functions are provided.

The usual async and safe variants exist as well:

// decode methods
stringToDate.decode("2024-01-15T10:30:00.000Z")
await stringToDate.decodeAsync("2024-01-15T10:30:00.000Z")
stringToDate.safeDecode("2024-01-15T10:30:00.000Z")
await stringToDate.safeDecodeAsync("2024-01-15T10:30:00.000Z")

// encode methods

stringToDate.encode(new Date())

await stringToDate.encodeAsync(new Date())

stringToDate.safeEncode(new Date())

await stringToDate.safeEncodeAsync(new Date())

Example codecs

Below are some "worked examples" for some commonly-needed codecs. These examples are all tested internally for correctness. Just copy/paste them into your project as needed. There is a more comprehensive set available at zod.dev/codecs.

stringToBigInt

Converts bigint into a serializable form.

const stringToBigInt = z.codec(z.string(), z.bigint(), {
  decode: (str) => BigInt(str),
  encode: (bigint) => bigint.toString(),
});

stringToBigInt.decode("12345");  // => 12345n

stringToBigInt.encode(12345n);   // => "12345"

json

Parses/stringifies JSON data.

const jsonCodec = z.codec(z.string(), z.json(), {
  decode: (jsonString, ctx) => {
    try {
      return JSON.parse(jsonString);
    } catch (err: any) {
      ctx.issues.push({
        code: "invalid_format",
        format: "json_string",
        input: jsonString,
        message: err.message,
      });
      return z.NEVER;
    }
  },
  encode: (value) => JSON.stringify(value),
});

To further validate the data, .pipe() the result of this codec into another schema.

const Params = z.object({ name: z.string(), age: z.number() });
const JsonToParams = jsonCodec.pipe(Params);

JsonToParams.decode('{"name":"Alice","age":30}');  // => { name: "Alice", age: 30 }

JsonToParams.encode({ name: "Bob", age: 25 });     // => '{"name":"Bob","age":25}'

Further reading

For more examples and a technical breakdown of how encoding works, reads theannouncement blog post and new Codecs docs page. The docs page contains implementations for several other commonly-needed codecs:

.safeExtend()

The existing way to add additional fields to an object is to use .extend().

const A = z.object({ a: z.string() })
const B = A.extend({ b: z.string() })

Unfortunately this is a bit of a misnomer, as it allows you to overwrite existing fields. This means the result of .extend() may not literally extend the original type (in the TypeScript sense).

const A = z.object({ a: z.string() }) // { a: string }
const B = A.extend({ a: z.number() }) // { a: number }

To enforce true extends logic, Zod 4.1 introduces a new .safeExtend() method. This statically enforces that the newly added properties conform to the existing ones.

z.object({ a: z.string() }).safeExtend({ a: z.number().min(5) }); // ✅
z.object({ a: z.string() }).safeExtend({ a: z.any() }); // ✅
z.object({ a: z.string() }).safeExtend({ a: z.number() });
//                                       ^  ❌ ZodNumber is not assignable

Importantly, this new API allows you to safely extend objects containing refinements.

const AB = z.object({ a: z.string(), b: z.string() }).refine(val => val.a === val.b);
const ABC = AB.safeExtend({ c: z.string() });
// ABC includes the refinements defined on AB

Previously (in Zod 4.x) any refinements attached to the base schema were dropped in the extended result. This was too unexpected. It now throws an error. (Zod 3 did not support extension of refined objects either.)

z.hash()

A new top-level string format for validating hashes produced using various common algorithms & encodings.

const md5Schema = z.hash("md5");          
// => ZodCustomStringFormat<"md5_hex">

const sha256Base64 = z.hash("sha256", { enc: "base64" });

// => ZodCustomStringFormat<"sha256_base64">

The following hash algorithms and encodings are supported. Each cell provides information about the expected number of characters/padding.

Algorithm / Encoding "hex" "base64" "base64url"
"md5" 32 24 (22 + "==") 22
"sha1" 40 28 (27 + "=") 27
"sha256" 64 44 (43 + "=") 43
"sha384" 96 64 (no padding) 64
"sha512" 128 88 (86 + "==") 86

z.hex()

To validate hexadecimal strings of any length.

const hexSchema = z.hex();

hexSchema.parse("123abc");    // ✅ "123abc"

hexSchema.parse("DEADBEEF");  // ✅ "DEADBEEF" 

hexSchema.parse("xyz");       // ❌ ZodError

Additional changes

  1. z.uuid() now supports the "Max UUID" (FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF) per the RFC
  2. $ZodFunction is now a subtype of $ZodType

Commits

4.0.17

Commits:

4.0.16

Commits:

4.0.15

Commits:

  • 7e7e346 Clean up docs
  • f2949a8 [docs] Fix migration guide upgrade command (#5021)
  • d43cf19 Fix recursive object initialization errors with check() and other methods (#5018)
  • 3de2b63 fix: remove redundant Required<> from input and output type definitions (#5033)
  • 93553bd Add needs info
  • 03cfa8d 4.0.15

Does any of this look wrong? Please let us know.

Commits

See the full diff on Github. The new version differs by 62 commits:

Depfu Status

Depfu will automatically keep this PR conflict-free, as long as you don't add any commits to this branch yourself. You can also trigger a rebase manually by commenting with @depfu rebase.

All Depfu comment commands
@​depfu rebase
Rebases against your default branch and redoes this update
@​depfu recreate
Recreates this PR, overwriting any edits that you've made to it
@​depfu merge
Merges this PR once your tests are passing and conflicts are resolved
@​depfu cancel merge
Cancels automatic merging of this PR
@​depfu close
Closes this PR and deletes the branch
@​depfu reopen
Restores the branch and reopens this PR (if it's closed)
@​depfu pause
Ignores all future updates for this dependency and closes this PR
@​depfu pause [minor|major]
Ignores all future minor/major updates for this dependency and closes this PR
@​depfu resume
Future versions of this dependency will create PRs again (leaves this PR as is)
Go to the Depfu Dashboard to see the state of your dependencies and to customize how Depfu works.

@depfu depfu bot added the depfu label Aug 29, 2025
@depfu depfu bot mentioned this pull request Aug 29, 2025
Closed
@depfu
Copy link
Contributor Author

depfu bot commented Sep 12, 2025

Closed in favor of #237.

@depfu depfu bot closed this Sep 12, 2025
@depfu depfu bot deleted the depfu/update/npm/zod-4.1.5 branch September 12, 2025 19:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

depfu

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant