expresso-macchiato 0.3.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "expresso-macchiato",
+  "version": "0.3.0",
+  "author": "Alessio Velluso",
+  "license": "MIT",
+  "description": "Description",
+  "devDependencies": {
+    "@types/bcrypt": "^5.0.2",
+    "@types/body-parser": "^1.19.5",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.5",
+    "@types/multer": "^1.4.12",
+    "@types/node": "^22.13.10",
+    "@types/node-jose": "^1.1.13",
+    "@types/swagger-ui-express": "^4.1.8",
+    "@types/validator": "^13.12.2",
+    "@types/winston": "^2.4.4",
+    "@typescript-eslint/eslint-plugin": "^6.18.1",
+    "@typescript-eslint/parser": "^6.18.1",
+    "eslint": "^8.56.0",
+    "express-winston": "^4.2.0",
+    "nodemon": "^3.0.2",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.1.0",
+    "typescript": "^5.3.3",
+    "winston": "^3.11.0"
+  },
+  "dependencies": {
+    "bcrypt": "^5.1.1",
+    "body-parser": "^1.20.2",
+    "cors": "^2.8.5",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2",
+    "jsonwebtoken": "^9.0.2",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1",
+    "multer": "^1.4.5-lts.1",
+    "node-jose": "^2.2.0",
+    "reflect-metadata": "^0.2.2",
+    "utils-logger-av": "^3.2.3",
+    "utils-stuff": "^4.5.0"
+  },
+  "peerDependencies": {
+    "typeorm": "^0.3.21"
+  },
+  "repository": {
+    "url": ""
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup"
+  },
+  "keywords": []
+}

package/types/db.sptypes.ts

@@ -0,0 +1,18 @@
+import { Router } from "express"
+import { BaseEntity } from "typeorm"
+import { Methods } from "./generic.sptypes"
+import { Parameter, SchemaV3 } from "./swagger.sptypes"
+import { SecureTokenConfig } from "./token.sptypes"
+
+export 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[]
+}

package/types/generic.sptypes.ts

@@ -0,0 +1,35 @@
+export type ErrorsMapping = Record<string, { status?:number, responseMessage?:string }>;
+
+export type Methods = "GET" | "DELETE" | "PUT" | "POST"
+
+export type ExpressReturn = { isOk:boolean, result:any, status:number, contentType?:string }
+
+export type SwaggerMetadataInterface = {
+    required?:boolean, hide?:boolean,
+}
+
+export 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
+
+    // MINIO_ENDPOINT:string,
+    // MINIO_PORT?:number,
+    // MINIO_SSL?:boolean,
+    // MINIO_ACCESS_KEY?:string,
+    // MINIO_SECRET_KEY?:string,
+}
+
+
+export type SearchQuery = Record<string, string | number | boolean | undefined | null>
+export type ListOptions = { pageSize?:number, page?:number, orderBy?:string, order?:'ASC' | 'DESC'} & SearchQuery;

package/types/router.sptypes.ts

@@ -0,0 +1,39 @@
+import { Response as ExpressResponse, Request, RequestHandler } from "express";
+import { BaseEntity } from "typeorm";
+import { ExpressReturn, Methods } from "./generic.sptypes";
+import { Parameter, Reference, SchemaV3, Response as SwaggerResponse } from "./swagger.sptypes";
+import { SecureTokenConfig } from "./token.sptypes";
+
+export 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
+    }>
+}
+
+export type MethodPathHandling = {
+    swaggerBody?:{
+        schema:string,
+        required?:boolean,
+        description?:string,
+        comType?:'application/json' | 'multipart/form-data',
+    },
+    swaggerResponses?:Record<string, Reference | SwaggerResponse>,
+    swaggerParameters?:Array<Parameter>
+    middlewares?: RequestHandler[];
+    handler: (req:Request, res:ExpressResponse) => Promise<ExpressReturn>
+}

package/types/starter.sptypes.ts

@@ -0,0 +1,36 @@
+import { Express } from "express"
+import http from "http"
+import { EntitySchema, MixedList } from "typeorm"
+import { RouterWrapper } from "../src/RouterWrapper"
+import { Token } from "../src/Token"
+import { ProjectConfigs } from "./generic.sptypes"
+import { TokenApiOptions } from "./token.sptypes"
+
+export 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>
+    },
+}
+
+
+
+export type SocketWrapperConstructor = {
+    name:string,
+    beforeConnection?:() => Promise<void>
+    onDisconnect?:(...params:any[]) => Promise<void>
+    listeners?:Record<string, (...params:any[]) => Promise<void>>
+}

package/types/swagger.sptypes.ts

@@ -0,0 +1,375 @@
+export interface Info {
+    title: string;
+    version: string;
+    description?: string | undefined;
+    termsOfService?: string | undefined;
+    contact?: Contact | undefined;
+    license?: License | undefined;
+}
+
+export interface Contact {
+    name?: string | undefined;
+    email?: string | undefined;
+    url?: string | undefined;
+}
+
+export interface License {
+    name: string;
+    url?: string | undefined;
+}
+
+export interface ExternalDocs {
+    url: string;
+    description?: string | undefined;
+}
+
+export interface Tag {
+    name: string;
+    description?: string | undefined;
+    externalDocs?: ExternalDocs | undefined;
+}
+
+export interface Header extends BaseSchema {
+    type: ParameterType;
+}
+
+// ----------------------------- Parameter -----------------------------------
+
+export type ParameterType = "string" | "number" | "integer" | "boolean" | "array" | "object" | "file" | "date";
+
+export type BaseParameter = {
+    name: string;
+    in: "body" | "query" | "path" | "header" | "formData";
+    required?: boolean | undefined;
+    description?: string | undefined;
+};
+
+export type BodyParameter = BaseParameter & {
+    in: "body";
+    schema?: Schema | undefined;
+};
+
+export type GenericFormat = {
+    type?: ParameterType | undefined;
+    format?: string | undefined;
+};
+
+export type IntegerFormat = {
+    type: "integer";
+    format?: "int32" | "int64" | undefined;
+};
+
+export type NumberFormat = {
+    type: "number";
+    format?: "float" | "double" | undefined;
+};
+
+export type StringFormat = {
+    type: "string";
+    format?: "" | "byte" | "binary" | "date" | "date-time" | "password" | undefined;
+};
+
+export type SchemaFormatConstraints = GenericFormat | IntegerFormat | NumberFormat | StringFormat;
+export type BaseFormatContrainedParameter = BaseParameter & SchemaFormatConstraints;
+export type ParameterCollectionFormat = "csv" | "ssv" | "tsv" | "pipes" | "multi";
+
+export type QueryParameter =
+    & BaseFormatContrainedParameter
+    & BaseSchema
+    & {
+        in: "query";
+        allowEmptyValue?: boolean | undefined;
+        collectionFormat?: ParameterCollectionFormat | undefined;
+    };
+
+export type PathParameter =
+    & BaseFormatContrainedParameter
+    & BaseSchema
+    & {
+        in: "path";
+        required: boolean;
+    };
+
+export type HeaderParameter =
+    & BaseFormatContrainedParameter
+    & BaseSchema
+    & {
+        in: "header";
+    };
+
+export type FormDataParameter =
+    & BaseFormatContrainedParameter
+    & BaseSchema
+    & {
+        in: "formData";
+        type: ParameterType | "file";
+        allowEmptyValue?: boolean | undefined;
+        collectionFormat?: ParameterCollectionFormat | undefined;
+    };
+
+export type Parameter = { like?:boolean} & (BodyParameter | FormDataParameter | QueryParameter | PathParameter | HeaderParameter);
+
+// ------------------------------- Path --------------------------------------
+export 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;
+}
+
+
+
+export 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;
+}
+
+
+
+// ----------------------------- Components -----------------------------------
+export interface Components {
+    schemas?: { [schemaName: string]: SchemaV3 };
+    parameters?: { [parameterName: string]: Parameter };
+    securitySchemes?:Record<string, {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat?: 'JWT'
+    }>
+}
+
+
+
+// ----------------------------- Operation -----------------------------------
+export 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
+}
+
+export 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;
+}
+export 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;
+    }
+}
+
+
+
+
+export type RequestBodyOperation = {
+    description?: string;
+    required:boolean;
+    content: {
+        "application/json": {
+          schema: { $ref: string }
+        }
+      }
+    | {
+        "multipart/form-data": {
+          schema: { $ref: string }
+        }
+    };
+}
+export type DynamicSwaggerRequestBodyOperation = {
+    description?: string;
+    required:boolean;
+    content: {
+        "application/json": {
+            schema: { $ref: string }
+        }
+    }
+}
+// ----------------------------- Reference -----------------------------------
+export interface Reference {
+    $ref: string;
+}
+
+// ----------------------------- Response ------------------------------------
+export interface Response {
+    description: string;
+    schema?: Schema | undefined;
+    headers?: { [headerName: string]: Header } | undefined;
+    examples?: { [exampleName: string]: {} } | undefined;
+}
+
+// ------------------------------ Schema -------------------------------------
+export 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;
+};
+
+export 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;
+}
+
+export interface SchemaV3 extends BaseSchema {
+    type:"object"
+    properties?: { [propertyName: string]: Schema } | undefined;
+    required?:boolean;
+}
+
+export interface XML {
+    name?: string | undefined;
+    namespace?: string | undefined;
+    prefix?: string | undefined;
+    attribute?: boolean | undefined;
+    wrapped?: boolean | undefined;
+}
+
+// ----------------------------- Security ------------------------------------
+export interface BaseSecurity {
+    type: "basic" | "apiKey" | "oauth2";
+    description?: string | undefined;
+}
+
+export interface BasicAuthenticationSecurity extends BaseSecurity {
+    type: "basic";
+}
+
+export interface ApiKeySecurity extends BaseSecurity {
+    type: "apiKey";
+    name: string;
+    in: "query" | "header";
+}
+
+export interface BaseOAuthSecurity extends BaseSecurity {
+    type: "oauth2";
+    flow: "accessCode" | "application" | "implicit" | "password";
+    scopes?: OAuthScope | undefined;
+}
+
+export interface OAuth2ImplicitSecurity extends BaseOAuthSecurity {
+    type: "oauth2";
+    flow: "implicit";
+    authorizationUrl: string;
+}
+
+export interface OAuth2PasswordSecurity extends BaseOAuthSecurity {
+    type: "oauth2";
+    flow: "password";
+    tokenUrl: string;
+}
+
+export interface OAuth2ApplicationSecurity extends BaseOAuthSecurity {
+    type: "oauth2";
+    flow: "application";
+    tokenUrl: string;
+}
+
+export interface OAuth2AccessCodeSecurity extends BaseOAuthSecurity {
+    type: "oauth2";
+    flow: "accessCode";
+    tokenUrl: string;
+    authorizationUrl: string;
+}
+
+export interface OAuthScope {
+    [scopeName: string]: string;
+}
+
+export type Security =
+    | BasicAuthenticationSecurity
+    | OAuth2AccessCodeSecurity
+    | OAuth2ApplicationSecurity
+    | OAuth2ImplicitSecurity
+    | OAuth2PasswordSecurity
+    | ApiKeySecurity;
+
+// --------------------------------- Spec ------------------------------------
+export type Server = {
+    url:string;
+    description?:string;
+}
+
+
+export 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;
+
+}

package/types/token.sptypes.ts

@@ -0,0 +1,20 @@
+import { Request, Response } from "express"
+import { Methods } from "./generic.sptypes"
+
+export type DefaultTokenPayload = { id: string, [key:string]:any }
+
+export type SecureTokenConfig = boolean | { [columnName:string]:{
+    tokenKey:string,
+    methods:"*" | Array<Methods | "LIST">
+} }
+
+
+export type TokenConstructor =
+{
+    SECRET_KEY:string,
+    ExpTime:number,
+    EncAlgorithm:string // https://github.com/panva/jose/issues/210#jwe-alg
+    KeyLength:number
+}
+
+export type TokenApiOptions = { path?:string, callback:(req:Request, res:Response) => Promise<void> }