@mark1russell7/docker-sqlite 0.0.0-stage → 0.1.0

package/src/migrate.ts

@@ -0,0 +1,159 @@
+/**
+ * Migration utilities for SQLite
+ */
+
+import type { Database } from "sql.js";
+import type { Migration, MigrationStatus } from "./types.js";
+import { query, execute, execMultiple } from "./query.js";
+
+/**
+ * Schema for tracking migrations
+ */
+const MIGRATIONS_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS _migrations (
+    version INTEGER PRIMARY KEY,
+    description TEXT NOT NULL,
+    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+  )
+`;
+
+/**
+ * Ensure the migrations table exists
+ */
+function ensureMigrationsTable(db: Database): void {
+  execMultiple(db, MIGRATIONS_TABLE_SQL);
+}
+
+/**
+ * Get the current migration status
+ */
+export function getMigrationStatus(
+  db: Database,
+  migrations: Migration[]
+): MigrationStatus {
+  ensureMigrationsTable(db);
+
+  const applied = query<{ version: number }>(
+    db,
+    "SELECT version FROM _migrations ORDER BY version"
+  );
+
+  const appliedVersions = new Set(applied.rows.map((r) => r.version));
+  const appliedMigrations = [...appliedVersions].sort((a, b) => a - b);
+  const currentVersion =
+    appliedMigrations.length > 0
+      ? appliedMigrations[appliedMigrations.length - 1]!
+      : 0;
+
+  const pendingMigrations = migrations
+    .filter((m) => !appliedVersions.has(m.version))
+    .sort((a, b) => a.version - b.version);
+
+  return {
+    currentVersion,
+    appliedMigrations,
+    pendingMigrations,
+  };
+}
+
+/**
+ * Run all pending migrations
+ *
+ * @example
+ * ```typescript
+ * const migrations: Migration[] = [
+ *   {
+ *     version: 1,
+ *     description: 'Create users table',
+ *     up: 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)',
+ *     down: 'DROP TABLE users'
+ *   },
+ *   {
+ *     version: 2,
+ *     description: 'Add email column',
+ *     up: 'ALTER TABLE users ADD COLUMN email TEXT',
+ *   }
+ * ];
+ *
+ * const applied = runMigrations(db, migrations);
+ * console.log(`Applied ${applied.length} migrations`);
+ * ```
+ */
+export function runMigrations(db: Database, migrations: Migration[]): Migration[] {
+  const status = getMigrationStatus(db, migrations);
+  const applied: Migration[] = [];
+
+  for (const migration of status.pendingMigrations) {
+    try {
+      // Run the migration
+      execMultiple(db, migration.up);
+
+      // Record it as applied
+      execute(
+        db,
+        "INSERT INTO _migrations (version, description) VALUES (?, ?)",
+        [migration.version, migration.description]
+      );
+
+      applied.push(migration);
+    } catch (error) {
+      throw new Error(
+        `Failed to apply migration ${migration.version} (${migration.description}): ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  return applied;
+}
+
+/**
+ * Rollback the last applied migration
+ */
+export function rollbackMigration(
+  db: Database,
+  migrations: Migration[]
+): Migration | null {
+  const status = getMigrationStatus(db, migrations);
+
+  if (status.currentVersion === 0) {
+    return null;
+  }
+
+  const migration = migrations.find((m) => m.version === status.currentVersion);
+
+  if (!migration) {
+    throw new Error(`Migration ${status.currentVersion} not found in migrations list`);
+  }
+
+  if (!migration.down) {
+    throw new Error(
+      `Migration ${migration.version} (${migration.description}) has no down migration`
+    );
+  }
+
+  try {
+    execMultiple(db, migration.down);
+    execute(db, "DELETE FROM _migrations WHERE version = ?", [migration.version]);
+    return migration;
+  } catch (error) {
+    throw new Error(
+      `Failed to rollback migration ${migration.version}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Create a migration from SQL strings
+ */
+export function createMigration(
+  version: number,
+  description: string,
+  up: string,
+  down?: string
+): Migration {
+  const migration: Migration = { version, description, up };
+  if (down !== undefined) {
+    migration.down = down;
+  }
+  return migration;
+}

package/src/query.ts

@@ -0,0 +1,147 @@
+/**
+ * Query helper utilities for SQLite
+ */
+
+import type { Database } from "sql.js";
+import type { QueryResult, ExecuteResult } from "./types.js";
+
+/**
+ * Execute a SELECT query and return results
+ *
+ * @example
+ * ```typescript
+ * const result = query(db, 'SELECT * FROM users WHERE age > ?', [21]);
+ * console.log(result.columns); // ['id', 'name', 'age']
+ * console.log(result.rows);    // [{ id: 1, name: 'Alice', age: 25 }, ...]
+ * ```
+ */
+export function query<T = Record<string, unknown>>(
+  db: Database,
+  sql: string,
+  params: unknown[] = []
+): QueryResult<T> {
+  const stmt = db.prepare(sql);
+
+  try {
+    stmt.bind(params as (string | number | Uint8Array | null)[]);
+
+    const rows: T[] = [];
+    let columns: string[] = [];
+
+    while (stmt.step()) {
+      if (columns.length === 0) {
+        columns = stmt.getColumnNames();
+      }
+      rows.push(stmt.getAsObject() as T);
+    }
+
+    return { columns, rows };
+  } finally {
+    stmt.free();
+  }
+}
+
+/**
+ * Execute an INSERT, UPDATE, DELETE, or other statement
+ *
+ * @example
+ * ```typescript
+ * const result = execute(db, 'INSERT INTO users (name, age) VALUES (?, ?)', ['Bob', 30]);
+ * console.log(result.changes); // 1
+ * ```
+ */
+export function execute(
+  db: Database,
+  sql: string,
+  params: unknown[] = []
+): ExecuteResult {
+  // With parameters, sql.js runs only the first statement. Before, the other statements were
+  // ignored and the call reported success. Now several statements run with no parameters, and
+  // are an error with parameters.
+  if (hasSeveralStatements(db, sql)) {
+    if (params.length > 0) {
+      throw new Error(
+        "execute() binds parameters to one statement, and the SQL has several. Send one statement per call."
+      );
+    }
+    const before = totalChanges(db);
+    db.exec(sql);
+    return { changes: totalChanges(db) - before };
+  }
+  db.run(sql, params as (string | number | Uint8Array | null)[]);
+  const changes = db.getRowsModified();
+  return { changes };
+}
+
+/** The number of rows that the statements of this connection changed. */
+function totalChanges(db: Database): number {
+  const result = db.exec("SELECT total_changes()");
+  return Number(result[0]?.values[0]?.[0] ?? 0);
+}
+
+/** True when the text holds SQL other than spaces, ";" and comments. */
+function holdsStatement(sql: string): boolean {
+  return sql
+    .replace(/--[^\n]*/g, "")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/[\s;]/g, "")
+    .length > 0;
+}
+
+/**
+ * True when `sql` holds more than one statement. Nothing runs: the function only prepares the
+ * first statement and examines the SQL after it.
+ */
+export function hasSeveralStatements(db: Database, sql: string): boolean {
+  const iterator = db.iterateStatements(sql);
+  const first = iterator.next();
+  if (first.done) {
+    return false;
+  }
+  const rest = iterator.getRemainingSQL();
+  // Read the iterator to its end: this frees the statement and the copy of the SQL. A later
+  // statement can fail to prepare (its table does not exist yet), and that also ends it.
+  try {
+    while (!iterator.next().done) {
+      // Prepare only
+    }
+  } catch {
+    // The iterator ended
+  }
+  return holdsStatement(rest);
+}
+
+/**
+ * Execute multiple statements (for schema setup, etc.)
+ *
+ * @example
+ * ```typescript
+ * execMultiple(db, `
+ *   CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT);
+ *   CREATE TABLE IF NOT EXISTS posts (id INTEGER PRIMARY KEY, user_id INTEGER);
+ * `);
+ * ```
+ */
+export function execMultiple(db: Database, sql: string): void {
+  db.exec(sql);
+}
+
+/**
+ * Get the last inserted row ID
+ */
+export function lastInsertRowId(db: Database): number {
+  const result = query<{ id: number }>(db, "SELECT last_insert_rowid() as id");
+  return result.rows[0]?.id ?? 0;
+}
+
+/**
+ * Check if a table exists
+ */
+export function tableExists(db: Database, tableName: string): boolean {
+  const result = query<{ name: string }>(
+    db,
+    "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+    [tableName]
+  );
+  return result.rows.length > 0;
+}

package/src/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Type definitions for docker-sqlite
+ */
+
+import type { Database } from "sql.js";
+
+/**
+ * Configuration for SQLite connection
+ */
+export interface ConnectionConfig {
+  /** Path to the SQLite database file. Use ":memory:" for in-memory database */
+  dbPath: string;
+}
+
+/**
+ * Callback function for withConnection
+ */
+export type ConnectionCallback<T> = (db: Database) => T | Promise<T>;
+
+/**
+ * Result of a query operation
+ */
+export interface QueryResult<T = Record<string, unknown>> {
+  /** Column names */
+  columns: string[];
+  /** Row values */
+  rows: T[];
+}
+
+/**
+ * Result of an execute operation (INSERT, UPDATE, DELETE)
+ */
+export interface ExecuteResult {
+  /** Number of rows affected */
+  changes: number;
+}
+
+/**
+ * Migration definition
+ */
+export interface Migration {
+  /** Migration version (must be unique and sequential) */
+  version: number;
+  /** Description of the migration */
+  description: string;
+  /** SQL to apply the migration */
+  up: string;
+  /** SQL to revert the migration (optional) */
+  down?: string;
+}
+
+/**
+ * Migration status
+ */
+export interface MigrationStatus {
+  /** Current version (0 if no migrations applied) */
+  currentVersion: number;
+  /** List of applied migrations */
+  appliedMigrations: number[];
+  /** List of pending migrations */
+  pendingMigrations: Migration[];
+}