objection-js-soft-delete

A plugin that adds soft-delete functionality to Objection.js

• Installation
• Register the plugin
• Usage
  • Methods
    • .whereNotDeleted()
    • .whereDeleted()
    • .undelete()
    • .hardDelete()
  • Filters
    • notDeleted
    • deleted
    • in a relationship
  • Using with upsertGraph
  • Lifecycle functions

Installation

NPM

1npm i objection-js-soft-delete

Yarn

1yarn add objection-js-soft-delete

Register the plugin

The mixin provides the following configuration to override the default options:

columnName: the column name that indicate if the record is deleted. The column must exist on the table for the model. Default: 'deleted_at'

deletedValue: define which value indicate if the record is deleted. Default: new Date() (local time zone of the server)

It's also possible to use the time from the database: knex.fn.now()

notDeletedValue: define which value indicate if the record is not deleted. You can set (and should) this option along with deletedValue. Default: NULL

1// Import objection and the plugin.
2import { Model } from 'objection';
3import objectionSoftDelete from 'objection-js-soft-delete';
4
5// Specify the options for this plugin. This are the defaults.
6const softDelete = objectionSoftDelete({
7    columnName: 'deleted_at',
8    deletedValue: new Date(),
9    notDeletedValue: null,
10});
11
12// Inject the plugin to the model
13class User extends softDelete(Model) {
14  static get tableName() {
15    return 'Users';
16  }
17}

Note: A deletedValue value of NULL will result in this plugin an unexpected behavior.

Usage

• Soft delete records: When an record will be deleted then the deleted field is set to the value that is specified as deletedValue:

1await User.query().where('id', 1).delete();
2await User.query().deleteById(1);
3
4// Deleted rows are still in the db:
5// User { id: 1, deleted_at: 'Sat Oct 31 2020 15:42:29 GMT+0100 (Central European Standard Time)' , ... }

Methods

• .whereNotDeleted(): Returns only records that aren't deleted.

1const notDeletedUsers = await User.query().whereNotDeleted();

• .whereDeleted(): Returns only records that are deleted.

1const deletedUsers = await User.query().whereDeleted();

• .undelete(): Restore deleted records.

1await User.query().where('id', 1).undelete();
2// User { id: 1, deleted_at: null }

• .hardDelete(): Permanently delete records.

1await User.query.where('id', 1).hardDelete();

Filters

A notDeleted and a deleted filter will be added to the list of named filters for any model that use this mixin. Internally they are using the methods .whereNotDeleted() and .whereDeleted() from above:

• notDeleted: Returns only records from the relation that are not deleted.

1// withGraphFetched
2const rows = await User.query().withGraphFetched('contact(notDeleted)');
3// withGraphJoined
4const rows = await User.query().withGraphJoined('contact(notDeleted)');

• deleted: Returns only records from the relation that are deleted.

1// withGraphFetched
2const rows = await User.query().withGraphFetched('contact(deleted)');
3// withGraphJoined
4const rows = await User.query().withGraphJoined('contact(deleted)');

• Relationship filter: A filter can be applied also directly to a relationship:

1class User extends Model {
2  static get tableName() {
3    return 'user';
4  }
5
6  static get relationMappings() {
7      const Contact = require('./Contact');
8
9      return {
10          contact: {
11            relation: Model.ManyToManyRelation,
12            modelClass: Contact,
13            join: {
14                from: 'user.id',
15                through: {
16                    from: 'user_contact.user_id',
17                    to: 'user_contact.contact_id',
18                },
19                to: 'contact.id',
20            },
21            // .whereNotDeleted() or .whereDeleted()
22            filter: (f) => f.whereNotDeleted(),
23          },
24      };
25  }
26}

then:

1// Will return only records from the relationship contact that are not deleted
2await User.query().withGraphFetched('contact');

Using with upsertGraph

This plugin was actually born out of a need to have .upsertGraph() soft delete in some tables, and hard delete in others.

1// a model with soft delete
2class Phone extends softDelete(Model) {
3  static get tableName() {
4    return 'Phones';
5  }
6}
7
8// a model without soft delete
9class Email extends Model {
10  static get tableName() {
11    return 'Emails';
12  }
13}
14
15// assume a User model that relates to both, and the following existing data:
16User {
17  id: 1,
18  name: 'Johnny Cash',
19  phones: [
20    {
21      id: 6,
22      number: '+19195551234',
23    },
24  ],
25  emails: [
26    {
27      id: 3,
28      address: 'mib@americanrecords.com',
29    },
30  ]
31}
32
33await User.query().upsertGraph({
34  id: 1,
35  name: 'Johnny Cash',
36  phones: [],
37  emails: [],
38});
39// => phone id 6 will be flagged deleted (and will still be related to Johnny!), email id 3 will be removed from the database

Lifecycle Functions

One issue that comes with doing soft deletes is that your calls to .delete() will actually trigger lifecycle functions for .update(), which may not be expected or desired. To help address this, some context flags have been added to the queryContext that is passed into lifecycle functions to help discern whether the event that triggered (e.g.) $beforeUpdate was a true update, a soft delete, or an undelete:

1$beforeUpdate(opt, queryContext) {
2  if (queryContext.softDelete) {
3    // do something before a soft delete, possibly including calling your $beforeDelete function.
4    // Think this through carefully if you are using additional plugins, as their lifecycle
5    // functions may execute before this one depending on how you have set up your inheritance chain!
6  } else if (queryContext.undelete) {
7    // do something before an undelete
8  } else {
9    // do something before a normal update
10  }
11}
12  
13// same procedure for $afterUpdate

Available flags are:

• softDelete
• undelete

Flags will be true if set, and undefined otherwise.

Checking Whether a Model is SoftDelete

All models with the soft delete mixin will have an isSoftDelete property, which returns true.

1const modelHasSoftDelete = User.isSoftDelete;

Tests

Tests can be run with:

1npm test

or:

1yarn test

Linting

The linter can be run with:

1npm run lint

or:

1yarn lint