express-zod-api 21.9.0 → 22.0.0-beta.2

package/dist/index.d.cts

@@ -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';
@@ -442,15 +442,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 +482,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 +529,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 +572,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 +656,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 +665,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 +747,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 +780,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 +794,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 */
@@ -920,10 +925,10 @@ interface IntegrationParams {
      * */
     variant?: "types" | "client";
     /**
-     * @todo remove in v22
-     * @deprecated
+     * @desc The API URL to use in the generated code
+     * @default https://example.com
      * */
-    splitResponse?: boolean;
+    serverUrl?: string;
     /**
      * @desc configures the style of object's optional properties
      * @default { withQuestionMark: true, withUndefined: true }
@@ -967,7 +972,6 @@ declare class Integration {
     protected program: ts.Node[];
     protected usage: Array<ts.Node | string>;
     protected registry: Map<string, Record<IOKind, ts.TypeNode> & {
-        isJson: boolean;
         tags: ReadonlyArray<string>;
     }>;
     protected paths: Set<string>;
@@ -976,18 +980,12 @@ declare class Integration {
         pathType: ts.Identifier;
         methodType: ts.Identifier;
         requestType: ts.Identifier;
-        /** @todo remove in v22 */
-        methodPathType: ts.Identifier;
         inputInterface: ts.Identifier;
         posResponseInterface: ts.Identifier;
         negResponseInterface: ts.Identifier;
         encResponseInterface: ts.Identifier;
         responseInterface: ts.Identifier;
-        /** @todo remove in v22 */
-        jsonEndpointsConst: ts.Identifier;
         endpointTagsConst: ts.Identifier;
-        /** @todo remove in v22 */
-        providerType: ts.Identifier;
         implementationType: ts.Identifier;
         clientClass: ts.Identifier;
         keyParameter: ts.Identifier;
@@ -995,8 +993,6 @@ declare class Integration {
         paramsArgument: ts.Identifier;
         methodParameter: ts.Identifier;
         requestParameter: ts.Identifier;
-        /** @todo use request and params in v22 */
-        args: ts.Identifier;
         accumulator: ts.Identifier;
         provideMethod: ts.Identifier;
         implementationArgument: ts.Identifier;
@@ -1019,7 +1015,7 @@ declare class Integration {
     protected makeAlias(schema: z.ZodTypeAny, produce: () => ts.TypeNode): ts.TypeReferenceNode;
     /** @example SomeOf<_>*/
     protected makeSomeOf: ({ name }: ts.TypeAliasDeclaration) => ts.TypeReferenceNode;
-    constructor({ routing, brandHandling, variant, optionalPropStyle, noContent, }: IntegrationParams);
+    constructor({ routing, brandHandling, variant, serverUrl, optionalPropStyle, noContent, }: IntegrationParams);
     protected printUsage(printerOptions?: ts.PrinterOptions): string | undefined;
     print(printerOptions?: ts.PrinterOptions): string;
     printFormatted({ printerOptions, format: userDefined, }?: FormattedPrintingOptions): Promise<string>;
@@ -1032,12 +1028,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 };

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';
@@ -442,15 +442,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 +482,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 +529,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 +572,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 +656,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 +665,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 +747,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 +780,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 +794,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 */
@@ -920,10 +925,10 @@ interface IntegrationParams {
      * */
     variant?: "types" | "client";
     /**
-     * @todo remove in v22
-     * @deprecated
+     * @desc The API URL to use in the generated code
+     * @default https://example.com
      * */
-    splitResponse?: boolean;
+    serverUrl?: string;
     /**
      * @desc configures the style of object's optional properties
      * @default { withQuestionMark: true, withUndefined: true }
@@ -967,7 +972,6 @@ declare class Integration {
     protected program: ts.Node[];
     protected usage: Array<ts.Node | string>;
     protected registry: Map<string, Record<IOKind, ts.TypeNode> & {
-        isJson: boolean;
         tags: ReadonlyArray<string>;
     }>;
     protected paths: Set<string>;
@@ -976,18 +980,12 @@ declare class Integration {
         pathType: ts.Identifier;
         methodType: ts.Identifier;
         requestType: ts.Identifier;
-        /** @todo remove in v22 */
-        methodPathType: ts.Identifier;
         inputInterface: ts.Identifier;
         posResponseInterface: ts.Identifier;
         negResponseInterface: ts.Identifier;
         encResponseInterface: ts.Identifier;
         responseInterface: ts.Identifier;
-        /** @todo remove in v22 */
-        jsonEndpointsConst: ts.Identifier;
         endpointTagsConst: ts.Identifier;
-        /** @todo remove in v22 */
-        providerType: ts.Identifier;
         implementationType: ts.Identifier;
         clientClass: ts.Identifier;
         keyParameter: ts.Identifier;
@@ -995,8 +993,6 @@ declare class Integration {
         paramsArgument: ts.Identifier;
         methodParameter: ts.Identifier;
         requestParameter: ts.Identifier;
-        /** @todo use request and params in v22 */
-        args: ts.Identifier;
         accumulator: ts.Identifier;
         provideMethod: ts.Identifier;
         implementationArgument: ts.Identifier;
@@ -1019,7 +1015,7 @@ declare class Integration {
     protected makeAlias(schema: z.ZodTypeAny, produce: () => ts.TypeNode): ts.TypeReferenceNode;
     /** @example SomeOf<_>*/
     protected makeSomeOf: ({ name }: ts.TypeAliasDeclaration) => ts.TypeReferenceNode;
-    constructor({ routing, brandHandling, variant, optionalPropStyle, noContent, }: IntegrationParams);
+    constructor({ routing, brandHandling, variant, serverUrl, optionalPropStyle, noContent, }: IntegrationParams);
     protected printUsage(printerOptions?: ts.PrinterOptions): string | undefined;
     print(printerOptions?: ts.PrinterOptions): string;
     printFormatted({ printerOptions, format: userDefined, }?: FormattedPrintingOptions): Promise<string>;
@@ -1032,12 +1028,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 };