@dockstat/sqlite-wrapper 1.2.7 → 1.3.0

package/utils/logger.ts

@@ -0,0 +1,184 @@
+import Logger 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) {
+    this.logger = parent ? parent.spawn(name) : new Logger(name)
+    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): SqliteLogger {
+  return logger.child(name)
+}
+
+export function addLoggerParents(parents: string[]): void {
+  logger.addParents(parents)
+}
+
+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],
+  }
+}

package/utils/transformer.ts

@@ -0,0 +1,256 @@
+import type { SQLQueryBindings } from "bun:sqlite"
+import type { Parser } from "../types"
+import { createLogger } from "./logger"
+
+/**
+ * Row Transformer for sqlite-wrapper
+ *
+ * Handles serialization (to DB) and deserialization (from DB) of row data,
+ * including JSON columns, Boolean columns, and Module columns.
+ */
+
+const logger = createLogger("transformer")
+
+/**
+ * Generic row data type
+ */
+export type RowData = Record<string, SQLQueryBindings>
+
+/**
+ * Transform options
+ */
+export interface TransformOptions<T> {
+  parser?: Parser<T>
+}
+
+/**
+ * Transform a row FROM the database (deserialization)
+ *
+ * - JSON columns: Parse JSON strings back to objects
+ * - BOOLEAN columns: Convert 0/1 to true/false
+ * - MODULE columns: Transpile and create importable URLs
+ */
+export function transformFromDb<T extends Record<string, unknown>>(
+  row: unknown,
+  options?: TransformOptions<T>
+): T {
+  if (!row || typeof row !== "object") {
+    return row as T
+  }
+
+  const parser = options?.parser
+  if (!parser) {
+    return row as T
+  }
+
+  const transformed = { ...row } as RowData
+  const transformedColumns: string[] = []
+
+  // Transform JSON columns
+  if (parser.JSON && parser.JSON.length > 0) {
+    for (const column of parser.JSON) {
+      const columnKey = String(column)
+      const value = transformed[columnKey]
+
+      if (value !== null && value !== undefined && typeof value === "string") {
+        try {
+          transformed[columnKey] = JSON.parse(value)
+          transformedColumns.push(`JSON:${columnKey}`)
+        } catch {
+          // Keep original value if JSON parsing fails
+          logger.warn(`Failed to parse JSON column: ${columnKey}`)
+        }
+      }
+    }
+  }
+
+  // Transform BOOLEAN columns
+  if (parser.BOOLEAN && parser.BOOLEAN.length > 0) {
+    for (const column of parser.BOOLEAN) {
+      const columnKey = String(column)
+      const value = transformed[columnKey]
+
+      if (value === null || value === undefined) {
+        continue
+      }
+
+      // Already a boolean - no transformation needed
+      if (typeof value === "boolean") {
+        continue
+      }
+
+      // Convert number (0/1) to boolean
+      if (typeof value === "number") {
+        transformed[columnKey] = value === 1
+        transformedColumns.push(`BOOL:${columnKey}`)
+        continue
+      }
+
+      // Convert string representations
+      if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase()
+        if (["1", "true", "t", "yes"].includes(normalized)) {
+          transformed[columnKey] = true
+          transformedColumns.push(`BOOL:${columnKey}`)
+        } else if (["0", "false", "f", "no"].includes(normalized)) {
+          transformed[columnKey] = false
+          transformedColumns.push(`BOOL:${columnKey}`)
+        } else {
+          // Try numeric conversion
+          const num = Number(normalized)
+          if (!Number.isNaN(num)) {
+            transformed[columnKey] = num === 1
+            transformedColumns.push(`BOOL:${columnKey}`)
+          }
+        }
+      }
+    }
+  }
+
+  // Transform MODULE columns
+  if (parser.MODULE && Object.keys(parser.MODULE).length > 0) {
+    for (const [funcKey, options] of Object.entries(parser.MODULE)) {
+      const value = transformed[funcKey]
+
+      if (value !== undefined && value !== null && typeof value === "string") {
+        try {
+          const transpiler = new Bun.Transpiler(options)
+          const compiled = transpiler.transformSync(value)
+          const blob = new Blob([compiled], { type: "text/javascript" })
+          transformed[funcKey] = URL.createObjectURL(blob)
+          transformedColumns.push(`MODULE:${funcKey}`)
+        } catch (_error) {
+          logger.warn(`Failed to transpile MODULE column: ${funcKey}`)
+        }
+      }
+    }
+  }
+
+  if (transformedColumns.length > 0) {
+    logger.transform("deserialize", transformedColumns)
+  }
+
+  return transformed as T
+}
+
+/**
+ * Transform multiple rows FROM the database
+ */
+export function transformRowsFromDb<T extends Record<string, unknown>>(
+  rows: unknown[],
+  options?: TransformOptions<T>
+): T[] {
+  if (!rows || !Array.isArray(rows)) {
+    return []
+  }
+
+  return rows.map((row) => transformFromDb<T>(row, options))
+}
+
+/**
+ * Transform a row TO the database (serialization)
+ *
+ * - JSON columns: Stringify objects to JSON strings
+ * - MODULE columns: Stringify functions
+ */
+export function transformToDb<T extends Record<string, unknown>>(
+  row: Partial<T>,
+  options?: TransformOptions<T>
+): RowData {
+  if (!row || typeof row !== "object") {
+    return row as RowData
+  }
+
+  const parser = options?.parser
+  if (!parser) {
+    return row as RowData
+  }
+
+  const transformed = { ...row } as RowData
+  const transformedColumns: string[] = []
+
+  // Serialize JSON columns
+  if (parser.JSON && parser.JSON.length > 0) {
+    for (const column of parser.JSON) {
+      const columnKey = String(column)
+      const value = transformed[columnKey]
+
+      if (value !== undefined && value !== null && typeof value === "object") {
+        transformed[columnKey] = JSON.stringify(value)
+        transformedColumns.push(`JSON:${columnKey}`)
+      }
+    }
+  }
+
+  // Serialize MODULE columns (functions to strings)
+  if (parser.MODULE && Object.keys(parser.MODULE).length > 0) {
+    for (const [funcKey, options] of Object.entries(parser.MODULE)) {
+      const value = transformed[funcKey]
+
+      if (value !== undefined && value !== null && typeof value === "function") {
+        try {
+          const transpiler = new Bun.Transpiler(options)
+          const fnValue = value as () => unknown
+          transformed[funcKey] = transpiler.transformSync(fnValue.toString())
+          transformedColumns.push(`MODULE:${funcKey}`)
+        } catch {
+          logger.warn(`Failed to serialize MODULE column: ${funcKey}`)
+        }
+      }
+    }
+  }
+
+  if (transformedColumns.length > 0) {
+    logger.transform("serialize", transformedColumns)
+  }
+
+  return transformed
+}
+
+/**
+ * Transform multiple rows TO the database
+ */
+export function transformRowsToDb<T extends Record<string, unknown>>(
+  rows: Partial<T>[],
+  options?: TransformOptions<T>
+): RowData[] {
+  if (!rows || !Array.isArray(rows)) {
+    return []
+  }
+
+  return rows.map((row) => transformToDb<T>(row, options))
+}
+
+/**
+ * Check if a parser has any transformations configured
+ */
+export function hasTransformations<T>(parser?: Parser<T>): boolean {
+  if (!parser) return false
+
+  const hasJson = !!(parser.JSON && parser.JSON.length > 0)
+  const hasBoolean = !!(parser.BOOLEAN && parser.BOOLEAN.length > 0)
+  const hasModule = !!(parser.MODULE && Object.keys(parser.MODULE).length > 0)
+
+  return hasJson || hasBoolean || hasModule
+}
+
+/**
+ * Get a summary of parser configuration
+ */
+export function getParserSummary<T>(parser?: Parser<T>): string {
+  if (!parser) return "none"
+
+  const parts: string[] = []
+
+  if (parser.JSON && parser.JSON.length > 0) {
+    parts.push(`JSON(${parser.JSON.length})`)
+  }
+  if (parser.BOOLEAN && parser.BOOLEAN.length > 0) {
+    parts.push(`BOOL(${parser.BOOLEAN.length})`)
+  }
+  if (parser.MODULE && Object.keys(parser.MODULE).length > 0) {
+    parts.push(`MODULE(${Object.keys(parser.MODULE).length})`)
+  }
+
+  return parts.length > 0 ? parts.join(", ") : "none"
+}