@villedemontreal/mongo 6.7.2 → 6.7.3

package/dist/scripts/index.d.ts

@@ -0,0 +1,6 @@
+export { LintScript } from './lint';
+export { LintFixScript } from './lintFix';
+export { ShowCoverageScript } from './showCoverage';
+export { TestScript } from './test';
+export { TestUnitsScript } from './testUnits';
+export { WatchScript } from './watch';

package/dist/scripts/lint.d.ts

@@ -0,0 +1,6 @@
+import { ScriptBase } from '@villedemontreal/scripting/dist/src';
+export declare class LintScript extends ScriptBase {
+    get name(): string;
+    get description(): string;
+    protected main(): Promise<void>;
+}

package/dist/scripts/lintFix.d.ts

@@ -0,0 +1,6 @@
+import { ScriptBase } from '@villedemontreal/scripting/dist/src';
+export declare class LintFixScript extends ScriptBase {
+    get name(): string;
+    get description(): string;
+    protected main(): Promise<void>;
+}

package/dist/scripts/showCoverage.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@caporal/core';
+import { ScriptBase } from '@villedemontreal/scripting/dist/src';
+export interface Options {
+    report?: string;
+}
+export declare class ShowCoverageScript extends ScriptBase<Options> {
+    get name(): string;
+    get description(): string;
+    protected get requiredDependencies(): string[];
+    protected configure(command: Command): Promise<void>;
+    protected main(): Promise<void>;
+    protected getReportDir(): string;
+}

package/dist/scripts/test.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@caporal/core';
+import { ScriptBase } from '@villedemontreal/scripting/dist/src';
+export interface Options {
+    bail?: boolean;
+    jenkins?: boolean;
+    report?: string;
+}
+export declare class TestScript extends ScriptBase<Options> {
+    get name(): string;
+    get description(): string;
+    protected configure(command: Command): Promise<void>;
+    protected main(): Promise<void>;
+}

package/dist/scripts/testUnits.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@caporal/core';
+import { ScriptBase } from '@villedemontreal/scripting/dist/src';
+export interface Options {
+    bail?: boolean;
+    jenkins?: boolean;
+    report?: string;
+}
+export declare class TestUnitsScript extends ScriptBase<Options> {
+    get name(): string;
+    get description(): string;
+    protected configure(command: Command): Promise<void>;
+    protected get requiredDependencies(): string[];
+    private addQuotes;
+    protected main(): Promise<void>;
+}

package/dist/scripts/watch.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@caporal/core';
+import { ScriptBase } from '@villedemontreal/scripting/dist/src';
+export interface Options {
+    /**
+     * Disable the visual notification
+     */
+    dn?: boolean;
+}
+export declare class WatchScript extends ScriptBase<Options> {
+    get name(): string;
+    get description(): string;
+    protected configure(command: Command): Promise<void>;
+    protected main(): Promise<void>;
+}

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

@@ -0,0 +1,19 @@
+import { ILogger } from '@villedemontreal/logger';
+/**
+ * Lib configs
+ */
+export declare class Configs {
+    isWindows: boolean;
+    libRoot: string;
+    private _loggerCreator;
+    constructor();
+    /**
+     * The Logger creator
+     */
+    get loggerCreator(): (name: string) => ILogger;
+    /**
+     * Sets the Logger creator.
+     */
+    setLoggerCreator(loggerCreator: (name: string) => ILogger): void;
+}
+export declare const configs: Configs;

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 const constants: Constants;

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/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);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from './mongoUtils';
+export * from './config/constants';
+export { IMongooseConfigs } from './config/mongooseConfigs';
+export * from './mongoClient';
+export * from './config/init';
+export * from './plugins/pagination';

package/dist/src/mongoClient.d.ts

@@ -0,0 +1,19 @@
+import * as mongoose from 'mongoose';
+import { IMongooseConfigs } from './config/mongooseConfigs';
+/**
+ * This is the entry point to use this library to manage your
+ * Mongoose connections.
+ *
+ * It *must* be called when the application starts, before any
+ * connection is made to Mongo.
+ *
+ * @returns the Mongoose connection to Mongo.
+ */
+export declare function initMongoose(mongooseConfig: IMongooseConfigs): Promise<mongoose.Connection>;
+/**
+ * Returns the Mongoose connection.
+ *
+ * Will throw an error if Mongo haass not been initialized
+ * using the "initMongo()" function.
+ */
+export declare function getMongooseConnection(): mongoose.Connection;

package/dist/src/mongoUpdater.d.ts

@@ -0,0 +1,103 @@
+import * as MongoDb from 'mongodb';
+/**
+ * Mongo updater
+ * Manages the updates of the mongo schemas
+ */
+export interface IMongoUpdater {
+    /**
+     * Validates that the application has been installed.
+     * This involves creating a special "appSchema" collection
+     * and document to track the application version and being able
+     * to update its schemas and documents...
+     */
+    checkInstallation(): Promise<void>;
+    /**
+     * Checks if the application needs update or not. Installs the updates
+     * if so.
+     */
+    checkUpdates(): Promise<void>;
+    /**
+     * Locks the appSchema document.
+     *
+     * @returns true if the lock has been acquired succesfully
+     * or false if the document was already locked.
+     */
+    lockAppSchemaDocument(): Promise<boolean>;
+    /**
+     * Unlocks the appSchema document.
+     *
+     * @returns true if the lock has been removed succesfully
+     * or false if the document was not locked.
+     */
+    unlockAppSchemaDocument(): Promise<boolean>;
+    /**
+     * Updates the app schema version stored in mongo database
+     */
+    updateAppSchemaVersion(currentVersion: string, newVersion: string): Promise<void>;
+    /**
+     * Installs the appSchema collection.
+     */
+    installAppSchemaCollection(): Promise<any>;
+    /**
+     * Gets a list of available app schema update files.
+     */
+    getAppSchemaUpdateFiles(currentVersion: string, newVersion: string): Promise<string[]>;
+    /**
+     * Updates the app schema
+     */
+    applyAppSchemaUpdates(currentVersion: string, newVersion: string): Promise<any>;
+    /**
+     * Gets the appSchema collection
+     */
+    getAppSchemaCollection(): Promise<MongoDb.Collection>;
+    /**
+     * Gets the current version from the appSchema document.
+     */
+    getAppSchemaVersion(): Promise<string>;
+}
+export interface ISchemeInfo {
+    version: string;
+    lock: boolean;
+    lockTimestamp: number;
+}
+export declare class MongoUpdater implements IMongoUpdater {
+    private mongoDb;
+    /**
+     * The *relative* path to the directory where the
+     * update files are.
+     */
+    private mongoSchemaUpdatesDirPath;
+    private lockMaxAgeSeconds;
+    private appSchemaCollectionName;
+    constructor(mongoDb: MongoDb.Db, 
+    /**
+     * The *relative* path to the directory where the
+     * update files are.
+     */
+    mongoSchemaUpdatesDirPath: string, lockMaxAgeSeconds: number, appSchemaCollectionName: string);
+    installAppSchemaCollection(): Promise<any>;
+    updateAppSchemaVersion(currentVersion: string, newVersion: string): Promise<void>;
+    getAppSchemaUpdateFiles(currentAppSchemaVersion: string, targetAppSchemaVersion: string): Promise<string[]>;
+    applyAppSchemaUpdates(currentVersion: string, newVersion: string): Promise<void>;
+    getAppSchemaCollection(): Promise<MongoDb.Collection>;
+    getAppSchemaVersion(): Promise<string>;
+    /**
+     * Tries to get the lock to modify Mongo's schemas.
+     *
+     * If a lock already exists, checks if it is too old.
+     * If too old, will create a new one... This is to prevents
+     * situations where a lock would have been taken by an app
+     * but that app *crashed* while the lock was on. We don't want
+     * suck lock to be active forever...
+     *
+     */
+    lockAppSchemaDocument(): Promise<boolean>;
+    unlockAppSchemaDocument(): Promise<boolean>;
+    checkInstallation(): Promise<void>;
+    checkUpdates: () => Promise<void>;
+    protected getAppSchemaFilesDirPath(): string;
+    /**
+     * Finds the latest Mongo update file version.
+     */
+    protected findMongoAppSchemaTargetVersion(): string;
+}

package/dist/src/mongoUpdater.test.d.ts

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

package/dist/src/mongoUtils.d.ts

@@ -0,0 +1,68 @@
+import { ApiErrorAndInfo } from '@villedemontreal/general-utils';
+import * as mocha from 'mocha';
+import { MongoMemoryReplSet, MongoMemoryServer } from 'mongodb-memory-server-core';
+import * as mongoose from 'mongoose';
+/**
+ * Mongo utilities
+ */
+export declare class MongoUtils {
+    private mongoMemServer;
+    private useReplSet;
+    private mockgosseMockedFlag;
+    /**
+     * Mocks the Mongo databases created through Mongoose.
+     *
+     * IMPORTANT!!
+     * For the "mochaInstance" parameter to be the proper
+     * one, this function must be called from a *regular function* in a
+     * test file, not from an *arrow function*! For more informations,
+     * see : https://github.com/mochajs/mocha/issues/2018
+     *
+     * Note that, currently, once this mocking is in place,
+     * it can't be removed. You should only call this function
+     * during testing!
+     *
+     * If Mongoose is already mocked, the function does nothing.
+     *
+     * @param mocha from a Mocha test file, pass "this" as the value
+     * for this parameter or "null" from elsewhere.
+     *
+     * @param mongoServerVersion the Mongo version to use.
+     * Pass null (or undefined) to use the default version
+     * downloaded by mongodb-memory-server.
+     */
+    mockMongoose(mochaInstance: mocha.Context, mongoServerVersion: string, useReplSet?: boolean): Promise<MongoMemoryServer | MongoMemoryReplSet>;
+    /**
+     * Drop all mocked Mongo databases.
+     *
+     */
+    dropMockedDatabases(): Promise<void>;
+    getMockedServerPort(): Promise<number>;
+    /**
+     * Validates if an object is a Mongoose
+     * error.
+     */
+    isMongooseError(obj: any): boolean;
+    /**
+     * Validates if an object is a plain
+     * Mongo error.
+     */
+    isPlainMongoError(errorObject: any): boolean;
+    /**
+     * Creates an Api eror from an error thrown
+     * by Mongoose.
+     *
+     * If the specified error is not a Mongo/Mongoose error, it
+     * will be returned as is.
+     *
+     * @param error the Mongo/Mongoose error object
+     * @param publicMessage a public message to be used in the
+     * generated error. Fopr example : "The user is invalid".
+     */
+    convertMongoOrMongooseErrorToApiError(err: any, publicMessage: string): ApiErrorAndInfo | any;
+    /**
+     * Converts a Mongoose Document to a plain Pojo.
+     */
+    convertMongooseDocumentToPlainObject<T>(document: T & mongoose.Document): T;
+}
+export declare const mongoUtils: MongoUtils;

package/dist/src/plugins/pagination/index.d.ts

@@ -0,0 +1,11 @@
+import { IPaginateOptions } from './specs/IPaginateOptions';
+/**
+ * @param {Schema} schema
+ */
+export declare function mongoosePaginate(schema: any): void;
+export declare class PaginateBuilder {
+    private static readonly defaultOptions;
+    static getOptions(...options: IPaginateOptions[]): IPaginateOptions;
+    static executeQueries(model: any, query: any, options: IPaginateOptions): [Promise<any[]>, Promise<number>];
+    static processResult(promises: any[], options: IPaginateOptions, callback: (error: Error, result: any) => void): Promise<any>;
+}

package/dist/src/plugins/pagination/index.test.d.ts

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

package/dist/src/plugins/pagination/specs/IPaginateOptions.d.ts

@@ -0,0 +1,51 @@
+export interface IPaginateOptions {
+    /**
+     * Fields to return (by default returns all fields)
+     * http://mongoosejs.com/docs/api.html#query_Query-select
+     * @type {string}
+     * @memberof IPaginateOptions
+     */
+    select?: string;
+    /**
+     * Sort order
+     * http://mongoosejs.com/docs/api.html#query_Query-sort
+     * @type {*}
+     * @memberof IPaginateOptions
+     */
+    sort?: any;
+    /**
+     * Paths which should be populated with other documents.
+     * http://mongoosejs.com/docs/api.html#query_Query-populate
+     * @type {string}
+     * @memberof IPaginateOptions
+     */
+    populate?: string;
+    /**
+     * Should return plain javascript objects instead of Mongoose documents?
+     * default false
+     * @type {boolean}
+     * @memberof IPaginateOptions
+     */
+    lean?: boolean;
+    /**
+     * If lean and leanWithId are true, adds id field with string representation of _id to every document
+     * default true
+     * @type {boolean}
+     * @memberof IPaginateOptions
+     */
+    leanWithId?: boolean;
+    /**
+     * Use offset to set skip position
+     * default 0
+     * @type {number}
+     * @memberof IPaginateOptions
+     */
+    offset?: number;
+    /**
+     * limit the items returned
+     * default 10
+     * @type {number}
+     * @memberof IPaginateOptions
+     */
+    limit?: number;
+}

package/dist/src/utils/logger.d.ts

@@ -0,0 +1,11 @@
+import { ILogger } from '@villedemontreal/logger';
+/**
+ * Creates a Logger.
+ */
+export declare function createLogger(name: string): ILogger;
+/**
+ * A Logger that uses a dummy cid provider.
+ *
+ * Only use this when running the tests!
+ */
+export declare function getTestingLoggerCreator(): (name: string) => ILogger;

package/dist/src/utils/testingConfigurations.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Call this when your need to set
+ * *Testing* configurations to the current
+ * library, without the need for a calling code
+ * to do so.
+ *
+ */
+export declare function setTestingConfigurations(): void;

package/dist/tests/testingMongoUpdates/1.0.0.d.ts

@@ -0,0 +1,5 @@
+import * as MongoDb from 'mongodb';
+/**
+ * TEST update - version 1.0.0
+ */
+export default function update(db: MongoDb.Db): Promise<void>;

package/dist/tests/testingMongoUpdates/1.0.1.d.ts

@@ -0,0 +1,5 @@
+import * as MongoDb from 'mongodb';
+/**
+ * TEST update - version 1.0.1
+ */
+export default function update(db: MongoDb.Db): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@villedemontreal/mongo",
-  "version": "6.7.2",
+  "version": "6.7.3",
   "description": "Utilities for Mongo / Mongoose",
   "main": "dist/src/index.js",
   "typings": "dist/src",