@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/client/index.mjs

@@ -1,5 +1,5 @@
-import { DatabaseClient, createEndpointTransport, toBaseUrl, DEFAULT_HTTP_REQUEST_TIMEOUT_MS, postJson, decodeTaggedValues, RemoteError, encodeTaggedValues, toWsUrl, STAGED_STREAM_CAPABILITY, verifyDeviceSyncCapabilities, unrefTimer, WebSocketTransport } from '../chunk-H237TXZW.mjs';
-export { HttpTransport, RemoteDatabase, RemoteError, RemoteLiveQuery, RemoteSubscriptionBuilderImpl, SQL_REFUSED_MESSAGE, ServerCapabilities, WebSocketTransport } from '../chunk-H237TXZW.mjs';
+import { DatabaseClient, createEndpointTransport, toBaseUrl, DEFAULT_HTTP_REQUEST_TIMEOUT_MS, postJson, decodeTaggedValues, RemoteError, encodeTaggedValues, STAGED_STREAM_CAPABILITY, verifyDeviceSyncCapabilities, unrefTimer, toWsUrl, WebSocketTransport } from '../chunk-WJ67DTD6.mjs';
+export { HttpTransport, RemoteDatabase, RemoteError, RemoteLiveQuery, RemoteSubscriptionBuilderImpl, SQL_REFUSED_MESSAGE, ServerCapabilities, WebSocketTransport } from '../chunk-WJ67DTD6.mjs';
 
 // src/core/sync/canonicalise.ts
 function canonicaliseForChecksum(value) {
@@ -74,7 +74,11 @@ var HLC = class _HLC {
     this.wallMs = 0;
     this.logical = 0;
   }
-  /** Generate a new HLC timestamp, advancing the clock. */
+  /**
+   * Generate a new HLC timestamp, advancing the clock.
+   *
+   * @internal
+   */
   now() {
     const physicalMs = Date.now();
     if (physicalMs > this.wallMs) {
@@ -88,7 +92,11 @@ var HLC = class _HLC {
     }
     return _HLC.encode(this.wallMs, this.logical, this.nodeId);
   }
-  /** Merge a remote HLC timestamp into the local clock and return the updated value. */
+  /**
+   * Merge a remote HLC timestamp into the local clock and return the updated value.
+   *
+   * @internal
+   */
   receive(remote) {
     const r = _HLC.decode(remote);
     const physicalMs = Date.now();
@@ -126,6 +134,14 @@ var HLC = class _HLC {
       nodeId: parts.slice(2).join("-")
     };
   }
+  /**
+   * Builds the string form of a clock reading, which sorts in the same order as the reading itself.
+   *
+   * @param wallMs - Wall-clock milliseconds since the Unix epoch.
+   * @param logical - Counter that orders events sharing one millisecond.
+   * @param nodeId - Identifier of the node taking the reading.
+   * @returns The encoded stamp.
+   */
   static encode(wallMs, logical, nodeId) {
     const wallHex = wallMs.toString(16).padStart(12, "0");
     const logicalHex = logical.toString(16).padStart(4, "0");
@@ -135,6 +151,12 @@ var HLC = class _HLC {
 
 // src/core/sync/conflict/lww.ts
 var LWWResolver = class {
+  /**
+   * Takes the incoming row when its stamp is higher, and keeps the local row otherwise.
+   *
+   * @param ctx - The local and incoming versions of one row.
+   * @returns Which version to write.
+   */
   resolve(ctx) {
     if (ctx.remoteChange.operation === "delete") {
       return { action: "accept_remote" };
@@ -163,6 +185,12 @@ var FieldMergeResolver = class {
   constructor(getColumnVersions) {
     this.getColumnVersions = getColumnVersions;
   }
+  /**
+   * Merges columns only one side changed, and settles overlapping columns by their per-column stamps.
+   *
+   * @param ctx - The local and incoming versions of one row.
+   * @returns Which version to write, or the merged row.
+   */
   async resolve(ctx) {
     const columnVersions = await this.getColumnVersions(ctx.table, ctx.rowId);
     if (columnVersions.size === 0) {
@@ -237,6 +265,12 @@ var PrimaryWinsResolver = class {
   constructor(primaryNodeId) {
     this.primaryNodeId = primaryNodeId;
   }
+  /**
+   * Takes the version authored by the configured primary node, and falls back to last-writer-wins otherwise.
+   *
+   * @param ctx - The local and incoming versions of one row.
+   * @returns Which version to write.
+   */
   resolve(ctx) {
     if (ctx.remoteChange.nodeId === this.primaryNodeId) {
       return { action: "accept_remote" };
@@ -266,9 +300,20 @@ var SirannonClient = class extends DatabaseClient {
     super(options);
     this.baseUrl = normaliseClientUrl(url);
   }
+  /**
+   * Builds the transport a database's requests travel over.
+   *
+   * @param databaseId - Identifier of the database.
+   * @returns A transport bound to that database.
+   */
   createTransport(databaseId) {
     return createEndpointTransport(this.settings, this.baseUrl, databaseId);
   }
+  /**
+   * Returns the address requests are sent to.
+   *
+   * @returns The server's base address.
+   */
   resolveServerUrl() {
     return this.baseUrl;
   }
@@ -875,7 +920,7 @@ var PushLoop = class {
     this.timer = null;
   }
   /**
-   * Empties the outbox before a snapshot replaces the database, so local work
+   * Empties the outbox before a snapshot replaces the database so that local work
    * reaches the server before the copy overwrites it. A schema refusal is
    * reconciled once; a device that still cannot push returns rather than
    * looping, leaving the snapshot to bring it back into line.
@@ -1007,13 +1052,75 @@ var ResyncScheduler = class {
   }
 };
 
-// src/client/sync-controller.ts
+// src/client/sync-controller-wiring.ts
 var DEFAULT_BATCH_SIZE = 100;
 var DEFAULT_PUSH_INTERVAL_MS = 1e3;
 var DEFAULT_ACK_INTERVAL_MS = 2e3;
 var DEFAULT_MAX_PUSH_RETRY_DELAY_MS = 3e4;
 var DEFAULT_SNAPSHOT_RETRY_DELAY_MS = 5e3;
 var DEFAULT_MAX_SNAPSHOT_RETRY_DELAY_MS = 3e5;
+function createSyncCollaborators(baseUrl, options, host) {
+  const isRunning = () => host.state() === "running";
+  const push = new PushLoop(
+    {
+      baseUrl,
+      databaseId: options.databaseId,
+      headers: options.headers,
+      requestTimeout: options.requestTimeout,
+      batchSize: options.batchSize ?? DEFAULT_BATCH_SIZE,
+      intervalMs: options.pushIntervalMs ?? DEFAULT_PUSH_INTERVAL_MS,
+      maxRetryDelayMs: options.maxPushRetryDelayMs ?? DEFAULT_MAX_PUSH_RETRY_DELAY_MS
+    },
+    {
+      isRunning,
+      port: () => host.port(),
+      schemaVersion: () => host.schemaVersion(),
+      reconcileSchema: () => host.reconcileSchema(),
+      recordError: (err) => host.recordError(err),
+      onDrained: () => host.clearError()
+    }
+  );
+  const pull = new PullStream(
+    {
+      wsBaseUrl: toWsUrl(baseUrl),
+      databaseId: options.databaseId,
+      tables: options.tables,
+      headers: options.headers,
+      ackIntervalMs: options.ackIntervalMs ?? DEFAULT_ACK_INTERVAL_MS,
+      requestTimeout: options.requestTimeout,
+      immediateAckAfterChanges: options.immediateAckAfterChanges,
+      resolver: options.resolver
+    },
+    {
+      isRunning,
+      port: () => host.port(),
+      onChange: options.onChange,
+      onResyncRequired: () => host.markResyncRequired(),
+      onApplyFailure: (err) => host.onApplyFailure(err),
+      onApplySuccess: () => host.onApplySuccess(),
+      recordError: (err) => host.recordError(err)
+    }
+  );
+  const resync = new ResyncScheduler(
+    {
+      autoResync: options.autoResync,
+      retryDelayMs: options.snapshotRetryDelayMs ?? DEFAULT_SNAPSHOT_RETRY_DELAY_MS,
+      maxRetryDelayMs: options.maxSnapshotRetryDelayMs ?? DEFAULT_MAX_SNAPSHOT_RETRY_DELAY_MS,
+      onResyncRequired: options.onResyncRequired,
+      onSnapshotComplete: options.onSnapshotComplete
+    },
+    {
+      isRunning,
+      isSnapshotting: () => host.state() === "snapshotting",
+      port: () => host.port(),
+      recordError: (err) => host.recordError(err),
+      download: () => host.download()
+    }
+  );
+  return { push, pull, resync };
+}
+
+// src/client/sync-controller.ts
 var SyncController = class {
   constructor(db, options) {
     this.db = db;
@@ -1021,69 +1128,25 @@ var SyncController = class {
     this.baseUrl = toBaseUrl(options.url);
     this.pushIntervalMs = options.pushIntervalMs ?? DEFAULT_PUSH_INTERVAL_MS;
     this.maxPushRetryDelayMs = options.maxPushRetryDelayMs ?? DEFAULT_MAX_PUSH_RETRY_DELAY_MS;
-    this.push = new PushLoop(
-      {
-        baseUrl: this.baseUrl,
-        databaseId: options.databaseId,
-        headers: options.headers,
-        requestTimeout: options.requestTimeout,
-        batchSize: options.batchSize ?? DEFAULT_BATCH_SIZE,
-        intervalMs: this.pushIntervalMs,
-        maxRetryDelayMs: this.maxPushRetryDelayMs
-      },
-      {
-        isRunning: () => this.state === "running",
-        port: () => this.port,
-        schemaVersion: () => this.schemaVersion ?? 0,
-        reconcileSchema: () => this.reconcileSchema(),
-        recordError: (err) => this.recordError(err),
-        onDrained: () => {
-          this.lastError = null;
-        }
-      }
-    );
-    this.pull = new PullStream(
-      {
-        wsBaseUrl: toWsUrl(this.baseUrl),
-        databaseId: options.databaseId,
-        tables: options.tables,
-        headers: options.headers,
-        ackIntervalMs: options.ackIntervalMs ?? DEFAULT_ACK_INTERVAL_MS,
-        requestTimeout: options.requestTimeout,
-        immediateAckAfterChanges: options.immediateAckAfterChanges,
-        resolver: options.resolver
+    const collaborators = createSyncCollaborators(this.baseUrl, options, {
+      state: () => this.state,
+      port: () => this.port,
+      schemaVersion: () => this.schemaVersion ?? 0,
+      reconcileSchema: () => this.reconcileSchema(),
+      recordError: (err) => this.recordError(err),
+      clearError: () => {
+        this.lastError = null;
       },
-      {
-        isRunning: () => this.state === "running",
-        port: () => this.port,
-        onChange: options.onChange,
-        onResyncRequired: () => this.markResyncRequired(),
-        onApplyFailure: (err) => this.handleApplyFailure(err),
-        onApplySuccess: () => {
-          this.consecutivePullFailures = 0;
-        },
-        recordError: (err) => this.recordError(err)
-      }
-    );
-    this.resync = new ResyncScheduler(
-      {
-        autoResync: options.autoResync,
-        retryDelayMs: options.snapshotRetryDelayMs ?? DEFAULT_SNAPSHOT_RETRY_DELAY_MS,
-        maxRetryDelayMs: options.maxSnapshotRetryDelayMs ?? DEFAULT_MAX_SNAPSHOT_RETRY_DELAY_MS,
-        onResyncRequired: options.onResyncRequired,
-        onSnapshotComplete: options.onSnapshotComplete
+      markResyncRequired: () => this.markResyncRequired(),
+      onApplyFailure: (err) => this.handleApplyFailure(err),
+      onApplySuccess: () => {
+        this.consecutivePullFailures = 0;
       },
-      {
-        isRunning: () => this.state === "running",
-        isSnapshotting: () => this.state === "snapshotting",
-        port: () => this.port,
-        recordError: (err) => this.recordError(err),
-        download: () => this.downloadSnapshot({
-          pageSize: options.snapshotPageSize,
-          onProgress: options.onSnapshotProgress
-        })
-      }
-    );
+      download: () => this.downloadSnapshot({ pageSize: options.snapshotPageSize, onProgress: options.onSnapshotProgress })
+    });
+    this.push = collaborators.push;
+    this.pull = collaborators.pull;
+    this.resync = collaborators.resync;
   }
   baseUrl;
   pushIntervalMs;
@@ -1099,6 +1162,9 @@ var SyncController = class {
   pullRetryTimer = null;
   consecutivePullFailures = 0;
   lastError = null;
+  /**
+   * Connects to the server and starts pushing and pulling changes.
+   */
   async start() {
     if (this.state === "running" || this.state === "starting") return;
     this.state = "starting";
@@ -1138,23 +1204,37 @@ var SyncController = class {
       this.resync.schedule();
     }
   }
+  /**
+   * Holds pushing and pulling without disconnecting.
+   */
   pause() {
     if (this.state !== "running") return;
     this.teardownStream();
     this.state = "paused";
     void this.pull.persist();
   }
+  /**
+   * Resumes pushing and pulling after a pause.
+   */
   async resume() {
     if (this.state !== "paused") return;
     this.state = "stopped";
     await this.start();
   }
+  /**
+   * Stops syncing and closes the connection to the server.
+   */
   async stop() {
     if (this.state === "stopped") return;
     this.teardownStream();
     this.state = "stopped";
     await this.pull.persist();
   }
+  /**
+   * Reports where this device stands against the server.
+   *
+   * @returns The device's state, cursors, pending push count, and last failure.
+   */
   async status() {
     const pendingPushCount = this.port ? await this.port.countOutboxPending(this.push.cursor) : 0;
     return {
@@ -1170,6 +1250,9 @@ var SyncController = class {
       lastError: this.lastError
     };
   }
+  /**
+   * Pushes local changes now instead of waiting for the next interval.
+   */
   triggerPush() {
     void this.push.drain();
   }
@@ -1211,6 +1294,11 @@ var SyncController = class {
     this.resync.markRequired();
     this.resync.schedule();
   }
+  /**
+   * Replaces the local database with a fresh copy from the server and resumes syncing from it.
+   *
+   * @param options - Page size and the progress callback for this download.
+   */
   async downloadSnapshot(options) {
     if (this.state === "snapshotting") {
       throw new Error("A snapshot download is already in progress");

package/dist/client/topology.d.ts

@@ -1,10 +1,11 @@
-import { g as ReadConcernLevel } from '../types-zhnRXrsb.js';
-import { T as Transport, D as DatabaseClient } from '../client-base-CLWmH5Ln.js';
-import { C as ClientOptions } from '../server-options-1JHu8pid.js';
-import '../types-CL6piSnD.js';
-import '../operation-registry-9DcvxcE5.js';
-import '../protocol-6KrSq2Hy.js';
-import '../types-C_D8IhpO.js';
+import { a as ReadConcernLevel } from '../query-types-DL3LtPvY.js';
+import { C as ClientOptions } from '../server-options-Dab_Jvd_.js';
+import { T as Transport, D as DatabaseClient } from '../client-base-CmZO0v3m.js';
+import '../operation-registry-hlbhqu7q.js';
+import '../types-CjhxcjhA.js';
+import '../types-rVZKnKN-.js';
+import '../types-BCejqzNA.js';
+import '../protocol-rqANt-9Q.js';
 
 interface TopologyRouting {
     _getReadEndpoint(databaseId?: string, readConcern?: ReadConcernLevel): Promise<string>;
@@ -16,14 +17,42 @@ interface TopologyRouting {
     _createTransportForEndpoint(url: string, databaseId: string): Transport;
 }
 
+/**
+ * @public
+ *
+ * Which nodes the client holds, how it finds the rest, and where it sends each read.
+ */
 interface TopologyAwareClientOptions extends ClientOptions {
+    /**
+     * Nodes the client starts from when it discovers the group through the coordinator.
+     */
     endpoints?: string[];
+    /**
+     * Address of the primary, for a group you list by hand.
+     */
     primary?: string;
+    /**
+     * Addresses of the replicas, for a group you list by hand.
+     */
     replicas?: string[];
+    /**
+     * Where reads go. Default: 'primary'.
+     */
     readPreference?: 'primary' | 'replica' | 'nearest';
+    /**
+     * Whether the client uses the nodes you listed or asks the group for them. Default: 'static'.
+     */
     discovery?: 'static' | 'coordinator';
+    /**
+     * Currency every read requires, which the client uses to choose a node.
+     */
     readConcern?: ReadConcernLevel;
 }
+/**
+ * @public
+ *
+ * Connects to a replication group rather than one server: it routes each read to a node that meets its read concern, and each write to the primary.
+ */
 declare class TopologyAwareClient extends DatabaseClient implements TopologyRouting {
     private readonly baseUrl;
     private readonly primaryUrl;
@@ -39,15 +68,34 @@ declare class TopologyAwareClient extends DatabaseClient implements TopologyRout
     private latencyMeasuring;
     private readonly removedReplicas;
     constructor(options: TopologyAwareClientOptions);
+    /**
+     * Builds the routing transport a database's requests travel over.
+     *
+     * @param databaseId - Identifier of the database.
+     * @returns A transport that picks a node per request.
+     */
     protected createTransport(databaseId: string): Transport;
+    /** @internal */
     _createTransportForEndpoint(url: string, databaseId: string): Transport;
+    /**
+     * Returns the address writes are sent to, which is the current primary.
+     *
+     * @param databaseId - Identifier of the database.
+     * @returns Address of the node that accepts writes.
+     */
     protected resolveServerUrl(databaseId: string): Promise<string>;
+    /** @internal */
     _getReadEndpoint(databaseId?: string, readConcern?: ReadConcernLevel): Promise<string>;
     private routedReadEndpoint;
+    /** @internal */
     _getWriteEndpoint(databaseId?: string): Promise<string>;
+    /** @internal */
     _getReadConcern(): ReadConcernLevel | undefined;
+    /** @internal */
     _usesCoordinatorDiscovery(): boolean;
+    /** @internal */
     _removeReplica(url: string): void;
+    /** @internal */
     _refreshClusterRouting(databaseId: string): Promise<void>;
     private fetchClusterRouting;
     private ensureClusterRouting;

package/dist/client/topology.mjs

@@ -1,4 +1,4 @@
-import { DatabaseClient, toBaseUrl, createEndpointTransport, RemoteError, toServerBaseUrl, unrefTimer } from '../chunk-H237TXZW.mjs';
+import { DatabaseClient, toBaseUrl, createEndpointTransport, RemoteError, toServerBaseUrl, unrefTimer } from '../chunk-WJ67DTD6.mjs';
 
 // src/client/cluster-routing.ts
 function clusterRoutingFingerprint(state) {
@@ -484,6 +484,12 @@ var TopologyAwareClient = class extends DatabaseClient {
     this.starterEndpoints = (options.endpoints ?? []).map(toBaseUrl);
     this.baseUrl = this.primaryUrl ?? this.replicaUrls[0] ?? this.starterEndpoints[0] ?? "";
   }
+  /**
+   * Builds the routing transport a database's requests travel over.
+   *
+   * @param databaseId - Identifier of the database.
+   * @returns A transport that picks a node per request.
+   */
   createTransport(databaseId) {
     const transport = new TopologyAwareTransport(
       databaseId,
@@ -493,12 +499,20 @@ var TopologyAwareClient = class extends DatabaseClient {
     this.topologyTransports.set(databaseId, transport);
     return transport;
   }
+  /** @internal */
   _createTransportForEndpoint(url, databaseId) {
     return createEndpointTransport(this.settings, url, databaseId);
   }
+  /**
+   * Returns the address writes are sent to, which is the current primary.
+   *
+   * @param databaseId - Identifier of the database.
+   * @returns Address of the node that accepts writes.
+   */
   async resolveServerUrl(databaseId) {
     return this._getWriteEndpoint(databaseId);
   }
+  /** @internal */
   async _getReadEndpoint(databaseId, readConcern) {
     if (this.discovery === "coordinator" && databaseId) {
       return this.routedReadEndpoint(databaseId, readConcern);
@@ -541,6 +555,7 @@ var TopologyAwareClient = class extends DatabaseClient {
     if (localReadable) return localReadable.url;
     throw new RemoteError("ROUTING_ERROR", "No usable read endpoint is available");
   }
+  /** @internal */
   async _getWriteEndpoint(databaseId) {
     if (this.discovery === "coordinator" && databaseId) {
       const routing = await this.ensureClusterRouting(databaseId);
@@ -551,15 +566,19 @@ var TopologyAwareClient = class extends DatabaseClient {
     }
     return this.primaryUrl ?? this.baseUrl;
   }
+  /** @internal */
   _getReadConcern() {
     return this.readConcern;
   }
+  /** @internal */
   _usesCoordinatorDiscovery() {
     return this.discovery === "coordinator";
   }
+  /** @internal */
   _removeReplica(url) {
     this.removedReplicas.add(url);
   }
+  /** @internal */
   async _refreshClusterRouting(databaseId) {
     const encodedId = encodeURIComponent(databaseId);
     for (const endpoint of this.clusterDiscoveryCandidates(databaseId)) {