@dockstat/sqlite-wrapper 1.2.1 → 1.2.3

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dockstat/sqlite-wrapper",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "A TypeScript wrapper around bun:sqlite with type-safe query building",
   "type": "module",
   "main": "./index.ts",
   "types": "./index.ts",
-  "files": ["index.ts", "src/**/*", "README.md", "types.ts"],
+  "files": ["index.ts", "query-builder/**/*", "README.md", "types.ts"],
   "scripts": {
     "dev": "bun build index.ts",
     "lint": "biome lint .",

package/query-builder/base.ts

@@ -0,0 +1,217 @@
+import type { Database, SQLQueryBindings } from 'bun:sqlite'
+import { createLogger } from '@dockstat/logger'
+import type {
+  ColumnNames,
+  DatabaseRowData,
+  JsonColumnConfig,
+  OrderDirection,
+  QueryBuilderState,
+} from '../types'
+
+/**
+ * Base QueryBuilder class that manages core state and shared functionality.
+ * This class provides the foundation for all query operations.
+ */
+export abstract class BaseQueryBuilder<T extends Record<string, unknown>> {
+  private logger = createLogger('BaseQueryBuilder')
+  protected state: QueryBuilderState<T>
+
+  /**
+   * Get the logger instance
+   */
+  protected getLogger() {
+    return this.logger
+  }
+
+  constructor(
+    db: Database,
+    tableName: string,
+    jsonConfig?: JsonColumnConfig<T>
+  ) {
+    this.state = {
+      db,
+      tableName,
+      whereConditions: [],
+      whereParams: [],
+      regexConditions: [],
+      jsonColumns: jsonConfig?.jsonColumns,
+    }
+    this.logger.debug(`Created QueryBuilder for table: ${tableName}`)
+  }
+
+  /**
+    * Reset query builder state
+    */
+    protected reset(): void {
+      this.state.whereConditions = []
+      this.state.whereParams = []
+      this.state.regexConditions = []
+      // Reset any ordering, limit, offset, selected columns if present
+      if ('orderColumn' in this) (this as any).orderColumn = undefined
+      if ('orderDirection' in this) (this as any).orderDirection = 'ASC'
+      if ('limitValue' in this) (this as any).limitValue = undefined
+      if ('offsetValue' in this) (this as any).offsetValue = undefined
+      if ('selectedColumns' in this) (this as any).selectedColumns = ['*']
+    }
+
+  /**
+   * Get the database instance
+   */
+  protected getDb(): Database {
+    return this.state.db
+  }
+
+  /**
+   * Get the table name
+   */
+  protected getTableName(): string {
+    return this.state.tableName
+  }
+
+  /**
+   * Build the WHERE clause portion of a SQL query.
+   * @returns Tuple of [whereClause, parameters] where whereClause includes "WHERE" prefix
+   */
+  protected buildWhereClause(): [string, SQLQueryBindings[]] {
+    if (this.state.whereConditions.length === 0) {
+      return ['', []]
+    }
+    return [
+      ` WHERE ${this.state.whereConditions.join(' AND ')}`,
+      this.state.whereParams.slice(),
+    ]
+  }
+
+  /**
+   * Check if there are any regex conditions that require client-side filtering.
+   */
+  protected hasRegexConditions(): boolean {
+    return this.state.regexConditions.length > 0
+  }
+
+  /**
+   * Apply client-side regex filtering to a set of rows.
+   * This is used when regex conditions are present.
+   */
+  protected applyRegexFiltering(rows: T[]): T[] {
+    if (this.state.regexConditions.length === 0) {
+      return rows
+    }
+
+    return rows.filter((row) =>
+      this.state.regexConditions.every(({ column, regex }) => {
+        const value = row[String(column)]
+        if (value === null || value === undefined) return false
+        return regex.test(String(value))
+      })
+    )
+  }
+
+  /**
+   * Validate that WHERE conditions exist for operations that require them.
+   * Throws an error if no WHERE conditions are present.
+   */
+  protected requireWhereClause(operation: string): void {
+    if (
+      this.state.whereConditions.length === 0 &&
+      this.state.regexConditions.length === 0
+    ) {
+      const error = `${operation} operation requires at least one WHERE condition. Use where(), whereRaw(), whereIn(), whereOp(), or whereRgx() to add conditions.`
+      this.logger.error(error)
+      throw new Error(error)
+    }
+  }
+
+  /**
+   * Quote SQL identifiers to prevent injection and handle special characters.
+   */
+  protected quoteIdentifier(identifier: string): string {
+    return `"${identifier.replace(/"/g, '""')}"`
+  }
+
+  /**
+   * Reset all WHERE conditions and parameters.
+   * Useful for reusing the same builder instance.
+   */
+  protected resetWhereConditions(): void {
+    this.state.whereConditions = []
+    this.state.whereParams = []
+    this.state.regexConditions = []
+  }
+
+  /**
+   * Transform row data after fetching from database (deserialize JSON columns).
+   */
+  protected transformRowFromDb(row: unknown): T {
+    if (!this.state.jsonColumns || !row) return row as T
+
+    try {
+      const transformed = { ...row } as DatabaseRowData
+      for (const column of this.state.jsonColumns) {
+        const columnKey = String(column)
+        if (
+          transformed[columnKey] !== null &&
+          transformed[columnKey] !== undefined &&
+          typeof transformed[columnKey] === 'string'
+        ) {
+          try {
+            transformed[columnKey] = JSON.parse(
+              transformed[columnKey] as string
+            )
+          } catch (parseError) {
+            // Keep original value if JSON parsing fails
+            this.logger.warn(
+              `JSON parse failed for column ${columnKey}: ${parseError}`
+            )
+          }
+        }
+      }
+      return transformed as T
+    } catch (error) {
+      this.logger.error(`Error in transformRowFromDb: ${error}`)
+      return row as T
+    }
+  }
+
+  /**
+   * Transform multiple rows after fetching from database.
+   */
+  protected transformRowsFromDb(rows: unknown[]): T[] {
+    if (!this.state.jsonColumns || !Array.isArray(rows)) return rows as T[]
+
+    try {
+      return rows.map((row, index) => {
+        try {
+          return this.transformRowFromDb(row)
+        } catch (error) {
+          this.logger.error(`Error transforming row ${index}: ${error}`)
+          return row as T
+        }
+      })
+    } catch (error) {
+      this.logger.error(`Error in transformRowsFromDb: ${error}`)
+      return rows as T[]
+    }
+  }
+
+  /**
+   * Transform row data before inserting/updating to database (serialize JSON columns).
+   */
+  protected transformRowToDb(row: Partial<T>): DatabaseRowData {
+    if (!this.state.jsonColumns || !row) return row as DatabaseRowData
+
+    const transformed: DatabaseRowData = { ...row } as DatabaseRowData
+    for (const column of this.state.jsonColumns) {
+      const columnKey = String(column)
+      if (
+        transformed[columnKey] !== undefined &&
+        transformed[columnKey] !== null
+      ) {
+        if (typeof transformed[columnKey] === 'object') {
+          transformed[columnKey] = JSON.stringify(transformed[columnKey])
+        }
+      }
+    }
+    return transformed
+  }
+}

package/query-builder/delete.ts

@@ -0,0 +1,352 @@
+import type { SQLQueryBindings } from "bun:sqlite";
+import type { DeleteResult } from "../types";
+import { SelectQueryBuilder } from "./select";
+
+/**
+ * Mixin class that adds DELETE functionality to the QueryBuilder.
+ * Handles safe delete operations with mandatory WHERE conditions.
+ */
+export class DeleteQueryBuilder<
+  T extends Record<string, unknown>,
+> extends SelectQueryBuilder<T> {
+  /**
+   * Delete rows matching the WHERE conditions.
+   * Requires at least one WHERE condition to prevent accidental full table deletion.
+   *
+   * @returns Delete result with changes count
+   */
+  delete(): DeleteResult {
+    this.requireWhereClause("DELETE");
+
+    // Handle regex conditions by first fetching matching rows
+    if (this.hasRegexConditions()) {
+      const result = this.deleteWithRegexConditions();
+      this.reset();
+      return result;
+    }
+
+    // Build DELETE statement
+    const [whereClause, whereParams] = this.buildWhereClause();
+    const query = `DELETE FROM ${this.quoteIdentifier(this.getTableName())}${whereClause}`;
+
+    const result = this.getDb()
+      .prepare(query)
+      .run(...whereParams);
+
+    this.reset();
+    return {
+      changes: result.changes,
+    };
+  }
+
+  /**
+   * Handle DELETE operations when regex conditions are present.
+   * This requires client-side filtering and individual row deletion.
+   */
+  private deleteWithRegexConditions(): DeleteResult {
+    this.reset();
+    // First, get all rows matching SQL conditions (without regex)
+    const [selectQuery, selectParams] = this.buildWhereClause();
+    const candidateRows = this.getDb()
+      .prepare(
+        `SELECT rowid, * FROM ${this.quoteIdentifier(this.getTableName())}${selectQuery}`,
+      )
+      .all(...selectParams) as (T & { rowid: number })[];
+
+    // Apply regex filtering
+    const matchingRows = this.applyRegexFiltering(candidateRows);
+
+    if (matchingRows.length === 0) {
+      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);
+
+    let totalChanges = 0;
+    for (const row of matchingRows) {
+      const result = stmt.run(row.rowid as SQLQueryBindings);
+      totalChanges += result.changes;
+    }
+
+    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.
+   *
+   * @returns Array of deleted rows
+   */
+  deleteAndGet(): T[] {
+    // First, get the rows that will be deleted
+    const rowsToDelete = this.all();
+
+    // Perform the delete
+    const deleteResult = this.delete();
+
+    if (deleteResult.changes === 0) {
+      return [];
+    }
+
+    // Return the rows that were deleted
+    const out = rowsToDelete;
+    this.reset();
+    return out;
+  }
+
+  /**
+   * Soft delete - mark rows as deleted instead of physically removing them.
+   * This requires a 'deleted_at' or similar column in your table schema.
+   *
+   * @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
+   */
+  softDelete(
+    deletedColumn: keyof T = "deleted_at" as keyof T,
+    deletedValue: SQLQueryBindings = Math.floor(Date.now() / 1000),
+  ): DeleteResult {
+    this.requireWhereClause("SOFT DELETE");
+
+    // Handle regex conditions
+    if (this.hasRegexConditions()) {
+      const result = this.softDeleteWithRegexConditions(deletedColumn, deletedValue);
+      this.reset();
+      return result;
+    }
+
+    // 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 result = this.getDb()
+      .prepare(query)
+      .run(deletedValue, ...whereParams);
+
+    this.reset();
+    return {
+      changes: result.changes,
+    };
+  }
+
+  /**
+   * Handle soft delete operations when regex conditions are present.
+   */
+  private softDeleteWithRegexConditions(
+    deletedColumn: keyof T,
+    deletedValue: SQLQueryBindings,
+  ): DeleteResult {
+    // First, get all rows matching SQL conditions (without regex)
+    const [selectQuery, selectParams] = this.buildWhereClause();
+    const candidateRows = this.getDb()
+      .prepare(
+        `SELECT rowid, * FROM ${this.quoteIdentifier(this.getTableName())}${selectQuery}`,
+      )
+      .all(...selectParams) as (T & { rowid: number })[];
+
+    // Apply regex filtering
+    const matchingRows = this.applyRegexFiltering(candidateRows);
+
+    if (matchingRows.length === 0) {
+      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);
+
+    let totalChanges = 0;
+    for (const row of matchingRows) {
+      const result = stmt.run(deletedValue, row.rowid as SQLQueryBindings);
+      totalChanges += result.changes;
+    }
+
+    return { changes: totalChanges };
+  }
+
+  /**
+   * Restore soft deleted rows by clearing the deleted marker.
+   *
+   * @param deletedColumn - Column name that marks rows as deleted
+   * @returns Update result with changes count
+   */
+  restore(deletedColumn: keyof T = "deleted_at" as keyof T): DeleteResult {
+    this.requireWhereClause("RESTORE");
+
+    // Handle regex conditions
+    if (this.hasRegexConditions()) {
+      const result = this.restoreWithRegexConditions(deletedColumn);
+      this.reset();
+      return result;
+    }
+
+    // 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 result = this.getDb()
+      .prepare(query)
+      .run(...whereParams);
+
+    this.reset();
+    return {
+      changes: result.changes,
+    };
+  }
+
+  /**
+   * Handle restore operations 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();
+    const candidateRows = this.getDb()
+      .prepare(
+        `SELECT rowid, * FROM ${this.quoteIdentifier(this.getTableName())}${selectQuery}`,
+      )
+      .all(...selectParams) as (T & { rowid: number })[];
+
+    // Apply regex filtering
+    const matchingRows = this.applyRegexFiltering(candidateRows);
+
+    if (matchingRows.length === 0) {
+      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);
+
+    let totalChanges = 0;
+    for (const row of matchingRows) {
+      const result = stmt.run(row.rowid as SQLQueryBindings);
+      totalChanges += result.changes;
+    }
+
+    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.
+   *
+   * @param conditions - Array of WHERE condition objects
+   * @returns Delete result with total changes count
+   */
+  deleteBatch(conditions: Array<Partial<T>>): DeleteResult {
+    if (!Array.isArray(conditions) || conditions.length === 0) {
+      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);
+            }
+          }
+
+          if (whereConditions.length === 0) {
+            throw new Error(
+              "deleteBatch: each delete must have WHERE conditions",
+            );
+          }
+
+          // Build DELETE statement
+          const whereClause = ` WHERE ${whereConditions.join(" AND ")}`;
+          const query = `DELETE FROM ${this.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;
+  }
+
+  /**
+   * 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
+   */
+  truncate(): DeleteResult {
+    const query = `DELETE FROM ${this.quoteIdentifier(this.getTableName())}`;
+    const result = this.getDb().prepare(query).run();
+
+    this.reset();
+    return {
+      changes: result.changes,
+    };
+  }
+
+  /**
+   * 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
+   */
+  deleteOlderThan(timestampColumn: keyof T, olderThan: number): DeleteResult {
+    const changes = this.whereOp(timestampColumn, "<", olderThan).delete();
+    this.reset();
+    return changes;
+  }
+
+  /**
+   * Delete duplicate rows based on specified columns, keeping only the first occurrence.
+   * This is useful for data cleanup operations.
+   *
+   * @param columns - Columns to check for duplicates
+   * @returns Delete result with changes count
+   */
+  deleteDuplicates(columns: Array<keyof T>): DeleteResult {
+    if (!Array.isArray(columns) || columns.length === 0) {
+      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(", ");
+
+    // Find duplicate rows, keeping the one with the minimum rowid
+    const query = `
+      DELETE FROM ${this.quoteIdentifier(this.getTableName())}
+      WHERE rowid NOT IN (
+        SELECT MIN(rowid)
+        FROM ${this.quoteIdentifier(this.getTableName())}
+        GROUP BY ${quotedColumns}
+      )
+    `;
+
+    const result = this.getDb().prepare(query).run();
+
+    this.reset();
+    return {
+      changes: result.changes,
+    };
+  }
+}