mongoose-history-plugin
Mongoose plugin that saves documents history in JsonPatch format and SemVer format.
Table of Contents
Features
- Multiple history collections or one shared collection for the schemas
- Reference an account within the saved history
- Reference the user that performes the event within the saved history
- Save history for embedded documents
- Save history for populated fields
- Get diffs in JsonPatch format
- Get documents state for each version
- Compare two different versions
Install
This is a Node.js module available through the npm registry. Installation is done using the npm install
command:
If using mongoose 4.x.x remove will only save if calling model.remove. Mongoose 5.x now applies middleware hooks for remove on both schema and model.
See https://mongoosejs.com/docs/middleware.html
$ npm install mongoose-history-plugin
Use
;; mongoose; // Default optionslet options = mongoose: mongoose // A mongoose instance userCollection: 'users' // Colletcion to ref when you pass an user id userCollectionIdType: false // Type for user collection ref id, defaults to ObjectId accountCollection: 'accounts' // Collection to ref when you pass an account id or the item has an account property accountCollectionIdType: false // Type for account collection ref id, defaults to ObjectId userFieldName: 'user' // Name of the property for the user accountFieldName: 'account' // Name of the property of the account if any timestampFieldName: 'timestamp' // Name of the property of the timestamp methodFieldName: 'method' // Name of the property of the method collectionIdType: false // Cast type for _id (support for other binary types like uuid) defaults to ObjectId ignore: // List of fields to ignore when compare changes noDiffSave: false // If true save event even if there are no changes noDiffSaveOnMethods: 'delete' // If a method is in this list, it saves history even if there is no diff. noEventSave: true // If false save only when __history property is passed modelName: '__histories' // Name of the collection for the histories embeddedDocument: false // Is this a sub document embeddedModelName: '' // Name of model if used with embedded document // If true save only the _id of the populated fields // If false save the whole object of the populated fields // If false and a populated field property changes it triggers a new history // You need to populate the field after a change is made on the original document or it will not catch the differences ignorePopulatedFields: true; // Add the plugin to the schema with default optionslet Schema = mongoose;Schema; // Create a modellet Tank = mongoose; // Create a documentlet small = size: 'small' // History property is optional by default __history: event: 'created' user: undefined // An object id of the user that generate the event reason: undefined data: undefined // Additional data to save with the event type: undefined // One of 'patch', 'minor', 'major'. If undefined defaults to 'major' method: 'newTank' // Optional and intended for method reference ;small ; small ; // Add the plugin to many schemas with a single history collectionlet plugin = ;Schema;AnotherSchema; // Add the plugin with a dedicated history collection for every schemaSchema;AnotherSchema;
Document Methods
document.getDiffs([findQuery])
Returns an array of all the histories of the document. You can pass a options object that will be passed to a collection find method.
The returned objects within the array have the next shape:
version // The version of the document according to the SemVer format diff // Changes made in this version diffed against the previous version and according to the JsonPatch format event // The event that create this version if any method // The name of the method that create this version if any timestamp // The timestamp in which this version was created
document.getDiff(version)
Returns the version history for this document.
The returned object has the next shape:
_id // ObjectId for this history version // The version of the document according to the SemVer format collectionName // Name of the collection that belongs to this document collectionId // ObjectId of the document diff // Changes made in this version diffed against the previous version and according to the JsonPatch format event // The event that create this version if any method // The name of the method that create this version if any timestamp // The timestamp in which this version was created
document.getVersions([findQuery])
Returns an array of all the versions of the document. You can pass a options object that will be passed to a collection find method.
The returned objects within the array have the next shape:
version // The version of the document according to the SemVer format event // The event that create this version if any method // The name of the method that create this version if any timestamp // The timestamp in which this version was created object // Object with the properties changed in this version diffed against the previous version
document.getVersion(version)
Returns the document as it was at the time of this version.
The returned object has the next shape:
_id // ObjectId for this history version // The version of the document according to the SemVer format collectionName // Name of the collection that belongs to this document collectionId // ObjectId of the document event // The event that create this version if any method // The name of the method that create this version if any timestamp // The timestamp in which this version was created object // The complete object as it was at this version
document.compareVersions(versionLeft, versionRight)
Returns the differences between two versions of the document.
The returned object has the next shape:
diff // The differences between the two versions according to the JsonPatch format left // The document as it was at the left version right // The document as it was at the right version
Tests
npm test
For development use npm dev:test
Contributing
- Use prettify and eslint to lint your code.
- Add tests for any new or changed functionality.
- Update the readme with an example if you add or change any functionality.
Legal
Author: Masquerade Circus. License Apache-2.0