expresso-macchiato 1.0.0-dev.7 → 1.0.0-dev.9

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-import { Request, Response as Response$1, RequestHandler, Router, Express } from 'express';
+import { Request, Response, Router, RequestHandler, Express } from 'express';
+import { ParamDefinition, ExpressoSwagger, HttpMethod, ExpressoSwaggerDocument, ExpressoSwaggerModel } from 'expresso-swagger';
 import { BaseEntity, MixedList, EntitySchema } from 'typeorm';
-import { Socket, Namespace, Server as Server$1, ServerOptions } from 'socket.io';
+import { Socket, Namespace, Server, ServerOptions } from 'socket.io';
 import http from 'http';
 import * as utils_logger_av from 'utils-logger-av';
 import { Logger } from 'utils-logger-av';
@@ -16,6 +17,38 @@ declare class BackgroundService {
     constructor(data: BackgroundServiceConstructor);
 }
 
+type CustomSwaggerParameter = ParamDefinition & {
+    in: 'path' | 'query';
+    name: string;
+    like?: boolean;
+};
+declare class MySwagger extends ExpressoSwagger {
+    constructor();
+    private fromExpressParamsToSwagger;
+    setBaseUrl(url: string): void;
+    addSchema(name: string, schema: any): void;
+    /**
+     * Adds a single API path by accumulating it into the internal list.
+     */
+    addSingleApiPath(group: string, basePath: string, _path: string, method: HttpMethod, options: {
+        name?: string;
+        description?: string;
+        parameters?: Array<CustomSwaggerParameter>;
+        body?: any;
+        responses?: Record<string | number, {
+            description: string;
+            body?: any;
+        }>;
+    }): void;
+    static getIdParam: (name?: string) => any;
+    static getPaginationParams: () => any[];
+    /**
+     * Instantiates ExpressoSwagger and generates the final document.
+     */
+    generateDocument(): ExpressoSwaggerDocument;
+}
+declare const Swagger: MySwagger;
+
 type ErrorsMapping = Record<string, {
     status?: number;
     responseMessage?: string;
@@ -50,346 +83,6 @@ type ListOptions = {
     order?: 'ASC' | 'DESC';
 } & SearchQuery;
 
-interface Info {
-    title: string;
-    version: string;
-    description?: string | undefined;
-    termsOfService?: string | undefined;
-    contact?: Contact | undefined;
-    license?: License | undefined;
-}
-interface Contact {
-    name?: string | undefined;
-    email?: string | undefined;
-    url?: string | undefined;
-}
-interface License {
-    name: string;
-    url?: string | undefined;
-}
-interface ExternalDocs {
-    url: string;
-    description?: string | undefined;
-}
-interface Tag {
-    name: string;
-    description?: string | undefined;
-    externalDocs?: ExternalDocs | undefined;
-}
-interface Header extends BaseSchema {
-    type: ParameterType;
-}
-type ParameterType = "string" | "number" | "integer" | "boolean" | "array" | "object" | "file" | "date";
-type BaseParameter = {
-    name: string;
-    in: "body" | "query" | "path" | "header" | "formData";
-    required?: boolean | undefined;
-    description?: string | undefined;
-};
-type BodyParameter = BaseParameter & {
-    in: "body";
-    schema?: Schema | undefined;
-};
-type GenericFormat = {
-    type?: ParameterType | undefined;
-    format?: string | undefined;
-};
-type IntegerFormat = {
-    type: "integer";
-    format?: "int32" | "int64" | undefined;
-};
-type NumberFormat = {
-    type: "number";
-    format?: "float" | "double" | undefined;
-};
-type StringFormat = {
-    type: "string";
-    format?: "" | "byte" | "binary" | "date" | "date-time" | "password" | undefined;
-};
-type SchemaFormatConstraints = GenericFormat | IntegerFormat | NumberFormat | StringFormat;
-type BaseFormatContrainedParameter = BaseParameter & SchemaFormatConstraints;
-type ParameterCollectionFormat = "csv" | "ssv" | "tsv" | "pipes" | "multi";
-type QueryParameter = BaseFormatContrainedParameter & BaseSchema & {
-    in: "query";
-    allowEmptyValue?: boolean | undefined;
-    collectionFormat?: ParameterCollectionFormat | undefined;
-};
-type PathParameter = BaseFormatContrainedParameter & BaseSchema & {
-    in: "path";
-    required: boolean;
-};
-type HeaderParameter = BaseFormatContrainedParameter & BaseSchema & {
-    in: "header";
-};
-type FormDataParameter = BaseFormatContrainedParameter & BaseSchema & {
-    in: "formData";
-    type: ParameterType | "file";
-    allowEmptyValue?: boolean | undefined;
-    collectionFormat?: ParameterCollectionFormat | undefined;
-};
-type Parameter = {
-    like?: boolean;
-} & (BodyParameter | FormDataParameter | QueryParameter | PathParameter | HeaderParameter);
-interface Path {
-    $ref?: string | undefined;
-    get?: Operation | undefined;
-    put?: Operation | undefined;
-    post?: Operation | undefined;
-    delete?: Operation | undefined;
-    options?: Operation | undefined;
-    head?: Operation | undefined;
-    patch?: Operation | undefined;
-    parameters?: Array<Parameter | Reference> | undefined;
-}
-interface DynamicSwaggerPath {
-    $ref?: string | undefined;
-    get?: DynamicSwaggerOperation | undefined;
-    put?: DynamicSwaggerOperationBody | undefined;
-    post?: DynamicSwaggerOperationBody | undefined;
-    delete?: DynamicSwaggerOperationBody | undefined;
-    options?: DynamicSwaggerOperation | undefined;
-    head?: DynamicSwaggerOperation | undefined;
-    patch?: DynamicSwaggerOperation | undefined;
-    parameters?: Array<Parameter | Reference> | undefined;
-}
-interface Components {
-    schemas?: {
-        [schemaName: string]: SchemaV3;
-    };
-    parameters?: {
-        [parameterName: string]: Parameter;
-    };
-    securitySchemes?: Record<string, {
-        type: 'http';
-        scheme: 'bearer';
-        bearerFormat?: 'JWT';
-    }>;
-}
-interface Operation {
-    responses: {
-        [responseName: string]: Response | Reference;
-    };
-    summary?: string | undefined;
-    description?: string | undefined;
-    externalDocs?: ExternalDocs | undefined;
-    operationId?: string | undefined;
-    produces?: string[] | undefined;
-    consumes?: string[] | undefined;
-    parameters?: Array<Parameter | Reference> | undefined;
-    schemes?: string[] | undefined;
-    deprecated?: boolean | undefined;
-    security?: Array<{
-        [securityDefinitionName: string]: string[];
-    }> | undefined;
-    tags?: string[] | undefined;
-    requestBody?: RequestBodyOperation;
-}
-interface DynamicSwaggerOperation {
-    responses: {
-        [responseName: string]: Response | Reference;
-    };
-    summary?: string | undefined;
-    description?: string | undefined;
-    operationId?: string | undefined;
-    parameters?: Array<Parameter | Reference> | undefined;
-    deprecated?: boolean | undefined;
-    security?: Array<{
-        [securityDefinitionName: string]: string[];
-    }> | undefined;
-    tags?: string[] | undefined;
-}
-interface DynamicSwaggerOperationBody {
-    responses: {
-        [responseName: string]: Response | Reference;
-    };
-    summary?: string | undefined;
-    description?: string | undefined;
-    operationId?: string | undefined;
-    parameters?: Array<Parameter | Reference> | undefined;
-    deprecated?: boolean | undefined;
-    security?: Array<{
-        [securityDefinitionName: string]: string[];
-    }> | undefined;
-    tags?: string[] | undefined;
-    requestBody?: {
-        required: boolean;
-        description?: string;
-        schemaName: string;
-        schema?: {
-            [key: string]: SchemaV3;
-        };
-        comType?: 'multipart/form-data' | 'application/json' | undefined;
-    };
-}
-type RequestBodyOperation = {
-    description?: string;
-    required: boolean;
-    content: {
-        "application/json": {
-            schema: {
-                $ref: string;
-            };
-        };
-    } | {
-        "multipart/form-data": {
-            schema: {
-                $ref: string;
-            };
-        };
-    };
-};
-type DynamicSwaggerRequestBodyOperation = {
-    description?: string;
-    required: boolean;
-    content: {
-        "application/json": {
-            schema: {
-                $ref: string;
-            };
-        };
-    };
-};
-interface Reference {
-    $ref: string;
-}
-interface Response {
-    description: string;
-    schema?: Schema | undefined;
-    headers?: {
-        [headerName: string]: Header;
-    } | undefined;
-    examples?: {
-        [exampleName: string]: {};
-    } | undefined;
-}
-type BaseSchema = {
-    type?: ParameterType | undefined;
-    format?: string | undefined;
-    title?: string | undefined;
-    description?: string | undefined;
-    default?: any;
-    multipleOf?: number | undefined;
-    maximum?: number | undefined;
-    exclusiveMaximum?: boolean | undefined;
-    minimum?: number | undefined;
-    exclusiveMinimum?: boolean | undefined;
-    maxLength?: number | undefined;
-    minLength?: number | undefined;
-    pattern?: string | undefined;
-    maxItems?: number | undefined;
-    minItems?: number | undefined;
-    uniqueItems?: boolean | undefined;
-    maxProperties?: number | undefined;
-    minProperties?: number | undefined;
-    enum?: any[] | undefined;
-    items?: Schema | Schema[] | undefined;
-};
-interface Schema extends BaseSchema {
-    $ref?: string | undefined;
-    allOf?: Schema[] | undefined;
-    additionalProperties?: Schema | boolean | undefined;
-    properties?: {
-        [propertyName: string]: Schema;
-    } | undefined;
-    discriminator?: string | undefined;
-    readOnly?: boolean | undefined;
-    xml?: XML | undefined;
-    externalDocs?: ExternalDocs | undefined;
-    example?: any;
-    required?: boolean;
-}
-interface SchemaV3 extends BaseSchema {
-    type: "object";
-    properties?: {
-        [propertyName: string]: Schema;
-    } | undefined;
-    required?: boolean;
-}
-interface XML {
-    name?: string | undefined;
-    namespace?: string | undefined;
-    prefix?: string | undefined;
-    attribute?: boolean | undefined;
-    wrapped?: boolean | undefined;
-}
-interface BaseSecurity {
-    type: "basic" | "apiKey" | "oauth2";
-    description?: string | undefined;
-}
-interface BasicAuthenticationSecurity extends BaseSecurity {
-    type: "basic";
-}
-interface ApiKeySecurity extends BaseSecurity {
-    type: "apiKey";
-    name: string;
-    in: "query" | "header";
-}
-interface BaseOAuthSecurity extends BaseSecurity {
-    type: "oauth2";
-    flow: "accessCode" | "application" | "implicit" | "password";
-    scopes?: OAuthScope | undefined;
-}
-interface OAuth2ImplicitSecurity extends BaseOAuthSecurity {
-    type: "oauth2";
-    flow: "implicit";
-    authorizationUrl: string;
-}
-interface OAuth2PasswordSecurity extends BaseOAuthSecurity {
-    type: "oauth2";
-    flow: "password";
-    tokenUrl: string;
-}
-interface OAuth2ApplicationSecurity extends BaseOAuthSecurity {
-    type: "oauth2";
-    flow: "application";
-    tokenUrl: string;
-}
-interface OAuth2AccessCodeSecurity extends BaseOAuthSecurity {
-    type: "oauth2";
-    flow: "accessCode";
-    tokenUrl: string;
-    authorizationUrl: string;
-}
-interface OAuthScope {
-    [scopeName: string]: string;
-}
-type Security = BasicAuthenticationSecurity | OAuth2AccessCodeSecurity | OAuth2ApplicationSecurity | OAuth2ImplicitSecurity | OAuth2PasswordSecurity | ApiKeySecurity;
-type Server = {
-    url: string;
-    description?: string;
-};
-interface Spec {
-    openapi: "3.0.4";
-    info: Info;
-    servers: Server[];
-    paths: {
-        [pathName: string]: Path;
-    };
-    tags?: Tag[];
-    components?: Components;
-    externalDocs?: ExternalDocs | undefined;
-    host?: string | undefined;
-    basePath?: string | undefined;
-    schemes?: string[] | undefined;
-    consumes?: string[] | undefined;
-    produces?: string[] | undefined;
-    definitions?: {
-        [definitionsName: string]: Schema;
-    } | undefined;
-    parameters?: {
-        [parameterName: string]: BodyParameter | QueryParameter;
-    } | undefined;
-    responses?: {
-        [responseName: string]: Response;
-    } | undefined;
-    security?: Array<{
-        [securityDefinitionName: string]: string[];
-    }> | undefined;
-    securityDefinitions?: {
-        [securityDefinitionName: string]: Security;
-    } | undefined;
-}
-
 type DefaultTokenPayload = {
     id: string;
     [key: string]: any;
@@ -409,23 +102,44 @@ type TokenConstructor = {
 };
 type TokenApiOptions = {
     path?: string;
-    callback: (req: Request, res: Response$1) => Promise<void>;
+    callback: (req: Request, res: Response) => Promise<void>;
+};
+
+type DynamicDbRouterOptions<T extends typeof BaseEntity> = {
+    router: Router;
+    entity: T;
+    primaryKey?: string;
+    tag: string;
+    basePath: string;
+    getParameters?: Array<CustomSwaggerParameter>;
+    bodyParameters?: ExpressoSwaggerModel;
+    avoid?: Array<Methods | 'LIST'>;
+    secure?: SecureTokenConfig;
+    returningProps?: string[];
+    responses?: Record<string | number, {
+        description: string;
+        body?: any;
+    }>;
 };
 
 interface RouterWrapperInterface<T extends typeof BaseEntity = typeof BaseEntity> {
     basePath: string;
     tag: string;
     swaggerNewSchemas?: {
-        [schema: string]: SchemaV3;
+        [schema: string]: ExpressoSwaggerModel;
     };
     dbRouting?: {
         entity: T;
         primaryKey?: string;
-        getParameters?: Array<Parameter>;
-        bodyParameters?: SchemaV3;
+        getParameters?: Array<CustomSwaggerParameter>;
+        bodyParameters?: ExpressoSwaggerModel;
         avoid?: Array<Methods | 'LIST'>;
         secure?: SecureTokenConfig;
         returningProps?: string[];
+        responses?: Record<string | number, {
+            description: string;
+            body?: any;
+        }>;
     };
     apis?: Record<string, {
         'GET'?: MethodPathHandling;
@@ -441,10 +155,10 @@ type MethodPathHandling = {
         description?: string;
         comType?: 'application/json' | 'multipart/form-data';
     };
-    swaggerResponses?: Record<string, Reference | Response>;
-    swaggerParameters?: Array<Parameter>;
+    swaggerResponses?: DynamicDbRouterOptions<any>['responses'];
+    swaggerParameters?: Array<CustomSwaggerParameter>;
     middlewares?: RequestHandler[];
-    handler: (req: Request, res: Response$1) => Promise<ExpressReturn>;
+    handler: (req: Request, res: Response) => Promise<ExpressReturn>;
 };
 
 declare class RouterWrapper {
@@ -483,7 +197,7 @@ declare class SocketWrapper<Metadata extends Record<string, any> = any> {
     protected readonly data: SocketWrapperConstructor<Metadata>;
     protected namespace?: Namespace;
     constructor(data: SocketWrapperConstructor<Metadata>);
-    setupConnection: (io: Server$1) => void;
+    setupConnection: (io: Server) => void;
     protected handleDisconnection: (clientId: string) => void;
     broadcast: (eventName: string, data: any) => void;
     broadcastExceptClient: (clientId: string, eventName: string, data: any) => void;
@@ -503,7 +217,7 @@ declare class Token<Payload extends Record<string, any> = DefaultTokenPayload> {
     private keyStore;
     constructor(tokenPayload: TokenConstructor);
     private getKey;
-    authorize(req: Request): Promise<Payload>;
+    authorize(req: Request | string): Promise<Payload>;
     private deriveEncryptionKey;
     generateJWE(payload: Payload): Promise<string>;
     verifyJWE(token: string): Promise<Payload>;
@@ -515,7 +229,7 @@ type StarterOptions = {
     clientPath?: string;
     swagger?: boolean;
     projectConfig: ProjectConfigs;
-    beforeStartListening?: (app: Express, httpServer?: http.Server, socketIoServerInstance?: Server$1) => void;
+    beforeStartListening?: (app: Express, httpServer?: http.Server, socketIoServerInstance?: Server) => void;
     sockets?: {
         wrappers: Array<SocketWrapper>;
         options?: Partial<ServerOptions>;
@@ -539,108 +253,6 @@ declare class Starter {
     private initDb;
 }
 
-declare class Swagger {
-    private static fromExpressParamsToSwagger;
-    private static readonly restMethodToSwaggerKeyMapping;
-    static addServer: (server: {
-        url: string;
-    }) => number;
-    static generateOpenAPIDocument: () => any;
-    static apiDocument: Spec;
-    /**
-     * @Description
-     * - ❌ ROUTER-WRAPPER.
-     * - 🛠️ ADD-API-PATH
-     * - This method is not directly to insert inside the structur of addApiPath but is useful to create Schemas while not using the routerWrapper
-     */
-    static addSchema: (schema: string, properties?: {
-        [propName: string]: Schema;
-    }) => void;
-    /**
-     * @Description
-     * - ❌ ROUTER-WRAPPER.
-     * - 🛠️ ADD-API-PATH
-     * - This method is thought to reduce the code in the addApiPath method
-     * - You can create a schema while declaring it and associating to the path calling this method
-     */
-    static getBasicPost: (schema: string, required: boolean, parameters?: Parameter[], properties?: {
-        [propName: string]: Schema;
-    }, description?: string) => DynamicSwaggerOperationBody;
-    /**
-     * @Description
-     * - ❌ **ROUTER-WRAPPER.**
-     * - 🛠️ **ADD-API-PATH**
-     * - This method is thought to reduce the code in the addApiPath method
-     */
-    static getBasicGet: (parameters?: Array<Parameter>) => DynamicSwaggerOperation;
-    /**
-     * @Description
-     * - ❌ ROUTER-WRAPPER.
-     * - This method is useful if you don't want to  use the router wrapper but add your swagger schema anyway.
-     * - **It is thought to be used inside the library**, iterating through the paths of the router wrapper.
-     * - **Devs can't use inside the parameters of a RouterWrapper constructor**
-     * - You can create the structure of a specified path and method, with a schema name that should be created elsewhere
-     */
-    static addSingleApiPath: (tag: string, basePath: string, _path: string, method: "GET" | "POST" | "PUT" | "DELETE", parameters?: Array<Parameter>, bodyObj?: {
-        schema: string;
-        required?: boolean;
-        description?: string;
-        comType?: "application/json" | "multipart/form-data";
-    }, responses?: Record<string, Reference | Response>) => void;
-    /**
-     * @Description
-     * - ❌ ROUTER-WRAPPER.
-     * - 🛠️ ADD-API-PATH
-     * - **This method is useful if you don't want to  use the router wrapper but add your swagger schema anyway**.
-     * - You can use other other methods of this class to ease the writing
-     * - It is thought to create a full section of apis (hypotetically under one single tag) **while you create the schema in the meanwhile**
-     */
-    static _addApiPath: (tag: string, basePath: string, options: {
-        [key: string]: DynamicSwaggerPath;
-    }) => void;
-    /**
-     * @Description
-     * - ✅ ROUTER-WRAPPER
-     * - Returns the tipical /:id parameter
-     */
-    static getIdParam: (pkLabel?: string) => Parameter;
-    /**
-     * @Description
-     * - ✅ ROUTER-WRAPPER
-     * - Returns the tipical list pagination parameters
-     */
-    static getPaginationParams: (options?: ListOptions) => Parameter[];
-    /**
-     * @Description
-     * - ✅ ROUTER-WRAPPER
-     * - Creates the swagger schema expected by your api
-     */
-    static createMultipartSchema: (name?: string, props?: {
-        [prop: string]: Schema;
-    }) => SchemaV3;
-    /**
-     * @Description
-     * - ✅ ROUTER-WRAPPER
-     * - Creates the swagger schema expected by your api
-     */
-    static createSchema: (props: {
-        [prop: string]: Schema | ParameterType;
-    }, required?: boolean) => SchemaV3;
-}
-
-type DynamicDbRouterOptions<T extends typeof BaseEntity> = {
-    router: Router;
-    entity: T;
-    primaryKey?: string;
-    tag: string;
-    basePath: string;
-    getParameters?: Array<Parameter>;
-    bodyParameters?: SchemaV3;
-    avoid?: Array<Methods | 'LIST'>;
-    secure?: SecureTokenConfig;
-    returningProps?: string[];
-};
-
 declare class MyLogger extends Logger {
     setFilePath: (filePath?: string) => void;
     fullLogOk: (service: string, message: string) => void;
@@ -653,10 +265,10 @@ declare const fullLogOk: (service: string, message: string) => void;
 declare const fullLogNok: (service: string, ...args: any[]) => void;
 declare const apiOk: (res: any, status?: number, contentType?: string) => ExpressReturn;
 declare const apiNok: (err: any, status?: number) => ExpressReturn;
-declare const errorCatcher: (res: Response$1, err: unknown, errorsList?: ErrorsMapping, errorString?: string) => void;
+declare const errorCatcher: (res: Response, err: unknown, errorsList?: ErrorsMapping, errorString?: string) => void;
 declare const socketOk: <T extends Record<string, any> = any>(newMetadata?: T) => SocketConnectionOk;
 declare const socketNok: (message: string) => SocketConnectionNok;
 declare const sleep: (ms: number) => Promise<unknown>;
 declare const getCompiledPath: (__filename: string, __dirname: string, pathsWithoutExtension: string[]) => string[];
 
-export { type ApiKeySecurity, BackgroundService, type BaseFormatContrainedParameter, type BaseOAuthSecurity, type BaseParameter, type BaseSchema, type BaseSecurity, type BasicAuthenticationSecurity, type BodyParameter, type Components, type ConnectedSocketClient, type Contact, type DefaultTokenPayload, type DynamicDbRouterOptions, type DynamicSwaggerOperation, type DynamicSwaggerOperationBody, type DynamicSwaggerPath, type DynamicSwaggerRequestBodyOperation, type ErrorsMapping, type ExpressReturn, type ExternalDocs, type FormDataParameter, type GenericFormat, type Header, type HeaderParameter, type Info, type IntegerFormat, type License, type ListOptions, type MethodPathHandling, type Methods, type NumberFormat, type OAuth2AccessCodeSecurity, type OAuth2ApplicationSecurity, type OAuth2ImplicitSecurity, type OAuth2PasswordSecurity, type OAuthScope, type Operation, type Parameter, type ParameterCollectionFormat, type ParameterType, type Path, type PathParameter, type ProjectConfigs, type QueryParameter, type Reference, type RequestBodyOperation, type Response, RouterWrapper, type RouterWrapperInterface, type Schema, type SchemaFormatConstraints, type SchemaV3, type SearchQuery, type SecureTokenConfig, type Security, type Server, type SocketConnectionMiddleware, type SocketConnectionNok, type SocketConnectionOk, SocketWrapper, type SocketWrapperConstructor, type Spec, Starter, type StarterOptions, type StringFormat, Swagger, type SwaggerMetadataInterface, type Tag, Token, type TokenApiOptions, type TokenConstructor, type XML, apiNok, apiOk, c, errorCatcher, fullLogNok, fullLogOk, getCompiledPath, i, log, sleep, socketNok, socketOk };
+export { BackgroundService, type ConnectedSocketClient, type DefaultTokenPayload, type DynamicDbRouterOptions, type ErrorsMapping, type ExpressReturn, type ListOptions, type MethodPathHandling, type Methods, type ProjectConfigs, RouterWrapper, type RouterWrapperInterface, type SearchQuery, type SecureTokenConfig, type SocketConnectionMiddleware, type SocketConnectionNok, type SocketConnectionOk, SocketWrapper, type SocketWrapperConstructor, Starter, type StarterOptions, Swagger, type SwaggerMetadataInterface, Token, type TokenApiOptions, type TokenConstructor, apiNok, apiOk, c, errorCatcher, fullLogNok, fullLogOk, getCompiledPath, i, log, sleep, socketNok, socketOk };