Sequelize-paper-trail-3 NPM

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. Record the user who created the version.

Sequelize Paper Trail - Installation - Usage - Example - User Tracking - Options - Default options - Options documentation - Limitations

Installation

npm install --save sequelize-paper-trail-3
# or with yarn:
# yarn add sequelize-paper-trail-3

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

Usage

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

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

then adding Sequelize Paper Trail is as easy as:

const PaperTrail = require('sequelize-paper-trail-3').init(sequelize, options);
PaperTrail.defineModels();

which loads the Paper Trail library, and the defineModels() method sets up a Revisions and RevisionHistory table.

Note: If you pass userModel option to init in order to enable user tracking, userModel should be setup before defineModels() is called.

Then for each model that you want to keep a paper trail you simply add:

Model.hasPaperTrail();

hasPaperTrail returns the hasMany association to the revisionModel so you can keep track of the association for reference later.

Example

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

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

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

User.Revisions = User.hasPaperTrail();

User Tracking

There are 2 steps to enable user tracking, ie, recording the user who created a particular revision. 1. Enable user tracking by passing userModel option to init, with the name of the model which stores users in your application as the value.

const options = {
  /* ... */
  userModel: 'user',
};

Pass the id of the user who is responsible for the database operation to sequelize-paper-trail-3 either by sequelize options or by using continuation-local-storage.

Model.update({
  /* ... */
}, {
  userId: user.id
}).then(() {
  /* ... */
});

const createNamespace = require('continuation-local-storage').createNamespace;
const session = createNamespace('my session');

session.set('userId', user.id);

Model.update({
  /* ... */
}).then(() {
  /* ... */
});

To enable continuation-local-storage set continuationNamespace in initialization options. Additionally, you may also have to call .run() or .bind() on your cls namespace, as described in the docs.

Disable logging for a single call

To not log a specific change to a revisioned object, just pass a noPaperTrail with a truthy (true, 1, ' ') value.

const instance = await Model.findOne();
instance.update({ noPaperTrail: true }).then(() {
  /* ... */
});

Options

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

Default options

// Default options
const options = {
  exclude: [
    'id',
    'createdAt',
    'updatedAt',
    'deletedAt',
    'created_at',
    'updated_at',
    'deleted_at'
  ],
  revisionAttribute: 'revision',
  revisionModel: 'Revision',
  revisionChangeModel: 'RevisionChange',
  enableRevisionChangeModel: false,
  UUID: false,
  underscored: false,
  underscoredAttributes: false,
  defaultAttributes: {
    documentId: 'documentId',
    revisionId: 'revisionId'
  },
  enableCompression: false,
  enableMigration: false,
  enableStrictDiff: true,
  continuationKey: 'userId',
  belongsToUserOptions: undefined,
  metaDataFields: undefined,
  metaDataContinuationKey: 'metaData',
  documentFieldType: 'mysql'
};

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.
tableName	String	undefined	Name of the table that keeps the revision models. Passed to Sequelize. Necessary in Sequelize 5+ when underscored is true and the table is camelCase or PascalCase.
revisionChangeModel	String	'RevisionChange'	Name of the model that tracks all the attributes that have changed during each create and update call.
enableRevisionChangeModel	Boolean	false	Disable the revision change model to save space.
revisionChangeTableName	String	undefined	Name of the table that keeps the revision change models. Passed to Sequelize. Necessary in Sequelize 5+ when underscored is true and the table is camelCase or PascalCase.
UUID	Boolean	false	The revisionModel has id attribute of type UUID for postgresql.
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' }
userModel	String		Name of the model that stores users in your.
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'`
continuationNamespace	String		Name of the name space used with the continuation-local-storage module.
continuationKey	String	'userId'	The continuation-local-storage key that contains the user id.
belongsToUserOptions	Object	undefined	The options used for belongsTo between userModel and Revision model
metaDataFields	Object	undefined	The keys that will be provided in the meta data object. { key: isRequired (boolean)} format. Can be used to privovide additional fields - other associations, dates, etc to the Revision model
metaDataContinuationKey	String	'metaData'	The continuation-local-storage key that contains the meta data object, from where the metaDataFields are extracted.
documentFieldType	String	'mysql' - 'legacy', 'postgres', 'mysql'	Changes the type of field 'document' what will be created. 'legacy' produces a `TEXT`, 'postgres' a `JSONB` and 'mysql' a `JSON` field.