express-zod-api/dist/index.d.ts

A Typescript framework to help you get an API server up and running with I/O schema validation and custom middlewares in minutes.

import "@express-zod-api/zod-plugin";
import * as zod0 from "zod";
import { z } from "zod";
import { HttpError } from "http-errors";
import "ansis";
import * as express0 from "express";
import express, { IRouter, NextFunction, Request, RequestHandler, Response } from "express";
import http from "node:http";
import https, { ServerOptions } from "node:https";
import { OpenApiBuilder, ReferenceObject, SchemaObject, TagObject } from "openapi3-ts/oas31";
import * as node_mocks_http0 from "node-mocks-http";
import { RequestOptions, ResponseOptions } from "node-mocks-http";
import ts from "typescript";
import compression from "compression";
import * as express_fileupload0 from "express-fileupload";
import fileUpload from "express-fileupload";
import { ListenOptions } from "node:net";
import * as express_serve_static_core0 from "express-serve-static-core";
import * as qs0 from "qs";
import * as zod_v4_core0 from "zod/v4/core";

//#region src/method.d.ts
declare const methods: ("get" | "post" | "put" | "delete" | "patch")[];
declare const clientMethods: ("get" | "post" | "put" | "delete" | "patch" | "head")[];
/**
 * @desc Methods supported by the framework API to produce Endpoints on EndpointsFactory.
 * @see BuildProps
 * @example "get" | "post" | "put" | "delete" | "patch"
 * */
type Method = (typeof methods)[number];
/**
 * @desc Methods usable on the client side, available via generated Integration and Documentation
 * @see withHead
 * @example Method | "head"
 * */
type ClientMethod = (typeof clientMethods)[number];
/**
 * @desc Methods supported in CORS headers
 * @see makeCorsHeaders
 * @see createWrongMethodHandler
 * @example ClientMethod | "options"
 * */
//#endregion
//#region src/api-response.d.ts
/** @public this is the user facing configuration */
interface ApiResponse<S extends z.ZodType> {
  schema: S;
  /** @default 200 for a positive and 400 for a negative response */
  statusCode?: number | [number, ...number[]];
  /**
   * @example null is for no content, such as 204 and 302
   * @default "application/json"
   * */
  mimeType?: string | [string, ...string[]] | null;
}
/**
 * @private This is what the framework entities operate
 * @see normalize
 * */
//#endregion
//#region src/common-helpers.d.ts
/** @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>;
type FlatObject = Record<string, unknown>;
/** @link https://stackoverflow.com/a/65492934 */
type NoNever<T, F> = [T] extends [never] ? F : T;
/**
 * @desc Using module augmentation approach you can specify tags as the keys of this interface
 * @example declare module "express-zod-api" { interface TagOverrides { users: unknown } }
 * @link https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation
 * */
interface TagOverrides {}
type Tag = NoNever<keyof TagOverrides, string>;
/** @see https://expressjs.com/en/guide/routing.html */

declare const getMessageFromError: (error: Error) => string;
/** Faster replacement to instanceof for code operating core types (traversing schemas) */
//#endregion
//#region src/logger-helpers.d.ts
declare const severity: {
  debug: number;
  info: number;
  warn: number;
  error: number;
};
type Severity = keyof typeof severity;
/** @desc You can use any logger compatible with this type. */
type AbstractLogger = Record<Severity, (message: string, meta?: any) => any>;
/**
 * @desc Using module augmentation approach you can set the type of the actual logger used
 * @example declare module "express-zod-api" { interface LoggerOverrides extends winston.Logger {} }
 * @link https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation
 * */
interface LoggerOverrides {}
type ActualLogger = AbstractLogger & LoggerOverrides;
//#endregion
//#region src/builtin-logger.d.ts
interface Context$1 extends FlatObject {
  requestId?: string;
}
interface BuiltinLoggerConfig {
  /**
   * @desc The minimal severity to log or "silent" to disable logging
   * @example "debug" also enables pretty output for inspected entities
   * */
  level: "silent" | "warn" | "info" | "debug";
  /** @desc Enables colors on printed severity and inspected entities */
  color: boolean;
  /**
   * @desc Control how deeply entities should be inspected
   * @example null
   * @example Infinity
   * */
  depth: number | null;
  /**
   * @desc Context: the metadata applicable for each logged entry, used by .child() method
   * @see childLoggerProvider
   * */
  ctx: Context$1;
}
interface ProfilerOptions {
  message: string;
  /** @default "debug" */
  severity?: Severity | ((ms: number) => Severity);
  /** @default formatDuration - adaptive units and limited fraction */
  formatter?: (ms: number) => string | number;
}
/** @desc Built-in console logger with optional colorful inspections */
declare class BuiltinLogger implements AbstractLogger {
  protected readonly config: BuiltinLoggerConfig;
  /** @example new BuiltinLogger({ level: "debug", color: true, depth: 4 }) */
  constructor({
    color,
    level,
    depth,
    ctx
  }?: Partial<BuiltinLoggerConfig>);
  protected format(subject: unknown): string;
  protected print(method: Severity, message: string, meta?: unknown): void;
  debug(message: string, meta?: unknown): void;
  info(message: string, meta?: unknown): void;
  warn(message: string, meta?: unknown): void;
  error(message: string, meta?: unknown): void;
  child(ctx: Context$1): BuiltinLogger;
  /**
   * @desc The argument used for instance created by .child() method
   * @see ChildLoggerProvider
   * */
  get ctx(): Context$1;
  /** @desc Measures the duration until you invoke the returned callback */
  profile(message: string): () => void;
  profile(options: ProfilerOptions): () => void;
}
//#endregion
//#region src/io-schema.d.ts
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;
/** Makes a schema for EndpointsFactory extended with a Middleware */

/** 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>;
/** Makes the Endpoint input schema */
//#endregion
//#region src/logical-container.d.ts
type LogicalOr<T> = {
  or: T[];
};
type LogicalAnd<T> = {
  and: T[];
};
type LogicalContainer<T> = LogicalOr<T | LogicalAnd<T>> | LogicalAnd<T | LogicalOr<T>> | T;
//#endregion
//#region src/security.d.ts
interface BasicSecurity {
  type: "basic";
}
interface BearerSecurity {
  type: "bearer";
  format?: "JWT" | string;
}
interface InputSecurity<K extends string> {
  type: "input";
  name: K;
}
interface HeaderSecurity {
  type: "header";
  name: string;
}
interface CookieSecurity {
  type: "cookie";
  name: string;
}
/**
 * @see https://swagger.io/docs/specification/authentication/openid-connect-discovery/
 * @desc available scopes has to be provided via the specified URL
 */
interface OpenIdSecurity {
  type: "openid";
  url: string;
}
interface AuthUrl {
  /**
   * @desc The authorization URL to use for this flow. Can be relative to the API server URL.
   * @see https://swagger.io/docs/specification/api-host-and-base-path/
   */
  authorizationUrl: string;
}
interface TokenUrl {
  /** @desc The token URL to use for this flow. Can be relative to the API server URL. */
  tokenUrl: string;
}
interface RefreshUrl {
  /** @desc The URL to be used for obtaining refresh tokens. Can be relative to the API server URL. */
  refreshUrl?: string;
}
interface Scopes<K extends string> {
  /** @desc The available scopes for the OAuth2 security and their short descriptions. Optional. */
  scopes?: Record<K, string>;
}
type AuthCodeFlow<S extends string> = AuthUrl & TokenUrl & RefreshUrl & Scopes<S>;
type ImplicitFlow<S extends string> = AuthUrl & RefreshUrl & Scopes<S>;
type PasswordFlow<S extends string> = TokenUrl & RefreshUrl & Scopes<S>;
type ClientCredFlow<S extends string> = TokenUrl & RefreshUrl & Scopes<S>;
/**
 * @see https://swagger.io/docs/specification/authentication/oauth2/
 */
interface OAuth2Security<S extends string> {
  type: "oauth2";
  flows?: {
    /** @desc Authorization Code flow (previously called accessCode in OpenAPI 2.0) */
    authorizationCode?: AuthCodeFlow<S>;
    /** @desc Implicit flow */
    implicit?: ImplicitFlow<S>;
    /** @desc Resource Owner Password flow */
    password?: PasswordFlow<S>;
    /** @desc Client Credentials flow (previously called application in OpenAPI 2.0) */
    clientCredentials?: ClientCredFlow<S>;
  };
}
/**
 * @desc Middleware security schema descriptor
 * @param K is an optional input field used by InputSecurity
 * @param S is an optional union of scopes used by OAuth2Security
 * */
type Security<K extends string = string, S extends string = string> = BasicSecurity | BearerSecurity | InputSecurity<K> | HeaderSecurity | CookieSecurity | OpenIdSecurity | OAuth2Security<S>;
//#endregion
//#region src/middleware.d.ts
type Handler$2<IN, OPT, OUT> = (params: {
  /** @desc The inputs from the enabled input sources validated against the input schema of the Middleware */
  input: IN;
  /**
   * @desc The returns of the previously executed Middlewares (typed when chaining Middlewares)
   * @link https://github.com/RobinTail/express-zod-api/discussions/1250
   * */
  options: OPT;
  /** @link https://expressjs.com/en/5x/api.html#req */
  request: Request;
  /** @link https://expressjs.com/en/5x/api.html#res */
  response: Response;
  /** @desc The instance of the configured logger */
  logger: ActualLogger;
}) => Promise<OUT>;
declare abstract class AbstractMiddleware {
  abstract execute(params: {
    input: unknown;
    options: FlatObject;
    request: Request;
    response: Response;
    logger: ActualLogger;
  }): Promise<FlatObject>;
}
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 undefined
     * @see defaultInputSources
     * */
    input?: IN;
    /** @desc Declaration of the security schemas implemented within the handler */
    security?: LogicalContainer<Security<Extract<keyof z.input<IN>, string>, SCO>>;
    /** @desc The handler returning options available to Endpoints */
    handler: Handler$2<z.output<IN>, OPT, OUT>;
  });
  /** @throws InputValidationError */
  execute({
    input,
    ...rest
  }: {
    input: unknown;
    options: OPT;
    request: Request;
    response: Response;
    logger: ActualLogger;
  }): Promise<OUT>;
}
declare class ExpressMiddleware<R extends Request, S extends Response, OUT extends FlatObject> extends Middleware<FlatObject, OUT, string> {
  constructor(nativeMw: (request: R, response: S, next: NextFunction) => any, {
    provider,
    transformer
  }?: {
    provider?: (request: R, response: S) => OUT | Promise<OUT>;
    transformer?: (err: Error) => Error;
  });
}
//#endregion
//#region src/depends-on-method.d.ts
declare class DependsOnMethod extends Routable {
  #private;
  constructor(endpoints: Partial<Record<Method, AbstractEndpoint>>);
  deprecated(): this;
}
//#endregion
//#region src/serve-static.d.ts
type OriginalStatic = typeof express.static;
declare class ServeStatic {
  #private;
  constructor(...params: Parameters<OriginalStatic>);
}
//#endregion
//#region src/result-helpers.d.ts
type ResultSchema<R extends Result> = R extends Result<infer S> ? S : never;
type DiscriminatedResult = {
  output: FlatObject;
  error: null;
} | {
  output: null;
  error: Error;
};
/** @throws ResultHandlerError when Result is an empty array */

/**
 * @example InputValidationError —> BadRequest(400)
 * @example Error —> InternalServerError(500)
 * */
declare const ensureHttpError: (error: Error) => HttpError;
//#endregion
//#region src/result-handler.d.ts
type Handler$1<RES = unknown> = (params: DiscriminatedResult & {
  /** null in case of failure to parse or to find the matching endpoint (error: not found) */
  input: FlatObject | null;
  /** can be empty: check presence of the required property using "in" operator */
  options: FlatObject;
  request: Request;
  response: Response<RES>;
  logger: ActualLogger;
}) => void | Promise<void>;
type Result<S extends z.ZodType = z.ZodType> = S | ApiResponse<S> | ApiResponse<S>[];
type LazyResult<R extends Result, A extends unknown[] = []> = (...args: A) => R;
declare abstract class AbstractResultHandler {
  #private;
  protected constructor(handler: Handler$1);
  execute(...params: Parameters<Handler$1>): void | Promise<void>;
}
declare class ResultHandler<POS extends Result, NEG extends Result> extends AbstractResultHandler {
  #private;
  constructor(params: {
    /** @desc A description of the API response in case of success (schema, status code, MIME type) */
    positive: POS | LazyResult<POS, [IOSchema]>;
    /** @desc A description of the API response in case of error (schema, status code, MIME type) */
    negative: NEG | LazyResult<NEG>;
    /** @desc The actual implementation to transmit the response in any case */
    handler: Handler$1<z.output<ResultSchema<POS> | ResultSchema<NEG>>>;
  });
}
declare const defaultResultHandler: ResultHandler<z.ZodObject<{
  status: z.ZodLiteral<"success">;
  data: IOSchema;
}, z.core.$strip>, z.ZodObject<{
  status: z.ZodLiteral<"error">;
  error: z.ZodObject<{
    message: z.ZodString;
  }, z.core.$strip>;
}, z.core.$strip>>;
/**
 * @deprecated Resist the urge of using it: this handler is designed only to simplify the migration of legacy APIs.
 * @desc Responding with array is a bad practice keeping your endpoints from evolving without breaking changes.
 * @desc This handler expects your endpoint to have the property 'items' in the output object schema
 * */
declare const arrayResultHandler: ResultHandler<z.ZodArray<z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>> | z.ZodArray<z.ZodAny>, {
  schema: z.ZodString;
  mimeType: string;
}>;
//#endregion
//#region src/server-helpers.d.ts
/** @desc Returns child logger for the given request (if configured) or the configured logger otherwise */
type GetLogger = (request?: Request) => ActualLogger;
//#endregion
//#region src/routing.d.ts
/**
 * @example { v1: { books: { ":bookId": getBookEndpoint } } }
 * @example { "v1/books/:bookId": getBookEndpoint }
 * @example { "get /v1/books/:bookId": getBookEndpoint }
 * @example { v1: { "patch /books/:bookId": changeBookEndpoint } }
 * */
interface Routing {
  [K: string]: Routing | DependsOnMethod | AbstractEndpoint | ServeStatic;
}
//#endregion
//#region src/routable.d.ts
declare abstract class Routable {
  /** @desc Marks the route as deprecated (makes a copy of the endpoint) */
  abstract deprecated(): this;
  /** @desc Enables nested routes within the path assigned to the subject */
  nest(routing: Routing): Routing;
}
//#endregion
//#region src/endpoint.d.ts
type Handler<IN, OUT, OPT> = (params: {
  /** @desc The inputs from the enabled input sources validated against the final input schema (incl. Middlewares) */
  input: IN;
  /** @desc The returns of the assigned Middlewares */
  options: OPT;
  /** @desc The instance of the configured logger */
  logger: ActualLogger;
}) => Promise<OUT>;
declare abstract class AbstractEndpoint extends Routable {
  abstract execute(params: {
    request: Request;
    response: Response;
    logger: ActualLogger;
    config: CommonConfig;
  }): Promise<void>;
}
declare class Endpoint<IN extends IOSchema, OUT extends IOSchema, OPT extends FlatObject> extends AbstractEndpoint {
  #private;
  constructor(def: {
    deprecated?: boolean;
    middlewares?: AbstractMiddleware[];
    inputSchema: IN;
    outputSchema: OUT;
    handler: Handler<z.output<IN>, z.input<OUT>, OPT>;
    resultHandler: AbstractResultHandler;
    description?: string;
    shortDescription?: string;
    getOperationId?: (method: ClientMethod) => string | undefined;
    methods?: Method[];
    scopes?: string[];
    tags?: string[];
  });
  deprecated(): this;
  execute({
    request,
    response,
    logger,
    config
  }: {
    request: Request;
    response: Response;
    logger: ActualLogger;
    config: CommonConfig;
  }): Promise<undefined>;
}
//#endregion
//#region src/config-type.d.ts
type InputSource = keyof Pick<Request, "query" | "body" | "files" | "params" | "headers">;
type InputSources = Record<Method, InputSource[]>;
type Headers = Record<string, string>;
type HeadersProvider = (params: {
  /** @desc The default headers to be overridden. */
  defaultHeaders: Headers;
  request: Request;
  endpoint: AbstractEndpoint;
  logger: ActualLogger;
}) => Headers | Promise<Headers>;
type ChildLoggerProvider = (params: {
  request: Request;
  parent: ActualLogger;
}) => ActualLogger | Promise<ActualLogger>;
type LogAccess = (request: Request, logger: ActualLogger) => void;
interface CommonConfig {
  /**
   * @desc Enables cross-origin resource sharing.
   * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
   * @desc You can override the default CORS headers by setting up a provider function here.
   */
  cors: boolean | HeadersProvider;
  /**
   * @desc How to respond to a request that uses a wrong method to an existing endpoint
   * @example 404 — Not found
   * @example 405 — Method not allowed, incl. the "Allow" header with a list of methods
   * @default 405
   * */
  wrongMethodBehavior?: 404 | 405;
  /**
   * @desc The ResultHandler to use for handling routing, parsing and upload errors
   * @default defaultResultHandler
   * @see defaultResultHandler
   */
  errorHandler?: AbstractResultHandler;
  /**
   * @desc Built-in logger configuration or an instance of any compatible logger.
   * @example { level: "debug", color: true }
   * @default { level: NODE_ENV === "production" ? "warn" : "debug", color: isSupported(), depth: 2 }
   * */
  logger?: Partial<BuiltinLoggerConfig> | AbstractLogger;
  /**
   * @desc A child logger returned by this function can override the logger in all handlers for each request
   * @example ({ parent }) => parent.child({ requestId: uuid() })
   * */
  childLoggerProvider?: ChildLoggerProvider;
  /**
   * @desc The function for producing access logs
   * @default ({ method, path }, logger) => logger.debug(`${method}: ${path}`)
   * @example null — disables the feature
   * */
  accessLogger?: null | LogAccess;
  /**
   * @desc You can disable the startup logo.
   * @default true
   */
  startupLogo?: boolean;
  /**
   * @desc Which properties of request are combined into the input for endpoints and middlewares.
   * @desc The order matters: priority from lowest to highest
   * @default defaultInputSources
   * @see defaultInputSources
   */
  inputSources?: Partial<InputSources>;
}
type BeforeUpload = (params: {
  request: Request;
  logger: ActualLogger;
}) => void | Promise<void>;
type UploadOptions = Pick<fileUpload.Options, "createParentPath" | "uriDecodeFileNames" | "safeFileNames" | "preserveExtension" | "useTempFiles" | "tempFileDir" | "debug" | "uploadTimeout" | "limits"> & {
  /**
   * @desc The error to throw when the file exceeds the configured fileSize limit (handled by errorHandler).
   * @see limits
   * @override limitHandler
   * @example createHttpError(413, "The file is too large")
   * */
  limitError?: Error;
  /**
   * @desc A handler to execute before uploading — it can be used for restrictions by throwing an error.
   * @example ({ request }) => { throw createHttpError(403, "Not authorized"); }
   * */
  beforeUpload?: BeforeUpload;
};
type CompressionOptions = Pick<compression.CompressionOptions, "threshold" | "level" | "strategy" | "chunkSize" | "memLevel">;
interface GracefulOptions {
  /**
   * @desc Time given to drain ongoing requests before closing the server.
   * @default 1000
   * */
  timeout?: number;
  /**
   * @desc Process event (Signal) that triggers the graceful shutdown.
   * @see Signals
   * @default [SIGINT, SIGTERM]
   * */
  events?: string[];
  /** @desc The hook to call after the server was closed, but before terminating the process. */
  beforeExit?: () => void | Promise<void>;
}
type BeforeRouting = (params: {
  app: IRouter;
  /** @desc Returns child logger for the given request (if configured) or the configured logger otherwise */
  getLogger: GetLogger;
}) => void | Promise<void>;
interface HttpConfig {
  /** @desc Port, UNIX socket or custom options. */
  listen: number | string | ListenOptions;
}
interface HttpsConfig extends HttpConfig {
  /** @desc At least "cert" and "key" options required. */
  options: ServerOptions;
}
interface ServerConfig extends CommonConfig {
  /** @desc HTTP server configuration. */
  http?: HttpConfig;
  /** @desc HTTPS server configuration. */
  https?: HttpsConfig;
  /**
   * @desc Custom JSON parser.
   * @default express.json()
   * @link https://expressjs.com/en/5x/api.html#express.json
   * */
  jsonParser?: RequestHandler;
  /**
   * @desc Enable or configure uploads handling.
   * @requires express-fileupload
   * */
  upload?: boolean | UploadOptions;
  /**
   * @desc Enable or configure response compression.
   * @requires compression
   */
  compression?: boolean | CompressionOptions;
  /**
   * @desc Configure or customize the parser for request query string
   * @example "simple" // for "node:querystring" module, array elements must be repeated: ?a=1&a=2
   * @example "extended" // for "qs" module, supports nested objects and arrays with brackets: ?a[]=1&a[]=2
   * @example (query) => qs.parse(query, {comma: true}) // for comma-separated arrays: ?a=1,2,3
   * @default "simple"
   * @link https://expressjs.com/en/5x/api.html#req.query
   */
  queryParser?: "simple" | "extended" | ((query: string) => object);
  /**
   * @desc Custom raw parser (assigns Buffer to request body)
   * @default 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/5x/api.html#express.urlencoded
   * */
  formParser?: RequestHandler;
  /**
   * @desc A code to execute before processing the Routing of your API (and before parsing).
   * @desc This can be a good place for express middlewares establishing their own routes.
   * @desc It can help to avoid making a DIY solution based on the attachRouting() approach.
   * @example ({ app }) => { app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); }
   * */
  beforeRouting?: BeforeRouting;
  /**
   * @desc Rejects new connections and attempts to finish ongoing ones in the specified time before exit.
   * */
  gracefulShutdown?: boolean | GracefulOptions;
}
interface AppConfig extends CommonConfig {
  /** @desc Your custom express app or express router instead. */
  app: IRouter;
}
declare function createConfig(config: ServerConfig): ServerConfig;
declare function createConfig(config: AppConfig): AppConfig;
//#endregion
//#region src/endpoints-factory.d.ts
interface BuildProps<IN extends IOSchema, OUT extends IOSchema | z.ZodVoid, MIN extends IOSchema | undefined, OPT extends FlatObject, SCO extends string> {
  /**
   * @desc Input schema of the Endpoint, combining properties from all the enabled input sources (path params, headers)
   * @default z.object({})
   * @see defaultInputSources
   * */
  input?: IN;
  /** @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<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) */
  shortDescription?: string;
  /** @desc The operation ID for the generated Documentation (must be unique) */
  operationId?: string | ((method: ClientMethod) => string);
  /**
   * @desc HTTP method(s) this endpoint can handle
   * @default "get" unless the Endpoint is assigned within DependsOnMethod
   * @see DependsOnMethod
   * */
  method?: Method | [Method, ...Method[]];
  /**
   * @desc Scope(s) from the list of the ones defined by the added Middlewares having "oauth2" security type
   * @see OAuth2Security
   * */
  scope?: SCO | SCO[];
  /**
   * @desc Tag(s) for generating Documentation. For establishing constraints:
   * @see TagOverrides
   * */
  tag?: Tag | Tag[];
  /** @desc Marks the operation deprecated in the generated Documentation */
  deprecated?: boolean;
}
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 | 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: express0.NextFunction) => any, params_1?: {
    provider?: ((request: R, response: S) => AOUT | Promise<AOUT>) | undefined;
    transformer?: (err: Error) => Error;
  } | 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<FinalInputSchema<IN, BIN>, z.ZodObject<{}, z.core.$strip>, OUT>;
}
declare const defaultEndpointsFactory: EndpointsFactory<undefined, Record<string, never>, string>;
/**
 * @deprecated Resist the urge of using it: this factory is designed only to simplify the migration of legacy APIs.
 * @desc Responding with array is a bad practice keeping your endpoints from evolving without breaking changes.
 * @desc The result handler of this factory expects your endpoint to have the property 'items' in the output schema
 */
declare const arrayEndpointsFactory: EndpointsFactory<undefined, Record<string, never>, string>;
//#endregion
//#region src/server.d.ts
declare const attachRouting: (config: AppConfig, routing: Routing) => {
  notFoundHandler: express.RequestHandler<express_serve_static_core0.ParamsDictionary, any, any, qs0.ParsedQs, Record<string, any>>;
  logger: AbstractLogger | BuiltinLogger;
};
declare const createServer: (config: ServerConfig, routing: Routing) => Promise<{
  app: express_serve_static_core0.Express;
  logger: AbstractLogger | BuiltinLogger;
  servers: (http.Server<typeof http.IncomingMessage, typeof http.ServerResponse> | https.Server<typeof http.IncomingMessage, typeof http.ServerResponse>)[];
}>;
//#endregion
//#region src/documentation-helpers.d.ts
interface ReqResCommons {
  makeRef: (key: object | string, subject: SchemaObject | ReferenceObject, name?: 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 | SchemaObject;
/** @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>;
declare const depictTags: (tags: Partial<Record<Tag, string | {
  description: string;
  url?: string;
}>>) => TagObject[];
//#endregion
//#region src/documentation.d.ts
type Component = "positiveResponse" | "negativeResponse" | "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;
interface DocumentationParams {
  title: string;
  version: string;
  serverUrl: string | [string, ...string[]];
  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>>;
  /** @default true */
  hasSummaryFromDescription?: boolean;
  /**
   * @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 branded schemas.
   * @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" })
   */
  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 {
  #private;
  constructor({
    routing,
    config,
    title,
    version,
    serverUrl,
    descriptions,
    brandHandling,
    tags,
    isHeader,
    hasSummaryFromDescription,
    hasHeadMethod,
    composition
  }: DocumentationParams);
}
//#endregion
//#region src/errors.d.ts
/** @desc An error related to the wrong Routing declaration */
declare class RoutingError extends Error {
  name: string;
  readonly cause: {
    method: Method;
    path: string;
  };
  constructor(message: string, method: Method, path: string);
}
/**
 * @desc An error related to the generating of the documentation
 * */
declare class DocumentationError extends Error {
  name: string;
  readonly cause: string;
  constructor(message: string, {
    method,
    path,
    isResponse
  }: Pick<OpenAPIContext, "path" | "method" | "isResponse">);
}
/** @desc An error related to the input and output schemas declaration */
declare class IOSchemaError extends Error {
  name: string;
}
/** @desc An error of validating the Endpoint handler's returns against the Endpoint output schema */
declare class OutputValidationError extends IOSchemaError {
  readonly cause: z.ZodError;
  name: string;
  constructor(cause: z.ZodError);
}
/** @desc An error of validating the input sources against the Middleware or Endpoint input schema */
declare class InputValidationError extends IOSchemaError {
  readonly cause: z.ZodError;
  name: string;
  constructor(cause: z.ZodError);
}
/** @desc An error related to the execution or incorrect configuration of ResultHandler */

declare class MissingPeerError extends Error {
  name: string;
  constructor(module: string);
}
//#endregion
//#region src/testing.d.ts
interface TestingProps<REQ, LOG> {
  /**
   * @desc Additional properties to set on Request mock
   * @default { method: "GET", headers: { "content-type": "application/json" } }
   * */
  requestProps?: REQ;
  /**
   * @link https://www.npmjs.com/package/node-mocks-http
   * @default { req: requestMock }
   * */
  responseOptions?: ResponseOptions;
  /**
   * @desc Additional properties to set on config mock
   * @default { cors: false, logger }
   * */
  configProps?: Partial<CommonConfig>;
  /**
   * @desc Additional properties to set on logger mock
   * @default { info, warn, error, debug }
   * */
  loggerProps?: LOG;
}
declare const testEndpoint: <LOG extends FlatObject, REQ extends RequestOptions>({
  endpoint,
  ...rest
}: TestingProps<REQ, LOG> & {
  /** @desc The endpoint to test */
  endpoint: AbstractEndpoint;
}) => Promise<{
  requestMock: node_mocks_http0.MockRequest<Request<express_serve_static_core0.ParamsDictionary, any, any, qs0.ParsedQs, Record<string, any>> & REQ>;
  responseMock: node_mocks_http0.MockResponse<Response<any, Record<string, any>>>;
  loggerMock: AbstractLogger & LOG & {
    _getLogs: () => Record<"debug" | "info" | "warn" | "error", unknown[]>;
  };
}>;
declare const testMiddleware: <LOG extends FlatObject, REQ extends RequestOptions>({
  middleware,
  options,
  ...rest
}: TestingProps<REQ, LOG> & {
  /** @desc The middleware to test */
  middleware: AbstractMiddleware;
  /** @desc The aggregated output from previously executed middlewares */
  options?: FlatObject;
}) => Promise<{
  requestMock: node_mocks_http0.MockRequest<Request<express_serve_static_core0.ParamsDictionary, any, any, qs0.ParsedQs, Record<string, any>> & REQ>;
  responseMock: node_mocks_http0.MockResponse<Response<any, Record<string, any>>>;
  loggerMock: AbstractLogger & LOG & {
    _getLogs: () => Record<"debug" | "info" | "warn" | "error", unknown[]>;
  };
  output: FlatObject;
}>;
//#endregion
//#region src/integration-base.d.ts
declare abstract class IntegrationBase {
  #private;
  private readonly serverUrl;
  protected constructor(serverUrl: string);
}
//#endregion
//#region src/schema-walker.d.ts
interface NextHandlerInc<U> {
  next: (schema: z.core.$ZodType) => U;
}
interface PrevInc<U> {
  prev: U;
}
type SchemaHandler<U, Context extends FlatObject = EmptyObject, Variant extends "regular" | "each" | "last" = "regular"> = (schema: any,
// eslint-disable-line @typescript-eslint/no-explicit-any -- for assignment compatibility
ctx: Context & (Variant extends "regular" ? NextHandlerInc<U> : Variant extends "each" ? PrevInc<U> : Context)) => U;
type HandlingRules<U, Context extends FlatObject = EmptyObject, K extends string | symbol = string | symbol> = Partial<Record<K, SchemaHandler<U, Context>>>;
/** @since 10.1.1 calling onEach _after_ handler and giving it the previously achieved result */
//#endregion
//#region src/zts-helpers.d.ts
interface ZTSContext extends FlatObject {
  isResponse: boolean;
  makeAlias: (key: object, produce: () => ts.TypeNode) => ts.TypeNode;
}
type Producer = SchemaHandler<ts.TypeNode, ZTSContext>;
//#endregion
//#region src/integration.d.ts
interface IntegrationParams {
  routing: Routing;
  /**
   * @desc What should be generated
   * @example "types" — types of your endpoint requests and responses (for a DIY solution)
   * @example "client" — an entity for performing typed requests and receiving typed responses
   * @default "client"
   * */
  variant?: "types" | "client";
  /** @default Client */
  clientClassName?: string;
  /** @default Subscription */
  subscriptionClassName?: string;
  /**
   * @desc The API URL to use in the generated code
   * @default https://example.com
   * */
  serverUrl?: string;
  /**
   * @desc The schema to use for responses without body such as 204
   * @default z.undefined()
   * */
  noContent?: z.ZodType;
  /**
   * @desc Depict the HEAD method for each Endpoint supporting the GET method (feature of Express)
   * @default true
   * */
  hasHeadMethod?: boolean;
  /**
   * @desc Handling rules for your own branded schemas.
   * @desc Keys: brands (recommended to use unique symbols).
   * @desc Values: functions having schema as first argument that you should assign type to, second one is a context.
   * @example { MyBrand: ( schema: typeof myBrandSchema, { next } ) => createKeywordTypeNode(SyntaxKind.AnyKeyword)
   */
  brandHandling?: HandlingRules<ts.TypeNode, ZTSContext>;
}
interface FormattedPrintingOptions {
  /** @desc Typescript printer options */
  printerOptions?: ts.PrinterOptions;
  /**
   * @desc Typescript code formatter
   * @default prettier.format
   * */
  format?: (program: string) => Promise<string>;
}
declare class Integration extends IntegrationBase {
  #private;
  constructor({
    routing,
    brandHandling,
    variant,
    clientClassName,
    subscriptionClassName,
    serverUrl,
    noContent,
    hasHeadMethod
  }: IntegrationParams);
  print(printerOptions?: ts.PrinterOptions): string;
  printFormatted({
    printerOptions,
    format: userDefined
  }?: FormattedPrintingOptions): Promise<string>;
}
//#endregion
//#region src/sse.d.ts
type EventsMap = Record<string, z.ZodType>;
interface Emitter<E extends EventsMap> extends FlatObject {
  /** @desc Returns true when the connection was closed or terminated */
  isClosed: () => boolean;
  /** @desc Sends an event to the stream according to the declared schema */
  emit: <K extends keyof E>(event: K, data: z.input<E[K]>) => void;
}
declare class EventStreamFactory<E extends EventsMap> extends EndpointsFactory<undefined, Emitter<E>> {
  constructor(events: E);
}
//#endregion
//#region src/date-in-schema.d.ts
interface DateInParams extends Omit<Parameters<z.ZodString["meta"]>[0], "examples"> {
  examples?: string[];
}
//#endregion
//#region src/date-out-schema.d.ts
interface DateOutParams extends Omit<Parameters<z.ZodString["meta"]>[0], "examples"> {
  examples?: string[];
}
//#endregion
//#region src/raw-schema.d.ts
declare const base: z.ZodObject<{
  raw: z.core.$ZodBranded<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, symbol>;
}, z.core.$strip>;
type Base = ReturnType<typeof base.brand<symbol>>;
declare const extended: <S extends z.core.$ZodShape>(extra: S) => z.core.$ZodBranded<z.ZodObject<("raw" & keyof S extends never ? {
  raw: z.core.$ZodBranded<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, symbol>;
} & S : ({
  raw: z.core.$ZodBranded<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, symbol>;
} extends infer T_1 extends z.core.util.SomeObject ? { [K in keyof T_1 as K extends keyof S ? never : K]: T_1[K] } : never) & { [K_1 in keyof S]: S[K_1] }) extends infer T ? { [k in keyof T]: T[k] } : never, z.core.$strip>, symbol>;
declare function raw(): Base;
declare function raw<S extends z.core.$ZodShape>(extra: S): ReturnType<typeof extended<S>>;
//#endregion
//#region src/proprietary-schemas.d.ts
declare const ez: {
  dateIn: ({
    examples,
    ...rest
  }?: DateInParams) => zod_v4_core0.$ZodBranded<zod0.ZodPipe<zod0.ZodPipe<zod0.ZodUnion<readonly [zod0.ZodISODate, zod0.ZodISODateTime, zod0.ZodISODateTime]>, zod0.ZodTransform<Date, string>>, zod0.ZodDate>, symbol>;
  dateOut: (meta?: DateOutParams) => zod_v4_core0.$ZodBranded<zod0.ZodPipe<zod0.ZodDate, zod0.ZodTransform<string, Date>>, symbol>;
  form: <S extends zod_v4_core0.$ZodShape>(base: S | zod0.ZodObject<S>) => zod_v4_core0.$ZodBranded<zod0.ZodObject<S, zod_v4_core0.$strip>, symbol>;
  upload: () => zod_v4_core0.$ZodBranded<zod0.ZodCustom<express_fileupload0.UploadedFile, express_fileupload0.UploadedFile>, symbol>;
  raw: typeof raw;
  buffer: () => zod_v4_core0.$ZodBranded<zod0.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, symbol>;
};
//#endregion
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, getMessageFromError, testEndpoint, testMiddleware };