v25 is for Sara Millerey González (#2741)

### Dedication


![image](https://github.com/user-attachments/assets/47dc18f9-70fa-4276-9c79-2a84ef360642)

**Sara Millerey González** was a 32 years young trans woman from Bello,
Antioquia, Colombia.
She was killed in April 2025. Millerey was raped, tortured, and thrown
into a ravine by a group of men. Denounced as a hate crime by press and
Antioquia's mayor, the Colombian National Working Group on Violence
Based on Victims' Sexual Orientation or Gender Identity is collaborating
with the Attorney's General's Office on identifying remaining suspects.

Transgender women suffer too frequently from transphobic violence and
cruelty, being the less protected social group. I'd like to raise an
awareness of this problem. Humans should be creators — not killers. But
most importantly, I want every transgender girl to have an opportunity
to create applications quickly and, in general, learn to write code
easily in order to receive job offers and leave dangerously transphobic
territories for more favorable and civilized ones, and live happily
there. Protect transgender women.

### Breaking

- `zod` version is `^4.0.0`;
  - Compatibility with `zod@^3` is dropped;
  - You SHOULD now `import { z } from "zod"` without the `/v4` suffix;
- Node.js version is `^20.19.0 || ^22.12.0 || ^24.0.0`;
  - The framework distribution is now ESM-only (finally);
  - All the Node.js versions listed above support `require(ESM)` syntax;
- Changes to the `Middleware` class:
- When the `input` schema is not defined, the `input` argument of the
`handler` method is now `unknown`;
- Plugin changes to metadata:
  - `example` removed;
  - object-based `examples` removed (only array remains);
- use either `.example()` or `.meta({})` with `examples` being an array.
- Public `getExamples()` helper removed:
  - use `.meta()?.examples` or `globalRegistry.get()?.examples` instead.

### Content

- #2622 
- #2711 
- #2740 
- #2742 
- #2777 
- #2809 
- #2814 
- #2815 
- #2842 
- #2843 
- #2844 

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Summary by CodeRabbit

* **New Features**
* Dropped support for Zod v3; now requires Zod v4 and updates all
imports to use `"zod"` directly.
* Framework is now distributed as ESM-only and supports Node.js
^20.19.0, ^22.12.0, or ^24.0.0.
  * Introduced a unified empty schema utility for input/output defaults.
* Added Vitest configuration with experimental eventsource flag for
testing.

* **Breaking Changes**
* Removed the public `getExamples()` helper; access examples via
`.meta()?.examples` or the global registry.
* Middleware and factory input schemas now default to `undefined` when
omitted, not an empty object schema.
* Dropped support for object-based `examples` in schema metadata; use
`.example()` or array-based `examples` instead.
* Removed deprecated enum and literal depicters from documentation
helpers.
* Updated import paths from `"zod/v4"` to `"zod"` throughout codebase
and examples.
* Adjusted migration rules to reflect import and metadata changes only.

* **Bug Fixes**
* Improved handling of empty schemas and type inference for middleware
and endpoint factories.

* **Chores**
* Updated documentation and changelogs for new Zod import paths and
version requirements.
* Updated build, test, and lint configurations for ESM-only output and
new dependency versions.
* Adjusted GitHub workflows to monitor new branches and updated Node.js
versions.
* Removed legacy migration rules and simplified migration logic focusing
on import and metadata changes.
* Removed legacy dependencies like `undici` and adjusted package
metadata.
  * Simplified ESLint and tsup configurations for ESM-only builds.
  * Updated startup logo dedication message.

* **Tests**
* Refactored and updated tests to align with new schema defaults and Zod
v4 usage.
* Simplified migration tests and rules to focus on import path changes.
  * Added tests for new empty schema utilities.

* **Style**
  * Updated dedication message in the startup logo.

* **Revert**
* Removed legacy and deprecated migration logic and configuration
overrides.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: RobinTail

.github/workflows/codeql-analysis.yml

@@ -13,10 +13,10 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ master, v20, v21, v22, v23 ]
+    branches: [ master, v21, v22, v23, v24 ]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [ master, v20, v21, v22, v23 ]
+    branches: [ master, v21, v22, v23, v24 ]
   schedule:
     - cron: '26 8 * * 1'
 

.github/workflows/node.js.yml

@@ -5,17 +5,17 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ master, v20, v21, v22, v23 ]
+    branches: [ master, v21, v22, v23, v24 ]
   pull_request:
-    branches: [ master, v20, v21, v22, v23 ]
+    branches: [ master, v21, v22, v23, v24 ]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        node-version: [20.9.0, 20.x, 22.0.0, 22.x, 24.0.0, 24.x]
+        node-version: [20.19.0, 20.x, 22.12.0, 22.x, 24.0.0, 24.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
     steps:
     - name: Checkout

CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## Version 25
+
+### v25.0.0
+
+- Supported Node.js versions: `^20.19.0 || ^22.12.0 || ^24.0.0`:
+- The framework distribution is now ESM-only (finally);
+  - All the Node.js versions listed above support `require(ESM)` syntax;
+  - If facing TypeScript error `TS1479`, ensure either:
+    - using the [recommended tsconfig base for Node 20+](https://github.com/tsconfig/bases/blob/main/bases/node20.json);
+    - or switching your project to ESM by setting `"type": "module"` in `package.json`;
+- Supported `zod` version: `^4.0.0`;
+  - Compatibility with `zod@^3` is dropped;
+  - You SHOULD now `import { z } from "zod"` without the `/v4` suffix;
+- Changes to the Zod plugin and metadata processing:
+  - Dropped support of examples that are given as `example` property of `.meta()` argument;
+  - Dropped support of examples given within an object-based value of `examples` property of `.meta()` argument;
+  - Use either `.example()` method or `.meta()` method with `examples` property being an array;
+- Changes to the `Middleware` class:
+  - When the `input` schema is not defined, the `input` argument of the `handler` method is now `unknown`;
+- Changes to publicly exposed method:
+  - The `getExamples()` helper is removed, use `.meta().examples` or `globalRegistry.get().examples` instead.
+- Consider [the automated migration](https://www.npmjs.com/package/@express-zod-api/migration).
+
+```diff
+- z.string().meta({ example: "test" });
+- z.string().meta({ examples: { one: { value: "test" } } });
++ z.string().meta({ examples: ["test"] });
++ z.string().example("test").example("another"); // plugin method
+```
+
+```diff
+- getExamples(schema);
++ schema.meta()?.examples || [];
++ globalRegistry.get(schema)?.examples || [];
+```
+
 ## Version 24
 
 ### v24.7.3

README.md

@@ -58,8 +58,7 @@ Start your API server with I/O schema validation and custom middlewares in minut
    5. [Graceful shutdown](#graceful-shutdown)
    6. [Subscriptions](#subscriptions)
 8. [Caveats](#caveats)
-   1. [Zod 4 schema assignment error](#zod-4-schema-assignment-error)
-   2. [Excessive properties in endpoint output](#excessive-properties-in-endpoint-output)
+   1. [Excessive properties in endpoint output](#excessive-properties-in-endpoint-output)
 9. [Your input to my output](#your-input-to-my-output)
 
 See also [Changelog](CHANGELOG.md) and [automated migration](https://www.npmjs.com/package/@express-zod-api/migration).
@@ -193,8 +192,6 @@ Ensure having the following options in order to make it work as expected:
 }
 ```
 
-See also how `moduleResolution` may cause [Zod 4 schema assignment error](#zod-4-schema-assignment-error).
-
 ## Set up config
 
 Create a minimal configuration. Find out all configurable options
@@ -216,7 +213,7 @@ Learn how to make factories for [custom response](#response-customization) and b
 
 ```typescript
 import { defaultEndpointsFactory } from "express-zod-api";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 const helloWorldEndpoint = defaultEndpointsFactory.build({
   // method: "get" (default) or array ["get", "post", ...]
@@ -328,7 +325,7 @@ Inputs of middlewares are also available to endpoint handlers within `input`.
 Here is an example of the authentication middleware, that checks a `key` from input and `token` from headers:
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "zod";
 import createHttpError from "http-errors";
 import { Middleware } from "express-zod-api";
 
@@ -458,7 +455,7 @@ You can implement additional validations within schemas using refinements.
 Validation errors are reported in a response with a status code `400`.
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "zod";
 import { Middleware } from "express-zod-api";
 
 const nicknameConstraintMiddleware = new Middleware({
@@ -499,7 +496,7 @@ Since parameters of GET requests come in the form of strings, there is often a n
 arrays of numbers.
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "zod";
 
 const getUserEndpoint = endpointsFactory.build({
   input: z.object({
@@ -530,7 +527,7 @@ Here is a recommended solution: it is important to use shallow transformations o
 ```ts
 import camelize from "camelize-ts";
 import snakify from "snakify-ts";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 const endpoint = endpointsFactory.build({
   input: z
@@ -583,7 +580,7 @@ provides your endpoint handler or middleware with a `Date`. It supports the foll
 format for the response transmission. Both schemas accept metadata as an argument. Consider the following example:
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "zod";
 import { ez, defaultEndpointsFactory } from "express-zod-api";
 
 const updateUserEndpoint = defaultEndpointsFactory.build({
@@ -758,7 +755,7 @@ In a similar way you can enable request headers as the input source. This is an
 
 ```typescript
 import { createConfig, Middleware } from "express-zod-api";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 createConfig({
   inputSources: {
@@ -793,7 +790,7 @@ type DefaultResponse<OUT> =
 You can create your own result handler by using this example as a template:
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "zod";
 import {
   ResultHandler,
   ensureHttpError,
@@ -918,7 +915,7 @@ which is `express.urlencoded()` by default. The request content type should be `
 
 ```ts
 import { defaultEndpointsFactory, ez } from "express-zod-api";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 export const submitFeedbackEndpoint = defaultEndpointsFactory.build({
   method: "post",
@@ -958,7 +955,7 @@ const config = createConfig({
 Then use `ez.upload()` schema for a corresponding property. The request content type must be `multipart/form-data`:
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "zod";
 import { ez, defaultEndpointsFactory } from "express-zod-api";
 
 const fileUploadEndpoint = defaultEndpointsFactory.build({
@@ -1036,7 +1033,7 @@ from outputs of previous middlewares, if the one being tested somehow depends on
 either by `errorHandler` configured within given `configProps` or `defaultResultHandler`.
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "zod";
 import { Middleware, testMiddleware } from "express-zod-api";
 
 const middleware = new Middleware({
@@ -1179,7 +1176,7 @@ You can also deprecate all routes the `Endpoint` assigned to by setting `Endpoin
 
 ```ts
 import { Routing, DependsOnMethod } from "express-zod-api";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 const someEndpoint = factory.build({
   deprecated: true, // deprecates all routes the endpoint assigned to
@@ -1204,7 +1201,7 @@ need to reuse a handling rule for multiple brands, use the exposed types `Depict
 
 ```ts
 import ts from "typescript";
-import { z } from "zod/v4";
+import { z } from "zod";
 import {
   Documentation,
   Integration,
@@ -1361,7 +1358,7 @@ Client application can subscribe to the event stream using `EventSource` class i
 the implementation emitting the `time` event each second.
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "zod";
 import { EventStreamFactory } from "express-zod-api";
 import { setTimeout } from "node:timers/promises";
 
@@ -1386,18 +1383,6 @@ framework, [Zod Sockets](https://github.com/RobinTail/zod-sockets), which has si
 There are some well-known issues and limitations, or third party bugs that cannot be fixed in the usual way, but you
 should be aware of them.
 
-## Zod 4 schema assignment error
-
-When using `zod@^4` and doing `import { z } from "zod"` you may encounter the following error:
-
-```text
-TS2739: ZodObject<...> is missing the following properties from ZodType<...>: example, deprecated.
-```
-
-In this case make sure the `moduleResolution` in your `tsconfig.json` is either `node16`, `nodenext` or `bundler`.
-Consider the [recommended tsconfig base, Node 20+](https://github.com/tsconfig/bases/blob/main/bases/node20.json).
-Otherwise, keep importing `from "zod/v4"` or consider upgrading the framework to v25.
-
 ## Excessive properties in endpoint output
 
 The schema validator removes excessive properties by default. However, Typescript
@@ -1406,7 +1391,7 @@ in this case during development. You can achieve this verification by assigning
 reusing it in forced type of the output:
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "zod";
 
 const output = z.object({
   anything: z.number(),

SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Code name     | Release |     Supported      |
 | ------: | :------------ | :------ | :----------------: |
+|  25.x.x | Sara          | 08.2025 | :white_check_mark: |
 |  24.x.x | Ashley        | 06.2025 | :white_check_mark: |
 |  23.x.x | Sonia         | 04.2025 | :white_check_mark: |
 |  22.x.x | Tai           | 01.2025 | :white_check_mark: |

compat-test/eslint.config.js

@@ -3,5 +3,5 @@ import migration from "@express-zod-api/migration";
 
 export default [
   { languageOptions: { parser }, plugins: { migration } },
-  { files: ["**/*.ts"], rules: { "migration/v24": "error" } },
+  { files: ["**/*.ts"], rules: { "migration/v25": "error" } },
 ];

compat-test/migration.spec.ts

@@ -4,6 +4,6 @@ import { describe, test, expect } from "vitest";
 describe("Migration", () => {
   test("should fix the import", async () => {
     const fixed = await readFile("./sample.ts", "utf-8");
-    expect(fixed).toBe('import {} from "zod/v4";\n');
+    expect(fixed).toBe('import {} from "zod";\n');
   });
 });

compat-test/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "pretest": "echo 'import {} from \"zod\";' > sample.ts",
+    "pretest": "echo 'import {} from \"zod/v4\";' > sample.ts",
     "test": "eslint --fix && vitest --run",
     "posttest": "rm sample.ts"
   },
@@ -15,6 +15,6 @@
     "http-errors": "npm:[email protected]",
     "typescript": "npm:[email protected]",
     "typescript-eslint": "npm:[email protected]",
-    "zod": "npm:zod@3.25.35"
+    "zod": "npm:zod@4.0.0"
   }
 }

eslint.config.js

@@ -23,10 +23,6 @@ const importConcerns = [
     selector: "ImportDeclaration[source.value=/^zod/] > ImportDefaultSpecifier",
     message: "do import { z } instead",
   },
-  {
-    selector: "ImportDeclaration[source.value='zod'] > ImportSpecifier",
-    message: "should import from zod/v4", // @todo remove when zod version changed to 4.0.0
-  },
   ...builtinModules.map((mod) => ({
     selector: `ImportDeclaration[source.value='${mod}']`,
     message: `use node:${mod} for the built-in module`,

example/endpoints/accept-raw.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v4";
+import { z } from "zod";
 import { defaultEndpointsFactory, ez } from "express-zod-api";
 
 export const rawAcceptingEndpoint = defaultEndpointsFactory.build({