@dockstat/sqlite-wrapper 1.2.7 → 1.3.0

package/query-builder/delete.ts

@@ -1,352 +1,441 @@
-import type { SQLQueryBindings } from "bun:sqlite";
-import type { DeleteResult } from "../types";
-import { SelectQueryBuilder } from "./select";
+import type { SQLQueryBindings } from "bun:sqlite"
+import type { DeleteResult } from "../types"
+import { createLogger, quoteIdentifier } from "../utils"
+import { SelectQueryBuilder } from "./select"
 
 /**
- * Mixin class that adds DELETE functionality to the QueryBuilder.
- * Handles safe delete operations with mandatory WHERE conditions.
+ * DeleteQueryBuilder - Handles DELETE operations with safety checks
+ *
+ * Features:
+ * - Safe deletes (WHERE required to prevent accidental full-table deletes)
+ * - Soft delete (mark as deleted instead of removing)
+ * - Restore soft deleted rows
+ * - Delete and get (returns deleted rows)
+ * - Batch deletes with transaction support
+ * - Delete older than timestamp
+ * - Delete duplicates
+ * - Truncate (explicit full-table delete)
  */
-export class DeleteQueryBuilder<
-  T extends Record<string, unknown>,
-> extends SelectQueryBuilder<T> {
+export class DeleteQueryBuilder<T extends Record<string, unknown>> extends SelectQueryBuilder<T> {
+  private deleteLog = createLogger("delete")
+
+  // ===== Public Delete Methods =====
+
   /**
-   * Delete rows matching the WHERE conditions.
-   * Requires at least one WHERE condition to prevent accidental full table deletion.
+   * Delete rows matching the WHERE conditions
+   *
+   * Requires at least one WHERE condition to prevent accidental full-table deletes.
+   *
+   * @example
+   * table.where({ id: 1 }).delete()
    *
-   * @returns Delete result with changes count
+   * @example
+   * table.where({ active: false, deleted_at: null }).delete()
    */
   delete(): DeleteResult {
-    this.requireWhereClause("DELETE");
+    this.requireWhereClause("DELETE")
 
-    // Handle regex conditions by first fetching matching rows
+    // Handle regex conditions by fetching matching rows first
     if (this.hasRegexConditions()) {
-      const result = this.deleteWithRegexConditions();
-      this.reset();
-      return result;
+      return this.deleteWithRegexConditions()
     }
 
     // Build DELETE statement
-    const [whereClause, whereParams] = this.buildWhereClause();
-    const query = `DELETE FROM ${this.quoteIdentifier(this.getTableName())}${whereClause}`;
+    const [whereClause, whereParams] = this.buildWhereClause()
+    const query = `DELETE FROM ${quoteIdentifier(this.getTableName())}${whereClause}`
+
+    this.deleteLog.query("DELETE", query, whereParams)
 
     const result = this.getDb()
       .prepare(query)
-      .run(...whereParams);
+      .run(...whereParams)
+
+    this.deleteLog.result("DELETE", result.changes)
+    this.reset()
 
-    this.reset();
-    return {
-      changes: result.changes,
-    };
+    return { changes: result.changes }
   }
 
   /**
-   * Handle DELETE operations when regex conditions are present.
-   * This requires client-side filtering and individual row deletion.
+   * Handle DELETE when regex conditions are present
+   *
+   * Since regex conditions are applied client-side, we need to:
+   * 1. Fetch all rows matching SQL conditions
+   * 2. Filter with regex client-side
+   * 3. Delete each matching row by rowid
    */
   private deleteWithRegexConditions(): DeleteResult {
-    this.reset();
-    // First, get all rows matching SQL conditions (without regex)
-    const [selectQuery, selectParams] = this.buildWhereClause();
+    // Get rows matching SQL conditions (without regex)
+    // Use alias for rowid to avoid collision with INTEGER PRIMARY KEY columns
+    const [whereClause, whereParams] = this.buildWhereClause()
+    const selectQuery = `SELECT rowid as _rowid_, * FROM ${quoteIdentifier(this.getTableName())}${whereClause}`
+
     const candidateRows = this.getDb()
-      .prepare(
-        `SELECT rowid, * FROM ${this.quoteIdentifier(this.getTableName())}${selectQuery}`,
-      )
-      .all(...selectParams) as (T & { rowid: number })[];
+      .prepare(selectQuery)
+      .all(...whereParams) as (T & { _rowid_: number })[]
 
     // Apply regex filtering
-    const matchingRows = this.applyRegexFiltering(candidateRows);
+    const matchingRows = this.applyRegexFiltering(candidateRows)
 
     if (matchingRows.length === 0) {
-      return { changes: 0 };
+      this.reset()
+      return { changes: 0 }
     }
 
     // Delete each matching row by rowid
-    const deleteQuery = `DELETE FROM ${this.quoteIdentifier(this.getTableName())} WHERE rowid = ?`;
-    const stmt = this.getDb().prepare(deleteQuery);
+    const deleteQuery = `DELETE FROM ${quoteIdentifier(this.getTableName())} WHERE rowid = ?`
+    const stmt = this.getDb().prepare(deleteQuery)
+
+    this.deleteLog.query("DELETE (regex)", deleteQuery)
+
+    let totalChanges = 0
 
-    let totalChanges = 0;
     for (const row of matchingRows) {
-      const result = stmt.run(row.rowid as SQLQueryBindings);
-      totalChanges += result.changes;
+      const result = stmt.run(row._rowid_ as SQLQueryBindings)
+      totalChanges += result.changes
     }
 
-    return { changes: totalChanges };
+    this.deleteLog.result("DELETE (regex)", totalChanges)
+    this.reset()
+
+    return { changes: totalChanges }
   }
 
   /**
-   * Delete and get the deleted rows back.
-   * This is useful when you want to see what was deleted for logging or audit purposes.
+   * Delete rows and return the deleted rows
+   *
+   * Useful for logging or audit purposes.
    *
-   * @returns Array of deleted rows
+   * @example
+   * const deletedUsers = table.where({ active: false }).deleteAndGet()
+   * console.log(`Deleted ${deletedUsers.length} inactive users`)
    */
   deleteAndGet(): T[] {
-    // First, get the rows that will be deleted
-    const rowsToDelete = this.all();
+    // Preserve WHERE state before all() resets it
+    const savedWhereConditions = [...this.state.whereConditions]
+    const savedWhereParams = [...this.state.whereParams]
+    const savedRegexConditions = [...this.state.regexConditions]
+
+    // Get rows before deletion
+    const rowsToDelete = this.all()
+
+    // Restore WHERE state for the delete
+    this.state.whereConditions = savedWhereConditions
+    this.state.whereParams = savedWhereParams
+    this.state.regexConditions = savedRegexConditions
 
     // Perform the delete
-    const deleteResult = this.delete();
+    const deleteResult = this.delete()
 
     if (deleteResult.changes === 0) {
-      return [];
+      return []
     }
 
-    // Return the rows that were deleted
-    const out = rowsToDelete;
-    this.reset();
-    return out;
+    return rowsToDelete
   }
 
   /**
-   * Soft delete - mark rows as deleted instead of physically removing them.
-   * This requires a 'deleted_at' or similar column in your table schema.
+   * Soft delete - mark rows as deleted instead of removing them
+   *
+   * Sets a timestamp column to mark rows as deleted.
+   * Useful for data recovery and audit trails.
    *
-   * @param deletedColumn - Column name to mark as deleted (defaults to 'deleted_at')
-   * @param deletedValue - Value to set for the deleted marker (defaults to current timestamp)
-   * @returns Update result with changes count
+   * @example
+   * // Using default column name 'deleted_at'
+   * table.where({ id: 1 }).softDelete()
+   *
+   * @example
+   * // Using custom column name and value
+   * table.where({ id: 1 }).softDelete("removed_at", Date.now())
    */
   softDelete(
     deletedColumn: keyof T = "deleted_at" as keyof T,
-    deletedValue: SQLQueryBindings = Math.floor(Date.now() / 1000),
+    deletedValue: SQLQueryBindings = Math.floor(Date.now() / 1000)
   ): DeleteResult {
-    this.requireWhereClause("SOFT DELETE");
+    this.requireWhereClause("SOFT DELETE")
 
     // Handle regex conditions
     if (this.hasRegexConditions()) {
-      const result = this.softDeleteWithRegexConditions(deletedColumn, deletedValue);
-      this.reset();
-      return result;
+      return this.softDeleteWithRegexConditions(deletedColumn, deletedValue)
     }
 
     // Build UPDATE statement to mark as deleted
-    const [whereClause, whereParams] = this.buildWhereClause();
-    const query = `UPDATE ${this.quoteIdentifier(this.getTableName())} SET ${this.quoteIdentifier(String(deletedColumn))} = ?${whereClause}`;
+    const [whereClause, whereParams] = this.buildWhereClause()
+    const query = `UPDATE ${quoteIdentifier(this.getTableName())} SET ${quoteIdentifier(String(deletedColumn))} = ?${whereClause}`
+    const params = [deletedValue, ...whereParams] as SQLQueryBindings[]
+
+    this.deleteLog.query("SOFT DELETE", query, params)
 
     const result = this.getDb()
       .prepare(query)
-      .run(deletedValue, ...whereParams);
+      .run(...params)
 
-    this.reset();
-    return {
-      changes: result.changes,
-    };
+    this.deleteLog.result("SOFT DELETE", result.changes)
+    this.reset()
+
+    return { changes: result.changes }
   }
 
   /**
-   * Handle soft delete operations when regex conditions are present.
+   * Handle soft delete when regex conditions are present
    */
   private softDeleteWithRegexConditions(
     deletedColumn: keyof T,
-    deletedValue: SQLQueryBindings,
+    deletedValue: SQLQueryBindings
   ): DeleteResult {
-    // First, get all rows matching SQL conditions (without regex)
-    const [selectQuery, selectParams] = this.buildWhereClause();
+    // Get rows matching SQL conditions (without regex)
+    // Use alias for rowid to avoid collision with INTEGER PRIMARY KEY columns
+    const [whereClause, whereParams] = this.buildWhereClause()
+    const selectQuery = `SELECT rowid as _rowid_, * FROM ${quoteIdentifier(this.getTableName())}${whereClause}`
+
     const candidateRows = this.getDb()
-      .prepare(
-        `SELECT rowid, * FROM ${this.quoteIdentifier(this.getTableName())}${selectQuery}`,
-      )
-      .all(...selectParams) as (T & { rowid: number })[];
+      .prepare(selectQuery)
+      .all(...whereParams) as (T & { _rowid_: number })[]
 
     // Apply regex filtering
-    const matchingRows = this.applyRegexFiltering(candidateRows);
+    const matchingRows = this.applyRegexFiltering(candidateRows)
 
     if (matchingRows.length === 0) {
-      return { changes: 0 };
+      this.reset()
+      return { changes: 0 }
     }
 
     // Soft delete each matching row by rowid
-    const updateQuery = `UPDATE ${this.quoteIdentifier(this.getTableName())} SET ${this.quoteIdentifier(String(deletedColumn))} = ? WHERE rowid = ?`;
-    const stmt = this.getDb().prepare(updateQuery);
+    const updateQuery = `UPDATE ${quoteIdentifier(this.getTableName())} SET ${quoteIdentifier(String(deletedColumn))} = ? WHERE rowid = ?`
+    const stmt = this.getDb().prepare(updateQuery)
+
+    this.deleteLog.query("SOFT DELETE (regex)", updateQuery)
+
+    let totalChanges = 0
 
-    let totalChanges = 0;
     for (const row of matchingRows) {
-      const result = stmt.run(deletedValue, row.rowid as SQLQueryBindings);
-      totalChanges += result.changes;
+      const result = stmt.run(deletedValue, row._rowid_ as SQLQueryBindings)
+      totalChanges += result.changes
     }
 
-    return { changes: totalChanges };
+    this.deleteLog.result("SOFT DELETE (regex)", totalChanges)
+    this.reset()
+
+    return { changes: totalChanges }
   }
 
   /**
-   * Restore soft deleted rows by clearing the deleted marker.
+   * Restore soft deleted rows by clearing the deleted marker
    *
-   * @param deletedColumn - Column name that marks rows as deleted
-   * @returns Update result with changes count
+   * @example
+   * // Restore using default column name 'deleted_at'
+   * table.where({ id: 1 }).restore()
+   *
+   * @example
+   * // Restore using custom column name
+   * table.where({ email: "user@example.com" }).restore("removed_at")
    */
   restore(deletedColumn: keyof T = "deleted_at" as keyof T): DeleteResult {
-    this.requireWhereClause("RESTORE");
+    this.requireWhereClause("RESTORE")
 
     // Handle regex conditions
     if (this.hasRegexConditions()) {
-      const result = this.restoreWithRegexConditions(deletedColumn);
-      this.reset();
-      return result;
+      return this.restoreWithRegexConditions(deletedColumn)
     }
 
     // Build UPDATE statement to clear the deleted marker
-    const [whereClause, whereParams] = this.buildWhereClause();
-    const query = `UPDATE ${this.quoteIdentifier(this.getTableName())} SET ${this.quoteIdentifier(String(deletedColumn))} = NULL${whereClause}`;
+    const [whereClause, whereParams] = this.buildWhereClause()
+    const query = `UPDATE ${quoteIdentifier(this.getTableName())} SET ${quoteIdentifier(String(deletedColumn))} = NULL${whereClause}`
+
+    this.deleteLog.query("RESTORE", query, whereParams)
 
     const result = this.getDb()
       .prepare(query)
-      .run(...whereParams);
+      .run(...whereParams)
+
+    this.deleteLog.result("RESTORE", result.changes)
+    this.reset()
 
-    this.reset();
-    return {
-      changes: result.changes,
-    };
+    return { changes: result.changes }
   }
 
   /**
-   * Handle restore operations when regex conditions are present.
+   * Handle restore when regex conditions are present
    */
   private restoreWithRegexConditions(deletedColumn: keyof T): DeleteResult {
-    // First, get all rows matching SQL conditions (without regex)
-    const [selectQuery, selectParams] = this.buildWhereClause();
+    // Get rows matching SQL conditions (without regex)
+    // Use alias for rowid to avoid collision with INTEGER PRIMARY KEY columns
+    const [whereClause, whereParams] = this.buildWhereClause()
+    const selectQuery = `SELECT rowid as _rowid_, * FROM ${quoteIdentifier(this.getTableName())}${whereClause}`
+
     const candidateRows = this.getDb()
-      .prepare(
-        `SELECT rowid, * FROM ${this.quoteIdentifier(this.getTableName())}${selectQuery}`,
-      )
-      .all(...selectParams) as (T & { rowid: number })[];
+      .prepare(selectQuery)
+      .all(...whereParams) as (T & { _rowid_: number })[]
 
     // Apply regex filtering
-    const matchingRows = this.applyRegexFiltering(candidateRows);
+    const matchingRows = this.applyRegexFiltering(candidateRows)
 
     if (matchingRows.length === 0) {
-      return { changes: 0 };
+      this.reset()
+      return { changes: 0 }
     }
 
     // Restore each matching row by rowid
-    const updateQuery = `UPDATE ${this.quoteIdentifier(this.getTableName())} SET ${this.quoteIdentifier(String(deletedColumn))} = NULL WHERE rowid = ?`;
-    const stmt = this.getDb().prepare(updateQuery);
+    const updateQuery = `UPDATE ${quoteIdentifier(this.getTableName())} SET ${quoteIdentifier(String(deletedColumn))} = NULL WHERE rowid = ?`
+    const stmt = this.getDb().prepare(updateQuery)
+
+    this.deleteLog.query("RESTORE (regex)", updateQuery)
+
+    let totalChanges = 0
 
-    let totalChanges = 0;
     for (const row of matchingRows) {
-      const result = stmt.run(row.rowid as SQLQueryBindings);
-      totalChanges += result.changes;
+      const result = stmt.run(row._rowid_ as SQLQueryBindings)
+      totalChanges += result.changes
     }
 
-    return { changes: totalChanges };
+    this.deleteLog.result("RESTORE (regex)", totalChanges)
+    this.reset()
+
+    return { changes: totalChanges }
   }
 
   /**
-   * Batch delete multiple sets of rows based on different conditions.
-   * This is more efficient than individual deletes when removing many different row sets.
+   * Batch delete multiple sets of rows based on different conditions
+   *
+   * Each condition set deletes rows matching those conditions.
+   * All deletes are wrapped in a transaction for atomicity.
    *
-   * @param conditions - Array of WHERE condition objects
-   * @returns Delete result with total changes count
+   * @example
+   * table.deleteBatch([
+   *   { id: 1 },
+   *   { id: 2 },
+   *   { email: "deleted@example.com" },
+   * ])
    */
   deleteBatch(conditions: Array<Partial<T>>): DeleteResult {
     if (!Array.isArray(conditions) || conditions.length === 0) {
-      throw new Error("deleteBatch: conditions must be a non-empty array");
+      throw new Error("deleteBatch: conditions must be a non-empty array")
     }
 
-    const db = this.getDb();
-
-    // Use a transaction for batch operations
-    const transaction = db.transaction(
-      (conditionsToProcess: Array<Partial<T>>) => {
-        let totalChanges = 0;
-
-        for (const whereData of conditionsToProcess) {
-          // Build WHERE conditions for this delete
-          const whereConditions: string[] = [];
-          const whereParams: SQLQueryBindings[] = [];
-
-          for (const [column, value] of Object.entries(whereData)) {
-            if (value === null || value === undefined) {
-              whereConditions.push(`${this.quoteIdentifier(column)} IS NULL`);
-            } else {
-              whereConditions.push(`${this.quoteIdentifier(column)} = ?`);
-              whereParams.push(value);
-            }
-          }
+    const db = this.getDb()
 
-          if (whereConditions.length === 0) {
-            throw new Error(
-              "deleteBatch: each delete must have WHERE conditions",
-            );
-          }
+    const transaction = db.transaction((conditionsToProcess: Array<Partial<T>>) => {
+      let totalChanges = 0
+
+      for (const whereData of conditionsToProcess) {
+        // Build WHERE conditions for this delete
+        const whereConditions: string[] = []
+        const whereParams: SQLQueryBindings[] = []
 
-          // Build DELETE statement
-          const whereClause = ` WHERE ${whereConditions.join(" AND ")}`;
-          const query = `DELETE FROM ${this.quoteIdentifier(this.getTableName())}${whereClause}`;
+        for (const [column, value] of Object.entries(whereData)) {
+          if (value === null || value === undefined) {
+            whereConditions.push(`${quoteIdentifier(column)} IS NULL`)
+          } else {
+            whereConditions.push(`${quoteIdentifier(column)} = ?`)
+            whereParams.push(value as SQLQueryBindings)
+          }
+        }
 
-          const result = db.prepare(query).run(...whereParams);
-          totalChanges += result.changes;
+        if (whereConditions.length === 0) {
+          throw new Error("deleteBatch: each delete must have WHERE conditions")
         }
 
-        return { changes: totalChanges };
-      },
-    );
+        // Build DELETE statement
+        const whereClause = ` WHERE ${whereConditions.join(" AND ")}`
+        const query = `DELETE FROM ${quoteIdentifier(this.getTableName())}${whereClause}`
+
+        const result = db.prepare(query).run(...whereParams)
+        totalChanges += result.changes
+      }
+
+      return { changes: totalChanges }
+    })
 
-    const result = transaction(conditions);
-    this.reset();
-    return result;
+    this.deleteLog.query("DELETE BATCH", `${conditions.length} deletes`)
+
+    const result = transaction(conditions)
+
+    this.deleteLog.result("DELETE BATCH", result.changes)
+    this.reset()
+
+    return result
   }
 
   /**
-   * Truncate the entire table (delete all rows).
+   * Truncate the entire table (delete all rows)
+   *
    * This bypasses the WHERE condition requirement since it's explicitly destructive.
    * USE WITH EXTREME CAUTION!
    *
-   * @returns Delete result with changes count
+   * @example
+   * // Delete all rows from the table
+   * table.truncate()
    */
   truncate(): DeleteResult {
-    const query = `DELETE FROM ${this.quoteIdentifier(this.getTableName())}`;
-    const result = this.getDb().prepare(query).run();
+    const query = `DELETE FROM ${quoteIdentifier(this.getTableName())}`
+
+    this.deleteLog.query("TRUNCATE", query)
+
+    const result = this.getDb().prepare(query).run()
+
+    this.deleteLog.result("TRUNCATE", result.changes)
+    this.reset()
 
-    this.reset();
-    return {
-      changes: result.changes,
-    };
+    return { changes: result.changes }
   }
 
   /**
-   * Delete rows older than a specified timestamp.
+   * Delete rows older than a specified timestamp
+   *
    * Convenience method for common cleanup operations.
    *
-   * @param timestampColumn - Column name containing the timestamp
-   * @param olderThan - Timestamp threshold (rows older than this will be deleted)
-   * @returns Delete result with changes count
+   * @example
+   * // Delete rows older than 24 hours
+   * table.deleteOlderThan("created_at", Date.now() - 86400000)
+   *
+   * @example
+   * // Delete rows older than 30 days (Unix timestamp)
+   * const thirtyDaysAgo = Math.floor(Date.now() / 1000) - (30 * 24 * 60 * 60)
+   * table.deleteOlderThan("timestamp", thirtyDaysAgo)
    */
   deleteOlderThan(timestampColumn: keyof T, olderThan: number): DeleteResult {
-    const changes = this.whereOp(timestampColumn, "<", olderThan).delete();
-    this.reset();
-    return changes;
+    return this.whereOp(timestampColumn, "<", olderThan).delete()
   }
 
   /**
-   * Delete duplicate rows based on specified columns, keeping only the first occurrence.
-   * This is useful for data cleanup operations.
+   * Delete duplicate rows based on specified columns
+   *
+   * Keeps the row with the minimum rowid for each unique combination.
+   * Useful for data cleanup operations.
    *
-   * @param columns - Columns to check for duplicates
-   * @returns Delete result with changes count
+   * @example
+   * // Delete duplicate emails, keeping the first occurrence
+   * table.deleteDuplicates(["email"])
+   *
+   * @example
+   * // Delete rows with duplicate name+email combinations
+   * table.deleteDuplicates(["name", "email"])
    */
   deleteDuplicates(columns: Array<keyof T>): DeleteResult {
     if (!Array.isArray(columns) || columns.length === 0) {
-      throw new Error("deleteDuplicates: columns must be a non-empty array");
+      throw new Error("deleteDuplicates: columns must be a non-empty array")
     }
 
-    const columnNames = columns.map((col) => String(col));
-    const quotedColumns = columnNames
-      .map((col) => this.quoteIdentifier(col))
-      .join(", ");
+    const quotedColumns = columns.map((col) => quoteIdentifier(String(col))).join(", ")
+    const tableName = quoteIdentifier(this.getTableName())
 
-    // Find duplicate rows, keeping the one with the minimum rowid
+    // Delete all rows except the one with minimum rowid for each unique combination
     const query = `
-      DELETE FROM ${this.quoteIdentifier(this.getTableName())}
+      DELETE FROM ${tableName}
       WHERE rowid NOT IN (
         SELECT MIN(rowid)
-        FROM ${this.quoteIdentifier(this.getTableName())}
+        FROM ${tableName}
         GROUP BY ${quotedColumns}
       )
-    `;
+    `.trim()
+
+    this.deleteLog.query("DELETE DUPLICATES", query)
+
+    const result = this.getDb().prepare(query).run()
 
-    const result = this.getDb().prepare(query).run();
+    this.deleteLog.result("DELETE DUPLICATES", result.changes)
+    this.reset()
 
-    this.reset();
-    return {
-      changes: result.changes,
-    };
+    return { changes: result.changes }
   }
 }