@dockstat/sqlite-wrapper 1.3.3 → 1.3.4

package/README.md

@@ -12,22 +12,26 @@ Schema-first table helpers, an expressive chainable QueryBuilder, safe defaults
 ## 🆕 What's New in v1.3
 
 ### Bug Fixes
+
 - **Fixed Boolean parsing** — Boolean columns now correctly convert SQLite's `0`/`1` to JavaScript `true`/`false`
 - **Fixed Wrong packing** — Before the `publish` script was added, workspace dependencies were not correctly propagated
 
 ### New Features
+
 - **Auto-detection of JSON & Boolean columns** — No more manual parser configuration! Columns using `column.json()` or `column.boolean()` are automatically detected from schema
 - **Automatic backups with retention** — Configure `autoBackup` to create periodic backups with automatic cleanup of old files
 - **Backup & Restore API** — New `backup()`, `restore()`, and `listBackups()` methods
 - **`getPath()` method** — Get the database file path
 
 ### Architecture Improvements
+
 - **New `utils/` module** — Reusable utilities for SQL building, logging, and row transformation
 - **Structured logging** — Cleaner, more consistent log output with dedicated loggers per component
 - **Reduced code duplication** — Extracted common patterns into shared utilities
 - **Better maintainability** — Clearer separation of concerns across modules
 
 ### Breaking Changes
+
 - None! v1.3 is fully backward compatible with v1.2.x
 
 ---
@@ -284,7 +288,10 @@ const activeAdmins = userTable
   .all();
 
 // Get first match
-const user = userTable.select(["*"]).where({ email: "alice@example.com" }).first();
+const user = userTable
+  .select(["*"])
+  .where({ email: "alice@example.com" })
+  .first();
 
 // Count records
 const count = userTable.where({ active: true }).count();
@@ -321,7 +328,10 @@ userTable.insertOrIgnore({ email: "existing@example.com", name: "Name" });
 userTable.insertOrReplace({ email: "existing@example.com", name: "New Name" });
 
 // Insert and get the row back
-const newUser = userTable.insertAndGet({ name: "Charlie", email: "charlie@example.com" });
+const newUser = userTable.insertAndGet({
+  name: "Charlie",
+  email: "charlie@example.com",
+});
 ```
 
 ### UPDATE Operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dockstat/sqlite-wrapper",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "description": "A TypeScript wrapper around bun:sqlite with type-safe query building",
   "type": "module",
   "main": "./src/index.ts",

package/src/query-builder/select.ts

@@ -177,6 +177,9 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
 
   // ===== Execution Methods =====
 
+  // Use the protected static helper inherited from WhereQueryBuilder: `safeStringify`
+  // (Removed duplicate implementation to avoid static-side conflicts with the base class.)
+
   /**
    * Execute the query and return all matching rows
    *
@@ -187,6 +190,9 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
     const hasRegex = this.hasRegexConditions()
     const [query, params] = this.buildSelectQuery(!hasRegex)
 
+    // Info-level log for invocation
+    this.selectLog.info(`all | query=${query} params=${WhereQueryBuilder.safeStringify(params)}`)
+
     this.selectLog.query("SELECT", query, params)
 
     const rows = this.getDb()
@@ -201,6 +207,11 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
     // Apply client-side operations if needed
     const result = hasRegex ? this.applyClientSideOperations(transformed) : transformed
 
+    // Info-level log for returned data (length + sample)
+    this.selectLog.info(
+      `all | returned=${result.length} sample=${WhereQueryBuilder.safeStringify(result[0] ?? null)}`
+    )
+
     this.reset()
     return result
   }
@@ -216,6 +227,11 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
       const [query, params] = this.buildSelectQuery(true)
       const optimizedQuery = `${query} LIMIT 1`
 
+      // Info-level log for invocation
+      this.selectLog.info(
+        `get | optimizedQuery=${optimizedQuery} params=${WhereQueryBuilder.safeStringify(params)}`
+      )
+
       this.selectLog.query("SELECT (get)", optimizedQuery, params)
 
       const row = this.getDb()
@@ -225,6 +241,10 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
       this.selectLog.result("SELECT (get)", row ? 1 : 0)
 
       const result = row ? this.transformRowFromDb(row) : null
+
+      // Info-level log for returned row
+      this.selectLog.info(`get | returned=${WhereQueryBuilder.safeStringify(result)}`)
+
       this.reset()
       return result
     }
@@ -233,6 +253,9 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
     if (!this.hasRegexConditions()) {
       const [query, params] = this.buildSelectQuery(true)
 
+      // Info-level log for invocation
+      this.selectLog.info(`get | query=${query} params=${WhereQueryBuilder.safeStringify(params)}`)
+
       this.selectLog.query("SELECT (get)", query, params)
 
       const row = this.getDb()
@@ -242,6 +265,10 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
       this.selectLog.result("SELECT (get)", row ? 1 : 0)
 
       const result = row ? this.transformRowFromDb(row) : null
+
+      // Info-level log for returned row
+      this.selectLog.info(`get | returned=${WhereQueryBuilder.safeStringify(result)}`)
+
       this.reset()
       return result
     }
@@ -272,6 +299,11 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
       const [whereClause, whereParams] = this.buildWhereClause()
       const query = `SELECT COUNT(*) AS __count FROM ${quoteIdentifier(this.getTableName())}${whereClause}`
 
+      // Info-level log
+      this.selectLog.info(
+        `count | query=${query} params=${WhereQueryBuilder.safeStringify(whereParams)}`
+      )
+
       this.selectLog.query("COUNT", query, whereParams)
 
       const result = this.getDb()
@@ -279,6 +311,10 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
         .get(...whereParams) as { __count: number } | null
 
       this.reset()
+
+      // Info-level log for returned count
+      this.selectLog.info(`count | returned=${result?.__count ?? 0}`)
+
       return result?.__count ?? 0
     }
 
@@ -297,6 +333,11 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
       const subquery = `SELECT 1 FROM ${quoteIdentifier(this.getTableName())}${whereClause} LIMIT 1`
       const query = `SELECT EXISTS(${subquery}) AS __exists`
 
+      // Info-level log
+      this.selectLog.info(
+        `exists | query=${query} params=${WhereQueryBuilder.safeStringify(whereParams)}`
+      )
+
       this.selectLog.query("EXISTS", query, whereParams)
 
       const result = this.getDb()
@@ -304,6 +345,10 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
         .get(...whereParams) as { __exists: number } | null
 
       this.reset()
+
+      // Info-level log for returned boolean
+      this.selectLog.info(`exists | returned=${Boolean(result?.__exists)}`)
+
       return Boolean(result?.__exists)
     }
 
@@ -319,7 +364,14 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
    */
   value<K extends keyof T>(column: K): T[K] | null {
     const row = this.first()
-    return row ? row[column] : null
+    const value = row ? row[column] : null
+
+    // Info-level log
+    this.selectLog.info(
+      `value | column=${String(column)} returned=${WhereQueryBuilder.safeStringify(value)}`
+    )
+
+    return value
   }
 
   /**
@@ -330,6 +382,13 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
    */
   pluck<K extends keyof T>(column: K): T[K][] {
     const rows = this.all()
-    return rows.map((row) => row[column])
+    const values = rows.map((row) => row[column])
+
+    // Info-level log
+    this.selectLog.info(
+      `pluck | column=${String(column)} returned=${WhereQueryBuilder.safeStringify(values)}`
+    )
+
+    return values
   }
 }

package/src/query-builder/where.ts

@@ -54,6 +54,15 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
 
   // ===== Public WHERE Methods =====
 
+  // Helper to stringify values safely (converts RegExp to string and falls back)
+  protected static safeStringify(obj: unknown): string {
+    try {
+      return JSON.stringify(obj, (_k, v) => (v instanceof RegExp ? v.toString() : v))
+    } catch {
+      return String(obj)
+    }
+  }
+
   /**
    * Add simple equality conditions to the WHERE clause
    *
@@ -66,6 +75,9 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "deleted_at" IS NULL
    */
   where(conditions: WhereCondition<T>): this {
+    // Log invocation with a safe serializer (handles RegExp and other non-JSON types)
+    this.log.info(`where | conditions=${WhereQueryBuilder.safeStringify(conditions)}`)
+
     for (const [column, value] of Object.entries(conditions)) {
       this.removeExistingCondition(column)
 
@@ -76,6 +88,14 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
         this.state.whereParams.push(this.toSqliteValue(value))
       }
     }
+
+    // Log resulting WHERE clause state
+    this.log.info(
+      `where | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -86,6 +106,9 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * .whereRgx({ email: /@gmail\.com$/ })
    */
   whereRgx(conditions: RegexCondition<T>): this {
+    // Log invocation with a safe serializer for regex values
+    this.log.info(`whereRgx | conditions=${WhereQueryBuilder.safeStringify(conditions)}`)
+
     for (const [column, value] of Object.entries(conditions)) {
       this.removeExistingCondition(column)
 
@@ -105,6 +128,14 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
         this.state.whereParams.push(value as SQLQueryBindings)
       }
     }
+
+    // Log resulting WHERE/regex state
+    this.log.info(
+      `whereRgx | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} regexConditions=${WhereQueryBuilder.safeStringify(
+        this.state.regexConditions
+      )} params=${WhereQueryBuilder.safeStringify(this.state.whereParams)}`
+    )
+
     return this
   }
 
@@ -116,6 +147,9 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * .whereExpr("created_at > datetime('now', '-1 day')")
    */
   whereExpr(expr: string, params: SQLQueryBindings[] = []): this {
+    // Log invocation
+    this.log.info(`whereExpr | expr=${expr} params=${WhereQueryBuilder.safeStringify(params)}`)
+
     if (!expr || typeof expr !== "string") {
       throw new Error("whereExpr: expression must be a non-empty string")
     }
@@ -127,6 +161,13 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
       this.state.whereParams.push(...params)
     }
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereExpr | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -134,6 +175,8 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * Alias for whereExpr
    */
   whereRaw(expr: string, params: SQLQueryBindings[] = []): this {
+    // Log alias invocation
+    this.log.info(`whereRaw | expr=${expr} params=${WhereQueryBuilder.safeStringify(params)}`)
     return this.whereExpr(expr, params)
   }
 
@@ -145,6 +188,11 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "status" IN (?, ?)
    */
   whereIn(column: keyof T, values: SQLQueryBindings[]): this {
+    // Log invocation
+    this.log.info(
+      `whereIn | column=${String(column)} values=${WhereQueryBuilder.safeStringify(values)}`
+    )
+
     if (!Array.isArray(values) || values.length === 0) {
       throw new Error("whereIn: values must be a non-empty array")
     }
@@ -155,6 +203,13 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
     this.state.whereConditions.push(sql)
     this.state.whereParams.push(...params)
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereIn | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -166,6 +221,11 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "role" NOT IN (?, ?)
    */
   whereNotIn(column: keyof T, values: SQLQueryBindings[]): this {
+    // Log invocation
+    this.log.info(
+      `whereNotIn | column=${String(column)} values=${WhereQueryBuilder.safeStringify(values)}`
+    )
+
     if (!Array.isArray(values) || values.length === 0) {
       throw new Error("whereNotIn: values must be a non-empty array")
     }
@@ -176,6 +236,13 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
     this.state.whereConditions.push(sql)
     this.state.whereParams.push(...params)
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereNotIn | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -189,6 +256,11 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * .whereOp("name", "LIKE", "%smith%")
    */
   whereOp(column: keyof T, op: string, value: SQLQueryBindings): this {
+    // Log invocation
+    this.log.info(
+      `whereOp | column=${String(column)} op=${op} value=${WhereQueryBuilder.safeStringify(value)}`
+    )
+
     const normalizedOp = normalizeOperator(op)
     const columnStr = String(column)
 
@@ -196,10 +268,13 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
     if (value === null || value === undefined) {
       if (normalizedOp === "=" || normalizedOp === "IS") {
         this.state.whereConditions.push(`${quoteIdentifier(columnStr)} IS NULL`)
+        // Log resulting state for null-case
+        this.log.info(`whereOp | added IS NULL for ${columnStr}`)
         return this
       }
       if (normalizedOp === "!=" || normalizedOp === "<>" || normalizedOp === "IS NOT") {
         this.state.whereConditions.push(`${quoteIdentifier(columnStr)} IS NOT NULL`)
+        this.log.info(`whereOp | added IS NOT NULL for ${columnStr}`)
         return this
       }
     }
@@ -207,6 +282,13 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
     this.state.whereConditions.push(`${quoteIdentifier(columnStr)} ${normalizedOp} ?`)
     this.state.whereParams.push(value)
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereOp | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -218,12 +300,26 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "age" BETWEEN ? AND ?
    */
   whereBetween(column: keyof T, min: SQLQueryBindings, max: SQLQueryBindings): this {
+    // Log invocation
+    this.log.info(
+      `whereBetween | column=${String(column)} min=${WhereQueryBuilder.safeStringify(min)} max=${WhereQueryBuilder.safeStringify(
+        max
+      )}`
+    )
+
     this.removeExistingCondition(String(column), "BETWEEN")
 
     const { sql, params } = buildBetweenClause(String(column), min, max, false)
     this.state.whereConditions.push(sql)
     this.state.whereParams.push(...params)
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereBetween | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -235,12 +331,26 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "score" NOT BETWEEN ? AND ?
    */
   whereNotBetween(column: keyof T, min: SQLQueryBindings, max: SQLQueryBindings): this {
+    // Log invocation
+    this.log.info(
+      `whereNotBetween | column=${String(column)} min=${WhereQueryBuilder.safeStringify(min)} max=${WhereQueryBuilder.safeStringify(
+        max
+      )}`
+    )
+
     this.removeExistingCondition(String(column), "NOT BETWEEN")
 
     const { sql, params } = buildBetweenClause(String(column), min, max, true)
     this.state.whereConditions.push(sql)
     this.state.whereParams.push(...params)
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereNotBetween | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -252,8 +362,19 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "deleted_at" IS NULL
    */
   whereNull(column: keyof T): this {
+    // Log invocation
+    this.log.info(`whereNull | column=${String(column)}`)
+
     this.removeExistingCondition(String(column))
     this.state.whereConditions.push(`${quoteIdentifier(String(column))} IS NULL`)
+
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereNull | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -265,8 +386,19 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "email" IS NOT NULL
    */
   whereNotNull(column: keyof T): this {
+    // Log invocation
+    this.log.info(`whereNotNull | column=${String(column)}`)
+
     this.removeExistingCondition(String(column))
     this.state.whereConditions.push(`${quoteIdentifier(String(column))} IS NOT NULL`)
+
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereNotNull | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 }