@villedemontreal/correlation-id 5.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Ville de Montréal and other contributors
+
+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.

package/README.md

@@ -0,0 +1,119 @@
+# @villedemontreal/correlation-id
+Module fournissant un middleware Express pour propager ou/et générer le correlation id et un service permettant de le récupérer à n'importe quel moment de la requête sans devoir le propager à la main.
+
+
+## Installation
+Installer la bibliothèque:
+```shell
+    npm install --save @villedemontreal/correlation-id
+```
+
+Avec yarn:
+```shell
+    yarn add @villedemontreal/correlation-id
+```
+
+## Mise en garde!
+
+**Attention!** Pour que les Correlation Ids soient les bons partout dans une application, il faut que ces cid aient été
+retournées *par le même `correlationIdService`*! Vous ne devez pas importer un `correlationIdService` dans une librairie dans le
+but d'utiliser `correlationIdService.getId()` : cela ne retournera pas le bon cid!
+
+Cette librarie ne devrait donc qu'être utilisée que par un projet API racine, et non dans une librairie. C'est à 
+cette application racine de passer ce qu'il faut comme configurations aux diverses librairies pour qu'elles puissent avoir
+accès aux bons cids.
+
+Si votre librairie, pour une raison quelconque, doit avoir accès aux Correlations Ids directement, il faut que l'application racine lui passe un "`Correlation Id Provider`", utilisant le service racine! Voir le projet [http-request] pour un exemple.
+
+
+## Utilisation
+
+### Configurations
+
+Un code utilisant cette librarie doit premièrement la configurer en appellant la fonction
+"`init(...)`" exportée par le fichier "`src/config/init.ts`".
+
+La configuration "`loggerCreator`" est *requise* par cette librairie. Cela signifie qu'un code utilisant la librairie
+(que ce soit du code d'un projet d'API ou d'une autre librairie) *doit* setter cette configuration *avant* que les composants
+de la librairie ne soient utilisés. 
+
+Finalement, notez qu'une fonction "`isInited()`" est exportée et permet au code appelant de valider que la librairie a été
+configurée correctement!
+
+### Mise en place
+
+Il suffit d'ajouter le middleware `correlationIdMiddleware` dans une application `Express`. Par la suite, tout appel
+à `correlationIdService.getId()` va retourner le bon correlation id du contexte courant. Cet id sera
+sera reçu dans la requête, par le header "`X-Correlation-ID`" ou, s'il n'est pas présent, sera un nouvel id
+généré.
+
+Notez qu'un API démarré avec le générateur [generator-mtl-node-api]
+aura déjà tout en place pour la gestion du correlation id.
+
+Exemple :
+```typescript
+import { correlationIdMiddleware } from "@villedemontreal/correlation-id";
+
+const app = express();
+app.use(correlationIdMiddleware);
+```
+
+**Important!** : Si vous utilisez un middleware "`bodyParser`", assurez-vous que `correlationIdMiddleware` est enregistré
+*après*, autrement une requête POST pourrait ne pas trouver le correlation id du context correctement!
+
+### Obtention du correlation id
+
+Exemple :
+```typescript
+import { correlationIdService, CorrelationId } from "@villedemontreal/correlation-id";
+
+// Controller to update an account: PUT /accounts/:inum
+public async update(req: express.Request, res: express.Response, next: express.NextFunction): Promise<void> {
+
+    // Get Correlation ID
+    let cid: CorrelationId = correlationIdService.getId();
+    console.log(cid);
+}
+```
+
+# Builder le projet
+
+**Note**: Sur Linux/Mac assurz-vous que le fichier `run` est exécutable. Autrement, lancez `chmod +x ./run`.
+
+Pour lancer le build :
+
+- > `run compile` ou `./run compile` (sur Linux/Mac)
+
+Pour lancer les tests :
+
+- > `run test` ou `./run test` (sur Linux/Mac)
+
+# Mode Watch
+
+Lors du développement, il est possible de lancer `run watch` (ou `./run watch` sur Linux/mac) dans un terminal
+externe pour démarrer la compilation incrémentale. Il est alors possible de lancer certaines _launch configuration_
+comme `Debug current tests file - fast` dans VsCode et ainsi déboguer le fichier de tests présentement ouvert sans
+avoir à (re)compiler au préalable (la compilation incrémentale s'en sera chargé).
+
+Notez que, par défaut, des _notifications desktop_ sont activées pour indiquer visuellement si la compilation
+incrémentale est un succès ou si une erreur a été trouvée. Vous pouvez désactiver ces notifications en utilisant
+`run watch --dn` (`d`isable `n`otifications).
+
+# Déboguer le projet
+
+Trois "_launch configurations_" sont founies pour déboguer le projet dans VSCode :
+
+- "`Debug all tests`", la launch configuration par défaut. Lance les tests en mode debug. Vous pouvez mettre
+  des breakpoints et ils seront respectés.
+
+- "`Debug a test file`". Lance _un_ fichier de tests en mode debug. Vous pouvez mettre
+  des breakpoints et ils seront respectés. Pour changer le fichier de tests à être exécuté, vous devez modifier la ligne appropriée dans le fichier "`.vscode/launch.json`".
+
+- "`Debug current tests file`". Lance le fichier de tests _présentement ouvert_ dans VSCode en mode debug. Effectue la compîlation au préalable.
+
+- "`Debug current tests file - fast`". Lance le fichier de tests _présentement ouvert_ dans VSCode en mode debug. Aucune compilation
+  n'est effectuée au préalable. Cette launch configuration doit être utilisée lorsque la compilation incrémentale roule (voir la section "`Mode Watch`" plus haut)
+
+# Aide / Contributions
+
+Notez que les contributions sous forme de pull requests sont bienvenues.

package/dist/src/config/configs.d.ts

@@ -0,0 +1,16 @@
+import { ILogger } from '@villedemontreal/logger';
+/**
+ * Http Client Config
+ */
+export declare class Configs {
+    private loggerCreatorVar;
+    /**
+     * Sets the Logger creator.
+     */
+    setLoggerCreator(loggerCreator: (name: string) => ILogger): void;
+    /**
+     * The Logger creator
+     */
+    get loggerCreator(): (name: string) => ILogger;
+}
+export declare let configs: Configs;

package/dist/src/config/configs.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configs = exports.Configs = void 0;
+/**
+ * Http Client Config
+ */
+class Configs {
+    /**
+     * Sets the Logger creator.
+     */
+    setLoggerCreator(loggerCreator) {
+        this.loggerCreatorVar = loggerCreator;
+    }
+    /**
+     * The Logger creator
+     */
+    get loggerCreator() {
+        if (!this.loggerCreatorVar) {
+            throw new Error(`The Logger Creator HAS to be set as a configuration! Please call the init(...) fonction first.`);
+        }
+        return this.loggerCreatorVar;
+    }
+}
+exports.Configs = Configs;
+exports.configs = new Configs();
+//# sourceMappingURL=configs.js.map

package/dist/src/config/configs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configs.js","sourceRoot":"","sources":["../../../src/config/configs.ts"],"names":[],"mappings":";;;AAEA;;GAEG;AACH,MAAa,OAAO;IAGlB;;OAEG;IACI,gBAAgB,CAAC,aAAwC;QAC9D,IAAI,CAAC,gBAAgB,GAAG,aAAa,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,IAAI,aAAa;QACf,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE;YAC1B,MAAM,IAAI,KAAK,CAAC,gGAAgG,CAAC,CAAC;SACnH;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAnBD,0BAmBC;AACU,QAAA,OAAO,GAAY,IAAI,OAAO,EAAE,CAAC"}

package/dist/src/config/constants.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Library constants
+ */
+export declare class Constants {
+    /**
+     * The library root. When this library is used
+     * as a dependency in a project, the "libRoot"
+     * will be the path to the dependency folder,
+     * inside the "node_modules".
+     */
+    libRoot: string;
+    /**
+     * The app root. When this library is used
+     * as a dependency in a project, the "appRoot"
+     * will be the path to the root project!
+     */
+    appRoot: string;
+    constructor();
+    /**
+     * Extra values that we can add to the original Express request.
+     */
+    get requestExtraVariables(): {
+        cidReceivedInRequest: string;
+        cidNew: string;
+    };
+}
+export declare let constants: Constants;

package/dist/src/config/constants.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constants = exports.Constants = void 0;
+const app_root_path_1 = require("app-root-path");
+const path = require("path");
+/**
+ * Library constants
+ */
+class Constants {
+    constructor() {
+        // From the "dist/src/config" folder
+        this.libRoot = path.normalize(__dirname + '/../../..');
+        this.appRoot = app_root_path_1.path;
+    }
+    /**
+     * Extra values that we can add to the original Express request.
+     */
+    get requestExtraVariables() {
+        return {
+            cidReceivedInRequest: '_cidReceivedInRequest',
+            cidNew: '_cidNew'
+        };
+    }
+}
+exports.Constants = Constants;
+exports.constants = new Constants();
+//# sourceMappingURL=constants.js.map

package/dist/src/config/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/config/constants.ts"],"names":[],"mappings":";;;AAAA,iDAAgD;AAChD,6BAA6B;AAE7B;;GAEG;AACH,MAAa,SAAS;IAgBpB;QACE,oCAAoC;QACpC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,GAAG,WAAW,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO,GAAG,oBAAO,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,IAAI,qBAAqB;QACvB,OAAO;YACL,oBAAoB,EAAE,uBAAuB;YAC7C,MAAM,EAAE,SAAS;SAClB,CAAC;IACJ,CAAC;CACF;AA/BD,8BA+BC;AAEU,QAAA,SAAS,GAAc,IAAI,SAAS,EAAE,CAAC"}

package/dist/src/config/init.d.ts

@@ -0,0 +1,15 @@
+import { ILogger } from '@villedemontreal/logger';
+/**
+ * Inits the library.
+ */
+export declare function init(loggerCreator: (name: string) => ILogger): void;
+/**
+ * Is the library properly initialized?
+ *
+ * This function MUST be named "isInited()"!
+ * Code using this library may loop over all its "@villemontreal"
+ * dependencies and, if one of those exports a "isInited" fonction,
+ * it will enforce that the lib has been properly initialized before
+ * starting...
+ */
+export declare function isInited(): boolean;

package/dist/src/config/init.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInited = exports.init = void 0;
+const configs_1 = require("./configs");
+let libIsInited = false;
+/**
+ * Inits the library.
+ */
+function init(loggerCreator) {
+    if (!loggerCreator) {
+        throw new Error(`The Logger Creator is required.`);
+    }
+    configs_1.configs.setLoggerCreator(loggerCreator);
+    // ==========================================
+    // Set as being "properly initialized".
+    // At the very end of the "init()" function!
+    // ==========================================
+    libIsInited = true;
+}
+exports.init = init;
+/**
+ * Is the library properly initialized?
+ *
+ * This function MUST be named "isInited()"!
+ * Code using this library may loop over all its "@villemontreal"
+ * dependencies and, if one of those exports a "isInited" fonction,
+ * it will enforce that the lib has been properly initialized before
+ * starting...
+ */
+function isInited() {
+    return libIsInited;
+}
+exports.isInited = isInited;
+//# sourceMappingURL=init.js.map

package/dist/src/config/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/config/init.ts"],"names":[],"mappings":";;;AACA,uCAAoC;AAEpC,IAAI,WAAW,GAAY,KAAK,CAAC;AAEjC;;GAEG;AACH,SAAgB,IAAI,CAAC,aAAwC;IAC3D,IAAI,CAAC,aAAa,EAAE;QAClB,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;KACpD;IACD,iBAAO,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAExC,6CAA6C;IAC7C,uCAAuC;IACvC,4CAA4C;IAC5C,6CAA6C;IAC7C,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAXD,oBAWC;AAED;;;;;;;;GAQG;AACH,SAAgB,QAAQ;IACtB,OAAO,WAAW,CAAC;AACrB,CAAC;AAFD,4BAEC"}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from './services/correlationIdService';
+export * from './middleware/correlationIdMiddleware';
+export * from './config/init';

package/dist/src/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./services/correlationIdService"), exports);
+__exportStar(require("./middleware/correlationIdMiddleware"), exports);
+// ==========================================
+// We do not export the configs instance itself,
+// only the "init()" method, so we can define
+// required parameters.
+// ==========================================
+__exportStar(require("./config/init"), exports);
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kEAAgD;AAChD,uEAAqD;AAErD,6CAA6C;AAC7C,gDAAgD;AAChD,6CAA6C;AAC7C,uBAAuB;AACvB,6CAA6C;AAC7C,gDAA8B"}

package/dist/src/middleware/correlationIdMiddleware.d.ts

@@ -0,0 +1,8 @@
+import * as express from 'express';
+/**
+ * Correlation ID Middleware
+ *
+ * @param filter a filter which is going to be called with the request to see if a
+ * colleration id scope must be managed or not.
+ */
+export declare let createCorrelationIdMiddleware: (filter?: (req: express.Request) => boolean) => (req: express.Request, res: express.Response, next: express.NextFunction) => Promise<void>;

package/dist/src/middleware/correlationIdMiddleware.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCorrelationIdMiddleware = void 0;
+const http_header_fields_typed_1 = require("http-header-fields-typed");
+const constants_1 = require("../config/constants");
+const correlationIdService_1 = require("../services/correlationIdService");
+/**
+ * Correlation ID Middleware
+ *
+ * @param filter a filter which is going to be called with the request to see if a
+ * colleration id scope must be managed or not.
+ */
+let createCorrelationIdMiddleware = (filter) => {
+    const correlationIdMiddleware = (req, res, next) => {
+        if (filter && !filter(req)) {
+            next();
+        }
+        else {
+            // ==========================================
+            // If a Correlation ID (cid) exists in the request
+            // it will be used. Otherwise, a new one is created.
+            //
+            // We add the cid to the response!
+            // ==========================================
+            let correlationId = req.get(http_header_fields_typed_1.default.X_CORRELATION_ID);
+            if (!correlationId) {
+                correlationId = correlationIdService_1.correlationIdService.createNewId();
+                req[constants_1.constants.requestExtraVariables.cidNew] = correlationId;
+            }
+            else {
+                req[constants_1.constants.requestExtraVariables.cidReceivedInRequest] = correlationId;
+            }
+            if (!res.headersSent) {
+                res.set(http_header_fields_typed_1.default.X_CORRELATION_ID, correlationId);
+            }
+            correlationIdService_1.correlationIdService.withId(next, correlationId);
+        }
+        return null;
+    };
+    return correlationIdMiddleware;
+};
+exports.createCorrelationIdMiddleware = createCorrelationIdMiddleware;
+//# sourceMappingURL=correlationIdMiddleware.js.map

package/dist/src/middleware/correlationIdMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlationIdMiddleware.js","sourceRoot":"","sources":["../../../src/middleware/correlationIdMiddleware.ts"],"names":[],"mappings":";;;AACA,uEAA6D;AAC7D,mDAAgD;AAChD,2EAAwE;AAExE;;;;;GAKG;AACI,IAAI,6BAA6B,GAAG,CACzC,MAA0C,EACoD,EAAE;IAChG,MAAM,uBAAuB,GAAG,CAC9B,GAAoB,EACpB,GAAqB,EACrB,IAA0B,EACX,EAAE;QACjB,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;YAC1B,IAAI,EAAE,CAAC;SACR;aAAM;YACL,6CAA6C;YAC7C,kDAAkD;YAClD,oDAAoD;YACpD,EAAE;YACF,kCAAkC;YAClC,6CAA6C;YAC7C,IAAI,aAAa,GAAG,GAAG,CAAC,GAAG,CAAC,kCAAqB,CAAC,gBAAgB,CAAC,CAAC;YACpE,IAAI,CAAC,aAAa,EAAE;gBAClB,aAAa,GAAG,2CAAoB,CAAC,WAAW,EAAE,CAAC;gBACnD,GAAG,CAAC,qBAAS,CAAC,qBAAqB,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC;aAC7D;iBAAM;gBACL,GAAG,CAAC,qBAAS,CAAC,qBAAqB,CAAC,oBAAoB,CAAC,GAAG,aAAa,CAAC;aAC3E;YACD,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE;gBACpB,GAAG,CAAC,GAAG,CAAC,kCAAqB,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC;aAChE;YACD,2CAAoB,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;SAClD;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,OAAO,uBAAuB,CAAC;AACjC,CAAC,CAAC;AAjCS,QAAA,6BAA6B,iCAiCtC"}

package/dist/src/middleware/correlationIdMiddleware.test.d.ts

@@ -0,0 +1 @@
+export {};