@eienjs/adonisjs-soft-deletes

Provider-based Soft deletes for AdonisJS with full Lucid ORM support.

Features

• Full Lucid ORM Integration: Automatic query filtering (deleted_at is null), eager relationship filtering, and ModelQueryBuilder macros.
• Fluent Querying: User.query().withTrashed(), User.query().onlyTrashed(), User.query().restore(), plus static helpers User.withTrashed() and User.onlyTrashed().
• Instance Helpers: .$trashed boolean getter, .delete() (soft delete), .restore(), and .forceDelete().

Quick Start

Install the package using the following command:

node ace add @eienjs/adonisjs-soft-deletes

This will register the Lucid provider in your adonisrc.ts file:

export default defineConfig({
  providers: [
    () => import('@eienjs/adonisjs-soft-deletes/providers/lucid_provider'),
  ],
});

Usage

1. Database Migration

Ensure your database table includes a nullable deleted_at timestamp:

import { BaseSchema } from '@adonisjs/lucid/schema';

export default class UsersTable extends BaseSchema {
  protected tableName = 'users';

  public async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id');
      table.string('email').notNullable();
      table.timestamp('deleted_at').nullable();
      table.timestamp('created_at').notNullable();
      table.timestamp('updated_at').nullable();
    });
  }

  public async down() {
    this.schema.dropTable(this.tableName);
  }
}

2. Model Definition

Apply the SoftDeletes mixin to your Lucid model:

import { compose } from '@adonisjs/core/helpers';
import { BaseModel } from '@adonisjs/lucid/orm';
import { SoftDeletes } from '@eienjs/adonisjs-soft-deletes/lucid/mixin';

export default class User extends compose(BaseModel, SoftDeletes) {
  // Model properties and columns...
}

3. Soft Deleting and Restoring Records

// Find a record and soft delete
const user = await User.findOrFail(1);
await user.delete(); // Sets deleted_at to current timestamp

console.log(user.$trashed); // true

// Restore soft-deleted record
await user.restore();
console.log(user.$trashed); // false

// Permanently delete from database
await user.forceDelete();

4. Querying Records

By default, queries automatically exclude soft-deleted records:

// Excludes soft-deleted records automatically
const activeUsers = await User.all();

// Include soft-deleted records via query builder
const allUsers = await User.query().withTrashed();

// Retrieve only soft-deleted records via query builder
const archivedUsers = await User.query().onlyTrashed();

// Bulk restore soft-deleted records via query builder
await User.query().onlyTrashed().where('status', 'inactive').restore();

// Static helpers on model
const all = await User.withTrashed();
const archived = await User.onlyTrashed();

Documentation

The documentation is available on EienJS.

Contributing

Contributions are welcome. Please read CONTRIBUTING for more details and remember to check the CHANGELOG file.

Copyright and License

The @eienjs/adonisjs-soft-deletes library is licensed for use under the MIT License (MIT). Please see LICENSE for more information.