express-zod-api 24.5.0 → 25.0.0-beta.2

package/CHANGELOG.md

@@ -1,7 +1,25 @@
 # 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;
+- Supported `zod` version: `^4.0.0`;
+- Changes to the `Middleware` class:
+  - When the `input` schema is not defined, the `input` argument of the `handler` method is now `unknown`;
+
 ## Version 24
 
+### v24.6.0
+
+- Supporting `zod` versions `^3.25.35 || ^4.0.0`:
+  - If you use `zod@^4.0.0` then `import { z } from "zod"`;
+  - If you use `zod@^3.25.35` then keep `import { z } from "zod/v4"`;
+  - For more details, see the [Explanation of the versioning strategy](https://github.com/colinhacks/zod/issues/4371).
+
 ### v24.5.0
 
 - `openapi3-ts` version is `^4.5.0`;

package/README.md

@@ -206,7 +206,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", ...]
@@ -318,7 +318,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";
 
@@ -448,7 +448,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({
@@ -489,7 +489,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({
@@ -520,7 +520,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
@@ -573,7 +573,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({
@@ -748,7 +748,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: {
@@ -783,7 +783,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,
@@ -908,7 +908,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",
@@ -948,7 +948,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({
@@ -1026,7 +1026,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({
@@ -1169,7 +1169,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
@@ -1194,7 +1194,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,
@@ -1351,7 +1351,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";
 
@@ -1384,7 +1384,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(),

package/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: |

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import * as zod_v4 from 'zod/v4';
-import { z } from 'zod/v4';
+import * as zod from 'zod';
+import { z } from 'zod';
 import * as zod_v4_core from 'zod/v4/core';
 import { $ZodTypeInternals, $ZodType, SomeType, $ZodDefaultInternals, $ZodDefault, $ZodShape, $ZodLooseShape, $ZodObjectConfig, $strip, $ZodObjectInternals, $ZodObject, JSONSchema } from 'zod/v4/core';
 import compression from 'compression';
@@ -46,7 +46,7 @@ declare module "zod/v4/core" {
         default?: unknown;
     }
 }
-declare module "zod/v4" {
+declare module "zod" {
     interface ZodType<out Output = unknown, out Input = unknown, out Internals extends $ZodTypeInternals<Output, Input> = $ZodTypeInternals<Output, Input>> extends $ZodType<Output, Input, Internals> {
         /** @desc Alias for .meta({examples}), but argument is typed to ensure the correct placement for transformations */
         example(example: z.output<this>): this;
@@ -68,10 +68,11 @@ declare module "zod/v4" {
 declare const methods: ("delete" | "get" | "post" | "put" | "patch")[];
 type Method = (typeof methods)[number];
 
+/** @since zod 3.25.61 output type fixed */
+declare const emptySchema: z.ZodObject<{}, z.core.$strip>;
+type EmptySchema = typeof emptySchema;
 /** @desc this type does not allow props assignment, but it works for reading them when merged with another interface */
 type EmptyObject = z.output<EmptySchema>;
-/** Avoiding z.ZodObject<Record<string, never>, $strip>, because its z.output<> is generic "object" (external issue) */
-type EmptySchema = z.ZodRecord<z.ZodString, z.ZodNever>;
 type FlatObject = Record<string, unknown>;
 /** @link https://stackoverflow.com/a/65492934 */
 type NoNever<T, F> = [T] extends [never] ? F : T;
@@ -155,6 +156,16 @@ declare class BuiltinLogger implements AbstractLogger {
     profile(options: ProfilerOptions): () => void;
 }
 
+type Base$1 = object & {
+    [Symbol.iterator]?: never;
+};
+/** @desc The type allowed on the top level of Middlewares and Endpoints */
+type IOSchema = z.ZodType<Base$1>;
+/** EndpointsFactory schema extended type when adding a Middleware */
+type Extension<Current extends IOSchema | undefined, Inc extends IOSchema | undefined> = Current extends IOSchema ? Inc extends IOSchema ? z.ZodIntersection<Current, Inc> : Current : Inc;
+/** The Endpoint input schema type, condition wrapped into schema to make it z.output-compatible */
+type FinalInputSchema<FIN extends IOSchema | undefined, BIN extends IOSchema> = z.ZodIntersection<FIN extends IOSchema ? FIN : BIN, BIN>;
+
 type LogicalOr<T> = {
     or: T[];
 };
@@ -260,12 +271,12 @@ declare abstract class AbstractMiddleware {
         logger: ActualLogger;
     }): Promise<FlatObject>;
 }
-declare class Middleware<OPT extends FlatObject, OUT extends FlatObject, SCO extends string, IN extends IOSchema = EmptySchema> extends AbstractMiddleware {
+declare class Middleware<OPT extends FlatObject, OUT extends FlatObject, SCO extends string, IN extends IOSchema | undefined = undefined> extends AbstractMiddleware {
     #private;
     constructor({ input, security, handler, }: {
         /**
          * @desc Input schema of the Middleware, combining properties from all the enabled input sources
-         * @default z.object({})
+         * @default undefined
          * @see defaultInputSources
          * */
         input?: IN;
@@ -290,13 +301,6 @@ declare class ExpressMiddleware<R extends Request, S extends Response, OUT exten
     });
 }
 
-type Base$1 = object & {
-    [Symbol.iterator]?: never;
-};
-/** @desc The type allowed on the top level of Middlewares and Endpoints */
-type IOSchema = z.ZodType<Base$1>;
-type ConditionalIntersection<Current extends IOSchema | undefined, Inc extends IOSchema> = z.ZodIntersection<Current extends IOSchema ? Current : Inc, Inc>;
-
 declare class DependsOnMethod extends Routable {
     #private;
     constructor(endpoints: Partial<Record<Method, AbstractEndpoint>>);
@@ -559,7 +563,7 @@ interface ServerConfig extends CommonConfig {
     /**
      * @desc Custom JSON parser.
      * @default express.json()
-     * @link https://expressjs.com/en/4x/api.html#express.json
+     * @link https://expressjs.com/en/5x/api.html#express.json
      * */
     jsonParser?: RequestHandler;
     /**
@@ -575,13 +579,13 @@ interface ServerConfig extends CommonConfig {
     /**
      * @desc Custom raw parser (assigns Buffer to request body)
      * @default express.raw()
-     * @link https://expressjs.com/en/4x/api.html#express.raw
+     * @link https://expressjs.com/en/5x/api.html#express.raw
      * */
     rawParser?: RequestHandler;
     /**
      * @desc Custom parser for URL Encoded requests used for submitting HTML forms
      * @default express.urlencoded()
-     * @link https://expressjs.com/en/4x/api.html#express.urlencoded
+     * @link https://expressjs.com/en/5x/api.html#express.urlencoded
      * */
     formParser?: RequestHandler;
     /**
@@ -613,7 +617,7 @@ interface BuildProps<IN extends IOSchema, OUT extends IOSchema | z.ZodVoid, MIN
     /** @desc The schema by which the returns of the Endpoint handler is validated */
     output: OUT;
     /** @desc The Endpoint handler receiving the validated inputs, returns of added Middlewares (options) and a logger */
-    handler: Handler<z.output<ConditionalIntersection<MIN, IN>>, z.input<OUT>, OPT>;
+    handler: Handler<z.output<FinalInputSchema<MIN, IN>>, z.input<OUT>, OPT>;
     /** @desc The operation description for the generated Documentation */
     description?: string;
     /** @desc The operation summary for the generated Documentation (50 symbols max) */
@@ -642,18 +646,19 @@ interface BuildProps<IN extends IOSchema, OUT extends IOSchema | z.ZodVoid, MIN
 declare class EndpointsFactory<IN extends IOSchema | undefined = undefined, OUT extends FlatObject = EmptyObject, SCO extends string = string> {
     #private;
     protected resultHandler: AbstractResultHandler;
+    protected schema: IN;
     protected middlewares: AbstractMiddleware[];
     constructor(resultHandler: AbstractResultHandler);
-    addMiddleware<AOUT extends FlatObject, ASCO extends string, AIN extends IOSchema = EmptySchema>(subject: Middleware<OUT, AOUT, ASCO, AIN> | ConstructorParameters<typeof Middleware<OUT, AOUT, ASCO, AIN>>[0]): EndpointsFactory<ConditionalIntersection<IN, AIN>, OUT & AOUT, SCO & ASCO>;
+    addMiddleware<AOUT extends FlatObject, ASCO extends string, AIN extends IOSchema | undefined = undefined>(subject: Middleware<OUT, AOUT, ASCO, AIN> | ConstructorParameters<typeof Middleware<OUT, AOUT, ASCO, AIN>>[0]): EndpointsFactory<Extension<IN, AIN>, OUT & AOUT, SCO & ASCO>;
     use: <R extends Request, S extends Response, AOUT extends FlatObject = Record<string, never>>(nativeMw: (request: R, response: S, next: express.NextFunction) => void | Promise<void>, params_1?: {
         provider?: ((request: R, response: S) => AOUT | Promise<AOUT>) | undefined;
         transformer?: (err: Error) => Error;
-    } | undefined) => EndpointsFactory<IN, OUT & AOUT, SCO>;
-    addExpressMiddleware<R extends Request, S extends Response, AOUT extends FlatObject = EmptyObject>(...params: ConstructorParameters<typeof ExpressMiddleware<R, S, AOUT>>): EndpointsFactory<IN, OUT & AOUT, SCO>;
-    addOptions<AOUT extends FlatObject>(getOptions: () => Promise<AOUT>): EndpointsFactory<IN, OUT & AOUT, SCO>;
-    build<BOUT extends IOSchema, BIN extends IOSchema = EmptySchema>({ input, output: outputSchema, operationId, scope, tag, method, ...rest }: BuildProps<BIN, BOUT, IN, OUT, SCO>): Endpoint<ConditionalIntersection<IN, BIN>, BOUT, OUT>;
+    } | undefined) => EndpointsFactory<Extension<IN, undefined>, OUT & AOUT, SCO>;
+    addExpressMiddleware<R extends Request, S extends Response, AOUT extends FlatObject = EmptyObject>(...params: ConstructorParameters<typeof ExpressMiddleware<R, S, AOUT>>): EndpointsFactory<Extension<IN, undefined>, OUT & AOUT, SCO>;
+    addOptions<AOUT extends FlatObject>(getOptions: () => Promise<AOUT>): EndpointsFactory<Extension<IN, undefined>, OUT & AOUT, SCO>;
+    build<BOUT extends IOSchema, BIN extends IOSchema = EmptySchema>({ input, output: outputSchema, operationId, scope, tag, method, ...rest }: BuildProps<BIN, BOUT, IN, OUT, SCO>): Endpoint<FinalInputSchema<IN, BIN>, BOUT, OUT>;
     /** @desc shorthand for returning {} while having output schema z.object({}) */
-    buildVoid<BIN extends IOSchema = EmptySchema>({ handler, ...rest }: Omit<BuildProps<BIN, z.ZodVoid, IN, OUT, SCO>, "output">): Endpoint<ConditionalIntersection<IN, BIN>, z.ZodObject<{}, z.core.$strip>, OUT>;
+    buildVoid<BIN extends IOSchema = EmptySchema>({ handler, ...rest }: Omit<BuildProps<BIN, z.ZodVoid, IN, OUT, SCO>, "output">): Endpoint<FinalInputSchema<IN, BIN>, z.ZodObject<{}, z.core.$strip>, OUT>;
 }
 declare const defaultEndpointsFactory: EndpointsFactory<undefined, Record<string, never>, string>;
 /**
@@ -931,12 +936,12 @@ declare function raw(): Base;
 declare function raw<S extends $ZodShape>(extra: S): ReturnType<typeof extended<S>>;
 
 declare const ez: {
-    dateIn: ({ examples, ...rest }?: Parameters<zod_v4.ZodString["meta"]>[0]) => zod_v4_core.$ZodBranded<zod_v4.ZodPipe<zod_v4.ZodPipe<zod_v4.ZodUnion<readonly [zod_v4.ZodISODate, zod_v4.ZodISODateTime, zod_v4.ZodISODateTime]>, zod_v4.ZodTransform<Date, string>>, zod_v4.ZodDate>, symbol>;
-    dateOut: (meta?: Parameters<zod_v4.ZodString["meta"]>[0]) => zod_v4_core.$ZodBranded<zod_v4.ZodPipe<zod_v4.ZodDate, zod_v4.ZodTransform<string, Date>>, symbol>;
-    form: <S extends zod_v4_core.$ZodShape>(base: S | zod_v4.ZodObject<S>) => zod_v4_core.$ZodBranded<zod_v4.ZodObject<S, zod_v4_core.$strip>, symbol>;
-    upload: () => zod_v4_core.$ZodBranded<zod_v4.ZodCustom<express_fileupload.UploadedFile, express_fileupload.UploadedFile>, symbol>;
+    dateIn: ({ examples, ...rest }?: Parameters<zod.ZodString["meta"]>[0]) => zod_v4_core.$ZodBranded<zod.ZodPipe<zod.ZodPipe<zod.ZodUnion<readonly [zod.ZodISODate, zod.ZodISODateTime, zod.ZodISODateTime]>, zod.ZodTransform<Date, string>>, zod.ZodDate>, symbol>;
+    dateOut: (meta?: Parameters<zod.ZodString["meta"]>[0]) => zod_v4_core.$ZodBranded<zod.ZodPipe<zod.ZodDate, zod.ZodTransform<string, Date>>, symbol>;
+    form: <S extends zod_v4_core.$ZodShape>(base: S | zod.ZodObject<S>) => zod_v4_core.$ZodBranded<zod.ZodObject<S, zod_v4_core.$strip>, symbol>;
+    upload: () => zod_v4_core.$ZodBranded<zod.ZodCustom<express_fileupload.UploadedFile, express_fileupload.UploadedFile>, symbol>;
     raw: typeof raw;
-    buffer: () => zod_v4_core.$ZodBranded<zod_v4.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, symbol>;
+    buffer: () => zod_v4_core.$ZodBranded<zod.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, symbol>;
 };
 
 export { type ApiResponse, type AppConfig, type BasicSecurity, type BearerSecurity, BuiltinLogger, type CommonConfig, type CookieSecurity, DependsOnMethod, type Depicter, Documentation, DocumentationError, EndpointsFactory, EventStreamFactory, type FlatObject, type HeaderSecurity, type IOSchema, type InputSecurity, InputValidationError, Integration, type LoggerOverrides, type Method, Middleware, MissingPeerError, type OAuth2Security, type OpenIdSecurity, OutputValidationError, type Producer, ResultHandler, type Routing, RoutingError, ServeStatic, type ServerConfig, type TagOverrides, arrayEndpointsFactory, arrayResultHandler, attachRouting, createConfig, createServer, defaultEndpointsFactory, defaultResultHandler, ensureHttpError, ez, getExamples, getMessageFromError, testEndpoint, testMiddleware };