Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/buunguyen/mongoose-deep-populate
Mongoose plugin to enable deep population of nested models ⛺
https://github.com/buunguyen/mongoose-deep-populate
mongoose mongoose-plugin population
Last synced: about 2 months ago
JSON representation
Mongoose plugin to enable deep population of nested models ⛺
- Host: GitHub
- URL: https://github.com/buunguyen/mongoose-deep-populate
- Owner: buunguyen
- License: mit
- Created: 2014-11-04T01:08:15.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2020-07-15T20:10:08.000Z (about 4 years ago)
- Last Synced: 2024-05-17T06:02:09.177Z (4 months ago)
- Topics: mongoose, mongoose-plugin, population
- Language: JavaScript
- Homepage:
- Size: 80.1 KB
- Stars: 469
- Watchers: 16
- Forks: 44
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-vietnamese - Mongoose plugin to enable deep population of nested models - deep-populate.svg?style=flat-square) (Podcast)
- annals-of-awesome - Resource - Plugin that enables multi level population of nested models from mongoDB using mongoose (Persistence / Angular)
README
Mongoose plugin to enable population of nested models at any level of depth. Support **Mongoose 3.8.x** and later. Refer to [changelog](https://github.com/buunguyen/mongoose-deep-populate#changelog) for breaking changes.
[](https://www.npmjs.com/package/mongoose-deep-populate)
[](https://travis-ci.org/buunguyen/mongoose-deep-populate)
[](https://www.codeshelter.co/)
### Usage
Sample usages are based on the following schemas:
```javascript
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
```javascript
// 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:
```javascript
// 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`:
```javascript
// 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):
```javascript
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:
```javascript
post.deepPopulate('user comments.user likes.user approved.user', cb);
```
Or use an array of strings:
```javascript
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.
```javascript
PostSchema.plugin(deepPopulate, {
whitelist: [
'user',
'comments.user'
]
});
```
Use the `populate` option to supply paths with corresponding [Mongoose populate options](http://mongoosejs.com/docs/api.html#model_Model.populate).
```javascript
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:
```javascript
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`.
```javascript
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