Sequelize Central Log

Maintain Sequelize Model change history in a central table. This is highly configurable and supports composite primary keys ( up to 3 for now). Written in Typescript and provides typing.

Can be used with Sequelize-typescript as well.

Install
Usage
Options
Support
Author
Thanks

Install

To install run the following npm command:

npm install sequelize-central-log

Usage

Setup

Sequelize Central log needs your initated sequelize connection for example:

import { Sequelize } from 'sequelize';

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

Import Sequelize Central Log, create a new instance by passing in your sequelize instance and options ( see below ) as well as defineModels() to setup the revision model, which should be done after initalizing them in sequelize.

import { SequelizeCentralLog } from 'sequelize-central-log';
const options = {...}; // define options from list below
const centralLog = new SequelizeCentralLog(sequelize, options);
const Revision = centralLog.defineModels(); // returns your revision model instance for querying

This sets up your central log (revision table) and returns the table instance to be used for querying.

Lastly for each model you want to track history on call the addHistory function passing in the model.

centralLog.addHistory(sequelize.model('ModelName'));

// For those that define their models as a class, you can simply pass that class in.
import SequelizeModelClass from '../sequelize_model_class';
centralLog.addHistory(SequelizeModelClass);

The hasHistory function will add a hasMany association from the model to the revision model so you can include and have revisions returned with your results.

Excluding Columns

There are two ways to exclude columns from being tracked in the revision history table.

You can pass them in as a string array your options when instantiating the Sequelize Central Log ( this will override the defaults). See options below for the defaults. You can override the defaults by passing an empty array.

const centralLog = new SequelizeCentralLog(sequelizeDB, { exclude: ['column1', 'column2']});

or you can pass them in per model as a string array when adding the history to the sequelize model:

centralLog.addHistory(ModelA, {exclude: ['columnModelA']});
centralLog.addHistory(ModelB);

General exclude and model level exclude are added together on the model level. So a globally excluded id column will apply to every model while a column excluded when adding history to the model will be excluded only for that table.

Example based on the setup above:

Table A will have the columns id and columnModelA excluded.
Table B will only have the id column excluded.

Composite Keys

You can use composite keys while tracking history. Current limitations are limited to 2 keys currently. The second key is tracked in a column added to the revision table modelId2, (which you can override the column name). A Third Composite key works the same with a default of modelId3.

This is configured by passing the option when creating the log and then per model.

const centralLog = new SequelizeCentralLog(sequelizeDB, {useCompositeKeys: true});
centralLog.addHistory(Model, { hasCompositeKey: true });

/**
 * For a Third Composite Key
 */
centralLog.addHistory(Model, { hasCompositeKey: true, thirdCompositeKey: true });

This will still create the hasMany association on the model and will pull back the revisions. YAY!

Tracking Author

You can track the author of the revision by passing the user model as an option when creating the SequelizeCentralLog instance( model must be initialized in sequelize first).

const centralLog = SequelizeCentralLog(sequelizeDB, {userModel: User});

This will create a foreign key ( allowed null ) column on the revision table pointing to the id column in the user model.

There are two ways to set the userid when tracking the author. You can use a namespace (cls-hooked) or pass a userId as an option on the sequelize query. The option passed on the query will override the namespace if you want to for some reason.

import { createNamespace } from 'cls-hooked';

const nameSpace = createNamespace('amespaceName');

// don't forget to call run on the namespace.
nameSpace.run(() => {
  nameSpace.set('keyName', userID);
  // somehwere in your async chain..
  Model.update(...{});
  Model.create(...{});
});

/**
 * OR
 */

Model.update({...values}, {userId: userID});

Bulk Actions

By default Sequelize Central Log will track bulk actions. You can disable this on a per model basis.

CentralLog.hasHistory(Model, {disableHistoryAutoHook: true});

Options

Option	Type	Default Value	Description
[attributeModelId	String	modelID	column name for primary key of model tracked.
[attributeModelId2	String	modelID2	column name for the 2nd primary key for a composite key.
[attributeRevision]	String	revision	column name added to model being tracked with hasHistory()
[attributeRevisionModel]	String	Revision	revision table sequelize model name
[attributeRevisionModelTableName]	String	Revision	revision table name in database, if different.
[attributeUserId]	String	userId	column name on revision table for the user id.
[continuationKey]	String	userId	continuation key to set / get when tracking author.
[continuationNamespace]	String	NULL	continuation namespace name.
[debug]	Boolean	false	Enables console logging.
[enableMigration]	Boolean	false	Enables Database sync of only the revision model so the table will be created in database.
[enableRevisionAttributeMigration]	Boolean	false	Enables addHistory to add the revision column on the model in the database.
[exclude]	Array(string)	['id', 'createdAt', 'updatedAt', 'deletedAt', 'created_at', 'updated_at', 'deleted_at', [options.revisionAttribute]]	Array of global attributes to exclude from the revision log.
[freezeTableName]	Boolean	false	Adds revision model level option of freeze table name.
[primaryKeyType]	DataType	DataTypes.Integer	Allows Defining something Other than Integer as the Column Type. This uses Sequelizes DataTypes Field.
[trackFullModel]	Boolean	false	Adds another column (current) to the table and tracks the full non excluded current values ( not just what changed ).
[useCompositeKeys]	Boolean	false	Denotes that composite keys are used in your models and adds the attributeModelId2 column to the revision table.
[underscored]	Boolean	false	Adds revision model level option of underscored column names ( created_at ).
[userModel]	Model Object	NULL	Sequelize Model instance for the user.

Support

Please use GitHub's Issue Tracker

Author

Distributed under the MIT license. See LICENSE for more information.

Thanks

This project was inspired by:

Sequelize Paper Trail

duncanhoggan/sequelize-central-log