loopback-changes-history-mixin

Loopback mixin to generate a new model to save history changes by record of a model.

Installation

npm install loopback-changes-history-mixin --save

Usage

Add the mixins property to your server/model-config.json:

{
  "_meta": {
    "sources": [
      "loopback/common/models",
      "loopback/server/models",
      "../common/models",
      "./models"
    ],
    "mixins": [
      "loopback/common/mixins",
      "../node_modules/loopback-changes-history-mixin",
      "../common/mixins"
    ]
  }
}

Add mixin params in model definition. Example:

{
  "name": "Person",
  "properties": {
    "name": "string",
    "email": "string",
    "status": "string",
    "description": "string"
  },
  "mixins": {
    "ChangeHistory": true
  }
}

In the above definition it will define the following:

• A model called Person_history with properties indicated in fields: name, email, status and description.
• Relation Person has many history (model Person_history, foreign key _recordId).
• Relation Person_history belongs record (model Person, foreign key _recordId).
• Properties _version and _hash as string in models Person and Person_history.
• Properties _action as string and _update as date in model Person_history.

Every time a change is made in a record of Person, it will be saved in Person_history a record with new values and the following fields:

• _version = <version code>
• _hash = <hash code>
• _action = <'create' or 'update' or 'delete'>
• _update = <date of change>

Options

The mixin supports the following parameters:

Name | Type | Default | Optional | Description ----------------------|-------------------------|------------------------|----------|------------ fields | array or string * | * | No | Array with the fields to version modelName | string | ${ModelName}_history | No | Name to history model relationName | string | history | No | Model has many history model relation name relationParentName | string | _record | No | History model belongs to model relation name relationForeignKey | string | _recordId | No | Foreign key for relations versionFieldName | string | _version | No | Field name to version code versionFieldLen | number | 5 | No | Length to versionField hashFieldName | string or false | _hash | Yes | Field name to hash code hashFieldLen | number | 10 | No | Length to hashField actionFieldName | string or false | _action | Yes | Field name to action name updatedFieldName | string or false | _update | Yes | Field name to update date

Notes:

• hashFieldName allow create a history change only if any property in fields was alter. If setup hashFieldName: false then a history change will be creates with update method called.
• If hashFieldName is false then hashFieldLen is. ignoored.

Loopback methods

Generates create records

• Model.create
• Model.updateOrCreate (AKA Model.upsert)
• Model.findOrCreate
• Model.replaceOrCreate
• Model.upsertWithWhere (view Model.upsertWithWhere section below)

Generates update records

• Model.updateOrCreate (AKA Model.upsert)
• Model.replaceOrCreate
• Model.upsertWithWhere (view Model.upsertWithWhere section below)
• Model.replaceById
• Model.prototype.save
• Model.prototype.updateAttribute
• Model.prototype.updateAttributes
• Model.prototype.replaceAtributes

Generates destroy records

• Model.prototype.delete (AKA Model.prototype.destroy)
• Model.deleteById (AKA Model.destroyById)

Unsupported methods

• Model.updateAll
• Model.deleteAll (AKA Model.destroyAll)

Model.upsertWithWhere

To create history change with method upsertWithWhere option instanceByWhere: true must be passed:

const where = { /* ... */};
const data = { /* ... */ };
Person.upsertWithWhere(where, data, { instanceByWhere: true });

Troubles

If you have any kind of trouble with it, just let me now by raising an issue on the GitHub issue tracker here:

https://github.com/arondn2/loopback-changes-history-mixin/issues

Also, you can report the orthographic errors in the READMEs files or comments. Sorry for that, English is not my main language.

Tests

npm test or npm run cover