@cley_faye/boilerplate 3.21.3 → 4.0.1

package/lib/express/pipelinebuilder.js

@@ -1,288 +0,0 @@
-/**
- * @license
- * @preserve
- * MIT License
- *
- * Copyright (c) 2021 Gabriel Paul "Cley Faye" Risterucci
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- *
- */
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const express_1 = __importDefault(require("express"));
-const winston_js_1 = require("../winston.js");
-const logger_js_1 = require("./logger.js");
-const unprocessableentityerror_js_1 = require("./unprocessableentityerror.js");
-const getErrorData = (error) => {
-    const unprocessable = (0, unprocessableentityerror_js_1.get422Fields)(error);
-    if (unprocessable) {
-        return {
-            message: unprocessable.message,
-            extraFields: { fields: unprocessable.fields, errors: unprocessable.errors },
-        };
-    }
-    return error.expose ? { message: error.message } : {};
-};
-const defaultErrorHandler = (errorHandlerConfig) => (err, req, res, next) => {
-    const noErrorFilter = typeof errorHandlerConfig === "boolean"
-        ? false
-        : Boolean(errorHandlerConfig.noErrorFilter);
-    if (!res.headersSent) {
-        if (err.statusCode) {
-            const errorData = getErrorData(err);
-            const accepted = req.accepts([
-                "text",
-                "html",
-                "json",
-            ]);
-            if (accepted === "json") {
-                res.status(err.statusCode).send({
-                    statusCode: err.statusCode,
-                    message: errorData.message,
-                    ...errorData.extraFields,
-                });
-                return;
-            }
-            if (errorData.message) {
-                res.status(err.statusCode).send(errorData.message);
-            }
-            else {
-                res.sendStatus(err.statusCode);
-            }
-            return;
-        }
-        if (!noErrorFilter) {
-            // eslint-disable-next-line @typescript-eslint/no-magic-numbers
-            res.status(500).send("An unexpected error occured");
-            return;
-        }
-    }
-    next(err);
-};
-class PipelineBuilder {
-    constructor(debugLog) {
-        this._debugLog = debugLog;
-    }
-    static _addRouterToRouter(baseRouter, newRouter) {
-        baseRouter.use(newRouter);
-    }
-    static _addMiddlewareToRouter(router, middleware) {
-        router.use(middleware);
-    }
-    /** Register error handlers
-     *
-     * @param router
-     * @param errorHandlers
-     */
-    static _setErrorHandlers(router, errorHandlers) {
-        (errorHandlers ?? []).forEach(errorHandler => {
-            router.use(errorHandler);
-        });
-    }
-    /** Appropriate call to express.static() */
-    static _buildStaticHandler(staticDef) {
-        return typeof staticDef === "string"
-            ? express_1.default.static(staticDef)
-            : express_1.default.static(staticDef.root, staticDef.options);
-    }
-    /** See createPipeline() for more info */
-    createPipeline({ topLevels, routes, statics, postStatics, errorHandlers, options, }) {
-        const { middleware, log, defaultErrorHandler: useDefaultErrorHandler } = options ?? {};
-        this.internalLog("createPipeline()");
-        if (log) {
-            const errorConfig = typeof log.error === "boolean"
-                ? {}
-                : log.error ?? {};
-            (0, winston_js_1.setConfig)({
-                timestamp: log.timestamp ?? false,
-                collapseNodeModules: errorConfig.collapseNodeModules ?? true,
-                collapseStacktrace: errorConfig.collapseStacktrace ?? true,
-            });
-        }
-        const router = express_1.default.Router();
-        this.internalLog("setGenericMiddlewares()");
-        this._setGenericMiddlewares(router, middleware);
-        this.internalLog("add top level routes/middleware");
-        this._setRoutes(router, topLevels);
-        this.internalLog("add logger (route call)");
-        this._setRouteLogger(router, log);
-        this.internalLog("add routes");
-        this._setRoutes(router, routes);
-        this.internalLog("add statics");
-        this._setStatics(router, statics);
-        this.internalLog("add post statics routes");
-        this._setRoutes(router, postStatics);
-        this.internalLog("add logger (errors)");
-        this._setErrorLogger(router, log);
-        this.internalLog("add error handlers");
-        PipelineBuilder._setErrorHandlers(router, errorHandlers);
-        this.internalLog("add default error handlers");
-        this._setDefaultErrorHandler(router, useDefaultErrorHandler);
-        return router;
-    }
-    internalLog(...args) {
-        if (this._debugLog) {
-            this._debugLog(...args);
-        }
-    }
-    /** Add generic middlewares to a router
-     *
-     * @param router
-     * @param [middlewareOptions]
-     * @param [middlewareOptions.json]
-     * Process JSON body
-     */
-    _setGenericMiddlewares(router, middlewareOptions) {
-        const { urlencoded, text, raw, json, } = middlewareOptions ?? {};
-        if (urlencoded) {
-            this.internalLog("express.urlencoded()");
-            const options = urlencoded === true
-                ? { extended: true }
-                : urlencoded;
-            router.use(express_1.default.urlencoded(options));
-        }
-        if (text) {
-            this.internalLog("express.text()");
-            const options = text === true
-                ? undefined
-                : text;
-            router.use(express_1.default.text(options));
-        }
-        if (raw) {
-            this.internalLog("express.raw()");
-            const options = raw === true
-                ? undefined
-                : raw;
-            router.use(express_1.default.raw(options));
-        }
-        if (json) {
-            this.internalLog("express.json()");
-            const options = json === true
-                ? undefined
-                : json;
-            router.use(express_1.default.json(options));
-        }
-    }
-    _addRouteToRouter(router, route) {
-        const method = route.method ?? "get";
-        this.internalLog(`Adding route "${route.route}" [${method}]`);
-        // Simple route definition
-        if (Array.isArray(route.handler)) {
-            // Multiple handlers for same route
-            route.handler.forEach(handler => router[method](route.route, handler));
-        }
-        else {
-            // Simple handler
-            router[method](route.route, route.handler);
-        }
-    }
-    /** Register routes
-     *
-     * @param router
-     * @param routes
-     * See routes in createPipeline()
-     */
-    _setRoutes(router, routes) {
-        (routes ?? []).filter((e) => Boolean(e)).forEach(routeDef => {
-            const asRouter = routeDef;
-            const asRouteDef = routeDef;
-            const asRequestHandler = routeDef;
-            if (asRouter.name === "router") {
-                // Raw router
-                this.internalLog("Adding raw router");
-                PipelineBuilder._addRouterToRouter(router, asRouter);
-            }
-            else if (asRouteDef.route) {
-                // Specific routes
-                this._addRouteToRouter(router, asRouteDef);
-            }
-            else {
-                // Middleware
-                this.internalLog("Adding middleware");
-                PipelineBuilder._addMiddlewareToRouter(router, asRequestHandler);
-            }
-        });
-    }
-    /** Use a static definition */
-    _useComplexStatic(router, staticDef) {
-        const staticHandler = PipelineBuilder._buildStaticHandler(staticDef);
-        if (typeof staticDef === "string") {
-            this.internalLog("Adding statics");
-            router.use(staticHandler);
-        }
-        else if (staticDef.route) {
-            this.internalLog(`Adding statics for route "${staticDef.route}"`);
-            router.use(staticDef.route, staticHandler);
-        }
-        else {
-            this.internalLog("Adding statics");
-            router.use(staticHandler);
-        }
-    }
-    /** Define static resources for the express server
-     *
-     * @param router
-     * @param statics
-     * See createPipeline()
-     */
-    _setStatics(router, statics) {
-        (statics ?? []).forEach(staticDef => this._useComplexStatic(router, staticDef));
-    }
-    /** Register pre-route loggers
-     *
-     * @param router
-     * @param [logOptions]
-     * @param [logOptions.route]
-     * Log each route call
-     * @param [logOptions.logger]
-     */
-    _setRouteLogger(router, logOptions) {
-        const { route } = logOptions ?? {};
-        if (route) {
-            this.internalLog("Adding route logger");
-            (0, logger_js_1.registerRouteLogger)(router, logOptions);
-        }
-    }
-    /** Register post-route loggers
-     *
-     * @param {Router} router
-     * @param {object} [logOptions]
-     * @param {bool} [logOptions.error]
-     * Log each error
-     * @param {winstonLogger} [logOptions.logger]
-     */
-    _setErrorLogger(router, logOptions) {
-        const { error } = logOptions ?? {};
-        if (error) {
-            this.internalLog("Adding error logger");
-            (0, logger_js_1.registerErrorLogger)(router, logOptions);
-        }
-    }
-    _setDefaultErrorHandler(router, defaultErrorHandlerConfig) {
-        if (defaultErrorHandlerConfig) {
-            this.internalLog("Adding default error handler");
-            router.use(defaultErrorHandler(defaultErrorHandlerConfig));
-        }
-    }
-}
-exports.default = PipelineBuilder;

package/lib/express/unprocessableentityerror.d.ts

@@ -1,8 +0,0 @@
-import { ExtendedError } from "../winston.js";
-interface Error422Fields {
-    message: string;
-    fields: Array<string>;
-    errors: Array<unknown>;
-}
-export declare const get422Fields: (error: ExtendedError) => Error422Fields | undefined;
-export {};

package/lib/express/unprocessableentityerror.js

@@ -1,57 +0,0 @@
-/**
- * @license
- * @preserve
- * MIT License
- *
- * Copyright (c) 2021 Gabriel Paul "Cley Faye" Risterucci
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- *
- */
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.get422Fields = void 0;
-const UNPROCESSABLE_ENTITY = 422;
-const get422Fields = (error) => {
-    const { statusCode, cause, fields } = error;
-    if (statusCode !== UNPROCESSABLE_ENTITY
-        || !cause
-        || !Array.isArray(cause)
-        || !fields
-        || !Array.isArray(fields)) {
-        return;
-    }
-    let fieldsStr;
-    try {
-        fieldsStr = JSON.stringify(fields);
-    }
-    catch {
-        fieldsStr = "<error>";
-    }
-    let errorsStr;
-    try {
-        errorsStr = JSON.stringify(cause);
-    }
-    catch {
-        errorsStr = "<error>";
-    }
-    const message = `${error.message}: fields=${fieldsStr}, errors=${errorsStr}`;
-    return { message, fields, errors: cause };
-};
-exports.get422Fields = get422Fields;

package/lib/express.d.ts

@@ -1,156 +0,0 @@
-import { Server } from "net";
-import express from "express";
-import winston from "winston";
-import { PipelineSettings, LogFunction } from "./express/pipelinebuilder.js";
-/** Create the full processing pipeline for an Express server
- *
- * This function creates a pipeline this way:
- *  - Pass generic middlewares (see options)
- *  - Pass custom top-level middlewares
- *  - Pass logging middleware (see options)
- *  - Pass routes
- *  - Pass error logging middleware (see options)
- *  - Pass error handlers
- *  - Fallback to a default error handler (see below)
- *
- * The default error handler is a layer above the express default error
- * handler.
- * If it is reached, it will check if the error object looks like an
- * http-errors exception, and if that's the case, send the error code and the
- * message (if applicable).
- * If the request accepts json, a json object with the error is returned.
- * Otherwise text is returned.
- *
- * For convenience, providing timestamp and collapseNodeModules here will automatically
- * update the basic consoleLogger configuration.
- *
- * @param settings
- *
- * @param [settings.topLevels]
- * List top-level middlewares. See routes.
- *
- * @param [settings.routes]
- * List routes and routers.
- * For each router and function, a simple "use()" call is used.
- * If an object is provided, it must have two properties:
- *  - route: the actual route to listen to
- *  - handler: either a function, a router, or an array of functions that will
- *  be called in sequence on this request.
- *  - method: the method ("get", "post", "put", "options"). If missing,
- *    default to "get".
- *
- * @param [settings.statics]
- * List of directory to serve as static content.
- * Can be either a string (the path) or an object with the following
- * properties:
- *  - root: the root in the filesystem for this static provider
- *  - options: (optional) the options to pass to static()
- *  - route: (optional) the route where the static resources will be served
- *
- * @param [settings.postStatics]
- * Register routes handled after statics. See routes.
- *
- * @param [settings.errorHandlers]
- * Process errors. Must be function with four parameters.
- *
- * @param [settings.options]
- * @param [settings.options.log]
- * @param [settings.options.log.route]
- * Log each route. Can be an object with all properties expected from
- * winston-express.logger()
- *
- * @param [settings.options.log.error]
- * Log error content. Can be either a boolean or an object with the
- * "collapseNodeModules" property. The error log will then display a truncated
- * stacktrace where lines containing node_modules are removed.
- *
- * @param [settings.options.log.timestamp]
- * Log timestamps on each lines
- *
- * @param [settings.options.log.logger]
- * An existing winston logger to use. Only the transport will be used.
- *
- * @param [settings.options.middleware]
- * @param [settings.options.middleware.urlencoded]
- * Parse URL encoded requests. Can be true or settings for urlencoded().
- * Default to handling application/x-www-form-urlencoded.
- *
- * @param [settings.options.middleware.text]
- * Parse raw text body requests. Can be true or settings for text()
- * Default to handling text/plain
- *
- * @param [settings.options.middleware.raw]
- * Parse raw body requests into an arraybuffer. Can be true or settings for
- * raw()
- * Default to handling application/octet-stream
- *
- * @param [settings.options.middleware.json]
- * Parse JSON body requests. Can be true or settings for json()
- * Default to handling application/json
- *
- * @param [settings.options.defaultErrorHandler]
- * Setup the default error handler. Defaults to false.
- *
- * @param [debugLog]
- * Function to log debug informations
- *
- * @return
- * The returned object can be used
- */
-export declare const createPipeline: (settings: PipelineSettings, debugLog?: LogFunction) => express.Router;
-/**
- * Configure the views rendering engine for an ExpressJS App
- */
-export declare const setViewEngine: (app: express.Express, viewEngine: string, viewsDirectory: string, extraLocals?: Record<string, string | number>) => void;
-/**
- * Function to call when the server stops.
- *
- * This is usually triggered by a SIGTERM.
- *
- * If the function returns "true", it prevent the process from stopping.
- * Otherwise `process.exit()` is called.
- */
-type ShutdownFunction = () => Promise<boolean | undefined> | boolean | undefined;
-export interface StartDefinition {
-    app: express.Application;
-    /** @deprecated use listenInterface instead */
-    allowNonLocal?: boolean;
-    /**
-     * Which interface to listen on.
-     *
-     * Defaults to `false` which means listen only on localhost.
-     * Set to `true` to listen on all interfaces
-     * Set to an IP to bind on a specific interface.
-     */
-    listenInterface?: boolean | string;
-    port?: number;
-    shutdownFunction?: ShutdownFunction;
-    logger?: winston.Logger;
-    noReady?: boolean;
-}
-export interface StartResult {
-    port: number;
-    server: Server;
-}
-/** Start the server and register signal for automatic closing.
- *
- * @param app
- * @param [allowNonLocal]
- * Allow requests from outside of localhost
- *
- * @param [port]
- * Port to listen from. Default to a random available port.
- *
- * @param [shutdownFunction]
- * Function to call after the server is shutdown (all connection closed)
- *
- * @param [logger]
- *
- * @return
- * @property port
- * The port the server is listening on
- *
- * @property server
- */
-export declare const appStart: ({ app, allowNonLocal, listenInterface, port, shutdownFunction, logger, noReady, }: StartDefinition) => Promise<StartResult>;
-export {};