express-zod-api 28.7.5 → 29.0.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # 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 `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`:
+  - Moved to the dedicated subpath `express-zod-api/documentation` along with `Depicter` type;
+  - `serverUrl` constructor option renamed to `server` and now also accepts OpenAPI's ServerObject;
+  - `title` option and `version` must be wrapped into `info`, assignable with OpenAPI's InfoObject;
+  - Now produces OpenAPI 3.2.0 with better SSE support and other features.
+- Changes to `Integration`:
+  - Moved to the dedicated subpath `express-zod-api/integration` along with `Producer` type;
+  - The static async method `create()` removed — use `new Integration()` instead;
+  - Removed `typescript` option from constructor — now imported statically.
+- Consider using [the automated migration](https://www.npmjs.com/package/@express-zod-api/migration).
+
+```diff
+- import { Integration, Documentation, type Producer, type Depicter } from "express-zod-api";
++ import { Integration, type Producer } from "express-zod-api/integration";
++ import { Documentation, type Depicter } from "express-zod-api/documentation";
+
+  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
@@ -4242,9 +4298,7 @@ import { z } from "express-zod-api";
 
 const endpoint = endpointsFactory.build({
   input: z
-    .object({
-      /* ... */
-    })
+    .object({/* ... */})
     .refine(() => true)
     .refine(() => true)
     .refine(() => true),
@@ -4503,9 +4557,7 @@ const myMiddleware = createMiddleware({
     },
   },
   input: z.object({}),
-  middleware: async () => ({
-    /* ... */
-  }),
+  middleware: async () => ({/* ... */}),
 });
 
 // example endpoint
@@ -4514,9 +4566,7 @@ const myEndpoint = defaultEndpointsFactory.addMiddleware(myMiddleware).build({
   method: "post",
   input: z.object({}),
   output: z.object({}),
-  handler: async () => ({
-    /* ... */
-  }),
+  handler: async () => ({/* ... */}),
 });
 ```
 
@@ -5448,15 +5498,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 {/* ... */};
   },
 });
 ```
@@ -5690,15 +5736,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 }
 
@@ -5707,15 +5749,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:
 //  {
@@ -5729,13 +5767,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
@@ -5760,12 +5794,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

@@ -2,12 +2,11 @@
 
 ![logo](https://raw.githubusercontent.com/RobinTail/express-zod-api/master/logo.svg)
 
-![CI](https://github.com/RobinTail/express-zod-api/actions/workflows/node.js.yml/badge.svg)
-![OpenAPI](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2FRobinTail%2Fexpress-zod-api%2Fmaster%2Fexample%2Fexample.documentation.yaml&label=OpenAPI)
-[![coverage](https://coveralls.io/repos/github/RobinTail/express-zod-api/badge.svg)](https://coveralls.io/github/RobinTail/express-zod-api)
+![CI](https://img.shields.io/github/actions/workflow/status/RobinTail/express-zod-api/node.js.yml?label=CI)
+![OpenAPI](https://img.shields.io/github/actions/workflow/status/RobinTail/express-zod-api/oas.yml?label=OpenAPI)
+[![coverage](https://img.shields.io/coverallsCoverage/github/RobinTail/express-zod-api)](https://coveralls.io/github/RobinTail/express-zod-api)
 
 ![downloads](https://img.shields.io/npm/dw/express-zod-api.svg)
-![npm release](https://img.shields.io/npm/v/express-zod-api.svg?color=green25&label=latest)
 ![GitHub Repo stars](https://img.shields.io/github/stars/RobinTail/express-zod-api.svg?style=flat)
 ![License](https://img.shields.io/npm/l/express-zod-api.svg?color=green25)
 
@@ -83,7 +82,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 +170,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 +423,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 +646,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 +691,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 +793,7 @@ createConfig({
     put: ["body", "params"],
     patch: ["body", "params"],
     delete: ["query", "params"],
+    query: ["query", "body", "params"],
   }, // ...
 });
 ```
@@ -1124,7 +1131,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
 
@@ -1206,7 +1213,7 @@ safety between your API and frontend. Make sure you have `typescript` installed.
 and using the async `printFormatted()` method.
 
 ```ts
-import { Integration } from "express-zod-api";
+import { Integration } from "express-zod-api/integration";
 
 const client = new Integration({
   routing,
@@ -1236,14 +1243,13 @@ new Subscription("get /v1/events/stream", {}).on("time", (time) => {}); // Serve
 You can generate the specification of your API and write it to a `.yaml` file, that can be used as the documentation:
 
 ```ts
-import { Documentation } from "express-zod-api";
+import { Documentation } from "express-zod-api/documentation";
 
 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();
@@ -1281,7 +1287,8 @@ endpoints is available for that purpose. In order to establish the constraints o
 should be declared as keys of `TagOverrides` interface. Consider the following example:
 
 ```ts
-import { defaultEndpointsFactory, Documentation } from "express-zod-api";
+import { defaultEndpointsFactory } from "express-zod-api";
+import { Documentation } from "express-zod-api/documentation";
 
 // Add similar declaration once, somewhere in your code, preferably near config
 declare module "express-zod-api" {
@@ -1340,12 +1347,8 @@ handling rule for multiple brands, use the exposed types `Depicter` and `Produce
 ```ts
 import ts from "typescript";
 import { z } from "zod";
-import {
-  Documentation,
-  Integration,
-  Depicter,
-  Producer,
-} from "express-zod-api";
+import { Documentation, type Depicter } from "express-zod-api/documentation";
+import { Integration, type Producer } from "express-zod-api/integration";
 
 const myBrand = Symbol("MamaToldMeImSpecial"); // I recommend to use symbols for this purpose
 const myBrandedSchema = z.string().xBrand(myBrand); // requires Zod Plugin, or .meta({ "x-brand": myBrand })

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

package/dist/documentation-helpers-BLgXFiWr.d.ts

@@ -0,0 +1,30 @@
+import { P as ClientMethod, y as Tag } from "./routing-C0jFxoT6.js";
+import { z } from "zod";
+import { ReferenceObject, SchemaObjectValue, TagObject } from "openapi3-ts/oas32";
+interface ReqResCommons {
+  makeRef: (key: object | string, value: SchemaObjectValue | ReferenceObject, proposedName?: string) => ReferenceObject;
+  path: string;
+  method: ClientMethod;
+}
+interface OpenAPIContext extends ReqResCommons {
+  isResponse: boolean;
+}
+type Depicter = (
+  zodCtx: {
+    zodSchema: z.core.$ZodType;
+    jsonSchema: z.core.JSONSchema.BaseSchema;
+  },
+  oasCtx: OpenAPIContext,
+) => z.core.JSONSchema.BaseSchema | SchemaObjectValue;
+/** @desc Using defaultIsHeader when returns null or undefined */
+type IsHeader = (name: string, method: ClientMethod, path: string) => boolean | null | undefined;
+type BrandHandling = Record<string | symbol, Depicter>;
+interface TagDetails extends Pick<TagObject, "summary" | "description" | "externalDocs" | "kind"> {
+  /** @desc shorthand for externalDocs.url */
+  url?: string;
+  parent?: Tag;
+}
+declare const depictTags: (tags: Partial<Record<Tag, string | TagDetails>>) => TagObject[];
+/** @desc Ensures the summary string does not exceed the limit */
+declare const trimSummary: (summary?: string, limit?: number) => string | undefined;
+export { depictTags as a, OpenAPIContext as i, Depicter as n, trimSummary as o, IsHeader as r, BrandHandling as t };

package/dist/documentation.d.ts

@@ -0,0 +1,75 @@
+import { B as ResponseVariant, C as CommonConfig, t as Routing } from "./routing-C0jFxoT6.js";
+import {
+  a as depictTags,
+  n as Depicter,
+  o as trimSummary,
+  r as IsHeader,
+  t as BrandHandling,
+} from "./documentation-helpers-BLgXFiWr.js";
+import { InfoObject, OpenApiBuilder, ServerObject } from "openapi3-ts/oas32";
+type Component = `${ResponseVariant}Response` | "requestParameter" | "requestBody";
+/** @desc user defined function that creates a component description from its properties */
+type Descriptor = (
+  props: Record<"method" | "path" | "operationId", string> & {
+    statusCode?: number;
+  },
+) => string;
+type Summarizer = (params: { summary?: string; description?: string; trim: typeof trimSummary }) => string | undefined;
+interface DocumentationParams {
+  /**
+   * @desc The metadata about the API
+   * @default { title: "Generated by Express Zod API", version: "0.0.0" }
+   * */
+  info?: InfoObject;
+  /**
+   * @desc Server URL(s) or their complete definitions
+   * @default []
+   * */
+  server?: string | ServerObject | Array<string | ServerObject>;
+  routing: Routing;
+  config: CommonConfig;
+  /**
+   * @desc Descriptions of various components based on their properties (method, path, operationId).
+   * @desc When composition set to "components", component name is generated from this description
+   * @default () => `${method} ${path} ${component}`
+   * */
+  descriptions?: Partial<Record<Component, Descriptor>>;
+  /**
+   * @desc The function that ensures the maximum length for summary fields. Can optionally make them from descriptions.
+   * @see defaultSummarizer
+   * @see trimSummary
+   * */
+  summarizer?: Summarizer;
+  /**
+   * @desc Depict the HEAD method for each Endpoint supporting the GET method (feature of Express)
+   * @default true
+   * */
+  hasHeadMethod?: boolean;
+  /** @default inline */
+  composition?: "inline" | "components";
+  /**
+   * @desc Handling rules for your own schemas branded with `x-brand` metadata.
+   * @desc Keys: brands (recommended to use unique symbols).
+   * @desc Values: functions having Zod context as first argument, second one is the framework context.
+   * @example { MyBrand: ({ zodSchema, jsonSchema }) => ({ type: "object" })
+   * @link https://www.npmjs.com/package/@express-zod-api/zod-plugin
+   */
+  brandHandling?: BrandHandling;
+  /**
+   * @desc Ability to configure recognition of headers among other input data
+   * @desc Only applicable when "headers" is present within inputSources config option
+   * @see defaultIsHeader
+   * @link https://www.iana.org/assignments/http-fields/http-fields.xhtml
+   * */
+  isHeader?: IsHeader;
+  /**
+   * @desc Extended description of tags used in endpoints. For enforcing constraints:
+   * @see TagOverrides
+   * @example { users: "About users", files: { description: "About files", url: "https://example.com" } }
+   * */
+  tags?: Parameters<typeof depictTags>[0];
+}
+declare class Documentation extends OpenApiBuilder {
+  constructor({ hasHeadMethod, ...rest }: DocumentationParams);
+}
+export { type Depicter, Documentation };

package/dist/documentation.js

@@ -0,0 +1 @@
+import{B as e,D as t,G as n,H as r,J as i,K as a,M as o,P as s,R as c,V as l,W as u,Z as d,_ as f,a as p,b as m,h,j as g,k as _,n as v,q as y,t as b}from"./routing-walker--qYUjhGi.js";import{t as x}from"./json-schema-helpers-Bhz0qPT7.js";import{z as S}from"zod";import*as C from"ramda";import{OpenApiBuilder as w,isReferenceObject as T,isSchemaObject as E}from"openapi3-ts/oas32";const D=e=>r(e)&&`or`in e,O=e=>r(e)&&`and`in e,k=e=>!O(e)&&!D(e),A=e=>{let t=C.filter(k,e),n=C.chain(C.prop(`and`),C.filter(O,e)),[r,i]=C.partition(k,n),a=C.concat(t,r),o=C.filter(D,e);return C.map(C.prop(`or`),C.concat(o,i)).reduce((e,t)=>s(e,C.map(e=>k(e)?[e]:e.and,t),([e,t])=>C.concat(e,t)),C.reject(C.isEmpty,[a]))},j=(e,t)=>O(e)?C.chain(e=>j(e,t),e.and):D(e)?C.chain(e=>j(e,t),e.or):e.type===t?[e.name]:[],M=(e,t)=>new Set(C.chain(e=>j(e,t),e));let N;const P=()=>N??=new Set(`a-im.accept.accept-additions.accept-charset.accept-datetime.accept-encoding.accept-features.accept-language.accept-signature.access-control.access-control-request-headers.access-control-request-method.alpn.alt-used.amp-cache-transform.apply-to-redirect-ref.authorization.available-dictionary.c-ext.c-man.c-opt.c-pep.c-pep-info.cache-control.cal-managed-id.caldav-timezones.capsule-protocol.cdn-loop.cert-not-after.cert-not-before.client-cert.client-cert-chain.close.cmcd-object.cmcd-request.cmcd-session.cmcd-status.cmsd-dynamic.cmsd-static.concealed-auth-export.configuration-context.connection.content-digest.content-disposition.content-encoding.content-id.content-language.content-length.content-location.content-md5.content-range.content-script-type.content-type.cookie.cookie2.cta-common-access-token.dasl.date.dav.default-style.delta-base.deprecation.depth.derived-from.destination.detached-jws.dictionary-id.differential-id.digest.dpop.early-data.ediint-features.expect.expect-ct.ext.forwarded.from.getprofile.hobareg.host.http2-settings.if.if-match.if-modified-since.if-none-match.if-range.if-schedule-tag-match.if-unmodified-since.im.include-referred-token-binding-id.incremental.isolation.keep-alive.label.last-event-id.link.link-template.lock-token.man.max-forwards.memento-datetime.meter.method-check.method-check-expires.mime-version.negotiate.odata-entityid.odata-isolation.odata-maxversion.odata-version.opt.ordering-type.origin.origin-agent-cluster.oscore.oslc-core-version.overwrite.pep.pep-info.permissions-policy.pics-label.ping-from.ping-to.position.pragma.prefer.preference-applied.priority.profileobject.protocol.protocol-info.protocol-query.protocol-request.proxy-authorization.proxy-features.proxy-instruction.range.redirect-ref.referer.referer-root.referrer-policy.repeatability-client-id.repeatability-first-sent.repeatability-request-id.repeatability-result.replay-nonce.reporting-endpoints.repr-digest.safe.schedule-reply.schedule-tag.sec-fetch-storage-access.sec-gpc.sec-purpose.sec-token-binding.sec-websocket-extensions.sec-websocket-key.sec-websocket-protocol.sec-websocket-version.security-scheme.signature.signature-input.slug.soapaction.status-uri.sunset.surrogate-capability.tcn.te.timeout.topic.traceparent.tracestate.trailer.transfer-encoding.ttl.upgrade.urgency.uri.user-agent.variant-vary.via.want-content-digest.want-digest.want-repr-digest.want-unencoded-digest.warning.x-content-type-options.x-frame-options`.split(`.`)),ee={integer:0,number:0,string:``,boolean:!1,object:{},null:null,array:[]},te=e=>e.replace(a,e=>`{${e.slice(1)}}`),ne=({},e)=>{if(e.isResponse)throw new m(`Please use ez.upload() only for input.`,e);return{type:`string`,format:`binary`}},re=({jsonSchema:e})=>({...e,externalDocs:{description:`raw binary data`,url:`https://swagger.io/specification/#working-with-binary-data`}}),ie=({zodSchema:e,jsonSchema:t})=>{if(!u(e,`union`)||!(`discriminator`in e._zod.def))return t;let n=e._zod.def.discriminator;return{...t,discriminator:t.discriminator??{propertyName:n}}},F=C.tryCatch(({jsonSchema:e})=>{if(!e.allOf)throw`no allOf`;return x(e,`throw`)},(e,{jsonSchema:t})=>t),I=({jsonSchema:e})=>{if(!e.anyOf||!e.anyOf.length)return e;let t=e.anyOf[0];return Object.assign(t,{type:U(t.type)})},L=e=>e,R=({jsonSchema:e},t)=>{if(t.isResponse)throw new m(`Please use ez.dateOut() for output.`,t);return e},z=({jsonSchema:e},t)=>{if(!t.isResponse)throw new m(`Please use ez.dateIn() for input.`,t);return e},B=()=>({type:`string`,format:`bigint`,pattern:`^-?\\d+$`}),V=({zodSchema:e,jsonSchema:t})=>e._zod.def.rest===null?{...t,items:{not:{}}}:t,H=e=>{let t=Array.isArray(e.type)?e.type[0]:e.type;return ee?.[t]},U=e=>e===`null`?e:typeof e==`string`?[e,`null`]:e&&[...new Set(e).add(`null`)],W=({zodSchema:e,jsonSchema:t},n)=>{let r=e._zod.def[n.isResponse?`out`:`in`],i=e._zod.def[n.isResponse?`in`:`out`];if(!u(r,`transform`))return t;let a=L(X(i,{ctx:n}));if(E(a))if(n.isResponse){let e=l(r,H(a));if(e&&[`number`,`string`,`boolean`].includes(e))return{...t,type:e}}else{let{type:e,...t}=a;return{...t,format:`${t.format||e} (preprocessed)`}}return t},G=({jsonSchema:e})=>{if(e.type!==`object`)return e;let t=e;return!t.properties||!(`raw`in t.properties)||!r(t.properties.raw)?e:t.properties.raw},K=e=>e.length?C.fromPairs(C.zip(C.times(e=>`example${e+1}`,e.length),C.map(C.objOf(`dataValue`),e))):void 0,q=(e,t)=>t?.has(e)||e.startsWith(`x-`)||P().has(e),J=({path:t,method:i,request:a,inputSources:o,makeRef:s,composition:c,isHeader:l,securityHeaders:u,securityCookies:d,description:f=`${i.toUpperCase()} ${t} Parameter`})=>{let p=x(a),m=e(t),h=o.includes(`query`),g=o.includes(`params`),_=o.includes(`headers`),v=o.includes(`cookies`)||o.includes(`signedCookies`),y=e=>{if(g&&m.includes(e))return`path`;if(v&&d?.has(e))return`cookie`;if(_&&(l?.(e,i,t)??q(e,u)))return`header`;if(h&&i!==`query`)return`query`};return Object.entries(p.properties).reduce((e,[t,i])=>{if(!r(i))return e;let a=y(t);if(!a)return e;let o=L(i),l=c===`components`?s(i.id||JSON.stringify(i),o,i.id||n(f,t)):o;return e.concat({name:t,in:a,deprecated:i.deprecated,required:p.required?.includes(t)||!1,description:o.description||f,schema:l,examples:K(E(o)&&o.examples?.length?o.examples:C.pluck(t,p.examples?.filter(C.both(r,C.has(t)))||[]))})},[])},Y={nullable:I,union:ie,bigint:B,intersection:F,tuple:V,pipe:W,[_]:R,[t]:z,[f]:ne,[h]:G,[g]:re},ae=(e,t,n)=>{let r=[e,t],i=e=>/schema\d+$/.test(e)?void 0:e;for(let e=0;e<r.length;e++){let a=r[e];if(C.is(Object,a)){if(T(a)&&!a.$ref.startsWith(`#/components`)){let e=a.$ref.split(`/`).pop(),r=t[e];r&&(a.$ref=n.makeRef(r.id||r,L(r),r.id||i(e)).$ref);continue}r.push(...C.values(a))}C.is(Array,a)&&r.push(...C.values(a))}return e},X=(e,{ctx:t,rules:n=Y})=>{let{$defs:i={},properties:a={}}=S.toJSONSchema(S.object({subject:e}),{unrepresentable:`any`,io:t.isResponse?`output`:`input`,override:e=>{let r=o(e.zodSchema),i=n[r&&r in n?r:e.zodSchema._zod.def.type];if(i){let n={...i(e,t)};for(let t in e.jsonSchema)delete e.jsonSchema[t];Object.assign(e.jsonSchema,n)}}});return ae(r(a.subject)?a.subject:{},i,t)},Z=(e,t)=>{if(T(e))return[e,!1];let n=!1,r=C.map(e=>{let[r,i]=Z(e,t);return n||=i,r}),i=C.omit(t),a={properties:i,examples:C.map(i),required:C.without(t),allOf:r,oneOf:r,anyOf:r},o=C.evolve(a,e);return[o,n||!!o.required?.length]},oe=({method:e,path:t,schema:r,mimeTypes:a,variant:o,makeRef:s,composition:c,hasMultipleStatusCodes:l,statusCode:u,brandHandling:f,description:p=`${e.toUpperCase()} ${t} ${i(o)} response ${l?u:``}`.trim()})=>{if(!y(e,a))return{description:p};let m=L(X(r,{rules:{...f,...Y},ctx:{isResponse:!0,makeRef:s,path:t,method:e}})),h=[];E(m)&&m.examples&&(h.push(...m.examples),delete m.examples);let g=c===`components`?s(r,m,n(p)):m;return{description:p,content:C.fromPairs(a.map(e=>[e,{[e===d.sse?`itemSchema`:`schema`]:g,examples:K(h)}]))}},se=({format:e})=>{let t={type:`http`,scheme:`bearer`};return e&&(t.bearerFormat=e),t},ce=({name:e},t)=>{let n={type:`apiKey`,in:`query`,name:e};return t?.includes(`body`)&&(t?.includes(`query`)?(n[`x-in-alternative`]=`body`,n.description=`${e} CAN also be supplied within the request body`):(n[`x-in-actual`]=`body`,n.description=`${e} MUST be supplied within the request body instead of query`)),n},le=({name:e})=>({type:`apiKey`,in:`header`,name:e}),ue=({name:e})=>({type:`apiKey`,in:`cookie`,name:e}),de=({url:e})=>({type:`openIdConnect`,openIdConnectUrl:e}),fe=({flows:e={},oauth2MetadataUrl:t})=>({type:`oauth2`,flows:C.map(e=>({...e,scopes:e.scopes||{}}),C.reject(C.isNil,e)),oauth2MetadataUrl:t}),pe=(e,t=[])=>{let n=e=>e.type===`basic`?{type:`http`,scheme:`basic`}:e.type===`bearer`?se(e):e.type===`input`?ce(e,t):e.type===`header`?le(e):e.type===`cookie`?ue(e):e.type===`openid`?de(e):fe(e);return e.map(e=>e.map(({deprecated:e,...t})=>({...n(t),deprecated:e})))},me=(e,t,n)=>e.map(e=>e.reduce((e,r)=>{let i=n(r),a=[`oauth2`,`openIdConnect`].includes(r.type);return Object.assign(e,{[i]:a?t:[]})},{})),Q=({schema:e,brandHandling:t,makeRef:n,path:r,method:i})=>X(e,{rules:{...t,...Y},ctx:{isResponse:!1,makeRef:n,path:r,method:i}}),he=({method:e,path:t,schema:i,request:a,mimeType:o,makeRef:s,composition:c,paramNames:l,description:u=`${e.toUpperCase()} ${t} Request body`})=>{let[f,p]=Z(a,l),m=L(f),h=[];E(m)&&m.examples&&(h.push(...m.examples),delete m.examples);let g={schema:c===`components`?s(i,m,n(u)):m,examples:K(h.length?h:x(a).examples?.filter(e=>r(e)&&!Array.isArray(e)).map(C.omit(l))||[])},_={description:u,content:{[o]:g}};return(p||o===d.raw)&&(_.required=!0),_},ge=e=>Object.entries(e).reduce((e,[t,n])=>{if(!n)return e;if(typeof n==`string`)return e.concat({name:t,description:n});let{url:r,...i}=n,a={...i,name:t};return r&&(a.externalDocs={...a.externalDocs,url:r}),e.concat(a)},[]),_e=(e,t=50)=>!e||e.length<=t?e:e.slice(0,Math.max(1,t||0)-1)+`…`,$=e=>e.length?e.slice():void 0,ve=({description:e,summary:t=e,trim:n})=>n(t);var ye=class extends w{#e=new Map;#t=new Map;#n=new Map;#r(e,t,n){let r=this.#n.get(e);if(!r){let t=+!n;do r=`${n??`Schema`}${t?this.#n.size+t:``}`,t++;while(this.rootDoc.components?.schemas?.[r]);this.#n.set(e,r)}return this.addSchema(r,t),{$ref:`#/components/schemas/${r}`}}#i(e,t,r){let i=r||n(t,e),a=this.#t.get(i);if(a===void 0)return this.#t.set(i,1),i;if(r)throw new m(`Duplicated operationId: "${r}"`,{method:t,isResponse:!1,path:e});return a++,this.#t.set(i,a),`${i}${a}`}#a(e){let t=JSON.stringify(e);for(let e in this.rootDoc.components?.securitySchemes||{})if(t===JSON.stringify(this.rootDoc.components?.securitySchemes?.[e]))return e;let n=(this.#e.get(e.type)||0)+1;return this.#e.set(e.type,n),`${e.type.toUpperCase()}_${n}`}#o({tags:e,server:t,info:n={title:`Generated by Express Zod API`,version:`0.0.0`}}){if(this.addInfo(n),e&&(this.rootDoc.tags=ge(e)),t)for(let e of Array.isArray(t)?t:[t])this.addServer(typeof e==`string`?{url:e}:e)}#s({config:e,descriptions:t,brandHandling:n,isHeader:r,summarizer:i=ve,composition:a=`inline`}){return(o,s,l)=>{let u={path:s,method:o,endpoint:l,composition:a,brandHandling:n,makeRef:this.#r.bind(this)},{description:f,summary:m,scopes:h,inputSchema:g}=l,_=c(o,e.inputSources),v=this.#i(s,o,l.getOperationId(o)),y=Q({...u,schema:g}),b=J({...u,inputSources:_,isHeader:r,securityHeaders:M(l.security,`header`),securityCookies:M(l.security,`cookie`),request:y,description:t?.requestParameter?.({method:o,path:s,operationId:v})}),x={};for(let e of p){let n=l.getResponses(e);for(let{mimeTypes:r,schema:i,statusCodes:a}of n)for(let c of a)x[c]=oe({...u,variant:e,schema:i,mimeTypes:r,statusCode:c,hasMultipleStatusCodes:n.length>1||a.length>1,description:t?.[`${e}Response`]?.({method:o,path:s,operationId:v,statusCode:c})})}let S=_.includes(`body`)?he({...u,request:y,paramNames:C.pluck(`name`,b),schema:g,mimeType:d[l.getProbableRequestType(o)],description:t?.requestBody?.({method:o,path:s,operationId:v})}):void 0,w=me(pe(A(l.security),_),h,e=>{let t=this.#a(e);return this.addSecurityScheme(t,e),t}),T={operationId:v,summary:i({summary:m,description:f,trim:_e}),description:f,deprecated:l.isDeprecated||void 0,tags:$(l.tags),parameters:$(b),requestBody:S,security:$(w),responses:x};this.addPath(te(s),{[o]:T})}}constructor({hasHeadMethod:e=!0,...t}){super(),this.#o(t);let n=this.#s(t),r=e?v(n):n;b({...t,onEndpoint:r})}};export{ye as Documentation};