Sequelize Revision

TIPS | Troubleshooting | Code of Conduct | Contributing | Security Policy | Changelog

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

Installation

$ npm install --save sequelize-revision

Usage

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);

Example

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);

Options

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

Options documentation

| 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"). |

Sequelize Models

Revision

| 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. |

RevisionChnage

| 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. |