# sequelize-paper-trail-scalio

> Track changes to your Sequelize models data. Perfect for auditing or versioning.

Latest version **0.0.2** (published 2017-01-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install sequelize-paper-trail-scalio
pnpm add sequelize-paper-trail-scalio
yarn add sequelize-paper-trail-scalio
bun add sequelize-paper-trail-scalio
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.2 |
| Published | 2017-01-20 |
| First published | 2017-01-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=5.0.0 <6 |
| Dependencies | 5 |
| Known vulnerabilities | 0 (+10 in 2 direct dependencies) |
| Install scripts | no |
| Author | Niels van Galen Last |
| Maintainers | scalio |
| Keywords | sequelize, sequelize-plugin, audit, paper trail, audit trail, trail, revision, revisions, versioning, nodejs |

## Links

- npm: https://www.npmjs.com/package/sequelize-paper-trail-scalio
- Repository: https://github.com/scalio/sequelize-paper-trail
- Homepage: https://github.com/scalio/sequelize-paper-trail#readme
- Issues: https://github.com/scalio/sequelize-paper-trail/issues
- npm.io page: https://npm.io/package/sequelize-paper-trail-scalio

## Dependencies (5)

- [diff](https://npm.io/package/diff.md) ^2.2.2
- [lodash](https://npm.io/package/lodash.md) ^4.11.1
- [deep-diff](https://npm.io/package/deep-diff.md) ^0.3.4
- [sequelize](https://npm.io/package/sequelize.md) ^3.21.0
- [continuation-local-storage](https://npm.io/package/continuation-local-storage.md) ^3.1.7

## Recent versions

- 0.0.2 (latest) — 2017-01-20

## README

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


<!-- [![NPM](https://nodei.co/npm/sequelize-paper-trail.png?downloads=true)](https://nodei.co/npm/sequelize-paper-trail/) -->

[![node-version](https://img.shields.io/node/v/sequelize-paper-trail.svg)](https://www.npmjs.org/package/sequelize-paper-trail)
[![npm-version](https://img.shields.io/npm/v/sequelize-paper-trail.svg)](https://www.npmjs.org/package/sequelize-paper-trail)
[![David](https://img.shields.io/david/nielsgl/sequelize-paper-trail.svg?maxAge=3600)]()
[![David](https://img.shields.io/david/dev/nielsgl/sequelize-paper-trail.svg?maxAge=3600)]()

[![GitHub release](https://img.shields.io/github/release/nielsgl/sequelize-paper-trail.svg)](https://www.npmjs.org/package/sequelize-paper-trail)
[![GitHub tag](https://img.shields.io/github/tag/nielsgl/sequelize-paper-trail.svg)](https://www.npmjs.org/package/sequelize-paper-trail)
[![GitHub commits](https://img.shields.io/github/commits-since/nielsgl/sequelize-paper-trail/1.2.0.svg)]()
[![npm-downloads](https://img.shields.io/npm/dt/sequelize-paper-trail.svg)](https://www.npmjs.org/package/sequelize-paper-trail)

[![license](https://img.shields.io/github/license/nielsgl/sequelize-paper-trail.svg)](https://github.com/nielsgl/sequelize-paper-trail/blob/master/LICENSE)

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
  - [Example](#example)
- [Options](#options)
- [Local development and running tests](#local-development-and-running-tests)
- [Support](#support)
- [Contributing](#contributing)
- [Author](#author)
- [Thanks](#thanks)
- [Links](#links)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation

```bash
npm install --save sequelize-paper-trail
```

## Usage

Sequelize Paper Trail assumes that you already set up your Sequelize connection, for example, like this:
```javascript
var Sequelize = require('sequelize');
var sequelize = new Sequelize('database', 'username', 'password');
```

then adding Sequelize Paper Trail is as easy as:

```javascript
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:

```javascript
Model.hasPaperTrail();
```

### Example

```javascript
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

```javascript
// 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:

```bash
git clone git@github.com:nielsgl/sequelize-paper-trail.git
```

Install dependencies:
```bash
npm install
```

Run test script:
```bash
npm test
```


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

## Support

Please use:
* GitHub's [issue tracker](https://github.com/nielsgl/sequelize-paper-trail/issues)
* 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](https://nielsgl.com) – [@nielsgl](https://twitter.com/nielsgl) – nvangalenlast@gmail.com  
Distributed under the MIT license. See ``LICENSE`` for more information.  
[https://github.com/nielsgl/sequelize-paper-trail](https://github.com/nielsgl/)  

## Thanks

This project was inspired by:
* [Sequelize-Revisions](https://github.com/bkniffler/sequelize-revisions)
* [Paper Trail](https://github.com/airblade/paper_trail)

## Links

---
_Source: https://npm.io/package/sequelize-paper-trail-scalio · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._