expresso-macchiato 0.3.0

package/README.md

@@ -0,0 +1,3 @@
+# Expresso-macchiato
+
+Deploying the doc, repo not public yet.

package/dist/index.d.mts

@@ -0,0 +1,603 @@
+import { Request, Response as Response$1, RequestHandler, Router, Express } from 'express';
+import { BaseEntity, MixedList, EntitySchema } from 'typeorm';
+import http from 'http';
+import { Logger } from 'utils-logger-av';
+
+type ErrorsMapping = Record<string, {
+    status?: number;
+    responseMessage?: string;
+}>;
+type Methods = "GET" | "DELETE" | "PUT" | "POST";
+type ExpressReturn = {
+    isOk: boolean;
+    result: any;
+    status: number;
+    contentType?: string;
+};
+type SwaggerMetadataInterface = {
+    required?: boolean;
+    hide?: boolean;
+};
+type ProjectConfigs = {
+    SERVER_PORT: number;
+    DB_DIALECT?: string;
+    DB_NAME?: string;
+    DB_HOST?: string;
+    DB_PORT?: number;
+    DB_USER?: string;
+    DB_PASSWORD?: string;
+    API_URL?: string;
+    ERROR_FILE_PATH?: string;
+};
+type SearchQuery = Record<string, string | number | boolean | undefined | null>;
+type ListOptions = {
+    pageSize?: number;
+    page?: number;
+    orderBy?: string;
+    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;
+};
+type SecureTokenConfig = boolean | {
+    [columnName: string]: {
+        tokenKey: string;
+        methods: "*" | Array<Methods | "LIST">;
+    };
+};
+type TokenConstructor = {
+    SECRET_KEY: string;
+    ExpTime: number;
+    EncAlgorithm: string;
+    KeyLength: number;
+};
+type TokenApiOptions = {
+    path?: string;
+    callback: (req: Request, res: Response$1) => Promise<void>;
+};
+
+interface RouterWrapperInterface<T extends typeof BaseEntity = typeof BaseEntity> {
+    basePath: string;
+    tag: string;
+    swaggerNewSchemas?: {
+        [schema: string]: SchemaV3;
+    };
+    dbRouting?: {
+        entity: T;
+        primaryKey?: string;
+        getParameters?: Array<Parameter>;
+        bodyParameters?: SchemaV3;
+        avoid?: Array<Methods | 'LIST'>;
+        secure?: SecureTokenConfig;
+        returningProps?: string[];
+    };
+    apis?: Record<string, {
+        'GET'?: MethodPathHandling;
+        'POST'?: MethodPathHandling;
+        'PUT'?: MethodPathHandling;
+        'DELETE'?: MethodPathHandling;
+    }>;
+}
+type MethodPathHandling = {
+    swaggerBody?: {
+        schema: string;
+        required?: boolean;
+        description?: string;
+        comType?: 'application/json' | 'multipart/form-data';
+    };
+    swaggerResponses?: Record<string, Reference | Response>;
+    swaggerParameters?: Array<Parameter>;
+    middlewares?: RequestHandler[];
+    handler: (req: Request, res: Response$1) => Promise<ExpressReturn>;
+};
+
+declare class RouterWrapper {
+    readonly basePath: string;
+    private readonly data;
+    constructor(data: RouterWrapperInterface);
+    createExpressRouter: () => Router;
+}
+
+declare class Token<Payload extends Record<string, any> = DefaultTokenPayload> {
+    private SECRET_KEY;
+    private ExpTime;
+    private EncAlgorithm;
+    private KeyLength;
+    private keyStore;
+    constructor(tokenPayload: TokenConstructor);
+    private getKey;
+    authorize: (req: Request) => Promise<Payload>;
+    private deriveEncryptionKey;
+    generateJWE(payload: Payload): Promise<string>;
+    verifyJWE(token: string): Promise<Payload>;
+}
+
+type StarterOptions = {
+    plugins?: Array<any>;
+    routers?: Array<RouterWrapper>;
+    clientPath?: string;
+    swagger?: boolean;
+    projectConfig: ProjectConfigs;
+    beforeStartListening?: (app: Express, server?: http.Server) => void;
+    socket?: boolean;
+    tokenOptions?: {
+        tokenInstance: Token;
+        api?: TokenApiOptions;
+    };
+    db?: {
+        entities: MixedList<Function | string | EntitySchema>;
+        migrations?: string[];
+        sync?: boolean;
+        afterDbConnection?: () => Promise<void>;
+    };
+};
+type SocketWrapperConstructor = {
+    name: string;
+    beforeConnection?: () => Promise<void>;
+    onDisconnect?: (...params: any[]) => Promise<void>;
+    listeners?: Record<string, (...params: any[]) => Promise<void>>;
+};
+
+declare class Starter {
+    constructor(options: StarterOptions);
+    private init;
+    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;
+    fullLogNok: (service: string, error: any, ...args: any[]) => void;
+}
+declare const log: MyLogger;
+declare const fullLogOk: (service: string, message: string) => void;
+declare const fullLogNok: (service: string, error: any, ...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;
+
+export { type ApiKeySecurity, type BaseFormatContrainedParameter, type BaseOAuthSecurity, type BaseParameter, type BaseSchema, type BaseSecurity, type BasicAuthenticationSecurity, type BodyParameter, type Components, 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 SocketWrapperConstructor, type Spec, Starter, type StarterOptions, type StringFormat, Swagger, type SwaggerMetadataInterface, type Tag, Token, type TokenApiOptions, type TokenConstructor, type XML, apiNok, apiOk, errorCatcher, fullLogNok, fullLogOk, log };