@cley_faye/boilerplate 3.4.1 → 3.7.0

package/README.md

@@ -318,6 +318,7 @@ It supports the following properties:
 - route: log all route called. Can be either a boolean or an express-winston configuration.
   In the later case, all properties are accepted except the winston instance, which is set
   separately.
+  More details in the "custom logging" section below.
 - error: log all errors. Accept a boolean, or an object with the "collapseNodeModules" boolean
   property.
 - logger: an instance of a winston logger.
@@ -366,6 +367,40 @@ root of the service, or an object with the following properties:
 - options: The options to pass to express static handler
 - route: The route under which the static files will be served
 
+### Custom logging
+The default configuration (by setting `options.log.route: true`) allows some level of customization
+of the actual logged data.
+If a custom object is passed instead of `true`, the following will not automatically apply.
+
+By default, all body content is logged.
+To finely tune what body elements are logged on each route the `bodyLogger()` middleware can be
+used.
+It takes two parameters, the first one is an array of properties that *should* be logged, the second
+one can be a custom object or a function returning a custom object with extra properties to log.
+
+For example, for a login route, you might want to hide the provided password but still get some info
+(note: this is an example, in practice you probably shouldn't care about this)
+
+```JavaScript
+router.post(
+  "/login",
+  bodyLogger(
+    ["login"],
+    req => ({
+      passwordLength: req.body.password.length,
+    }),
+  ),
+  processLogin,
+);
+```
+
+In addition to excluding properties from the body of a request and adding custom properties, it can
+be useful to always identify a request coming from a logged-in user.
+
+You can provide a `userFromReq` property to the `options.log` configuration.
+It should be a function that receive `req` as its argument and returns a string identifying the
+logged-in user.
+
 ### Configuring global aspects of an Express App
 
 #### Configuring the template engine

package/lib/express/logger.d.ts

@@ -1,11 +1,22 @@
-import expressWinston from "express-winston";
-import { Router } from "express";
-import { LogOptions } from "./pipelinebuilder.js";
+import expressWinston, { BaseLoggerOptions } from "express-winston";
+import { Request, Router } from "express";
+import { LogOptions, UserFromReqFunc } from "./pipelinebuilder.js";
 export declare type LoggerOptions = expressWinston.LoggerOptions | boolean;
 interface ErrorLoggerConfiguration {
     collapseNodeModules?: boolean;
 }
 export declare type ErrorLoggerOptions = ErrorLoggerConfiguration | boolean;
+export interface LoggingData {
+    extraLoggingData?: Record<string, unknown>;
+}
+export interface RequestWithLoggingData extends Request {
+    _cleyfayeLogging?: LoggingData;
+    _routeWhitelists?: {
+        body?: Array<string>;
+    };
+}
+/** Return the default value for route logger is it is set as `true` */
+export declare const defaultRouteLoggerConfig: (userFromReq?: UserFromReqFunc | undefined) => BaseLoggerOptions;
 export declare const registerRouteLogger: (app: Router, logOptions?: LogOptions | undefined) => void;
 export declare const registerErrorLogger: (app: Router, logOptions?: LogOptions | undefined) => void;
 export {};

package/lib/express/logger.js

@@ -29,42 +29,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerErrorLogger = exports.registerRouteLogger = void 0;
+exports.registerErrorLogger = exports.registerRouteLogger = exports.defaultRouteLoggerConfig = void 0;
 const winston_1 = __importDefault(require("winston"));
 const express_winston_1 = __importDefault(require("express-winston"));
 const winston_js_1 = require("../winston.js");
-// High value because of colorize()
-const LOG_LEVEL_PADDING_SIZE = 19;
-/**
- * Collapse all lines containing /node_modules/ into an ellipsis
- */
-const filterNodeModules = function* (message) {
-    let inNodeModules = false;
-    const lines = message.split("\n");
-    for (const line of lines) {
-        if (/\/node_modules\//u.exec(line)) {
-            if (!inNodeModules) {
-                inNodeModules = true;
-                yield "[...]";
-            }
-        }
-        else {
-            inNodeModules = false;
-            yield line;
-        }
-    }
-};
-/**
- * Prefix all lines with the level and the timestamp if needed
- */
-const prefixOutput = (level, message, timestamp) => {
-    const timestampPrefix = timestamp
-        ? `${new Date().toISOString()} `
-        : "";
-    const levelPrefix = `${level.toString().padStart(LOG_LEVEL_PADDING_SIZE)}: `;
-    return message.split("\n").map(line => `${timestampPrefix}${levelPrefix}${line}`)
-        .join("\n");
-};
 const customRouteFormat = (outputTimestamp) => winston_1.default.format.printf((info) => {
     const meta = info.meta;
     // Clean the meta object from stuff displayed in the regular message
@@ -86,13 +54,27 @@ const customRouteFormat = (outputTimestamp) => winston_1.default.format.printf((
     }
     const metaString = JSON.stringify(info.meta);
     const finalMessage = `${info.message} ${metaString === "{}" ? "" : metaString}`;
-    return prefixOutput(info.level, finalMessage, outputTimestamp);
+    return (0, winston_js_1.prefixOutput)(info.level, finalMessage, outputTimestamp);
 });
+/** Return the default value for route logger is it is set as `true` */
+const defaultRouteLoggerConfig = (userFromReq) => ({
+    meta: true,
+    requestWhitelist: ["body"],
+    responseWhitelist: [],
+    dynamicMeta: (req) => {
+        const castReq = req;
+        const data = { ...castReq._cleyfayeLogging?.extraLoggingData };
+        if (userFromReq)
+            data.user = userFromReq(req) ?? null;
+        return data;
+    },
+});
+exports.defaultRouteLoggerConfig = defaultRouteLoggerConfig;
 const registerRouteLogger = (app, logOptions) => {
-    const { route, logger, timestamp } = logOptions ?? {};
+    const { route, timestamp, userFromReq } = logOptions ?? {};
     let extraConfig;
     if (typeof route === "boolean") {
-        extraConfig = {};
+        extraConfig = (0, exports.defaultRouteLoggerConfig)(userFromReq);
     }
     else {
         extraConfig = { ...route };
@@ -110,20 +92,11 @@ const registerRouteLogger = (app, logOptions) => {
         colorize: true,
         msg: "{{req.method}} {{req.url}} {{res.statusCode}} {{res.responseTime}}ms",
     };
-    if (logger) {
-        app.use(express_winston_1.default.logger({
-            transports: winston_js_1.transports,
-            ...baseConfig,
-            ...extraConfig,
-        }));
-    }
-    else {
-        app.use(express_winston_1.default.logger({
-            transports: winston_js_1.transports,
-            ...baseConfig,
-            ...extraConfig,
-        }));
-    }
+    app.use(express_winston_1.default.logger({
+        transports: winston_js_1.transports,
+        ...baseConfig,
+        ...extraConfig,
+    }));
 };
 exports.registerRouteLogger = registerRouteLogger;
 const customErrorFormat = (outputTimestamp, config) => {
@@ -131,9 +104,9 @@ const customErrorFormat = (outputTimestamp, config) => {
     return winston_1.default.format.printf((info) => {
         const meta = info.meta;
         const finalMessage = collapseNodeModules
-            ? [...filterNodeModules(meta.message)].join("\n")
+            ? [...(0, winston_js_1.filterNodeModules)(meta.message)].join("\n")
             : meta.message;
-        return prefixOutput(info.level, finalMessage, outputTimestamp);
+        return (0, winston_js_1.prefixOutput)(info.level, finalMessage, outputTimestamp);
     });
 };
 const registerErrorLogger = (app, logOptions) => {

package/lib/express/middlewares/bodylogger.d.ts

@@ -0,0 +1,5 @@
+import { NextFunction, Request, Response } from "express";
+export declare type ExtraLoggingDataType = Record<string, unknown> | undefined;
+export declare type ExtraLoggingDataFunc = (req: Request) => Promise<ExtraLoggingDataType> | ExtraLoggingDataType;
+export declare type ExtraLoggingData = ExtraLoggingDataFunc | Record<string, unknown>;
+export declare const bodyLogger: (bodyProps?: string[] | undefined, extraLoggingData?: ExtraLoggingData | undefined) => (req: Request, res: Response, next: NextFunction) => void;

package/lib/express/middlewares/bodylogger.js

@@ -0,0 +1,56 @@
+/**
+ * @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.bodyLogger = void 0;
+const setLogInfoInReq = (req, body, extraData) => {
+    const castReq = req;
+    if (body) {
+        if (!castReq._routeWhitelists)
+            castReq._routeWhitelists = {};
+        castReq._routeWhitelists.body = body;
+    }
+    if (extraData) {
+        castReq._cleyfayeLogging = { extraLoggingData: extraData };
+    }
+};
+const bodyLogger = (bodyProps, extraLoggingData) => (req, res, next) => {
+    const asyncFunc = async () => {
+        const extraLogData = typeof extraLoggingData === "function"
+            ? await extraLoggingData(req)
+            : extraLoggingData;
+        setLogInfoInReq(req, bodyProps, extraLogData);
+    };
+    asyncFunc()
+        .then(() => {
+        next();
+    })
+        .catch((error) => {
+        next(error);
+    });
+};
+exports.bodyLogger = bodyLogger;

package/lib/express/pipelinebuilder.d.ts

@@ -1,4 +1,4 @@
-import express from "express";
+import express, { Request } from "express";
 import { OptionsJson, OptionsUrlencoded, OptionsText, Options as OptionsRaw } from "body-parser";
 import winston from "winston";
 import { LoggerOptions, ErrorLoggerOptions } from "./logger.js";
@@ -24,11 +24,17 @@ export interface ComplexStaticDefinition {
     route?: string;
 }
 export declare type StaticDefinition = ComplexStaticDefinition | string;
+export declare type UserFromReqFunc = (req: Request) => string | undefined;
 export interface LogOptions {
     route?: LoggerOptions;
     error?: ErrorLoggerOptions;
     logger?: winston.Logger;
     timestamp?: boolean;
+    userFromReq?: UserFromReqFunc;
+}
+export interface DefaultErrorHandlerConfig {
+    /** Set to true to allow server errors without a code to be sent as-is in the response */
+    noErrorFilter?: boolean;
 }
 export interface PipelineSettings {
     topLevels?: Array<RouterWithNullDef>;
@@ -39,7 +45,7 @@ export interface PipelineSettings {
     options?: {
         log?: LogOptions;
         middleware?: MiddlewareOptions;
-        defaultErrorHandler?: boolean;
+        defaultErrorHandler?: boolean | DefaultErrorHandlerConfig;
     };
 }
 export default class PipelineBuilder {

package/lib/express/pipelinebuilder.js

@@ -30,31 +30,42 @@ var __importDefault = (this && this.__importDefault) || function (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 defaultErrorHandler = (err, req, res, next) => {
-    if (!res.headersSent && err.statusCode) {
-        const message = err.expose
-            ? err.message
-            : undefined;
-        const accepted = req.accepts([
-            "text",
-            "html",
-            "json",
-        ]);
-        if (accepted === "json") {
-            res.status(err.statusCode).send({
-                statusCode: err.statusCode,
-                message,
-            });
+const defaultErrorHandler = (errorHandlerConfig) => (err, req, res, next) => {
+    const noErrorFilter = typeof errorHandlerConfig === "boolean"
+        ? false
+        : Boolean(errorHandlerConfig.noErrorFilter);
+    if (!res.headersSent) {
+        if (err.statusCode) {
+            const message = err.expose
+                ? err.message
+                : undefined;
+            const accepted = req.accepts([
+                "text",
+                "html",
+                "json",
+            ]);
+            if (accepted === "json") {
+                res.status(err.statusCode).send({
+                    statusCode: err.statusCode,
+                    message,
+                });
+                return;
+            }
+            if (message) {
+                res.status(err.statusCode).send(message);
+            }
+            else {
+                res.sendStatus(err.statusCode);
+            }
             return;
         }
-        if (message) {
-            res.status(err.statusCode).send(message);
-        }
-        else {
-            res.sendStatus(err.statusCode);
+        if (!noErrorFilter) {
+            // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+            res.status(500).send("An unexpected error occured");
+            return;
         }
-        return;
     }
     next(err);
 };
@@ -88,6 +99,15 @@ class PipelineBuilder {
     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,
+            });
+        }
         const router = express_1.default.Router();
         this.internalLog("setGenericMiddlewares()");
         this._setGenericMiddlewares(router, middleware);
@@ -247,10 +267,10 @@ class PipelineBuilder {
             (0, logger_js_1.registerErrorLogger)(router, logOptions);
         }
     }
-    _setDefaultErrorHandler(router, enableDefaultErrorHandler) {
-        if (enableDefaultErrorHandler) {
+    _setDefaultErrorHandler(router, defaultErrorHandlerConfig) {
+        if (defaultErrorHandlerConfig) {
             this.internalLog("Adding default error handler");
-            router.use(defaultErrorHandler);
+            router.use(defaultErrorHandler(defaultErrorHandlerConfig));
         }
     }
 }

package/lib/express.d.ts

@@ -23,6 +23,9 @@ import { PipelineSettings, LogFunction } from "./express/pipelinebuilder.js";
  * 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]

package/lib/express.js

@@ -51,6 +51,9 @@ const pipelinebuilder_js_1 = __importDefault(require("./express/pipelinebuilder.
  * 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]

package/lib/winston.d.ts

@@ -1,3 +1,17 @@
 import winston from "winston";
+/**
+ * Collapse all lines containing /node_modules/ into an ellipsis
+ */
+export declare const filterNodeModules: (message: string) => Generator<string>;
+/**
+ * Prefix all lines with the level and the timestamp if needed
+ */
+export declare const prefixOutput: (level: string, message: string, timestamp: boolean | undefined) => string;
+export interface LogConfig {
+    timestamp: boolean;
+    collapseNodeModules: boolean;
+}
+/** Edit the configuration applied to consoleLogger */
+export declare const setConfig: (config: LogConfig) => void;
 export declare const transports: winston.transports.ConsoleTransportInstance[];
 export declare const consoleLogger: winston.Logger;

package/lib/winston.js

@@ -29,11 +29,61 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.consoleLogger = exports.transports = void 0;
+exports.consoleLogger = exports.transports = exports.setConfig = exports.prefixOutput = exports.filterNodeModules = void 0;
 const winston_1 = __importDefault(require("winston"));
+// High value because of colorize()
+const LOG_LEVEL_PADDING_SIZE = 19;
+/**
+ * Collapse all lines containing /node_modules/ into an ellipsis
+ */
+const filterNodeModules = function* (message) {
+    let inNodeModules = false;
+    const lines = message.split("\n");
+    for (const line of lines) {
+        if (/\/node_modules\//u.exec(line)) {
+            if (!inNodeModules) {
+                inNodeModules = true;
+                yield "[...]";
+            }
+        }
+        else {
+            inNodeModules = false;
+            yield line;
+        }
+    }
+};
+exports.filterNodeModules = filterNodeModules;
+/**
+ * Prefix all lines with the level and the timestamp if needed
+ */
+const prefixOutput = (level, message, timestamp) => {
+    const timestampPrefix = timestamp
+        ? `${new Date().toISOString()} `
+        : "";
+    const levelPrefix = `${level.toString().padStart(LOG_LEVEL_PADDING_SIZE)}: `;
+    return message.split("\n").map(line => `${timestampPrefix}${levelPrefix}${line}`)
+        .join("\n");
+};
+exports.prefixOutput = prefixOutput;
+const logConfig = {
+    timestamp: true,
+    collapseNodeModules: true,
+};
+const customFormat = winston_1.default.format.printf((info) => {
+    const message = ("stack" in info) ? info.stack : info.message;
+    const filteredMessage = logConfig.collapseNodeModules
+        ? [...(0, exports.filterNodeModules)(message)].join("\n")
+        : message;
+    return (0, exports.prefixOutput)(info.level, filteredMessage, logConfig.timestamp);
+});
+/** Edit the configuration applied to consoleLogger */
+const setConfig = (config) => {
+    Object.assign(logConfig, config);
+};
+exports.setConfig = setConfig;
 exports.transports = [new winston_1.default.transports.Console()];
 exports.consoleLogger = winston_1.default.createLogger({
     level: "info",
-    format: winston_1.default.format.combine(winston_1.default.format.colorize(), winston_1.default.format.simple()),
+    format: winston_1.default.format.combine(winston_1.default.format.colorize(), customFormat),
     transports: exports.transports,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cley_faye/boilerplate",
-  "version": "3.4.1",
+  "version": "3.7.0",
   "description": "Boilerplate code generator for generic projects",
   "repository": {
     "type": "git",
@@ -17,13 +17,13 @@
   },
   "homepage": "https://github.com/CleyFaye/boilerplate#readme",
   "devDependencies": {
-    "@keeex/eslint-config": "^1.7.0",
+    "@keeex/eslint-config": "^1.7.1",
     "@types/express": "^4.17.11",
     "@types/grunt": "^0.4.25",
     "@types/http-errors": "^1.8.0",
     "@types/node": "^16.0.0",
-    "@typescript-eslint/eslint-plugin": "^5.3.1",
-    "@typescript-eslint/parser": "^5.3.1",
+    "@typescript-eslint/eslint-plugin": "^5.12.0",
+    "@typescript-eslint/parser": "^5.12.0",
     "eslint": "^8.7.0",
     "eslint-plugin-import": "^2.25.4",
     "eslint-plugin-promise": "^6.0.0",