README.md
[](https://travis-ci.org/mimani/mongoose-diff-history)
[](https://www.npmjs.com/package/mongoose-diff-history)
[](https://www.codacy.com/app/mimani-saurabh/mongoose-diff-history)
[](https://codeclimate.com/github/mimani/mongoose-diff-history)
[](https://codeclimate.com/github/mimani/mongoose-diff-history/coverage)
# mongoose-diff-history
Stores and Manages all the differences and versions, any Mongo collection goes through it's lifecycle.
## Installation
---
### npm
```sh
npm install mongoose-diff-history
```
## Operation
---
Each update will create a history record with [jsonDiff](https://github.com/benjamine/jsondiffpatch) of the change. This helps in tracking all the changes happened to an object from the beginning.
Following will be the structure of the diff history being saved:
diff Collection schema:
```
_id : mongo id of the diff object
collectionName: Name of the collection for which diff is saved
collectionId : Mongo Id of the collection being modified
diff: diff object
user: User who modified
reason: Why the collection is modified
createdAt: When the collection is modified
_v: version
```
## Usage
---
Use as you would any Mongoose plugin:
```js
var mongoose = require('mongoose'),
diffHistory = require('mongoose-diff-history/diffHistory'),
schema = new mongoose.Schema({ ... });
schema.plugin(diffHistory.plugin);
```
The plugin also has an omit option which accepts either a string or array. This will omit the given
keys from history. Follows dot syntax for deeply nested values.
```js
const mongoose = require('mongoose');
const diffHistory = require('mongoose-diff-history/diffHistory');
const schema = new mongoose.Schema({
someField: String,
ignoredField: String,
some: {
deepField: String
}
});
schema.plugin(diffHistory.plugin, { omit: ['ignoredField', 'some.deepField'] });
```
## Helper Methods
---
You can get all the histories created for an object using following method:
```js
const diffHistory = require('mongoose-diff-history/diffHistory');
const expandableFields = ['abc', 'def'];
diffHistory.getHistories('modelName', ObjectId, expandableFields, function (
err,
histories
) {});
// or, as a promise
diffHistory
.getHistories('modelName', ObjectId, expandableFields)
.then(histories => {})
.catch(console.error);
```
If you just want the raw histories return with json diff patches:
```js
const diffHistory = require('mongoose-diff-history/diffHistory');
diffHistory.getDiffs('modelName', ObjectId, function (err, histories) {});
// or, as a promise
diffHistory
.getDiffs('modelName', ObjectId)
.then(histories => {})
.catch(console.error);
// with optional query parameters:
diffHistory
.getDiffs('modelName', ObjectId, { select: 'diff user' })
.then(histories => {})
.catch(console.error);
```
You can get an older version of the object using following method:
```js
const diffHistory = require('mongoose-diff-history/diffHistory');
diffHistory.getVersion(mongooseModel, ObjectId, version, function (
err,
oldObject
) {});
// or, as a promise
diffHistory
.getVersion(mongooseModel, ObjectId, version)
.then(oldObject => {})
.catch(console.error);
```
You can also use Mongoose query options with getVersion like so:
```js
const diffHistory = require('mongoose-diff-history/diffHistory');
diffHistory.getVersion(
mongooseModel,
ObjectId,
version,
{ lean: true },
function (err, oldObject) {}
);
// or, as a promise
diffHistory
.getVersion(mongooseModel, ObjectId, version, { lean: true })
.then(oldObject => {})
.catch(console.error);
```
## Example
---
I have created an [example](https://github.com/mimani/mongoose-diff-history/tree/master/example) express service (documentation [here](https://github.com/mimani/mongoose-diff-history/blob/master/example/README.md)), demonstrating this plugin via an simple employee schema, checkout `example` directory in this repo.
## Contributing
---
This project is now using [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) syntax for commit messages, to allow for easier updates in change logs & release notes. Please follow these conventions in your commits.