Newly Purchased Memories

    mongoose-deep-populate
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/mongoose-deep-populate package

    3.2.0 • Public • Published

    Mongoose plugin to enable population of nested models at any level of depth. Support Mongoose 3.8.x and later. Refer to changelog for breaking changes.

    NPM

    Build Status Code Shelter

    Usage

    Sample usages are based on the following schemas:

    var UserSchema = new Schema({})
     
    var CommentSchema = new Schema({
      user  : {type: Number, ref: 'User'}
    })
     
    var PostSchema = new Schema({
      user    : {type: Number, ref: 'User'},
      comments: [{type: Number, ref: 'Comment'}],
      likes   : [{user: {type: Number, ref: 'User'}}],
      approved: {status: Boolean, user: {type: Number, ref: 'User'}}
    })

    Register plugin

    // CHANGE from 1.x: need to pass in mongoose instance
    var deepPopulate = require('mongoose-deep-populate')(mongoose);
    PostSchema.plugin(deepPopulate, options /* more on options below */);

    Perform population

    On Post model:

     
    // Use callback
    Post.deepPopulate(posts, 'comments.user', function (err, _posts) {
      // _posts is the same instance as posts and provided for convenience
      posts.forEach(function (post) {
        // post.comments and post.comments.user are fully populated
      });
    });
     
    // Use promise
    Post.deepPopulate(posts, 'comments.user').then(...);

    On an instance of Post:

    // Use callback
    post.deepPopulate('comments.user', function (err, _post) {
      // _post is the same instance as post and provided for convenience
    });
     
     
    // Use promise
    post.deepPopulate('comments.user').then(...);

    On Query (returns the same query object to chain):

    Post.find().deepPopulate('comments.user').exec(function (err, posts) { ... });
    Post.findOne().deepPopulate('comments.user').exec(function (err, post) { ... });
    Post.findById(id).deepPopulate('comments.user').exec(function (err, post) { ... });

    Populate multiple paths

    Pass paths in a space- or comma-delimited string:

    post.deepPopulate('user comments.user likes.user approved.user', cb);

    Or use an array of strings:

    post.deepPopulate(['comments.user', 'user', 'likes.user', 'approved.user'], cb);

    Specify options

    Specify whitelist option to ensure only certain paths can be populated. This is to prevent potential performance and security issues if you allow API clients to supply population paths.

    PostSchema.plugin(deepPopulate, {
      whitelist: [
        'user',
        'comments.user'
      ]
    });

    Use the populate option to supply paths with corresponding Mongoose populate options.

    PostSchema.plugin(deepPopulate, {
      populate: {
        'comments.user': {
          select: 'name',
          options: {
            limit: 5
          }
        },
        'approved.user': {
          select: 'name'
        }
      }
    });

    Use rewrite option to rewrite provided paths as well as paths in whitelist and populate. This is useful when you allow API clients to supply population paths (e.g. via query string) and want to make these paths more user-friendly. For example:

    PostSchema.plugin(deepPopulate, {
      rewrite: {
        author: 'user',
        approver: 'approved.user'
      }
    });
     
    // assume the query string is: ?populate=author,approver
    post.deepPopulate(req.query.populate, cb);  
    Overriding options

    You can override the above plugin options when invoking deepPopulate.

    Post.deepPopulate(posts, paths, {
      whitelist: [],
      populate: {},
      rewrite: {}
    }, cb)
     
    post.deepPopulate(paths, {
      whitelist: [],
      populate: {},
      rewrite: {}
    }, cb);
     
    Post.find({}).deepPopulate(paths, {
      whitelist: [],
      populate: {},
      rewrite: {}
    }).exec(cb)

    Test

    The test suite will drop the database each run, so only run it against a test database. To run tests, execute this command where --db is the connection string.

    gulp test --db mongodb://127.0.0.1/mongoose_deep_populate_test_db
    

    Changelog

    v3.2.0

    • [Bug] Support async callback #70

    v3.1.1

    • [Bug] Fix issue custom Promise not work in Mongoose 5

    v3.1.0

    • [Feature] Support Mongoose 5

    v3.0.0

    • [Feature] Return a promise when invoking deepPopulate() on model or model instance.

    v2.0.3

    • [Bug] Fix bug cannot use native ES6 Promise

    v2.0.2

    • [Bug] Fix bug populating when there is a subdocument within a linked document (see #29)

    v2.0.0

    • [Breaking] Need a mongoose instance passed to the function returned by require
    • [Feature] Support mongoose promise provider

    v1.1.0

    • [Feature] Make mongoose a peer dependency to enforce supported versions

    v1.0.2

    • [Bug] Fix bug happening when Mongoose#populate does not infer the expected schema

    v1.0.1

    • [Bug] Apply lean to populated documents

    v1.0.0

    • [Feature] Apply rewrites to whitelist and populate

    v0.0.7

    • [Feature] Add deepPopulate to Query
    • [Feature] Support space delimiter in paths

    v0.0.6

    • [Feature] Support populate options
    • [Feature] Override options per call
    • [Bug] Handle null paths and callback

    v0.0.1

    • Initial release

    License

    MIT

    Install

    npm i mongoose-deep-populate

    DownloadsWeekly Downloads

    5,550

    Version

    3.2.0

    License

    MIT

    Unpacked Size

    38.4 kB

    Total Files

    11

    Last publish

    Collaborators

    • buunguyen