Sequelize Paper Trail

Track changes to your models, for auditing or versioning. See how a model looked at any stage in its lifecycle, revert it to any version, or restore it after it has been destroyed.

Table of Contents

• Installation
• Usage
  • Example
• Options
• Local development and running tests
• Support
• Contributing
• Author
• Thanks
• Links

Installation

npm install --save sequelize-paper-trail

Usage

Sequelize Paper Trail assumes that you already set up your Sequelize connection, for example, like this:

var Sequelize = require('sequelize');
var sequelize = new Sequelize('database', 'username', 'password');

then adding Sequelize Paper Trail is as easy as:

var PaperTrail = require('sequelize-paper-trail')(sequelize, options={});
PaperTrail.defineModels();

which loads the Paper Trail library, and the defineModels() method sets up a Revisions and RevisionHistory table. Then for each model that you want to keep a paper trail you simply add:

Model.hasPaperTrail();

Example

var Sequelize = require('sequelize');
var sequelize = new Sequelize('database', 'username', 'password');

var PaperTrail = require('sequelize-paper-trail')(sequelize, options || {});
PaperTrail.defineModels();

var User = sequelize.define('User', {
  username: Sequelize.STRING,
  birthday: Sequelize.DATE
});

User.hasPaperTrail();

Options

Paper Trail supports various options that can be passed into the initialization. The following are the default options:

Default options

// Default options
var options = {
  exclude: [
    'id',
    'createdAt',
    'updatedAt',
    'deletedAt',
    'created_at',
    'updated_at',
    'deleted_at'
  ],
  revisionAttribute: 'revision',
  revisionModel: 'Revision',
  revisionChangeModel: 'RevisionChange',
  UUID: false,
  underscored: false,
  underscoredAttributes: false,
  defaultAttributes: {
    documentId: 'documentId',
    revisionId: 'revisionId'
  },
  userModel: 'User',
  enableCompression: false,
  enableMigration: true,
  enableStrictDiff: true
};

Options documentation

| Option | Type | Default Value | Description | |-------------------------|---------|-----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [debug] | Boolean | false | Enables logging to the console. | | [exclude] | Array | ['id', 'createdAt', 'updatedAt', 'deletedAt', 'created_at', 'updated_at', 'deleted_at', [options.revisionAttribute]] | Array of global attributes to exclude from the paper trail. | | [revisionAttribute] | String | 'revision' | Name of the attribute in the table that corresponds to the current revision. | | [revisionModel] | String | 'Revision' | Name of the model that keeps the revision models. | | [revisionChangeModel] | String | 'RevisionChange' | Name of the model that tracks all the attributes that have changed during each create and update call. | | [underscored] | Boolean | false | The [revisionModel] and [revisionChangeModel] have 'createdAt' and 'updatedAt' attributes, by default, setting this option to true changes it to 'created_at' and 'updated_at'. | | [underscoredAttributes] | Boolean | false | The [revisionModel] has a [defaultAttribute] 'documentId', and the [revisionChangeModel] has a [defaultAttribute] 'revisionId, by default, setting this option to true changes it to 'document_id' and 'revision_id'. | | [defaultAttributes] | Object | { documentId: 'documentId', revisionId: 'revisionId' } | | | [UUID] | Boolean | false | (only for Postgres) uses UUID's instead of id's. | | [enableCompression] | Boolean | false | Compresses the revision attribute in the [revisionModel] to only the diff instead of all model attributes. | | [enableMigration] | Boolean | false | Automatically adds the [revisionAttribute] via a migration to the models that have paper trails enabled. | | [enableStrictDiff] | Boolean | true | Reports integers and strings as different, e.g. 3.14 !== '3.14' |

Demo

A working demo application is available at

https://github.com/nielsgl/sequelize-paper-trail-example

Local development and running tests

Clone repo:

git clone [email protected]:nielsgl/sequelize-paper-trail.git

Install dependencies:

npm install

Run test script:

npm test

Note: the current test suite is very limited in coverage.

Support

Please use:

• GitHub's issue tracker
• Tweet directly to ``

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Author

© Niels van Galen Last – @nielsgl – [email protected]
Distributed under the MIT license. See LICENSE for more information.
https://github.com/nielsgl/sequelize-paper-trail

Thanks

This project was inspired by:

• Sequelize-Revisions
• Paper Trail

Links