@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/{chunk-6IYS4WLH.mjs → chunk-VO3ZWA2G.mjs}

@@ -1,6 +1,6 @@
 // src/client/types.ts
 var RemoteError = class extends Error {
-  /** Machine-readable code the server sent with the error. */
+  /** The machine-readable error code, from the server's error response or from the client. */
   code;
   constructor(code, message) {
     super(message);
@@ -62,13 +62,13 @@ var RemoteLiveQuery = class _RemoteLiveQuery {
     return query;
   }
   /**
-   * Returns the rows the query holds right now.
+   * Returns the query's current state, which is its status with either its rows or its error.
    */
   getState() {
     return this.state;
   }
   /**
-   * Calls back on each update and returns a function that stops the listener.
+   * Calls the listener with each update, and returns a function that removes it.
    *
    * @param listener - Receives each update.
    * @returns A function that removes the listener.
@@ -80,7 +80,7 @@ var RemoteLiveQuery = class _RemoteLiveQuery {
     };
   }
   /**
-   * Ends the query and releases its subscription.
+   * Ends the query and unsubscribes it from the server.
    */
   async close() {
     if (this.closed) return;
@@ -206,11 +206,11 @@ var RemoteDatabase = class {
     );
   }
   /**
-   * Execute multiple statements as a single atomic transaction.
-   * Returns an array of results, one per statement.
+   * Executes several statements as one atomic transaction and returns one result
+   * per statement.
    *
-   * 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.
+   * The client sends the whole list in one request, and the server commits or
+   * rolls it back as a unit, with no round trip between statements.
    */
   async transaction(statements) {
     await this.capabilities.assertSqlAccepted();
@@ -218,10 +218,10 @@ var RemoteDatabase = class {
     return response.results;
   }
   /**
-   * Run the same statement once per parameter set as a single atomic
-   * transaction that commits with one fsync. Returns one result per
-   * parameter set, in order. Use this for a burst of same-shape writes
-   * (an import, a bulk insert) that must all commit or all roll back.
+   * Executes the same statement once for each parameter set, in one atomic
+   * transaction that commits with one fsync, and returns one result per
+   * parameter set, in order. Use it for a burst of writes with the same shape,
+   * such as an import or a bulk insert, that must all commit or all roll back.
    */
   async batch(sql, paramsBatch, writeConcern) {
     await this.capabilities.assertSqlAccepted();
@@ -229,16 +229,16 @@ var RemoteDatabase = class {
     return response.results;
   }
   /**
-   * Load a whole dataset through the same statement, batching it into requests
-   * 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 RemoteDatabase.load} for anything larger than a single request:
-   * it finalises the load itself, so there is no checkpoint flag to forget.
+   * Loads a whole dataset through one statement in requests of `batchSize` rows,
+   * and asks the server to perform the fsyncing WAL checkpoint once, after the final
+   * batch. The server restores the configured durability after every batch, so an
+   * import that stops partway leaves the writer at its configured level. Use this
+   * in place of {@link RemoteDatabase.load} for anything larger than one request,
+   * because it sets the `checkpoint` flag itself.
    *
-   * 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.
+   * It accepts a synchronous or asynchronous iterable of parameter sets, so rows can
+   * stream from a file or the network while the client holds at most two batches in
+   * memory. It returns the total number of rows loaded and changes applied.
    *
    * ```ts
    * const summary = await db.loadAll(
@@ -288,25 +288,24 @@ var RemoteDatabase = class {
     return total;
   }
   /**
-   * 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 RemoteDatabase.loadAll} for a dataset that spans more
-   * than one request, since it finalises the load itself rather than relying on
-   * a `checkpoint` flag.
+   * Loads one batch of rows through one statement, while the server relaxes the
+   * writer's durability for this call and restores it before the call resolves.
+   * For a dataset that spans more than one request, use {@link RemoteDatabase.loadAll},
+   * which sets the `checkpoint` flag itself.
    *
-   * Returns the total rows loaded and changes applied. When splitting a dataset
-   * across many `load` calls by hand, pass `checkpoint: false` on every call
-   * but the last so the one fsyncing WAL checkpoint runs once at the end; the
-   * configured durability is restored after each call regardless.
+   * It returns the total number of rows loaded and changes applied. When you split
+   * a dataset across many `load` calls yourself, pass `checkpoint: false` on every
+   * call except the last, so that the server performs the fsyncing WAL checkpoint once
+   * at the end. The server restores the configured durability after each call.
    */
   async load(sql, paramsBatch, durability, checkpoint) {
     await this.capabilities.assertSqlAccepted();
     return this.transport.load(sql, paramsBatch, durability, checkpoint);
   }
   /**
-   * Start building a CDC subscription for the given table.
+   * Returns a builder for a change subscription on one table.
    * Chain `.filter()` to narrow the events, then call `.subscribe()`
-   * with a callback to begin receiving real-time change events.
+   * with a callback to start receiving change events.
    *
    * ```ts
    * const sub = await db
@@ -318,17 +317,15 @@ var RemoteDatabase = class {
    * 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.
+   * @param table - The name of the table.
+   * @returns A builder that you narrow with a filter and then subscribe to.
    */
   on(table) {
     return new RemoteSubscriptionBuilderImpl(table, this.transport);
   }
   /**
-   * Close the transport for this database. After calling `close()`,
-   * all pending requests are rejected and new calls will throw.
+   * Closes the transport for this database, so every later call throws.
+   * With the WebSocket transport, it also rejects every pending request.
    */
   close() {
     this.transport.close();
@@ -566,6 +563,12 @@ async function verifyDeviceSyncCapabilities(options) {
   }
   const announced = new Set(capabilities);
   const missing = REQUIRED_DEVICE_SYNC_CAPABILITIES.filter((name) => !announced.has(name));
+  if (missing.length === REQUIRED_DEVICE_SYNC_CAPABILITIES.length) {
+    throw new RemoteError(
+      "DEVICE_SYNC_NOT_ACCEPTED",
+      "The server keeps device sync off; the server has to set acceptDeviceSync before a device can sync."
+    );
+  }
   if (missing.length > 0) {
     throw new RemoteError(
       "SYNC_UNSUPPORTED",
@@ -652,13 +655,13 @@ var HttpTransport = class {
   async execute(sql, params) {
     return this.post("/execute", { sql, params: encodeTaggedValues(params) });
   }
-  /** Sends several statements the server runs in one transaction. */
+  /** Sends several statements that the server executes 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. */
+  /** Sends one statement with many parameter sets, which the server executes in one transaction. */
   async batch(sql, paramsBatch, writeConcern) {
     return this.post("/batch", {
       sql,
@@ -666,7 +669,7 @@ var HttpTransport = class {
       writeConcern
     });
   }
-  /** Sends a bulk load, which the server runs at relaxed durability. */
+  /** Sends a bulk load, which the server executes at relaxed durability. */
   async load(sql, paramsBatch, durability, checkpoint) {
     return this.post("/load", {
       sql,
@@ -675,7 +678,7 @@ var HttpTransport = class {
       checkpoint
     });
   }
-  /** Runs a registered read by name and returns its rows. */
+  /** Executes 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),
@@ -683,28 +686,28 @@ var HttpTransport = class {
     });
     return { rows: decodeTaggedValues(response.rows ?? []) };
   }
-  /** Runs a registered write by name. */
+  /** Executes 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. */
+  /** Throws a `RemoteError` with code `TRANSPORT_ERROR`, because live queries need the WebSocket transport. */
   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. */
+  /** Throws a `RemoteError` with code `TRANSPORT_ERROR`, because change subscriptions need the WebSocket transport. */
   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. */
+  /** Closes the transport, so every later request throws a `RemoteError` with code `TRANSPORT_ERROR`. */
   close() {
     this.closed = true;
   }
@@ -1139,6 +1142,66 @@ var PendingRequests = class {
   }
 };
 
+// src/client/transport/ws-request-frames.ts
+function encodedParams(params) {
+  return encodeTaggedValues(params);
+}
+function encodedArgs(args) {
+  return args === void 0 ? void 0 : encodeTaggedValues(args);
+}
+function queryFrame(id, sql, params, readConcern) {
+  return { type: "query", id, sql, params: encodedParams(params), ...readConcern ? { readConcern } : {} };
+}
+function executeFrame(id, sql, params) {
+  return { type: "execute", id, sql, params: encodedParams(params) };
+}
+function transactionFrame(id, statements) {
+  return {
+    type: "transaction",
+    id,
+    statements: statements.map((statement) => ({ sql: statement.sql, params: encodedParams(statement.params) }))
+  };
+}
+function batchFrame(id, sql, paramsBatch, writeConcern) {
+  return {
+    type: "batch",
+    id,
+    sql,
+    paramsBatch: paramsBatch.map((entry) => encodeTaggedValues(entry)),
+    ...writeConcern ? { writeConcern } : {}
+  };
+}
+function loadFrame(id, sql, paramsBatch, durability, checkpoint) {
+  return {
+    type: "load",
+    id,
+    sql,
+    paramsBatch: paramsBatch.map((entry) => encodeTaggedValues(entry)),
+    ...durability ? { durability } : {},
+    ...checkpoint !== void 0 ? { checkpoint } : {}
+  };
+}
+function namedQueryFrame(id, name, args, readConcern) {
+  const encoded = encodedArgs(args);
+  return {
+    type: "query",
+    id,
+    name,
+    ...encoded === void 0 ? {} : { args: encoded },
+    ...readConcern ? { readConcern } : {}
+  };
+}
+function namedExecuteFrame(id, name, args, writeConcern) {
+  const encoded = encodedArgs(args);
+  return {
+    type: "execute",
+    id,
+    name,
+    ...encoded === void 0 ? {} : { args: encoded },
+    ...writeConcern ? { writeConcern } : {}
+  };
+}
+
 // src/client/transport/ws.ts
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var WebSocketTransport = class {
@@ -1163,6 +1226,8 @@ var WebSocketTransport = class {
   closed = false;
   connectPromise = null;
   reconnectTimer = null;
+  subscriptionsRestored = true;
+  restorePromise = null;
   constructor(url, options) {
     this.url = url;
     this.autoReconnect = options?.autoReconnect ?? true;
@@ -1175,96 +1240,46 @@ var WebSocketTransport = class {
   /** Sends a read and returns its rows. */
   async query(sql, params, readConcern) {
     await this.ensureConnected();
-    const id = this.nextId();
-    const response = await this.request({
-      type: "query",
-      id,
-      sql,
-      params: encodeTaggedValues(params),
-      ...readConcern ? { readConcern } : {}
-    });
+    const response = await this.request(queryFrame(this.nextId(), sql, params, readConcern));
     return { rows: decodeTaggedValues(response.rows ?? []) };
   }
   /** Sends one write. */
   async execute(sql, params) {
     await this.ensureConnected();
-    const id = this.nextId();
-    return this.request({
-      type: "execute",
-      id,
-      sql,
-      params: encodeTaggedValues(params)
-    });
+    return this.request(executeFrame(this.nextId(), sql, params));
   }
-  /** Sends several statements the server runs in one transaction. */
+  /** Sends several statements that the server executes in one transaction. */
   async transaction(statements) {
     await this.ensureConnected();
-    const id = this.nextId();
-    return this.request({
-      type: "transaction",
-      id,
-      statements: statements.map((stmt) => ({
-        sql: stmt.sql,
-        params: encodeTaggedValues(stmt.params)
-      }))
-    });
+    return this.request(transactionFrame(this.nextId(), statements));
   }
-  /** Sends one statement over many parameter sets, which the server runs in one transaction. */
+  /** Sends one statement with many parameter sets, which the server executes in one transaction. */
   async batch(sql, paramsBatch, writeConcern) {
     await this.ensureConnected();
-    const id = this.nextId();
-    return this.request({
-      type: "batch",
-      id,
-      sql,
-      paramsBatch: paramsBatch.map((entry) => encodeTaggedValues(entry)),
-      ...writeConcern ? { writeConcern } : {}
-    });
+    return this.request(batchFrame(this.nextId(), sql, paramsBatch, writeConcern));
   }
-  /** Sends a bulk load, which the server runs at relaxed durability. */
+  /** Sends a bulk load, which the server executes at relaxed durability. */
   async load(sql, paramsBatch, durability, checkpoint) {
     await this.ensureConnected();
-    const id = this.nextId();
-    return this.request({
-      type: "load",
-      id,
-      sql,
-      paramsBatch: paramsBatch.map((entry) => encodeTaggedValues(entry)),
-      ...durability ? { durability } : {},
-      ...checkpoint !== void 0 ? { checkpoint } : {}
-    });
+    return this.request(loadFrame(this.nextId(), sql, paramsBatch, durability, checkpoint));
   }
-  /** Runs a registered read by name and returns its rows. */
+  /** Executes a registered read by name and returns its rows. */
   async queryNamed(name, args, readConcern) {
     await this.ensureConnected();
-    const id = this.nextId();
-    const response = await this.request({
-      type: "query",
-      id,
-      name,
-      ...args === void 0 ? {} : { args: encodeTaggedValues(args) },
-      ...readConcern ? { readConcern } : {}
-    });
+    const response = await this.request(namedQueryFrame(this.nextId(), name, args, readConcern));
     return { rows: decodeTaggedValues(response.rows ?? []) };
   }
-  /** Runs a registered write by name. */
+  /** Executes a registered write by name. */
   async executeNamed(name, args, writeConcern) {
     await this.ensureConnected();
-    const id = this.nextId();
-    return this.request({
-      type: "execute",
-      id,
-      name,
-      ...args === void 0 ? {} : { args: encodeTaggedValues(args) },
-      ...writeConcern ? { writeConcern } : {}
-    });
+    return this.request(namedExecuteFrame(this.nextId(), name, args, writeConcern));
   }
-  /** Opens a live query on a registered read and delivers its updates to the handlers. */
+  /** Opens a live query on a registered read and passes 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. */
+  /** Opens a change subscription on a table. */
   async subscribe(table, filter, callback, options) {
     await this.ensureConnected();
     const id = this.nextId();
@@ -1316,10 +1331,11 @@ var WebSocketTransport = class {
   /** @internal */
   async ack(deviceId, seq) {
     await this.ensureConnected();
+    await this.restoreSubscriptions();
     const id = this.nextId();
     return this.request({ type: "ack", id, deviceId, seq: seq.toString() });
   }
-  /** Closes the transport and every subscription running on it. */
+  /** Closes the transport and ends every subscription on it. */
   close() {
     this.closed = true;
     this.cancelReconnect();
@@ -1379,6 +1395,9 @@ var WebSocketTransport = class {
     this.pending.rejectAll(this.refusal ?? new RemoteError("CONNECTION_ERROR", "WebSocket disconnected"));
     this.liveQueries.markDisconnected();
     const restorable = this.activeSubscriptions.size + this.liveQueries.size;
+    if (restorable > 0) {
+      this.subscriptionsRestored = false;
+    }
     if (this.autoReconnect && !this.closed && this.refusal === null && restorable > 0) {
       this.scheduleReconnect();
     }
@@ -1392,7 +1411,7 @@ var WebSocketTransport = class {
       if (this.closed) return;
       try {
         await this.ensureConnected();
-        await this.resubscribeAll();
+        await this.restoreSubscriptions();
       } catch {
         if (!this.closed && this.refusal === null && this.activeSubscriptions.size + this.liveQueries.size > 0) {
           this.scheduleReconnect();
@@ -1400,7 +1419,15 @@ var WebSocketTransport = class {
       }
     }, this.reconnectInterval);
   }
+  restoreSubscriptions() {
+    if (this.subscriptionsRestored) return Promise.resolve();
+    this.restorePromise ??= this.resubscribeAll().finally(() => {
+      this.restorePromise = null;
+    });
+    return this.restorePromise;
+  }
   async resubscribeAll() {
+    this.subscriptionsRestored = true;
     const entries = [...this.activeSubscriptions.entries()];
     for (const [id, sub] of entries) {
       if (this.closed) break;
@@ -1467,9 +1494,9 @@ var DatabaseClient = class {
     this.settings = resolveTransportSettings(options);
   }
   /**
-   * Returns the handle a caller queries and writes one database through, opening it on the first call for that identifier.
+   * Returns the handle that you use to query and write one database, and opens it on the first call for that identifier.
    *
-   * @param id - Identifier the server registered the database under.
+   * @param id - The identifier under which the server registered the database.
    * @returns The database handle, which stays open until the caller closes it.
    */
   database(id) {
@@ -1495,7 +1522,7 @@ var DatabaseClient = class {
     );
   }
   /**
-   * Closes every database this client opened, which ends their transports and stops their subscriptions.
+   * Closes every database that this client opened, which closes their transports and stops their subscriptions.
    */
   close() {
     this.closed = true;

package/dist/chunk-WOMADPM4.mjs

@@ -0,0 +1,12 @@
+import { SirannonError } from './chunk-KINDFBQP.mjs';
+
+// src/core/optional-dependency.ts
+function optionalDependencyError(dependency, loadFailure) {
+  const reported = loadFailure instanceof Error ? loadFailure.message : String(loadFailure);
+  return new SirannonError(
+    `${dependency.neededBy} needs the '${dependency.packageName}' package, which this process could not load. Install it with \`${dependency.installCommand}\`, or fix the failure that the loader reported: ${reported}`,
+    dependency.code
+  );
+}
+
+export { optionalDependencyError };

package/dist/{chunk-OUSWVNWT.mjs → chunk-YCMB6GR4.mjs}

@@ -1,4 +1,4 @@
-import { SirannonError } from './chunk-PBRXXISQ.mjs';
+import { SirannonError } from './chunk-KINDFBQP.mjs';
 
 // src/core/driver/synchronous.ts
 var DEFAULT_SYNCHRONOUS = "normal";

package/dist/{chunk-YNTDOFTN.mjs → chunk-YW7IKQ7T.mjs}

@@ -1,4 +1,4 @@
-import { SirannonError } from './chunk-PBRXXISQ.mjs';
+import { SirannonError } from './chunk-KINDFBQP.mjs';
 
 // src/core/backup/chain-queries.ts
 function chainError(message) {