Usage

API Reference

Complete reference of mixins, methods, query builder macros, TypeScript types, and exceptions.

Complete technical reference for all exports and augmentations provided by @eienjs/adonisjs-soft-deletes.

Package Entrypoints

Import Path	Description
`@eienjs/adonisjs-soft-deletes`	Exports the `configure` hook for `node ace configure`.
`@eienjs/adonisjs-soft-deletes/lucid/mixin`	Exports the `SoftDeletes` model mixin.
`@eienjs/adonisjs-soft-deletes/lucid/types`	Exports TypeScript interfaces and helper types.
`@eienjs/adonisjs-soft-deletes/providers/lucid_provider`	Exports `LucidSoftDeletesProvider` and Lucid module augmentations.

`SoftDeletes` Mixin

Imported from @eienjs/adonisjs-soft-deletes/lucid/mixin.

import { SoftDeletes } from '@eienjs/adonisjs-soft-deletes/lucid/mixin';

Instance Properties & Getters

Property	Type	Description
`deletedAt`	`DateTime \| null \| undefined`	Luxon `DateTime` column storing when the model was soft-deleted.
`$trashed`	`boolean` (readonly)	Computed getter returning `Boolean(this.deletedAt)`.
`$forceDelete`	`boolean`	Internal flag (`false` by default) indicating whether `.delete()` should permanently remove the row.

Instance Methods

Method	Signature	Description
`delete()`	`() => Promise<void>`	Soft-deletes the model by setting `deletedAt = DateTime.local()` and calling `.save()`, unless `$forceDelete` is `true`.
`restore()`	`() => Promise<this>`	Sets `deletedAt = null` and saves the model if `$trashed` is `true`. Throws `E_MODEL_FORCE_DELETED` if `$isDeleted` is `true`.
`forceDelete()`	`() => Promise<void>`	Sets `$forceDelete = true` and permanently deletes the row from the database.

Static Methods & Hooks

Method	Signature	Description
`withTrashed()`	`() => ModelQueryBuilderContract<Model>`	Creates a new query builder instance with `ignoreDeleted` set to `false`.
`onlyTrashed()`	`() => ModelQueryBuilderContract<Model>`	Creates a new query builder instance with `ignoreDeleted = false` and `whereNotNull('<table>.<deleted_at>')`.
`disableIgnore(query)`	`(query) => query`	Sets `query.ignoreDeleted = false` on the given query builder and returns it.
`ignoreDeleted(query)`	`(query) => void`	`@beforeFind()` and `@beforeFetch()` hook that appends `whereNull('<table>.<deleted_at>')` unless `query.ignoreDeleted === false`.
`ignoreDeletedPaginate`	`([countQuery, query]) => void`	`@beforePaginate()` hook that synchronizes `ignoreDeleted` onto `countQuery` and applies `ignoreDeleted(countQuery)`.

`ModelQueryBuilder` Macros

Registered automatically by LucidSoftDeletesProvider.

Macro	Signature	Description
`withTrashed()`	`() => this`	Disables the `ignoreDeleted` filter on the current query builder.
`onlyTrashed()`	`() => this`	Disables the `ignoreDeleted` filter and adds `whereNotNull('<table>.<deleted_at>')`.
`restore()`	`() => Promise<unknown>`	Updates matching rows setting the model's `deletedAt` column to `null`.

Calling .withTrashed(), .onlyTrashed(), or .restore() on a query builder for a model that does not use the SoftDeletes mixin throws an E_MODEL_SOFT_DELETE exception.

TypeScript Types

Imported from @eienjs/adonisjs-soft-deletes/lucid/types:

import type {
  ModelQueryBuilderContractWithIgnoreDeleted,
  ModelWithSoftDeletes,
  SoftDeletableModelContract,
  SoftDeletesModel,
} from '@eienjs/adonisjs-soft-deletes/lucid/types';

SoftDeletableModelContract: Instance contract describing $forceDelete, $trashed, deletedAt, delete(), restore(), and forceDelete().
SoftDeletesModel<T>: Return type of SoftDeletes(superclass), combining the base model constructor and instance types with SoftDeletableModelContract and static soft delete methods.
ModelWithSoftDeletes: Type representing a LucidModel augmented with ignoreDeleted, ignoreDeletedPaginate, disableIgnore, withTrashed, and onlyTrashed.
ModelQueryBuilderContractWithIgnoreDeleted<T, R>: Intersection of ModelQueryBuilderContract<T, R> with { ignoreDeleted?: boolean }.

Exceptions

Code	Status	Message	Cause
`E_MODEL_FORCE_DELETED`	`500`	`Cannot restore a model instance that was force deleted`	Calling `model.restore()` after `model.forceDelete()` has completed.
`E_MODEL_SOFT_DELETE`	`500`	`<ModelName> model does not support Soft Deletes`	Calling `withTrashed()`, `onlyTrashed()`, or `restore()` on a query builder whose model is not composed with `SoftDeletes`.

Usage

Apply the SoftDeletes mixin to Lucid models, soft delete and restore instances, and query trashed records.