@kysera/soft-delete 0.6.0 → 0.7.0

package/README.md

@@ -1,1349 +1,857 @@
 # @kysera/soft-delete
 
-> Soft delete plugin for Kysera ORM - Mark records as deleted without actually removing them from the database, with powerful restore and query capabilities.
-
-[![Version](https://img.shields.io/npm/v/@kysera/soft-delete.svg)](https://www.npmjs.com/package/@kysera/soft-delete)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
-
-## 📦 Package Information
-
-| Metric | Value |
-|--------|-------|
-| **Version** | 0.5.1 |
-| **Bundle Size** | ~4 KB (minified) |
-| **Test Coverage** | 39+ tests passing |
-| **Dependencies** | @kysera/core (workspace) |
-| **Peer Dependencies** | kysely >=0.28.8, @kysera/repository, zod ^4.1.13 (optional) |
-| **Target Runtimes** | Node.js 20+, Bun 1.0+, Deno |
-| **Module System** | ESM only |
-| **Database Support** | PostgreSQL, MySQL, SQLite |
-
-## 🎯 Features
-
-- ✅ **Soft Delete** - Mark records as deleted without removing them
-- ✅ **Automatic Filtering** - Deleted records excluded from queries by default
-- ✅ **Restore Capability** - Bring back soft-deleted records
-- ✅ **Hard Delete** - Permanently remove records when needed
-- ✅ **Query Helpers** - Find deleted, include deleted, or exclude deleted
-- ✅ **Type-Safe** - Full TypeScript support
-- ✅ **Table Filtering** - Apply to specific tables only
-- ✅ **Custom Column Names** - Use any column name for deleted_at
-- ✅ **Production Ready** - Battle-tested with comprehensive coverage
-
-## 📥 Installation
+Soft delete plugin for Kysera. Implements soft delete functionality using the Method Override pattern with automatic filtering of deleted records.
 
-```bash
-# npm
-npm install @kysera/soft-delete @kysera/repository kysely
+## Features
 
-# pnpm
-pnpm add @kysera/soft-delete @kysera/repository kysely
+- Automatic filtering of soft-deleted records in SELECT queries
+- Repository methods for soft delete operations (softDelete, restore, hardDelete)
+- Bulk operations (softDeleteMany, restoreMany, hardDeleteMany)
+- Query methods for deleted records (findWithDeleted, findAllWithDeleted, findDeleted)
+- Works with both Repository and DAL patterns through unified executor layer
+- Full transaction support with ACID compliance
+- Configurable deleted column name, primary key, and table filtering
+- Cross-runtime compatible (Node.js, Bun, Deno)
+- Zero runtime dependencies
 
-# bun
-bun add @kysera/soft-delete @kysera/repository kysely
+## Installation
 
-# deno
-import { softDeletePlugin } from "npm:@kysera/soft-delete"
+```bash
+npm install @kysera/soft-delete
+# or
+pnpm add @kysera/soft-delete
+# or
+yarn add @kysera/soft-delete
+# or
+bun add @kysera/soft-delete
+```
+
+### Peer Dependencies
+
+```json
+{
+  "@kysera/executor": ">=0.7.0",
+  "kysely": ">=0.28.8",
+  "zod": ">=4.1.13"
+}
 ```
 
-## 🚀 Quick Start
-
-### 1. Add deleted_at Column to Your Database
-
-```sql
--- PostgreSQL / MySQL / SQLite
-ALTER TABLE users ADD COLUMN deleted_at TIMESTAMP NULL;
+Note: `zod` is optional (used for configuration schema validation in `kysera-cli`)
 
--- Or include in table creation
-CREATE TABLE users (
-  id SERIAL PRIMARY KEY,
-  email VARCHAR(255) NOT NULL,
-  name VARCHAR(255) NOT NULL,
-  created_at TIMESTAMP DEFAULT NOW(),
-  deleted_at TIMESTAMP NULL  -- Soft delete column
-);
-```
+## Quick Start
 
-### 2. Setup Plugin
+### With Repository Pattern
 
 ```typescript
-import { Kysely, PostgresDialect, Generated } from 'kysely'
-import { Pool } from 'pg'
-import { createORM, createRepositoryFactory } from '@kysera/repository'
-import { softDeletePlugin } from '@kysera/soft-delete'
-import { z } from 'zod'
-
-// Define database schema
-interface Database {
-  users: {
-    id: Generated<number>
-    email: string
-    name: string
-    created_at: Generated<Date>
-    deleted_at: Date | null  // Nullable for soft delete
-  }
-}
-
-// Create database connection
-const db = new Kysely<Database>({
-  dialect: new PostgresDialect({
-    pool: new Pool({ /* config */ })
-  })
-})
+import { createORM } from '@kysera/repository';
+import { softDeletePlugin } from '@kysera/soft-delete';
 
-// Create ORM with soft delete plugin
+// Create plugin container with soft-delete plugin
 const orm = await createORM(db, [
-  softDeletePlugin()  // ✨ That's it!
-])
-
-// Create repository
-const userRepo = orm.createRepository((executor) => {
-  const factory = createRepositoryFactory(executor)
-  return factory.create<'users', User>({
-    tableName: 'users',
-    mapRow: (row) => row as User,
-    schemas: {
-      create: z.object({
-        email: z.string().email(),
-        name: z.string()
-      })
-    }
+  softDeletePlugin({
+    deletedAtColumn: 'deleted_at',
+    includeDeleted: false,
+    tables: ['users', 'posts'] // Only these tables support soft delete
   })
-})
-
-// Use repository with soft delete!
-const user = await userRepo.create({
-  email: 'alice@example.com',
-  name: 'Alice'
-})
+]);
 
-// Soft delete (sets deleted_at timestamp)
-await userRepo.softDelete(user.id)
-
-// Find all - excludes soft-deleted records
-const users = await userRepo.findAll()  // Alice not included
+// Create repository
+const userRepo = orm.createRepository(createUserRepository);
 
-// Find including deleted
-const allUsers = await userRepo.findAllWithDeleted()  // Alice included
+// Soft delete a user (sets deleted_at timestamp)
+await userRepo.softDelete(1);
 
-// Restore
-await userRepo.restore(user.id)  // Alice is back!
+// Find all users (excludes soft-deleted automatically)
+const users = await userRepo.findAll();
 
-// Hard delete (permanently remove)
-await userRepo.hardDelete(user.id)  // Alice gone forever
-```
+// Find including deleted records
+const allUsers = await userRepo.findAllWithDeleted();
 
----
-
-## 📚 Table of Contents
-
-1. [Core Concepts](#-core-concepts)
-   - [What is Soft Delete?](#what-is-soft-delete)
-   - [Method Override Pattern](#method-override-pattern)
-   - [Automatic Filtering](#automatic-filtering)
-2. [Configuration](#-configuration)
-   - [Default Configuration](#default-configuration)
-   - [Custom Column Names](#custom-column-names)
-   - [Table Filtering](#table-filtering)
-   - [Include Deleted by Default](#include-deleted-by-default)
-3. [Repository Methods](#-repository-methods)
-   - [softDelete](#softdelete)
-   - [restore](#restore)
-   - [hardDelete](#harddelete)
-   - [findAllWithDeleted](#findallwithdeleted)
-   - [findDeleted](#finddeleted)
-   - [findWithDeleted](#findwithdeleted)
-4. [Automatic Filtering](#-automatic-filtering-1)
-5. [Advanced Usage](#-advanced-usage)
-6. [Multi-Database Support](#-multi-database-support)
-7. [Type Safety](#-type-safety)
-8. [API Reference](#-api-reference)
-9. [Best Practices](#-best-practices)
-10. [Performance](#-performance)
-11. [Troubleshooting](#-troubleshooting)
-
----
-
-## 💡 Core Concepts
-
-### What is Soft Delete?
-
-Soft delete is a data management pattern where records are marked as deleted rather than actually removed from the database. This provides:
-
-- **Data Recovery** - Restore accidentally deleted records
-- **Audit Trail** - Keep history of what was deleted and when
-- **Compliance** - Meet regulatory requirements for data retention
-- **User Experience** - Implement "Trash" or "Recycle Bin" features
-- **Safety** - Prevent permanent data loss
-
-**Example:**
+// Restore a soft-deleted user
+await userRepo.restore(1);
 
-```typescript
-// Traditional hard delete (data lost forever)
-await db.deleteFrom('users').where('id', '=', 1).execute()
-// Record is GONE
-
-// Soft delete (data preserved)
-await userRepo.softDelete(1)
-// Record still in database, just marked as deleted
-// Can be restored later!
+// Permanently delete (real DELETE)
+await userRepo.hardDelete(1);
 ```
 
-### Method Override Pattern
-
-This plugin uses the **Method Override pattern**, not full query interception:
-
-**✅ What happens automatically:**
-- `SELECT` queries filter out soft-deleted records
-- `findAll()` excludes soft-deleted records
-- `findById()` excludes soft-deleted records
-
-**❌ What does NOT happen automatically:**
-- `DELETE` operations are NOT converted to soft deletes
-- You must explicitly use `softDelete()` method
-- Regular `delete()` performs a hard delete
-
-**Why this design?**
-
-This approach is intentional for:
-- **Explicitness** - Clear intent: `softDelete()` vs `delete()`
-- **Simplicity** - No magic query transformations
-- **Control** - Choose soft or hard delete per operation
-- **Performance** - No overhead on DELETE queries
+### With DAL Pattern
 
 ```typescript
-// ✅ Explicit soft delete
-await userRepo.softDelete(userId)  // Sets deleted_at
-
-// ❌ This performs a HARD delete (if repository has delete method)
-await userRepo.delete(userId)  // Actually removes record
-
-// ✅ Use hardDelete for clarity
-await userRepo.hardDelete(userId)  // Explicitly hard delete
-```
+import { createExecutor } from '@kysera/executor';
+import { createContext, createQuery, withTransaction } from '@kysera/dal';
+import { softDeletePlugin } from '@kysera/soft-delete';
+import { sql } from 'kysely';
 
-### Automatic Filtering
+// Create executor with soft-delete plugin
+const executor = await createExecutor(db, [
+  softDeletePlugin({
+    deletedAtColumn: 'deleted_at',
+    includeDeleted: false
+  })
+]);
 
-When the plugin is active, soft-deleted records are **automatically excluded** from queries:
+// Create context
+const ctx = createContext(executor);
 
-```typescript
-// Create and soft-delete a user
-await userRepo.softDelete(aliceId)
+// Define queries - soft-delete filter applied automatically
+const getUsers = createQuery((ctx) =>
+  ctx.db.selectFrom('users').selectAll().execute()
+);
 
-// Queries automatically exclude soft-deleted
-const users = await userRepo.findAll()
-// Alice NOT included
+const getUserById = createQuery((ctx, id: number) =>
+  ctx.db
+    .selectFrom('users')
+    .selectAll()
+    .where('id', '=', id)
+    .executeTakeFirst()
+);
 
-const user = await userRepo.findById(aliceId)
-// Returns null (Alice is soft-deleted)
+// Execute queries - deleted records automatically filtered
+const users = await getUsers(ctx); // Excludes soft-deleted
+const user = await getUserById(ctx, 1);
 
-// Explicitly include deleted
-const allUsers = await userRepo.findAllWithDeleted()
-// Alice included
+// Soft delete within transaction
+await withTransaction(executor, async (txCtx) => {
+  await txCtx.db
+    .updateTable('users')
+    .set({ deleted_at: sql`CURRENT_TIMESTAMP` })
+    .where('id', '=', 1)
+    .execute();
 
-const userWithDeleted = await userRepo.findWithDeleted(aliceId)
-// Returns Alice even though soft-deleted
+  // Subsequent queries in same transaction see the deletion
+  const users = await getUsers(txCtx); // User 1 excluded
+});
 ```
 
----
+## Plugin Architecture
 
-## ⚙️ Configuration
+The soft-delete plugin leverages `@kysera/executor` for unified plugin support across both Repository and DAL patterns.
 
-### Default Configuration
-
-The plugin works with zero configuration using sensible defaults:
+### How It Works
 
 ```typescript
-const plugin = softDeletePlugin()
-
-// Equivalent to:
-const plugin = softDeletePlugin({
-  deletedAtColumn: 'deleted_at',
-  includeDeleted: false,
-  tables: undefined,  // All tables
-  primaryKeyColumn: 'id'  // Default primary key
-})
-```
-
-### Custom Column Names
+import { createExecutor, getRawDb } from '@kysera/executor';
+import type { Plugin, QueryBuilderContext } from '@kysera/executor';
 
-Use your own column naming convention:
+// Plugin implements the Plugin interface
+const plugin = softDeletePlugin();
 
-```typescript
-// Example: Use "removed_at"
-const plugin = softDeletePlugin({
-  deletedAtColumn: 'removed_at'
-})
-
-// Database schema
-interface Database {
-  users: {
-    id: Generated<number>
-    email: string
-    removed_at: Date | null  // ✅ Custom name
-  }
-}
+// Executor wraps Kysely with plugin interception
+const executor = await createExecutor(db, [plugin]);
 
-// Example: Use "archived_at"
-const plugin = softDeletePlugin({
-  deletedAtColumn: 'archived_at'
-})
+// All queries through executor have soft-delete filter applied
+const users = await executor
+  .selectFrom('users')
+  .selectAll()
+  .execute(); // WHERE users.deleted_at IS NULL (added automatically)
 ```
 
-### Custom Primary Key Column
+### Plugin Interface
 
-Configure tables with different primary key column names:
+The plugin implements the `Plugin` interface from `@kysera/executor`:
 
 ```typescript
-// Example: Use "uuid" as primary key
-const plugin = softDeletePlugin({
-  primaryKeyColumn: 'uuid'
-})
-
-// Database schema
-interface Database {
-  users: {
-    uuid: Generated<string>  // ✅ Custom primary key
-    email: string
-    name: string
-    deleted_at: Date | null
-  }
+interface Plugin {
+  name: string;
+  version: string;
+  interceptQuery<QB>(qb: QB, context: QueryBuilderContext): QB;
+  extendRepository<T extends object>(repo: T): T;
 }
-
-// Example: Use "user_id"
-const plugin = softDeletePlugin({
-  primaryKeyColumn: 'user_id'
-})
-
-// Usage remains the same
-await userRepo.softDelete(userId)
-await userRepo.restore(userId)
-await userRepo.hardDelete(userId)
 ```
 
-**When to use:**
-- Tables with UUID primary keys (`uuid`, `guid`)
-- Tables with composite naming (`user_id`, `post_id`)
-- Legacy databases with custom key columns
-- Multi-tenant systems with custom identifiers
-
-### Table Filtering
+#### interceptQuery
 
-Apply soft delete only to specific tables:
+Modifies SELECT query builders to automatically filter out soft-deleted records:
 
 ```typescript
-// Only enable for specific tables
-const plugin = softDeletePlugin({
-  tables: ['users', 'posts', 'comments']
-})
-
-// users, posts, comments:  ✅ Soft delete enabled
-// other tables:             ❌ Soft delete disabled
-```
-
-**When to use table filtering:**
+interceptQuery<QB>(qb: QB, context: QueryBuilderContext): QB {
+  // Check if table supports soft delete
+  const supportsSoftDelete = !tables || tables.includes(context.table);
 
-```typescript
-// ✅ Good: User-facing data
-const plugin = softDeletePlugin({
-  tables: ['users', 'posts', 'comments', 'orders']
-})
+  // Only filter SELECT queries when not explicitly including deleted
+  if (
+    supportsSoftDelete &&
+    context.operation === 'select' &&
+    !context.metadata['includeDeleted'] &&
+    !includeDeleted
+  ) {
+    // Add WHERE deleted_at IS NULL to the query builder
+    return qb.where(`${context.table}.${deletedAtColumn}`, 'is', null);
+  }
 
-// ❌ Skip: System/config tables (don't need soft delete)
-// migrations, config, sessions - not included in tables list
+  return qb;
+}
 ```
 
-### Include Deleted by Default
+#### extendRepository
 
-Reverse the default behavior (include deleted records):
+Adds soft delete methods to repositories (Repository pattern only):
 
 ```typescript
-const plugin = softDeletePlugin({
-  includeDeleted: true  // Include deleted by default
-})
-
-// Now queries include soft-deleted records by default
-const users = await userRepo.findAll()  // Includes deleted
-
-// You'd need to explicitly exclude
-// (Note: this is less common)
+extendRepository<T extends object>(repo: T): T {
+  // Adds: softDelete, restore, hardDelete, findWithDeleted,
+  // findAllWithDeleted, findDeleted, softDeleteMany, restoreMany, hardDeleteMany
+}
 ```
 
----
-
-## 🔧 Repository Methods
-
-The plugin extends repositories with these methods:
-
-### softDelete
-
-Mark a record as deleted by setting `deleted_at` timestamp.
+### Using getRawDb
 
-```typescript
-async softDelete(id: number | string): Promise<T>
-```
-
-**Example:**
+The plugin uses `getRawDb()` from `@kysera/executor` to bypass interceptors when needed:
 
 ```typescript
-const user = await userRepo.softDelete(userId)
+import { getRawDb } from '@kysera/executor';
 
-console.log(user.deleted_at)  // 2024-01-15T10:30:00.000Z
+// Inside plugin's extendRepository method
+const rawDb = getRawDb(repo.executor);
 
-// Record still exists in database
-const directQuery = await db
+// Use rawDb to bypass soft-delete filter
+// (needed for findWithDeleted, restore, etc.)
+const allRecords = await rawDb
   .selectFrom('users')
   .selectAll()
-  .where('id', '=', userId)
-  .executeTakeFirst()
-
-console.log(directQuery)  // Record exists with deleted_at set
+  .execute(); // No soft-delete filter applied
 ```
 
-**Use Cases:**
-- User account deletion
-- Content moderation
-- Order cancellation
-- Temporary removals
-- Implementing "Trash" feature
+This is critical for methods like `findWithDeleted()` and `restore()` that need to access soft-deleted records.
 
-### restore
+## Configuration Options
 
-Restore a soft-deleted record by setting `deleted_at` to `null`.
+### SoftDeleteOptions
 
 ```typescript
-async restore(id: number | string): Promise<T>
+interface SoftDeleteOptions {
+  /**
+   * Column name for soft delete timestamp.
+   * @default 'deleted_at'
+   */
+  deletedAtColumn?: string;
+
+  /**
+   * Include deleted records by default in queries.
+   * When false, soft-deleted records are automatically filtered out.
+   * @default false
+   */
+  includeDeleted?: boolean;
+
+  /**
+   * List of tables that support soft delete.
+   * If not provided, all tables are assumed to support it.
+   * @example ['users', 'posts', 'comments']
+   */
+  tables?: string[];
+
+  /**
+   * Primary key column name used for identifying records.
+   * @default 'id'
+   * @example 'uuid', 'user_id', 'post_id'
+   */
+  primaryKeyColumn?: string;
+
+  /**
+   * Logger for plugin operations.
+   * Uses KyseraLogger interface from @kysera/core.
+   * @default silentLogger (no output)
+   */
+  logger?: KyseraLogger;
+}
 ```
 
-**Example:**
+### Example Configurations
 
 ```typescript
-// Soft delete a user
-await userRepo.softDelete(userId)
-
-// Later, restore them
-const restored = await userRepo.restore(userId)
+// Default configuration
+softDeletePlugin();
 
-console.log(restored.deleted_at)  // null
+// Custom deleted column
+softDeletePlugin({
+  deletedAtColumn: 'removed_at'
+});
 
-// User now appears in queries again
-const users = await userRepo.findAll()
-// Includes restored user
-```
+// Only specific tables
+softDeletePlugin({
+  tables: ['users', 'posts'], // Only these tables support soft delete
+  deletedAtColumn: 'deleted_at'
+});
 
-**Use Cases:**
-- Undo accidental deletions
-- User account reactivation
-- Content restoration
-- Admin recovery tools
+// Include deleted by default
+softDeletePlugin({
+  includeDeleted: true // Don't filter deleted records
+});
 
-### hardDelete
+// Custom primary key
+softDeletePlugin({
+  primaryKeyColumn: 'uuid' // For tables using 'uuid' instead of 'id'
+});
 
-Permanently delete a record from the database (bypasses soft delete).
+// With logging
+import { consoleLogger } from '@kysera/core';
 
-```typescript
-async hardDelete(id: number | string): Promise<void>
+softDeletePlugin({
+  logger: consoleLogger
+});
 ```
 
-**Example:**
+## Repository Methods
 
-```typescript
-// Permanently remove a user
-await userRepo.hardDelete(userId)
+The plugin extends repositories with the following methods:
 
-// Record is GONE from database
-const user = await db
-  .selectFrom('users')
-  .selectAll()
-  .where('id', '=', userId)
-  .executeTakeFirst()
+### SoftDeleteMethods Interface
 
-console.log(user)  // undefined
+```typescript
+interface SoftDeleteMethods<T> {
+  softDelete(id: number | string): Promise<T>;
+  restore(id: number | string): Promise<T>;
+  hardDelete(id: number | string): Promise<void>;
+  findWithDeleted(id: number | string): Promise<T | null>;
+  findAllWithDeleted(): Promise<T[]>;
+  findDeleted(): Promise<T[]>;
+  softDeleteMany(ids: (number | string)[]): Promise<T[]>;
+  restoreMany(ids: (number | string)[]): Promise<T[]>;
+  hardDeleteMany(ids: (number | string)[]): Promise<void>;
+}
 ```
 
-**Use Cases:**
-- GDPR "right to be forgotten" compliance
-- Cleaning up test data
-- Purging old soft-deleted records
-- Admin force-delete
+### Method Documentation
 
-### findAllWithDeleted
+#### softDelete(id)
 
-Find all records including soft-deleted ones.
+Marks a record as deleted by setting the `deleted_at` timestamp to `CURRENT_TIMESTAMP`.
 
 ```typescript
-async findAllWithDeleted(): Promise<T[]>
+// Soft delete user with id 1
+const deletedUser = await userRepo.softDelete(1);
+console.log(deletedUser.deleted_at); // '2025-12-11T10:30:00Z'
+
+// Record still exists in database but won't appear in findAll()
+const users = await userRepo.findAll(); // Excludes deleted user
 ```
 
-**Example:**
+**Returns**: `Promise<T>` - The soft-deleted record
+**Throws**: `NotFoundError` if record doesn't exist
 
-```typescript
-// Soft delete Bob
-await userRepo.softDelete(bobId)
+#### restore(id)
+
+Restores a soft-deleted record by setting `deleted_at` to `null`.
 
-// Normal query excludes Bob
-const active = await userRepo.findAll()
-console.log(active.length)  // 2
+```typescript
+// Restore soft-deleted user
+const restoredUser = await userRepo.restore(1);
+console.log(restoredUser.deleted_at); // null
 
-// Include deleted shows Bob
-const all = await userRepo.findAllWithDeleted()
-console.log(all.length)  // 3 (includes Bob)
+// Record now appears in queries again
+const users = await userRepo.findAll(); // Includes restored user
 ```
 
-**Use Cases:**
-- Admin panels showing all records
-- Audit trails
-- Data export including deleted
-- Recovery interfaces
+**Returns**: `Promise<T>` - The restored record
+**Throws**: `NotFoundError` if record doesn't exist
 
-### findDeleted
+#### hardDelete(id)
 
-Find only soft-deleted records.
+Permanently deletes a record using real SQL DELETE. Cannot be restored.
 
 ```typescript
-async findDeleted(): Promise<T[]>
-```
+// Permanently delete user
+await userRepo.hardDelete(1);
 
-**Example:**
-
-```typescript
-// Soft delete some users
-await userRepo.softDelete(aliceId)
-await userRepo.softDelete(bobId)
-
-// Find only deleted
-const deleted = await userRepo.findDeleted()
-console.log(deleted.length)  // 2 (Alice and Bob)
-console.log(deleted[0].deleted_at)  // Not null
+// Record is gone forever
+const user = await userRepo.findWithDeleted(1); // null
 ```
 
-**Use Cases:**
-- "Trash" or "Recycle Bin" view
-- Deleted items list
-- Cleanup candidates
-- Audit reports
+**Returns**: `Promise<void>`
 
-### findWithDeleted
+#### findWithDeleted(id)
 
-Find a specific record including if soft-deleted.
+Finds a record by ID including soft-deleted records.
 
 ```typescript
-async findWithDeleted(id: number | string): Promise<T | null>
+// Find user even if soft-deleted
+const user = await userRepo.findWithDeleted(1);
+if (user?.deleted_at) {
+  console.log('User was soft-deleted');
+}
 ```
 
-**Example:**
+**Returns**: `Promise<T | null>`
 
-```typescript
-// Soft delete Alice
-await userRepo.softDelete(aliceId)
+#### findAllWithDeleted()
 
-// Normal findById returns null
-const user1 = await userRepo.findById(aliceId)
-console.log(user1)  // null
+Returns all records including soft-deleted ones.
 
-// findWithDeleted returns the record
-const user2 = await userRepo.findWithDeleted(aliceId)
-console.log(user2)  // Alice's record
-console.log(user2.deleted_at)  // Not null
+```typescript
+// Get all users including deleted
+const allUsers = await userRepo.findAllWithDeleted();
+const deletedCount = allUsers.filter(u => u.deleted_at !== null).length;
+console.log(`${deletedCount} deleted users`);
 ```
 
-**Use Cases:**
-- Recovery by ID
-- Audit lookups
-- Admin record inspection
-- Restore confirmation
-
----
+**Returns**: `Promise<T[]>`
 
-## 🎯 Automatic Filtering
+#### findDeleted()
 
-The plugin automatically filters soft-deleted records from queries.
-
-### How It Works
+Returns only soft-deleted records.
 
 ```typescript
-// Behind the scenes, the plugin adds WHERE clause:
-db.selectFrom('users').selectAll()
-
-// Becomes:
-db.selectFrom('users')
-  .selectAll()
-  .where('users.deleted_at', 'is', null)  // Auto-added!
+// Get only deleted users
+const deletedUsers = await userRepo.findDeleted();
+console.log(`Found ${deletedUsers.length} deleted users`);
 ```
 
-### What Gets Filtered
+**Returns**: `Promise<T[]>`
+
+#### softDeleteMany(ids)
 
-**✅ Automatically filtered:**
+Soft deletes multiple records in a single operation (bulk operation).
 
 ```typescript
-// Repository methods
-await userRepo.findAll()         // ✅ Filtered
-await userRepo.findById(1)       // ✅ Filtered
-await userRepo.find({ where: {...} })  // ✅ Filtered
-
-// SELECT queries through ORM
-const result = await orm.applyPlugins(
-  db.selectFrom('users').selectAll(),
-  'select',
-  'users',
-  {}
-).execute()  // ✅ Filtered
+// Soft delete multiple users at once
+const deletedUsers = await userRepo.softDeleteMany([1, 2, 3]);
+console.log(`Soft deleted ${deletedUsers.length} users`);
 ```
 
-**❌ NOT automatically filtered:**
+**Returns**: `Promise<T[]>` - Array of deleted records
+**Throws**: `NotFoundError` if any record doesn't exist
 
-```typescript
-// Direct Kysely queries (bypass ORM)
-await db.selectFrom('users').selectAll().execute()
-// ❌ Not filtered (direct DB access)
+#### restoreMany(ids)
 
-// DELETE operations
-await db.deleteFrom('users').where('id', '=', 1).execute()
-// ❌ Still deletes (not converted to soft delete)
+Restores multiple soft-deleted records in a single operation.
 
-// Custom repository methods
-await userRepo.customMethod()
-// ❌ Not filtered (unless explicitly implemented)
+```typescript
+// Restore multiple users at once
+const restoredUsers = await userRepo.restoreMany([1, 2, 3]);
+console.log(`Restored ${restoredUsers.length} users`);
 ```
 
-### Bypassing Filters
+**Returns**: `Promise<T[]>` - Array of restored records
+
+#### hardDeleteMany(ids)
 
-When you need to include deleted records:
+Permanently deletes multiple records in a single operation.
 
 ```typescript
-// Method 1: Use *WithDeleted methods
-const all = await userRepo.findAllWithDeleted()
-const user = await userRepo.findWithDeleted(userId)
-
-// Method 2: Use metadata flag (with ORM)
-const result = await orm.applyPlugins(
-  db.selectFrom('users').selectAll(),
-  'select',
-  'users',
-  { includeDeleted: true }  // ✅ Include deleted
-).execute()
-
-// Method 3: Direct Kysely query (bypass plugin)
-const all = await db.selectFrom('users').selectAll().execute()
+// Permanently delete multiple users
+await userRepo.hardDeleteMany([1, 2, 3]);
 ```
 
----
+**Returns**: `Promise<void>`
 
-## 🔧 Advanced Usage
+## DAL Integration
 
-### Multiple Plugins
+The soft-delete plugin works seamlessly with the DAL pattern through the executor layer.
 
-Combine soft delete with other plugins:
+### Automatic Filtering in DAL Queries
 
 ```typescript
-import { softDeletePlugin } from '@kysera/soft-delete'
-import { timestampsPlugin } from '@kysera/timestamps'
-import { auditPlugin } from '@kysera/audit'
+import { createExecutor } from '@kysera/executor';
+import { createContext, createQuery } from '@kysera/dal';
 
-const orm = await createORM(db, [
-  timestampsPlugin(),     // Auto timestamps
-  softDeletePlugin(),     // Soft delete
-  auditPlugin({ userId }) // Audit logging
-])
-
-// All plugins work together:
-await userRepo.softDelete(userId)
-// ✅ deleted_at timestamp set
-// ✅ updated_at timestamp updated (timestamps plugin)
-// ✅ Audit log created (audit plugin)
-```
-
-### Transaction Support
+const executor = await createExecutor(db, [softDeletePlugin()]);
 
-Soft deletes work seamlessly with transactions:
-
-```typescript
-await db.transaction().execute(async (trx) => {
-  const txRepo = userRepo.withTransaction(trx)
-
-  // Soft delete in transaction
-  await txRepo.softDelete(userId)
+// Define queries - filter applied automatically
+const getAllUsers = createQuery((ctx) =>
+  ctx.db.selectFrom('users').selectAll().execute()
+);
 
-  // Other operations
-  await txRepo.create({ email: 'new@example.com', name: 'New User' })
+const getUserById = createQuery((ctx, id: number) =>
+  ctx.db
+    .selectFrom('users')
+    .selectAll()
+    .where('id', '=', id)
+    .executeTakeFirst()
+);
 
-  // If transaction fails, soft delete is rolled back
-})
+// Execute queries
+const ctx = createContext(executor);
+const users = await getAllUsers(ctx); // Excludes deleted
+const user = await getUserById(ctx, 1);
 ```
 
-### Batch Operations
+### Query Interception
 
-The plugin provides efficient batch operations for handling multiple records:
+The plugin's `interceptQuery` method modifies SELECT query builders:
 
 ```typescript
-// ✅ Efficient: Single query batch operations
-const userIds = [1, 2, 3, 4, 5]
-
-// Soft delete multiple records (single UPDATE query)
-const deletedUsers = await userRepo.softDeleteMany(userIds)
-console.log(deletedUsers.length)  // 5
-
-// Restore multiple records (single UPDATE query)
-const restoredUsers = await userRepo.restoreMany(userIds)
-console.log(restoredUsers.length)  // 5
+// Original query
+ctx.db.selectFrom('users').selectAll()
 
-// Hard delete multiple records (single DELETE query)
-await userRepo.hardDeleteMany(userIds)
-
-// ❌ Inefficient: Loop approach (N queries)
-for (const id of userIds) {
-  await userRepo.softDelete(id)  // 5 separate UPDATE queries
-}
+// After plugin interception
+ctx.db
+  .selectFrom('users')
+  .selectAll()
+  .where('users.deleted_at', 'is', null) // Added automatically
 ```
 
-**Performance Comparison:**
-- Loop: 100 records = 100 queries (~2000ms)
-- Batch: 100 records = 1 query (~20ms)
-- **100x faster! 🚀**
+### Operations Not Intercepted
 
-**See [BATCH_OPERATIONS.md](./BATCH_OPERATIONS.md) for detailed documentation.**
+The plugin uses Method Override pattern, not full query interception:
 
-### Conditional Soft Delete
+- **SELECT queries**: Automatically filtered
+- **INSERT queries**: Not affected
+- **UPDATE queries**: Not affected
+- **DELETE queries**: NOT converted to soft deletes
+
+To perform soft deletes, use the `softDelete()` method explicitly:
 
 ```typescript
-// Only soft delete if certain conditions met
-async function conditionalDelete(userId: number) {
-  const user = await userRepo.findById(userId)
+import { sql } from 'kysely';
 
-  if (!user) {
-    throw new Error('User not found')
-  }
+// ❌ This performs a real DELETE (not soft delete)
+await ctx.db.deleteFrom('users').where('id', '=', 1).execute();
 
-  // Check if user has important data
-  const hasOrders = await db
-    .selectFrom('orders')
-    .select('id')
-    .where('user_id', '=', userId)
-    .executeTakeFirst()
+// ✅ Use softDelete method instead (in Repository pattern)
+await userRepo.softDelete(1);
 
-  if (hasOrders) {
-    // Soft delete (preserve for order history)
-    await userRepo.softDelete(userId)
-  } else {
-    // Hard delete (no dependencies)
-    await userRepo.hardDelete(userId)
-  }
-}
+// ✅ Or manual UPDATE in DAL pattern
+await ctx.db
+  .updateTable('users')
+  .set({ deleted_at: sql`CURRENT_TIMESTAMP` })
+  .where('id', '=', 1)
+  .execute();
 ```
 
-### Cleanup Old Soft-Deleted Records
+### DAL Transaction Support
 
 ```typescript
-// Delete records soft-deleted more than 30 days ago
-async function cleanupOldDeleted() {
-  const thirtyDaysAgo = new Date()
-  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30)
+import { withTransaction } from '@kysera/dal';
+import { sql } from 'kysely';
 
-  const oldDeleted = await db
+await withTransaction(executor, async (txCtx) => {
+  // Soft delete user
+  await txCtx.db
+    .updateTable('users')
+    .set({ deleted_at: sql`CURRENT_TIMESTAMP` })
+    .where('id', '=', 1)
+    .execute();
+
+  // Query in same transaction sees deletion
+  const users = await txCtx.db
     .selectFrom('users')
     .selectAll()
-    .where('deleted_at', 'is not', null)
-    .where('deleted_at', '<', thirtyDaysAgo.toISOString())
-    .execute()
-
-  for (const user of oldDeleted) {
-    await userRepo.hardDelete(user.id)
-  }
+    .execute(); // User 1 excluded
 
-  console.log(`Cleaned up ${oldDeleted.length} old records`)
-}
+  // If transaction rolls back, soft delete is also rolled back
+});
 ```
 
----
-
-## 🗄️ Multi-Database Support
+## Transaction Behavior
 
-The plugin works across PostgreSQL, MySQL, and SQLite.
+The soft-delete plugin respects ACID properties and works correctly with transactions.
 
-### PostgreSQL
+### ACID Compliance
 
 ```typescript
-// Schema
-CREATE TABLE users (
-  id SERIAL PRIMARY KEY,
-  email VARCHAR(255) NOT NULL,
-  name VARCHAR(255) NOT NULL,
-  created_at TIMESTAMP DEFAULT NOW(),
-  deleted_at TIMESTAMP NULL  -- TIMESTAMP column
-);
+import { withTransaction } from '@kysera/dal';
 
-// Plugin uses CURRENT_TIMESTAMP (native PostgreSQL)
-const plugin = softDeletePlugin({
-  deletedAtColumn: 'deleted_at'
-})
+// ✅ CORRECT: Soft delete commits with transaction
+await withTransaction(executor, async (txCtx) => {
+  const repos = createRepositories(txCtx); // Use transaction executor
+  await repos.users.softDelete(1);
+  await repos.posts.softDeleteMany([1, 2, 3]);
+  // If transaction commits, both operations commit
+  // If transaction rolls back, both operations roll back
+});
 ```
 
-### MySQL
+### Rollback Behavior
 
 ```typescript
-// Schema
-CREATE TABLE users (
-  id INT AUTO_INCREMENT PRIMARY KEY,
-  email VARCHAR(255) NOT NULL,
-  name VARCHAR(255) NOT NULL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  deleted_at DATETIME NULL  -- DATETIME column
-);
+try {
+  await withTransaction(executor, async (txCtx) => {
+    const repos = createRepositories(txCtx);
 
-// Plugin uses CURRENT_TIMESTAMP (native MySQL)
-const plugin = softDeletePlugin({
-  deletedAtColumn: 'deleted_at'
-})
-```
-
-### SQLite
-
-```typescript
-// Schema (TEXT for timestamps)
-CREATE TABLE users (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  email TEXT NOT NULL,
-  name TEXT NOT NULL,
-  created_at TEXT DEFAULT (datetime('now')),
-  deleted_at TEXT NULL  -- TEXT column for timestamp
-);
+    // Soft delete user
+    await repos.users.softDelete(1);
 
-// Or INTEGER for Unix timestamp
-CREATE TABLE users (
-  ...
-  deleted_at INTEGER NULL  -- Unix timestamp
-);
+    // Force rollback
+    throw new Error('Force rollback');
+  });
+} catch (error) {
+  // Transaction rolled back
+}
 
-// Plugin uses CURRENT_TIMESTAMP (SQLite compatible)
-const plugin = softDeletePlugin({
-  deletedAtColumn: 'deleted_at'
-})
+// Verify soft-delete was rolled back
+const user = await userRepo.findById(1);
+console.log(user?.deleted_at); // null (not deleted)
 ```
 
-### Database-Specific Behavior
+### Cascade Soft Delete Pattern
 
-| Feature | PostgreSQL | MySQL | SQLite |
-|---------|-----------|-------|--------|
-| **Timestamp Format** | TIMESTAMP | DATETIME | TEXT or INTEGER |
-| **NULL Handling** | ✅ Native | ✅ Native | ✅ Native |
-| **CURRENT_TIMESTAMP** | ✅ Supported | ✅ Supported | ✅ Supported |
-| **Index on deleted_at** | ✅ Recommended | ✅ Recommended | ✅ Recommended |
-
----
-
-## 🎨 Type Safety
-
-The plugin is fully type-safe with TypeScript.
-
-### Extended Repository Interface
+The plugin does not automatically cascade soft deletes. You must implement cascade patterns manually:
 
 ```typescript
-interface SoftDeleteRepository<T> extends Repository<T> {
-  softDelete(id: number | string): Promise<T>
-  restore(id: number | string): Promise<T>
-  hardDelete(id: number | string): Promise<void>
-  findAllWithDeleted(): Promise<T[]>
-  findDeleted(): Promise<T[]>
-  findWithDeleted(id: number | string): Promise<T | null>
-}
-
-// Type-safe usage
-const userRepo: SoftDeleteRepository<User> = orm.createRepository(/* ... */)
-
-// ✅ Type-safe calls
-const user: User = await userRepo.softDelete(1)
-const deleted: User[] = await userRepo.findDeleted()
-
-// ❌ Type error
-await userRepo.softDelete('invalid')  // Error: string not assignable to number
-```
-
-### Database Schema Types
+// Manual cascade soft delete
+await db.transaction().execute(async (trx) => {
+  const repos = createRepositories(trx);
+  const userId = 123;
+
+  // Step 1: Find related records
+  const userPosts = await repos.posts.findBy({ user_id: userId });
+  const postIds = userPosts.map(p => p.id);
+
+  // Step 2: Soft delete children first
+  if (postIds.length > 0) {
+    const postComments = await repos.comments.findBy({
+      post_id: { in: postIds }
+    });
+    const commentIds = postComments.map(c => c.id);
+
+    if (commentIds.length > 0) {
+      await repos.comments.softDeleteMany(commentIds);
+    }
 
-```typescript
-import type { Generated } from 'kysely'
-
-interface Database {
-  users: {
-    id: Generated<number>
-    email: string
-    name: string
-    created_at: Generated<Date>
-    deleted_at: Date | null  // ✅ Must be nullable
+    await repos.posts.softDeleteMany(postIds);
   }
-}
 
-// TypeScript ensures deleted_at is nullable
-const plugin = softDeletePlugin({
-  deletedAtColumn: 'deleted_at'  // ✅ Must exist in schema
-})
+  // Step 3: Soft delete parent
+  await repos.users.softDelete(userId);
+});
 ```
 
----
-
-## 📖 API Reference
+### Transaction Isolation
 
-### softDeletePlugin(options?)
-
-Creates a soft delete plugin instance.
-
-**Parameters:**
+Soft-delete operations within a transaction are immediately visible to subsequent queries in the same transaction:
 
 ```typescript
-interface SoftDeleteOptions {
-  deletedAtColumn?: string    // Default: 'deleted_at'
-  includeDeleted?: boolean    // Default: false
-  tables?: string[]           // Default: undefined (all tables)
-  primaryKeyColumn?: string   // Default: 'id'
-  logger?: KyseraLogger       // Default: silentLogger (no output)
-}
-```
-
-**Returns:** `Plugin` instance
-
-**Example:**
-
-```typescript
-const plugin = softDeletePlugin({
-  deletedAtColumn: 'deleted_at',
-  tables: ['users', 'posts']
-})
-```
-
----
-
-### Repository Methods
-
-#### softDelete(id)
-
-Soft delete a record by ID.
-
-**Parameters:**
-- `id: number | string` - Record ID
-
-**Returns:** `Promise<T>` - The soft-deleted record
-
-**Throws:** Error if record not found
-
----
-
-#### restore(id)
-
-Restore a soft-deleted record.
-
-**Parameters:**
-- `id: number | string` - Record ID
-
-**Returns:** `Promise<T>` - The restored record
+await withTransaction(executor, async (txCtx) => {
+  const repos = createRepositories(txCtx);
 
----
+  // Before soft delete
+  const usersBefore = await repos.users.findAll();
+  console.log(usersBefore.length); // 10
 
-#### hardDelete(id)
-
-Permanently delete a record.
-
-**Parameters:**
-- `id: number | string` - Record ID
-
-**Returns:** `Promise<void>`
-
----
-
-#### findAllWithDeleted()
-
-Find all records including soft-deleted.
-
-**Returns:** `Promise<T[]>`
-
----
-
-#### findDeleted()
-
-Find only soft-deleted records.
-
-**Returns:** `Promise<T[]>`
-
----
-
-#### findWithDeleted(id)
-
-Find a record by ID including if soft-deleted.
-
-**Parameters:**
-- `id: number | string` - Record ID
-
-**Returns:** `Promise<T | null>`
+  // Soft delete user
+  await repos.users.softDelete(1);
 
----
-
-#### softDeleteMany(ids)
-
-Soft delete multiple records in a single query.
-
-**Parameters:**
-- `ids: (number | string)[]` - Array of record IDs
-
-**Returns:** `Promise<T[]>` - Array of soft-deleted records
-
-**Throws:** Error if any record not found
-
-**Example:**
-```typescript
-const deletedUsers = await userRepo.softDeleteMany([1, 2, 3, 4, 5])
-console.log(deletedUsers.length)  // 5
+  // Immediately visible in same transaction
+  const usersAfter = await repos.users.findAll();
+  console.log(usersAfter.length); // 9
+});
 ```
 
----
-
-#### restoreMany(ids)
+## Database Schema Requirements
 
-Restore multiple soft-deleted records in a single query.
+Your database tables need a `deleted_at` column (or custom column name) to support soft delete:
 
-**Parameters:**
-- `ids: (number | string)[]` - Array of record IDs
-
-**Returns:** `Promise<T[]>` - Array of restored records
+```sql
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY,
+  email TEXT NOT NULL,
+  name TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  deleted_at TIMESTAMP NULL -- Required for soft delete
+);
 
-**Example:**
-```typescript
-const restoredUsers = await userRepo.restoreMany([1, 2, 3])
-console.log(restoredUsers.every(u => u.deleted_at === null))  // true
+CREATE INDEX idx_users_deleted_at ON users(deleted_at);
 ```
 
----
-
-#### hardDeleteMany(ids)
-
-Permanently delete multiple records in a single query.
-
-**Parameters:**
-- `ids: (number | string)[]` - Array of record IDs
+### Custom Column Name
 
-**Returns:** `Promise<void>`
-
-**Example:**
-```typescript
-await userRepo.hardDeleteMany([1, 2, 3])
-// Records permanently removed from database
+```sql
+CREATE TABLE posts (
+  id INTEGER PRIMARY KEY,
+  title TEXT NOT NULL,
+  content TEXT,
+  removed_at TIMESTAMP NULL -- Custom name
+);
 ```
 
----
-
-## ✨ Best Practices
-
-### 1. Always Use Nullable deleted_at
-
 ```typescript
-// ✅ Good: deleted_at is nullable
-interface Database {
-  users: {
-    id: Generated<number>
-    deleted_at: Date | null  // ✅ Can be null
-  }
-}
-
-// ❌ Bad: deleted_at not nullable
-interface Database {
-  users: {
-    deleted_at: Date  // ❌ Must always have value
-  }
-}
+// Configure plugin to use custom column
+softDeletePlugin({
+  deletedAtColumn: 'removed_at',
+  tables: ['posts']
+});
 ```
 
-### 2. Index deleted_at Column
+### Custom Primary Key
 
 ```sql
--- ✅ Good: Index for performance
-CREATE INDEX idx_users_deleted_at ON users(deleted_at);
-
--- Even better: Partial index (PostgreSQL)
-CREATE INDEX idx_users_not_deleted ON users(id)
-WHERE deleted_at IS NULL;
+CREATE TABLE comments (
+  comment_id INTEGER PRIMARY KEY, -- Custom primary key
+  content TEXT NOT NULL,
+  deleted_at TIMESTAMP NULL
+);
 ```
 
-### 3. Use Explicit Method Names
-
 ```typescript
-// ✅ Good: Clear intent
-await userRepo.softDelete(userId)     // Soft delete
-await userRepo.hardDelete(userId)     // Hard delete
-
-// ❌ Confusing: What does delete do?
-await userRepo.delete(userId)  // Soft or hard delete?
+// Configure plugin to use custom primary key
+softDeletePlugin({
+  primaryKeyColumn: 'comment_id',
+  tables: ['comments']
+});
 ```
 
-### 4. Clean Up Old Soft-Deleted Records
+## Type Safety
 
-```typescript
-// ✅ Good: Regular cleanup
-async function cleanup() {
-  const cutoff = new Date()
-  cutoff.setDate(cutoff.getDate() - 90)  // 90 days ago
-
-  const old = await db
-    .selectFrom('users')
-    .selectAll()
-    .where('deleted_at', '<', cutoff.toISOString())
-    .where('deleted_at', 'is not', null)
-    .execute()
-
-  for (const user of old) {
-    await userRepo.hardDelete(user.id)
-  }
-}
-```
-
-### 5. Consider Cascade Behavior
+The plugin maintains full type safety with TypeScript:
 
 ```typescript
-// When soft deleting, consider related records
-async function softDeleteUserWithData(userId: number) {
-  await db.transaction().execute(async (trx) => {
-    const txUserRepo = userRepo.withTransaction(trx)
-    const txPostRepo = postRepo.withTransaction(trx)
+import type { SoftDeleteRepository } from '@kysera/soft-delete';
 
-    // Soft delete user
-    await txUserRepo.softDelete(userId)
+// Extend repository type with soft delete methods
+type UserRepository = SoftDeleteRepository<User>;
 
-    // Also soft delete their posts
-    const posts = await db
-      .selectFrom('posts')
-      .selectAll()
-      .where('user_id', '=', userId)
-      .execute()
+const userRepo: UserRepository = orm.createRepository((executor) => {
+  const base = createRepositoryFactory(executor);
+  return base.create({
+    tableName: 'users',
+    mapRow: (row) => row as User
+  });
+});
 
-    for (const post of posts) {
-      await txPostRepo.softDelete(post.id)
-    }
-  })
-}
+// TypeScript knows about soft delete methods
+const deletedUser: User = await userRepo.softDelete(1);
+const allUsers: User[] = await userRepo.findAllWithDeleted();
+const deletedUsers: User[] = await userRepo.findDeleted();
 ```
 
-### 6. Implement Restore Validation
+## Error Handling
 
-```typescript
-// ✅ Good: Validate before restore
-async function safeRestore(userId: number) {
-  const user = await userRepo.findWithDeleted(userId)
+The plugin uses error types from `@kysera/core`:
 
-  if (!user) {
-    throw new Error('User not found')
-  }
+```typescript
+import { NotFoundError } from '@kysera/core';
 
-  if (!user.deleted_at) {
-    throw new Error('User is not deleted')
+try {
+  await userRepo.softDelete(999); // Non-existent ID
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.error('User not found:', error.metadata);
+    // error.metadata = { id: 999 }
   }
+}
 
-  // Check if restore is allowed
-  const daysSinceDeleted = Math.floor(
-    (Date.now() - new Date(user.deleted_at).getTime()) / (1000 * 60 * 60 * 24)
-  )
-
-  if (daysSinceDeleted > 30) {
-    throw new Error('Cannot restore: deleted more than 30 days ago')
+try {
+  await userRepo.softDeleteMany([1, 2, 999]); // One ID doesn't exist
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.error('Some users not found:', error.metadata);
+    // error.metadata = { ids: [999] }
   }
-
-  return await userRepo.restore(userId)
 }
 ```
 
-### 7. Use Table Filtering Wisely
-
-```typescript
-// ✅ Good: Only user-facing tables
-const plugin = softDeletePlugin({
-  tables: ['users', 'posts', 'comments', 'orders']
-})
-
-// ❌ Bad: Including system tables
-const plugin = softDeletePlugin({
-  tables: ['users', 'posts', 'migrations', 'sessions']
-  // migrations and sessions shouldn't need soft delete
-})
-```
-
----
+## Performance Considerations
 
-## ⚡ Performance
+### Index Requirements
 
-### Plugin Overhead
+Always add an index on the `deleted_at` column for optimal query performance:
 
-| Operation | Base | With Soft Delete | Overhead |
-|-----------|------|------------------|----------|
-| **create** | 2ms | 2ms | 0ms |
-| **findById** | 1ms | 1.1ms | +0.1ms |
-| **findAll** | 15ms | 15.2ms | +0.2ms |
-| **softDelete** | - | 2ms | N/A |
-| **restore** | - | 2ms | N/A |
+```sql
+CREATE INDEX idx_users_deleted_at ON users(deleted_at);
+CREATE INDEX idx_posts_deleted_at ON posts(deleted_at);
+```
 
 ### Query Performance
 
-```typescript
-// Without index on deleted_at
-SELECT * FROM users WHERE deleted_at IS NULL
-// Full table scan: O(n)
+The plugin adds a `WHERE deleted_at IS NULL` condition to all SELECT queries. With proper indexing, this has minimal performance impact.
 
-// With index on deleted_at
-CREATE INDEX idx_users_deleted_at ON users(deleted_at);
-// Index scan: O(log n)
+```sql
+-- Without index: Full table scan
+SELECT * FROM users WHERE deleted_at IS NULL;
 
-// Even better: Partial index (PostgreSQL only)
-CREATE INDEX idx_users_not_deleted ON users(id)
-WHERE deleted_at IS NULL;
-// Smallest index, fastest queries for non-deleted records
+-- With index: Index scan (fast)
+CREATE INDEX idx_users_deleted_at ON users(deleted_at);
+SELECT * FROM users WHERE deleted_at IS NULL;
 ```
 
-### Bundle Size
+### Bulk Operations
 
-```
-@kysera/soft-delete: 477 B (minified)
-├── softDeletePlugin: 350 B
-├── Type definitions: 77 B
-└── Repository extensions: 50 B
-```
+Use bulk methods for better performance when operating on multiple records:
 
----
+```typescript
+// ❌ Inefficient: N queries
+for (const id of userIds) {
+  await userRepo.softDelete(id);
+}
 
-## 🔧 Troubleshooting
+// ✅ Efficient: Single query
+await userRepo.softDeleteMany(userIds);
+```
 
-### Records Not Filtered Out
+## Architecture Notes
 
-**Problem:** Soft-deleted records still appear in queries.
+### Method Override Pattern
 
-**Solutions:**
+The plugin uses Method Override, not full query interception:
 
-1. **Check plugin is registered:**
-```typescript
-// ❌ No plugin
-const orm = await createORM(db, [])
+- **SELECT queries**: Automatically filtered using `interceptQuery`
+- **DELETE operations**: NOT automatically converted to soft deletes
+- Use `softDelete()` method explicitly instead of `delete()`
+- Use `hardDelete()` method to bypass soft delete and perform real DELETE
 
-// ✅ Plugin registered
-const orm = await createORM(db, [softDeletePlugin()])
-```
+This design is intentional for simplicity and explicitness.
 
-2. **Check table is included:**
-```typescript
-// Check configuration
-const plugin = softDeletePlugin({
-  tables: ['posts']  // ❌ 'users' not included!
-})
-
-// Fix: Add 'users'
-const plugin = softDeletePlugin({
-  tables: ['users', 'posts']  // ✅ Both included
-})
-```
+### Plugin Execution Flow
 
-3. **Check using ORM-created repository:**
-```typescript
-// ❌ Wrong: Direct factory (no plugins)
-const factory = createRepositoryFactory(db)
-const repo = factory.create(/* ... */)
-
-// ✅ Correct: ORM with plugins
-const orm = await createORM(db, [softDeletePlugin()])
-const repo = orm.createRepository((executor) => {
-  const factory = createRepositoryFactory(executor)
-  return factory.create(/* ... */)
-})
-```
+1. Plugin is registered with `createORM()` or `createExecutor()`
+2. `interceptQuery()` modifies SELECT query builders to add `WHERE deleted_at IS NULL`
+3. `extendRepository()` adds soft delete methods to repositories (Repository pattern only)
+4. Query execution flows through the executor with plugin interception applied
 
-### softDelete Method Not Available
+### Raw Database Access
 
-**Problem:** `repo.softDelete` is undefined.
+The plugin uses `getRawDb()` to access the underlying Kysely instance without plugin interception. This is necessary for:
 
-**Solution:** Ensure you're using the ORM-created repository:
+- `findWithDeleted()`: Needs to see soft-deleted records
+- `findAllWithDeleted()`: Needs to see all records
+- `findDeleted()`: Needs to query deleted records specifically
+- `softDelete()`, `restore()`: Need to fetch records after update
 
 ```typescript
-// ❌ Wrong: Direct repository creation
-const repo = factory.create(/* ... */)
-await repo.softDelete(1)  // ❌ Method doesn't exist
-
-// ✅ Correct: ORM-extended repository
-const orm = await createORM(db, [softDeletePlugin()])
-const repo = orm.createRepository((executor) => {
-  const factory = createRepositoryFactory(executor)
-  return factory.create(/* ... */)
-})
-await repo.softDelete(1)  // ✅ Method exists
-```
-
-### Restore Not Working
-
-**Problem:** `restore()` doesn't bring back the record.
+import { getRawDb } from '@kysera/executor';
 
-**Solution:** Check if record was hard-deleted:
+// Inside plugin
+const rawDb = getRawDb(repo.executor);
 
-```typescript
-// Check if record exists at all
-const user = await db
+// Bypass soft-delete filter
+const allRecords = await rawDb
   .selectFrom('users')
   .selectAll()
-  .where('id', '=', userId)
-  .executeTakeFirst()
-
-if (!user) {
-  // Record was hard-deleted, cannot restore
-  console.error('Record permanently deleted')
-} else if (user.deleted_at) {
-  // Record is soft-deleted, can restore
-  await userRepo.restore(userId)
-} else {
-  // Record is not deleted
-  console.error('Record is not deleted')
-}
+  .execute();
 ```
 
-### Performance Issues
+## Testing
 
-**Problem:** Queries with soft delete filtering are slow.
+The package includes comprehensive test coverage:
 
-**Solution:** Add indexes:
+```bash
+# Run all tests
+pnpm test
 
-```sql
--- Basic index
-CREATE INDEX idx_users_deleted_at ON users(deleted_at);
+# Run with coverage
+pnpm test:coverage
 
--- Partial index (PostgreSQL - even better)
-CREATE INDEX idx_users_not_deleted ON users(id)
-WHERE deleted_at IS NULL;
+# Run specific test file
+pnpm test soft-delete-repository.test.ts
 
--- Composite index if you filter by other columns
-CREATE INDEX idx_users_status_deleted
-ON users(status, deleted_at);
+# Run DAL integration tests
+pnpm test dal-integration.test.ts
 ```
 
----
-
-## 🤝 Contributing
-
-Contributions are welcome! This package follows strict development principles:
-
-- ✅ **Minimal dependencies** (@kysera/repository only)
-- ✅ **100% type safe** (TypeScript strict mode)
-- ✅ **95%+ test coverage** (39+ tests)
-- ✅ **Multi-database tested** (PostgreSQL, MySQL, SQLite)
-- ✅ **ESM only** (no CommonJS)
-
-See [CLAUDE.md](../../CLAUDE.md) for development guidelines.
-
----
-
-## 📄 License
+Test files:
+- `test/dal-integration.test.ts` - DAL pattern with createQuery and withTransaction
+- `test/soft-delete-comprehensive.test.ts` - All 9 methods + configuration options
+- `test/soft-delete-repository.test.ts` - Repository pattern core functionality
+- `test/soft-delete-edge-cases.test.ts` - Edge cases and error handling
+- `test/batch-operations.test.ts` - Bulk operation tests (softDeleteMany, etc.)
+- `test/custom-primary-key.test.ts` - Custom primary key column support
+- `test/soft-delete-custom-keys.test.ts` - Custom column name configurations
+- `test/soft-delete-operations.test.ts` - Core soft delete operations
+- `test/soft-delete.test.ts` - Basic soft delete functionality
+- `test/soft-delete-plugin-interaction.test.ts` - Plugin interaction tests
+- `test/multi-db.test.ts` - Multi-database compatibility (PostgreSQL, MySQL, SQLite)
 
-MIT © Kysera
+## License
 
----
+MIT
 
-## 🔗 Links
+## Contributing
 
-- [GitHub Repository](https://github.com/kysera-dev/kysera)
-- [@kysera/repository Documentation](../repository/README.md)
-- [@kysera/core Documentation](../core/README.md)
-- [Kysely Documentation](https://kysely.dev)
-- [Issue Tracker](https://github.com/kysera-dev/kysera/issues)
+See the main [Kysera repository](https://github.com/kysera-dev/kysera) for contribution guidelines.
 
----
+## Links
 
-**Built with ❤️ for safe, recoverable data management**
+- [Documentation](https://kysera.dev)
+- [GitHub](https://github.com/kysera-dev/kysera)
+- [Issues](https://github.com/kysera-dev/kysera/issues)
+- [NPM](https://www.npmjs.com/package/@kysera/soft-delete)