mongoose-history-plugin

Mongoose plugin that saves documents history in JsonPatch format and SemVer format.

Table of Contents

• Features

• Install

• Use

• Document Methods

  • document.getDiffs(findQuery)
  • document.getDiff(version)
  • document.getVersions(findQuery)
  • document.getVersion(version)
  • document.compareVersions(versionLeft, versionRight)

• Tests

• Contributing

• Legal

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

import mongoose from 'mongoose';
import MongooseHistoryPlugin from 'mongoose-history-plugin';

mongoose.connect('mongodb://localhost/Default');

// Default options
let 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 options
let Schema = mongoose.Schema({ name: 'string', size: 'string' });
Schema.plugin(MongooseHistoryPlugin(options));

// Create a model
let Tank = mongoose.model('tank', Schema);

// Create a document
let small = new Tank({
  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
  .save()
  .then((small) => {
    small.name = 'Small tank';

    // History property is optional by default
    small.__history = {
      event: 'updated',
      user: undefined,
      reason: undefined,
      data: undefined,
      type: undefined,
      method: 'updateTank'
    };

    return small.save();
  })
  .then((small) => {
    // Create another history version
    small.name = 'Smallest tank';

    // History property is optional by default
    small.__history = {
      event: 'updated',
      user: undefined,
      reason: undefined,
      data: undefined,
      type: undefined,
      method: 'updateTank'
    };

    return small.save();
  })
  .then((small) => {
    // All options are optional
    let query = {
      find: {}, // Must be an object
      select: {}, // Must be an object
      sort: '',
      populate: '',
      limit: 20
    };

    // Get the diff histories in JsonDiffPatch format
    small.getDiffs(query).then(console.log);
    /*
    [ 
      { 
        version: '2.0.0',
        diff: { name: ['Small tank', 'Smallest tank'] },
        event: 'updated',
        method: 'updateTank',
        timestamp: 2019-08-24T12:04:15.253Z },
      { 
        version: '1.0.0',
        diff: { name: [ 'Small tank' ] },
        event: 'updated',
        method: 'updateTank',
        timestamp: 2019-08-24T12:04:15.253Z },
      { 
        version: '0.0.0',
        diff: { _id: [ '5d6127bf3a50db72bc8cbed2' ], size: [ 'small' ] },
        event: 'created',
        method: 'newTank',
        timestamp: 2019-08-24T12:04:15.157Z 
      } 
    ]
    */

    // Get a diff history in JsonDiffPatch format
    small.getDiff('1.0.0').then(console.log);

    /*
    { 
      _id: 5d6127bf3a50db72bc8cbed4,
      version: '1.0.0',
      collectionName: 'tank6',
      collectionId: 5d6127bf3a50db72bc8cbed2,
      diff: { name: [ 'Small tank' ] },
      event: 'updated',
      method: 'updateTank',
      timestamp: 2019-08-24T12:04:15.253Z 
    }
    */

    // Get the versions
    small.getVersions(query).then(console.log);
    /*
    [ 
      {
        version: '2.0.0',
        event: 'updated',
        method: 'updateTank',
        timestamp: expect.any(Date),
        object: { name: 'Smallest tank' }
      },
      { 
        version: '1.0.0',
        event: 'updated',
        method: 'updateTank',
        timestamp: 2019-08-24T12:04:15.253Z,
        object: { name: 'Small tank' } 
      },
      { 
        version: '0.0.0',
        event: 'created',
        method: 'newTank',
        timestamp: 2019-08-24T12:04:15.157Z,
        object: { 
          name: 'Small tank',
          _id: '5d6127bf3a50db72bc8cbed2',
          size: 'small' 
        } 
      } 
    ]
    */

    // Get a version
    small.getVersion('1.0.0').then(console.log);
    /*
    { 
      _id: 5d6127bf3a50db72bc8cbed4,
      version: '1.0.0',
      collectionName: 'tank6',
      collectionId: 5d6127bf3a50db72bc8cbed2,
      event: 'updated',
      method: 'updateTank',
      timestamp: 2019-08-24T12:04:15.253Z,
      object: { 
        _id: '5d6127bf3a50db72bc8cbed2',
        size: 'small',
        name: 'Small tank' 
      } 
    }
    */

    // Compare two versions
    small.compareVersions('0.0.0', '1.0.0').then(console.log);
    /*
    { 
      diff: { name: [ 'Small tank' ] },
      left: { _id: '5d6127bf3a50db72bc8cbed2', size: 'small' },
      right: { 
        _id: '5d6127bf3a50db72bc8cbed2',
        size: 'small',
        name: 'Small tank' 
      } 
    }
    */
  });

small
  .remove()
  .then((small) => {
    small.__history = {
      event: 'removed',
      user: undefined,
      reason: undefined,
      data: undefined,
      type: undefined,
      method: 'delete'
    };

    return small.remove();
  })
  .then((small) => {
    // All options are optional
    let query = {
      find: {}, // Must be an object
      select: {}, // Must be an object
      sort: '',
      populate: '',
      limit: 20
    };

    // Get the diff histories in JsonDiffPatch format
    small.getDiffs(query).then(console.log);

    // Get a diff history in JsonDiffPatch format
    small.getDiff('2.0.0').then(console.log);

    // Get the versions
    small.getVersions(query).then(console.log);

    // Get a version
    small.getVersion('2.0.0').then(console.log);

    // Compare two versions
    // In the case of delete, the diff is empty because the object is not changed.
    small.compareVersions('1.0.0', '2.0.0').then(console.log);
  });

// Add the plugin to many schemas with a single history collection
let plugin = MongooseHistoryPlugin(options);
Schema.plugin(plugin);
AnotherSchema.plugin(plugin);

// Add the plugin with a dedicated history collection for every schema
Schema.plugin(
  MongooseHistoryPlugin(
    Object.assign({}, options, { modelName: 'collectionName_versions' })
  )
);
AnotherSchema.plugin(
  MongooseHistoryPlugin(
    Object.assign({}, options, { modelName: 'anotherCollectionName_versions' })
  )
);

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