@delali/sirannon-db 0.1.3 → 0.1.5

package/dist/chunk-UTO3ZAFS.mjs

@@ -0,0 +1,514 @@
+import { decodeTaggedValues, SAFE_INT_BOUND_TEXT } from './chunk-GS7T5YMI.mjs';
+import { CDCError } from './chunk-O7BHI3CF.mjs';
+
+// src/core/cdc/trigger-sql.ts
+async function dropCdcTriggers(conn, table) {
+  await conn.exec(`DROP TRIGGER IF EXISTS "_sirannon_trg_${table}_insert"`);
+  await conn.exec(`DROP TRIGGER IF EXISTS "_sirannon_trg_${table}_update"`);
+  await conn.exec(`DROP TRIGGER IF EXISTS "_sirannon_trg_${table}_delete"`);
+}
+async function installCdcTriggers(conn, changesTable, table, columns, pkColumns, replication) {
+  const newJson = buildJsonObject(columns, "NEW");
+  const oldJson = buildJsonObject(columns, "OLD");
+  const newPk = buildPkRef(pkColumns, "NEW");
+  const oldPk = buildPkRef(pkColumns, "OLD");
+  const replCols = replication ? ", node_id, tx_id, hlc" : "";
+  const replVals = replication ? ", '', '', ''" : "";
+  await conn.exec(`
+			CREATE TRIGGER IF NOT EXISTS "_sirannon_trg_${table}_insert"
+			AFTER INSERT ON "${table}"
+			BEGIN
+				INSERT INTO "${changesTable}" (table_name, operation, row_id, new_data${replCols})
+				VALUES ('${table}', 'INSERT', ${newPk}, ${newJson}${replVals});
+			END
+		`);
+  await conn.exec(`
+			CREATE TRIGGER IF NOT EXISTS "_sirannon_trg_${table}_update"
+			AFTER UPDATE ON "${table}"
+			BEGIN
+				INSERT INTO "${changesTable}" (table_name, operation, row_id, old_data, new_data${replCols})
+				VALUES ('${table}', 'UPDATE', ${newPk}, ${oldJson}, ${newJson}${replVals});
+			END
+		`);
+  await conn.exec(`
+			CREATE TRIGGER IF NOT EXISTS "_sirannon_trg_${table}_delete"
+			AFTER DELETE ON "${table}"
+			BEGIN
+				INSERT INTO "${changesTable}" (table_name, operation, row_id, old_data${replCols})
+				VALUES ('${table}', 'DELETE', ${oldPk}, ${oldJson}${replVals});
+			END
+		`);
+}
+function buildPkRef(pkColumns, ref) {
+  if (pkColumns.length === 0) {
+    return `${ref}.rowid`;
+  }
+  if (pkColumns.length === 1) {
+    return `${ref}."${escId(pkColumns[0])}"`;
+  }
+  return pkColumns.map((col) => `${ref}."${escId(col)}"`).join(" || '-' || ");
+}
+function buildJsonObject(columns, ref) {
+  const pairs = columns.map((col) => {
+    const ident = `${ref}."${escId(col)}"`;
+    return `'${escStr(col)}', CASE typeof(${ident}) WHEN 'blob' THEN json(json_object('__sirannon_blob', hex(${ident}))) WHEN 'integer' THEN CASE WHEN ${ident} > ${SAFE_INT_BOUND_TEXT} OR ${ident} < -${SAFE_INT_BOUND_TEXT} THEN json(json_object('__sirannon_int', printf('%d', ${ident}))) ELSE ${ident} END ELSE ${ident} END`;
+  }).join(", ");
+  return `json_object(${pairs})`;
+}
+function escId(name) {
+  return name.replace(/"/g, '""');
+}
+function escStr(name) {
+  return name.replace(/'/g, "''");
+}
+
+// src/core/cdc/change-tracker.ts
+var DEFAULT_RETENTION_MS = 36e5;
+var DEFAULT_CHANGES_TABLE = "_sirannon_changes";
+var DEFAULT_POLL_BATCH_SIZE = 1e3;
+var IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var ChangeTracker = class {
+  watched = /* @__PURE__ */ new Map();
+  lastSeq = 0n;
+  retentionMs;
+  changesTable;
+  pollBatchSize;
+  replication;
+  changesTableReady = false;
+  watchedTablesCache = null;
+  stmtCache = /* @__PURE__ */ new WeakMap();
+  pruneBoundary = null;
+  constructor(options) {
+    this.retentionMs = options?.retention ?? DEFAULT_RETENTION_MS;
+    this.changesTable = options?.changesTable ?? DEFAULT_CHANGES_TABLE;
+    this.pollBatchSize = options?.pollBatchSize ?? DEFAULT_POLL_BATCH_SIZE;
+    this.replication = options?.replication ?? false;
+    this.assertIdentifier(this.changesTable, "changes table name");
+  }
+  async watch(conn, table) {
+    this.assertIdentifier(table, "table name");
+    await this.ensureChangesTable(conn);
+    const columns = await this.getColumns(conn, table);
+    if (columns.length === 0) {
+      throw new CDCError(`Table '${table}' does not exist or has no columns`);
+    }
+    for (const col of columns) {
+      this.assertIdentifier(col, `column name in table '${table}'`);
+    }
+    const pkColumns = await this.getPkColumns(conn, table);
+    const existing = this.watched.get(table);
+    if (existing) {
+      const same = existing.columns.length === columns.length && existing.columns.every((col, i) => col === columns[i]);
+      if (same) {
+        return;
+      }
+      await conn.transaction(async (txConn) => {
+        await this.dropTriggers(txConn, table);
+        await this.installTriggers(txConn, table, columns, pkColumns);
+      });
+    } else {
+      await this.installTriggers(conn, table, columns, pkColumns);
+    }
+    this.watched.set(table, { table, columns, pkColumns });
+    this.watchedTablesCache = null;
+  }
+  async unwatch(conn, table) {
+    if (!this.watched.has(table)) {
+      return;
+    }
+    await this.dropTriggers(conn, table);
+    this.watched.delete(table);
+    this.watchedTablesCache = null;
+  }
+  /**
+   * 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.
+   */
+  async refreshAllTriggersUsingConnection(conn) {
+    const tables = Array.from(this.watched.keys());
+    let anyMutated = false;
+    for (const table of tables) {
+      const existing = this.watched.get(table);
+      if (!existing) continue;
+      const columns = await this.getColumns(conn, table);
+      if (columns.length === 0) {
+        continue;
+      }
+      for (const col of columns) {
+        this.assertIdentifier(col, `column name in table '${table}'`);
+      }
+      const same = existing.columns.length === columns.length && existing.columns.every((col, i) => col === columns[i]);
+      if (same) {
+        continue;
+      }
+      const pkColumns = await this.getPkColumns(conn, table);
+      await this.dropTriggers(conn, table);
+      await this.installTriggers(conn, table, columns, pkColumns);
+      this.watched.set(table, { table, columns, pkColumns });
+      anyMutated = true;
+    }
+    if (anyMutated) {
+      this.watchedTablesCache = null;
+    }
+  }
+  /**
+   * 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.
+   */
+  async pruneDroppedTables(conn, tables) {
+    let mutated = false;
+    for (const table of tables) {
+      if (!this.watched.has(table)) {
+        continue;
+      }
+      await this.dropTriggers(conn, table);
+      this.watched.delete(table);
+      mutated = true;
+    }
+    if (mutated) {
+      this.watchedTablesCache = null;
+    }
+  }
+  async poll(conn) {
+    if (!this.changesTableReady) {
+      await this.detectChangesTable(conn);
+      if (!this.changesTableReady) {
+        return [];
+      }
+    }
+    const stmt = await this.getStmt(
+      conn,
+      "poll",
+      `SELECT seq, table_name, operation, row_id, changed_at, old_data, new_data
+			 FROM "${this.changesTable}"
+			 WHERE seq > ?
+			 ORDER BY seq ASC
+			 LIMIT ?`
+    );
+    const rows = await stmt.all(this.lastSeq.toString(), this.pollBatchSize);
+    if (rows.length === 0) {
+      return [];
+    }
+    const events = [];
+    for (const row of rows) {
+      events.push({
+        type: row.operation.toLowerCase(),
+        table: row.table_name,
+        row: row.new_data ? decodeTaggedValues(JSON.parse(row.new_data)) : {},
+        oldRow: row.old_data ? decodeTaggedValues(JSON.parse(row.old_data)) : void 0,
+        seq: BigInt(row.seq),
+        timestamp: row.changed_at
+      });
+    }
+    this.lastSeq = BigInt(rows[rows.length - 1].seq);
+    return events;
+  }
+  async advanceToLatest(conn) {
+    if (!this.changesTableReady) {
+      await this.detectChangesTable(conn);
+      if (!this.changesTableReady) {
+        return;
+      }
+    }
+    const stmt = await this.getStmt(conn, "latest_seq", `SELECT MAX(seq) AS seq FROM "${this.changesTable}"`);
+    const row = await stmt.get();
+    const seq = row?.seq;
+    if (seq === void 0 || seq === null) {
+      return;
+    }
+    const latestSeq = typeof seq === "bigint" ? seq : BigInt(String(seq));
+    if (latestSeq > this.lastSeq) {
+      this.lastSeq = latestSeq;
+    }
+  }
+  async cleanup(conn) {
+    if (!this.changesTableReady) {
+      await this.detectChangesTable(conn);
+      if (!this.changesTableReady) {
+        return 0;
+      }
+    }
+    const cutoff = Date.now() / 1e3 - this.retentionMs / 1e3;
+    const seqBound = this.computeSeqBound();
+    if (seqBound !== null) {
+      const stmt2 = await this.getStmt(
+        conn,
+        "cleanup_coordinated",
+        `DELETE FROM "${this.changesTable}" WHERE changed_at < ? AND seq <= ?`
+      );
+      const result2 = await stmt2.run(cutoff, seqBound.toString());
+      return result2.changes;
+    }
+    const stmt = await this.getStmt(conn, "cleanup", `DELETE FROM "${this.changesTable}" WHERE changed_at < ?`);
+    const result = await stmt.run(cutoff);
+    return result.changes;
+  }
+  setPruneBoundary(seq) {
+    this.pruneBoundary = seq;
+  }
+  clearPruneBoundary() {
+    this.pruneBoundary = null;
+  }
+  get watchedTables() {
+    if (!this.watchedTablesCache) {
+      this.watchedTablesCache = new Set(this.watched.keys());
+    }
+    return this.watchedTablesCache;
+  }
+  computeSeqBound() {
+    const boundary = this.pruneBoundary;
+    if (this.lastSeq > 0n && boundary !== null) {
+      return this.lastSeq < boundary ? this.lastSeq : boundary;
+    }
+    if (boundary !== null) {
+      return boundary;
+    }
+    if (this.lastSeq > 0n) {
+      return this.lastSeq;
+    }
+    return null;
+  }
+  assertIdentifier(name, label) {
+    if (!IDENTIFIER_RE.test(name)) {
+      throw new CDCError(
+        `Invalid ${label} '${name}': must contain only letters, digits, and underscores, and start with a letter or underscore`
+      );
+    }
+  }
+  async detectChangesTable(conn) {
+    const stmt = await conn.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?");
+    const row = await stmt.get(this.changesTable);
+    if (row) {
+      this.changesTableReady = true;
+    }
+  }
+  async ensureChangesTable(conn) {
+    if (this.changesTableReady) {
+      return;
+    }
+    if (this.replication) {
+      await conn.exec(`
+CREATE TABLE IF NOT EXISTS "${this.changesTable}" (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  table_name TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  row_id TEXT NOT NULL,
+  changed_at REAL NOT NULL DEFAULT (unixepoch('subsec')),
+  old_data TEXT,
+  new_data TEXT,
+  node_id TEXT NOT NULL DEFAULT '',
+  tx_id TEXT NOT NULL DEFAULT '',
+  hlc TEXT NOT NULL DEFAULT ''
+)`);
+      await conn.exec(
+        `CREATE INDEX IF NOT EXISTS "idx_${this.changesTable}_changed_at" ON "${this.changesTable}" (changed_at)`
+      );
+      await conn.exec(
+        `CREATE INDEX IF NOT EXISTS "idx_${this.changesTable}_node_id" ON "${this.changesTable}" (node_id)`
+      );
+      await conn.exec(`CREATE INDEX IF NOT EXISTS "idx_${this.changesTable}_hlc" ON "${this.changesTable}" (hlc)`);
+    } else {
+      await conn.exec(`
+CREATE TABLE IF NOT EXISTS "${this.changesTable}" (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  table_name TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  row_id TEXT NOT NULL,
+  changed_at REAL NOT NULL DEFAULT (unixepoch('subsec')),
+  old_data TEXT,
+  new_data TEXT
+)`);
+      await conn.exec(
+        `CREATE INDEX IF NOT EXISTS "idx_${this.changesTable}_changed_at" ON "${this.changesTable}" (changed_at)`
+      );
+    }
+    this.changesTableReady = true;
+  }
+  async getColumns(conn, table) {
+    const stmt = await conn.prepare(`PRAGMA table_info("${table}")`);
+    const info = await stmt.all();
+    return info.map((col) => col.name);
+  }
+  async getPkColumns(conn, table) {
+    const stmt = await conn.prepare(`PRAGMA table_info("${table}")`);
+    const info = await stmt.all();
+    return info.filter((col) => col.pk > 0).sort((a, b) => a.pk - b.pk).map((col) => col.name);
+  }
+  async dropTriggers(conn, table) {
+    await dropCdcTriggers(conn, table);
+  }
+  async getStmt(conn, key, sql) {
+    let stmts = this.stmtCache.get(conn);
+    if (!stmts) {
+      stmts = /* @__PURE__ */ new Map();
+      this.stmtCache.set(conn, stmts);
+    }
+    const existing = stmts.get(key);
+    if (existing) return existing;
+    const pending = conn.prepare(sql);
+    stmts.set(key, pending);
+    try {
+      return await pending;
+    } catch (err) {
+      stmts.delete(key);
+      throw err;
+    }
+  }
+  async installTriggers(conn, table, columns, pkColumns) {
+    await installCdcTriggers(conn, this.changesTable, table, columns, pkColumns, this.replication);
+  }
+};
+
+// src/core/cdc/subscription.ts
+var SubscriptionManager = class {
+  nextId = 1;
+  subscriptions = /* @__PURE__ */ new Map();
+  byTable = /* @__PURE__ */ new Map();
+  subscribe(table, filter, callback) {
+    const id = this.nextId++;
+    this.subscriptions.set(id, { id, table, filter, callback });
+    let tableSet = this.byTable.get(table);
+    if (!tableSet) {
+      tableSet = /* @__PURE__ */ new Set();
+      this.byTable.set(table, tableSet);
+    }
+    tableSet.add(id);
+    return {
+      unsubscribe: () => {
+        this.subscriptions.delete(id);
+        const set = this.byTable.get(table);
+        if (set) {
+          set.delete(id);
+          if (set.size === 0) {
+            this.byTable.delete(table);
+          }
+        }
+      }
+    };
+  }
+  dispatch(events) {
+    for (const event of events) {
+      const ids = this.byTable.get(event.table);
+      if (!ids) continue;
+      for (const id of ids) {
+        const sub = this.subscriptions.get(id);
+        if (!sub) continue;
+        if (sub.filter && !matchesFilter(event, sub.filter)) {
+          continue;
+        }
+        try {
+          sub.callback(event);
+        } catch {
+        }
+      }
+    }
+  }
+  get size() {
+    return this.subscriptions.size;
+  }
+  subscriberCount(table) {
+    return this.byTable.get(table)?.size ?? 0;
+  }
+};
+var SubscriptionBuilderImpl = class {
+  constructor(table, manager) {
+    this.table = table;
+    this.manager = manager;
+  }
+  conditions;
+  filter(conditions) {
+    this.conditions = { ...this.conditions, ...conditions };
+    return this;
+  }
+  subscribe(callback) {
+    return this.manager.subscribe(this.table, this.conditions, callback);
+  }
+};
+function startPolling(conn, tracker, manager, intervalMs, onError) {
+  let consecutiveErrors = 0;
+  let tickCount = 0;
+  let polling = false;
+  const MAX_CONSECUTIVE_ERRORS = 10;
+  const CLEANUP_INTERVAL_TICKS = 100;
+  const tick = async () => {
+    if (manager.size === 0) return;
+    if (polling) return;
+    polling = true;
+    try {
+      const events = await tracker.poll(conn);
+      if (events.length > 0) {
+        manager.dispatch(events);
+      }
+      consecutiveErrors = 0;
+      tickCount++;
+      if (tickCount >= CLEANUP_INTERVAL_TICKS) {
+        tickCount = 0;
+        await tracker.cleanup(conn);
+      }
+    } catch (err) {
+      consecutiveErrors++;
+      if (onError) {
+        onError(err instanceof Error ? err : new Error(String(err)));
+      }
+      if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+        stop();
+      }
+    } finally {
+      polling = false;
+    }
+  };
+  const interval = setInterval(tick, intervalMs);
+  interval.unref?.();
+  const stop = () => {
+    clearInterval(interval);
+  };
+  return stop;
+}
+function matchesFilter(event, filter) {
+  const target = event.type === "delete" ? event.oldRow ?? {} : event.row;
+  for (const [key, value] of Object.entries(filter)) {
+    if (target[key] !== value) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export { ChangeTracker, SubscriptionBuilderImpl, SubscriptionManager, startPolling };

package/dist/chunk-UVMVN3OT.mjs

@@ -0,0 +1,111 @@
+import { SirannonError } from './chunk-O7BHI3CF.mjs';
+
+// src/replication/errors.ts
+var ReplicationError = class extends SirannonError {
+  constructor(message, code = "REPLICATION_ERROR", details) {
+    super(message, code);
+    this.details = details;
+    this.name = "ReplicationError";
+  }
+};
+var ConflictError = class extends ReplicationError {
+  constructor(message, table, rowId) {
+    super(message, "CONFLICT_ERROR");
+    this.table = table;
+    this.rowId = rowId;
+    this.name = "ConflictError";
+  }
+};
+var TransportError = class extends ReplicationError {
+  constructor(message) {
+    super(message, "TRANSPORT_ERROR");
+    this.name = "TransportError";
+  }
+};
+var BatchValidationError = class extends ReplicationError {
+  constructor(message) {
+    super(message, "BATCH_VALIDATION_ERROR");
+    this.name = "BatchValidationError";
+  }
+};
+var WriteConcernError = class extends ReplicationError {
+  constructor(message) {
+    super(message, "WRITE_CONCERN_ERROR");
+    this.name = "WriteConcernError";
+  }
+};
+var ReadConcernError = class extends ReplicationError {
+  constructor(message, details) {
+    super(message, "READ_CONCERN_ERROR", details);
+    this.name = "ReadConcernError";
+  }
+};
+var TopologyError = class extends ReplicationError {
+  constructor(message) {
+    super(message, "TOPOLOGY_ERROR");
+    this.name = "TopologyError";
+  }
+};
+var CoordinatorError = class extends ReplicationError {
+  constructor(message, details) {
+    super(message, "COORDINATOR_UNAVAILABLE", details);
+    this.name = "CoordinatorError";
+  }
+};
+var AuthorityError = class extends ReplicationError {
+  constructor(message, code = "AUTHORITY_LOST", details) {
+    super(message, code, details);
+    this.name = "AuthorityError";
+  }
+};
+var StalePrimaryError = class extends AuthorityError {
+  constructor(message, details) {
+    super(message, "STALE_PRIMARY", details);
+    this.name = "StalePrimaryError";
+  }
+};
+var FailoverError = class extends ReplicationError {
+  constructor(message, code = "NO_SAFE_PRIMARY", details) {
+    super(message, code, details);
+    this.name = "FailoverError";
+  }
+};
+var NoSafePrimaryError = class extends FailoverError {
+  constructor(message, details) {
+    super(message, "NO_SAFE_PRIMARY", details);
+    this.name = "NoSafePrimaryError";
+  }
+};
+var NodeNotInSyncError = class extends ReplicationError {
+  constructor(message, details) {
+    super(message, "NODE_NOT_IN_SYNC", details);
+    this.name = "NodeNotInSyncError";
+  }
+};
+var NodeDrainingError = class extends ReplicationError {
+  constructor(message, details) {
+    super(message, "NODE_DRAINING", details);
+    this.name = "NodeDrainingError";
+  }
+};
+var ProtocolVersionMismatchError = class extends ReplicationError {
+  constructor(message, details) {
+    super(message, "PROTOCOL_VERSION_MISMATCH", details);
+    this.name = "ProtocolVersionMismatchError";
+  }
+};
+var UnsafeRecoveryRequiredError = class extends FailoverError {
+  constructor(message, details) {
+    super(message, "UNSAFE_RECOVERY_REQUIRED", details);
+    this.name = "UnsafeRecoveryRequiredError";
+  }
+};
+var SyncError = class extends ReplicationError {
+  constructor(message, requestId) {
+    super(message, "SYNC_ERROR");
+    this.requestId = requestId;
+    this.name = "SyncError";
+  }
+};
+
+export { AuthorityError, BatchValidationError, ConflictError, CoordinatorError, FailoverError, NoSafePrimaryError, NodeDrainingError, NodeNotInSyncError, ProtocolVersionMismatchError, ReadConcernError, ReplicationError, StalePrimaryError, SyncError, TopologyError, TransportError, UnsafeRecoveryRequiredError, WriteConcernError };