@villedemontreal/mongo 6.7.0

package/src/mongoUtils.ts

@@ -0,0 +1,322 @@
+// ==========================================
+// Mongo utilities
+// ==========================================
+import {
+  ApiErrorAndInfo,
+  createError,
+  createInvalidParameterError,
+  createNotFoundError,
+  createServerError,
+  globalConstants,
+  IApiError,
+  utils
+} from '@villedemontreal/general-utils';
+import { LogLevel } from '@villedemontreal/logger';
+import * as fs from 'fs-extra';
+import * as HttpStatusCodes from 'http-status-codes';
+import * as _ from 'lodash';
+import * as mocha from 'mocha';
+import { MongoMemoryReplSet, MongoMemoryServer } from 'mongodb-memory-server-core';
+import * as mongoose from 'mongoose';
+import { constants } from './config/constants';
+
+/**
+ * Mongo utilities
+ */
+export class MongoUtils {
+  private mongoMemServer: MongoMemoryServer | MongoMemoryReplSet;
+  private useReplSet: boolean = false;
+
+  private mockgosseMockedFlag = 'mocked';
+
+  /**
+   * 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.
+   */
+  public async mockMongoose(
+    mochaInstance: mocha.Context,
+    mongoServerVersion: string,
+    useReplSet: boolean = false
+  ): Promise<MongoMemoryServer | MongoMemoryReplSet> {
+    // ==========================================
+    // We only mock the database if it's
+    // not already so.
+    // ==========================================
+    if (!this.mongoMemServer) {
+      // this.useReplSet = useReplSet;
+      // ==========================================
+      // Path to download the mocked Mongo server to.
+      // We make sure this folder is wihtin the application
+      // so when the application is mounted in a Docker
+      // container, the server will not be downloaded
+      // over and over.
+      // ==========================================
+      const downloadDirPath = constants.appRoot + '/temp/mockServer';
+      if (!fs.existsSync(downloadDirPath)) {
+        fs.mkdirsSync(downloadDirPath);
+      }
+
+      // ==========================================
+      // Data directory
+      // ==========================================
+      const dataRootPath = downloadDirPath + '/data';
+      if (!fs.existsSync(dataRootPath)) {
+        fs.mkdirsSync(dataRootPath);
+      } else {
+        await utils.clearDir(dataRootPath);
+      }
+      const dataPath = `${dataRootPath}/${Date.now()}`;
+      fs.mkdirsSync(dataPath);
+
+      // ==========================================
+      // Increases the Mocha timeout to allow more time to
+      // download the test server, if required.
+      // ==========================================
+      if (mochaInstance) {
+        if (!mochaInstance.timeout || !_.isFunction(mochaInstance.timeout)) {
+          throw new Error(
+            `The "mocha" parameter passed to the "mockMongoose(...)" method ` +
+              `doesn't seems to be of the correct type. Make sure the function in which you ` +
+              `call "mockMongoose(...)" is itself a *regular* function, not an *arrow* function. ` +
+              `Have a look at https://github.com/mochajs/mocha/issues/2018 for more infos.`
+          );
+        }
+
+        mochaInstance.timeout(120000);
+      }
+
+      // Voir https://www.npmjs.com/package/mongodb-memory-server pour les options
+      const memoryServerOption: any = {
+        instance: {
+          dbPath: dataPath // by default create in temp directory,
+        },
+
+        binary: {
+          version: mongoServerVersion ? mongoServerVersion : 'latest', // by default 'latest'
+          downloadDir: downloadDirPath // by default node_modules/.cache/mongodb-memory-server/mongodb-binaries
+        },
+        debug: false
+      };
+
+      if (useReplSet) {
+        const replSetOptions: any = {
+          ...memoryServerOption,
+          replSet: { count: 3 }
+        };
+        this.mongoMemServer = await MongoMemoryReplSet.create(replSetOptions);
+      } else {
+        // Create mock
+        this.mongoMemServer = await MongoMemoryServer.create(memoryServerOption);
+      }
+    }
+    return this.mongoMemServer;
+  }
+
+  /**
+   * Drop all mocked Mongo databases.
+   *
+   */
+  public async dropMockedDatabases(): Promise<void> {
+    if (this.mongoMemServer) {
+      await mongoose.disconnect();
+      await this.mongoMemServer.stop();
+      this.mongoMemServer = null;
+    }
+  }
+
+  public async getMockedServerPort(): Promise<number> {
+    const mongooseConnection = mongoose[this.mockgosseMockedFlag];
+    if (mongooseConnection && this.mongoMemServer && !this.useReplSet) {
+      return (this.mongoMemServer as MongoMemoryServer).instanceInfo.port;
+    }
+    if (mongooseConnection && this.mongoMemServer && this.useReplSet) {
+      const servers = (this.mongoMemServer as MongoMemoryReplSet).servers;
+      let port = null;
+      for (const serv of servers) {
+        if (serv.instanceInfo.instance.isInstancePrimary) {
+          port = serv.instanceInfo.port;
+          break;
+        }
+      }
+      return port;
+    }
+
+    return null;
+  }
+
+  /**
+   * Validates if an object is a Mongoose
+   * error.
+   */
+  public isMongooseError(obj: any): boolean {
+    if (_.isEmpty(obj)) {
+      return false;
+    }
+
+    if (_.isEmpty(obj.errors) && 'kind' in obj && 'path' in obj && 'message' in obj) {
+      return true;
+    }
+
+    Object.keys(obj.errors).forEach(errorKey => {
+      const errorObject = obj.errors[errorKey];
+
+      if (!('kind' in errorObject) || !('path' in errorObject) || !('message' in errorObject)) {
+        return false;
+      }
+      return true;
+    });
+    return true;
+  }
+
+  /**
+   * Validates if an object is a plain
+   * Mongo error.
+   */
+  public isPlainMongoError(errorObject: any): boolean {
+    if (_.isEmpty(errorObject)) {
+      return false;
+    }
+
+    if (
+      !('code' in errorObject) ||
+      !('name' in errorObject) ||
+      !('errmsg' in errorObject) ||
+      !('message' in errorObject)
+    ) {
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * 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".
+   */
+  public convertMongoOrMongooseErrorToApiError(err: any, publicMessage: string): ApiErrorAndInfo | any {
+    if (!err) {
+      return createServerError('Empty error object');
+    }
+
+    let errClean = err;
+
+    // ==========================================
+    // Plain Mongo error
+    // ==========================================
+    if (this.isPlainMongoError(errClean)) {
+      // ==========================================
+      // Duplicate key error?
+      // We create an error with a "Conflit" http status
+      // code.
+      // ==========================================
+      if (errClean.code === constants.mongo.mongoErrorCodes.DUPLICATE_KEY) {
+        return createError(globalConstants.errors.apiGeneralErrors.codes.DUPLICATE_KEY, publicMessage)
+          .httpStatus(HttpStatusCodes.CONFLICT)
+          .publicMessage(publicMessage)
+          .logLevel(LogLevel.INFO)
+          .logStackTrace(false)
+          .build();
+      }
+
+      // ==========================================
+      // Unmanaged Mongo error, we return it as is.
+      // ==========================================
+      return errClean;
+    }
+    if (this.isMongooseError(errClean)) {
+      // ==========================================
+      // Mongoose error
+      // ==========================================
+      if (_.isEmpty(errClean.errors)) {
+        // ==========================================
+        // Invalid id
+        // ==========================================
+        if (
+          errClean.kind === constants.mongo.mongoose.errorKinds.OBJECT_ID &&
+          errClean.name === constants.mongo.mongoose.errorNames.CAST_ERROR
+        ) {
+          throw createNotFoundError('Invalid ObjectId id', publicMessage);
+        } else {
+          const error = errClean;
+          errClean = {
+            errors: [error]
+          };
+        }
+      }
+
+      let errorDetails: IApiError[];
+      if (errClean.errors && !_.isEmpty(errClean.errors)) {
+        errorDetails = [];
+        Object.keys(errClean.errors).forEach(errorKey => {
+          const errorMessage = errClean.errors[errorKey];
+
+          const errorDetail: IApiError = {
+            code: errorMessage.kind,
+            target: errorMessage.path,
+            message: errorMessage.message
+          };
+          errorDetails.push(errorDetail);
+        });
+      }
+      throw createInvalidParameterError(publicMessage, errorDetails);
+    } else {
+      // ==========================================
+      // Not a Mongo or Mongoose error, we return it
+      // as is.
+      // ==========================================
+      return errClean;
+    }
+  }
+
+  /**
+   * Converts a Mongoose Document to a plain Pojo.
+   */
+  public convertMongooseDocumentToPlainObject<T>(document: T & mongoose.Document): T {
+    if (!document) {
+      return document;
+    }
+
+    const pojo: T = document.toObject() as T;
+
+    // ==========================================
+    // Converts the "_id" property to "id"
+    // ==========================================
+    // tslint:disable-next-line:no-string-literal
+    pojo['id'] = pojo['_id'].toString();
+    // tslint:disable-next-line:no-string-literal
+    delete pojo['_id'];
+
+    // ==========================================
+    // Removes the "__v"
+    // ==========================================
+    // tslint:disable-next-line:no-string-literal
+    delete pojo['__v'];
+
+    return pojo;
+  }
+}
+export let mongoUtils: MongoUtils = new MongoUtils();

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

@@ -0,0 +1,140 @@
+// Some way of using chai requires disabling this rule:
+// tslint:disable:no-unused-expression
+
+import { IPaginatedResult } from '@villedemontreal/general-utils';
+import * as chai from 'chai';
+import * as mongoose from 'mongoose';
+import { constants } from '../../config/constants';
+import { mongoUtils } from '../../mongoUtils';
+import { mongoosePaginate } from './index';
+
+const expect = chai.expect;
+
+const authorSchema = new mongoose.Schema({ name: String });
+const authorModel = mongoose.model('Author', authorSchema);
+
+const bookSchema = new mongoose.Schema({
+  title: String,
+  date: Date,
+  author: {
+    type: String,
+    ref: 'Author'
+  }
+});
+
+bookSchema.plugin(mongoosePaginate);
+const bookModel: any = mongoose.model('Book', bookSchema);
+
+describe('plugin pagination', () => {
+  before(async function() {
+    this.timeout(120000);
+
+    // Makes sure Mongoose is mocked, but not in Jenkins as we will start a dedicated mongodb container.
+    const mockedDb = await mongoUtils.mockMongoose(this, constants.testsConfig.mockServer.serverVersion);
+    const connString = mockedDb.getUri();
+    await mongoose.connect(connString, { useNewUrlParser: true });
+  });
+
+  before(async function() {
+    this.timeout(10000);
+    let book;
+    const books: any = [];
+    const date = new Date();
+    return authorModel.create({ name: 'Arthur Conan Doyle' }).then(author => {
+      for (let i = 1; i <= 100; i++) {
+        book = new bookModel({
+          title: 'Book #' + i,
+          date: new Date(date.getTime() + i),
+          author: author._id
+        });
+        books.push(book);
+      }
+      return bookModel.create(books);
+    });
+  });
+
+  it('returns promise', () => {
+    const promise = bookModel.paginate();
+    expect(promise.then).to.be.an.instanceof(Function);
+  });
+
+  it('calls callback', done => {
+    bookModel.paginate({}, {}, (err: Error, result: IPaginatedResult<any>) => {
+      expect(err).to.be.null;
+      expect(result).to.be.an.instanceOf(Object);
+      done();
+    });
+  });
+
+  describe('paginates', () => {
+    it('with criteria', () => {
+      return bookModel.paginate({ title: 'Book #10' }).then((result: IPaginatedResult<any>) => {
+        expect(result.items).to.have.length(1);
+        expect(result.items[0].title).to.equal('Book #10');
+      });
+    });
+    it('with default options (limit=10, lean=false)', () => {
+      return bookModel.paginate().then((result: IPaginatedResult<any>) => {
+        expect(result.items).to.have.length(10);
+        expect(result.items[0]).to.be.an.instanceof((mongoose as any).Document);
+        expect(result.paging.totalCount).to.equal(100);
+        expect(result.paging.limit).to.equal(10);
+        expect(result.paging.offset).to.equal(0);
+      });
+    });
+    it('with offset and limit', () => {
+      return bookModel.paginate({}, { offset: 30, limit: 20 }).then((result: IPaginatedResult<any>) => {
+        expect(result.items).to.have.length(20);
+        expect(result.paging.totalCount).to.equal(100);
+        expect(result.paging.limit).to.equal(20);
+        expect(result.paging.offset).to.equal(30);
+      });
+    });
+    it('with zero limit', () => {
+      return bookModel.paginate({}, { page: 1, limit: 0 }).then((result: IPaginatedResult<any>) => {
+        expect(result.items).to.have.length(0);
+        expect(result.paging.totalCount).to.equal(100);
+        expect(result.paging.limit).to.equal(0);
+      });
+    });
+    it('with select', () => {
+      return bookModel.paginate({}, { select: 'title' }).then((result: IPaginatedResult<any>) => {
+        expect(result.items[0].title).to.exist;
+        expect(result.items[0].date).to.not.exist;
+      });
+    });
+    it('with sort', () => {
+      return bookModel.paginate({}, { sort: { date: -1 } }).then((result: IPaginatedResult<any>) => {
+        expect(result.items[0].title).to.equal('Book #100');
+      });
+    });
+    it('with populate', () => {
+      return bookModel.paginate({}, { populate: 'author' }).then((result: IPaginatedResult<any>) => {
+        expect(result.items[0].author.name).to.equal('Arthur Conan Doyle');
+      });
+    });
+    describe('with lean', () => {
+      it('with default leanWithId=true', () => {
+        return bookModel.paginate({}, { lean: true }).then((result: IPaginatedResult<any>) => {
+          expect(result.items[0]).to.not.be.an.instanceof((mongoose as any).Document);
+          expect(result.items[0].id).to.exist;
+          expect(result.items[0]).to.not.have.property('_id');
+        });
+      });
+      it('with leanWithId=false', () => {
+        return bookModel.paginate({}, { lean: true, leanWithId: false }).then((result: IPaginatedResult<any>) => {
+          expect(result.items[0]).to.not.be.an.instanceof((mongoose as any).Document);
+          expect(result.items[0]).to.not.have.property('id');
+        });
+      });
+    });
+  });
+
+  after(done => {
+    mongoose.connection.db.dropDatabase(done);
+  });
+
+  after(done => {
+    mongoose.disconnect(done);
+  });
+});

package/src/plugins/pagination/index.ts

@@ -0,0 +1,96 @@
+import { IPaginateOptions } from './specs/IPaginateOptions';
+
+function paginate(q: any, options: IPaginateOptions, callback: (error: Error, result: any) => void) {
+  const optionsClean = PaginateBuilder.getOptions((paginate as any).options, options);
+
+  const query = q || {};
+  const promises = PaginateBuilder.executeQueries(this, query, optionsClean);
+
+  return PaginateBuilder.processResult(promises, optionsClean, callback);
+}
+
+/**
+ * @param {Schema} schema
+ */
+
+export function mongoosePaginate(schema: any) {
+  schema.statics.paginate = paginate;
+}
+
+export class PaginateBuilder {
+  private static readonly defaultOptions = Object.freeze({
+    lean: false,
+    leanWithId: true,
+    limit: 10,
+    offset: 0
+  });
+
+  public static getOptions(...options: IPaginateOptions[]): IPaginateOptions {
+    return Object.assign({}, PaginateBuilder.defaultOptions, ...options);
+  }
+
+  public static executeQueries(model: any, query: any, options: IPaginateOptions): [Promise<any[]>, Promise<number>] {
+    const { select, sort, populate, lean, leanWithId, limit, offset } = options;
+    let itemsQuery: any;
+
+    if (leanWithId) {
+      // only to prevent "'leanWithId' is declared but its value is never read"
+    }
+
+    if (limit > 0) {
+      itemsQuery = model
+        .find(query)
+        .select(select)
+        .sort(sort)
+        .skip(offset)
+        .limit(limit)
+        .lean(lean);
+
+      if (populate) {
+        [].concat(populate).forEach(item => itemsQuery.populate(item));
+      }
+    }
+
+    return [itemsQuery && limit > 0 ? itemsQuery.exec() : Promise.resolve([]), model.countDocuments(query).exec()];
+  }
+
+  public static processResult(
+    promises: any[],
+    options: IPaginateOptions,
+    callback: (error: Error, result: any) => void
+  ): Promise<any> {
+    const { lean, leanWithId, limit, offset } = options;
+    return new Promise((resolve, reject) => {
+      Promise.all(promises).then(
+        data => {
+          const items = data[0] as any[];
+          const count = data[1] as number;
+          const result: any = { paging: { limit, offset, totalCount: count } };
+
+          if (lean && leanWithId) {
+            result.items = items.map((doc: any) => {
+              doc.id = String(doc._id);
+              delete doc._id;
+              delete doc.__v;
+              return doc;
+            });
+          } else {
+            result.items = items;
+          }
+
+          if (typeof callback === 'function') {
+            return callback(null, result);
+          }
+
+          resolve(result);
+        },
+        error => {
+          if (typeof callback === 'function') {
+            return callback(error, null);
+          }
+          reject(error);
+        }
+      );
+    });
+  }
+}

package/src/plugins/pagination/specs/IPaginateOptions.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/src/utils/logger.ts

@@ -0,0 +1,53 @@
+import { ILogger, initLogger, LazyLogger, Logger, LoggerConfigs, LogLevel } from '@villedemontreal/logger';
+import { configs } from '../config/configs';
+
+let testingLoggerLibInitialised = false;
+
+/**
+ * Creates a Logger.
+ */
+export function createLogger(name: string): ILogger {
+  // ==========================================
+  // We use a LazyLogger so the real Logger
+  // is only created when the first
+  // log is actually performed... At that point,
+  // our "configs.loggerCreator" configuration
+  // must have been set by the code using our library!
+  //
+  // This pattern allows calling code to import
+  // modules from us in which a logger is
+  // created in the global scope :
+  //
+  // let logger = createLogger('someName');
+  //
+  // Without a Lazy Logger, the library configurations
+  // would at that moment *not* have been set yet
+  // (by the calling code) and an Error would be thrown
+  // because the "configs.loggerCreator" is required.
+  // ==========================================
+  return new LazyLogger(name, (nameArg: string) => {
+    return configs.loggerCreator(nameArg);
+  });
+}
+
+function initTestingLoggerConfigs() {
+  const loggerConfig: LoggerConfigs = new LoggerConfigs(() => 'test-cid');
+  loggerConfig.setLogLevel(LogLevel.DEBUG);
+  initLogger(loggerConfig);
+}
+
+/**
+ * A Logger that uses a dummy cid provider.
+ *
+ * Only use this when running the tests!
+ */
+export function getTestingLoggerCreator(): (name: string) => ILogger {
+  return (name: string): ILogger => {
+    if (!testingLoggerLibInitialised) {
+      initTestingLoggerConfigs();
+      testingLoggerLibInitialised = true;
+    }
+
+    return new Logger(name);
+  };
+}

package/src/utils/testingConfigurations.ts

@@ -0,0 +1,13 @@
+import { configs } from '../config/configs';
+import { getTestingLoggerCreator } from '../utils/logger';
+
+/**
+ * Call this when your need to set
+ * *Testing* configurations to the current
+ * library, without the need for a calling code
+ * to do so.
+ *
+ */
+export function setTestingConfigurations(): void {
+  configs.setLoggerCreator(getTestingLoggerCreator());
+}