express-zod-api 18.5.2 → 19.0.0-beta.1

package/dist/index.d.cts

@@ -1,10 +1,10 @@
+import * as zod from 'zod';
+import { z, ZodError } from 'zod';
 import compression from 'compression';
 import express, { Request, Response, NextFunction, RequestHandler, IRouter } from 'express';
 import * as express_fileupload from 'express-fileupload';
 import express_fileupload__default from 'express-fileupload';
 import https, { ServerOptions } from 'node:https';
-import * as zod from 'zod';
-import { z, ZodError } from 'zod';
 import { HttpError } from 'http-errors';
 import { ListenOptions } from 'node:net';
 import * as qs from 'qs';
@@ -13,6 +13,37 @@ import http from 'node:http';
 import { OpenApiBuilder, SecuritySchemeType, SchemaObject, ReferenceObject, SecuritySchemeObject } from 'openapi3-ts/oas31';
 import ts from 'typescript';
 
+declare const metaSymbol: unique symbol;
+interface Metadata<T extends z.ZodTypeAny> {
+    examples: z.input<T>[];
+    /** @override ZodDefault::_def.defaultValue() in depictDefault */
+    defaultLabel?: string;
+    brand?: string | number | symbol;
+}
+
+/**
+ * @fileoverview Zod Runtime Plugin
+ * @see https://github.com/colinhacks/zod/blob/90efe7fa6135119224412c7081bd12ef0bccef26/plugin/effect/src/index.ts#L21-L31
+ * @desc This code modifies and extends zod's functionality immediately when importing express-zod-api
+ * @desc Enables .examples() on all schemas (ZodType)
+ * @desc Enables .label() on ZodDefault
+ * @desc Stores the argument supplied to .brand() on all schema (runtime distinguishable branded types)
+ * */
+
+declare module "zod" {
+    interface ZodTypeDef {
+        [metaSymbol]?: Metadata<z.ZodTypeAny>;
+    }
+    interface ZodType {
+        /** @desc Add an example value (before any transformations, can be called multiple times) */
+        example(example: this["_input"]): this;
+    }
+    interface ZodDefault<T extends z.ZodTypeAny> {
+        /** @desc Change the default value in the generated Documentation to a label */
+        label(label: string): this;
+    }
+}
+
 interface ApiResponse<S extends z.ZodTypeAny> {
     schema: S;
     /**
@@ -195,17 +226,51 @@ interface ExpressMiddlewareFeatures<R extends Request, S extends Response, OUT e
     transformer?: (err: Error) => HttpError | Error;
 }
 
+declare const ezFileBrand: unique symbol;
+declare const variants: {
+    buffer: () => z.ZodBranded<z.ZodType<Buffer, z.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+    string: () => z.ZodBranded<z.ZodString, typeof ezFileBrand>;
+    binary: () => z.ZodBranded<z.ZodUnion<[z.ZodType<Buffer, z.ZodTypeDef, Buffer>, z.ZodString]>, typeof ezFileBrand>;
+    base64: () => z.ZodBranded<z.ZodString, typeof ezFileBrand>;
+};
+type Variants = typeof variants;
+type Variant = keyof Variants;
+declare function file(): ReturnType<Variants["string"]>;
+declare function file<K extends Variant>(variant: K): ReturnType<Variants[K]>;
+
+declare const ezRawBrand: unique symbol;
+/** Shorthand for z.object({ raw: ez.file("buffer") }) */
+declare const raw: <S extends z.ZodRawShape>(extra?: S) => z.ZodBranded<z.ZodObject<z.objectUtil.extendShape<{
+    raw: z.ZodBranded<z.ZodType<Buffer, z.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+}, S>, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<z.objectUtil.extendShape<{
+    raw: z.ZodBranded<z.ZodType<Buffer, z.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+}, S>>, any> extends infer T ? { [k in keyof T]: z.objectUtil.addQuestionMarks<z.baseObjectOutputType<z.objectUtil.extendShape<{
+    raw: z.ZodBranded<z.ZodType<Buffer, z.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+}, S>>, any>[k]; } : never, z.baseObjectInputType<z.objectUtil.extendShape<{
+    raw: z.ZodBranded<z.ZodType<Buffer, z.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+}, S>> extends infer T_1 ? { [k_1 in keyof T_1]: z.baseObjectInputType<z.objectUtil.extendShape<{
+    raw: z.ZodBranded<z.ZodType<Buffer, z.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+}, S>>[k_1]; } : never>, typeof ezRawBrand>;
+type RawSchema = ReturnType<typeof raw>;
+
 type Refined<T extends z.ZodTypeAny> = T extends z.ZodType<infer O> ? z.ZodEffects<T | Refined<T>, O, O> : never;
 /**
  * @desc The type allowed on the top level of Middlewares and Endpoints
  * @param U — only "strip" is allowed for Middlewares due to intersection issue (Zod) #600
  * */
-type IOSchema<U extends z.UnknownKeysParam = any> = z.ZodObject<any, U> | z.ZodUnion<[IOSchema<U>, ...IOSchema<U>[]]> | z.ZodIntersection<IOSchema<U>, IOSchema<U>> | z.ZodDiscriminatedUnion<string, z.ZodObject<any, U>[]> | Refined<z.ZodObject<any, U>>;
+type IOSchema<U extends z.UnknownKeysParam = any> = z.ZodObject<any, U> | z.ZodUnion<[IOSchema<U>, ...IOSchema<U>[]]> | z.ZodIntersection<IOSchema<U>, IOSchema<U>> | z.ZodDiscriminatedUnion<string, z.ZodObject<any, U>[]> | Refined<z.ZodObject<any, U>> | RawSchema;
 type ProbableIntersection<A extends IOSchema<"strip"> | null, B extends IOSchema> = A extends null ? B : A extends IOSchema<"strip"> ? z.ZodIntersection<A, B> : never;
 
 declare const methods: ("get" | "post" | "put" | "delete" | "patch")[];
 type Method = (typeof methods)[number];
 
+declare const contentTypes: {
+    json: string;
+    upload: string;
+    raw: string;
+};
+type ContentType = keyof typeof contentTypes;
+
 interface ResultHandlerParams<RES> {
     /** null in case of failure to parse or to find the matching endpoint (error: not found) */
     input: FlatObject | null;
@@ -278,18 +343,19 @@ declare abstract class AbstractEndpoint {
         response: Response;
         logger: AbstractLogger;
         config: CommonConfig;
-        siblingMethods?: Method[];
+        siblingMethods?: ReadonlyArray<Method>;
     }): Promise<void>;
     abstract getDescription(variant: DescriptionVariant): string | undefined;
-    abstract getMethods(): Method[];
+    abstract getMethods(): ReadonlyArray<Method>;
     abstract getSchema(variant: IOVariant): IOSchema;
     abstract getSchema(variant: ResponseVariant): z.ZodTypeAny;
-    abstract getMimeTypes(variant: MimeVariant): string[];
-    abstract getResponses(variant: ResponseVariant): NormalizedResponse[];
+    abstract getMimeTypes(variant: MimeVariant): ReadonlyArray<string>;
+    abstract getResponses(variant: ResponseVariant): ReadonlyArray<NormalizedResponse>;
     abstract getSecurity(): LogicalContainer<Security>;
-    abstract getScopes(): string[];
-    abstract getTags(): string[];
+    abstract getScopes(): ReadonlyArray<string>;
+    abstract getTags(): ReadonlyArray<string>;
     abstract getOperationId(method: Method): string | undefined;
+    abstract getRequestType(): ContentType;
 }
 declare class Endpoint<IN extends IOSchema, OUT extends IOSchema, OPT extends FlatObject, SCO extends string, TAG extends string> extends AbstractEndpoint {
     #private;
@@ -307,15 +373,16 @@ declare class Endpoint<IN extends IOSchema, OUT extends IOSchema, OPT extends Fl
         tags?: TAG[];
     });
     getDescription(variant: DescriptionVariant): string | undefined;
-    getMethods(): Method[];
+    getMethods(): readonly ("get" | "post" | "put" | "delete" | "patch")[];
     getSchema(variant: "input"): IN;
     getSchema(variant: "output"): OUT;
     getSchema(variant: ResponseVariant): z.ZodTypeAny;
-    getMimeTypes(variant: MimeVariant): string[];
-    getResponses(variant: ResponseVariant): Required<Pick<ApiResponse<z.ZodTypeAny>, "schema" | "statusCodes" | "mimeTypes">>[];
+    getMimeTypes(variant: MimeVariant): readonly string[];
+    getRequestType(): "raw" | "json" | "upload";
+    getResponses(variant: ResponseVariant): readonly Required<Pick<ApiResponse<z.ZodTypeAny>, "schema" | "statusCodes" | "mimeTypes">>[];
     getSecurity(): LogicalContainer<Security>;
-    getScopes(): SCO[];
-    getTags(): TAG[];
+    getScopes(): readonly SCO[];
+    getTags(): readonly TAG[];
     getOperationId(method: Method): string | undefined;
     execute({ request, response, logger, config, siblingMethods, }: {
         request: Request;
@@ -385,6 +452,10 @@ interface CommonConfig<TAG extends string = string> {
      */
     tags?: TagsConfig<TAG>;
 }
+type BeforeUpload = (params: {
+    request: Request;
+    logger: AbstractLogger;
+}) => void | Promise<void>;
 type UploadOptions = Pick<express_fileupload__default.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).
@@ -394,15 +465,14 @@ type UploadOptions = Pick<express_fileupload__default.Options, "createParentPath
      * */
     limitError?: Error;
     /**
-     * @desc A code to execute before connecting the upload middleware.
-     * @desc It can be used to connect a middleware that restricts the ability to upload.
+     * @desc A handler to execute before uploading — it can be used for restrictions by throwing an error.
      * @default undefined
-     * @example ({ app }) => { app.use( ... ); }
+     * @example ({ request }) => { throw createHttpError(403, "Not authorized"); }
      * */
-    beforeUpload?: AppExtension;
+    beforeUpload?: BeforeUpload;
 };
 type CompressionOptions = Pick<compression.CompressionOptions, "threshold" | "level" | "strategy" | "chunkSize" | "memLevel">;
-type AppExtension = (params: {
+type BeforeRouting = (params: {
     app: IRouter;
     logger: AbstractLogger;
 }) => void | Promise<void>;
@@ -419,21 +489,19 @@ interface ServerConfig<TAG extends string = string> extends CommonConfig<TAG> {
         jsonParser?: RequestHandler;
         /**
          * @desc Enable or configure uploads handling.
-         * @default false
+         * @default undefined
          * @requires express-fileupload
          * */
         upload?: boolean | UploadOptions;
         /**
          * @desc Enable or configure response compression.
-         * @default false
+         * @default undefined
          * @requires compression
          */
         compression?: boolean | CompressionOptions;
         /**
-         * @desc Enables parsing certain request payloads into raw Buffers (application/octet-stream by default)
-         * @desc When enabled, use ez.raw() as input schema to get input.raw in Endpoint's handler
-         * @default undefined
-         * @example express.raw()
+         * @desc Custom raw parser (assigns Buffer to request body)
+         * @default express.raw()
          * @link https://expressjs.com/en/4x/api.html#express.raw
          * */
         rawParser?: RequestHandler;
@@ -444,7 +512,7 @@ interface ServerConfig<TAG extends string = string> extends CommonConfig<TAG> {
          * @default undefined
          * @example ({ app }) => { app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); }
          * */
-        beforeRouting?: AppExtension;
+        beforeRouting?: BeforeRouting;
     };
     /** @desc Enables HTTPS server as well. */
     https?: {
@@ -506,9 +574,9 @@ declare const defaultEndpointsFactory: EndpointsFactory<null, {}, string, string
 declare const arrayEndpointsFactory: EndpointsFactory<null, {}, string, string>;
 
 declare class DependsOnMethod {
-    readonly pairs: [Method, AbstractEndpoint][];
+    readonly pairs: ReadonlyArray<[Method, AbstractEndpoint]>;
     readonly firstEndpoint: AbstractEndpoint | undefined;
-    readonly siblingMethods: Method[];
+    readonly siblingMethods: ReadonlyArray<Method>;
     constructor(endpoints: Partial<Record<Method, AbstractEndpoint>>);
 }
 
@@ -572,40 +640,29 @@ declare class Documentation extends OpenApiBuilder {
     constructor({ routing, config, title, version, serverUrl, descriptions, hasSummaryFromDescription, composition, serializer, }: DocumentationParams);
 }
 
-declare const ezRawKind = "Raw";
+declare const ezDateInBrand: unique symbol;
 
-declare const ezDateInKind = "DateIn";
-
-declare const ezDateOutKind = "DateOut";
-
-declare const ezFileKind = "File";
-declare const variants: {
-    buffer: () => z.ZodType<Buffer, z.ZodTypeDef, Buffer>;
-    string: () => z.ZodString;
-    binary: () => z.ZodUnion<[z.ZodType<Buffer, z.ZodTypeDef, Buffer>, z.ZodString]>;
-    base64: () => z.ZodString;
-};
-type Variants = typeof variants;
-type Variant = keyof Variants;
-declare function file(): ReturnType<Variants["string"]>;
-declare function file<K extends Variant>(variant: K): ReturnType<Variants[K]>;
+declare const ezDateOutBrand: unique symbol;
 
-declare const ezUploadKind = "Upload";
+declare const ezUploadBrand: unique symbol;
 
 declare const ez: {
-    dateIn: () => zod.ZodPipeline<zod.ZodEffects<zod.ZodUnion<[zod.ZodString, zod.ZodString, zod.ZodString]>, Date, string>, zod.ZodEffects<zod.ZodDate, Date, Date>> | zod.ZodPipeline<zod.ZodEffects<zod.ZodString, Date, string>, zod.ZodEffects<zod.ZodDate, Date, Date>>;
-    dateOut: () => zod.ZodEffects<zod.ZodEffects<zod.ZodDate, Date, Date>, string, Date>;
+    dateIn: () => zod.ZodBranded<zod.ZodPipeline<zod.ZodEffects<zod.ZodUnion<[zod.ZodString, zod.ZodString, zod.ZodString]>, Date, string>, zod.ZodEffects<zod.ZodDate, Date, Date>>, typeof ezDateInBrand>;
+    dateOut: () => zod.ZodBranded<zod.ZodEffects<zod.ZodEffects<zod.ZodDate, Date, Date>, string, Date>, typeof ezDateOutBrand>;
     file: typeof file;
-    upload: () => zod.ZodType<express_fileupload.UploadedFile, zod.ZodTypeDef, express_fileupload.UploadedFile>;
-    raw: () => zod.ZodObject<{
-        raw: zod.ZodType<Buffer, zod.ZodTypeDef, Buffer>;
-    }, "strip", zod.ZodTypeAny, {
-        raw: Buffer;
-    }, {
-        raw: Buffer;
-    }>;
+    upload: () => zod.ZodBranded<zod.ZodType<express_fileupload.UploadedFile, zod.ZodTypeDef, express_fileupload.UploadedFile>, typeof ezUploadBrand>;
+    raw: <S extends zod.ZodRawShape>(extra?: S) => zod.ZodBranded<zod.ZodObject<zod.objectUtil.extendShape<{
+        raw: zod.ZodBranded<zod.ZodType<Buffer, zod.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+    }, S>, "strip", zod.ZodTypeAny, zod.objectUtil.addQuestionMarks<zod.baseObjectOutputType<zod.objectUtil.extendShape<{
+        raw: zod.ZodBranded<zod.ZodType<Buffer, zod.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+    }, S>>, any> extends infer T ? { [k in keyof T]: zod.objectUtil.addQuestionMarks<zod.baseObjectOutputType<zod.objectUtil.extendShape<{
+        raw: zod.ZodBranded<zod.ZodType<Buffer, zod.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+    }, S>>, any>[k]; } : never, zod.baseObjectInputType<zod.objectUtil.extendShape<{
+        raw: zod.ZodBranded<zod.ZodType<Buffer, zod.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+    }, S>> extends infer T_1 ? { [k_1 in keyof T_1]: zod.baseObjectInputType<zod.objectUtil.extendShape<{
+        raw: zod.ZodBranded<zod.ZodType<Buffer, zod.ZodTypeDef, Buffer>, typeof ezFileBrand>;
+    }, S>>[k_1]; } : never>, typeof ezRawBrand>;
 };
-type ProprietaryKind = typeof ezFileKind | typeof ezDateInKind | typeof ezDateOutKind | typeof ezUploadKind | typeof ezRawKind;
 
 interface OpenAPIContext extends FlatObject {
     isResponse: boolean;
@@ -650,31 +707,11 @@ declare class MissingPeerError extends Error {
     constructor(module: string | string[]);
 }
 
-declare const metaSymbol: unique symbol;
-interface Metadata<T extends z.ZodTypeAny> {
-    kind?: ProprietaryKind;
-    examples: z.input<T>[];
-    /** @override ZodDefault::_def.defaultValue() in depictDefault */
-    defaultLabel?: string;
-}
-declare module "zod" {
-    interface ZodTypeDef {
-        [metaSymbol]?: Metadata<z.ZodTypeAny>;
-    }
-    interface ZodType {
-        /** @desc Add an example value (before any transformations, can be called multiple times) */
-        example(example: this["_input"]): this;
-    }
-    interface ZodDefault<T extends z.ZodTypeAny> {
-        /** @desc Change the default value in the generated Documentation to a label */
-        label(label: string): this;
-    }
-}
-/**
- * @deprecated no longer required
- * @todo remove in v19
- * */
-declare const withMeta: <T extends z.ZodTypeAny>(schema: T) => T;
+type LocalResponse = Response<unknown, {
+    [metaSymbol]?: {
+        logger: AbstractLogger;
+    };
+}>;
 
 /**
  * @desc Using module augmentation approach you can set the Mock type of your actual testing framework.
@@ -724,7 +761,8 @@ declare const testEndpoint: <LOG extends Record<string, any>, REQ extends Record
         writableEnded: boolean;
         statusCode: number;
         statusMessage: string;
-    } & Record<"status" | "set" | "header" | "end" | "setHeader" | "json" | "send", MockOverrides> & RES;
+        locals: LocalResponse["locals"];
+    } & Record<"status" | "set" | "header" | "json" | "end" | "setHeader" | "send", MockOverrides> & RES;
     loggerMock: Record<"error" | "info" | "debug" | "warn", MockOverrides> & LOG;
 }>;
 
@@ -782,7 +820,7 @@ declare class Integration {
         path: string;
     }, Partial<Record<IOKind, string>> & {
         isJson: boolean;
-        tags: string[];
+        tags: ReadonlyArray<string>;
     }>;
     protected paths: string[];
     protected aliases: Map<string, ts.TypeAliasDeclaration>;
@@ -828,4 +866,4 @@ declare class Integration {
     printFormatted({ printerOptions, format: userDefined, }?: FormattedPrintingOptions): Promise<string>;
 }
 
-export { AbstractEndpoint, type ApiResponse, type AppConfig, type BasicSecurity, type BearerSecurity, type CommonConfig, type CookieSecurity, type CustomHeaderSecurity, DependsOnMethod, Documentation, DocumentationError, EndpointsFactory, type FlatObject, type IOSchema, type InputSecurity, InputValidationError, Integration, type LoggerOverrides, type Metadata, type Method, type MiddlewareDefinition, MissingPeerError, type MockOverrides, type OAuth2Security, type OpenIdSecurity, OutputValidationError, type ResultHandlerDefinition, type Routing, RoutingError, ServeStatic, type ServerConfig, arrayEndpointsFactory, arrayResultHandler, attachRouting, createConfig, createLogger, createMiddleware, createResultHandler, createServer, defaultEndpointsFactory, defaultResultHandler, ez, getExamples, getMessageFromError, getStatusCodeFromError, testEndpoint, withMeta };
+export { AbstractEndpoint, type ApiResponse, type AppConfig, type BasicSecurity, type BearerSecurity, type CommonConfig, type CookieSecurity, type CustomHeaderSecurity, DependsOnMethod, Documentation, DocumentationError, EndpointsFactory, type FlatObject, type IOSchema, type InputSecurity, InputValidationError, Integration, type LoggerOverrides, type Metadata, type Method, type MiddlewareDefinition, MissingPeerError, type MockOverrides, type OAuth2Security, type OpenIdSecurity, OutputValidationError, type ResultHandlerDefinition, type Routing, RoutingError, ServeStatic, type ServerConfig, arrayEndpointsFactory, arrayResultHandler, attachRouting, createConfig, createLogger, createMiddleware, createResultHandler, createServer, defaultEndpointsFactory, defaultResultHandler, ez, getExamples, getMessageFromError, getStatusCodeFromError, testEndpoint };