Using v4 from 3.25

.github/workflows/validations.yml

@@ -49,7 +49,7 @@ jobs:
           name: dist
       - name: Add dependencies
         run: |
-          yarn add express@${{matrix.express-version}} [email protected] http-errors zod@^4.0.0-beta.20250505T195954
+          yarn add express@${{matrix.express-version}} [email protected] http-errors zod@next
           yarn add -D [email protected] [email protected] vitest tsx
           yarn add express-zod-api@./dist.tgz
       - name: Run tests

CHANGELOG.md

@@ -5,8 +5,8 @@
 ### v24.0.0
 
 - Switched to Zod 4:
-  - Minimum supported version of `zod` is 4.0.0;
-  - ⚠️This version might not support all new features of Zod 4;
+  - Minimum supported version of `zod` is 3.25.0, BUT imports MUST be from `zod/v4`;
+  - Find out why it's so weird here: https://github.com/colinhacks/zod/issues/4371
   - `IOSchema` type had to be simplified down to a schema resulting to an `object`, but not an `array`;
   - Despite supporting examples by the new Zod method `.meta()`, users should still use `.example()` to set them;
   - Refer to [Migration guide on Zod 4](https://v4.zod.dev/v4/changelog) for adjusting your schemas;

README.md

@@ -213,7 +213,7 @@ import { defaultEndpointsFactory } from "express-zod-api";
 The endpoint responds with "Hello, World" or "Hello, {name}" if the name is supplied within `GET` request payload.
 
 ```typescript
-import { z } from "zod";
+import { z } from "zod/v4";
 
 const helloWorldEndpoint = defaultEndpointsFactory.build({
   // method: "get" (default) or array ["get", "post", ...]
@@ -325,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";
+import { z } from "zod/v4";
 import createHttpError from "http-errors";
 import { Middleware } from "express-zod-api";
 
@@ -455,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";
+import { z } from "zod/v4";
 import { Middleware } from "express-zod-api";
 
 const nicknameConstraintMiddleware = new Middleware({
@@ -496,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";
+import { z } from "zod/v4";
 
 const getUserEndpoint = endpointsFactory.build({
   input: z.object({
@@ -527,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";
+import { z } from "zod/v4";
 
 const endpoint = endpointsFactory.build({
   input: z
@@ -580,7 +580,7 @@ provides your endpoint handler or middleware with a `Date`. It supports the foll
 format for the response transmission. Consider the following simplified example for better understanding:
 
 ```typescript
-import { z } from "zod";
+import { z } from "zod/v4";
 import { ez, defaultEndpointsFactory } from "express-zod-api";
 
 const updateUserEndpoint = defaultEndpointsFactory.build({
@@ -790,7 +790,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";
+import { z } from "zod/v4";
 
 createConfig({
   inputSources: {
@@ -825,7 +825,7 @@ type DefaultResponse<OUT> =
 You can create your own result handler by using this example as a template:
 
 ```typescript
-import { z } from "zod";
+import { z } from "zod/v4";
 import {
   ResultHandler,
   ensureHttpError,
@@ -951,7 +951,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";
+import { z } from "zod/v4";
 
 export const submitFeedbackEndpoint = defaultEndpointsFactory.build({
   method: "post",
@@ -991,7 +991,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";
+import { z } from "zod/v4";
 import { ez, defaultEndpointsFactory } from "express-zod-api";
 
 const fileUploadEndpoint = defaultEndpointsFactory.build({
@@ -1069,7 +1069,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";
+import { z } from "zod/v4";
 import { Middleware, testMiddleware } from "express-zod-api";
 
 const middleware = new Middleware({
@@ -1180,7 +1180,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";
+import { z } from "zod/v4";
 import { EventStreamFactory } from "express-zod-api";
 import { setTimeout } from "node:timers/promises";
 
@@ -1320,7 +1320,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";
+import { z } from "zod/v4";
 
 const someEndpoint = factory.build({
   deprecated: true, // deprecates all routes the endpoint assigned to
@@ -1345,7 +1345,7 @@ need to reuse a handling rule for multiple brands, use the exposed types `Depict
 
 ```ts
 import ts from "typescript";
-import { z } from "zod";
+import { z } from "zod/v4";
 import {
   Documentation,
   Integration,
@@ -1391,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";
+import { z } from "zod/v4";
 
 const output = z.object({
   anything: z.number(),

example/endpoints/accept-raw.ts

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

example/endpoints/create-user.ts

@@ -1,6 +1,6 @@
 import createHttpError from "http-errors";
 import assert from "node:assert/strict";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { statusDependingFactory } from "../factories";
 
 /** @desc depending on the thrown error, the custom result handler of the factory responds slightly differently */

example/endpoints/delete-user.ts

@@ -1,6 +1,6 @@
 import createHttpError from "http-errors";
 import assert from "node:assert/strict";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { noContentFactory } from "../factories";
 
 /** @desc The endpoint demonstrates no content response established by its factory */

example/endpoints/list-users.ts

@@ -1,4 +1,4 @@
-import z from "zod";
+import z from "zod/v4";
 import { arrayRespondingFactory } from "../factories";
 
 /**

example/endpoints/retrieve-user.ts

@@ -1,6 +1,6 @@
 import createHttpError from "http-errors";
 import assert from "node:assert/strict";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { defaultEndpointsFactory } from "express-zod-api";
 import { methodProviderMiddleware } from "../middlewares";
 

example/endpoints/send-avatar.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import { fileSendingEndpointsFactory } from "../factories";
 import { readFile } from "node:fs/promises";
 

example/endpoints/stream-avatar.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import { fileStreamingEndpointsFactory } from "../factories";
 
 export const streamAvatarEndpoint = fileStreamingEndpointsFactory.build({

example/endpoints/submit-feedback.ts

@@ -1,5 +1,5 @@
 import { defaultEndpointsFactory, ez } from "express-zod-api";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 export const submitFeedbackEndpoint = defaultEndpointsFactory.build({
   method: "post",

example/endpoints/time-subscription.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import { setTimeout } from "node:timers/promises";
 import { eventsFactory } from "../factories";
 

example/endpoints/update-user.ts

@@ -1,6 +1,6 @@
 import createHttpError from "http-errors";
 import assert from "node:assert/strict";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { ez } from "express-zod-api";
 import { keyAndTokenAuthenticatedEndpointsFactory } from "../factories";
 

example/endpoints/upload-avatar.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import { defaultEndpointsFactory, ez } from "express-zod-api";
 import { createHash } from "node:crypto";
 

example/example.documentation.yaml

@@ -271,7 +271,7 @@ paths:
                       id:
                         type: integer
                         exclusiveMinimum: 0
-                        exclusiveMaximum: 9007199254740991
+                        maximum: 9007199254740991
                     required:
                       - id
                 required:
@@ -293,7 +293,7 @@ paths:
                       id:
                         type: integer
                         exclusiveMinimum: 0
-                        exclusiveMaximum: 9007199254740991
+                        maximum: 9007199254740991
                     required:
                       - id
                 required:
@@ -613,7 +613,7 @@ paths:
                   data:
                     type: integer
                     exclusiveMinimum: 0
-                    exclusiveMaximum: 9007199254740991
+                    maximum: 9007199254740991
                   event:
                     type: string
                     const: time
@@ -622,7 +622,7 @@ paths:
                   retry:
                     type: integer
                     exclusiveMinimum: 0
-                    exclusiveMaximum: 9007199254740991
+                    maximum: 9007199254740991
                 required:
                   - data
                   - event
@@ -676,7 +676,7 @@ paths:
                       crc:
                         type: integer
                         exclusiveMinimum: 0
-                        exclusiveMaximum: 9007199254740991
+                        maximum: 9007199254740991
                     required:
                       - crc
                 required:

example/factories.ts

@@ -9,7 +9,7 @@ import {
 } from "express-zod-api";
 import { authMiddleware } from "./middlewares";
 import { createReadStream } from "node:fs";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 /** @desc This factory extends the default one by enforcing the authentication using the specified middleware */
 export const keyAndTokenAuthenticatedEndpointsFactory =

example/middlewares.ts

@@ -1,6 +1,6 @@
 import createHttpError from "http-errors";
 import assert from "node:assert/strict";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { Method, Middleware } from "express-zod-api";
 
 export const authMiddleware = new Middleware({

express-zod-api/package.json

@@ -76,7 +76,7 @@
     "express-fileupload": "^1.5.0",
     "http-errors": "^2.0.0",
     "typescript": "^5.1.3",
-    "zod": "^4.0.0-beta.20250505T012514"
+    "zod": "3.25.0-beta.20250518T002810"
   },
   "peerDependenciesMeta": {
     "@types/compression": {

express-zod-api/src/api-response.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 
 export const defaultStatusCodes = {
   positive: 200,

express-zod-api/src/common-helpers.ts

@@ -3,10 +3,10 @@ import type {
   $ZodTransform,
   $ZodType,
   $ZodTypeInternals,
-} from "@zod/core";
+} from "zod/v4/core";
 import { Request } from "express";
 import * as R from "ramda";
-import { globalRegistry, z } from "zod";
+import { globalRegistry, z } from "zod/v4";
 import { CommonConfig, InputSource, InputSources } from "./config-type";
 import { contentTypes } from "./content-type";
 import { OutputValidationError } from "./errors";

express-zod-api/src/date-in-schema.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 
 export const ezDateInBrand = Symbol("DateIn");
 

express-zod-api/src/date-out-schema.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 
 export const ezDateOutBrand = Symbol("DateOut");
 

express-zod-api/src/deep-checks.ts

@@ -1,6 +1,6 @@
-import type { $ZodType, JSONSchema } from "@zod/core";
+import type { $ZodType, JSONSchema } from "zod/v4/core";
 import * as R from "ramda";
-import { globalRegistry, z } from "zod";
+import { globalRegistry, z } from "zod/v4";
 import { ezDateInBrand } from "./date-in-schema";
 import { ezDateOutBrand } from "./date-out-schema";
 import { DeepCheckError } from "./errors";

express-zod-api/src/diagnostics.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import { responseVariants } from "./api-response";
 import { FlatObject, getRoutePathParams } from "./common-helpers";
 import { contentTypes } from "./content-type";

express-zod-api/src/documentation-helpers.ts

@@ -5,7 +5,7 @@ import type {
   $ZodTuple,
   $ZodType,
   JSONSchema,
-} from "@zod/core";
+} from "zod/v4/core";
 import {
   ExamplesObject,
   isReferenceObject,
@@ -23,7 +23,7 @@ import {
   TagObject,
 } from "openapi3-ts/oas31";
 import * as R from "ramda";
-import { globalRegistry, z } from "zod";
+import { globalRegistry, z } from "zod/v4";
 import { ResponseVariant } from "./api-response";
 import {
   FlatObject,
@@ -45,7 +45,7 @@ import { ezDateOutBrand } from "./date-out-schema";
 import { DocumentationError } from "./errors";
 import { ezFileBrand } from "./file-schema";
 import { IOSchema } from "./io-schema";
-import { flattenIO, unref } from "./json-schema-helpers";
+import { flattenIO } from "./json-schema-helpers";
 import { Alternatives } from "./logical-container";
 import { metaSymbol } from "./metadata";
 import { Method } from "./method";
@@ -463,7 +463,6 @@ const depict = (
       unrepresentable: "any",
       io: ctx.isResponse ? "output" : "input",
       override: (zodCtx) => {
-        unref(zodCtx.jsonSchema);
         const { brand } =
           globalRegistry.get(zodCtx.zodSchema)?.[metaSymbol] ?? {};
         const depicter =

express-zod-api/src/endpoint.ts

@@ -1,6 +1,6 @@
 import { Request, Response } from "express";
 import * as R from "ramda";
-import { globalRegistry, z } from "zod";
+import { globalRegistry, z } from "zod/v4";
 import { NormalizedResponse, ResponseVariant } from "./api-response";
 import { findRequestTypeDefiningSchema } from "./deep-checks";
 import {

express-zod-api/src/endpoints-factory.ts

@@ -1,5 +1,5 @@
 import { Request, Response } from "express";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { EmptyObject, EmptySchema, FlatObject, Tag } from "./common-helpers";
 import { Endpoint, Handler } from "./endpoint";
 import { IOSchema, getFinalEndpointInputSchema } from "./io-schema";