@cley_faye/boilerplate 3.21.3 → 4.0.2

package/README.md

@@ -1,9 +1,12 @@
-Some Express/Webapp boilerplate
+Some webapp boilerplate
 ===============================
-This repository is a small set of functions to help setting up simple webapps/Express services.
 
-It's made of two parts: one that help setting up Express quickly, and one that provide Grunt tasks
-to transpile a webapp so it can work in most browsers.
+Note: this is legacy stuff. Low maintenance (well, lower than before). We moved toward better
+options, that directly embeds most of the work with tsc, babel and webpack.
+
+This repository is a small set of functions to help setting up simple webapps.
+
+It provides Grunt tasks to transpile a webapp so it can work in most browsers.
 
 These tools allows some level of configuration, but most default options expects a specific
 directory layout for your project.
@@ -13,8 +16,6 @@ This is not a "starter project" but an actual dependency to keep in your project
 Install it using
 
 ```shell
-npm install @cley_faye/boilerplate
-// alternatively, if you don't run an express server and only build a webapp offline
 npm install -D @cley_faye/boilerplate
 ```
 
@@ -45,12 +46,6 @@ For webapp building:
 - grunt
 - ts-loader (for supporting TypeScript import in webpack/babel)
 
-For express:
-
-- express
-- winston
-- express-winston
-
 Peer dependencies are used to limit major version mismatch.
 
 Webapp side
@@ -280,195 +275,6 @@ All names provided in the config are converted to kebab-case for the command lin
 If `--help` is passed to the command line, an additional help message will be displayed on the
 output, using the provided descriptions if available.
 
-Express application definition
-------------------------------
-The express helper actually provide a single place to configure most of the express pipeline with
-some generic options and generic-ish way to provide routes.
-
-It is limited to a very simple set of features but avoid having to retype them all the time.
-Some standard security features are not defined here; my personal usecases usually involves having a
-secure webserver in front that takes care of most headers.
-
-Default settings operate using winston for logging.
-
-To define your express app, you can call `createPipeline()`.
-
-Quick sample:
-
-```JavaScript
-import express from "express";
-import {createPipeline} from "@cley_faye/boilerplate/lib/express.js";
-
-const app = express();
-app.use(createPipeline({
-  topLevels: [],
-  routes: [],
-  statics: [],
-  postStatics: [],
-  errorHandlers: [],
-  options: {
-    log: {},
-    middleware: {},
-    defaultErrorHandler: true,
-  }
-}));
-
-export default app;
-```
-
-This will not serve anything by default, but display most top-level options that can be provided at
-this point.
-
-### Options
-The log options can be used to control the express server logging behavior.
-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.
-- timestamp: set to true to prepend a timestamp to each log line
-- ignoredRoutes: array of path to not log
-
-Note that if `route` is a full object, some of the other proprties might be ignored.
-
-The middleware options allow enabling/disabling common middlewares.
-Currently only support a few builtin middlewares from express:
-
-- `json`, to enable auto-parsing of json body.
-- `urlencoded`, to parse parameters from the query string
-- `text`, to populate body with the raw request as a string
-- `raw`, to populate body with the raw request content
-
-Each of these options accept either `true` (to use their default behavior) or an object with their
-configuration as specified in the ExpressJS manual.
-
-The `defaultErrorHandler` property enable a final error handler.
-It's behavior is to intercept errors/exceptions and return them as a reply.
-If the error is a proper error object (from `http-errors`), it will return the message (if expose is
-true) and the statusCode.
-If the request declares that it can accept json, the error is sent back as a json object with
-`statusCode` and `message`.
-Otherwise the message is sent as a plaintext reply.
-
-### Defining routes
-`topLevels`, `routes` and `postStatics` are arrays of handlers.
-Each handler can be either another Router (for route composition), a simple handler without route
-specification (a simple `req, res, next` function), or a complete route definition in the form of an
-object with the following properties:
-
-- route: the route to handle
-- handler: the route handler (or an array, or a Router)
-- method: the method this route should handle. Defaults to "get".
-
-### Defining error handlers
-The `errorHandlers` property accept an array of functions that follow the express "error handler"
-kind of functions (four parameters: `err`, `req`, `res` and `next`).
-If provided, and if the default error handler is set, they will be called before it.
-
-### Providing statics
-To serve static files, the `statics` property can be used.
-It's an array of either directly the path to a directory, in which case it will be served at the
-root of the service, or an object with the following properties:
-
-- root: The directory where the static files are
-- 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 `authFromReq` 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.
-(this only work with the default log handler; if you define anything in `route` you can set this in
-`dynamicMeta()`)
-
-### Configuring global aspects of an Express App
-
-#### Configuring the template engine
-
-```JavaScript
-import {setViewEngine} from "@cley_faye/boilerplate/lib/express.js";
-
-const app = express();
-setViewEngine(app, "pug", "webres/views", {});
-```
-
-The last parameter is optional; if provided it will define values available to the template engine.
-
-Running Express application
----------------------------
-Once the express application is defined, it need to be started to serve files and resources.
-A helper is provided to do so, using the `appStart()` function.
-
-```JavaScript
-import {consoleLogger} from "@cley_faye/boilerplate/lib/winston.js";
-import app from "./app.js";
-import {appStart} from "@cley_faye/boilerplate/lib/express.js";
-
-appStart({
-  app,
-  listenInterface: false,
-  port: 3000,
-  shutdownFunction: () => {;},
-  logger: consoleLogger,
-  noReady: false,
-}).then(({port, server}) => {;});
-```
-
-The settings are:
-
-- listenInterface: listen only to localhost or not. Can also be used to specify the address of an
-  interface to bind to.
-- port: port to listen to. Can be 0 to use a random available port
-- shutdownFunction: a function to call after the server stop listening
-- logger: a winston logger to log that the server started listening
-- noReady: if true, does not call `process.send("ready");` (used by PM2)
-
-The shutdown function can return a promise, and if it returns/resolve with `true` the process is
-left alive.
-Otherwise `process.exit()` is called after `shutdownFunction()` resolves/returns.
-
-The `appStart()` function returns a promise that resolve with the actual port used for listening
-when the server is started.
-
-The server is automatically registered using the `autoclose` part to stop when a SIGINT signal is
-received.
-It is also possible to trigger a stop by calling the `closeServer()` function on
-`@cley_faye/boilerplate/lib/express/autoclose.js`.
-This feature only supports one server at a time.
-
 Extra middleware
 ----------------
 
@@ -497,16 +303,6 @@ A convenience command is available as "serve_spa" to be called from the command
 It is possible to pass it some parameters; run it with `--help` for more informations.
 To use this tool, `minimist` must be installed in addition to express dependencies.
 
-Console logging
----------------
-For convenience, a winston logger using console as output is provided:
-
-```JavaScript
-import {consoleLogger} from "@cley_faye/boilerplate/lib/winston.js";
-
-consoleLogger.info("Log line");
-```
-
 Using TypeScript
 -----------------
 Typical use of TypeScript implies converting `.ts` file to `.js`.
@@ -522,11 +318,3 @@ If a `tsconfig-tsloader.json` file exists at the root of the project, it will be
 
 For Express app, there is no particular things to take care, except that if you use a facility like
 `nodemon` you have to watch the TypeScript output instead of the actual source files.
-
-REPL
-----
-This library provides a function to start a simple REPL instance (using node's built-in repl module)
-to provide access to JavaScript features.
-
-Basic usage includes predefined behavior for providing a database object and a list of services.
-The export is in `lib/repl.js`.

package/bin/serve_spa.js

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
-// eslint-disable-next-line i/no-unresolved
 import("../lib/bin/serve_spa.js");

package/lib/bin/serve_spa.js

@@ -41,33 +41,42 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable no-console */
+const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
-const node_fs_1 = require("node:fs");
 const express_1 = __importDefault(require("express"));
 const minimist_1 = __importDefault(require("minimist"));
 const singlepageapp_js_1 = require("../express/middlewares/singlepageapp.js");
-const express_js_1 = require("../express.js");
-const winston_js_1 = require("../winston.js");
 const ARGV_START_OFFSET = 2;
-const { port, root, index, help, staticlist, static: staticDirs } = (0, minimist_1.default)(process.argv.slice(ARGV_START_OFFSET));
+const { port, root, index, help, staticlist, static: staticDirs, } = (0, minimist_1.default)(process.argv.slice(ARGV_START_OFFSET));
 const DEFAULT_PORT = 3000;
 const DEFAULT_PATH = path.join("dist", "webapp");
 const DEFAULT_INDEX = "index.html";
 const DEFAULT_STATICFILE = "spa_static.config";
 const DEFAULT_STATIC = ["js", "css", "img"];
 if (help) {
-    winston_js_1.consoleLogger.info(`
+    console.log(`
 Usage:
 
 serve_spa \\
@@ -84,7 +93,6 @@ It defaults to ${JSON.stringify(DEFAULT_STATIC)}.
 The staticfile value is a text file with one static directory line.
 If present, they are merged with the CLI arguments.
 `.trim());
-    // eslint-disable-next-line no-process-exit
     process.exit(0);
 }
 const getPort = () => port ?? DEFAULT_PORT;
@@ -93,37 +101,57 @@ const getStatic = () => {
     if (staticDirs)
         result.push(...(Array.isArray(staticDirs) ? staticDirs : [staticDirs]));
     if (staticlist) {
-        for (const staticsrc of (Array.isArray(staticlist) ? staticlist : [staticlist])) {
-            if (!(0, node_fs_1.existsSync)(staticsrc))
+        for (const staticsrc of Array.isArray(staticlist) ? staticlist : [staticlist]) {
+            if (!fs.existsSync(staticsrc))
                 continue;
-            result.push(...(0, node_fs_1.readFileSync)(staticsrc, "utf8")
+            result.push(...fs
+                .readFileSync(staticsrc, "utf8")
                 .split("\n")
-                .filter(c => c));
+                .filter((c) => c));
         }
     }
     return result.length > 0 ? result : undefined;
 };
 const app = (0, express_1.default)();
-app.use((0, express_js_1.createPipeline)({
-    routes: (0, singlepageapp_js_1.singlePageApp)({
-        rootDir: root ?? "dist/webapp",
-        htmlFile: index,
-        staticRootDirectories: getStatic(),
-    }),
-    options: {
-        defaultErrorHandler: true,
-        log: {
-            route: true,
-            error: true,
-            logger: winston_js_1.consoleLogger,
-        },
-    },
+app.use((req, res, next) => {
+    console.log(`${Date.now()} - ${req.method} ${req.url}`);
+    next();
+});
+app.use((0, singlepageapp_js_1.singlePageApp)({
+    htmlFile: index,
+    rootDir: root ?? "dist/webapp",
+    staticRootDirectories: getStatic(),
 }));
-(0, express_js_1.appStart)({
-    app,
-    port: getPort(),
-    logger: winston_js_1.consoleLogger,
-}).then(({ port: activePort }) => {
-    winston_js_1.consoleLogger.info(`SPA served on port ${activePort}`);
-})
-    .catch(winston_js_1.consoleLogger.error);
+let server = null;
+const maxSignals = 5;
+let signalsReceived = 0;
+const signalHandler = (signal) => {
+    if (!server) {
+        console.log(`Received ${signal}, but server not started; exiting`);
+        process.exit(1);
+    }
+    if (signalsReceived === 0) {
+        signalsReceived = 1;
+        console.log(`Received ${signal}, stopping server`);
+        server.close();
+        return;
+    }
+    if (signalsReceived < maxSignals) {
+        ++signalsReceived;
+        console.log(`Received ${signal}, ${signalsReceived} / ${maxSignals}`);
+    }
+    else {
+        console.log(`Received final ${signal}, exiting`);
+        // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+        process.exit(2);
+    }
+};
+process.on("SIGINT", () => {
+    signalHandler("SIGINT");
+});
+process.on("SIGTERM", () => {
+    signalHandler("SIGTERM");
+});
+server = app.listen(getPort(), () => {
+    console.log(`Server listening on port ${port}`);
+});

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

@@ -1,4 +1,4 @@
-import { RequestHandler } from "express";
+import * as express from "express";
 interface SinglePageAppConfig {
     /** Path to the file to serve for the whole application
      *
@@ -37,5 +37,5 @@ interface SinglePageAppConfig {
  * someRouter.use("/app", singlePageApp({rootDir: "dist/webapp"});
  * ```
  */
-export declare const singlePageApp: (config: SinglePageAppConfig) => Array<RequestHandler>;
+export declare const singlePageApp: (config: SinglePageAppConfig) => Array<express.RequestHandler>;
 export {};

package/lib/express/middlewares/singlepageapp.js

@@ -41,20 +41,27 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.singlePageApp = void 0;
 const path = __importStar(require("node:path"));
-const express_1 = __importDefault(require("express"));
+const express = __importStar(require("express"));
 /** Serve a single page webapp using a modern browser URL router
  *
  * This will serve all requests from the router using the provided index.html file, except for files
@@ -75,7 +82,7 @@ const express_1 = __importDefault(require("express"));
 const singlePageApp = (config) => {
     const rootDir = path.resolve(config.rootDir);
     const htmlFile = config.htmlFile ?? "index.html";
-    const staticDirs = (config.staticRootDirectories ?? ["js", "css", "img"]).map(c => `/${c}`);
+    const staticDirs = (config.staticRootDirectories ?? ["js", "css", "img"]).map((c) => `/${c}`);
     const appRoute = (req, res, next) => {
         for (const candidates of staticDirs)
             if (req.url.startsWith(candidates))
@@ -85,7 +92,7 @@ const singlePageApp = (config) => {
                 return next(err);
         });
     };
-    const staticRoute = express_1.default.static(rootDir);
+    const staticRoute = express.static(rootDir);
     return [appRoute, staticRoute];
 };
 exports.singlePageApp = singlePageApp;

package/lib/grunt/args.d.ts

@@ -3,72 +3,44 @@ export declare enum OptType {
     NUMBER = "number",
     BOOLEAN = "boolean"
 }
-/**
- * Possible value type for options from command line
- */
+/** Possible value type for options from command line */
 export type OptValue = string | number | boolean;
-/**
- * List of all configured options
- */
+/** List of all configured options */
 export type Opts = Record<string, OptValue>;
-/**
- * Raw value type from command line
- */
+/** Raw value type from command line */
 export type RawOptValue = undefined | boolean | string;
-/**
- * Interface to an option provider (usually Grunt itself)
- */
+/** Interface to an option provider (usually Grunt itself) */
 export interface OptionsProvider {
-    /**
-     * Return the value of an option from its key
-     */
+    /** Return the value of an option from its key */
     option: (key: string) => RawOptValue;
 }
-/**
- * Expected option from command line
- */
+/** Expected option from command line */
 interface OptionDefinitionBase {
-    /**
-     * Description for --help
-     */
+    /** Description for --help */
     description?: string;
-    /**
-     * Value type. Default to STRING.
-     */
+    /** Value type. Default to STRING. */
     type?: OptType;
 }
-/**
- * String option from command line
- */
+/** String option from command line */
 export interface OptionDefinitionString extends OptionDefinitionBase {
     type: OptType.STRING;
     defaultValue?: string;
 }
-/**
- * Number option from command line
- */
+/** Number option from command line */
 export interface OptionDefinitionNumber extends OptionDefinitionBase {
     type: OptType.NUMBER;
     defaultValue?: number;
 }
-/**
- * Boolean option from command line
- */
+/** Boolean option from command line */
 export interface OptionDefinitionBoolean extends OptionDefinitionBase {
     type: OptType.BOOLEAN;
     defaultValue?: boolean;
 }
-/**
- * All possible option definition types
- */
+/** All possible option definition types */
 export type OptionDefinition = OptionDefinitionString | OptionDefinitionNumber | OptionDefinitionBoolean;
-/**
- * Expected options from command line
- */
+/** Expected options from command line */
 export type ConfigDefinition = Record<string, OptionDefinition>;
-/**
- * Display help to the user
- */
+/** Display help to the user */
 export declare const displayHelp: (configDef: ConfigDefinition) => void;
 /**
  * Construct the full config object from command line values.