express-zod-api 28.7.4 → 29.0.0-beta.2

package/CHANGELOG.md

@@ -1,7 +1,58 @@
 # Changelog
 
+## Version 29
+
+### v29.0.0
+
+- Supported Node.js versions: `^22.19.0 || ^24.11.0 || ^26.0.0`;
+- Breaking change to the `cors` config option:
+  - Changed from `boolean | HeadersProvider` to `boolean | RequestHandler`;
+  - You can now use the well-known `cors` package or pass a conventional `RequestHandler` directly.
+- Body parsers are now applied globally rather than per-endpoint (`createServer` experience only):
+  - Endpoints can accept requests in different content types (e.g., either JSON or URL-encoded body);
+  - The `Documentation` generator continues to guess the desired request type from the input schema;
+  - Parsers retain the ability for configuration via `jsonParser`, `formParser`, and `rawParser` config options;
+  - If using `attachRouting()` in a DIY server, parsers have to be installed manually.
+- Potentially breaking changes to the server lifecycle hooks:
+  - The hooks (`beforeRouting` and `afterRouting` config options) are no longer async;
+  - `beforeRouting` now runs after the installation of globally enabled parsers;
+  - Added new `beforeParsers` hook that runs before all parsers are installed.
+- The static async method `Integration::create()` removed — use `new Integration()` instead;
+- The `createServer()` function is now synchronous — that should simplify the daily routines for beginners;
+- Added HTTP QUERY method support (RFC 10008):
+  - The QUERY method is like GET but with a body — safe, idempotent, and cacheable;
+  - Default input sources for QUERY: `["query", "body", "params"]` (from the lowest priority to highest);
+  - Supported by `Integration` and `Documentation` generators.
+- Changes to `Documentation` constructor:
+  - `serverUrl` renamed to `server` and now also accepts OpenAPI's ServerObject;
+  - `title` and `version` must be wrapped into `info`, assignable with OpenAPI's InfoObject;
+- The Documentation generator is featuring the OpenAPI 3.2.0 with better SSE support and other features;
+
+```diff
+  const config = createConfig({
+-   cors: () => ({ origin: "https://example.com" }),
++   cors: cors({ origin: "https://example.com" }), // import cors from "cors"
+  });
+- await Integration.create({});
++ new Integration({});
+- const {} = await createServer({});
++ const {} = createServer({});
+  new Documentation({
++   info: {
+      title: "Sample API",
+      version: "1.2.3",
++   },
+-   serverUrl: "https://example.com",
++   server: "https://example.com",
+  });
+```
+
 ## Version 28
 
+### v28.7.5
+
+- Small performance improvement for startup and Documentation generator (cache for request type resolution).
+
 ### v28.7.4
 
 - Centralized the `ResultHandler` error handling by `AbstractResultHandler::execute()`:
@@ -4238,9 +4289,7 @@ import { z } from "express-zod-api";
 
 const endpoint = endpointsFactory.build({
   input: z
-    .object({
-      /* ... */
-    })
+    .object({/* ... */})
     .refine(() => true)
     .refine(() => true)
     .refine(() => true),
@@ -4499,9 +4548,7 @@ const myMiddleware = createMiddleware({
     },
   },
   input: z.object({}),
-  middleware: async () => ({
-    /* ... */
-  }),
+  middleware: async () => ({/* ... */}),
 });
 
 // example endpoint
@@ -4510,9 +4557,7 @@ const myEndpoint = defaultEndpointsFactory.addMiddleware(myMiddleware).build({
   method: "post",
   input: z.object({}),
   output: z.object({}),
-  handler: async () => ({
-    /* ... */
-  }),
+  handler: async () => ({/* ... */}),
 });
 ```
 
@@ -5444,15 +5489,11 @@ const fileUploadEndpoint = defaultEndpointsFactory.build({
   input: z.object({
     avatar: z.upload(),
   }),
-  output: z.object({
-    /* ... */
-  }),
+  output: z.object({/* ... */}),
   handler: async ({ input: { avatar } }) => {
     // avatar: {name, mv(), mimetype, encoding, data, truncated, size, etc}
     // avatar.truncated is true on failure
-    return {
-      /* ... */
-    };
+    return {/* ... */};
   },
 });
 ```
@@ -5686,15 +5727,11 @@ import { EndpointOutput } from "express-zod-api";
 
 const myEndpointV1 = endpointsFactory.build({
   method: "get",
-  input: z.object({
-    /* ... */
-  }),
+  input: z.object({/* ... */}),
   output: z.object({
     name: z.string(),
   }),
-  handler: async () => ({
-    /* ... */
-  }),
+  handler: async () => ({/* ... */}),
 });
 type MyEndpointOutput = EndpointOutput<typeof myEndpointV1>; // => { name: string }
 
@@ -5703,15 +5740,11 @@ import { defaultEndpointsFactory, EndpointResponse } from "express-zod-api";
 
 const myEndpointV2 = defaultEndpointsFactory.build({
   method: "get",
-  input: z.object({
-    /* ... */
-  }),
+  input: z.object({/* ... */}),
   output: z.object({
     name: z.string(),
   }),
-  handler: async () => ({
-    /* ... */
-  }),
+  handler: async () => ({/* ... */}),
 });
 type MyEndpointResponse = EndpointResponse<typeof myEndpointV2>; // => the following type:
 //  {
@@ -5725,13 +5758,9 @@ type MyEndpointResponse = EndpointResponse<typeof myEndpointV2>; // => the follo
 
 ```ts
 // before
-new OpenAPI({
-  /* ... */
-}).builder.getSpecAsYaml();
+new OpenAPI({/* ... */}).builder.getSpecAsYaml();
 // after
-new OpenAPI({
-  /* ... */
-}).getSpecAsYaml();
+new OpenAPI({/* ... */}).getSpecAsYaml();
 ```
 
 ```ts
@@ -5756,12 +5785,7 @@ const myResultHandlerV2 = createResultHandler({
       }),
       ["mime/type1", "mime/type2"], // optional, default: application/json
     ),
-  getNegativeResponse: () =>
-    createApiResponse(
-      z.object({
-        /* ... */
-      }),
-    ),
+  getNegativeResponse: () => createApiResponse(z.object({/* ... */})),
   handler: ({ error, input, output, request, response, logger }) => {
     /* ... */
   },

package/README.md

@@ -83,7 +83,7 @@ Therefore, many basic tasks can be achieved faster and easier, in particular:
 - All of your endpoints can respond consistently.
 - The expected endpoint input and response types can be exported to the frontend, giving you end-to-end type safety
   so you don't get confused about the field names when you implement the client for your API.
-- You can generate your API documentation in OpenAPI 3.1 and JSON Schema compatible format.
+- You can generate your API documentation in OpenAPI 3.2 and JSON Schema compatible format.
 
 ## Contributors
 
@@ -171,7 +171,7 @@ Much can be customized to fit your needs.
 - Supports any logger having `info()`, `debug()`, `error()` and `warn()` methods;
   - Built-in console logger with colorful and pretty inspections by default.
 - Generators:
-  - Documentation — [OpenAPI 3.1](https://github.com/metadevpro/openapi3-ts) (former Swagger);
+  - Documentation — [OpenAPI 3.2](https://github.com/metadevpro/openapi3-ts) (former Swagger);
   - Client side types — inspired by [zod-to-ts](https://github.com/sachinraja/zod-to-ts).
 - File uploads — [Express-FileUpload](https://github.com/richardgirges/express-fileupload)
   (based on [Busboy](https://github.com/mscdex/busboy)).
@@ -424,9 +424,9 @@ const resultHandlerWithCleanup = new ResultHandler({
 
 There are two ways of connecting the native express middlewares depending on their nature and your objective.
 
-In case it's a middleware establishing and serving its own routes, or somehow globally modifying the behaviour, or
-being an additional request parser (like `cookie-parser`), use the `beforeRouting` option. However, it might be better
-to avoid `cors` here — [the framework handles it on its own](#cross-origin-resource-sharing).
+In case it's middleware establishing and serving its own routes, or somehow globally modifying the behavior, use the
+`beforeRouting` or `beforeParsers` hooks. Note that [CORS](#cross-origin-resource-sharing), cookies, compression, and
+body parsing are already available as separate [config options](#set-up-config).
 
 ```ts
 import { createConfig } from "express-zod-api";
@@ -647,18 +647,27 @@ const listUsers = defaultEndpointsFactory.build({
 ## Cross-Origin Resource Sharing
 
 You can enable your API for other domains using the corresponding configuration option `cors`. The value is required to
-ensure you explicitly choose the correct setting. In addition to being a boolean, `cors` can also be assigned a
-function that overrides default CORS headers. That function has several parameters and can be asynchronous.
+ensure you explicitly choose the correct setting: `false | true` — disables/enables CORS for any origin, setting
+`Access-Control-Allow-Origin: *` and `Access-Control-Allow-Headers: content-type`. You can also pass standard Express
+middleware for full control, consider using the well-known [cors](https://www.npmjs.com/package/cors) package.
 
 ```ts
+import cors from "cors";
 import { createConfig } from "express-zod-api";
 
-const config = createConfig({
-  /** @link https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS */
-  cors: ({ defaultHeaders, request, endpoint, logger }) => ({
-    ...defaultHeaders,
-    "Access-Control-Max-Age": "5000",
-  }),
+const configWithCorsPackage = createConfig({
+  cors: cors({ origin: "https://example.com" }),
+});
+
+const configWithCustomRequestHandler = createConfig({
+  cors: (req, res, next) => {
+    res.set({
+      "Access-Control-Allow-Origin": "https://example.com",
+      "Access-Control-Allow-Headers": "content-type",
+      "Access-Control-Max-Age": "5000",
+    });
+    next();
+  },
 });
 ```
 
@@ -683,9 +692,7 @@ const config = createConfig({
   }, // ... cors, logger, etc
 });
 
-// 'await' is only needed if you're going to use the returned entities.
-// For top level CJS you can wrap you code with (async () => { ... })()
-const { app, servers, logger } = await createServer(config, routing);
+const { app, servers, logger } = createServer(config, routing);
 ```
 
 Ensure having `@types/node` package installed. At least you need to specify the port (usually it is 443) or UNIX socket,
@@ -787,6 +794,7 @@ createConfig({
     put: ["body", "params"],
     patch: ["body", "params"],
     delete: ["query", "params"],
+    query: ["query", "body", "params"],
   }, // ...
 });
 ```
@@ -1124,7 +1132,7 @@ errors yourself. In this regard `attachRouting()` provides you with `notFoundHan
 to your custom express app.
 
 Besides that, if you're looking to include additional request parsers, or a middleware that establishes its own routes,
-then consider using the `beforeRouting` [option in config instead](#using-native-express-middlewares).
+install them on your custom `app` before calling `attachRouting()`.
 
 ## Testing endpoints
 
@@ -1241,9 +1249,8 @@ import { Documentation } from "express-zod-api";
 const yamlString = new Documentation({
   routing, // the same routing and config that you use to start the server
   config,
-  version: "1.2.3",
-  title: "Example API",
-  serverUrl: "https://example.com",
+  info: { version: "1.2.3", title: "Example API" },
+  server: "https://example.com",
   composition: "inline", // optional, or "components" for keeping schemas in a separate dedicated section using refs
   // descriptions: { positiveResponse, negativeResponse, requestParameter, requestBody }, // check out these features
 }).getSpecAsYaml();

package/SECURITY.md

@@ -4,10 +4,11 @@
 
 | Version | Code name     | Release |     Supported      |
 | ------: | :------------ | :------ | :----------------: |
+|  29.x.x | Angie         | 08.2026 | :white_check_mark: |
 |  28.x.x | Koko          | 05.2026 | :white_check_mark: |
 |  27.x.x | Nikki         | 02.2026 | :white_check_mark: |
 |  26.x.x | Lia           | 12.2025 | :white_check_mark: |
-|  25.x.x | Sara          | 08.2025 | :white_check_mark: |
+|  25.x.x | Sara          | 08.2025 |        :x:         |
 |  24.x.x | Ashley        | 06.2025 |        :x:         |
 |  23.x.x | Sonia         | 04.2025 |        :x:         |
 |  22.x.x | Tai           | 01.2025 |        :x:         |