@kysera/soft-delete 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LuxQuant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+import { Plugin } from '@kysera/repository';
+
+/**
+ * Configuration options for the soft delete plugin.
+ *
+ * @example
+ * ```typescript
+ * const plugin = softDeletePlugin({
+ *   deletedAtColumn: 'deleted_at',
+ *   includeDeleted: false,
+ *   tables: ['users', 'posts'] // Only these tables support soft delete
+ * })
+ * ```
+ */
+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[];
+}
+/**
+ * Soft Delete Plugin for Kysera ORM
+ *
+ * This plugin implements soft delete functionality using the Method Override pattern:
+ * - Automatically filters out soft-deleted records from SELECT queries
+ * - Adds softDelete(), restore(), and hardDelete() methods to repositories
+ * - Provides findWithDeleted() and findDeleted() utility methods
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { softDeletePlugin } from '@kysera/soft-delete'
+ * import { createORM } from '@kysera/repository'
+ *
+ * const orm = await createORM(db, [
+ *   softDeletePlugin({
+ *     deletedAtColumn: 'deleted_at',
+ *     tables: ['users', 'posts']
+ *   })
+ * ])
+ *
+ * const userRepo = orm.createRepository(createUserRepository)
+ *
+ * // Soft delete a user (sets deleted_at)
+ * await userRepo.softDelete(1)
+ *
+ * // Find all users (excludes soft-deleted)
+ * await userRepo.findAll()
+ *
+ * // Find including deleted
+ * await userRepo.findAllWithDeleted()
+ *
+ * // Restore a soft-deleted user
+ * await userRepo.restore(1)
+ *
+ * // Permanently delete (real DELETE)
+ * await userRepo.hardDelete(1)
+ * ```
+ *
+ * ## Architecture Note
+ *
+ * This plugin uses Method Override, not full query interception:
+ * - ✅ SELECT queries are automatically filtered
+ * - ❌ DELETE queries are NOT automatically converted to soft deletes
+ * - Use softDelete() method explicitly instead of delete()
+ *
+ * This design is intentional for simplicity and explicitness.
+ *
+ * @param options - Configuration options for soft delete behavior
+ * @returns Plugin instance that can be used with createORM
+ */
+declare const softDeletePlugin: (options?: SoftDeleteOptions) => Plugin;
+
+export { type SoftDeleteOptions, softDeletePlugin };

package/dist/index.js

@@ -0,0 +1,2 @@
+import {sql}from'kysely';var y=(u={})=>{let{deletedAtColumn:t="deleted_at",includeDeleted:o=false,tables:s}=u;return {name:"@kysera/soft-delete",version:"1.0.0",interceptQuery(r,e){return (!s||s.includes(e.table))&&e.operation==="select"&&!e.metadata.includeDeleted&&!o?r.where(`${e.table}.${t}`,"is",null):r},extendRepository(r){let e=r;if(!("tableName"in e)||!("executor"in e)||!(!s||s.includes(e.tableName)))return r;let a=e.findAll.bind(e),l=e.findById.bind(e);return {...e,async findAll(){return o?await a():await e.executor.selectFrom(e.tableName).selectAll().where(t,"is",null).execute()},async findById(n){return o?await l(n):await e.executor.selectFrom(e.tableName).selectAll().where("id","=",n).where(t,"is",null).executeTakeFirst()??null},async softDelete(n){await e.executor.updateTable(e.tableName).set({[t]:sql`CURRENT_TIMESTAMP`}).where("id","=",n).execute();let i=await l(n);if(!i)throw new Error(`Record with id ${n} not found`);return i},async restore(n){return await e.update(n,{[t]:null})},async hardDelete(n){await e.executor.deleteFrom(e.tableName).where("id","=",n).execute();},async findWithDeleted(n){return await l(n)},async findAllWithDeleted(){return await a()},async findDeleted(){return await e.executor.selectFrom(e.tableName).selectAll().where(t,"is not",null).execute()}}}}};export{y as softDeletePlugin};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["softDeletePlugin","options","deletedAtColumn","includeDeleted","tables","qb","context","repo","baseRepo","originalFindAll","originalFindById","id","sql","record"],"mappings":"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","file":"index.js","sourcesContent":["import type { Plugin, AnyQueryBuilder } from '@kysera/repository'\nimport type { SelectQueryBuilder, Kysely } from 'kysely'\nimport { sql } from 'kysely'\n\n/**\n * Configuration options for the soft delete plugin.\n *\n * @example\n * ```typescript\n * const plugin = softDeletePlugin({\n *   deletedAtColumn: 'deleted_at',\n *   includeDeleted: false,\n *   tables: ['users', 'posts'] // Only these tables support soft delete\n * })\n * ```\n */\nexport interface SoftDeleteOptions {\n  /**\n   * Column name for soft delete timestamp.\n   *\n   * @default 'deleted_at'\n   */\n  deletedAtColumn?: string\n\n  /**\n   * Include deleted records by default in queries.\n   * When false, soft-deleted records are automatically filtered out.\n   *\n   * @default false\n   */\n  includeDeleted?: boolean\n\n  /**\n   * List of tables that support soft delete.\n   * If not provided, all tables are assumed to support it.\n   *\n   * @example ['users', 'posts', 'comments']\n   */\n  tables?: string[]\n}\n\ninterface BaseRepository {\n  tableName: string\n  executor: Kysely<Record<string, unknown>>\n  findAll: () => Promise<unknown[]>\n  findById: (id: number) => Promise<unknown>\n  update: (id: number, data: Record<string, unknown>) => Promise<unknown>\n}\n\n/**\n * Soft Delete Plugin for Kysera ORM\n *\n * This plugin implements soft delete functionality using the Method Override pattern:\n * - Automatically filters out soft-deleted records from SELECT queries\n * - Adds softDelete(), restore(), and hardDelete() methods to repositories\n * - Provides findWithDeleted() and findDeleted() utility methods\n *\n * ## Usage\n *\n * ```typescript\n * import { softDeletePlugin } from '@kysera/soft-delete'\n * import { createORM } from '@kysera/repository'\n *\n * const orm = await createORM(db, [\n *   softDeletePlugin({\n *     deletedAtColumn: 'deleted_at',\n *     tables: ['users', 'posts']\n *   })\n * ])\n *\n * const userRepo = orm.createRepository(createUserRepository)\n *\n * // Soft delete a user (sets deleted_at)\n * await userRepo.softDelete(1)\n *\n * // Find all users (excludes soft-deleted)\n * await userRepo.findAll()\n *\n * // Find including deleted\n * await userRepo.findAllWithDeleted()\n *\n * // Restore a soft-deleted user\n * await userRepo.restore(1)\n *\n * // Permanently delete (real DELETE)\n * await userRepo.hardDelete(1)\n * ```\n *\n * ## Architecture Note\n *\n * This plugin uses Method Override, not full query interception:\n * - ✅ SELECT queries are automatically filtered\n * - ❌ DELETE queries are NOT automatically converted to soft deletes\n * - Use softDelete() method explicitly instead of delete()\n *\n * This design is intentional for simplicity and explicitness.\n *\n * @param options - Configuration options for soft delete behavior\n * @returns Plugin instance that can be used with createORM\n */\nexport const softDeletePlugin = (options: SoftDeleteOptions = {}): Plugin => {\n  const {\n    deletedAtColumn = 'deleted_at',\n    includeDeleted = false,\n    tables\n  } = options\n\n  return {\n    name: '@kysera/soft-delete',\n    version: '1.0.0',\n\n    /**\n     * Intercept queries to automatically filter soft-deleted records.\n     *\n     * NOTE: This plugin uses the Method Override pattern, not full query interception.\n     * - SELECT queries are automatically filtered to exclude soft-deleted records\n     * - DELETE operations are NOT automatically converted to soft deletes\n     * - Use the softDelete() method instead of delete() to perform soft deletes\n     * - Use hardDelete() method to bypass soft delete and perform a real DELETE\n     *\n     * This approach is simpler and more explicit than full query interception.\n     */\n    interceptQuery<QB extends AnyQueryBuilder>(qb: QB, context: { operation: string; table: string; metadata: Record<string, unknown> }): QB {\n      // Check if table supports soft delete\n      const supportsSoftDelete = !tables || tables.includes(context.table)\n\n      // Only filter SELECT queries when not explicitly including deleted\n      if (\n        supportsSoftDelete &&\n        context.operation === 'select' &&\n        !context.metadata['includeDeleted'] &&\n        !includeDeleted\n      ) {\n        // Add WHERE deleted_at IS NULL to the query builder\n        type GenericSelectQueryBuilder = SelectQueryBuilder<\n          Record<string, unknown>,\n          string,\n          Record<string, unknown>\n        >\n        return (qb as unknown as GenericSelectQueryBuilder)\n          .where(`${context.table}.${deletedAtColumn}` as never, 'is', null) as QB\n      }\n\n      // Note: DELETE operations are NOT intercepted here\n      // Use softDelete() method instead of delete() to perform soft deletes\n      // This is by design - method override is simpler and more explicit\n\n      return qb\n    },\n\n    /**\n     * Extend repository with soft delete methods.\n     *\n     * Adds the following methods to repositories:\n     * - softDelete(id): Marks record as deleted by setting deleted_at timestamp\n     * - restore(id): Restores a soft-deleted record by setting deleted_at to null\n     * - hardDelete(id): Permanently deletes a record (bypasses soft delete)\n     * - findWithDeleted(id): Find a record including soft-deleted ones\n     * - findAllWithDeleted(): Find all records including soft-deleted ones\n     * - findDeleted(): Find only soft-deleted records\n     *\n     * Also overrides findAll() and findById() to automatically filter out\n     * soft-deleted records (unless includeDeleted option is set).\n     */\n    extendRepository<T extends object>(repo: T): T {\n      // Type assertion is safe here as we're checking for BaseRepository properties\n      const baseRepo = repo as unknown as BaseRepository\n\n      // Check if it's actually a repository (has required properties)\n      if (!('tableName' in baseRepo) || !('executor' in baseRepo)) {\n        return repo\n      }\n\n      // Check if table supports soft delete\n      const supportsSoftDelete = !tables || tables.includes(baseRepo.tableName)\n\n      // If table doesn't support soft delete, return unmodified repo\n      if (!supportsSoftDelete) {\n        return repo\n      }\n\n      // Wrap original methods to apply soft delete filtering\n      const originalFindAll = baseRepo.findAll.bind(baseRepo)\n      const originalFindById = baseRepo.findById.bind(baseRepo)\n\n      const extendedRepo = {\n        ...baseRepo,\n\n        // Override base methods to filter soft-deleted records\n        async findAll(): Promise<unknown[]> {\n          if (!includeDeleted) {\n            const result = await baseRepo.executor\n              .selectFrom(baseRepo.tableName)\n              .selectAll()\n              .where(deletedAtColumn as never, 'is', null)\n              .execute()\n            return result as unknown[]\n          }\n          return await originalFindAll()\n        },\n\n        async findById(id: number): Promise<unknown> {\n          if (!includeDeleted) {\n            const result = await baseRepo.executor\n              .selectFrom(baseRepo.tableName)\n              .selectAll()\n              .where('id' as never, '=', id as never)\n              .where(deletedAtColumn as never, 'is', null)\n              .executeTakeFirst()\n            return result ?? null\n          }\n          return await originalFindById(id)\n        },\n\n        async softDelete(id: number): Promise<unknown> {\n          // Use CURRENT_TIMESTAMP directly in SQL to avoid datetime format issues\n          // This works across all databases (MySQL, PostgreSQL, SQLite)\n          // We bypass repository.update() to avoid Zod validation issues with RawBuilder\n          await baseRepo.executor\n            .updateTable(baseRepo.tableName)\n            .set({ [deletedAtColumn]: sql`CURRENT_TIMESTAMP` } as never)\n            .where('id' as never, '=', id as never)\n            .execute()\n\n          // Fetch the updated record to verify it exists\n          const record = await originalFindById(id)\n\n          // If record not found or deleted_at not set, throw error\n          if (!record) {\n            throw new Error(`Record with id ${id} not found`)\n          }\n\n          return record\n        },\n\n        async restore(id: number): Promise<unknown> {\n          return await baseRepo.update(id, { [deletedAtColumn]: null })\n        },\n\n        async hardDelete(id: number): Promise<void> {\n          // Direct hard delete - bypass soft delete\n          await baseRepo.executor\n            .deleteFrom(baseRepo.tableName)\n            .where('id' as never, '=', id as never)\n            .execute()\n        },\n\n        async findWithDeleted(id: number): Promise<unknown> {\n          // Use original method without filtering\n          return await originalFindById(id)\n        },\n\n        async findAllWithDeleted(): Promise<unknown[]> {\n          // Use original method without filtering\n          return await originalFindAll()\n        },\n\n        async findDeleted(): Promise<unknown[]> {\n          const result = await baseRepo.executor\n            .selectFrom(baseRepo.tableName)\n            .selectAll()\n            .where(deletedAtColumn as never, 'is not', null)\n            .execute()\n          return result as unknown[]\n        }\n      }\n\n      return extendedRepo as T\n    }\n  }\n}"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@kysera/soft-delete",
+  "version": "0.3.0",
+  "description": "Soft delete plugin for Kysera ORM",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "kysely": ">=0.28.0"
+  },
+  "dependencies": {
+    "@kysera/repository": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^24.6.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "better-sqlite3": "^12.4.1",
+    "kysely": "^0.28.7",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4",
+    "zod": "^4.1.11"
+  },
+  "keywords": [
+    "kysely",
+    "orm",
+    "soft-delete",
+    "plugin"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omnitron/kysera.git",
+    "directory": "packages/soft-delete"
+  },
+  "bugs": {
+    "url": "https://github.com/omnitron/kysera/issues"
+  },
+  "homepage": "https://github.com/omnitron/kysera#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}

package/src/index.ts

@@ -0,0 +1,271 @@
+import type { Plugin, AnyQueryBuilder } from '@kysera/repository'
+import type { SelectQueryBuilder, Kysely } from 'kysely'
+import { sql } from 'kysely'
+
+/**
+ * Configuration options for the soft delete plugin.
+ *
+ * @example
+ * ```typescript
+ * const plugin = softDeletePlugin({
+ *   deletedAtColumn: 'deleted_at',
+ *   includeDeleted: false,
+ *   tables: ['users', 'posts'] // Only these tables support soft delete
+ * })
+ * ```
+ */
+export 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[]
+}
+
+interface BaseRepository {
+  tableName: string
+  executor: Kysely<Record<string, unknown>>
+  findAll: () => Promise<unknown[]>
+  findById: (id: number) => Promise<unknown>
+  update: (id: number, data: Record<string, unknown>) => Promise<unknown>
+}
+
+/**
+ * Soft Delete Plugin for Kysera ORM
+ *
+ * This plugin implements soft delete functionality using the Method Override pattern:
+ * - Automatically filters out soft-deleted records from SELECT queries
+ * - Adds softDelete(), restore(), and hardDelete() methods to repositories
+ * - Provides findWithDeleted() and findDeleted() utility methods
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { softDeletePlugin } from '@kysera/soft-delete'
+ * import { createORM } from '@kysera/repository'
+ *
+ * const orm = await createORM(db, [
+ *   softDeletePlugin({
+ *     deletedAtColumn: 'deleted_at',
+ *     tables: ['users', 'posts']
+ *   })
+ * ])
+ *
+ * const userRepo = orm.createRepository(createUserRepository)
+ *
+ * // Soft delete a user (sets deleted_at)
+ * await userRepo.softDelete(1)
+ *
+ * // Find all users (excludes soft-deleted)
+ * await userRepo.findAll()
+ *
+ * // Find including deleted
+ * await userRepo.findAllWithDeleted()
+ *
+ * // Restore a soft-deleted user
+ * await userRepo.restore(1)
+ *
+ * // Permanently delete (real DELETE)
+ * await userRepo.hardDelete(1)
+ * ```
+ *
+ * ## Architecture Note
+ *
+ * This plugin uses Method Override, not full query interception:
+ * - ✅ SELECT queries are automatically filtered
+ * - ❌ DELETE queries are NOT automatically converted to soft deletes
+ * - Use softDelete() method explicitly instead of delete()
+ *
+ * This design is intentional for simplicity and explicitness.
+ *
+ * @param options - Configuration options for soft delete behavior
+ * @returns Plugin instance that can be used with createORM
+ */
+export const softDeletePlugin = (options: SoftDeleteOptions = {}): Plugin => {
+  const {
+    deletedAtColumn = 'deleted_at',
+    includeDeleted = false,
+    tables
+  } = options
+
+  return {
+    name: '@kysera/soft-delete',
+    version: '1.0.0',
+
+    /**
+     * Intercept queries to automatically filter soft-deleted records.
+     *
+     * NOTE: This plugin uses the Method Override pattern, not full query interception.
+     * - SELECT queries are automatically filtered to exclude soft-deleted records
+     * - DELETE operations are NOT automatically converted to soft deletes
+     * - Use the softDelete() method instead of delete() to perform soft deletes
+     * - Use hardDelete() method to bypass soft delete and perform a real DELETE
+     *
+     * This approach is simpler and more explicit than full query interception.
+     */
+    interceptQuery<QB extends AnyQueryBuilder>(qb: QB, context: { operation: string; table: string; metadata: Record<string, unknown> }): QB {
+      // Check if table supports soft delete
+      const supportsSoftDelete = !tables || tables.includes(context.table)
+
+      // 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
+        type GenericSelectQueryBuilder = SelectQueryBuilder<
+          Record<string, unknown>,
+          string,
+          Record<string, unknown>
+        >
+        return (qb as unknown as GenericSelectQueryBuilder)
+          .where(`${context.table}.${deletedAtColumn}` as never, 'is', null) as QB
+      }
+
+      // Note: DELETE operations are NOT intercepted here
+      // Use softDelete() method instead of delete() to perform soft deletes
+      // This is by design - method override is simpler and more explicit
+
+      return qb
+    },
+
+    /**
+     * Extend repository with soft delete methods.
+     *
+     * Adds the following methods to repositories:
+     * - softDelete(id): Marks record as deleted by setting deleted_at timestamp
+     * - restore(id): Restores a soft-deleted record by setting deleted_at to null
+     * - hardDelete(id): Permanently deletes a record (bypasses soft delete)
+     * - findWithDeleted(id): Find a record including soft-deleted ones
+     * - findAllWithDeleted(): Find all records including soft-deleted ones
+     * - findDeleted(): Find only soft-deleted records
+     *
+     * Also overrides findAll() and findById() to automatically filter out
+     * soft-deleted records (unless includeDeleted option is set).
+     */
+    extendRepository<T extends object>(repo: T): T {
+      // Type assertion is safe here as we're checking for BaseRepository properties
+      const baseRepo = repo as unknown as BaseRepository
+
+      // Check if it's actually a repository (has required properties)
+      if (!('tableName' in baseRepo) || !('executor' in baseRepo)) {
+        return repo
+      }
+
+      // Check if table supports soft delete
+      const supportsSoftDelete = !tables || tables.includes(baseRepo.tableName)
+
+      // If table doesn't support soft delete, return unmodified repo
+      if (!supportsSoftDelete) {
+        return repo
+      }
+
+      // Wrap original methods to apply soft delete filtering
+      const originalFindAll = baseRepo.findAll.bind(baseRepo)
+      const originalFindById = baseRepo.findById.bind(baseRepo)
+
+      const extendedRepo = {
+        ...baseRepo,
+
+        // Override base methods to filter soft-deleted records
+        async findAll(): Promise<unknown[]> {
+          if (!includeDeleted) {
+            const result = await baseRepo.executor
+              .selectFrom(baseRepo.tableName)
+              .selectAll()
+              .where(deletedAtColumn as never, 'is', null)
+              .execute()
+            return result as unknown[]
+          }
+          return await originalFindAll()
+        },
+
+        async findById(id: number): Promise<unknown> {
+          if (!includeDeleted) {
+            const result = await baseRepo.executor
+              .selectFrom(baseRepo.tableName)
+              .selectAll()
+              .where('id' as never, '=', id as never)
+              .where(deletedAtColumn as never, 'is', null)
+              .executeTakeFirst()
+            return result ?? null
+          }
+          return await originalFindById(id)
+        },
+
+        async softDelete(id: number): Promise<unknown> {
+          // Use CURRENT_TIMESTAMP directly in SQL to avoid datetime format issues
+          // This works across all databases (MySQL, PostgreSQL, SQLite)
+          // We bypass repository.update() to avoid Zod validation issues with RawBuilder
+          await baseRepo.executor
+            .updateTable(baseRepo.tableName)
+            .set({ [deletedAtColumn]: sql`CURRENT_TIMESTAMP` } as never)
+            .where('id' as never, '=', id as never)
+            .execute()
+
+          // Fetch the updated record to verify it exists
+          const record = await originalFindById(id)
+
+          // If record not found or deleted_at not set, throw error
+          if (!record) {
+            throw new Error(`Record with id ${id} not found`)
+          }
+
+          return record
+        },
+
+        async restore(id: number): Promise<unknown> {
+          return await baseRepo.update(id, { [deletedAtColumn]: null })
+        },
+
+        async hardDelete(id: number): Promise<void> {
+          // Direct hard delete - bypass soft delete
+          await baseRepo.executor
+            .deleteFrom(baseRepo.tableName)
+            .where('id' as never, '=', id as never)
+            .execute()
+        },
+
+        async findWithDeleted(id: number): Promise<unknown> {
+          // Use original method without filtering
+          return await originalFindById(id)
+        },
+
+        async findAllWithDeleted(): Promise<unknown[]> {
+          // Use original method without filtering
+          return await originalFindAll()
+        },
+
+        async findDeleted(): Promise<unknown[]> {
+          const result = await baseRepo.executor
+            .selectFrom(baseRepo.tableName)
+            .selectAll()
+            .where(deletedAtColumn as never, 'is not', null)
+            .execute()
+          return result as unknown[]
+        }
+      }
+
+      return extendedRepo as T
+    }
+  }
+}