@delali/sirannon-db 0.1.6 → 0.1.7

package/dist/chunk-GEZUUIKV.mjs

@@ -0,0 +1,268 @@
+import { ForbiddenSqlError } from './chunk-YPYVQJ4C.mjs';
+
+// src/core/internal-tables.ts
+var INTERNAL_TABLE_PREFIX = "_sirannon_";
+var CHANGES_TABLE = "_sirannon_changes";
+var META_TABLE = "_sirannon_meta";
+var MIGRATIONS_TABLE = "_sirannon_migrations";
+var PEER_STATE_TABLE = "_sirannon_peer_state";
+var APPLIED_CHANGES_TABLE = "_sirannon_applied_changes";
+var COLUMN_VERSIONS_TABLE = "_sirannon_column_versions";
+var SYNC_STATE_TABLE = "_sirannon_sync_state";
+var CDC_TRIGGER_PREFIX = "_sirannon_trg_";
+var SIRANNON_PREFIX = "_sirannon";
+var SQLITE_PREFIX = "sqlite_";
+var SIRANNON_MESSAGE = "Access to internal tables is not permitted: identifiers beginning with '_sirannon' are reserved";
+var SQLITE_WRITE_MESSAGE = "The SQLite schema catalogue is read-only: statements that modify a 'sqlite_' identifier are not permitted";
+var ATTACH_MESSAGE = "ATTACH and DETACH statements are not permitted";
+var WRITABLE_SCHEMA_MESSAGE = "PRAGMA writable_schema is not permitted";
+var WRITE_VERBS = /* @__PURE__ */ new Set(["insert", "update", "delete", "replace", "create", "alter", "drop", "vacuum", "reindex"]);
+function reservedKind(name) {
+  const lower = name.toLowerCase();
+  if (lower.startsWith(SIRANNON_PREFIX)) return "sirannon";
+  if (lower.startsWith(SQLITE_PREFIX)) return "sqlite";
+  return null;
+}
+function isReservedIdentifier(name) {
+  return reservedKind(name) !== null;
+}
+function reservedSqlError(sql) {
+  const lower = sql.toLowerCase();
+  if (!lower.includes("_sirannon") && !lower.includes("sqlite_") && !lower.includes("attach") && !lower.includes("detach") && !lower.includes("writable_schema")) {
+    return null;
+  }
+  return scan(sql);
+}
+function assertSqlAllowed(sql) {
+  const reason = reservedSqlError(sql);
+  if (reason) {
+    throw new ForbiddenSqlError(reason);
+  }
+}
+function isWordStart(c) {
+  return c >= "a" && c <= "z" || c >= "A" && c <= "Z" || c === "_";
+}
+function isWordPart(c) {
+  return isWordStart(c) || c >= "0" && c <= "9" || c === "$";
+}
+function referenceError(kind, verb) {
+  if (kind === "sirannon") return SIRANNON_MESSAGE;
+  if (kind === "sqlite" && WRITE_VERBS.has(verb)) return SQLITE_WRITE_MESSAGE;
+  return null;
+}
+function scan(sql) {
+  const n = sql.length;
+  let i = 0;
+  let statementStart = true;
+  let verb = "";
+  while (i < n) {
+    const c = sql[i];
+    if (c === " " || c === "	" || c === "\n" || c === "\r" || c === "\f" || c === "\v") {
+      i++;
+      continue;
+    }
+    if (c === "-" && sql[i + 1] === "-") {
+      i += 2;
+      while (i < n && sql[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && sql[i + 1] === "*") {
+      i += 2;
+      while (i < n && !(sql[i] === "*" && sql[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    if (c === "'") {
+      i = skipQuoted(sql, i, "'");
+      statementStart = false;
+      continue;
+    }
+    if (c === '"' || c === "`") {
+      const delimited = readDelimited(sql, i, c);
+      const error = referenceError(reservedKind(delimited.value), verb);
+      if (error) return error;
+      i = delimited.next;
+      statementStart = false;
+      continue;
+    }
+    if (c === "[") {
+      const end = sql.indexOf("]", i + 1);
+      const stop = end === -1 ? n : end;
+      const error = referenceError(reservedKind(sql.slice(i + 1, stop)), verb);
+      if (error) return error;
+      i = stop + 1;
+      statementStart = false;
+      continue;
+    }
+    if (c === ";") {
+      i++;
+      statementStart = true;
+      verb = "";
+      continue;
+    }
+    if (isWordStart(c)) {
+      let j = i + 1;
+      while (j < n && isWordPart(sql[j])) j++;
+      const word = sql.slice(i, j);
+      const lowerWord = word.toLowerCase();
+      if (statementStart) {
+        verb = lowerWord;
+        if (lowerWord === "attach" || lowerWord === "detach") return ATTACH_MESSAGE;
+      } else if (verb === "pragma" && lowerWord === "writable_schema") {
+        return WRITABLE_SCHEMA_MESSAGE;
+      }
+      const error = referenceError(reservedKind(word), verb);
+      if (error) return error;
+      i = j;
+      statementStart = false;
+      continue;
+    }
+    i++;
+    statementStart = false;
+  }
+  return null;
+}
+function skipQuoted(sql, start, quote) {
+  const n = sql.length;
+  let i = start + 1;
+  while (i < n) {
+    if (sql[i] === quote) {
+      if (sql[i + 1] === quote) {
+        i += 2;
+        continue;
+      }
+      return i + 1;
+    }
+    i++;
+  }
+  return n;
+}
+function readDelimited(sql, start, quote) {
+  const n = sql.length;
+  let i = start + 1;
+  let value = "";
+  while (i < n) {
+    if (sql[i] === quote) {
+      if (sql[i + 1] === quote) {
+        value += quote;
+        i += 2;
+        continue;
+      }
+      return { value, next: i + 1 };
+    }
+    value += sql[i];
+    i++;
+  }
+  return { value, next: n };
+}
+
+// src/core/cdc/encoding.ts
+var BLOB_TAG = "__sirannon_blob";
+var INT_TAG = "__sirannon_int";
+var SAFE_INT_BOUND_TEXT = "9007199254740991";
+var SAFE_INT_BOUND = 9007199254740991n;
+var HEX_BYTES_RE = /^[0-9a-fA-F]*$/;
+var INT_PAYLOAD_RE = /^-?\d{1,19}$/;
+function encodeTaggedValues(value) {
+  if (typeof value === "bigint" || isBinaryValue(value)) {
+    return encodeTaggedLeaf(value);
+  }
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    return value.map(encodeTaggedValues);
+  }
+  if (typeof value.toJSON === "function") {
+    return value;
+  }
+  const obj = value;
+  const out = {};
+  for (const k of Object.keys(obj)) {
+    out[k] = encodeTaggedValues(obj[k]);
+  }
+  return out;
+}
+function encodeTaggedLeaf(value) {
+  if (typeof value === "bigint") {
+    if (value >= -SAFE_INT_BOUND && value <= SAFE_INT_BOUND) {
+      return Number(value);
+    }
+    return { [INT_TAG]: value.toString() };
+  }
+  if (isBinaryValue(value)) {
+    return { [BLOB_TAG]: encodeHexBytes(value) };
+  }
+  return value;
+}
+function encodeWireRowsInPlace(rows) {
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    if (row === null || typeof row !== "object") continue;
+    const obj = row;
+    for (const k of Object.keys(obj)) {
+      const cell = obj[k];
+      if (typeof cell === "bigint" || isBinaryValue(cell)) {
+        obj[k] = encodeTaggedLeaf(cell);
+      }
+    }
+  }
+  return rows;
+}
+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") {
+      if (!INT_PAYLOAD_RE.test(tagValue)) {
+        throw new Error("Invalid tagged integer payload");
+      }
+      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 encodeHexBytes(bytes) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("hex").toUpperCase();
+  }
+  let hex = "";
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex.toUpperCase();
+}
+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 { APPLIED_CHANGES_TABLE, CDC_TRIGGER_PREFIX, CHANGES_TABLE, COLUMN_VERSIONS_TABLE, INTERNAL_TABLE_PREFIX, META_TABLE, MIGRATIONS_TABLE, PEER_STATE_TABLE, SAFE_INT_BOUND_TEXT, SYNC_STATE_TABLE, assertSqlAllowed, decodeTaggedValues, encodeTaggedValues, encodeWireRowsInPlace, isReservedIdentifier };

package/dist/{chunk-UVMVN3OT.mjs → chunk-H5AB6NIR.mjs}

@@ -1,4 +1,4 @@
-import { SirannonError } from './chunk-O7BHI3CF.mjs';
+import { SirannonError } from './chunk-YPYVQJ4C.mjs';
 
 // src/replication/errors.ts
 var ReplicationError = class extends SirannonError {

package/dist/{chunk-UTO3ZAFS.mjs → chunk-HHRMRFFR.mjs}

@@ -1,11 +1,67 @@
-import { decodeTaggedValues, SAFE_INT_BOUND_TEXT } from './chunk-GS7T5YMI.mjs';
-import { CDCError } from './chunk-O7BHI3CF.mjs';
+import { synchronousPragmaValue } from './chunk-CJLYFDP5.mjs';
+import { CHANGES_TABLE, isReservedIdentifier, decodeTaggedValues, CDC_TRIGGER_PREFIX, SAFE_INT_BOUND_TEXT } from './chunk-GEZUUIKV.mjs';
+import { SirannonError, ForbiddenSqlError, CDCError } from './chunk-YPYVQJ4C.mjs';
+
+// src/core/bulk-load.ts
+var DEFAULT_LOAD_DURABILITY = "off";
+var CHECKPOINT_ATTEMPTS = 3;
+var CHECKPOINT_RETRY_DELAY_MS = 50;
+function isBulkLoadDurability(value) {
+  return value === "off" || value === "normal";
+}
+async function runBulkLoad(run) {
+  const durability = run.durability ?? DEFAULT_LOAD_DURABILITY;
+  if (!isBulkLoadDurability(durability)) {
+    throw new SirannonError("Bulk load durability must be 'off' or 'normal'", "INVALID_DURABILITY");
+  }
+  const restorePragma = `PRAGMA synchronous = ${synchronousPragmaValue(run.configuredSynchronous)}`;
+  await run.writer.exec(`PRAGMA synchronous = ${synchronousPragmaValue(durability)}`);
+  let result;
+  let loadError;
+  try {
+    result = await run.loadRows();
+  } catch (err) {
+    loadError = err;
+  }
+  try {
+    await run.writer.exec(restorePragma);
+  } catch {
+    if (loadError !== void 0) throw loadError;
+    throw new SirannonError(
+      "Bulk load committed but durability could not be restored because the writer connection failed",
+      "DURABILITY_RESTORE_FAILED"
+    );
+  }
+  if (loadError !== void 0) {
+    throw loadError;
+  }
+  if (result === void 0) {
+    throw new SirannonError("Bulk load completed without a result", "INTERNAL_ERROR");
+  }
+  if ((run.checkpoint ?? true) && run.walMode && result.changes > 0) {
+    await checkpoint(run.writer);
+  }
+  return result;
+}
+async function checkpoint(writer) {
+  for (let attempt = 0; attempt < CHECKPOINT_ATTEMPTS; attempt++) {
+    if (attempt > 0) {
+      await delay(attempt * CHECKPOINT_RETRY_DELAY_MS);
+    }
+    const stmt = await writer.prepare("PRAGMA wal_checkpoint(TRUNCATE)");
+    const row = await stmt.get();
+    if (!row || row.busy === 0) return;
+  }
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 // 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"`);
+  await conn.exec(`DROP TRIGGER IF EXISTS "${CDC_TRIGGER_PREFIX}${table}_insert"`);
+  await conn.exec(`DROP TRIGGER IF EXISTS "${CDC_TRIGGER_PREFIX}${table}_update"`);
+  await conn.exec(`DROP TRIGGER IF EXISTS "${CDC_TRIGGER_PREFIX}${table}_delete"`);
 }
 async function installCdcTriggers(conn, changesTable, table, columns, pkColumns, replication) {
   const newJson = buildJsonObject(columns, "NEW");
@@ -15,7 +71,7 @@ async function installCdcTriggers(conn, changesTable, table, columns, pkColumns,
   const replCols = replication ? ", node_id, tx_id, hlc" : "";
   const replVals = replication ? ", '', '', ''" : "";
   await conn.exec(`
-			CREATE TRIGGER IF NOT EXISTS "_sirannon_trg_${table}_insert"
+			CREATE TRIGGER IF NOT EXISTS "${CDC_TRIGGER_PREFIX}${table}_insert"
 			AFTER INSERT ON "${table}"
 			BEGIN
 				INSERT INTO "${changesTable}" (table_name, operation, row_id, new_data${replCols})
@@ -23,7 +79,7 @@ async function installCdcTriggers(conn, changesTable, table, columns, pkColumns,
 			END
 		`);
   await conn.exec(`
-			CREATE TRIGGER IF NOT EXISTS "_sirannon_trg_${table}_update"
+			CREATE TRIGGER IF NOT EXISTS "${CDC_TRIGGER_PREFIX}${table}_update"
 			AFTER UPDATE ON "${table}"
 			BEGIN
 				INSERT INTO "${changesTable}" (table_name, operation, row_id, old_data, new_data${replCols})
@@ -31,7 +87,7 @@ async function installCdcTriggers(conn, changesTable, table, columns, pkColumns,
 			END
 		`);
   await conn.exec(`
-			CREATE TRIGGER IF NOT EXISTS "_sirannon_trg_${table}_delete"
+			CREATE TRIGGER IF NOT EXISTS "${CDC_TRIGGER_PREFIX}${table}_delete"
 			AFTER DELETE ON "${table}"
 			BEGIN
 				INSERT INTO "${changesTable}" (table_name, operation, row_id, old_data${replCols})
@@ -64,7 +120,6 @@ function escStr(name) {
 
 // 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 {
@@ -80,13 +135,16 @@ var ChangeTracker = class {
   pruneBoundary = null;
   constructor(options) {
     this.retentionMs = options?.retention ?? DEFAULT_RETENTION_MS;
-    this.changesTable = options?.changesTable ?? DEFAULT_CHANGES_TABLE;
+    this.changesTable = options?.changesTable ?? 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");
+    if (isReservedIdentifier(table)) {
+      throw new ForbiddenSqlError(`Table '${table}' is reserved for Sirannon and cannot be watched`);
+    }
     await this.ensureChangesTable(conn);
     const columns = await this.getColumns(conn, table);
     if (columns.length === 0) {
@@ -226,20 +284,64 @@ var ChangeTracker = class {
     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
-      });
-    }
+    const events = rows.map((row) => this.rowToEvent(row));
     this.lastSeq = BigInt(rows[rows.length - 1].seq);
     return events;
   }
+  /** The highest seq already polled; live subscribers receive events beyond it. */
+  get cursor() {
+    return this.lastSeq;
+  }
+  /**
+   * Reads retained changes for one table with seq in `(afterSeq, upToSeq]`,
+   * ordered ascending and capped at `limit`. Used to replay history to a
+   * resuming subscriber without disturbing the shared poll cursor.
+   */
+  async readSince(conn, table, afterSeq, upToSeq, limit) {
+    if (!this.changesTableReady) {
+      await this.detectChangesTable(conn);
+      if (!this.changesTableReady) {
+        return [];
+      }
+    }
+    const stmt = await this.getStmt(
+      conn,
+      "read_since",
+      `SELECT seq, table_name, operation, row_id, changed_at, old_data, new_data
+			 FROM "${this.changesTable}"
+			 WHERE table_name = ? AND seq > ? AND seq <= ?
+			 ORDER BY seq ASC
+			 LIMIT ?`
+    );
+    const rows = await stmt.all(table, afterSeq.toString(), upToSeq.toString(), limit);
+    return rows.map((row) => this.rowToEvent(row));
+  }
+  /** The lowest retained seq, or `null` when the change log is empty. */
+  async getMinSeq(conn) {
+    if (!this.changesTableReady) {
+      await this.detectChangesTable(conn);
+      if (!this.changesTableReady) {
+        return null;
+      }
+    }
+    const stmt = await this.getStmt(conn, "min_seq", `SELECT MIN(seq) AS seq FROM "${this.changesTable}"`);
+    const row = await stmt.get();
+    const seq = row?.seq;
+    if (seq === void 0 || seq === null) {
+      return null;
+    }
+    return typeof seq === "bigint" ? seq : BigInt(String(seq));
+  }
+  rowToEvent(row) {
+    return {
+      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
+    };
+  }
   async advanceToLatest(conn) {
     if (!this.changesTableReady) {
       await this.detectChangesTable(conn);
@@ -430,7 +532,7 @@ var SubscriptionManager = class {
       for (const id of ids) {
         const sub = this.subscriptions.get(id);
         if (!sub) continue;
-        if (sub.filter && !matchesFilter(event, sub.filter)) {
+        if (sub.filter && !changeMatchesFilter(event, sub.filter)) {
           continue;
         }
         try {
@@ -461,18 +563,19 @@ var SubscriptionBuilderImpl = class {
     return this.manager.subscribe(this.table, this.conditions, callback);
   }
 };
-function startPolling(conn, tracker, manager, intervalMs, onError) {
+function startPolling(conn, tracker, manager, intervalMs, onError, runExclusive) {
   let consecutiveErrors = 0;
   let tickCount = 0;
   let polling = false;
   const MAX_CONSECUTIVE_ERRORS = 10;
   const CLEANUP_INTERVAL_TICKS = 100;
+  const exclusive = runExclusive ?? ((operation) => operation());
   const tick = async () => {
     if (manager.size === 0) return;
     if (polling) return;
     polling = true;
     try {
-      const events = await tracker.poll(conn);
+      const events = await exclusive(() => tracker.poll(conn));
       if (events.length > 0) {
         manager.dispatch(events);
       }
@@ -480,7 +583,7 @@ function startPolling(conn, tracker, manager, intervalMs, onError) {
       tickCount++;
       if (tickCount >= CLEANUP_INTERVAL_TICKS) {
         tickCount = 0;
-        await tracker.cleanup(conn);
+        await exclusive(() => tracker.cleanup(conn));
       }
     } catch (err) {
       consecutiveErrors++;
@@ -501,14 +604,31 @@ function startPolling(conn, tracker, manager, intervalMs, onError) {
   };
   return stop;
 }
-function matchesFilter(event, filter) {
+function changeMatchesFilter(event, filter) {
   const target = event.type === "delete" ? event.oldRow ?? {} : event.row;
   for (const [key, value] of Object.entries(filter)) {
-    if (target[key] !== value) {
+    if (!filterValueMatches(target[key], value)) {
       return false;
     }
   }
   return true;
 }
+function filterValueMatches(rowValue, filterValue) {
+  if (rowValue === filterValue) return true;
+  if (typeof rowValue === "bigint" && typeof filterValue === "number") {
+    return Number.isInteger(filterValue) && BigInt(filterValue) === rowValue;
+  }
+  if (typeof rowValue === "number" && typeof filterValue === "bigint") {
+    return Number.isInteger(rowValue) && BigInt(rowValue) === filterValue;
+  }
+  if (rowValue instanceof Uint8Array && filterValue instanceof Uint8Array) {
+    if (rowValue.byteLength !== filterValue.byteLength) return false;
+    for (let i = 0; i < rowValue.byteLength; i++) {
+      if (rowValue[i] !== filterValue[i]) return false;
+    }
+    return true;
+  }
+  return false;
+}
 
-export { ChangeTracker, SubscriptionBuilderImpl, SubscriptionManager, startPolling };
+export { ChangeTracker, SubscriptionBuilderImpl, SubscriptionManager, changeMatchesFilter, isBulkLoadDurability, runBulkLoad, startPolling };

package/dist/chunk-TKGHYWQ6.mjs

@@ -0,0 +1,35 @@
+import { query, execute, executeBatch } from './chunk-CW6S3WL5.mjs';
+
+// 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 };