@delali/sirannon-db 0.1.3 → 0.1.5

package/dist/backup-scheduler/index.d.ts

@@ -0,0 +1,3 @@
+export { a as BackupScheduler } from '../index-CLdNrcPz.js';
+export { m as BackupScheduleOptions } from '../types-D-74JiXb.js';
+import '../types-BFSsG77t.js';

package/dist/backup-scheduler/index.mjs

@@ -0,0 +1,2 @@
+export { BackupScheduler } from '../chunk-PXKAKK2V.mjs';
+import '../chunk-O7BHI3CF.mjs';

package/dist/change-tracker-CFTQ9TSn.d.ts

@@ -0,0 +1,89 @@
+import { a as SQLiteConnection } from './types-BFSsG77t.js';
+import { C as ChangeEvent } from './types-D-74JiXb.js';
+
+interface ChangeTrackerOptions {
+    retention?: number;
+    changesTable?: string;
+    pollBatchSize?: number;
+    replication?: boolean;
+}
+
+declare class ChangeTracker {
+    private readonly watched;
+    private lastSeq;
+    private readonly retentionMs;
+    private readonly changesTable;
+    private readonly pollBatchSize;
+    private readonly replication;
+    private changesTableReady;
+    private watchedTablesCache;
+    private readonly stmtCache;
+    private pruneBoundary;
+    constructor(options?: ChangeTrackerOptions);
+    watch(conn: SQLiteConnection, table: string): Promise<void>;
+    unwatch(conn: SQLiteConnection, table: string): Promise<void>;
+    /**
+     * Rebuilds CDC triggers for every watched table directly on the supplied
+     * connection, without opening a nested transaction.
+     *
+     * Required when a caller has already issued `BEGIN` on `conn` and runs a
+     * DDL statement that changes a watched table's column list: the next DML
+     * inside the same transaction must see triggers compiled against the new
+     * columns, otherwise CDC `new_data` silently omits them. Callers that are
+     * not inside an active transaction may also use this method; CREATE
+     * TRIGGER and DROP TRIGGER statements are committed individually by the
+     * driver in that case.
+     *
+     * Failure semantics:
+     * - If a watched table no longer exists (e.g. it was just dropped by the
+     *   DDL), it is skipped. The watched-map entry is left alone so a separate
+     *   cleanup path can handle it; throwing here would roll back the user's
+     *   transaction over a benign condition.
+     * - If reading column metadata succeeds but the column list is unchanged,
+     *   no triggers are touched.
+     * - If reading column metadata succeeds and the column list differs from
+     *   the cached one, the existing triggers are dropped and reinstalled on
+     *   `conn`. The cached column list is updated on success.
+     * - Any other error (driver failure, identifier validation failure) is
+     *   rethrown so the caller's transaction can roll back deterministically.
+     */
+    refreshAllTriggersUsingConnection(conn: SQLiteConnection): Promise<void>;
+    /**
+     * Removes the supplied tables from the watched map and drops any leftover
+     * CDC triggers carrying their identifier on the supplied connection.
+     *
+     * Intended to be called after a DDL transaction that dropped one or more
+     * watched tables has committed. On rollback the caller must not invoke
+     * this method; the rollback semantics rely on the caller discarding its
+     * captured drop list before reaching this call.
+     *
+     * Idempotent: tables not currently in the watched map are silently
+     * skipped. `dropCdcTriggers` issues `DROP TRIGGER IF EXISTS` so calling
+     * twice in succession produces the same state.
+     *
+     * Defence in depth: even after a `DROP TABLE`, the in-transaction trigger
+     * refresh path may have observed a freshly-created table of the same name
+     * (the DROP and CREATE happened inside the same transaction) and
+     * re-installed triggers compiled against the new schema. Those triggers
+     * are dropped here so the recreated table starts with a clean slate and
+     * the caller must explicitly `watch` it again.
+     */
+    pruneDroppedTables(conn: SQLiteConnection, tables: readonly string[]): Promise<void>;
+    poll(conn: SQLiteConnection): Promise<ChangeEvent[]>;
+    advanceToLatest(conn: SQLiteConnection): Promise<void>;
+    cleanup(conn: SQLiteConnection): Promise<number>;
+    setPruneBoundary(seq: bigint): void;
+    clearPruneBoundary(): void;
+    get watchedTables(): ReadonlySet<string>;
+    private computeSeqBound;
+    private assertIdentifier;
+    private detectChangesTable;
+    private ensureChangesTable;
+    private getColumns;
+    private getPkColumns;
+    private dropTriggers;
+    private getStmt;
+    private installTriggers;
+}
+
+export { ChangeTracker as C, type ChangeTrackerOptions as a };

package/dist/chunk-3MCMONVP.mjs

@@ -0,0 +1,115 @@
+import { QueryError } from './chunk-O7BHI3CF.mjs';
+
+// src/core/query-executor.ts
+var STATEMENT_CACHE_CAPACITY = 128;
+var statementCaches = /* @__PURE__ */ new WeakMap();
+async function getStatement(conn, sql) {
+  let cache = statementCaches.get(conn);
+  if (!cache) {
+    cache = /* @__PURE__ */ new Map();
+    statementCaches.set(conn, cache);
+  }
+  const cached = cache.get(sql);
+  if (cached) {
+    cache.delete(sql);
+    cache.set(sql, cached);
+    return cached;
+  }
+  const pending = conn.prepare(sql);
+  cache.set(sql, pending);
+  if (cache.size > STATEMENT_CACHE_CAPACITY) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== void 0) {
+      cache.delete(oldest);
+    }
+  }
+  try {
+    return await pending;
+  } catch (err) {
+    cache.delete(sql);
+    throw err;
+  }
+}
+function bindParams(params) {
+  if (params === void 0) return [];
+  if (Array.isArray(params)) return params;
+  return [params];
+}
+async function query(conn, sql, params) {
+  try {
+    const stmt = await getStatement(conn, sql);
+    return await stmt.all(...bindParams(params));
+  } catch (err) {
+    throw new QueryError(err instanceof Error ? err.message : String(err), sql);
+  }
+}
+async function queryOne(conn, sql, params) {
+  try {
+    const stmt = await getStatement(conn, sql);
+    return await stmt.get(...bindParams(params));
+  } catch (err) {
+    throw new QueryError(err instanceof Error ? err.message : String(err), sql);
+  }
+}
+async function execute(conn, sql, params) {
+  try {
+    const stmt = await getStatement(conn, sql);
+    const result = await stmt.run(...bindParams(params));
+    return {
+      changes: result.changes,
+      lastInsertRowId: result.lastInsertRowId
+    };
+  } catch (err) {
+    throw new QueryError(err instanceof Error ? err.message : String(err), sql);
+  }
+}
+async function executeBatch(conn, sql, paramsBatch) {
+  try {
+    const stmt = await getStatement(conn, sql);
+    const results = [];
+    for (const params of paramsBatch) {
+      const result = await stmt.run(...bindParams(params));
+      results.push({
+        changes: result.changes,
+        lastInsertRowId: result.lastInsertRowId
+      });
+    }
+    return results;
+  } catch (err) {
+    throw new QueryError(err instanceof Error ? err.message : String(err), sql);
+  }
+}
+
+// src/core/transaction.ts
+var Transaction = class _Transaction {
+  constructor(conn) {
+    this.conn = conn;
+  }
+  _lastInsertRowId = 0;
+  async query(sql, params) {
+    return query(this.conn, sql, params);
+  }
+  async execute(sql, params) {
+    const result = await execute(this.conn, sql, params);
+    this._lastInsertRowId = result.lastInsertRowId;
+    return result;
+  }
+  async executeBatch(sql, paramsBatch) {
+    const results = await executeBatch(this.conn, sql, paramsBatch);
+    if (results.length > 0) {
+      this._lastInsertRowId = results[results.length - 1].lastInsertRowId;
+    }
+    return results;
+  }
+  get lastInsertRowId() {
+    return this._lastInsertRowId;
+  }
+  static async run(conn, fn) {
+    return conn.transaction(async (txConn) => {
+      const tx = new _Transaction(txConn);
+      return fn(tx);
+    });
+  }
+};
+
+export { Transaction, execute, executeBatch, query, queryOne };

package/dist/chunk-74UN4DIE.mjs

@@ -0,0 +1,14 @@
+import { SirannonError } from './chunk-O7BHI3CF.mjs';
+
+// 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
+  });
+}
+
+export { defineDriver };

package/dist/chunk-ER7ODTDA.mjs

@@ -0,0 +1,23 @@
+// src/replication/coordinator/compatibility.ts
+function compatibilityAllowsPromotion(groupCompatibility, sessionCompatibility) {
+  if (!groupCompatibility) return true;
+  return compatibleMajorVersion(groupCompatibility.packageVersion, sessionCompatibility?.packageVersion) && compatibleMajorVersion(groupCompatibility.protocolVersion, sessionCompatibility?.protocolVersion) && compatibleMajorVersion(groupCompatibility.specVersion, sessionCompatibility?.specVersion);
+}
+function compatibleMajorVersion(required, candidate) {
+  if (!required) return true;
+  if (!candidate) return false;
+  const requiredMajor = parseMajorVersion(required);
+  const candidateMajor = parseMajorVersion(candidate);
+  if (requiredMajor === null || candidateMajor === null) {
+    return required === candidate;
+  }
+  return requiredMajor === candidateMajor;
+}
+function parseMajorVersion(version) {
+  const match = /^v?(\d+)/.exec(version);
+  if (!match) return null;
+  const major = match[1];
+  return major === void 0 ? null : Number(major);
+}
+
+export { compatibilityAllowsPromotion };

package/dist/chunk-FB2U2Q3Y.mjs

@@ -0,0 +1,21 @@
+// 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
+  });
+}
+
+export { defineDriver };

package/dist/chunk-GS7T5YMI.mjs

@@ -0,0 +1,51 @@
+// src/core/cdc/encoding.ts
+var BLOB_TAG = "__sirannon_blob";
+var INT_TAG = "__sirannon_int";
+var SAFE_INT_BOUND_TEXT = "9007199254740991";
+var HEX_BYTES_RE = /^[0-9a-fA-F]*$/;
+function decodeTaggedValues(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (isBinaryValue(value)) return value;
+  if (Array.isArray(value)) {
+    return value.map(decodeTaggedValues);
+  }
+  const obj = value;
+  const keys = Object.keys(obj);
+  if (keys.length === 1) {
+    const tag = keys[0];
+    const tagValue = obj[tag];
+    if (tag === BLOB_TAG && typeof tagValue === "string") {
+      return decodeHexBytes(tagValue);
+    }
+    if (tag === INT_TAG && typeof tagValue === "string") {
+      return BigInt(tagValue);
+    }
+  }
+  const out = {};
+  for (const k of keys) {
+    out[k] = decodeTaggedValues(obj[k]);
+  }
+  return out;
+}
+function isBinaryValue(value) {
+  return value instanceof Uint8Array || typeof Buffer !== "undefined" && Buffer.isBuffer(value);
+}
+function decodeHexBytes(hex) {
+  if (hex.length % 2 !== 0 || !HEX_BYTES_RE.test(hex)) {
+    throw new Error("Invalid CDC BLOB hex payload");
+  }
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(hex, "hex");
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    const byte = Number.parseInt(hex.slice(i, i + 2), 16);
+    if (Number.isNaN(byte)) {
+      throw new Error("Invalid CDC BLOB hex payload");
+    }
+    bytes[i / 2] = byte;
+  }
+  return bytes;
+}
+
+export { SAFE_INT_BOUND_TEXT, decodeTaggedValues };

package/dist/chunk-O7BHI3CF.mjs

@@ -0,0 +1,90 @@
+// src/core/errors.ts
+var SirannonError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "SirannonError";
+  }
+};
+var DatabaseNotFoundError = class extends SirannonError {
+  constructor(id) {
+    super(`Database '${id}' not found`, "DATABASE_NOT_FOUND");
+    this.name = "DatabaseNotFoundError";
+  }
+};
+var DatabaseAlreadyExistsError = class extends SirannonError {
+  constructor(id) {
+    super(`Database '${id}' already exists`, "DATABASE_ALREADY_EXISTS");
+    this.name = "DatabaseAlreadyExistsError";
+  }
+};
+var ReadOnlyError = class extends SirannonError {
+  constructor(id) {
+    super(`Database '${id}' is read-only`, "READ_ONLY");
+    this.name = "ReadOnlyError";
+  }
+};
+var QueryError = class extends SirannonError {
+  constructor(message, sql) {
+    super(message, "QUERY_ERROR");
+    this.sql = sql;
+    this.name = "QueryError";
+  }
+};
+var TransactionError = class extends SirannonError {
+  constructor(message) {
+    super(message, "TRANSACTION_ERROR");
+    this.name = "TransactionError";
+  }
+};
+var MigrationError = class extends SirannonError {
+  constructor(message, version, code = "MIGRATION_ERROR") {
+    super(message, code);
+    this.version = version;
+    this.name = "MigrationError";
+  }
+};
+var HookDeniedError = class extends SirannonError {
+  constructor(hookName, reason) {
+    super(
+      reason ? `Hook '${hookName}' denied the operation: ${reason}` : `Hook '${hookName}' denied the operation`,
+      "HOOK_DENIED"
+    );
+    this.name = "HookDeniedError";
+  }
+};
+var CDCError = class extends SirannonError {
+  constructor(message) {
+    super(message, "CDC_ERROR");
+    this.name = "CDCError";
+  }
+};
+var BackupError = class extends SirannonError {
+  constructor(message) {
+    super(message, "BACKUP_ERROR");
+    this.name = "BackupError";
+  }
+};
+var ConnectionPoolError = class extends SirannonError {
+  constructor(message) {
+    super(message, "CONNECTION_POOL_ERROR");
+    this.name = "ConnectionPoolError";
+  }
+};
+var MaxDatabasesError = class extends SirannonError {
+  constructor(max) {
+    super(`Maximum number of open databases (${max}) reached`, "MAX_DATABASES");
+    this.name = "MaxDatabasesError";
+  }
+};
+var ExtensionError = class extends SirannonError {
+  constructor(path, cause) {
+    super(
+      cause ? `Failed to load extension '${path}': ${cause}` : `Failed to load extension '${path}'`,
+      "EXTENSION_ERROR"
+    );
+    this.name = "ExtensionError";
+  }
+};
+
+export { BackupError, CDCError, ConnectionPoolError, DatabaseAlreadyExistsError, DatabaseNotFoundError, ExtensionError, HookDeniedError, MaxDatabasesError, MigrationError, QueryError, ReadOnlyError, SirannonError, TransactionError };

package/dist/chunk-PXKAKK2V.mjs

@@ -0,0 +1,124 @@
+import { BackupError } from './chunk-O7BHI3CF.mjs';
+import { existsSync, mkdirSync, rmSync, readdirSync, lstatSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { Cron } from 'croner';
+
+var BACKUP_FILE_PREFIX = "backup";
+function hasControlCharacters(s) {
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    if (code <= 31) return true;
+  }
+  return false;
+}
+var BackupManager = class {
+  async backup(conn, destPath) {
+    if (hasControlCharacters(destPath)) {
+      throw new BackupError("Backup path contains invalid characters");
+    }
+    const segments = destPath.split(/[/\\]/);
+    if (segments.includes("..")) {
+      throw new BackupError("Backup path must not contain directory traversal segments");
+    }
+    const resolved = resolve(destPath);
+    const dir = dirname(resolved);
+    if (!existsSync(dir)) {
+      try {
+        mkdirSync(dir, { recursive: true });
+      } catch (err) {
+        throw new BackupError(
+          `Failed to create backup directory '${dir}': ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    if (existsSync(resolved)) {
+      throw new BackupError(`Backup destination '${destPath}' already exists`);
+    }
+    const escaped = resolved.replace(/'/g, "''");
+    try {
+      await conn.exec(`VACUUM INTO '${escaped}'`);
+    } catch (err) {
+      try {
+        rmSync(resolved, { force: true });
+      } catch {
+      }
+      throw new BackupError(`Backup to '${destPath}' failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  generateFilename() {
+    const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    return `${BACKUP_FILE_PREFIX}-${ts}.db`;
+  }
+  rotate(dir, maxFiles) {
+    if (maxFiles <= 0) return;
+    const resolved = resolve(dir);
+    if (!existsSync(resolved)) return;
+    let entries;
+    try {
+      entries = readdirSync(resolved).filter((f) => f.startsWith(`${BACKUP_FILE_PREFIX}-`) && f.endsWith(".db")).map((f) => {
+        const filePath = join(resolved, f);
+        return { path: filePath, mtimeMs: lstatSync(filePath).mtimeMs };
+      }).sort((a, b) => b.mtimeMs - a.mtimeMs);
+    } catch (err) {
+      throw new BackupError(
+        `Failed to list backup files in '${dir}': ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    for (const entry of entries.slice(maxFiles)) {
+      try {
+        rmSync(entry.path, { force: true });
+      } catch {
+      }
+    }
+  }
+};
+var DEFAULT_MAX_FILES = 5;
+var BackupScheduler = class {
+  manager;
+  constructor(manager) {
+    this.manager = manager ?? new BackupManager();
+  }
+  schedule(conn, options) {
+    const { cron: cronExpr, destDir, maxFiles = DEFAULT_MAX_FILES, onError } = options;
+    const resolvedDir = resolve(destDir);
+    if (!existsSync(resolvedDir)) {
+      try {
+        mkdirSync(resolvedDir, { recursive: true });
+      } catch (err) {
+        throw new BackupError(
+          `Failed to create backup directory '${destDir}': ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    let job;
+    try {
+      job = new Cron(
+        cronExpr,
+        {
+          unref: true,
+          catch: (err) => {
+            if (onError) {
+              const error = err instanceof Error ? err : new BackupError(typeof err === "string" ? err : "Scheduled backup failed");
+              onError(error);
+            }
+          }
+        },
+        async () => {
+          const filename = this.manager.generateFilename();
+          const destPath = join(resolvedDir, filename);
+          await this.manager.backup(conn, destPath);
+          this.manager.rotate(resolvedDir, maxFiles);
+        }
+      );
+    } catch (err) {
+      throw new BackupError(
+        `Invalid cron expression '${cronExpr}': ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    return () => {
+      job.stop();
+    };
+  }
+};
+
+export { BackupManager, BackupScheduler };