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

package/dist/client/index.mjs

@@ -1,5 +1,5 @@
-import { DatabaseClient, createEndpointTransport, toBaseUrl, DEFAULT_HTTP_REQUEST_TIMEOUT_MS, postJson, decodeTaggedValues, RemoteError, invokeCallerCallback, encodeTaggedValues, assertWebSocketCredentials, STAGED_STREAM_CAPABILITY, verifyDeviceSyncCapabilities, unrefTimer, toWsUrl, WebSocketTransport } from '../chunk-6IYS4WLH.mjs';
-export { HttpTransport, RemoteDatabase, RemoteError, RemoteLiveQuery, RemoteSubscriptionBuilderImpl, SQL_REFUSED_MESSAGE, ServerCapabilities, WebSocketTransport } from '../chunk-6IYS4WLH.mjs';
+import { DatabaseClient, createEndpointTransport, toBaseUrl, DEFAULT_HTTP_REQUEST_TIMEOUT_MS, postJson, decodeTaggedValues, RemoteError, invokeCallerCallback, encodeTaggedValues, assertWebSocketCredentials, STAGED_STREAM_CAPABILITY, verifyDeviceSyncCapabilities, unrefTimer, toWsUrl, WebSocketTransport } from '../chunk-VO3ZWA2G.mjs';
+export { HttpTransport, RemoteDatabase, RemoteError, RemoteLiveQuery, RemoteSubscriptionBuilderImpl, SQL_REFUSED_MESSAGE, ServerCapabilities, WebSocketTransport } from '../chunk-VO3ZWA2G.mjs';
 
 // src/core/sync/canonicalise.ts
 function canonicaliseForChecksum(value) {
@@ -75,7 +75,7 @@ var HLC = class _HLC {
     this.logical = 0;
   }
   /**
-   * Generate a new HLC timestamp, advancing the clock.
+   * Returns a new timestamp and advances the clock.
    *
    * @internal
    */
@@ -93,7 +93,7 @@ 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.
+   * Merges a remote timestamp into the clock and returns the new local timestamp.
    *
    * @internal
    */
@@ -116,13 +116,13 @@ var HLC = class _HLC {
     }
     return _HLC.encode(this.wallMs, this.logical, this.nodeId);
   }
-  /** Lexicographic comparison of two encoded HLC strings. Returns -1, 0, or 1. */
+  /** Compares two encoded timestamps as strings and returns -1, 0, or 1. */
   static compare(a, b) {
     if (a < b) return -1;
     if (a > b) return 1;
     return 0;
   }
-  /** Parse an encoded HLC string into its wall-clock, logical, and nodeId components. */
+  /** Parses an encoded timestamp into its wall-clock, logical, and node ID parts. */
   static decode(hlc) {
     const parts = hlc.split("-");
     if (parts.length < 3) {
@@ -135,11 +135,11 @@ var HLC = class _HLC {
     };
   }
   /**
-   * Builds the string form of a clock reading, which sorts in the same order as the reading itself.
+   * Returns the string form of a clock reading, padded so that string order matches clock order.
    *
-   * @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.
+   * @param wallMs - The wall-clock milliseconds since the Unix epoch.
+   * @param logical - The counter that orders events within one millisecond.
+   * @param nodeId - The ID of the node that takes the reading.
    * @returns The encoded stamp.
    */
   static encode(wallMs, logical, nodeId) {
@@ -152,7 +152,7 @@ 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.
+   * Returns the incoming row when its stamp is higher, and the local row otherwise.
    *
    * @param ctx - The local and incoming versions of one row.
    * @returns Which version to write.
@@ -186,10 +186,10 @@ var FieldMergeResolver = class {
     this.getColumnVersions = getColumnVersions;
   }
   /**
-   * Merges columns only one side changed, and settles overlapping columns by their per-column stamps.
+   * Returns the resolution for one conflicting row, merging changes to different columns and settling each column that both sides changed by its per-column stamp.
    *
    * @param ctx - The local and incoming versions of one row.
-   * @returns Which version to write, or the merged row.
+   * @returns The version to keep, or the merged row.
    */
   async resolve(ctx) {
     const columnVersions = await this.getColumnVersions(ctx.table, ctx.rowId);
@@ -266,7 +266,7 @@ var PrimaryWinsResolver = class {
     this.primaryNodeId = primaryNodeId;
   }
   /**
-   * Takes the version authored by the configured primary node, and falls back to last-writer-wins otherwise.
+   * Returns the version that the primary node wrote, or the last-writer-wins result when neither version comes from the primary.
    *
    * @param ctx - The local and incoming versions of one row.
    * @returns Which version to write.
@@ -301,7 +301,7 @@ var SirannonClient = class extends DatabaseClient {
     this.baseUrl = normaliseClientUrl(url);
   }
   /**
-   * Builds the transport a database's requests travel over.
+   * Builds the transport that sends one database's requests.
    *
    * @param databaseId - Identifier of the database.
    * @returns A transport bound to that database.
@@ -310,7 +310,7 @@ var SirannonClient = class extends DatabaseClient {
     return createEndpointTransport(this.settings, this.baseUrl, databaseId);
   }
   /**
-   * Returns the address requests are sent to.
+   * Returns the address that this client sends requests to.
    *
    * @returns The server's base address.
    */
@@ -478,6 +478,13 @@ function validatePage(raw) {
   }
   return record;
 }
+async function snapshotGateOpen(port) {
+  try {
+    return !await port.snapshotLoadPending();
+  } catch {
+    return false;
+  }
+}
 async function downloadDatabaseSnapshot(port, options) {
   const baseUrl = toBaseUrl(options.url);
   const encodedId = encodeURIComponent(options.databaseId);
@@ -654,6 +661,29 @@ async function syncDeviceMigrations(db, options) {
   };
 }
 
+// src/client/network-signal.ts
+function onlineEventTarget() {
+  const candidate = globalThis;
+  if (typeof candidate.addEventListener !== "function" || typeof candidate.removeEventListener !== "function") {
+    return null;
+  }
+  return candidate;
+}
+function deviceNetworkSignal() {
+  return {
+    reportsOffline: () => globalThis.navigator?.onLine === false,
+    watchOnline(onOnline) {
+      const target = onlineEventTarget();
+      if (target === null) return () => {
+      };
+      const listener = () => onOnline();
+      const removeEventListener = target.removeEventListener.bind(target);
+      target.addEventListener("online", listener);
+      return () => removeEventListener("online", listener);
+    }
+  };
+}
+
 // src/client/sync-pull-stream.ts
 var DEFAULT_IMMEDIATE_ACK_AFTER_CHANGES = 500;
 var STAGE_BATCH_EVENTS = 500;
@@ -898,6 +928,66 @@ async function pushSyncBatch(baseUrl, databaseId, batch, headers, timeoutMs, sch
   return { applied: result.applied, skipped: result.skipped, conflicts: result.conflicts };
 }
 
+// src/client/sync-reconnect.ts
+function jitteredBackoff(baseMs, attempt, maxMs, random = Math.random) {
+  const ceiling = Math.min(baseMs * 2 ** attempt, maxMs);
+  return Math.round(ceiling / 2 + random() * (ceiling / 2));
+}
+var PullReconnector = class {
+  constructor(config, hooks) {
+    this.config = config;
+    this.hooks = hooks;
+  }
+  timer = null;
+  heldForNetwork = false;
+  failures = 0;
+  stopWatching = null;
+  /** Begins listening for the network's return. */
+  start() {
+    if (this.stopWatching !== null) return;
+    this.stopWatching = this.config.network.watchOnline(() => this.handleOnline());
+  }
+  /** Clears any pending retry and stops listening for the network. */
+  stop() {
+    this.clearTimer();
+    this.heldForNetwork = false;
+    this.stopWatching?.();
+    this.stopWatching = null;
+  }
+  /** Records that the pull connection works, so that the next failure waits the shortest time again. */
+  reset() {
+    this.failures = 0;
+  }
+  /** Schedules one reopen, unless one is already pending or held for the network. */
+  schedule() {
+    if (this.timer !== null || this.heldForNetwork) return;
+    const delay = jitteredBackoff(this.config.baseDelayMs, this.failures, this.config.maxDelayMs);
+    this.failures += 1;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      if (this.config.network.reportsOffline()) {
+        this.heldForNetwork = true;
+        return;
+      }
+      this.hooks.reopen();
+    }, delay);
+    unrefTimer(this.timer);
+  }
+  handleOnline() {
+    this.hooks.onOnline();
+    if (this.timer === null && !this.heldForNetwork) return;
+    this.clearTimer();
+    this.heldForNetwork = false;
+    this.failures = 0;
+    this.hooks.reopen();
+  }
+  clearTimer() {
+    if (this.timer === null) return;
+    clearTimeout(this.timer);
+    this.timer = null;
+  }
+};
+
 // src/client/sync-push-loop.ts
 var PushLoop = class {
   constructor(config, hooks) {
@@ -922,10 +1012,11 @@ var PushLoop = class {
     this.timer = null;
   }
   /**
-   * 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.
+   * Pushes every change in the outbox before a snapshot download replaces the
+   * database, so that the server receives local changes before the download
+   * overwrites them. After a `MIGRATION_REQUIRED` refusal, it reconciles migrations
+   * once, and when the device still cannot push, it returns so that the snapshot
+   * brings the device's schema up to date.
    */
   async drainFully(port) {
     let retriedAfterMigration = false;
@@ -942,10 +1033,15 @@ var PushLoop = class {
       }
     }
   }
+  retryNow() {
+    this.consecutiveFailures = 0;
+    this.nextAttemptAt = 0;
+    void this.drain();
+  }
   async drain() {
     const port = this.hooks.port();
     if (this.pushing || !this.hooks.isRunning() || port === null) return;
-    if (Date.now() < this.nextAttemptAt) return;
+    if (Date.now() < this.nextAttemptAt || this.config.network.reportsOffline()) return;
     this.pushing = true;
     try {
       while (this.hooks.isRunning()) {
@@ -964,7 +1060,7 @@ var PushLoop = class {
   async handleFailure(err) {
     this.hooks.recordError(err);
     this.consecutiveFailures += 1;
-    const delay = Math.min(this.config.intervalMs * 2 ** this.consecutiveFailures, this.config.maxRetryDelayMs);
+    const delay = jitteredBackoff(this.config.intervalMs, this.consecutiveFailures, this.config.maxRetryDelayMs);
     this.nextAttemptAt = Date.now() + delay;
     if (!(err instanceof RemoteError) || err.code !== "MIGRATION_REQUIRED" || !this.hooks.isRunning()) return;
     try {
@@ -1059,7 +1155,7 @@ 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) {
+function createSyncCollaborators(baseUrl, options, host, network) {
   const isRunning = () => host.state() === "running";
   const push = new PushLoop(
     {
@@ -1069,7 +1165,8 @@ function createSyncCollaborators(baseUrl, options, host) {
       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
+      maxRetryDelayMs: options.maxPushRetryDelayMs ?? DEFAULT_MAX_PUSH_RETRY_DELAY_MS,
+      network
     },
     {
       isRunning,
@@ -1135,7 +1232,7 @@ var SyncStatusNotifier = class {
   countTimer = null;
   lastCountAt = 0;
   /**
-   * Captures the controller's status now and delivers it on a microtask.
+   * Captures the controller's status now and passes it to the listener on a microtask.
    */
   notify() {
     if (this.listener === void 0) return;
@@ -1188,52 +1285,63 @@ var SyncStatusNotifier = class {
 };
 
 // src/client/sync-controller.ts
+var SERVER_REFUSES_DEVICE_SYNC_CODES = /* @__PURE__ */ new Set(["SYNC_UNSUPPORTED", "DEVICE_SYNC_NOT_ACCEPTED"]);
+var SERVER_UNREACHABLE_CODES = /* @__PURE__ */ new Set(["CONNECTION_ERROR", "TIMEOUT"]);
 var SyncController = class {
   constructor(db, options) {
     this.db = db;
     this.options = options;
     this.baseUrl = toBaseUrl(options.url);
-    this.pushIntervalMs = options.pushIntervalMs ?? DEFAULT_PUSH_INTERVAL_MS;
-    this.maxPushRetryDelayMs = options.maxPushRetryDelayMs ?? DEFAULT_MAX_PUSH_RETRY_DELAY_MS;
     assertWebSocketCredentials(options.headers, options.webSocketProtocols);
+    const network = deviceNetworkSignal();
     this.statusChanges = new SyncStatusNotifier(
       options.onStatusChange,
       () => this.captureStatus(),
       () => this.refreshOutboxCount()
     );
-    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.setError(null),
-      markResyncRequired: () => this.markResyncRequired(),
-      onApplyFailure: (err) => this.handleApplyFailure(err),
-      onApplySuccess: () => {
-        this.consecutivePullFailures = 0;
-        this.statusChanges.notify();
+    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.setError(null),
+        markResyncRequired: () => this.markResyncRequired(),
+        onApplyFailure: (err) => this.handleApplyFailure(err),
+        onApplySuccess: () => {
+          this.reconnect.reset();
+          this.statusChanges.notify();
+        },
+        download: () => this.downloadSnapshot({ pageSize: options.snapshotPageSize, onProgress: options.onSnapshotProgress })
       },
-      download: () => this.downloadSnapshot({ pageSize: options.snapshotPageSize, onProgress: options.onSnapshotProgress })
-    });
+      network
+    );
     this.push = collaborators.push;
     this.pull = collaborators.pull;
     this.resync = collaborators.resync;
+    this.reconnect = new PullReconnector(
+      {
+        baseDelayMs: options.pushIntervalMs ?? DEFAULT_PUSH_INTERVAL_MS,
+        maxDelayMs: options.maxPushRetryDelayMs ?? DEFAULT_MAX_PUSH_RETRY_DELAY_MS,
+        network
+      },
+      { reopen: () => void this.reopenPull(), onOnline: () => this.push.retryNow() }
+    );
   }
   baseUrl;
-  pushIntervalMs;
-  maxPushRetryDelayMs;
   pull;
   push;
   resync;
+  reconnect;
   statusChanges;
   port = null;
   deviceId = null;
   capabilities = null;
   schemaVersion = null;
   syncState = "stopped";
-  pullRetryTimer = null;
-  consecutivePullFailures = 0;
   pendingPushCount = 0;
   lastError = null;
   get state() {
@@ -1250,6 +1358,13 @@ var SyncController = class {
   }
   /**
    * Connects to the server and starts pushing and pulling changes.
+   *
+   * When the server is unreachable, the promise still resolves, `status()` reports `running` with the failure in
+   * `lastError`, and the controller retries the connection with growing waits. It makes no attempt while the device
+   * reports no network, and it retries at once when the network returns.
+   *
+   * @throws A `RemoteError` when the server refuses device sync, such as `DEVICE_SYNC_NOT_ACCEPTED`, `UNAUTHORIZED`, or
+   * `FORBIDDEN`.
    */
   async start() {
     if (this.state === "running" || this.state === "starting") return;
@@ -1276,8 +1391,12 @@ var SyncController = class {
         }
       }
       if (!this.resync.required) {
-        await this.openPull();
+        await this.openPull().catch((err) => {
+          if (!(err instanceof RemoteError) || !SERVER_UNREACHABLE_CODES.has(err.code)) throw err;
+          this.handleApplyFailure(err);
+        });
       }
+      this.reconnect.start();
       this.setState("running");
     } catch (err) {
       this.teardownStream();
@@ -1291,7 +1410,7 @@ var SyncController = class {
     }
   }
   /**
-   * Holds pushing and pulling without disconnecting.
+   * Pauses pushing and pulling and closes the pull connection until you call {@link SyncController.resume}.
    */
   pause() {
     if (this.state !== "running") return;
@@ -1317,7 +1436,7 @@ var SyncController = class {
     await this.pull.persist();
   }
   /**
-   * Reports where this device stands against the server.
+   * Returns this device's sync status, with the pending push count read fresh from the outbox.
    *
    * @returns The device's state, cursors, pending push count, and last failure.
    */
@@ -1346,7 +1465,7 @@ var SyncController = class {
     return changed;
   }
   /**
-   * Pushes local changes now instead of waiting for the next interval.
+   * Pushes local changes now, ahead of the next push interval.
    */
   triggerPush() {
     void this.push.drain();
@@ -1360,7 +1479,7 @@ var SyncController = class {
         requestTimeoutMs: this.options.requestTimeout
       });
     } catch (err) {
-      if (err instanceof RemoteError && err.code === "SYNC_UNSUPPORTED") throw err;
+      if (err instanceof RemoteError && SERVER_REFUSES_DEVICE_SYNC_CODES.has(err.code)) throw err;
       this.recordError(err);
     }
   }
@@ -1426,7 +1545,7 @@ var SyncController = class {
       const failure = describeError(err);
       this.setError(failure);
       this.resync.recordFailure();
-      const databaseUsable = await this.snapshotGateOpen(port);
+      const databaseUsable = await snapshotGateOpen(port);
       this.setState("stopped");
       try {
         await this.start();
@@ -1443,34 +1562,13 @@ var SyncController = class {
       this.resync.complete({ ok: true, error: null, databaseUsable: true, retrying: false });
     }
   }
-  /**
-   * Answers whether the local database serves reads and writes again. A failure
-   * before the wipe begins leaves it intact, while one after it leaves every
-   * statement refused with `SNAPSHOT_IN_PROGRESS` until a later copy succeeds,
-   * so the application learns which of the two it is rather than assuming.
-   */
-  async snapshotGateOpen(port) {
-    try {
-      return !await port.snapshotLoadPending();
-    } catch {
-      return false;
-    }
-  }
   recordError(err) {
     this.setError(describeError(err));
   }
   handleApplyFailure(err) {
     this.recordError(err);
     this.pull.teardown();
-    const live = this.state === "running" || this.state === "starting";
-    if (!live || this.pullRetryTimer !== null) return;
-    const delay = Math.min(this.pushIntervalMs * 2 ** this.consecutivePullFailures, this.maxPushRetryDelayMs);
-    this.consecutivePullFailures += 1;
-    this.pullRetryTimer = setTimeout(() => {
-      this.pullRetryTimer = null;
-      void this.reopenPull();
-    }, delay);
-    unrefTimer(this.pullRetryTimer);
+    if (this.state === "running" || this.state === "starting") this.reconnect.schedule();
   }
   async reopenPull() {
     if (this.state !== "running" || this.deviceId === null || this.resync.required) return;
@@ -1481,11 +1579,11 @@ var SyncController = class {
     }
   }
   /**
-   * Opens the pull subscription, reconciling migrations when the server refuses
-   * it because this device is behind. A device that only reads never pushes, so
-   * the subscribe refusal is the sole point at which it can learn that the
-   * server has migrated; without this it would retry the same refused
-   * subscription forever and silently receive nothing.
+   * Opens the pull subscription, and reconciles migrations when the server refuses
+   * it with `MIGRATION_REQUIRED` because this device's schema is behind. A device
+   * that only reads never pushes, so the refused subscription is the only signal
+   * that the server has migrated. Without this step, the controller would retry the
+   * same refused subscription indefinitely and the device would receive no changes.
    */
   async openPull() {
     const deviceId = this.deviceId;
@@ -1509,10 +1607,7 @@ var SyncController = class {
   teardownStream() {
     this.push.stop();
     this.resync.cancel();
-    if (this.pullRetryTimer !== null) {
-      clearTimeout(this.pullRetryTimer);
-      this.pullRetryTimer = null;
-    }
+    this.reconnect.stop();
     this.pull.teardown();
   }
 };

package/dist/client/topology.d.ts

@@ -1,73 +1,72 @@
-import { a as ReadConcernLevel } from '../query-types-p1liOP-b.js';
-import { C as ClientOptions } from '../server-options-Bj5iJnjx.js';
-import { T as Transport, D as DatabaseClient } from '../client-base-Cmd9EVme.js';
-import { H as ClusterStatusInfo } from '../types-DPSmjU54.js';
-import '../operation-registry-oiPuSYI6.js';
-import '../types-CjhxcjhA.js';
-import '../types-DTO4CYhW.js';
-import '../protocol-HI-nY8DD.js';
+import { a as ReadConcernLevel } from '../query-types-5B02ixH0.js';
+import { C as ClientOptions } from '../server-options-aYtCkefX.js';
+import { T as Transport, D as DatabaseClient } from '../client-base-BxTocU1x.js';
+import { H as ClusterStatusInfo } from '../types-Dc8oWlxj.js';
+import '../operation-registry-CGhNT-Sn.js';
+import '../types-DqODKeOq.js';
+import '../types-CEJG0eFS.js';
+import '../protocol-DFpNNsIT.js';
 
 interface TopologyRouting {
     _getReadEndpoint(databaseId?: string, readConcern?: ReadConcernLevel): Promise<string>;
     _getWriteEndpoint(databaseId?: string): Promise<string>;
     _getReadConcern(): ReadConcernLevel | undefined;
     _usesCoordinatorDiscovery(): boolean;
-    _removeReplica(url: string): void;
+    _setEndpointAside(url: string): void;
     _refreshClusterRouting(databaseId: string): Promise<void>;
     _createTransportForEndpoint(url: string, databaseId: string): Transport;
 }
 
 /**
- * Reads the body of `GET /db/{id}/cluster` into the status the server reported.
+ * Parses the body of `GET /db/{id}/cluster` and returns the cluster status that the server reports.
  *
- * The route answers with a decimal string for `primaryTerm`, so that a term beyond
- * the safe integer range survives JSON, and this returns it as a bigint. A caller
- * building a cluster view gets the health, the reason behind it, the node the group
- * names as primary, and the readable endpoints, each checked against the values the
- * engine reports.
+ * The route sends `primaryTerm` as a decimal string, so that JSON keeps a term beyond the
+ * safe integer range exact, and this function returns it as a bigint. It checks `health`
+ * and `healthReason` against the values that the engine can report, and checks the shape
+ * of the role, the current primary, and the read endpoints.
  *
  * @param data - The parsed JSON body of the response.
- * @param databaseId - The database the caller asked about.
- * @returns The status the server reported.
- * @throws A remote error with code `INVALID_RESPONSE` where the body is malformed or names another database.
+ * @param databaseId - The ID of the database that you asked about.
+ * @returns The cluster status that the server reports.
+ * @throws A `RemoteError` with code `INVALID_RESPONSE` when the body is malformed or its `databaseId` differs from `databaseId`.
  *
  * @public
  */
 declare function parseClusterStatus(data: unknown, databaseId: string): ClusterStatusInfo;
 
 /**
- * Which nodes the client holds, how it finds the rest, and where it sends each read.
+ * The nodes that the client starts with, how it discovers the rest, and where it sends each read.
  *
  * @public
  */
 interface TopologyAwareClientOptions extends ClientOptions {
     /**
-     * Nodes the client starts from when it discovers the group through the coordinator.
+     * The nodes that the client asks for the group's routing when it discovers the group through the coordinator.
      */
     endpoints?: string[];
     /**
-     * Address of the primary, for a group you list by hand.
+     * The address of the primary, for a group that you list by hand.
      */
     primary?: string;
     /**
-     * Addresses of the replicas, for a group you list by hand.
+     * The addresses of the replicas, for a group that you list by hand.
      */
     replicas?: string[];
     /**
-     * Where reads go. Default: 'primary'.
+     * Which kind of node the client sends each read to. Defaults to 'primary'.
      */
     readPreference?: 'primary' | 'replica' | 'nearest';
     /**
-     * Whether the client uses the nodes you listed or asks the group for them. Default: 'static'.
+     * Whether the client uses the nodes that you list or asks the group for them. Defaults to 'static'.
      */
     discovery?: 'static' | 'coordinator';
     /**
-     * Currency every read requires, which the client uses to choose a node.
+     * The read concern that every read requires, which the client uses to choose a node.
      */
     readConcern?: ReadConcernLevel;
 }
 /**
- * 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.
+ * Connects to a replication group, and routes each read to a node that meets its read concern and each write to the primary.
  *
  * @public
  */
@@ -84,19 +83,19 @@ declare class TopologyAwareClient extends DatabaseClient implements TopologyRout
     private latencies;
     private latencyMeasuredAt;
     private latencyMeasuring;
-    private readonly removedReplicas;
+    private readonly endpointsSetAside;
     constructor(options: TopologyAwareClientOptions);
     /**
-     * Builds the routing transport a database's requests travel over.
+     * Builds the routing transport that sends one database's requests.
      *
      * @param databaseId - Identifier of the database.
-     * @returns A transport that picks a node per request.
+     * @returns A transport that picks a node for each 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.
+     * Returns the address that the client sends writes to, which is the current primary.
      *
      * @param databaseId - Identifier of the database.
      * @returns Address of the node that accepts writes.
@@ -112,7 +111,8 @@ declare class TopologyAwareClient extends DatabaseClient implements TopologyRout
     /** @internal */
     _usesCoordinatorDiscovery(): boolean;
     /** @internal */
-    _removeReplica(url: string): void;
+    _setEndpointAside(url: string): void;
+    private isReachable;
     /** @internal */
     _refreshClusterRouting(databaseId: string): Promise<void>;
     private fetchClusterRouting;