@cley_faye/boilerplate 3.6.0 → 3.7.2

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,7 +29,7 @@ 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");
@@ -56,11 +56,25 @@ const customRouteFormat = (outputTimestamp) => winston_1.default.format.printf((
     const finalMessage = `${info.message} ${metaString === "{}" ? "" : metaString}`;
     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 };
@@ -78,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) => {

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

@@ -0,0 +1,9 @@
+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 interface ExtraLoggingOptions {
+    /** Do not expose the "hidden" body props */
+    noHiddenBodyProps?: boolean;
+}
+export declare const bodyLogger: (bodyProps?: string[] | undefined, extraLoggingData?: ExtraLoggingData | undefined, options?: ExtraLoggingOptions) => (req: Request, res: Response, next: NextFunction) => void;

package/lib/express/middlewares/bodylogger.js

@@ -0,0 +1,90 @@
+/**
+ * @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 getPropType = (value) => {
+    if (typeof value === "string")
+        return `string(${value.length})`;
+    if (typeof value === "number")
+        return "number";
+    if (typeof value === "boolean")
+        return "boolean";
+    if (typeof value === "undefined")
+        return "undefined";
+    if (Array.isArray(value))
+        return `Array(${value.length})`;
+    return "object";
+};
+const getHiddenBodyProps = (req, ignoreKeys = []) => {
+    if (typeof req.body !== "object")
+        return;
+    const body = req.body;
+    const res = {};
+    for (const key of Object.keys(body)) {
+        if (ignoreKeys.includes(key))
+            continue;
+        res[key] = getPropType(body[key]);
+    }
+    if (Object.keys(res).length === 0)
+        return;
+    return res;
+};
+const bodyLogger = (bodyProps, extraLoggingData, options = {}) => (req, res, next) => {
+    const asyncFunc = async () => {
+        const allExtraData = {};
+        if (!options.noHiddenBodyProps) {
+            const redactedBody = getHiddenBodyProps(req, bodyProps);
+            if (redactedBody)
+                Object.assign(allExtraData, { redactedBody });
+        }
+        const extraLogData = typeof extraLoggingData === "function"
+            ? await extraLoggingData(req)
+            : extraLoggingData;
+        Object.assign(allExtraData, extraLogData);
+        setLogInfoInReq(req, bodyProps, allExtraData);
+    };
+    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,13 @@ 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 */

package/lib/grunt/reactapp.js

@@ -49,7 +49,7 @@ var HandlerType;
     HandlerType["COPY"] = "copy";
 })(HandlerType = exports.HandlerType || (exports.HandlerType = {}));
 const gatherTasks = (handlers, gruntConfig, targetName, options) => Object.keys(handlers)
-    .reduce((acc, cur) => acc.concat((options?.[cur] && (options[cur] ?? {}).disabled)
+    .reduce((acc, cur) => acc.concat((options?.[cur] && options[cur]?.disabled)
     ? []
     : handlers[cur](gruntConfig, targetName, (options?.[cur]) ?? {})), []);
 const mergeResults = (tasksResults) => tasksResults.reduce((acc, cur) => {
@@ -184,7 +184,8 @@ const reactApp = (gruntConfig, targetName = "reactApp", options) => {
     };
     const tasksResults = gatherTasks(handlers, gruntConfig, targetName, options);
     const mergedResults = mergeResults(tasksResults);
-    createCopyTask(gruntConfig, targetName, mergedResults, options);
+    if (!options?.copy?.disabled)
+        createCopyTask(gruntConfig, targetName, mergedResults, options);
     // Add grunt-contrib-watch task
     createWatchTasks(gruntConfig, mergedResults, options?.watch);
     return mergedResults.requiredTasks;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cley_faye/boilerplate",
-  "version": "3.6.0",
+  "version": "3.7.2",
   "description": "Boilerplate code generator for generic projects",
   "repository": {
     "type": "git",