Track revisions of your Sequelize models, revert them to any revision or restore them after being destroyed. Written in TypeScript and can be used with sequelize-typescript.
Sequelize Revision is a fork from Sequelize Paper Trail supporting similar options and providing consistent behavior with following improvements:
- Re-written in TypeScript and support type checks
- Working well with or without sequelize-typescript
- Tracking users for making changes with cls-hooked
- Support JSON data type for storing revisions
- Exclude revision attributes for each model
- Passing revision metadata to operations
- Logging revisions for upsert operations
- Better coverage in unit tests
$ npm install --save sequelize-revision
Sequelize Revision assumes that you already set up your Sequelize connection, for example, like this:
import { Sequelize } from "sequelize";
const sequelize = new Sequelize("sqlite::memory:");
then adding Sequelize Revision is as easy as:
import { SequelizeRevision } from "sequelize-revision";
const sequelizeRevision = new SequelizeRevision(sequelize, options);
const [Revision, RevisionChanges] = sequelizeRevision.defineModels();
which loads the Sequelize Revision library, and the defineModels()
method sets up a Revision
and RevisionChange
models.
Note: If you pass userModel
option to the constructor 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:
sequelizeRevision.trackRevision(Model);
import Sequelize from "sequelize";
import { SequelizeRevision } from "sequelize-revision";
const sequelize = new Sequelize("sqlite::memory:");
const sequelizeRevision = new SequelizeRevision(sequelize, options);
const [Revision, RevisionChanges] = sequelizeRevision.defineModels();
const User = sequelize.define("User", { name: Sequelize.STRING });
sequelizeRevision.trackRevision(User);
Sequelize Revision supports various options that can be passed into the initialization. The following are the default options:
Option | Type | Default Value | Description |
---|---|---|---|
[exclude] | Array | ["id", "createdAt", "updatedAt", "deletedAt", "created_at", "updated_at", "deleted_at", [options.revisionAttribute]] |
Array of global attributes to exclude from the Sequelize Revision. |
[revisionAttribute] | String | "revision" |
Name of the attribute in the table that corresponds to the current revision. |
[revisionIdAttribute] | String | "revisionId" |
Name of the attribute in the RevisionChange model that corresponds to the ID of the Revision model. Attribute name can be modified to "revision_id" by passing [underscoredAttributes] option. |
[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. |
[changeTableName] | String | undefined |
Name of the table that keeps the revision change models. Passed to Sequelize. 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. |
[UUID] | Boolean | false |
The [revisionModel] has id attribute of type UUID for PostgreSQL. |
[underscored] | Boolean | false |
The [revisionModel] and [revisionChangeModel] have "createdAt" and "updatedAt" columns, by default, setting this option to true changes it to "created_at " and "updated_at" . Pass true to [underscoredAttributes] option as well for using underscored attributes to access those columns. |
[underscoredAttributes] | Boolean | false |
The [revisionModel] has "documentId" , and the [revisionChangeModel] has a [defaultAttributes.revisionId] "revisionId , by default, setting this option to true changes it to "document_id" and "revision_id" . |
[userModel] | String | undefined |
Name of the model that stores users in your application. |
[userIdAttribute] | String | "userId" |
Name of the attribute in the RevisionChange model that corresponds to the ID of the User model. Attribute name can be modified to "user_id" by passing [underscoredAttributes] option. |
[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 | undefined |
Name of the name space used with the cls-hooked module. |
[continuationKey] | String | "userId" |
The cls-hooked 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 cls-hooked key that contains the meta data object, from where the metaDataFields are extracted. |
[useJsonDataType] | Boolean | true |
Microsoft SQL Server and old versions of MySQL do not support JSON data type. Setting this option to false changes the data type to TEXT("medium"). |
Attribute | Data Type | Description |
---|---|---|
"id" |
INTEGER | UUID | Primary key of the model. Data type is INTEGER by default, but can be modified to UUID for PostgreSQL by passing [UUID] option. |
"model" |
STRING | Name of the tracked model. |
"document" |
JSON | TEXT("medium") | Attributes of the model after the operation. The entire attributes are saved by default, but can be compresses only to the diff by passing [enableCompression] option. |
"documentId" |
INTEGER | UUID | ID of the tracked document. Attribute name can be modified to "document_id" by passing [underscoredAttributes] option. |
"operation" |
STRING | Name of the operation such as "create" , "update" and "destroy" . |
[revisionAttribute] | INTEGER | Version of the document starting from 1 . The value is incremented every time when the document is created, updated or deleted. Attribute name is configured by [revisionAttribute], default to "revision" . The same value is saved to [revisionAttribute] attribute of the tracked document as well. |
[userIdAttribute] | (ID data type of of the user model) | Foreign key of the user model. Attribute name is configured by [userIdAttribute], default to "userId" and modified to "user_id" by passing [underscoredAttributes] option. |
Attribute | Data Type | Description |
---|---|---|
"id" |
INTEGER | UUID | Primary key of the model. Data type is INTEGER by default, but can be modified to UUID for PostgreSQL by passing [UUID] option. |
"path" |
TEXT | Modified attribute name. |
"document" |
JSON | TEXT("medium") | Modified attributes. |
"diff" |
JSON | TEXT("medium") | Difference of updated attribute, comparing character by character. |
[revisionIdAttribute] | (ID data type of of the Revision model) |
Foreign key of the Revision model. Attribute name is configured by [revisionIdAttribute], default to "revisionId" and modified to "revision_id" by passing [underscoredAttributes] option. |