@dockstat/sqlite-wrapper 1.2.7 → 1.3.0

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@dockstat/sqlite-wrapper",
-  "version": "1.2.7",
+  "version": "1.3.0",
   "description": "A TypeScript wrapper around bun:sqlite with type-safe query building",
   "type": "module",
   "main": "./index.ts",
   "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./types": "./types.ts",
+    "./utils": "./utils/index.ts"
+  },
   "files": [
     "index.ts",
     "query-builder/**/*",
+    "utils/**/*",
     "README.md",
     "types.ts"
   ],
@@ -17,7 +23,7 @@
     "lint:fix": "biome lint --write .",
     "lint:gh": "turbo run lint -- --reporter=github",
     "check-types": "bunx tsc --noEmit",
-    "test": "bun run test.ts"
+    "test": "DOCKSTAT_LOGGER_IGNORE_MESSAGES='Logger Status: active - ignoring messages:' bun test"
   },
   "keywords": [
     "sqlite",
@@ -42,13 +48,13 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "@dockstat/logger": "^1.0.0"
+    "@dockstat/logger": "1.0.1"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5.9.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@types/dockerode": "^3.3.42"
+    "@types/dockerode": "^3.3.44"
   }
 }

package/query-builder/base.ts

@@ -1,58 +1,42 @@
-import type { Database, SQLQueryBindings } from 'bun:sqlite'
-import { createLogger } from '@dockstat/logger'
-import type {
-  ColumnNames,
-  DatabaseRowData,
-  JsonColumnConfig,
-  OrderDirection,
-  QueryBuilderState,
-} from '../types'
+import type { Database, SQLQueryBindings } from "bun:sqlite"
+import type { Parser, QueryBuilderState } from "../types"
+import {
+  createLogger,
+  quoteIdentifier,
+  type RowData,
+  transformFromDb,
+  transformRowsFromDb,
+  transformToDb,
+} from "../utils"
 
 /**
  * Base QueryBuilder class that manages core state and shared functionality.
- * This class provides the foundation for all query operations.
+ *
+ * This class provides the foundation for all query operations including:
+ * - Database connection and table name management
+ * - WHERE clause building and management
+ * - Regex condition handling (client-side filtering)
+ * - Row transformation (JSON/Boolean serialization)
  */
 export abstract class BaseQueryBuilder<T extends Record<string, unknown>> {
-  private logger = createLogger('BaseQueryBuilder')
   protected state: QueryBuilderState<T>
+  protected log = createLogger("query")
 
-  /**
-   * Get the logger instance
-   */
-  protected getLogger() {
-    return this.logger
-  }
-
-  constructor(
-    db: Database,
-    tableName: string,
-    jsonConfig?: JsonColumnConfig<T>
-  ) {
+  constructor(db: Database, tableName: string, parser?: Parser<T>) {
     this.state = {
       db,
       tableName,
       whereConditions: [],
       whereParams: [],
       regexConditions: [],
-      jsonColumns: jsonConfig,
+      parser,
     }
-  }
 
-  /**
-    * 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 = ['*']
+    this.log.debug(`QueryBuilder initialized for table: ${tableName}`)
   }
 
+  // ===== State Accessors =====
+
   /**
    * Get the database instance
    */
@@ -68,32 +52,78 @@ export abstract class BaseQueryBuilder<T extends Record<string, unknown>> {
   }
 
   /**
-   * Build the WHERE clause portion of a SQL query.
-   * @returns Tuple of [whereClause, parameters] where whereClause includes "WHERE" prefix
+   * Get the parser configuration
+   */
+  protected getParser(): Parser<T> | undefined {
+    return this.state.parser
+  }
+
+  // ===== State Management =====
+
+  /**
+   * Reset query builder state to initial values
+   */
+  protected reset(): void {
+    this.state.whereConditions = []
+    this.state.whereParams = []
+    this.state.regexConditions = []
+
+    // Reset any additional state in subclasses
+    if ("orderColumn" in this) this.orderColumn = undefined
+    if ("orderDirection" in this) this.orderDirection = "ASC"
+    if ("limitValue" in this) this.limitValue = undefined
+    if ("offsetValue" in this) this.offsetValue = undefined
+    if ("selectedColumns" in this) this.selectedColumns = ["*"]
+  }
+
+  /**
+   * Reset only WHERE conditions (useful for reusing builder)
+   */
+  protected resetWhereConditions(): void {
+    this.state.whereConditions = []
+    this.state.whereParams = []
+    this.state.regexConditions = []
+  }
+
+  // ===== SQL Building Helpers =====
+
+  /**
+   * Quote a SQL identifier to prevent injection
+   */
+  protected quoteIdentifier(identifier: string): string {
+    return quoteIdentifier(identifier)
+  }
+
+  /**
+   * Build the WHERE clause from accumulated conditions
+   *
+   * @returns Tuple of [whereClause, parameters]
    */
   protected buildWhereClause(): [string, SQLQueryBindings[]] {
     if (this.state.whereConditions.length === 0) {
-      return ['', []]
+      return ["", []]
     }
-    return [
-      ` WHERE ${this.state.whereConditions.join(' AND ')}`,
-      this.state.whereParams.slice(),
-    ]
+
+    const clause = ` WHERE ${this.state.whereConditions.join(" AND ")}`
+    const params = [...this.state.whereParams]
+
+    return [clause, params]
   }
 
+  // ===== Regex Condition Handling =====
+
   /**
-   * Check if there are any regex conditions that require client-side filtering.
+   * Check if there are any regex conditions requiring 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.
+   * Apply regex filtering to rows (client-side)
    */
   protected applyRegexFiltering(rows: T[]): T[] {
-    if (this.state.regexConditions.length === 0) {
+    if (!this.hasRegexConditions()) {
       return rows
     }
 
@@ -106,116 +136,48 @@ export abstract class BaseQueryBuilder<T extends Record<string, unknown>> {
     )
   }
 
+  // ===== Validation =====
+
   /**
-   * Validate that WHERE conditions exist for operations that require them.
-   * Throws an error if no WHERE conditions are present.
+   * Validate that WHERE conditions exist for destructive operations
+   *
+   * @throws 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)
+    const hasWhere = this.state.whereConditions.length > 0
+    const hasRegex = this.state.regexConditions.length > 0
+
+    if (!hasWhere && !hasRegex) {
+      const message =
+        `${operation} requires at least one WHERE condition. ` +
+        `Use where(), whereRaw(), whereIn(), whereOp(), or whereRgx().`
+      this.log.error(message)
+      throw new Error(message)
     }
   }
 
-  /**
-   * 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 = []
-  }
+  // ===== Row Transformation =====
 
   /**
-   * Transform row data after fetching from database (deserialize JSON columns).
+   * Transform a single row FROM the database
+   * (deserialize JSON, convert booleans, etc.)
    */
   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
-    }
+    return transformFromDb<T>(row, { parser: this.state.parser })
   }
 
   /**
-   * Transform multiple rows after fetching from database.
+   * Transform multiple rows FROM the 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[]
-    }
+    return transformRowsFromDb<T>(rows, { parser: this.state.parser })
   }
 
   /**
-   * Transform row data before inserting/updating to database (serialize JSON columns).
+   * Transform a row TO the database
+   * (serialize JSON, stringify functions, etc.)
    */
-  protected transformRowToDb(row: Partial<T>): DatabaseRowData {
-    this.logger.debug(`Transforming row (${JSON.stringify(row)}) to row Data`)
-    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)
-      this.logger.debug(`Checking: ${columnKey}`)
-      if (
-        transformed[columnKey] !== undefined &&
-        transformed[columnKey] !== null
-      ) {
-        if (typeof transformed[columnKey] === 'object') {
-          transformed[columnKey] = JSON.stringify(transformed[columnKey])
-        }
-      }
-    }
-    return transformed
+  protected transformRowToDb(row: Partial<T>): RowData {
+    return transformToDb<T>(row, { parser: this.state.parser })
   }
 }