express-zod-api 24.6.2 → 25.0.0-beta.3

package/CHANGELOG.md

@@ -1,18 +1,17 @@
 # Changelog
 
-## Version 24
+## Version 25
+
+### v25.0.0
 
-### v24.6.2
+- 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`;
 
-- Correcting recommendations given in [v24.6.0](#v2460) regarding using with `zod@^4.0.0`:
-  - 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);
-  - Then you MAY `import { z } from "zod"`;
-  - Otherwise, you MUST keep `import { z } from "zod/v4"`;
-  - In some cases module augmentation (Zod plugin) did not work and caused schema assignment errors for some users;
-  - The issue was reported by [@MichaelHindley](https://github.com/MichaelHindley);
-- This potential inconvenience will be resolved by dropping `zod@^3` in the next version of Express Zod API:
-  - If you're having troubles using the framework with `zod@^4.0.0`, consider upgrading to v25 (currently beta).
+## Version 24
 
 ### v24.6.1
 
@@ -26,8 +25,7 @@
 ### v24.6.0
 
 - Supporting `zod` versions `^3.25.35 || ^4.0.0`:
-  - If you use `zod@^4.0.0` then you MAY `import { z } from "zod"`:
-    - If facing error, ensure `moduleResolution` in your `tsconfig.json` is either `node16`, `nodenext` or `bundler`;
+  - 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).
 

package/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).
@@ -85,7 +84,6 @@ Therefore, many basic tasks can be accomplished faster and easier, in particular
 
 These people contributed to the improvement of the framework by reporting bugs, making changes and suggesting ideas:
 
-[<img src="https://github.com/MichaelHindley.png" alt="@MichaelHindley" width="50px" />](https://github.com/MichaelHindley)
 [<img src="https://github.com/zoton2.png" alt="@zoton2" width="50px" />](https://github.com/zoton2)
 [<img src="https://github.com/ThomasKientz.png" alt="@ThomasKientz" width="50px" />](https://github.com/ThomasKientz)
 [<img src="https://github.com/james10424.png" alt="@james10424" width="50px" />](https://github.com/james10424)
@@ -177,11 +175,7 @@ pnpm add express-zod-api express zod typescript http-errors
 pnpm add -D @types/express @types/node @types/http-errors
 ```
 
-## Environment preparation
-
-Consider using the recommended `tsconfig.json` base for your project according to your Node.js version,
-for example [the base for Node.js 20+](https://github.com/tsconfig/bases/blob/main/bases/node20.json).
-Ensure having the following options in order to make it work as expected:
+Ensure having the following options in your `tsconfig.json` file in order to make it work as expected:
 
 ```json
 {
@@ -192,8 +186,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
@@ -215,7 +207,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", ...]
@@ -327,7 +319,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";
 
@@ -457,7 +449,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({
@@ -498,7 +490,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({
@@ -529,7 +521,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
@@ -582,7 +574,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({
@@ -757,7 +749,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: {
@@ -792,7 +784,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,
@@ -917,7 +909,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",
@@ -957,7 +949,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({
@@ -1035,7 +1027,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({
@@ -1178,7 +1170,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
@@ -1203,7 +1195,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,
@@ -1360,7 +1352,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";
 
@@ -1385,18 +1377,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
@@ -1405,7 +1385,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>>);
@@ -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) => any, 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 };