@dockstat/sqlite-wrapper 1.2.8 → 1.3.0

package/package.json

@@ -1,54 +1,60 @@
-{
-  "name": "@dockstat/sqlite-wrapper",
-  "version": "1.2.8",
-  "description": "A TypeScript wrapper around bun:sqlite with type-safe query building",
-  "type": "module",
-  "main": "./index.ts",
-  "types": "./index.ts",
-  "files": [
-    "index.ts",
-    "query-builder/**/*",
-    "README.md",
-    "types.ts"
-  ],
-  "scripts": {
-    "dev": "bun build index.ts",
-    "lint": "biome lint .",
-    "lint:fix": "biome lint --write .",
-    "lint:gh": "turbo run lint -- --reporter=github",
-    "check-types": "bunx tsc --noEmit",
-    "test": "bun run test.ts"
-  },
-  "keywords": [
-    "sqlite",
-    "database",
-    "typescript",
-    "bun",
-    "query-builder",
-    "orm"
-  ],
-  "author": "Its4Nik",
-  "license": "MPL-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Its4Nik/DockStat/tree/main/packages/sqlite-wrapper",
-    "directory": "packages/sqlite-wrapper"
-  },
-  "bugs": {
-    "url": "https://github.com/Its4Nik/DockStat/issues"
-  },
-  "homepage": "https://outline.itsnik.de/s/9d88c471-373e-4ef2-a955-b1058eb7dc99/doc/dockstatsqlite-wrapper-Lxt4IphXI5",
-  "engines": {
-    "bun": ">=1.0.0"
-  },
-  "dependencies": {
-    "@dockstat/logger": "latest"
-  },
-  "peerDependencies": {
-    "typescript": "^5.9.3"
-  },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "@types/dockerode": "^3.3.44"
-  }
-}
+{
+  "name": "@dockstat/sqlite-wrapper",
+  "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"
+  ],
+  "scripts": {
+    "dev": "bun build index.ts",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "lint:gh": "turbo run lint -- --reporter=github",
+    "check-types": "bunx tsc --noEmit",
+    "test": "DOCKSTAT_LOGGER_IGNORE_MESSAGES='Logger Status: active - ignoring messages:' bun test"
+  },
+  "keywords": [
+    "sqlite",
+    "database",
+    "typescript",
+    "bun",
+    "query-builder",
+    "orm"
+  ],
+  "author": "Its4Nik",
+  "license": "MPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Its4Nik/DockStat/tree/main/packages/sqlite-wrapper",
+    "directory": "packages/sqlite-wrapper"
+  },
+  "bugs": {
+    "url": "https://github.com/Its4Nik/DockStat/issues"
+  },
+  "homepage": "https://outline.itsnik.de/s/9d88c471-373e-4ef2-a955-b1058eb7dc99/doc/dockstatsqlite-wrapper-Lxt4IphXI5",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "@dockstat/logger": "1.0.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/dockerode": "^3.3.44"
+  }
+}

package/query-builder/base.ts

@@ -1,221 +1,183 @@
-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,
-    }
-  }
-
-  /**
-    * 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 {
-    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
-  }
-}
+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 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>> {
+  protected state: QueryBuilderState<T>
+  protected log = createLogger("query")
+
+  constructor(db: Database, tableName: string, parser?: Parser<T>) {
+    this.state = {
+      db,
+      tableName,
+      whereConditions: [],
+      whereParams: [],
+      regexConditions: [],
+      parser,
+    }
+
+    this.log.debug(`QueryBuilder initialized for table: ${tableName}`)
+  }
+
+  // ===== State Accessors =====
+
+  /**
+   * Get the database instance
+   */
+  protected getDb(): Database {
+    return this.state.db
+  }
+
+  /**
+   * Get the table name
+   */
+  protected getTableName(): string {
+    return this.state.tableName
+  }
+
+  /**
+   * 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 ["", []]
+    }
+
+    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 requiring client-side filtering
+   */
+  protected hasRegexConditions(): boolean {
+    return this.state.regexConditions.length > 0
+  }
+
+  /**
+   * Apply regex filtering to rows (client-side)
+   */
+  protected applyRegexFiltering(rows: T[]): T[] {
+    if (!this.hasRegexConditions()) {
+      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))
+      })
+    )
+  }
+
+  // ===== Validation =====
+
+  /**
+   * Validate that WHERE conditions exist for destructive operations
+   *
+   * @throws Error if no WHERE conditions are present
+   */
+  protected requireWhereClause(operation: string): void {
+    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)
+    }
+  }
+
+  // ===== Row Transformation =====
+
+  /**
+   * Transform a single row FROM the database
+   * (deserialize JSON, convert booleans, etc.)
+   */
+  protected transformRowFromDb(row: unknown): T {
+    return transformFromDb<T>(row, { parser: this.state.parser })
+  }
+
+  /**
+   * Transform multiple rows FROM the database
+   */
+  protected transformRowsFromDb(rows: unknown[]): T[] {
+    return transformRowsFromDb<T>(rows, { parser: this.state.parser })
+  }
+
+  /**
+   * Transform a row TO the database
+   * (serialize JSON, stringify functions, etc.)
+   */
+  protected transformRowToDb(row: Partial<T>): RowData {
+    return transformToDb<T>(row, { parser: this.state.parser })
+  }
+}