@delali/sirannon-db 0.1.3 → 0.1.5

package/dist/database-BVY1GqE7.d.ts

@@ -0,0 +1,95 @@
+import { S as SQLiteDriver } from './types-BFSsG77t.js';
+import { Q as QueryHookContext, f as ConnectionHookContext, g as BeforeSubscribeHook, H as HookConfig, M as MetricsConfig, h as QueryMetrics, i as ConnectionMetrics, j as CDCMetrics, D as DatabaseOptions, P as Params, k as QueryOptions, E as ExecuteResult, T as Transaction, l as SubscriptionBuilder, m as BackupScheduleOptions, B as BeforeQueryHook, A as AfterQueryHook } from './types-D-74JiXb.js';
+import { M as Migration, a as MigrationResult, R as RollbackResult } from './types-BeozgNPr.js';
+
+type HookEvent = 'beforeQuery' | 'afterQuery' | 'beforeConnect' | 'databaseOpen' | 'databaseClose' | 'beforeSubscribe';
+type SubscribeHookContext = Parameters<BeforeSubscribeHook>[0];
+interface HookEventContextMap {
+    beforeQuery: QueryHookContext;
+    afterQuery: QueryHookContext & {
+        durationMs: number;
+    };
+    beforeConnect: ConnectionHookContext;
+    databaseOpen: ConnectionHookContext;
+    databaseClose: ConnectionHookContext;
+    beforeSubscribe: SubscribeHookContext;
+}
+type HookHandler<E extends HookEvent> = (ctx: HookEventContextMap[E]) => void | Promise<void>;
+type HookDispose = () => void;
+
+declare class HookRegistry {
+    private hooks;
+    constructor(config?: HookConfig);
+    register<E extends HookEvent>(event: E, hook: HookHandler<E>): HookDispose;
+    invoke<E extends HookEvent>(event: E, ctx: HookEventContextMap[E]): Promise<void>;
+    invokeSync<E extends HookEvent>(event: E, ctx: HookEventContextMap[E]): void;
+    has(event: HookEvent): boolean;
+    count(event: HookEvent): number;
+    clear(event?: HookEvent): void;
+    private addHook;
+    private loadConfig;
+}
+
+declare class MetricsCollector {
+    private config;
+    constructor(config?: MetricsConfig);
+    trackQuery<T>(fn: () => Promise<T>, context: Omit<QueryMetrics, 'durationMs' | 'error'>): Promise<T>;
+    trackConnection(metrics: ConnectionMetrics): void;
+    trackCDCEvent(metrics: CDCMetrics): void;
+    get active(): boolean;
+}
+
+interface DatabaseInternals {
+    parentHooks?: HookRegistry;
+    metrics?: MetricsCollector;
+}
+declare class Database {
+    readonly id: string;
+    readonly path: string;
+    readonly readOnly: boolean;
+    private readonly pool;
+    private readonly driver;
+    private readonly closeListeners;
+    private _closed;
+    private changeTracker;
+    private subscriptionManager;
+    private stopCdcPolling;
+    private readonly cdcPollInterval;
+    private readonly cdcRetention;
+    private readonly hookRegistry;
+    private readonly parentHooks;
+    private readonly metricsCollector;
+    private readonly backupManager;
+    private readonly backupScheduler;
+    private readonly scheduledBackupCancellers;
+    private constructor();
+    static create(id: string, path: string, driver: SQLiteDriver, options?: DatabaseOptions, internals?: DatabaseInternals): Promise<Database>;
+    query<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T[]>;
+    queryOne<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T | undefined>;
+    execute(sql: string, params?: Params, options?: QueryOptions): Promise<ExecuteResult>;
+    executeBatch(sql: string, paramsBatch: Params[], options?: QueryOptions): Promise<ExecuteResult[]>;
+    transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    private maybeApplyDdlSideEffects;
+    watch(table: string): Promise<void>;
+    unwatch(table: string): Promise<void>;
+    on(table: string): SubscriptionBuilder;
+    migrate(migrations: Migration[]): Promise<MigrationResult>;
+    rollback(migrations: Migration[], version?: number): Promise<RollbackResult>;
+    backup(destPath: string): Promise<void>;
+    scheduleBackup(options: BackupScheduleOptions): void;
+    loadExtension(extensionPath: string): Promise<void>;
+    onBeforeQuery(hook: BeforeQueryHook): void;
+    onAfterQuery(hook: AfterQueryHook): void;
+    addCloseListener(fn: () => void | Promise<void>): void;
+    close(): Promise<void>;
+    get closed(): boolean;
+    get readerCount(): number;
+    private ensureOpen;
+    private ensureCdc;
+    private ensureCdcPolling;
+    private stopCdcPollingLoop;
+    private fireBeforeQueryHooks;
+    private fireAfterQueryHooks;
+}
+
+export { Database as D, type HookDispose as H, MetricsCollector as M, type SubscribeHookContext as S, type HookEvent as a, type HookEventContextMap as b, type HookHandler as c, HookRegistry as d };

package/dist/driver/better-sqlite3.d.ts

@@ -0,0 +1,8 @@
+import { S as SQLiteDriver } from '../types-BFSsG77t.js';
+
+interface BetterSqlite3Options {
+    busyTimeout?: number;
+}
+declare function betterSqlite3(driverOptions?: BetterSqlite3Options): SQLiteDriver;
+
+export { type BetterSqlite3Options, betterSqlite3 };

package/dist/driver/better-sqlite3.mjs

@@ -0,0 +1,63 @@
+import { defineDriver } from '../chunk-74UN4DIE.mjs';
+import '../chunk-O7BHI3CF.mjs';
+
+// src/drivers/better-sqlite3/index.ts
+function createConnection(db) {
+  const conn = {
+    async exec(sql) {
+      db.exec(sql);
+    },
+    async prepare(sql) {
+      const stmt = db.prepare(sql);
+      return {
+        async all(...params) {
+          return stmt.all(...params);
+        },
+        async get(...params) {
+          return stmt.get(...params);
+        },
+        async run(...params) {
+          const result = stmt.run(...params);
+          return {
+            changes: result.changes,
+            lastInsertRowId: result.lastInsertRowid
+          };
+        }
+      };
+    },
+    async transaction(fn) {
+      await conn.exec("BEGIN");
+      try {
+        const result = await fn(conn);
+        await conn.exec("COMMIT");
+        return result;
+      } catch (err) {
+        try {
+          await conn.exec("ROLLBACK");
+        } catch {
+        }
+        throw err;
+      }
+    },
+    async close() {
+      db.close();
+    }
+  };
+  return conn;
+}
+function betterSqlite3(driverOptions) {
+  return defineDriver({
+    capabilities: { multipleConnections: true, extensions: true },
+    async open(path, options) {
+      const Database = (await import('better-sqlite3')).default;
+      const db = new Database(path, { readonly: options?.readonly ?? false });
+      if (options?.walMode !== false) db.pragma("journal_mode = WAL");
+      db.pragma("synchronous = NORMAL");
+      db.pragma("foreign_keys = ON");
+      db.pragma(`busy_timeout = ${driverOptions?.busyTimeout ?? 5e3}`);
+      return createConnection(db);
+    }
+  });
+}
+
+export { betterSqlite3 };

package/dist/driver/bun.mjs

@@ -0,0 +1,61 @@
+import { defineDriver } from '../chunk-FB2U2Q3Y.mjs';
+
+// src/drivers/bun/index.ts
+function bunSqlite(driverOptions) {
+  return defineDriver({
+    capabilities: { multipleConnections: true, extensions: true },
+    async open(path, options) {
+      const { Database } = await import('bun:sqlite');
+      const db = new Database(path, { readonly: options?.readonly ?? false });
+      if (options?.walMode !== false) db.run("PRAGMA journal_mode = WAL");
+      db.run("PRAGMA synchronous = NORMAL");
+      db.run("PRAGMA foreign_keys = ON");
+      db.run(`PRAGMA busy_timeout = ${driverOptions?.busyTimeout ?? 5e3}`);
+      const conn = {
+        async exec(sql) {
+          db.run(sql);
+        },
+        async prepare(sql) {
+          const stmt = db.query(sql);
+          return {
+            async all(...params) {
+              return stmt.all(...params);
+            },
+            async get(...params) {
+              return stmt.get(...params) ?? void 0;
+            },
+            async run(...params) {
+              stmt.run(...params);
+              const changesStmt = db.query("SELECT changes() AS changes, last_insert_rowid() AS lastId");
+              const info = changesStmt.get();
+              return {
+                changes: info.changes,
+                lastInsertRowId: info.lastId
+              };
+            }
+          };
+        },
+        async transaction(fn) {
+          await conn.exec("BEGIN");
+          try {
+            const result = await fn(conn);
+            await conn.exec("COMMIT");
+            return result;
+          } catch (err) {
+            try {
+              await conn.exec("ROLLBACK");
+            } catch {
+            }
+            throw err;
+          }
+        },
+        async close() {
+          db.close();
+        }
+      };
+      return conn;
+    }
+  });
+}
+
+export { bunSqlite };

package/dist/driver/expo.mjs

@@ -0,0 +1,55 @@
+import { defineDriver } from '../chunk-FB2U2Q3Y.mjs';
+
+// src/drivers/expo/index.ts
+function expoSqlite() {
+  return defineDriver({
+    capabilities: { multipleConnections: false, extensions: false },
+    async open(path, options) {
+      const SQLite = await import('expo-sqlite');
+      const db = await SQLite.openDatabaseAsync(path, {
+        readOnly: options?.readonly
+      });
+      if (options?.walMode !== false) await db.execAsync("PRAGMA journal_mode = WAL");
+      await db.execAsync("PRAGMA synchronous = NORMAL");
+      await db.execAsync("PRAGMA foreign_keys = ON");
+      const buildConnectionFromHandle = (dbHandle) => ({
+        async exec(sql) {
+          await dbHandle.execAsync(sql);
+        },
+        async prepare(sql) {
+          return {
+            async all(...params) {
+              return dbHandle.getAllAsync(sql, params);
+            },
+            async get(...params) {
+              const row = await dbHandle.getFirstAsync(sql, params);
+              return row ?? void 0;
+            },
+            async run(...params) {
+              const result = await dbHandle.runAsync(sql, params);
+              return {
+                changes: result.changes,
+                lastInsertRowId: result.lastInsertRowId
+              };
+            }
+          };
+        },
+        async transaction(fn) {
+          let result;
+          await dbHandle.withExclusiveTransactionAsync(async (txDb) => {
+            const txConn = buildConnectionFromHandle(txDb);
+            result = await fn(txConn);
+          });
+          return result;
+        },
+        async close() {
+          await dbHandle.closeAsync();
+        }
+      });
+      const conn = buildConnectionFromHandle(db);
+      return conn;
+    }
+  });
+}
+
+export { expoSqlite };

package/dist/driver/node.d.ts

@@ -0,0 +1,8 @@
+import { S as SQLiteDriver } from '../types-BFSsG77t.js';
+
+interface NodeSqliteOptions {
+    busyTimeout?: number;
+}
+declare function nodeSqlite(driverOptions?: NodeSqliteOptions): SQLiteDriver;
+
+export { type NodeSqliteOptions, nodeSqlite };

package/dist/driver/node.mjs

@@ -0,0 +1,60 @@
+import { defineDriver } from '../chunk-74UN4DIE.mjs';
+import '../chunk-O7BHI3CF.mjs';
+
+// src/drivers/node/index.ts
+function nodeSqlite(driverOptions) {
+  return defineDriver({
+    capabilities: { multipleConnections: true, extensions: true },
+    async open(path, options) {
+      const { DatabaseSync } = await import('node:sqlite');
+      const db = new DatabaseSync(path, { readOnly: options?.readonly ?? false });
+      if (options?.walMode !== false) db.exec("PRAGMA journal_mode = WAL");
+      db.exec("PRAGMA synchronous = NORMAL");
+      db.exec("PRAGMA foreign_keys = ON");
+      db.exec(`PRAGMA busy_timeout = ${driverOptions?.busyTimeout ?? 5e3}`);
+      const conn = {
+        async exec(sql) {
+          db.exec(sql);
+        },
+        async prepare(sql) {
+          const stmt = db.prepare(sql);
+          return {
+            async all(...params) {
+              return stmt.all(...params);
+            },
+            async get(...params) {
+              return stmt.get(...params);
+            },
+            async run(...params) {
+              const result = stmt.run(...params);
+              return {
+                changes: Number(result.changes),
+                lastInsertRowId: result.lastInsertRowid
+              };
+            }
+          };
+        },
+        async transaction(fn) {
+          await conn.exec("BEGIN");
+          try {
+            const result = await fn(conn);
+            await conn.exec("COMMIT");
+            return result;
+          } catch (err) {
+            try {
+              await conn.exec("ROLLBACK");
+            } catch {
+            }
+            throw err;
+          }
+        },
+        async close() {
+          db.close();
+        }
+      };
+      return conn;
+    }
+  });
+}
+
+export { nodeSqlite };

package/dist/driver/wa-sqlite.d.ts

@@ -0,0 +1,34 @@
+interface RunResult {
+    changes: number;
+    lastInsertRowId: number | bigint;
+}
+interface SQLiteStatement {
+    all<T = unknown>(...params: unknown[]): Promise<T[]>;
+    get<T = unknown>(...params: unknown[]): Promise<T | undefined>;
+    run(...params: unknown[]): Promise<RunResult>;
+}
+interface SQLiteConnection {
+    exec(sql: string): Promise<void>;
+    prepare(sql: string): Promise<SQLiteStatement>;
+    transaction<T>(fn: (conn: SQLiteConnection) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+interface OpenOptions {
+    readonly?: boolean;
+    walMode?: boolean;
+}
+interface DriverCapabilities {
+    multipleConnections: boolean;
+    extensions: boolean;
+}
+interface SQLiteDriver {
+    readonly capabilities: DriverCapabilities;
+    open(path: string, options?: OpenOptions): Promise<SQLiteConnection>;
+}
+
+interface WaSqliteOptions {
+    vfs?: 'IDBBatchAtomicVFS' | 'AccessHandlePoolVFS';
+}
+declare function waSqlite(driverOptions?: WaSqliteOptions): SQLiteDriver;
+
+export { type WaSqliteOptions, waSqlite };

package/dist/driver/wa-sqlite.mjs

@@ -0,0 +1,141 @@
+// src/core/errors.ts
+var SirannonError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "SirannonError";
+  }
+};
+
+// src/core/driver/define.ts
+function defineDriver(config) {
+  if (!config.capabilities || typeof config.open !== "function") {
+    throw new SirannonError("Driver must define capabilities and open()", "INVALID_DRIVER");
+  }
+  return Object.freeze({
+    capabilities: Object.freeze({ ...config.capabilities }),
+    open: config.open
+  });
+}
+
+// src/drivers/wa-sqlite/index.ts
+function waSqlite(driverOptions) {
+  return defineDriver({
+    capabilities: { multipleConnections: false, extensions: false },
+    async open(path, options) {
+      const { default: SQLiteESMFactory } = await import('wa-sqlite/dist/wa-sqlite-async.mjs');
+      const { Factory } = await import('wa-sqlite');
+      const module = await SQLiteESMFactory();
+      const sqlite3 = Factory(module);
+      const vfsName = driverOptions?.vfs ?? "IDBBatchAtomicVFS";
+      if (vfsName === "AccessHandlePoolVFS") {
+        const { AccessHandlePoolVFS } = await import('../vfs-INWQ5DTE.mjs');
+        const vfs = new AccessHandlePoolVFS(path);
+        await vfs.isReady;
+        sqlite3.vfs_register(vfs, true);
+      } else {
+        const { IDBBatchAtomicVFS } = await import('../vfs-INWQ5DTE.mjs');
+        const vfs = new IDBBatchAtomicVFS(path);
+        await vfs.isReady;
+        sqlite3.vfs_register(vfs, true);
+      }
+      const db = await sqlite3.open_v2(path);
+      if (options?.walMode !== false) {
+        try {
+          await sqlite3.exec(db, "PRAGMA journal_mode = WAL");
+        } catch {
+        }
+      }
+      await sqlite3.exec(db, "PRAGMA synchronous = NORMAL");
+      await sqlite3.exec(db, "PRAGMA foreign_keys = ON");
+      async function execStatements(sql, params) {
+        const columns = [];
+        const rows = [];
+        let changes = 0;
+        let lastRowId = 0;
+        for await (const stmt of sqlite3.statements(db, sql)) {
+          if (params && params.length > 0) {
+            for (let i = 0; i < params.length; i++) {
+              sqlite3.bind(stmt, i + 1, params[i]);
+            }
+          }
+          const cols = sqlite3.column_names(stmt);
+          if (cols.length > 0 && columns.length === 0) {
+            columns.push(...cols);
+          }
+          while (await sqlite3.step(stmt) === 100) {
+            const row = [];
+            for (let i = 0; i < cols.length; i++) {
+              row.push(sqlite3.column(stmt, i));
+            }
+            rows.push(row);
+          }
+        }
+        changes = sqlite3.changes(db);
+        let rowIdCaptured = false;
+        await sqlite3.exec(db, "SELECT last_insert_rowid()", (row) => {
+          if (!rowIdCaptured && row[0] !== void 0) {
+            lastRowId = row[0];
+            rowIdCaptured = true;
+          }
+        });
+        return { columns, rows, changes, lastRowId };
+      }
+      const conn = {
+        async exec(sql) {
+          await sqlite3.exec(db, sql);
+        },
+        async prepare(sql) {
+          return {
+            async all(...params) {
+              const result = await execStatements(sql, params);
+              return result.rows.map((row) => {
+                const obj = {};
+                for (let i = 0; i < result.columns.length; i++) {
+                  obj[result.columns[i]] = row[i];
+                }
+                return obj;
+              });
+            },
+            async get(...params) {
+              const result = await execStatements(sql, params);
+              if (result.rows.length === 0) return void 0;
+              const obj = {};
+              for (let i = 0; i < result.columns.length; i++) {
+                obj[result.columns[i]] = result.rows[0][i];
+              }
+              return obj;
+            },
+            async run(...params) {
+              const result = await execStatements(sql, params);
+              return {
+                changes: result.changes,
+                lastInsertRowId: result.lastRowId
+              };
+            }
+          };
+        },
+        async transaction(fn) {
+          await conn.exec("BEGIN");
+          try {
+            const result = await fn(conn);
+            await conn.exec("COMMIT");
+            return result;
+          } catch (err) {
+            try {
+              await conn.exec("ROLLBACK");
+            } catch {
+            }
+            throw err;
+          }
+        },
+        async close() {
+          sqlite3.close(db);
+        }
+      };
+      return conn;
+    }
+  });
+}
+
+export { waSqlite };

package/dist/errors-C00ed08Q.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Base class for all sirannon-db errors. Extend this class to create
+ * domain-specific errors that carry a machine-readable {@link code}.
+ */
+declare class SirannonError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Thrown when a database ID cannot be resolved in the registry.
+ * This typically means the database was never opened or has already been closed.
+ */
+declare class DatabaseNotFoundError extends SirannonError {
+    constructor(id: string);
+}
+/**
+ * Thrown when attempting to register a database with an ID that is already
+ * in use. Each database ID must be unique within the registry.
+ */
+declare class DatabaseAlreadyExistsError extends SirannonError {
+    constructor(id: string);
+}
+/**
+ * Thrown when a write operation is attempted on a database that was opened
+ * in read-only mode.
+ */
+declare class ReadOnlyError extends SirannonError {
+    constructor(id: string);
+}
+/**
+ * Thrown when SQLite fails to execute a statement. The {@link sql} property
+ * holds the original SQL string that caused the failure, which is useful for
+ * debugging and logging.
+ */
+declare class QueryError extends SirannonError {
+    readonly sql: string;
+    constructor(message: string, sql: string);
+}
+/**
+ * Thrown when a transaction cannot be committed or is forcibly rolled back.
+ * Check the message for the underlying cause.
+ */
+declare class TransactionError extends SirannonError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a migration step fails. The {@link version} property identifies
+ * which schema version triggered the error so the failure can be pinpointed
+ * in the migration history.
+ */
+declare class MigrationError extends SirannonError {
+    readonly version: number;
+    constructor(message: string, version: number, code?: string);
+}
+/**
+ * Thrown when a before-hook explicitly rejects an operation. The optional
+ * `reason` string is surfaced in the message so callers can distinguish
+ * between different hook policies.
+ */
+declare class HookDeniedError extends SirannonError {
+    constructor(hookName: string, reason?: string);
+}
+/**
+ * Thrown when the change-data-capture pipeline encounters an unrecoverable
+ * error, such as a failed event dispatch or a corrupt change record.
+ */
+declare class CDCError extends SirannonError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a backup operation fails, whether that is an online backup via
+ * the SQLite backup API or a file-level copy.
+ */
+declare class BackupError extends SirannonError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the connection pool reaches its limit or is configured with
+ * invalid parameters such as a minimum size greater than the maximum.
+ */
+declare class ConnectionPoolError extends SirannonError {
+    constructor(message: string);
+}
+/**
+ * Thrown when opening a new database would exceed the configured cap on
+ * concurrently open databases. Close an existing database before opening
+ * another one.
+ */
+declare class MaxDatabasesError extends SirannonError {
+    constructor(max: number);
+}
+/**
+ * Thrown when a native SQLite extension cannot be loaded. The `path` argument
+ * is the filesystem path passed to `load_extension`, and the optional `cause`
+ * string carries the error detail reported by SQLite.
+ */
+declare class ExtensionError extends SirannonError {
+    constructor(path: string, cause?: string);
+}
+
+export { BackupError as B, CDCError as C, DatabaseAlreadyExistsError as D, ExtensionError as E, HookDeniedError as H, MaxDatabasesError as M, QueryError as Q, ReadOnlyError as R, SirannonError as S, TransactionError as T, ConnectionPoolError as a, DatabaseNotFoundError as b, MigrationError as c };

package/dist/file-migrations/index.d.ts

@@ -0,0 +1,16 @@
+import { M as Migration } from '../types-BeozgNPr.js';
+import '../types-D-74JiXb.js';
+import '../types-BFSsG77t.js';
+
+interface ScannedMigration {
+    version: number;
+    name: string;
+    upPath: string;
+    downPath: string | null;
+}
+declare function scanDirectory(dirPath: string): ScannedMigration[];
+declare function readUpMigrations(scanned: ScannedMigration[]): Migration[];
+declare function readDownMigrations(scanned: ScannedMigration[], versions: number[]): Migration[];
+declare function loadMigrations(dirPath: string): Migration[];
+
+export { type ScannedMigration, loadMigrations, readDownMigrations, readUpMigrations, scanDirectory };