@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.2

Version 0.7 adds an opt-in, fail-closed atomic lifecycle bridge for @nestarc/audit-log. Version 0.7.2 adds tenancy ^0.15.0 || ^0.16.0 compatibility and accepts the optional audit-log peer range ^0.4.1 || ^0.5.0 with the same capability handshake on both lines and no soft-delete runtime behavior changes. Prisma 5, 6, and 7 remain in the peer range; cascade and relation filters require explicit DMMF metadata. See the release overview for newer npm releases and their source before upgrading.

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.

---

Features

• Automatic soft-delete: delete and deleteMany become update/updateMany setting deletedAt
• Transparent query filtering: findMany, findFirst, findUnique, count, aggregate, groupBy all exclude soft-deleted rows by default
• Opt-in relation filtering for to-many Prisma include and select trees
• Cascade soft-delete and restore across related models
• restore(), restoreMany(), forceDelete(), and purge() operations on SoftDeleteService
• Route-decorator control: @WithDeleted(), @OnlyDeleted(), @SkipSoftDelete(), @WithDeletedRelations()
• Optional actor tracking via deletedByField and actorExtractor
• Lifecycle events (SoftDeletedEvent, RestoredEvent, PurgedEvent) via @nestjs/event-emitter for 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 auditMaxBatchRecords guard for record-level deleteMany and restoreMany evidence
• 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/soft-delete
# or
yarn add @nestarc/soft-delete
# or
pnpm add @nestarc/soft-delete

Required peer dependencies (install if not already present):

npm install @nestjs/common @nestjs/core @prisma/client reflect-metadata rxjs

For direct PostgreSQL connections with Prisma 7:

npm install @prisma/adapter-pg pg

Optional 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 @nestarc/audit-log@^0.5.0

# Optional tenant context for the composed Prisma client
npm install @nestarc/tenancy@^0.16.0

Supported peer ranges are NestJS 10/11 and Prisma 5/6/7. The optional audit-log peer range is ^0.4.1 || ^0.5.0. Prisma 7 is the primary development and PostgreSQL E2E target. See the installation guide, atomic lifecycle setup, and Prisma 7 setup guide.