@villedemontreal/mongo 6.7.0

package/LICENSE

@@ -0,0 +1,22 @@
+
+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,226 @@
+# @villedemontreal/mongo
+Module d'utilitaires pour les connections de Mongo.
+
+## Installation
+
+Installer la bibliothèque:
+
+```shell
+    npm install --save @villedemontreal/mongo
+```
+
+## Configuration pour utilisation dans Docker
+
+À lire si les tests fonctionnent bien en local mais timeout lors du build sur Jenkins.
+
+Il est conseiller d'activer les traces de débogage si cela se produit. Voir plus bas dans ce document.
+
+Mongo a une dépendance sur la libcurl. Cette librairie doit être présente dans l'image docker
+
+`apt-get install -y curl &&`
+
+Il faut veiller à utiliser une version de mongo compatible avec la libcurl sur l'OS du conteneur.
+
+La version 4.4.0 fonction avec les versions récentes de node (ex node-14-buster-slim)
+``
+
+### Références
+
+https://github.com/nodkz/mongodb-memory-server/issues/204
+https://jira.mongodb.org/browse/SERVER-37768
+https://jira.mongodb.org/browse/SERVER-44491
+
+## Utilisation
+
+Il faut premièrement initialiser la librairie elle-même. Par exemple, dans un projet d'API basé sur le générateur, ceci sera effectué dans le
+fichier "`src/init.ts`", au début de la fonction `initComponents()` :
+
+```typescript
+import { init as initMongoUtilsLib } from '@villedemontreal/mongo';
+import { createLogger } from './utils/logger';
+
+// ...
+
+export async function initComponents() {
+  initMongoUtilsLib(createLogger);
+
+  //...
+}
+```
+
+Puis si, en plus des simples utilitaire, vous désirez utiliser la gestion de Mongoose fournie par la librairie (pour
+profiter de la fonctionalité de migrations par exemple), il faut appeller `initMongoose(...)` avec les configurations
+appropriées.
+
+Par exemple :
+
+```typescript
+import { initMongoose, IMongooseConfigs } from "@villedemontreal/mongo";
+import { configs } from "../../../../config/configs";
+
+await initMongoose( new IMongooseConfigs {
+    applyUpdates: true,
+    connectionString: configs.mongo.connectionString,
+    connectionOptions: configs.mongo.connectionOptions,
+    //...
+});
+```
+
+# Débogage
+
+En cas de problème avec mongo-memory-server-core, vous pouvez activer les traces de debogage en utilisant une varible
+d'environnement.
+
+`DEBUG=MongoMS:*`
+
+Voir https://www.npmjs.com/package/debug pour les détails d'utilisation
+
+# Versions
+
+Importe les dépendances suivantes:
+
+- Mongo 3.5.9 [Détails](https://docs.mongodb.com/ecosystem/drivers/driver-compatibility-reference/#node-js-driver-compatibility)
+- Mongoose 5.9.19 [Détails](https://mongoosejs.com/docs/compatibility.html)
+- MongoMemoryServer 6.6.1
+- @types/mongodb: 3.5.22
+- @types/mongoose: 5.7.24
+
+## Notes
+
+- Lorsque vous appellez la méthode `MongoUtils#mockMongoose(...)` en passant une instance de "`mocha`", assurez-vous de le
+  faire dans une function _régulière_ et non dans une _arrow_ function ou alors une erreur sera lancée! Par exemple :
+
+Ceci ne fonctionnera **pas** :
+
+```typescript
+before(async () => {
+  // ...
+  await mongoUtils.mockMongoose(this, testconfig.mockServer.serverVersion);
+});
+```
+
+Mais ceci va fonctionner :
+
+```typescript
+before(async function() {
+  // ...
+  await mongoUtils.mockMongoose(this, testconfig.mockServer.serverVersion);
+});
+```
+
+Voir [cette issue](https://github.com/mochajs/mocha/issues/2018) pour plus de détails.
+
+# Plugins
+
+## Pagination
+
+Le but du plugin est de faciliter l'intégration de la pagination dans nos systèmes et de standardiser l'output afin de faciliter la consomation.
+
+### Utilisation
+
+```typescript
+import { mongoosePaginate } from '@villedemontreal/mongo';
+var schema = new mongoose.Schema({
+  /* schema definition */
+});
+schema.plugin(mongoosePaginate);
+
+var Model = mongoose.model('Model', schema); // Model.paginate()
+const result = Model.paginate({}, { offset: 0, limit: 10 });
+```
+
+### Output
+
+```json
+{
+  "paging": {
+    "totalCount": 4,
+    "limit": 25,
+    "offset": 0
+  },
+  "items": [
+    // your items
+  ]
+}
+```
+
+# 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)
+
+# Test et publication de la librairie sur Nexus
+
+En mergant une pull request dans la branche `develop`, un artifact "`-pre.build`" sera créé automatiquement dans Nexus. Vous
+pouvez utiliser cette version temporaire de la librairie pour bien la tester dans un réel projet.
+
+Une fois mergée dans `master`, la librairie est définitiement publiée dans Nexus, en utilisant la version spécifiée dans
+le `package.json`.
+
+## Artifact Nexus privé, lors du développement
+
+Lors du développement d'une nouvelle fonctionnalité, sur une branche `feature`, il peut parfois être
+utile de déployer une version temporaire de la librairie dans Nexus. Ceci permet de bien tester
+l'utilisation de la librairie modifiée dans un vrai projet, ou même dans une autre librairie
+elle-même par la suite utilisée dans un vrai projet.
+
+Si le code à tester est terminé et prêt à être mis en commun avec d'autres développeurs, la solution
+de base, comme spécifiée à la section précédante, est de merger sur `develop`: ceci créera
+automatiquement un artifact "`-pre-build`" dans Nexus. Cependant, si le code est encore en développement
+et vous désirez éviter de polluer la branche commune `develop` avec du code temporaire, il y a une
+solution permettant de générer un artifact "`[votre prénom]-pre-build`" temporaire dans Nexus,
+à partir d'une branche `feature` directement:
+
+1. Checkoutez votre branche `feature` dans une branche nommée "`nexus`". Ce nom est
+   important et correspond à une entrée dans le `Jenkinsfile`.
+2. Une fois sur la branche `nexus`, ajoutez un suffixe "`-[votre prénom]`" à
+   la version dans le `package.json`, par exemple: "`5.15.0-roger`".
+   Ceci permet d'éviter tout conflit dans Nexus et exprime clairement qu'il
+   s'agit d'une version temporaire pour votre développement privé.
+3. Commitez et poussez la branche `nexus`.
+4. Une fois le build Jenkins terminé, un artifact pour votre version aura été
+   déployé dans Nexus. Détruire votre branche dans Bitbucket pour permettre aux
+   autres developpeurs d'utiliser cette approche.
+
+**Notez** que, lors du développement dans une branche `feature`, l'utilisation d'un simple
+`npm link` local peut souvent être suffisant! Mais cette solution a ses limites, par exemple si
+vous désirez tester la librairie modifiée _dans un container Docker_.
+
+# Aide / Contributions
+
+Pour obtenir de l'aide avec cette librairie, vous pouvez poster sur la salle Google Chat [dev-discussions]
+
+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';
+/**
+ * Lib configs
+ */
+export declare class Configs {
+    private _loggerCreator;
+    /**
+     * The Logger creator
+     */
+    get loggerCreator(): (name: string) => ILogger;
+    /**
+     * Sets the Logger creator.
+     */
+    setLoggerCreator(loggerCreator: (name: string) => ILogger): void;
+}
+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;
+/**
+ * Lib configs
+ */
+class Configs {
+    /**
+     * The Logger creator
+     */
+    get loggerCreator() {
+        if (!this._loggerCreator) {
+            throw new Error(`The Logger Creator HAS to be set as a configuration`);
+        }
+        return this._loggerCreator;
+    }
+    /**
+     * Sets the Logger creator.
+     */
+    setLoggerCreator(loggerCreator) {
+        this._loggerCreator = loggerCreator;
+    }
+}
+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;IACH,IAAI,aAAa;QACf,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE;YACxB,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;SACxE;QACD,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED;;OAEG;IACI,gBAAgB,CAAC,aAAwC;QAC9D,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;IACtC,CAAC;CACF;AAnBD,0BAmBC;AAEU,QAAA,OAAO,GAAY,IAAI,OAAO,EAAE,CAAC"}

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

@@ -0,0 +1,85 @@
+import { IMongooseConfigs } from './mongooseConfigs';
+/**
+ * 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();
+    /**
+     * Base config to 'mock' a mongo server
+     */
+    get testsConfig(): IMongooseConfigs;
+    /**
+     * Mongo constants
+     */
+    get mongo(): {
+        testing: {
+            /**
+             * The "connectionString" to use for a mock
+             * Mongo server to be used instead of a real one.
+             * This option is only available on the "development"
+             * environment, or when tests are ran.
+             */
+            MOCK_CONNECTION_STRING: string;
+        };
+        /**
+         * The names of the Mongo collections used in
+         * this application.
+         */
+        collectionNames: {
+            /**
+             * Special collection that stores informations about the
+             * schema currently installed for the application.
+             */
+            APP_SCHEMA: string;
+        };
+        /**
+         * Mongo error codes
+         */
+        mongoErrorCodes: {
+            /**
+             * The code for a Mongo "duplicate key" error.
+             */
+            DUPLICATE_KEY: number;
+        };
+        /**
+         * Mongoose constants
+         */
+        mongoose: {
+            /**
+             *  Mongoose error codes
+             */
+            errorCodes: {
+                /**
+                 * The code for a Mongoose "required" error.
+                 */
+                REQUIRED_FIELD: string;
+            };
+            /**
+             *  Mongoose error kinds
+             */
+            errorKinds: {
+                OBJECT_ID: string;
+            };
+            /**
+             *  Mongoose error names
+             */
+            errorNames: {
+                CAST_ERROR: string;
+            };
+        };
+    };
+}
+export declare let constants: Constants;

package/dist/src/config/constants.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constants = exports.Constants = void 0;
+// ==========================================
+// Application constants
+// ==========================================
+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;
+    }
+    /**
+     * Base config to 'mock' a mongo server
+     */
+    get testsConfig() {
+        return {
+            applyUpdates: false,
+            connectionString: 'mock',
+            connectionOptions: {
+                useNewUrlParser: true,
+                useUnifiedTopology: true
+            },
+            updater: {
+                lockMaxAgeSeconds: 30,
+                mongoSchemaUpdatesDirPath: '/dist/tests/testingMongoUpdates',
+                appSchemaCollectionName: 'testAppSchema'
+            },
+            mockServer: {
+                serverVersion: '4.0.16'
+            }
+        };
+    }
+    /**
+     * Mongo constants
+     */
+    get mongo() {
+        return {
+            testing: {
+                /**
+                 * The "connectionString" to use for a mock
+                 * Mongo server to be used instead of a real one.
+                 * This option is only available on the "development"
+                 * environment, or when tests are ran.
+                 */
+                MOCK_CONNECTION_STRING: 'mock'
+            },
+            /**
+             * The names of the Mongo collections used in
+             * this application.
+             */
+            collectionNames: {
+                /**
+                 * Special collection that stores informations about the
+                 * schema currently installed for the application.
+                 */
+                APP_SCHEMA: 'appSchema'
+            },
+            /**
+             * Mongo error codes
+             */
+            mongoErrorCodes: {
+                /**
+                 * The code for a Mongo "duplicate key" error.
+                 */
+                DUPLICATE_KEY: 11000
+            },
+            /**
+             * Mongoose constants
+             */
+            mongoose: {
+                /**
+                 *  Mongoose error codes
+                 */
+                errorCodes: {
+                    /**
+                     * The code for a Mongoose "required" error.
+                     */
+                    REQUIRED_FIELD: 'required'
+                },
+                /**
+                 *  Mongoose error kinds
+                 */
+                errorKinds: {
+                    OBJECT_ID: 'ObjectId'
+                },
+                /**
+                 *  Mongoose error names
+                 */
+                errorNames: {
+                    CAST_ERROR: 'CastError'
+                }
+            }
+        };
+    }
+}
+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,6CAA6C;AAC7C,wBAAwB;AACxB,6CAA6C;AAC7C,iDAAgD;AAChD,6BAA6B;AAG7B;;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,WAAW;QACb,OAAO;YACL,YAAY,EAAE,KAAK;YACnB,gBAAgB,EAAE,MAAM;YACxB,iBAAiB,EAAE;gBACjB,eAAe,EAAE,IAAI;gBACrB,kBAAkB,EAAE,IAAI;aACzB;YACD,OAAO,EAAE;gBACP,iBAAiB,EAAE,EAAE;gBACrB,yBAAyB,EAAE,iCAAiC;gBAC5D,uBAAuB,EAAE,eAAe;aACzC;YACD,UAAU,EAAE;gBACV,aAAa,EAAE,QAAQ;aACxB;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACP,OAAO;YACL,OAAO,EAAE;gBACP;;;;;mBAKG;gBACH,sBAAsB,EAAE,MAAM;aAC/B;YACD;;;eAGG;YACH,eAAe,EAAE;gBACf;;;mBAGG;gBACH,UAAU,EAAE,WAAW;aACxB;YACD;;eAEG;YACH,eAAe,EAAE;gBACf;;mBAEG;gBACH,aAAa,EAAE,KAAK;aACrB;YAED;;eAEG;YACH,QAAQ,EAAE;gBACR;;mBAEG;gBACH,UAAU,EAAE;oBACV;;uBAEG;oBACH,cAAc,EAAE,UAAU;iBAC3B;gBAED;;mBAEG;gBACH,UAAU,EAAE;oBACV,SAAS,EAAE,UAAU;iBACtB;gBAED;;mBAEG;gBACH,UAAU,EAAE;oBACV,UAAU,EAAE,WAAW;iBACxB;aACF;SACF,CAAC;IACJ,CAAC;CACF;AA7GD,8BA6GC;AAEU,QAAA,SAAS,GAAc,IAAI,SAAS,EAAE,CAAC"}

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

@@ -0,0 +1,9 @@
+import { ILogger } from '@villedemontreal/logger';
+/**
+ * Inits the library.
+ */
+export declare function init(loggerCreator: (name: string) => ILogger): void;
+/**
+ * checks if the library has been initialized.
+ */
+export declare function isInited(): boolean;

package/dist/src/config/init.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInited = exports.init = void 0;
+const configs_1 = require("./configs");
+let libIsInitialized = false;
+/**
+ * Inits the library.
+ */
+function init(loggerCreator) {
+    if (!loggerCreator) {
+        throw new Error(`The Logger Creator is required.`);
+    }
+    configs_1.configs.setLoggerCreator(loggerCreator);
+    libIsInitialized = true;
+}
+exports.init = init;
+/**
+ * checks if the library has been initialized.
+ */
+function isInited() {
+    return libIsInitialized;
+}
+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,gBAAgB,GAAY,KAAK,CAAC;AACtC;;GAEG;AACH,SAAgB,IAAI,CAAC,aAAwC;IAC3D,IAAI,CAAC,aAAa,EAAE;QAClB,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;KACpD;IAED,iBAAO,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAExC,gBAAgB,GAAG,IAAI,CAAC;AAC1B,CAAC;AARD,oBAQC;AAED;;GAEG;AACH,SAAgB,QAAQ;IACtB,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAFD,4BAEC"}

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

@@ -0,0 +1,73 @@
+export interface IMongooseConfigs {
+    /**
+     * The updater.mongoSchemaUpdatesDirPath
+     * is a required config.
+     */
+    updater?: {
+        /**
+         * Name of the app schema collection name to use.
+         * Useful when multiple components use the same database.
+         */
+        appSchemaCollectionName?: string;
+        /**
+         * The path where to find update files.
+         */
+        mongoSchemaUpdatesDirPath: string;
+        lockMaxAgeSeconds?: number;
+    };
+    /**
+     * @param applyUpdates Should the database be checked for missing
+     * updates and have them applied if required?
+     * Defaults to true.
+     */
+    applyUpdates?: boolean;
+    /**
+     * If no connectionString is provided, "mock" will be
+     * used by default and a temporary Mongo server will
+     * be used.
+     */
+    connectionString?: string;
+    /**
+     * The Mongoose connection options.
+     */
+    connectionOptions?: any;
+    mockServer?: {
+        /**
+         *  @param mongoServerVersion the Mongo version to use.
+         *
+         * Pass null (or undefined) to use the default version
+         * downloaded by mockServer.
+         */
+        serverVersion?: string;
+    };
+}
+/**
+ * Mongoose configs with default values.
+ */
+export declare class MongooseConfigs implements IMongooseConfigs {
+    /**
+     * @param applyUpdates Should the database be checked for missing
+     * updates and have them applied if required?
+     */
+    applyUpdates: boolean;
+    /**
+     * If no connectionString is provided, "mock" will be
+     * used by default and a temporary Mongo server will
+     * be used.
+     */
+    connectionString: string;
+    connectionOptions: any;
+    updater: {
+        lockMaxAgeSeconds: number;
+        mongoSchemaUpdatesDirPath: string;
+        appSchemaCollectionName: string;
+    };
+    mockServer: {
+        serverVersion: string;
+    };
+    /**
+     * Overrides default configurations using the ones passed
+     * as parameters.
+     */
+    constructor(overridingConfigs: IMongooseConfigs);
+}