@larc-iu/plaid-client 0.2.0-alpha.12 → 0.2.0-alpha.14

package/index.d.ts

@@ -201,6 +201,7 @@ interface RelationsBundle {
   ): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
+  bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
 }
 
 interface SpanLayersBundle {
@@ -250,6 +251,7 @@ interface SpansBundle {
   update(spanId: string, value: any, auditMessage?: string): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
+  bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
   setMetadata(spanId: string, body: any, auditMessage?: string): Promise<any>;
   deleteMetadata(spanId: string, auditMessage?: string): Promise<any>;
   patchMetadata(spanId: string, body: any, auditMessage?: string): Promise<any>;
@@ -320,12 +322,26 @@ interface UserDataEntry {
   value?: any;
 }
 
+interface UserDataOptions {
+  prefix?: string;
+  pattern?: string;
+  includeValues?: boolean;
+}
+
 /** Private per-user key/value storage (owner or admin only; not audited). */
 interface UserDataBundle {
   list(
     userId: string,
-    opts?: { prefix?: string; includeValues?: boolean },
+    opts?: UserDataOptions & { pageSize?: number },
   ): Promise<UserDataEntry[]>;
+  listPage(
+    userId: string,
+    opts?: UserDataOptions & { limit?: number; cursor?: string },
+  ): Promise<Page<UserDataEntry>>;
+  iterPages(
+    userId: string,
+    opts?: UserDataOptions & { pageSize?: number },
+  ): AsyncGenerator<UserDataEntry[]>;
   get(userId: string, key: string): Promise<UserDataEntry & { value: any }>;
   put(
     userId: string,
@@ -568,6 +584,14 @@ interface AdminBundle {
     userId?: string;
   }): Promise<{ result: string }>;
   logs(opts?: {
+    limit?: number;
+    q?: string;
+    level?: string;
+    status?: string;
+    user?: string;
+    method?: string;
+  }): Promise<LiveLog>;
+  logFile(opts?: {
     lines?: number;
   }): Promise<{ file: string | null; lines: string[]; error?: string }>;
   userData(opts?: AdminUserDataOptions): Promise<AdminUserDataEntry[]>;
@@ -576,6 +600,71 @@ interface AdminBundle {
   ): Promise<Page<AdminUserDataEntry>>;
 }
 
+/** One HTTP request as the log buffer holds it. */
+interface LoggedRequest {
+  /** Epoch milliseconds. */
+  ts: number;
+  method: string;
+  path: string;
+  /** Query string with sensitive values replaced, or null. */
+  query: string | null;
+  /** Null when the handler threw before producing one. */
+  status: number | null;
+  ms: number;
+  /** Null for a request nobody was authenticated for. */
+  user: string | null;
+  ip: string | null;
+  /** Set when a named API token signed the request. */
+  token: string | null;
+  /** Exception class, when the handler threw. */
+  error: string | null;
+}
+
+/** One log event that was not a request. */
+interface LoggedEvent {
+  ts: number;
+  level: string;
+  ns: string;
+  message: string;
+  trace?: string;
+}
+
+/**
+ * The live log. Requests and events are buffered separately, so a burst of
+ * requests cannot evict an error.
+ */
+interface LiveLog {
+  requests: {
+    entries: LoggedRequest[];
+    /** How many passed the filters, which may exceed what `entries` holds. */
+    matched: number;
+    /** How many are buffered in total. */
+    held: number;
+    capacity: number;
+    stats: {
+      count: number;
+      failures: number;
+      serverErrors: number;
+      p50: number | null;
+      p95: number | null;
+      max: number | null;
+      perMinute: number | null;
+      oldest: number | null;
+      newest: number | null;
+    };
+  };
+  events: {
+    entries: LoggedEvent[];
+    matched: number;
+    held: number;
+    capacity: number;
+    /** Counts per level of what the search matched, before the level filter. */
+    byLevel: Record<string, number>;
+  };
+  /** Absolute path of the configured log file, or null when logging to stdout. */
+  file: string | null;
+}
+
 /** Narrowings for the cross-account private-data listing. */
 interface AdminUserDataOptions {
   /** Only keys starting with this literal head. */
@@ -692,10 +781,39 @@ interface TokenLayersBundle {
   ): Promise<any>;
 }
 
+/** Handle passed to a `documents.locked()` block. */
+export declare class DocumentLock {
+  readonly documentId: string;
+  /** The DocumentLockLost if the lock lapsed, else null. */
+  readonly lost: DocumentLockLost | null;
+  /** Throw if the lock lapsed; call it between steps that have not written. */
+  raiseIfLost(): void;
+}
+
+/** The lock a `documents.locked()` block was holding is no longer held. */
+export declare class DocumentLockLost extends Error {
+  readonly name: "DocumentLockLost";
+  readonly documentId: string;
+  readonly cause?: unknown;
+}
+
+/** The server's default document-lock window, in ms. */
+export const DOCUMENT_LOCK_TTL_MS: 60000;
+
 interface DocumentsBundle {
   checkLock(documentId: string, asOf?: string): Promise<any>;
   acquireLock(documentId: string, auditMessage?: string): Promise<any>;
   releaseLock(documentId: string, auditMessage?: string): Promise<any>;
+  /**
+   * Hold the document's lock for the length of `fn`, renewing it while `fn`
+   * runs and releasing it on the way out. Rejects with a 423 if another user
+   * holds it, and with DocumentLockLost if a renewal fails.
+   */
+  locked<T>(
+    documentId: string,
+    fn: (lock: DocumentLock) => T | Promise<T>,
+    options?: { keepAlive?: boolean },
+  ): Promise<T>;
   getMedia(documentId: string): Promise<ArrayBuffer>;
   uploadMedia(
     documentId: string,
@@ -953,6 +1071,7 @@ interface TokensBundle {
   ): Promise<any>;
   bulkCreate(body: any[], auditMessage?: string): Promise<{ ids: string[] }>;
   bulkDelete(body: any[], auditMessage?: string): Promise<void>;
+  bulkUpdate(body: any[], auditMessage?: string): Promise<{ count: number }>;
   split(tokenId: string, position: number, auditMessage?: string): Promise<any>;
   merge(
     tokenId: string,
@@ -1025,12 +1144,22 @@ export declare class PlaidClient {
   /** Fired once on HTTP 401 (see PlaidClientOptions.onAuthError). */
   onAuthError: ((error: Error) => void) | null;
 
-  // Batch control methods
+  // Batch control methods.
+  //
+  // Batch mode is one flag on the whole client, so it catches every write made
+  // while it is open, including writes made by code that knows nothing about
+  // the batch. Reads are never caught: every read method goes over the wire
+  // while a batch is open and is answered from the state the batch has not
+  // committed yet, so app chrome sharing a client with an importer keeps
+  // working. Neither are the calls that signal something out of band rather
+  // than write project data: stopping a service request, a service reporting
+  // its progress or result, taking and dropping a document lock, and the admin
+  // actions on the server itself.
   beginBatch(): void;
   submitBatch(): Promise<any[]>;
   abortBatch(): void;
   isBatchMode(): boolean;
-  /** Run `fn` with a batch open, then submit atomically (or abort if `fn` throws). Resolves to the results array. */
+  /** Run `fn` with a batch open, then submit atomically (or abort if `fn` throws). Resolves to the results array. Writes inside `fn` queue; reads go over the wire and see the pre-batch state. */
   batched(fn: () => void | Promise<void>): Promise<any[]>;
 
   // Strict mode methods

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larc-iu/plaid-client",
-  "version": "0.2.0-alpha.12",
+  "version": "0.2.0-alpha.14",
   "description": "JavaScript client for the Plaid annotation API",
   "type": "module",
   "repository": {

package/src/documentLock.js

@@ -0,0 +1,299 @@
+/**
+ * Keeping a document lock alive for as long as a `locked()` block runs.
+ *
+ * plaid-core expires a document lock about a minute after it was taken, and the
+ * holder's own writes are what renew it (`plaid.sql.operation` calls
+ * `refresh-locks!` on every write it accepts). That is the right rule for an
+ * editor, which writes as the person types. It is the wrong one for a service:
+ * a parser loads a model, reads the document, spends minutes in inference and
+ * only then writes, so for most of its run it holds nothing. The lock lapses in
+ * silence, a person's edit lands between the read the work was planned from and
+ * the write about to go out, and the write clobbers it.
+ *
+ * A `locked()` block therefore renews on a timer of its own. The renewal is a
+ * plain acquire: the server refreshes a lock whose holder asks for it again.
+ *
+ * The beat is unconditional rather than "only when no write has gone out
+ * recently". The request layer knows the method of a call but not which
+ * document it touched, so a write to some other document would count as a
+ * renewal here and would not be one. Two extra requests a minute is the whole
+ * cost.
+ *
+ * A renewal that fails means the block is no longer holding what it asked for,
+ * so it stops the run: the loss is recorded on the client and every later write
+ * throws `DocumentLockLost`. The guard sits in the request layer because the
+ * callers are services, and a check they have to remember to call is a check
+ * that is missing somewhere.
+ */
+
+/**
+ * How long plaid-core holds a document lock before it expires, in ms.
+ * `plaid.server.locks/default-lock-expiration-ms`. An operator can change it
+ * with `:plaid.server.locks/config :expiration-ms`, and a server publishes what
+ * it enforces as `lockExpirationMs` in `GET /info`. This is the last resort:
+ * what a live lock is renewed against is the `expiresAt` on the acquire
+ * response, which names the moment rather than the window.
+ */
+export const DOCUMENT_LOCK_TTL_MS = 60000;
+
+// Widest lock lifetime we will believe from a server response. Past this the
+// number is a clock skew between this machine and the server rather than a
+// configured window, and the documented default is the better guess.
+const MAX_BELIEVABLE_TTL_MS = 3600000;
+
+/**
+ * The lock a `documents.locked()` block was holding is no longer held.
+ *
+ * Thrown by the keep-alive when it cannot renew the lock, and then by the
+ * request layer on every write this client attempts, so work that has been
+ * running for minutes stops rather than writing over an edit that may have
+ * landed while the lock was gone.
+ */
+export class DocumentLockLost extends Error {
+  constructor(message, documentId, cause) {
+    super(message);
+    this.name = "DocumentLockLost";
+    this.documentId = documentId;
+    this.cause = cause;
+  }
+}
+
+/**
+ * How long a freshly taken lock lasts, from the server's own answer.
+ *
+ * `expiresAt` is the epoch-millisecond stamp the lock endpoints return.
+ * Comparing it against this machine's clock is the only way to learn a window
+ * an operator has retuned, and it is also the one place a clock skew can get
+ * in, so an answer outside a believable band falls back to the documented
+ * default rather than to a beat that never fires or fires constantly.
+ *
+ * @param {number|undefined} expiresAt
+ * @param {number} nowMs
+ * @param {number} [fallback]
+ * @returns {number}
+ */
+export function lockTtlMs(
+  expiresAt,
+  nowMs,
+  fallback = DOCUMENT_LOCK_TTL_MS,
+) {
+  if (typeof expiresAt === "number" && Number.isFinite(expiresAt)) {
+    const ttl = expiresAt - nowMs;
+    if (ttl > 0 && ttl <= MAX_BELIEVABLE_TTL_MS) return ttl;
+  }
+  return fallback;
+}
+
+/**
+ * Renews one document's lock until the block holding it exits.
+ *
+ * `refresh` is called with the document id and must reject on failure.
+ * `onLost` is called once, with the `DocumentLockLost`, when the lock can no
+ * longer be assumed.
+ *
+ * `clock` and `sleep` exist so the whole policy can be run on a fake clock:
+ * `sleep(delayMs)` resolves to true once the block has exited.
+ */
+export class LockKeeper {
+  constructor(
+    refresh,
+    documentId,
+    ttlMs,
+    { onLost = null, clock = Date.now, sleep = null } = {},
+  ) {
+    this._refresh = refresh;
+    this._documentId = documentId;
+    // A window under two seconds leaves no room for a retry; treat it as a
+    // misconfiguration and beat at the documented rate instead.
+    this._ttlMs = ttlMs >= 2000 ? ttlMs : DOCUMENT_LOCK_TTL_MS;
+    this._onLost = onLost;
+    this._clock = clock;
+    this._sleep = sleep || ((ms) => this._defaultSleep(ms));
+    this._stopped = false;
+    this._wake = null;
+    this._running = null;
+    /** The `DocumentLockLost` this keeper raised, or null. */
+    this.lost = null;
+  }
+
+  /**
+   * Time between renewals: half the window, so a renewal that fails has a
+   * second chance before the lock it is renewing expires.
+   */
+  get intervalMs() {
+    return Math.max(1000, this._ttlMs / 2);
+  }
+
+  /**
+   * Time before retrying a renewal that failed. A blip should not end a run
+   * that the server still considers the holder of.
+   */
+  get retryMs() {
+    return Math.max(500, this._ttlMs / 10);
+  }
+
+  _defaultSleep(ms) {
+    if (this._stopped) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this._wake = null;
+        resolve(this._stopped);
+      }, ms);
+      // Never hold a Node process open on the beat alone.
+      if (timer && typeof timer.unref === "function") timer.unref();
+      this._wake = () => {
+        clearTimeout(timer);
+        this._wake = null;
+        resolve(true);
+      };
+    });
+  }
+
+  /** The beat. Resolves when the block exits or the lock is lost. */
+  async run() {
+    let deadline = this._clock() + this._ttlMs;
+    let delay = this.intervalMs;
+    while (!(await this._sleep(delay))) {
+      try {
+        await this._refresh(this._documentId);
+      } catch (error) {
+        // 423 is definitive: somebody else holds the document now, so ours had
+        // already expired. Anything else may be a blip, and is only fatal once
+        // the lock we are renewing has actually run out.
+        if (error?.status === 423 || this._clock() >= deadline) {
+          this._fail(error);
+          return;
+        }
+        delay = this.retryMs;
+        continue;
+      }
+      deadline = this._clock() + this._ttlMs;
+      delay = this.intervalMs;
+    }
+  }
+
+  start() {
+    this._running = this.run();
+    // Nothing awaits the beat: a failure inside it is reported through onLost,
+    // not through this promise.
+    this._running.catch(() => {});
+    return this._running;
+  }
+
+  stop() {
+    this._stopped = true;
+    if (this._wake) this._wake();
+  }
+
+  _fail(error) {
+    this.lost = new DocumentLockLost(
+      `The lock on document ${this._documentId} lapsed: it could not be renewed.`,
+      this._documentId,
+      error,
+    );
+    if (this._onLost) this._onLost(this.lost);
+  }
+}
+
+/**
+ * What a `client.documents.locked(id, (lock) => ...)` block gets.
+ *
+ * The block does not have to consult it: a lost lock stops the next write on
+ * its own. Read `lock.lost` (or call `lock.raiseIfLost()`) to give up earlier,
+ * between steps of work that has not written anything yet.
+ */
+export class DocumentLock {
+  constructor(documentId, keeper) {
+    this.documentId = documentId;
+    this._keeper = keeper;
+  }
+
+  /** The `DocumentLockLost` if the lock lapsed, else null. */
+  get lost() {
+    return this._keeper ? this._keeper.lost : null;
+  }
+
+  raiseIfLost() {
+    if (this.lost) throw this.lost;
+  }
+}
+
+/**
+ * Hold `documentId`'s server-enforced lock for the length of `fn`.
+ * `client.documents.locked` is the entry point; see its doc comment.
+ *
+ * @param {object} client
+ * @param {string} documentId
+ * @param {(lock: DocumentLock) => any} fn
+ * @param {{ keepAlive?: boolean }} [options]
+ */
+export async function withDocumentLock(
+  client,
+  documentId,
+  fn,
+  { keepAlive = true } = {},
+) {
+  let info;
+  try {
+    info = await client.documents.acquireLock(documentId);
+  } catch (error) {
+    if (error?.status === 423) {
+      // The error body is raw JSON off the wire, so it is still kebab-cased.
+      const body = error.responseData || {};
+      const holder = body.userId || body["user-id"] || "another user";
+      const readable = new Error(
+        `Document ${documentId} is locked by ${holder} (likely being edited); try again once they're done.`,
+      );
+      readable.status = 423;
+      readable.statusText = error.statusText;
+      readable.url = error.url;
+      readable.method = error.method;
+      readable.responseData = error.responseData;
+      readable.cause = error;
+      throw readable;
+    }
+    throw error;
+  }
+
+  let keeper = null;
+  if (keepAlive) {
+    const ttlMs = lockTtlMs(info?.expiresAt, Date.now());
+    client.documentLockLost = null;
+    keeper = new LockKeeper(
+      (id) => client.documents.acquireLock(id),
+      documentId,
+      ttlMs,
+      {
+        onLost: (lost) => {
+          client.documentLockLost = lost;
+        },
+      },
+    );
+    keeper.start();
+  }
+
+  let result;
+  let threw = false;
+  try {
+    result = await fn(new DocumentLock(documentId, keeper));
+  } catch (error) {
+    threw = true;
+    throw error;
+  } finally {
+    if (keeper) keeper.stop();
+    const lost = keeper ? keeper.lost : null;
+    client.documentLockLost = null;
+    // Best-effort release: the server TTL reclaims a stranded lock, and we must
+    // not let a release failure mask the real error from the body.
+    try {
+      await client.documents.releaseLock(documentId);
+    } catch {
+      /* the lock expires on its own */
+    }
+    // A block that ran to the end without the lock it asked for did not do what
+    // it says it did. Only throw when nothing else is already propagating, so
+    // the real failure is never masked.
+    if (lost && !threw) throw lost;
+  }
+  return result;
+}

package/src/http.js

@@ -1,5 +1,52 @@
 import { transformRequest, transformResponse } from "./transforms.js";
 
+// ---------------------------------------------------------------------------
+// Batch mode: which calls join a batch, and which go over the wire anyway.
+//
+// `client.batched()` sets ONE flag on the whole client, and every call made
+// while it is set is queued, whatever code made it. A browser client is shared
+// by an editor, an importer and the app's chrome at once, so the call that
+// lands inside someone else's batch is usually not the one that opened it.
+// Every call reaching this layer is one of three things, and the third column
+// is what a new endpoint has to pick.
+//
+// 1. A WRITE of project data: an entity, its metadata, a layer, a membership,
+//    a comment. This is what a batch is for, so it QUEUES. It is the default
+//    and needs no flag.
+//
+// 2. A READ. Pass `bypassBatch`. A queued read is broken three ways: the
+//    caller gets `{ batched: true }` instead of data, the queued GET takes a
+//    slot in the batch's results array and shifts every positional read after
+//    it, and server-side the sub-request runs against the batch's transaction
+//    connection rather than the pool, where `/query` throws and 500s the whole
+//    batch, rolling back every write in it. Bypassed, the read is answered
+//    from the pool and sees exactly the state it would have seen had the batch
+//    not been open.
+//
+// 3. An OUT-OF-BAND SIGNAL: stopping a service request, reporting a service's
+//    progress or result, taking or dropping a document lock, an admin action
+//    on the server itself. It is shaped like a write but carries no project
+//    data, and its whole value is that it happens NOW. Queued, it happens at
+//    submit, or never if the batch aborts, while its caller reads success.
+//    Pass `bypassBatch` for these too.
+//
+// A bypassed call neither joins the batch nor spends its stamp. Strict mode
+// marks the batch's one expected document-version onto the first QUEUED write,
+// and a call that went over the wire on its own is not that write. It does not
+// join an open logical operation either: the audit group is a label for the
+// writes, and a signal that is never audited would mark the group written and
+// leave the relabel PATCH 404ing on a group nothing ever created.
+//
+// `noBatch` is not part of that judgment. It marks the five calls the batch
+// transport cannot carry at all (a batch inside a batch, the multipart media
+// and avatar uploads, the user-data store's put and delete) and raises so the
+// caller finds out. Never put it on a read: it turns a swallowed read into a
+// thrown one, which is what the chrome hit when an unrelated import was
+// running. A blobless DELETE beside an upload is not one of them: it carries
+// nothing the transport cannot express, so it takes its class from the three
+// above like anything else.
+// ---------------------------------------------------------------------------
+
 // Default per-request timeout (ms). Applied to every request unless the client
 // is constructed with a different `timeout` (0 / null disables it). Note: this
 // also bounds media up/downloads — bump it (or disable) for very large files.
@@ -253,14 +300,12 @@ export function xhrSend(
  *   rawBody         - Body value passed directly (no transform). Mutually exclusive with body.
  *   formData        - If true, body is FormData; skip Content-Type header
  *   queryParams     - Object of query param key/values to append
- *   noBatch         - If true, throw when in batch mode
+ *   noBatch         - If true, throw when in batch mode. Only for calls the
+ *                     batch transport cannot carry at all (see the note at the
+ *                     top of this file); never for a read.
  *   bypassBatch     - If true, go over the wire even while a batch is open.
- *                     For READS only: a batch is a write transaction, its
- *                     ops return no value to their caller until submit, and
- *                     the sub-request runs against the tx Connection rather
- *                     than the pool. A read swallowed by an ambient batch is
- *                     therefore useless to the caller AND can fail the whole
- *                     batch (see `query`).
+ *                     Every read carries it, and so does every out-of-band
+ *                     signal (see the note at the top of this file).
  *   skipResponseTransform - Return raw parsed JSON (no transformResponse)
  *   noAuth          - Skip Authorization header
  *   binaryResponse  - Return arrayBuffer instead of JSON/text
@@ -289,6 +334,20 @@ export async function makeRequest(client, method, path, options = {}) {
     onUploadProgress,
   } = options;
 
+  // A write must not go out on a lock that lapsed. `documents.locked()`
+  // records the loss here when its keep-alive cannot renew, and from that
+  // moment the block is holding nothing: an edit by somebody else can already
+  // have landed between the read the work was planned from and the write about
+  // to go out. Reads pass, and so do the lock routes themselves, which is how
+  // the block still releases on its way out.
+  if (
+    client.documentLockLost &&
+    method !== "GET" &&
+    !path.endsWith("/lock")
+  ) {
+    throw client.documentLockLost;
+  }
+
   // Build URL
   let url = `${client.baseUrl}${path}`;
 
@@ -318,7 +377,7 @@ export async function makeRequest(client, method, path, options = {}) {
   }
 
   // Strict mode: append document-version for non-GET requests.
-  // Inside a batch, stamp ONLY the first write: batches run atomically
+  // Inside a batch, stamp ONLY the first queued write: batches run atomically
   // server-side, so a version check on the first op gives whole-batch OCC
   // semantics, while stamping every op would 409 the second op against the
   // version bump the first op itself caused (every queued op captures the
@@ -333,7 +392,11 @@ export async function makeRequest(client, method, path, options = {}) {
       const docVersion = client.documentVersions[docId];
       const separator = url.includes("?") ? "&" : "?";
       url += `${separator}document-version=${encodeURIComponent(docVersion)}`;
-      if (client.isBatching) client.batchVersionStamped = true;
+      // A bypassing call queues nothing, so it must not spend the batch's one
+      // stamp. `query` is a POST and lands here from app chrome while someone
+      // else's batch is open: marking the batch stamped there left the first
+      // real write unversioned and the batch unguarded.
+      if (client.isBatching && !bypassBatch) client.batchVersionStamped = true;
     }
   }
 
@@ -350,7 +413,17 @@ export async function makeRequest(client, method, path, options = {}) {
   // Logical-operation group (see client.beginOperation): stamp every write
   // with the group id; the message rides along too so the server can label
   // the group lazily on whichever tagged write lands first.
-  if (client.operationGroup && method !== "GET") {
+  //
+  // A bypassing call is not one of those writes. The out-of-band signals are
+  // shaped like a write and carry no project data (a lock taken or renewed, a
+  // cancelled service request, a service reporting its progress, an admin
+  // control), and `query` is a read that travels as a POST. None of them lands
+  // in the audit log, so a stamp does nothing server-side while `written`
+  // promises a group that will never exist: the relabel PATCH then 404s. Same
+  // rule as the batch and the OCC stamp above, for the same reason: a
+  // bypassing call belongs to whoever made it, not to whatever operation
+  // happens to be open on this shared client.
+  if (client.operationGroup && method !== "GET" && !bypassBatch) {
     const group = client.operationGroup;
     const separator = url.includes("?") ? "&" : "?";
     url += `${separator}group-id=${encodeURIComponent(group.id)}`;
@@ -359,10 +432,10 @@ export async function makeRequest(client, method, path, options = {}) {
     group.written = true;
   }
 
-  // Batch mode. A `bypassBatch` read is deliberately NOT queued: it belongs to
-  // whoever called it, not to whatever batch happens to be open on this shared
-  // client (a document reconcile, an import), and it reads the pre-batch state
-  // exactly as it would have if the batch were not running.
+  // Batch mode. A `bypassBatch` call is deliberately NOT queued: it belongs to
+  // whoever made it, not to whatever batch happens to be open on this shared
+  // client (a document reconcile, an import). See the three classes at the top
+  // of this file.
   if (client.isBatching && !bypassBatch) {
     if (noBatch) {
       throw new Error(`This endpoint cannot be used in batch mode: ${path}`);