@nestarc/soft-delete
Prisma soft-delete extension for NestJS. Automatically intercepts delete operations, filters deleted records from queries, and supports cascade soft-delete, bulk restore, purge, events, and relation-aware reads.
For the database rules and client boundary behind a production setup, read Prisma Soft Delete: Why deletedAt Alone Is Not Enough.
Documented release
Documented package version: 0.7.6
Version 0.7.6 adds audit-log 0.8.0 compatibility while retaining all previous peer ranges. The current PostgreSQL lifecycle composition uses tenancy 0.16.4, audit-log 0.8.0, and soft-delete 0.7.6. Its public tenancyTransactionCallback() binds the authorized tenant inside audit-log's transaction on a dedicated audit-log → soft-delete client.
The release validates this composition with strict peer installation and packed PostgreSQL consumers on Node.js 22.23.4 / 24.22.1 and Prisma 6.19.3 / 7.10.1. Coverage includes tenant isolation under FORCE RLS, restore and permanent deletion, and rollback after user or audit-write failures. The existing audit-log 0.4.1 / tenancy 0.15.0 development baseline remains in place. Release integration fixture
Version 0.7.5 introduced shared service tokens and context between root and /testing imports within each module format, plus the configured cascade provider in TestSoftDeleteModule. These fixes remain available in 0.7.6; see testing setup and the 0.7.4 migration boundary.
No soft-delete schema or lifecycle protocol migration is required from 0.7.5. NestJS 10/11, Prisma 5/6/7, and tenancy ^0.15.0 || ^0.16.0 remain supported. See the 0.7.6 release source and compatibility guide before upgrading a composed client.
For a first integration, follow installation and use the extended Prisma client for both deletes and reads. If you also need audit evidence, use the atomic lifecycle setup with the documented version pairing. Choose relation filtering for nested reads, cascade and active-row uniqueness for dependent records, or restore and purge for retention workflows.
Audit-log 0.9.0 boundary
Soft-delete 0.7.6 does not include audit-log 0.9.0 in its optional peer range. Keep the verified lifecycle combination on audit-log 0.8.0; do not bypass strict peer validation. The new audit-to-Outbox path has a separate scope.
Features
- Automatic soft-delete:
deleteanddeleteManybecomeupdate/updateManysettingdeletedAt - Transparent query filtering:
findMany,findFirst,findUnique,count,aggregate,groupByall exclude soft-deleted rows by default - Opt-in relation filtering for to-many Prisma
includeandselecttrees - Cascade soft-delete and restore across related models
restore(),restoreMany(),forceDelete(), andpurge()operations onSoftDeleteService- Route-decorator control:
@WithDeleted(),@OnlyDeleted(),@SkipSoftDelete(),@WithDeletedRelations() - Optional actor tracking via
deletedByFieldandactorExtractor - Lifecycle events (
SoftDeletedEvent,RestoredEvent,PurgedEvent) via@nestjs/event-emitterfor notifications, with listener examples and testing helpers - Opt-in atomic lifecycle evidence for soft-delete, restore, purge, cascade, and bounded bulk work through
@nestarc/audit-log - Fail-closed
auditMaxBatchRecordsguard for record-leveldeleteManyandrestoreManyevidence - Testing utilities:
TestSoftDeleteModule,expectSoftDeleted,expectNotSoftDeleted,expectCascadeSoftDeleted - Standalone Prisma extension (
createPrismaSoftDeleteExtension) for use without NestJS - Global module — register once, use everywhere
The benchmark guide covers filtered reads, delete operations, and a small cascade workload. Its read scenarios return different row counts; use the methodology and interpretation notes to design a comparison for your own data before drawing performance conclusions.
Start Here
- Installation & Quick Start — supported versions and module setup
- Relation Filters — filter soft-deleted children in nested reads
- Cascade & Unique Constraints — cascade behavior and active-row uniqueness
- Restore, Force Delete & Purge — single and bulk recovery operations
- Upgrade to 0.6 — Prisma 7 and explicit DMMF migration notes
- v0.5 Upgrade & Resolved Issues — changes, fixes, and adoption checklist
- API Reference — generated TypeScript documentation
Installation
npm install @nestarc/[email protected]
# or
yarn add @nestarc/[email protected]
# or
pnpm add @nestarc/[email protected]Required peer dependencies (install if not already present):
npm install @nestjs/common @nestjs/core @prisma/client reflect-metadata rxjsFor direct PostgreSQL connections with Prisma 7:
npm install @prisma/adapter-pg pgOptional peer dependencies:
# For lifecycle events
npm install @nestjs/event-emitter
# For scheduled purge jobs
npm install @nestjs/schedule
# For authoritative, same-transaction lifecycle evidence
npm install --save-exact @nestarc/[email protected]
# Optional tenant context for the composed Prisma client
npm install --save-exact @nestarc/[email protected]Supported peer ranges remain NestJS 10/11 and Prisma 5/6/7. The optional audit-log peer range is ^0.4.1 || ^0.5.0 || ^0.6.0 || ^0.7.0 || ^0.8.0; upgrade soft-delete to 0.7.6 before adding audit-log 0.8.0. Soft-delete alone retains Node.js ^20.19.0 || ^22.12.0 || >=24.0.0. The current composition with tenancy 0.16.4 and audit-log 0.8.0 requires Node.js ^22.23.4 || ^24.22.1. Prisma 7 is the primary development and PostgreSQL E2E target; the dedicated latest-composition checks also exercise Prisma 6 consumers. See the installation guide, atomic lifecycle setup, and Prisma 7 setup guide.