@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/{chunk-JU64Y7HM.mjs → chunk-SBL6GN43.mjs}

@@ -1,4 +1,4 @@
-import { CDCError } from './chunk-UC3SCMIN.mjs';
+import { CDCError } from './chunk-PBRXXISQ.mjs';
 
 // src/core/live/sql-tokens.ts
 var WHITESPACE = /* @__PURE__ */ new Set([" ", "	", "\n", "\r", "\f", "\v"]);

package/dist/{chunk-EBJXPQQO.mjs → chunk-UPKKSUPA.mjs}

@@ -1,6 +1,6 @@
-import { BackupManager, BackupScheduler } from './chunk-PIKHN33N.mjs';
+import { BackupManager, BackupScheduler } from './chunk-VOYGMAU7.mjs';
 import { WORKER_CANCELLED_CODE, deserializeError } from './chunk-4ISB7XMA.mjs';
-import { SirannonError } from './chunk-UC3SCMIN.mjs';
+import { SirannonError } from './chunk-PBRXXISQ.mjs';
 import { Worker } from 'worker_threads';
 import { existsSync } from 'fs';
 import { resolve, dirname, join, sep } from 'path';

package/dist/{chunk-TJF5GZSV.mjs → chunk-VOSJBZ6Q.mjs}

@@ -1,4 +1,4 @@
-import { tokenizeSql, readSelectItems, findClauses } from './chunk-JU64Y7HM.mjs';
+import { tokenizeSql, readSelectItems, findClauses } from './chunk-SBL6GN43.mjs';
 import { operationRegistryDigest } from './chunk-TUD5CJ76.mjs';
 import { mkdirSync, writeFileSync } from 'fs';
 import { resolve, dirname } from 'path';

package/dist/{chunk-PIKHN33N.mjs → chunk-VOYGMAU7.mjs}

@@ -1,4 +1,4 @@
-import { BackupError } from './chunk-UC3SCMIN.mjs';
+import { BackupError } from './chunk-PBRXXISQ.mjs';
 import { existsSync, mkdirSync, rmSync, readdirSync, lstatSync } from 'fs';
 import { resolve, dirname, join } from 'path';
 
@@ -383,6 +383,14 @@ var BackupScheduler = class {
   constructor(manager) {
     this.manager = manager ?? new BackupManager();
   }
+  /**
+   * Starts repeating backups and returns a function that stops them.
+   *
+   * @param conn - Connection to the database being copied.
+   * @param options - Cron expression, destination directory, retention, time zone, and failure callback.
+   * @param runExclusive - Runs each copy with the database's writer held so that no write commits mid-copy.
+   * @returns A function that stops the schedule.
+   */
   schedule(conn, options, runExclusive = runDirect) {
     const { cron: cronExpr, destDir, maxFiles = DEFAULT_MAX_FILES, onError, timezone } = options;
     let cron;

package/dist/{chunk-H237TXZW.mjs → chunk-WJ67DTD6.mjs}

@@ -1,5 +1,6 @@
 // src/client/types.ts
 var RemoteError = class extends Error {
+  /** Machine-readable code the server sent with the error. */
   code;
   constructor(code, message) {
     super(message);
@@ -15,6 +16,7 @@ var RemoteLiveQuery = class _RemoteLiveQuery {
   listeners = /* @__PURE__ */ new Set();
   subscription = null;
   closed = false;
+  /** @internal */
   static async open(subscribe) {
     const query = new _RemoteLiveQuery();
     try {
@@ -30,15 +32,27 @@ var RemoteLiveQuery = class _RemoteLiveQuery {
     }
     return query;
   }
+  /**
+   * Returns the rows the query holds right now.
+   */
   getState() {
     return this.state;
   }
+  /**
+   * Calls back on each update and returns a function that stops the listener.
+   *
+   * @param listener - Receives each update.
+   * @returns A function that removes the listener.
+   */
   subscribe(listener) {
     this.listeners.add(listener);
     return () => {
       this.listeners.delete(listener);
     };
   }
+  /**
+   * Ends the query and releases its subscription.
+   */
   async close() {
     if (this.closed) return;
     this.closed = true;
@@ -168,7 +182,7 @@ var RemoteDatabase = class {
    * Execute multiple statements as a single atomic transaction.
    * Returns an array of results, one per statement.
    *
-   * The whole list travels in one request and commits or rolls back as a
+   * The whole list is sent in one request and commits or rolls back as a
    * unit, so the client is never in the loop between statements.
    */
   async transaction(statements) {
@@ -192,10 +206,10 @@ var RemoteDatabase = class {
    * for you and paying the one fsyncing WAL checkpoint once, after the final
    * batch. The configured durability is restored after every batch, so an
    * import that stops partway never leaves the writer at the relaxed level.
-   * Prefer this over {@link load} for anything larger than a single request:
-   * it runs the finalize itself, so there is no checkpoint flag to forget.
+   * Prefer this over {@link RemoteDatabase.load} for anything larger than a single request:
+   * it finalises the load itself, so there is no checkpoint flag to forget.
    *
-   * Accepts a synchronous or asynchronous iterable of parameter sets, so rows
+   * Accepts a synchronous or asynchronous iterable of parameter sets so that rows
    * can stream from a file or the network without being held in memory at
    * once. Returns the total rows loaded and changes applied.
    *
@@ -249,8 +263,8 @@ var RemoteDatabase = class {
   /**
    * Load one batch of rows through the same statement with writer durability
    * relaxed for the duration, then restored before this resolves. This is the
-   * low-level primitive; prefer {@link loadAll} for a dataset that spans more
-   * than one request, since it runs the finalize itself rather than relying on
+   * low-level primitive; prefer {@link RemoteDatabase.loadAll} for a dataset that spans more
+   * than one request, since it finalises the load itself rather than relying on
    * a `checkpoint` flag.
    *
    * Returns the total rows loaded and changes applied. When splitting a dataset
@@ -276,6 +290,11 @@ var RemoteDatabase = class {
    * // Later:
    * sub.unsubscribe()
    * ```
+   *
+   * Begins a change subscription on a watched table.
+   *
+   * @param table - Name of the watched table.
+   * @returns A builder you narrow with a filter and then subscribe to.
    */
   on(table) {
     return new RemoteSubscriptionBuilderImpl(table, this.transport);
@@ -581,6 +600,7 @@ function isMissingEndpoint(err) {
 
 // src/client/transport/http.ts
 var HttpTransport = class {
+  /** @internal */
   carriesReadConcern = true;
   baseUrl;
   headers;
@@ -592,6 +612,7 @@ var HttpTransport = class {
       ...headers
     };
   }
+  /** Sends a read and returns its rows. */
   async query(sql, params, readConcern) {
     const response = await this.post("/query", {
       sql,
@@ -600,14 +621,17 @@ var HttpTransport = class {
     });
     return { rows: decodeTaggedValues(response.rows ?? []) };
   }
+  /** Sends one write. */
   async execute(sql, params) {
     return this.post("/execute", { sql, params: encodeTaggedValues(params) });
   }
+  /** Sends several statements the server runs in one transaction. */
   async transaction(statements) {
     return this.post("/transaction", {
       statements: statements.map((stmt) => ({ sql: stmt.sql, params: encodeTaggedValues(stmt.params) }))
     });
   }
+  /** Sends one statement over many parameter sets, which the server runs in one transaction. */
   async batch(sql, paramsBatch, writeConcern) {
     return this.post("/batch", {
       sql,
@@ -615,6 +639,7 @@ var HttpTransport = class {
       writeConcern
     });
   }
+  /** Sends a bulk load, which the server runs at relaxed durability. */
   async load(sql, paramsBatch, durability, checkpoint) {
     return this.post("/load", {
       sql,
@@ -623,6 +648,7 @@ var HttpTransport = class {
       checkpoint
     });
   }
+  /** Runs a registered read by name and returns its rows. */
   async queryNamed(name, args, readConcern) {
     const response = await this.post(`/query/${encodeURIComponent(name)}`, {
       args: encodeTaggedValues(args),
@@ -630,24 +656,28 @@ var HttpTransport = class {
     });
     return { rows: decodeTaggedValues(response.rows ?? []) };
   }
+  /** Runs a registered write by name. */
   async executeNamed(name, args, writeConcern) {
     return this.post(`/execute/${encodeURIComponent(name)}`, {
       args: encodeTaggedValues(args),
       writeConcern
     });
   }
+  /** Opens a live query on a registered read and delivers its updates to the handlers. */
   async liveSubscribe() {
     throw new RemoteError(
       "TRANSPORT_ERROR",
       'Live queries require WebSocket transport. Create the client with { transport: "websocket" } to use them.'
     );
   }
+  /** Opens a change subscription on a watched table. */
   async subscribe(_table, _filter, _callback) {
     throw new RemoteError(
       "TRANSPORT_ERROR",
       'Subscriptions require WebSocket transport. Create the client with { transport: "websocket" } to use real-time subscriptions.'
     );
   }
+  /** Closes the transport and every subscription running on it. */
   close() {
     this.closed = true;
   }
@@ -1061,6 +1091,7 @@ var PendingRequests = class {
 // src/client/transport/ws.ts
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var WebSocketTransport = class {
+  /** @internal */
   carriesReadConcern = true;
   ws = null;
   url;
@@ -1090,6 +1121,7 @@ var WebSocketTransport = class {
     this.headers = options?.headers;
     this.pending = new PendingRequests(this.requestTimeout);
   }
+  /** Sends a read and returns its rows. */
   async query(sql, params, readConcern) {
     await this.ensureConnected();
     const id = this.nextId();
@@ -1102,6 +1134,7 @@ var WebSocketTransport = class {
     });
     return { rows: decodeTaggedValues(response.rows ?? []) };
   }
+  /** Sends one write. */
   async execute(sql, params) {
     await this.ensureConnected();
     const id = this.nextId();
@@ -1112,6 +1145,7 @@ var WebSocketTransport = class {
       params: encodeTaggedValues(params)
     });
   }
+  /** Sends several statements the server runs in one transaction. */
   async transaction(statements) {
     await this.ensureConnected();
     const id = this.nextId();
@@ -1124,6 +1158,7 @@ var WebSocketTransport = class {
       }))
     });
   }
+  /** Sends one statement over many parameter sets, which the server runs in one transaction. */
   async batch(sql, paramsBatch, writeConcern) {
     await this.ensureConnected();
     const id = this.nextId();
@@ -1135,6 +1170,7 @@ var WebSocketTransport = class {
       ...writeConcern ? { writeConcern } : {}
     });
   }
+  /** Sends a bulk load, which the server runs at relaxed durability. */
   async load(sql, paramsBatch, durability, checkpoint) {
     await this.ensureConnected();
     const id = this.nextId();
@@ -1147,6 +1183,7 @@ var WebSocketTransport = class {
       ...checkpoint !== void 0 ? { checkpoint } : {}
     });
   }
+  /** Runs a registered read by name and returns its rows. */
   async queryNamed(name, args, readConcern) {
     await this.ensureConnected();
     const id = this.nextId();
@@ -1159,6 +1196,7 @@ var WebSocketTransport = class {
     });
     return { rows: decodeTaggedValues(response.rows ?? []) };
   }
+  /** Runs a registered write by name. */
   async executeNamed(name, args, writeConcern) {
     await this.ensureConnected();
     const id = this.nextId();
@@ -1170,10 +1208,12 @@ var WebSocketTransport = class {
       ...writeConcern ? { writeConcern } : {}
     });
   }
+  /** Opens a live query on a registered read and delivers its updates to the handlers. */
   async liveSubscribe(name, args, handlers, registryDigest) {
     await this.ensureConnected();
     return this.liveQueries.open(this.nextId(), name, args, handlers, registryDigest);
   }
+  /** Opens a change subscription on a watched table. */
   async subscribe(table, filter, callback, options) {
     await this.ensureConnected();
     const id = this.nextId();
@@ -1221,11 +1261,13 @@ var WebSocketTransport = class {
       this.ws.send(JSON.stringify({ type: "unsubscribe", id }));
     }
   }
+  /** @internal */
   async ack(deviceId, seq) {
     await this.ensureConnected();
     const id = this.nextId();
     return this.request({ type: "ack", id, deviceId, seq: seq.toString() });
   }
+  /** Closes the transport and every subscription running on it. */
   close() {
     this.closed = true;
     this.cancelReconnect();

package/dist/{chunk-OQVZBEBY.mjs → chunk-XF2HH5E6.mjs}

@@ -1,70 +1,13 @@
-import { IDENTIFIER_RE, selectCountTableRows, computeChecksum, canonicaliseForChecksum, selectUserSchemaObjects, validateDdlSafety, selectUserTableNames, referencedTables } from './chunk-NVQS53NT.mjs';
-import { ReplicationError } from './chunk-5NOIGN5Y.mjs';
-import { INTERNAL_TABLE_PREFIX } from './chunk-D7LAYTKN.mjs';
+import { IDENTIFIER_RE, selectCountTableRows, canonicaliseForChecksum, selectUserSchemaObjects, validateDdlSafety, selectUserTableNames, referencedTables } from './chunk-7FQRQH5Z.mjs';
+import { ReplicationError } from './chunk-2QLXDHAP.mjs';
+import { INTERNAL_TABLE_PREFIX } from './chunk-7R4ER4FB.mjs';
 import { createHash } from 'crypto';
 
 var DumpOps = class {
-  constructor(conn, localNodeId, hlc, pkResolver) {
+  constructor(conn, pkResolver) {
     this.conn = conn;
-    this.localNodeId = localNodeId;
-    this.hlc = hlc;
     this.pkResolver = pkResolver;
   }
-  async *dumpTable(table, batchSize) {
-    if (!IDENTIFIER_RE.test(table)) {
-      throw new ReplicationError(`Invalid table name: ${table}`);
-    }
-    const total = await selectCountTableRows(this.conn, table);
-    if (total === 0) return;
-    const pkColumns = await this.pkResolver.forTable(table);
-    let offset = 0;
-    let batchNum = 0;
-    const needsRowid = pkColumns.length === 1 && pkColumns[0] === "rowid";
-    while (offset < total) {
-      const selectSql = needsRowid ? `SELECT rowid, * FROM "${table}" LIMIT ? OFFSET ?` : `SELECT * FROM "${table}" LIMIT ? OFFSET ?`;
-      const selectStmt = await this.conn.prepare(selectSql);
-      const rows = await selectStmt.all(batchSize, offset);
-      if (rows.length === 0) break;
-      const changes = [];
-      const hlcValue = this.hlc.now();
-      for (const row of rows) {
-        const primaryKey = {};
-        for (const col of pkColumns) {
-          if (col in row) {
-            primaryKey[col] = row[col];
-          }
-        }
-        const rowId = pkColumns.map((col) => String(row[col] ?? "")).join("-");
-        changes.push({
-          table,
-          operation: "insert",
-          rowId,
-          primaryKey,
-          hlc: hlcValue,
-          txId: `dump-${table}-${batchNum}`,
-          nodeId: this.localNodeId,
-          newData: row,
-          oldData: null
-        });
-      }
-      const checksum = computeChecksum(changes);
-      const dumpEpoch = BigInt(Date.now()) * 1000000n;
-      const fromSeq = dumpEpoch + BigInt(offset);
-      const toSeq = dumpEpoch + BigInt(offset + rows.length - 1);
-      const dumpNodeId = `dump-${this.localNodeId}`;
-      yield {
-        sourceNodeId: dumpNodeId,
-        batchId: `dump-${table}-${batchNum}`,
-        fromSeq,
-        toSeq,
-        hlcRange: { min: hlcValue, max: hlcValue },
-        changes,
-        checksum
-      };
-      offset += rows.length;
-      batchNum += 1;
-    }
-  }
   dumpTableOnConnection(conn, table, batchSize, startAfter) {
     return dumpTablePages(conn, this.pkResolver, table, batchSize, startAfter);
   }