@dockstat/sqlite-wrapper 1.2.8 → 1.3.1

package/utils/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Utilities for sqlite-wrapper
+ *
+ * Re-exports all utility modules for easy importing.
+ */
+
+// Logger utilities
+export {
+  addLoggerParents,
+  createLogger,
+  createSqliteBaseLogger,
+  logger,
+  SqliteLogger,
+  setSqliteLogHook,
+} from "./logger"
+
+// SQL utilities
+export {
+  buildBetweenClause,
+  buildCondition,
+  buildDeleteSQL,
+  buildInClause,
+  buildInsertSQL,
+  buildPlaceholders,
+  buildSelectSQL,
+  buildSetClause,
+  buildUpdateSQL,
+  escapeValue,
+  isSQLFunction,
+  normalizeOperator,
+  quoteIdentifier,
+  quoteIdentifiers,
+  quoteString,
+} from "./sql"
+
+// Transformer utilities
+export {
+  getParserSummary,
+  hasTransformations,
+  type RowData,
+  type TransformOptions,
+  transformFromDb,
+  transformRowsFromDb,
+  transformRowsToDb,
+  transformToDb,
+} from "./transformer"

package/utils/logger.ts

@@ -0,0 +1,216 @@
+import { Logger, type LogHook } from "@dockstat/logger"
+
+/**
+ * Centralized logging for sqlite-wrapper
+ *
+ * This module provides a clean, consistent logging interface
+ * for all sqlite-wrapper operations.
+ */
+
+/**
+ * Truncate a string to a maximum length with ellipsis
+ */
+function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str
+  return `${str.slice(0, maxLength)}...`
+}
+
+/**
+ * Format query parameters for logging (truncated for readability)
+ */
+function formatParams(params?: unknown[]): string {
+  if (!params || params.length === 0) return ""
+  const str = JSON.stringify(params)
+  return truncate(str, 60)
+}
+
+/**
+ * SqliteLogger - A wrapper around @dockstat/logger with sqlite-specific helpers
+ */
+export class SqliteLogger {
+  private logger: Logger
+  private tableName?: string
+
+  constructor(name: string, parent?: Logger, tableName?: string, logHook?: LogHook) {
+    try {
+      this.logger =
+        typeof parent?.spawn === "function" ? parent.spawn(name) : new Logger(name, [], logHook)
+    } catch (error) {
+      this.logger = new Logger(name, [], logHook)
+      console.error(error)
+    }
+
+    this.tableName = tableName
+  }
+
+  /**
+   * Create a child logger for a specific component
+   */
+  child(name: string): SqliteLogger {
+    return new SqliteLogger(name, this.logger, this.tableName)
+  }
+
+  /**
+   * Create a table-scoped logger
+   */
+  forTable(tableName: string): SqliteLogger {
+    const child = new SqliteLogger(tableName, this.logger, tableName)
+    return child
+  }
+
+  // ===== Standard log methods =====
+
+  debug(message: string): void {
+    this.logger.debug(message)
+  }
+
+  info(message: string): void {
+    this.logger.info(message)
+  }
+
+  warn(message: string): void {
+    this.logger.warn(message)
+  }
+
+  error(message: string): void {
+    this.logger.error(message)
+  }
+
+  // ===== Sqlite-specific log helpers =====
+
+  /**
+   * Log a database connection event
+   */
+  connection(path: string, action: "open" | "close"): void {
+    this.logger.info(`Database ${action}: ${path}`)
+  }
+
+  /**
+   * Log a SQL query execution
+   */
+  query(operation: string, sql: string, params?: unknown[]): void {
+    const paramStr = formatParams(params)
+    const sqlStr = truncate(sql.replace(/\s+/g, " ").trim(), 100)
+    const msg = paramStr
+      ? `${operation} | ${sqlStr} | params=${paramStr}`
+      : `${operation} | ${sqlStr}`
+    this.logger.debug(msg)
+  }
+
+  /**
+   * Log query results
+   */
+  result(operation: string, rowCount: number): void {
+    this.logger.debug(`${operation} | rows=${rowCount}`)
+  }
+
+  /**
+   * Log a table creation
+   */
+  tableCreate(tableName: string, columns: string[]): void {
+    this.logger.debug(`CREATE TABLE ${tableName} | columns=[${columns.join(", ")}]`)
+  }
+
+  /**
+   * Log backup operations
+   */
+  backup(action: "create" | "restore" | "list" | "delete", path?: string): void {
+    const msg = path ? `Backup ${action}: ${path}` : `Backup ${action}`
+    this.logger.info(msg)
+  }
+
+  /**
+   * Log row transformation
+   */
+  transform(direction: "serialize" | "deserialize", columnTypes: string[]): void {
+    if (columnTypes.length === 0) return
+    this.logger.debug(`Transform ${direction}: [${columnTypes.join(", ")}]`)
+  }
+
+  /**
+   * Log parser configuration
+   */
+  parserConfig(json: string[], boolean: string[], module: string[]): void {
+    const parts: string[] = []
+    if (json.length > 0) parts.push(`JSON=[${json.join(",")}]`)
+    if (boolean.length > 0) parts.push(`BOOL=[${boolean.join(",")}]`)
+    if (module.length > 0) parts.push(`MODULE=[${module.join(",")}]`)
+    if (parts.length > 0) {
+      this.logger.debug(`Parser config: ${parts.join(" ")}`)
+    }
+  }
+
+  /**
+   * Log transaction events
+   */
+  transaction(action: "begin" | "commit" | "rollback" | "savepoint", name?: string): void {
+    const msg = name ? `Transaction ${action}: ${name}` : `Transaction ${action}`
+    this.logger.debug(msg)
+  }
+
+  /**
+   * Get the underlying @dockstat/logger instance
+   */
+  getBaseLogger(): Logger {
+    return this.logger
+  }
+
+  /**
+   * Add parent loggers for chaining
+   */
+  addParents(parents: string[]): void {
+    this.logger.addParents(parents)
+  }
+
+  /**
+   * Get parents for logger chaining
+   */
+  getParentsForLoggerChaining(): string[] {
+    return this.logger.getParentsForLoggerChaining()
+  }
+}
+
+// ===== Module exports =====
+
+/**
+ * Main logger instance for sqlite-wrapper
+ */
+export const logger = new SqliteLogger("Sqlite")
+
+/**
+ * Create a new logger for a specific module
+ */
+export function createLogger(name: string, baseLogger?: Logger): SqliteLogger {
+  // If a base logger is provided (recommended for apps/packages that want shared LogHook/parents),
+  // derive a sqlite-scoped child logger from it.
+  if (baseLogger) return new SqliteLogger(name, baseLogger)
+
+  // Fallback to the package-level logger (works, but won't automatically inherit app hooks)
+  return logger.child(name)
+}
+
+export function addLoggerParents(parents: string[]): void {
+  logger.addParents(parents)
+}
+
+/**
+ * Configure a shared LogHook for sqlite-wrapper's root logger.
+ *
+ * Useful when consumers (e.g. `apps/api`, `packages/db`) want sqlite-wrapper logs
+ * to be routed through the same sink/formatter as the rest of the app.
+ */
+export function setSqliteLogHook(logHook: LogHook): void {
+  logger.getBaseLogger().setLogHook(logHook)
+}
+
+/**
+ * Optional convenience for consumers: create a sqlite-scoped base Logger that shares a LogHook.
+ *
+ * This is handy if you want to pass a base logger into `createLogger()` / `DB` and have
+ * everything inherit the same hook.
+ */
+export function createSqliteBaseLogger(logHook?: LogHook): Logger {
+  return new Logger("Sqlite", [], logHook)
+}
+
+export default logger

package/utils/sql.ts

@@ -0,0 +1,241 @@
+import type { SQLQueryBindings } from "bun:sqlite"
+
+/**
+ * SQL Utilities for sqlite-wrapper
+ *
+ * Common SQL operations and helpers used across the package.
+ */
+
+/**
+ * Quote a SQL identifier (table name, column name) to prevent injection
+ * and handle special characters.
+ *
+ * @example
+ * quoteIdentifier("users") // "users"
+ * quoteIdentifier("user name") // "user name"
+ * quoteIdentifier('with"quote') // "with""quote"
+ */
+export function quoteIdentifier(identifier: string): string {
+  return `"${identifier.replace(/"/g, '""')}"`
+}
+
+/**
+ * Quote a SQL string literal value
+ *
+ * @example
+ * quoteString("hello") // 'hello'
+ * quoteString("it's") // 'it''s'
+ */
+export function quoteString(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`
+}
+
+/**
+ * Build a comma-separated list of quoted identifiers
+ *
+ * @example
+ * quoteIdentifiers(["id", "name", "email"]) // "id", "name", "email"
+ */
+export function quoteIdentifiers(identifiers: string[]): string {
+  return identifiers.map(quoteIdentifier).join(", ")
+}
+
+/**
+ * Build placeholders for parameterized queries
+ *
+ * @example
+ * buildPlaceholders(3) // "?, ?, ?"
+ * buildPlaceholders(["a", "b"]) // "?, ?"
+ */
+export function buildPlaceholders(countOrArray: number | unknown[]): string {
+  const count = typeof countOrArray === "number" ? countOrArray : countOrArray.length
+  return Array(count).fill("?").join(", ")
+}
+
+/**
+ * Build a SET clause for UPDATE statements
+ *
+ * @example
+ * buildSetClause(["name", "email"]) // "name" = ?, "email" = ?
+ */
+export function buildSetClause(columns: string[]): string {
+  return columns.map((col) => `${quoteIdentifier(col)} = ?`).join(", ")
+}
+
+/**
+ * Build an INSERT statement
+ */
+export function buildInsertSQL(
+  table: string,
+  columns: string[],
+  conflictResolution?: "IGNORE" | "REPLACE" | "ABORT" | "FAIL" | "ROLLBACK"
+): string {
+  const insertType = conflictResolution ? `INSERT OR ${conflictResolution}` : "INSERT"
+  const quotedColumns = quoteIdentifiers(columns)
+  const placeholders = buildPlaceholders(columns)
+
+  return `${insertType} INTO ${quoteIdentifier(table)} (${quotedColumns}) VALUES (${placeholders})`
+}
+
+/**
+ * Build a simple SELECT statement
+ */
+export function buildSelectSQL(
+  table: string,
+  columns: string[] | "*",
+  options?: {
+    where?: string
+    orderBy?: string
+    orderDirection?: "ASC" | "DESC"
+    limit?: number
+    offset?: number
+  }
+): string {
+  const cols = columns === "*" ? "*" : quoteIdentifiers(columns)
+  let sql = `SELECT ${cols} FROM ${quoteIdentifier(table)}`
+
+  if (options?.where) {
+    sql += ` WHERE ${options.where}`
+  }
+
+  if (options?.orderBy) {
+    sql += ` ORDER BY ${quoteIdentifier(options.orderBy)} ${options.orderDirection || "ASC"}`
+  }
+
+  if (options?.limit !== undefined) {
+    sql += ` LIMIT ${options.limit}`
+  }
+
+  if (options?.offset !== undefined) {
+    sql += ` OFFSET ${options.offset}`
+  }
+
+  return sql
+}
+
+/**
+ * Build an UPDATE statement
+ */
+export function buildUpdateSQL(table: string, columns: string[], where: string): string {
+  const setClause = buildSetClause(columns)
+  return `UPDATE ${quoteIdentifier(table)} SET ${setClause} WHERE ${where}`
+}
+
+/**
+ * Build a DELETE statement
+ */
+export function buildDeleteSQL(table: string, where: string): string {
+  return `DELETE FROM ${quoteIdentifier(table)} WHERE ${where}`
+}
+
+/**
+ * Check if a string looks like a SQL function call
+ *
+ * @example
+ * isSQLFunction("datetime('now')") // true
+ * isSQLFunction("CURRENT_TIMESTAMP") // true
+ * isSQLFunction("hello") // false
+ */
+export function isSQLFunction(value: string): boolean {
+  const functionPatterns = [
+    /^\w+\s*\(/i, // function(...)
+    /^CURRENT_TIME(STAMP)?$/i,
+    /^CURRENT_DATE$/i,
+    /^NULL$/i,
+  ]
+  return functionPatterns.some((pattern) => pattern.test(value.trim()))
+}
+
+/**
+ * Escape a value for safe inclusion in SQL
+ * Returns the SQLite-safe representation
+ */
+export function escapeValue(value: SQLQueryBindings): string {
+  if (value === null) return "NULL"
+  if (typeof value === "number") return String(value)
+  if (typeof value === "boolean") return value ? "1" : "0"
+  if (typeof value === "string") return quoteString(value)
+  if (value instanceof Uint8Array) return `X'${Buffer.from(value).toString("hex")}'`
+  return quoteString(String(value))
+}
+
+/**
+ * Normalize a comparison operator
+ */
+export function normalizeOperator(op: string): string {
+  const normalized = op.toUpperCase().trim()
+  const allowed = ["=", "!=", "<>", "<", "<=", ">", ">=", "LIKE", "GLOB", "IS", "IS NOT"]
+
+  if (!allowed.includes(normalized)) {
+    throw new Error(`Invalid SQL operator: "${op}"`)
+  }
+
+  return normalized
+}
+
+/**
+ * Build a WHERE condition for a single column
+ */
+export function buildCondition(
+  column: string,
+  operator: string,
+  value: SQLQueryBindings | null | undefined
+): { sql: string; params: SQLQueryBindings[] } {
+  const normalizedOp = normalizeOperator(operator)
+  const quotedCol = quoteIdentifier(column)
+
+  // Handle NULL special cases
+  if (value === null || value === undefined) {
+    if (normalizedOp === "=" || normalizedOp === "IS") {
+      return { sql: `${quotedCol} IS NULL`, params: [] }
+    }
+    if (normalizedOp === "!=" || normalizedOp === "<>" || normalizedOp === "IS NOT") {
+      return { sql: `${quotedCol} IS NOT NULL`, params: [] }
+    }
+  }
+
+  return {
+    sql: `${quotedCol} ${normalizedOp} ?`,
+    params: [value as SQLQueryBindings],
+  }
+}
+
+/**
+ * Build an IN clause
+ */
+export function buildInClause(
+  column: string,
+  values: SQLQueryBindings[],
+  negate = false
+): { sql: string; params: SQLQueryBindings[] } {
+  if (values.length === 0) {
+    throw new Error("IN clause requires at least one value")
+  }
+
+  const quotedCol = quoteIdentifier(column)
+  const placeholders = buildPlaceholders(values)
+  const keyword = negate ? "NOT IN" : "IN"
+
+  return {
+    sql: `${quotedCol} ${keyword} (${placeholders})`,
+    params: values,
+  }
+}
+
+/**
+ * Build a BETWEEN clause
+ */
+export function buildBetweenClause(
+  column: string,
+  min: SQLQueryBindings,
+  max: SQLQueryBindings,
+  negate = false
+): { sql: string; params: SQLQueryBindings[] } {
+  const quotedCol = quoteIdentifier(column)
+  const keyword = negate ? "NOT BETWEEN" : "BETWEEN"
+
+  return {
+    sql: `${quotedCol} ${keyword} ? AND ?`,
+    params: [min, max],
+  }
+}