@dockstat/sqlite-wrapper 1.3.2 → 1.3.4

package/src/lib/backup/backup.ts

@@ -0,0 +1,56 @@
+import { Database } from "bun:sqlite"
+import type { AutoBackupOptions } from "../../index"
+import { applyRetentionPolicy } from "./applyRetentionPolicy"
+
+/**
+ * Create a backup of the database
+ *
+ * @param dbPath - original DB path
+ * @param db - Database instance
+ * @param backupLog - logger
+ * @param autoBackupOptions - if present, used to create filename and apply retention
+ * @param customPath - optional explicit backup path
+ * @returns path to created backup
+ */
+export function backup(
+  dbPath: string,
+  db: Database,
+  backupLog: any,
+  autoBackupOptions?: AutoBackupOptions,
+  customPath?: string
+): string {
+  if (dbPath === ":memory:") {
+    throw new Error("Cannot backup an in-memory database")
+  }
+
+  const path = require("node:path")
+
+  let backupPath: string
+
+  if (customPath) {
+    backupPath = customPath
+  } else if (autoBackupOptions) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-")
+    const filename = `${autoBackupOptions.filenamePrefix}_${timestamp}.db`
+    backupPath = path.join(autoBackupOptions.directory, filename)
+  } else {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-")
+    const dir = path.dirname(dbPath)
+    const basename = path.basename(dbPath, path.extname(dbPath))
+    backupPath = path.join(dir, `${basename}_backup_${timestamp}.db`)
+  }
+
+  try {
+    db.run(`VACUUM INTO '${backupPath.replace(/'/g, "''")}'`)
+    backupLog.backup("create", backupPath)
+
+    if (autoBackupOptions) {
+      applyRetentionPolicy(backupLog, autoBackupOptions)
+    }
+
+    return backupPath
+  } catch (error) {
+    backupLog.error(`Failed to create backup: ${error}`)
+    throw error
+  }
+}

package/src/lib/backup/listBackups.ts

@@ -0,0 +1,44 @@
+import type { AutoBackupOptions } from "../../index"
+
+/**
+ * List all available backups
+ *
+ * @param autoBackupOptions - Auto-backup configuration (if not present, warns and returns empty array)
+ * @param backupLog - logger used for warnings/errors
+ * @returns Array of backup file information
+ */
+export function listBackups(
+  autoBackupOptions: AutoBackupOptions | null | undefined,
+  backupLog: any
+): Array<{ filename: string; path: string; size: number; created: Date }> {
+  if (!autoBackupOptions) {
+    backupLog.warn("Auto-backup is not configured. Use backup() with a custom path instead.")
+    return []
+  }
+
+  const fs = require("node:fs")
+  const path = require("node:path")
+
+  const backupDir = autoBackupOptions.directory
+  const prefix = autoBackupOptions.filenamePrefix || "backup"
+
+  try {
+    return fs
+      .readdirSync(backupDir)
+      .filter((file: string) => file.startsWith(prefix) && file.endsWith(".db"))
+      .map((file: string) => {
+        const filePath = path.join(backupDir, file)
+        const stats = fs.statSync(filePath)
+        return {
+          filename: file,
+          path: filePath,
+          size: stats.size,
+          created: stats.mtime,
+        }
+      })
+      .sort((a: { created: Date }, b: { created: Date }) => b.created.getTime() - a.created.getTime())
+  } catch (error) {
+    backupLog.error(`Failed to list backups: ${error}`)
+    return []
+  }
+}

package/src/lib/backup/restore.ts

@@ -0,0 +1,61 @@
+import { Database } from "bun:sqlite"
+import type { SqliteLogger } from "../../utils"
+
+/**
+ * Restore database from a backup file
+ *
+ * Copies backupPath -> targetPath (or dbPath if targetPath omitted).
+ * If restoring to the same path as dbPath, closes the provided Database
+ * instance and reopens a new Database, returning it to the caller so the
+ * DB wrapper can replace its `this.db` reference.
+ *
+ * @returns Database | null — a newly opened Database instance when the restore was
+ * performed to the original dbPath (caller must replace its db reference);
+ * otherwise null.
+ */
+export function restore(
+  dbPath: string,
+  db: Database,
+  backupLog: SqliteLogger,
+  backupPath: string,
+  targetPath?: string
+): Database | null {
+  const fs = require("node:fs")
+
+  if (!fs.existsSync(backupPath)) {
+    throw new Error(`Backup file not found: ${backupPath}`)
+  }
+
+  const restorePath = targetPath || dbPath
+
+  if (restorePath === ":memory:") {
+    throw new Error("Cannot restore to an in-memory database path")
+  }
+
+  // If restoring to the same path, close current connection first
+  if (restorePath === dbPath) {
+    try {
+      db.close()
+    } catch (err) {
+      // continue — if close fails, copy may still succeed or re-open will error
+      backupLog.warn(`Error closing DB before restore: ${err}`)
+    }
+  }
+
+  try {
+    fs.copyFileSync(backupPath, restorePath)
+    backupLog.backup("restore", backupPath)
+
+    // If we restored to the original database path, reopen and return new Database
+    if (restorePath === dbPath) {
+      const reopened = new Database(dbPath)
+      backupLog.info("Database connection reopened after restore")
+      return reopened
+    }
+
+    return null
+  } catch (error) {
+    backupLog.error(`Failed to restore backup: ${error}`)
+    throw error
+  }
+}

package/src/lib/backup/setupAutoBackup.ts

@@ -0,0 +1,55 @@
+import type { AutoBackupOptions } from "../../index"
+import { backup } from "./backup"
+import { applyRetentionPolicy } from "./applyRetentionPolicy"
+
+export function setupAutoBackup(
+  dbPath: string,
+  db: any,
+  backupLog: any,
+  options: AutoBackupOptions
+): { timer: ReturnType<typeof setInterval> | null; autoBackupOptions: AutoBackupOptions } {
+  if (dbPath === ":memory:") {
+    backupLog.warn("Auto-backup is not available for in-memory databases")
+  }
+
+  const autoBackupOptions: AutoBackupOptions = {
+    enabled: options.enabled,
+    directory: options.directory,
+    intervalMs: options.intervalMs ?? 60 * 60 * 1000,
+    maxBackups: options.maxBackups ?? 10,
+    filenamePrefix: options.filenamePrefix ?? "backup",
+    compress: options.compress ?? false,
+  }
+
+  const fs = require("node:fs")
+  const path = require("node:path")
+
+  if (!fs.existsSync(autoBackupOptions.directory)) {
+    fs.mkdirSync(autoBackupOptions.directory, { recursive: true })
+    backupLog.info(`Created backup directory: ${autoBackupOptions.directory}`)
+  }
+
+  // Create initial backup
+  try {
+    backup(dbPath, db, backupLog, autoBackupOptions)
+  } catch (err) {
+    backupLog.error(`Initial backup failed: ${err}`)
+  }
+
+  // Setup interval for periodic backups
+  const timer = setInterval(() => {
+    try {
+      const p = backup(dbPath, db, backupLog, autoBackupOptions)
+      // applyRetentionPolicy already invoked inside backup, but keep safety
+      applyRetentionPolicy(backupLog, autoBackupOptions)
+    } catch (err) {
+      backupLog.error(`Auto-backup run failed: ${err}`)
+    }
+  }, autoBackupOptions.intervalMs)
+
+  backupLog.info(
+    `Auto-backup enabled: interval=${autoBackupOptions.intervalMs}ms, maxBackups=${autoBackupOptions.maxBackups}`
+  )
+
+  return { timer, autoBackupOptions }
+}

package/src/lib/index/createIndex.ts

@@ -0,0 +1,43 @@
+import type { Database } from "bun:sqlite"
+import type { IndexColumn, IndexMethod } from "../../types"
+
+const quoteIdent = (s: string) => `"${s.replace(/"/g, '""')}"`
+
+export function createIndex(
+  db: Database,
+  indexName: string,
+  tableName: string,
+  columns: IndexColumn | IndexColumn[],
+  options?: {
+    unique?: boolean
+    ifNotExists?: boolean
+    partial?: string
+    where?: string
+    using?: IndexMethod
+  }
+): void {
+  const unique = options?.unique ? "UNIQUE " : ""
+  const ifNot = options?.ifNotExists ? "IF NOT EXISTS " : ""
+  const using = options?.using ? ` USING ${options.using}` : ""
+
+  const normalizeColumn = (col: IndexColumn): string => {
+    if (typeof col === "string") {
+      return quoteIdent(col)
+    }
+
+    return `${quoteIdent(col.name)}${col.order ? ` ${col.order}` : ""}`
+  }
+
+  const columnList = Array.isArray(columns)
+    ? columns.map(normalizeColumn).join(", ")
+    : normalizeColumn(columns)
+
+  let sql = `CREATE ${unique}INDEX ${ifNot}${quoteIdent(indexName)} ON ${quoteIdent(tableName)}${using} (${columnList})`
+
+  const where = options?.where ?? options?.partial
+  if (where) {
+    sql += ` WHERE ${where}`
+  }
+
+  db.run(`${sql};`)
+}

package/src/lib/index/dropIndex.ts

@@ -0,0 +1,9 @@
+import type { Database } from "bun:sqlite"
+
+const quoteIdent = (s: string) => `"${s.replace(/"/g, '""')}"`
+
+export function dropIndex(db: Database, indexName: string, options?: { ifExists?: boolean }): void {
+  const ifExists = options?.ifExists ? "IF EXISTS " : ""
+  const sql = `DROP INDEX ${ifExists}${quoteIdent(indexName)};`
+  db.run(sql)
+}

package/src/lib/sql/isSQLFunction.ts

@@ -0,0 +1,15 @@
+/**
+ * Check if a string looks like a SQL function call
+ */
+export function isSQLFunction(str: string): boolean {
+  // Simple heuristic: contains parentheses and common SQL function patterns
+  const functionPatterns = [
+    /^\w+\s*\(/, // Function name followed by (
+    /^(datetime|date|time|strftime|current_timestamp|current_date|current_time)/i,
+    /^(random|abs|length|upper|lower|trim)/i,
+    /^(coalesce|ifnull|nullif|iif)/i,
+    /^(json|json_extract|json_valid)/i,
+  ]
+
+  return functionPatterns.some((pattern) => pattern.test(str.trim()))
+}

package/src/lib/table/buildColumnSQL.ts

@@ -0,0 +1,106 @@
+import type { ColumnDefinition } from "../../types"
+import { isSQLFunction } from "../../utils"
+
+/**
+ * Build SQL column definition from ColumnDefinition object
+ */
+export function buildColumnSQL(columnName: string, colDef: ColumnDefinition): string {
+  const parts: string[] = []
+
+  // Add type with optional parameters
+  let typeStr = colDef.type
+  if (colDef.length) {
+    typeStr += `(${colDef.length})`
+  } else if (colDef.precision !== undefined) {
+    if (colDef.scale !== undefined) {
+      typeStr += `(${colDef.precision}, ${colDef.scale})`
+    } else {
+      typeStr += `(${colDef.precision})`
+    }
+  }
+  parts.push(typeStr)
+
+  // Add PRIMARY KEY (must come before AUTOINCREMENT)
+  if (colDef.primaryKey) {
+    parts.push("PRIMARY KEY")
+  }
+
+  // Add AUTOINCREMENT (only valid with INTEGER PRIMARY KEY)
+  if (colDef.autoincrement) {
+    if (!colDef.type.includes("INT") || !colDef.primaryKey) {
+      throw new Error(
+        `AUTOINCREMENT can only be used with INTEGER PRIMARY KEY columns (column: ${columnName})`
+      )
+    }
+    parts.push("AUTOINCREMENT")
+  }
+
+  // Add NOT NULL (but skip if PRIMARY KEY is already specified, as it's implicit)
+  if (colDef.notNull && !colDef.primaryKey) {
+    parts.push("NOT NULL")
+  }
+
+  // Add UNIQUE
+  if (colDef.unique) {
+    parts.push("UNIQUE")
+  }
+
+  // Add DEFAULT
+  if (colDef.default !== undefined) {
+    if (colDef.default === null) {
+      parts.push("DEFAULT NULL")
+    } else if (typeof colDef.default === "object" && colDef.default._type === "expression") {
+      // Handle DefaultExpression
+      parts.push(`DEFAULT (${colDef.default.expression})`)
+    } else if (typeof colDef.default === "string") {
+      // Handle string defaults - check if it's a function call or literal
+      if (isSQLFunction(colDef.default)) {
+        parts.push(`DEFAULT (${colDef.default})`)
+      } else {
+        // Literal string value
+        parts.push(`DEFAULT '${colDef.default.replace(/'/g, "''")}'`)
+      }
+    } else if (typeof colDef.default === "boolean") {
+      parts.push(`DEFAULT ${colDef.default ? 1 : 0}`)
+    } else {
+      parts.push(`DEFAULT ${colDef.default}`)
+    }
+  }
+
+  // Add COLLATE
+  if (colDef.collate) {
+    parts.push(`COLLATE ${colDef.collate}`)
+  }
+
+  // Add CHECK constraint (replace placeholder with actual column name)
+  if (colDef.check) {
+    const checkConstraint = colDef.check.replace(
+      /\{\{COLUMN\}\}/g,
+      `"${columnName.replace(/"/g, '""')}"`
+    )
+    parts.push(`CHECK (${checkConstraint})`)
+  }
+
+  // Add REFERENCES (foreign key)
+  if (colDef.references) {
+    const ref = colDef.references
+    let refClause = `REFERENCES "${ref.table.replace(/"/g, '""')}"("${ref.column.replace(/"/g, '""')}")`
+
+    if (ref.onDelete) {
+      refClause += ` ON DELETE ${ref.onDelete}`
+    }
+
+    if (ref.onUpdate) {
+      refClause += ` ON UPDATE ${ref.onUpdate}`
+    }
+
+    parts.push(refClause)
+  }
+
+  // Add GENERATED column
+  if (colDef.generated) {
+    const storageType = colDef.generated.stored ? "STORED" : "VIRTUAL"
+    parts.push(`GENERATED ALWAYS AS (${colDef.generated.expression}) ${storageType}`)
+  }
+  return parts.join(" ")
+}

package/src/lib/table/buildTableConstraint.ts

@@ -0,0 +1,67 @@
+import type { TableConstraints } from "../../types"
+
+/**
+ * Build table-level constraints
+ */
+export function buildTableConstraints<T>(constraints: TableConstraints<T>): string[] {
+  const parts: string[] = []
+
+  // PRIMARY KEY constraint
+  if (constraints.primaryKey && constraints.primaryKey.length > 0) {
+    const columns = constraints.primaryKey
+      .map((col) => `"${String(col).replace(/"/g, '""')}"`)
+      .join(", ")
+    parts.push(`PRIMARY KEY (${columns})`)
+  }
+
+  // UNIQUE constraints
+  if (constraints.unique) {
+    if (Array.isArray(constraints.unique[0])) {
+      // Multiple composite unique constraints
+      for (const uniqueGroup of constraints.unique as string[][]) {
+        const columns = uniqueGroup.map((col) => `"${col.replace(/"/g, '""')}"`).join(", ")
+        parts.push(`UNIQUE (${columns})`)
+      }
+    } else {
+      // Single unique constraint
+      const columns = (constraints.unique as string[])
+        .map((col) => `"${col.replace(/"/g, '""')}"`)
+        .join(", ")
+      parts.push(`UNIQUE (${columns})`)
+    }
+  }
+
+  // CHECK constraints
+  if (constraints.check) {
+    for (const checkExpr of constraints.check) {
+      parts.push(`CHECK (${checkExpr})`)
+    }
+  }
+
+  // FOREIGN KEY constraints
+  if (constraints.foreignKeys) {
+    for (const fk of constraints.foreignKeys) {
+      const columns = fk.columns.map((col) => `"${String(col).replace(/"/g, '""')}"`).join(", ")
+      const refColumns = fk.references.columns
+        .map((col) => `"${col.replace(/"/g, '""')}"`)
+        .join(", ")
+
+      let fkClause = `FOREIGN KEY (${columns}) REFERENCES "${fk.references.table.replace(
+        /"/g,
+        '""'
+      )}" (${refColumns})`
+
+      if (fk.references.onDelete) {
+        fkClause += ` ON DELETE ${fk.references.onDelete}`
+      }
+
+      if (fk.references.onUpdate) {
+        fkClause += ` ON UPDATE ${fk.references.onUpdate}`
+      }
+
+      parts.push(fkClause)
+    }
+  }
+
+  return parts
+}

package/src/lib/table/getTableComment.ts

@@ -0,0 +1,16 @@
+import type { Database } from "bun:sqlite"
+
+/**
+ * Get table comment from metadata
+ */
+export function getTableComment(db: Database, tableName: string): string | null {
+  try {
+    const stmt = db.prepare(`
+      SELECT comment FROM __table_metadata__ WHERE table_name = ?
+    `)
+    const result = stmt.get(tableName) as { comment: string } | undefined
+    return result?.comment || null
+  } catch (_error) {
+    return null
+  }
+}

package/src/lib/table/isTableSchema.ts

@@ -0,0 +1,50 @@
+import type { TableSchema } from "../../types"
+
+/**
+ * Type guard to determine if the provided columns object
+ * is a TableSchema (typed ColumnDefinition objects).
+ */
+export function isTableSchema(columns: unknown): columns is TableSchema {
+  if (typeof columns !== "object" || columns === null) {
+    return false
+  }
+
+  // Check if any value has a 'type' property with a valid SQLite type
+  for (const [_key, value] of Object.entries(columns as Record<string, unknown>)) {
+    if (typeof value === "object" && value !== null && "type" in value) {
+      const type = (value as { type: string }).type
+      const validTypes = [
+        "INTEGER",
+        "TEXT",
+        "REAL",
+        "BLOB",
+        "NUMERIC",
+        "INT",
+        "TINYINT",
+        "SMALLINT",
+        "MEDIUMINT",
+        "BIGINT",
+        "VARCHAR",
+        "CHAR",
+        "CHARACTER",
+        "NCHAR",
+        "NVARCHAR",
+        "CLOB",
+        "DOUBLE",
+        "FLOAT",
+        "DECIMAL",
+        "DATE",
+        "DATETIME",
+        "TIMESTAMP",
+        "TIME",
+        "BOOLEAN",
+        "JSON",
+      ]
+      if (validTypes.includes(type)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}

package/src/lib/table/setTableComment.ts

@@ -0,0 +1,30 @@
+import type { Database } from "bun:sqlite"
+import type { SqliteLogger } from "../../utils"
+
+/**
+ * Store table comment as metadata (using a system table if needed)
+ */
+export function setTableComment(
+  db: Database,
+  tableLog: SqliteLogger,
+  tableName: string,
+  comment: string
+): void {
+  try {
+    db.run(`
+      CREATE TABLE IF NOT EXISTS __table_metadata__ (
+        table_name TEXT PRIMARY KEY,
+        comment TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `)
+
+    const stmt = db.prepare(`
+      INSERT OR REPLACE INTO __table_metadata__ (table_name, comment, created_at)
+      VALUES (?, ?, CURRENT_TIMESTAMP)
+    `)
+    stmt.run(tableName, comment)
+  } catch (error) {
+    tableLog.warn(`Could not store table comment for ${tableName}: ${error}`)
+  }
+}