express-zod-api 22.0.0-beta.1 → 22.0.0-beta.3

package/dist/index.d.ts

@@ -12,7 +12,7 @@ import { ListenOptions } from 'node:net';
 import * as qs from 'qs';
 import * as express_serve_static_core from 'express-serve-static-core';
 import http from 'node:http';
-import { SchemaObject, ReferenceObject, OpenApiBuilder, SecuritySchemeType, SecuritySchemeObject } from 'openapi3-ts/oas31';
+import { SchemaObject, ReferenceObject, TagObject, OpenApiBuilder, SecuritySchemeType, SecuritySchemeObject } from 'openapi3-ts/oas31';
 import * as node_mocks_http from 'node-mocks-http';
 import { RequestOptions, ResponseOptions } from 'node-mocks-http';
 import ts from 'typescript';
@@ -78,6 +78,11 @@ declare class BuiltinLogger implements AbstractLogger {
     warn(message: string, meta?: unknown): void;
     error(message: string, meta?: unknown): void;
     child(ctx: Context): BuiltinLogger;
+    /**
+     * @desc The argument used for instance created by .child() method
+     * @see ChildLoggerProvider
+     * */
+    get ctx(): Context;
     /** @desc Measures the duration until you invoke the returned callback */
     profile(message: string): () => void;
     profile(options: ProfilerOptions): () => void;
@@ -442,15 +447,11 @@ type HeadersProvider = (params: {
     endpoint: AbstractEndpoint;
     logger: ActualLogger;
 }) => Headers | Promise<Headers>;
-type TagsConfig<TAG extends string> = Record<TAG, string | {
-    description: string;
-    url?: string;
-}>;
 type ChildLoggerProvider = (params: {
     request: Request;
     parent: ActualLogger;
 }) => ActualLogger | Promise<ActualLogger>;
-interface CommonConfig<TAG extends string = string> {
+interface CommonConfig {
     /**
      * @desc Enables cross-origin resource sharing.
      * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
@@ -486,11 +487,6 @@ interface CommonConfig<TAG extends string = string> {
      * @see defaultInputSources
      */
     inputSources?: Partial<InputSources>;
-    /**
-     * @desc Optional endpoints tagging configuration.
-     * @example: { users: "Everything about the users" }
-     */
-    tags?: TagsConfig<TAG>;
 }
 type BeforeUpload = (params: {
     request: Request;
@@ -538,7 +534,7 @@ interface HttpsConfig extends HttpConfig {
     /** @desc At least "cert" and "key" options required. */
     options: ServerOptions;
 }
-interface ServerConfig<TAG extends string = string> extends CommonConfig<TAG> {
+interface ServerConfig extends CommonConfig {
     /** @desc HTTP server configuration. */
     http?: HttpConfig;
     /** @desc HTTPS server configuration. */
@@ -581,17 +577,27 @@ interface ServerConfig<TAG extends string = string> extends CommonConfig<TAG> {
      * */
     gracefulShutdown?: boolean | GracefulOptions;
 }
-interface AppConfig<TAG extends string = string> extends CommonConfig<TAG> {
+interface AppConfig extends CommonConfig {
     /** @desc Your custom express app or express router instead. */
     app: IRouter;
 }
-declare function createConfig<TAG extends string>(config: ServerConfig<TAG>): ServerConfig<TAG>;
-declare function createConfig<TAG extends string>(config: AppConfig<TAG>): AppConfig<TAG>;
+declare function createConfig(config: ServerConfig): ServerConfig;
+declare function createConfig(config: AppConfig): AppConfig;
 
 /** @desc this type does not allow props assignment, but it works for reading them when merged with another interface */
 type EmptyObject = Record<string, never>;
 type EmptySchema = z.ZodObject<EmptyObject, "strip">;
 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>;
 declare const getMessageFromError: (error: Error) => string;
 declare const getExamples: <T extends z.ZodTypeAny, V extends "original" | "parsed" | undefined>({ schema, variant, validate, }: {
     schema: T;
@@ -655,7 +661,7 @@ declare module "zod" {
     }
 }
 
-interface BuildProps<IN extends IOSchema, OUT extends IOSchema | z.ZodVoid, MIN extends IOSchema<"strip">, OPT extends FlatObject, SCO extends string, TAG extends string> {
+interface BuildProps<IN extends IOSchema, OUT extends IOSchema | z.ZodVoid, MIN extends IOSchema<"strip">, OPT extends FlatObject, SCO extends string> {
     input?: IN;
     output: OUT;
     handler: Handler<z.output<z.ZodIntersection<MIN, IN>>, z.input<OUT>, OPT>;
@@ -664,37 +670,31 @@ interface BuildProps<IN extends IOSchema, OUT extends IOSchema | z.ZodVoid, MIN
     operationId?: string | ((method: Method) => string);
     method?: Method | [Method, ...Method[]];
     scope?: SCO | SCO[];
-    tag?: TAG | TAG[];
+    tag?: Tag | Tag[];
 }
-declare class EndpointsFactory<IN extends IOSchema<"strip"> = EmptySchema, OUT extends FlatObject = EmptyObject, SCO extends string = string, TAG extends string = string> {
+declare class EndpointsFactory<IN extends IOSchema<"strip"> = EmptySchema, OUT extends FlatObject = EmptyObject, SCO extends string = string> {
     #private;
     protected resultHandler: AbstractResultHandler;
     protected middlewares: AbstractMiddleware[];
-    /** @desc Consider using the "config" prop with the "tags" option to enforce constraints on tagging the endpoints */
     constructor(resultHandler: AbstractResultHandler);
-    /** @todo consider migrating tags into augmentation approach in v22 */
-    constructor(params: {
-        resultHandler: AbstractResultHandler;
-        config?: CommonConfig<TAG>;
-    });
-    addMiddleware<AOUT extends FlatObject, ASCO extends string, AIN extends IOSchema<"strip"> = EmptySchema>(subject: Middleware<OUT, AOUT, ASCO, AIN> | ConstructorParameters<typeof Middleware<OUT, AOUT, ASCO, AIN>>[0]): EndpointsFactory<z.ZodIntersection<IN, AIN>, OUT & AOUT, SCO & ASCO, TAG>;
+    addMiddleware<AOUT extends FlatObject, ASCO extends string, AIN extends IOSchema<"strip"> = EmptySchema>(subject: Middleware<OUT, AOUT, ASCO, AIN> | ConstructorParameters<typeof Middleware<OUT, AOUT, ASCO, AIN>>[0]): EndpointsFactory<z.ZodIntersection<IN, AIN>, OUT & AOUT, SCO & ASCO>;
     use: <R extends Request, S extends Response, AOUT extends FlatObject = EmptyObject>(nativeMw: (request: R, response: S, next: express.NextFunction) => void | Promise<void>, params_1?: {
         provider?: ((request: R, response: S) => AOUT | Promise<AOUT>) | undefined;
         transformer?: (err: Error) => Error;
-    } | undefined) => EndpointsFactory<IN, OUT & AOUT, SCO, TAG>;
-    addExpressMiddleware<R extends Request, S extends Response, AOUT extends FlatObject = EmptyObject>(...params: ConstructorParameters<typeof ExpressMiddleware<R, S, AOUT>>): EndpointsFactory<IN, OUT & AOUT, SCO, TAG>;
-    addOptions<AOUT extends FlatObject>(getOptions: () => Promise<AOUT>): EndpointsFactory<IN, OUT & AOUT, SCO, TAG>;
-    build<BOUT extends IOSchema, BIN extends IOSchema = EmptySchema>({ input, handler, output: outputSchema, description, shortDescription, operationId, scope, tag, method, }: BuildProps<BIN, BOUT, IN, OUT, SCO, TAG>): Endpoint<z.ZodIntersection<IN, BIN>, BOUT, OUT>;
+    } | undefined) => EndpointsFactory<IN, OUT & AOUT, SCO>;
+    addExpressMiddleware<R extends Request, S extends Response, AOUT extends FlatObject = EmptyObject>(...params: ConstructorParameters<typeof ExpressMiddleware<R, S, AOUT>>): EndpointsFactory<IN, OUT & AOUT, SCO>;
+    addOptions<AOUT extends FlatObject>(getOptions: () => Promise<AOUT>): EndpointsFactory<IN, OUT & AOUT, SCO>;
+    build<BOUT extends IOSchema, BIN extends IOSchema = EmptySchema>({ input, handler, output: outputSchema, description, shortDescription, operationId, scope, tag, method, }: BuildProps<BIN, BOUT, IN, OUT, SCO>): Endpoint<z.ZodIntersection<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, TAG>, "output">): Endpoint<z.ZodIntersection<IN, BIN>, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, OUT>;
+    buildVoid<BIN extends IOSchema = EmptySchema>({ handler, ...rest }: Omit<BuildProps<BIN, z.ZodVoid, IN, OUT, SCO>, "output">): Endpoint<z.ZodIntersection<IN, BIN>, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, OUT>;
 }
-declare const defaultEndpointsFactory: EndpointsFactory<EmptySchema, EmptyObject, string, string>;
+declare const defaultEndpointsFactory: EndpointsFactory<EmptySchema, EmptyObject, 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<EmptySchema, EmptyObject, string, string>;
+declare const arrayEndpointsFactory: EndpointsFactory<EmptySchema, EmptyObject, string>;
 
 declare const attachRouting: (config: AppConfig, routing: Routing) => {
     notFoundHandler: express__default.RequestHandler<express_serve_static_core.ParamsDictionary, any, any, qs.ParsedQs, Record<string, any>>;
@@ -752,6 +752,10 @@ interface OpenAPIContext extends FlatObject {
     method: Method;
 }
 type Depicter = SchemaHandler<SchemaObject | ReferenceObject, OpenAPIContext>;
+declare const depictTags: (tags: Partial<Record<Tag, string | {
+    description: string;
+    url?: string;
+}>>) => TagObject[];
 
 type Component = "positiveResponse" | "negativeResponse" | "requestParameter" | "requestBody";
 /** @desc user defined function that creates a component description from its properties */
@@ -781,6 +785,12 @@ interface DocumentationParams {
      * @example { MyBrand: ( schema: typeof myBrandSchema, { next } ) => ({ type: "object" })
      */
     brandHandling?: HandlingRules<SchemaObject | ReferenceObject, OpenAPIContext>;
+    /**
+     * @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 {
     protected lastSecuritySchemaIds: Map<SecuritySchemeType, number>;
@@ -789,7 +799,7 @@ declare class Documentation extends OpenApiBuilder {
     protected makeRef(schema: z.ZodTypeAny, subject: SchemaObject | ReferenceObject | (() => SchemaObject | ReferenceObject), name?: string | undefined): ReferenceObject;
     protected ensureUniqOperationId(path: string, method: Method, userDefined?: string): string;
     protected ensureUniqSecuritySchemaName(subject: SecuritySchemeObject): string;
-    constructor({ routing, config, title, version, serverUrl, descriptions, brandHandling, hasSummaryFromDescription, composition, }: DocumentationParams);
+    constructor({ routing, config, title, version, serverUrl, descriptions, brandHandling, tags, hasSummaryFromDescription, composition, }: DocumentationParams);
 }
 
 /** @desc An error related to the wrong Routing declaration */
@@ -899,9 +909,70 @@ declare const testMiddleware: <LOG extends FlatObject, REQ extends RequestOption
     output: FlatObject;
 }>;
 
+type IOKind = "input" | "response" | ResponseVariant | "encoded";
+declare abstract class IntegrationBase {
+    private readonly serverUrl;
+    protected paths: Set<string>;
+    protected tags: Map<string, readonly string[]>;
+    protected registry: Map<string, Record<IOKind, ts.TypeNode>>;
+    protected ids: {
+        pathType: ts.Identifier;
+        methodType: ts.Identifier;
+        requestType: ts.Identifier;
+        inputInterface: ts.Identifier;
+        posResponseInterface: ts.Identifier;
+        negResponseInterface: ts.Identifier;
+        encResponseInterface: ts.Identifier;
+        responseInterface: ts.Identifier;
+        endpointTagsConst: ts.Identifier;
+        implementationType: ts.Identifier;
+        clientClass: ts.Identifier;
+        keyParameter: ts.Identifier;
+        pathParameter: ts.Identifier;
+        paramsArgument: ts.Identifier;
+        methodParameter: ts.Identifier;
+        requestParameter: ts.Identifier;
+        parseRequestFn: ts.Identifier;
+        substituteFn: ts.Identifier;
+        provideMethod: ts.Identifier;
+        implementationArgument: ts.Identifier;
+        headersProperty: ts.Identifier;
+        hasBodyConst: ts.Identifier;
+        undefinedValue: ts.Identifier;
+        bodyProperty: ts.Identifier;
+        responseConst: ts.Identifier;
+        restConst: ts.Identifier;
+        searchParamsConst: ts.Identifier;
+        exampleImplementationConst: ts.Identifier;
+        clientConst: ts.Identifier;
+        contentTypeConst: ts.Identifier;
+        isJsonConst: ts.Identifier;
+    };
+    protected interfaces: Array<{
+        id: ts.Identifier;
+        kind: IOKind;
+    }>;
+    protected methodType: ts.TypeAliasDeclaration;
+    protected someOfType: ts.TypeAliasDeclaration;
+    protected requestType: ts.TypeAliasDeclaration;
+    protected constructor(serverUrl: string);
+    /** @example SomeOf<_> */
+    protected someOf: ({ name }: ts.TypeAliasDeclaration) => ts.TypeReferenceNode;
+    protected makePathType: () => ts.TypeAliasDeclaration;
+    protected makePublicInterfaces: () => ts.InterfaceDeclaration[];
+    protected makeEndpointTags: () => ts.VariableStatement;
+    protected makeImplementationType: () => ts.TypeAliasDeclaration;
+    protected makeParseRequestFn: () => ts.VariableStatement;
+    protected makeSubstituteFn: () => ts.VariableStatement;
+    private makeProvider;
+    protected makeClientClass: () => ts.ClassDeclaration;
+    protected makeExampleImplementation: () => ts.VariableStatement;
+    protected makeUsageStatements: () => (ts.VariableStatement | ts.ExpressionStatement)[];
+}
+
 interface ZTSContext extends FlatObject {
     isResponse: boolean;
-    makeAlias: (schema: z.ZodTypeAny, produce: () => ts.TypeNode) => ts.TypeReferenceNode;
+    makeAlias: (schema: z.ZodTypeAny, produce: () => ts.TypeNode) => ts.TypeNode;
     optionalPropStyle: {
         withQuestionMark?: boolean;
         withUndefined?: boolean;
@@ -909,7 +980,6 @@ interface ZTSContext extends FlatObject {
 }
 type Producer = SchemaHandler<ts.TypeNode, ZTSContext>;
 
-type IOKind = "input" | "response" | ResponseVariant | "encoded";
 interface IntegrationParams {
     routing: Routing;
     /**
@@ -962,54 +1032,11 @@ interface FormattedPrintingOptions {
      * */
     format?: (program: string) => Promise<string>;
 }
-declare class Integration {
-    protected someOf: ts.TypeAliasDeclaration;
+declare class Integration extends IntegrationBase {
     protected program: ts.Node[];
     protected usage: Array<ts.Node | string>;
-    protected registry: Map<string, Record<IOKind, ts.TypeNode> & {
-        tags: ReadonlyArray<string>;
-    }>;
-    protected paths: Set<string>;
     protected aliases: Map<z.ZodTypeAny, ts.TypeAliasDeclaration>;
-    protected ids: {
-        pathType: ts.Identifier;
-        methodType: ts.Identifier;
-        requestType: ts.Identifier;
-        inputInterface: ts.Identifier;
-        posResponseInterface: ts.Identifier;
-        negResponseInterface: ts.Identifier;
-        encResponseInterface: ts.Identifier;
-        responseInterface: ts.Identifier;
-        endpointTagsConst: ts.Identifier;
-        implementationType: ts.Identifier;
-        clientClass: ts.Identifier;
-        keyParameter: ts.Identifier;
-        pathParameter: ts.Identifier;
-        paramsArgument: ts.Identifier;
-        methodParameter: ts.Identifier;
-        requestParameter: ts.Identifier;
-        accumulator: ts.Identifier;
-        provideMethod: ts.Identifier;
-        implementationArgument: ts.Identifier;
-        headersProperty: ts.Identifier;
-        hasBodyConst: ts.Identifier;
-        undefinedValue: ts.Identifier;
-        bodyProperty: ts.Identifier;
-        responseConst: ts.Identifier;
-        searchParamsConst: ts.Identifier;
-        exampleImplementationConst: ts.Identifier;
-        clientConst: ts.Identifier;
-        contentTypeConst: ts.Identifier;
-        isJsonConst: ts.Identifier;
-    };
-    protected interfaces: Array<{
-        id: ts.Identifier;
-        kind: IOKind;
-        props: ts.PropertySignature[];
-    }>;
-    protected makeAlias(schema: z.ZodTypeAny, produce: () => ts.TypeNode): ts.TypeReferenceNode;
-    /** @example SomeOf<_>*/
-    protected makeSomeOf: ({ name }: ts.TypeAliasDeclaration) => ts.TypeReferenceNode;
+    protected makeAlias(schema: z.ZodTypeAny, produce: () => ts.TypeNode): ts.TypeNode;
     constructor({ routing, brandHandling, variant, serverUrl, optionalPropStyle, noContent, }: IntegrationParams);
     protected printUsage(printerOptions?: ts.PrinterOptions): string | undefined;
     print(printerOptions?: ts.PrinterOptions): string;
@@ -1023,12 +1050,8 @@ interface Emitter<E extends EventsMap> extends FlatObject {
     /** @desc Sends an event to the stream accordin to the declared schema */
     emit: <K extends keyof E>(event: K, data: z.input<E[K]>) => void;
 }
-/** @desc This feature is in active development and can be changed or removed regardlress of SemVer */
-declare class EventStreamFactory<E extends EventsMap, TAG extends string> extends EndpointsFactory<EmptySchema, Emitter<E>, string, TAG> {
-    constructor({ events, config }: {
-        events: E;
-        config?: CommonConfig<TAG>;
-    });
+declare class EventStreamFactory<E extends EventsMap> extends EndpointsFactory<EmptySchema, Emitter<E>> {
+    constructor(events: E);
 }
 
-export { type ApiResponse, type AppConfig, type BasicSecurity, type BearerSecurity, BuiltinLogger, type CommonConfig, type CookieSecurity, type CustomHeaderSecurity, DependsOnMethod, type Depicter, Documentation, DocumentationError, EndpointsFactory, EventStreamFactory, type FlatObject, type IOSchema, type InputSecurity, InputValidationError, Integration, type LoggerOverrides, type Method, Middleware, MissingPeerError, type NormalizedResponse, type OAuth2Security, type OpenIdSecurity, OutputValidationError, type Producer, ResultHandler, type Routing, RoutingError, ServeStatic, type ServerConfig, arrayEndpointsFactory, arrayResultHandler, attachRouting, createConfig, createServer, defaultEndpointsFactory, defaultResultHandler, ensureHttpError, ez, getExamples, getMessageFromError, testEndpoint, testMiddleware };
+export { type ApiResponse, type AppConfig, type BasicSecurity, type BearerSecurity, BuiltinLogger, type CommonConfig, type CookieSecurity, type CustomHeaderSecurity, DependsOnMethod, type Depicter, Documentation, DocumentationError, EndpointsFactory, EventStreamFactory, type FlatObject, type IOSchema, type InputSecurity, InputValidationError, Integration, type LoggerOverrides, type Method, Middleware, MissingPeerError, type NormalizedResponse, type OAuth2Security, type OpenIdSecurity, OutputValidationError, type Producer, ResultHandler, type Routing, RoutingError, ServeStatic, type ServerConfig, type TagOverrides, arrayEndpointsFactory, arrayResultHandler, attachRouting, createConfig, createServer, defaultEndpointsFactory, defaultResultHandler, ensureHttpError, ez, getExamples, getMessageFromError, testEndpoint, testMiddleware };