@larc-iu/plaid-client 0.2.0-alpha.3 → 0.2.0-alpha.32

package/src/sse.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Project a parsed SSE `data:` object onto what a listener callback sees.
+ *
+ * The envelope is API surface and gets the usual `transformResponse` recasing.
+ * A `message` event's `data` is NOT: it is opaque application data (whatever
+ * `sendMessage` was handed), so its keys must survive verbatim, exactly as
+ * `metadata` and `config` do elsewhere. Without this, a key written
+ * `case-marker` reaches a JavaScript listener as `caseMarker` and a Python
+ * listener as `case_marker`, so the same broadcast reads differently depending
+ * on the reader's language.
+ */
+export function eventPayload(eventType: any, parsed: any): any;
+/**
+ * Create an SSE connection to the listen endpoint using fetch-based streaming.
+ * Automatically handles heartbeat confirmations and event parsing.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {function} onEvent - Callback (eventType, data). Return true to stop.
+ * @param {string} [path] - Stream path under baseUrl. Defaults to the project
+ *   /listen bus; service request channels pass their own. Only /listen emits
+ *   `heartbeat` events needing a POST confirmation — other streams keep
+ *   themselves alive with ignored SSE comments.
+ * @returns {Object} SSE connection with .close(), .getStats(), .readyState,
+ *   and .error: once CLOSED, why (null when this side closed it). A refused
+ *   stream's error carries the HTTP `status`, and a stream the server ended
+ *   carries an error named `StreamClosed`.
+ */
+export function createSSEConnection(client: any, projectId: string, onEvent: Function, path?: string): any;
+export const SSE_IDLE_TIMEOUT_MS: 60000;

package/src/sse.js

@@ -1,5 +1,22 @@
 import { transformResponse } from './transforms.js';
 
+// A live SSE stream is never silent for long: the server sends a keepalive
+// comment on service channels (every 25s) and a heartbeat event on the /listen
+// bus (every 30s). So if NOTHING arrives for longer than this, the connection is
+// dead: the server was killed without closing the socket, the network dropped
+// it, or a reconnect caught the server mid-restart (port accepting, app not yet
+// streaming). We must surface that as a drop so the registration supervisor in
+// serve() can reopen it. Without the watchdog such a silent drop
+// leaves `reader.read()` pending forever: readyState never reaches CLOSED, so
+// nothing reconnects and the service never heals. Comfortably above both server
+// cadences, so a healthy idle stream never trips it.
+export const SSE_IDLE_TIMEOUT_MS = 60000;
+
+// The last failure warned about per stream URL, so a stream retried every few
+// seconds through an outage warns once per distinct failure rather than once
+// per attempt. Cleared when the stream opens. Mirrors the Python client.
+const lastWarning = new Map();
+
 /**
  * Project a parsed SSE `data:` object onto what a listener callback sees.
  *
@@ -19,6 +36,12 @@ export function eventPayload(eventType, parsed) {
   return payload;
 }
 
+// Tell the client a stream of its own dropped or opened (a stand-in client in
+// a test may not listen).
+function tell(client, hook) {
+  try { client[hook]?.(); } catch (_) { /* the stream must not die of it */ }
+}
+
 /**
  * Create an SSE connection to the listen endpoint using fetch-based streaming.
  * Automatically handles heartbeat confirmations and event parsing.
@@ -30,7 +53,10 @@ export function eventPayload(eventType, parsed) {
  *   /listen bus; service request channels pass their own. Only /listen emits
  *   `heartbeat` events needing a POST confirmation — other streams keep
  *   themselves alive with ignored SSE comments.
- * @returns {Object} SSE connection with .close(), .getStats(), .readyState
+ * @returns {Object} SSE connection with .close(), .getStats(), .readyState,
+ *   and .error: once CLOSED, why (null when this side closed it). A refused
+ *   stream's error carries the HTTP `status`, and a stream the server ended
+ *   carries an error named `StreamClosed`.
  */
 export function createSSEConnection(client, projectId, onEvent, path) {
   const streamPath = path || `/api/v1/projects/${projectId}/listen`;
@@ -59,13 +85,30 @@ export function createSSEConnection(client, projectId, onEvent, path) {
     }
   };
 
+  // Watchdog: abort the fetch if the stream goes silent for longer than the
+  // server's keepalive cadence, so a silently-dropped connection lands in the
+  // catch below (readyState CLOSED) instead of blocking on a read that will
+  // never resolve.
+  let idleTimer = null;
+  const clearIdleTimer = () => {
+    if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+  };
+  const armIdleTimer = () => {
+    clearIdleTimer();
+    idleTimer = setTimeout(() => {
+      if (!isClosed) abortController.abort(new Error('SSE stream went silent'));
+    }, SSE_IDLE_TIMEOUT_MS);
+  };
+
   const sseConnection = {
     readyState: 0, // CONNECTING
+    error: null,
     close: () => {
       if (!isClosed) {
         isClosed = true;
         isConnected = false;
         sseConnection.readyState = 2; // CLOSED
+        clearIdleTimer();
         abortController.abort();
       }
     },
@@ -83,6 +126,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
   (async () => {
     try {
       const url = `${client.baseUrl}${streamPath}`;
+      armIdleTimer();
       const response = await fetch(url, {
         method: 'GET',
         headers: {
@@ -101,11 +145,25 @@ export function createSSEConnection(client, projectId, onEvent, path) {
           // takes over.
           console.warn('Service registration rejected (409): another instance of this service is already connected; will retry');
         }
-        throw new Error(`HTTP ${response.status} ${response.statusText}`);
+        // A refusal says why in its body (`{error}`), as on every other route.
+        let said = null;
+        try {
+          said = await response.json();
+        } catch {
+          said = null;
+        }
+        const why = typeof said?.error === 'string' ? `: ${said.error}` : '';
+        const refused = new Error(`HTTP ${response.status} ${response.statusText}${why}`);
+        refused.status = response.status;
+        if (said && typeof said === 'object') refused.responseData = said;
+        throw refused;
       }
 
       isConnected = true;
       sseConnection.readyState = 1; // OPEN
+      lastWarning.delete(url);
+      // After a drop the server may have restarted with other limits.
+      tell(client, '_noteStreamOpened');
 
       const reader = response.body.getReader();
       const decoder = new TextDecoder();
@@ -120,6 +178,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
       while (true) {
         const { done, value } = await reader.read();
         if (done || isClosed) break;
+        armIdleTimer();
 
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split('\n');
@@ -158,14 +217,32 @@ export function createSSEConnection(client, projectId, onEvent, path) {
           }
         }
       }
+      if (!isClosed) {
+        // The server ended the stream, for instance because the opener lost
+        // the right to it. Say so, so a caller can tell it from a close of
+        // its own.
+        sseConnection.error = Object.assign(new Error('The server closed the stream'), {
+          name: 'StreamClosed',
+        });
+      }
     } catch (error) {
+      if (!isClosed) sseConnection.error = error;
       if (error.name !== 'AbortError') {
-        console.warn('SSE connection error:', error);
+        const url = `${client.baseUrl}${streamPath}`;
+        const message = String(error?.message || error);
+        if (lastWarning.get(url) !== message) {
+          lastWarning.set(url, message);
+          console.warn('SSE connection error:', error);
+        }
       }
     } finally {
+      // Ended without a close() of this side's own: a drop.
+      const dropped = !isClosed;
+      clearIdleTimer();
       isConnected = false;
       isClosed = true;
       sseConnection.readyState = 2; // CLOSED
+      if (dropped) tell(client, '_noteStreamDropped');
     }
   })();
 

package/src/testing.d.ts

@@ -0,0 +1,128 @@
+/**
+ * A request as `answer` is asked it: the bundle call that made it (`kind` and
+ * `args`), and the request as the server reads it.
+ * @typedef {{kind?: string, args: any[], method: string, path: string,
+ *   query: Record<string, string>, body: any, batched: boolean}} FakeRequest
+ */
+/**
+ * A round trip as `requests` holds it and `onRequest` hears it: a request,
+ * or a batch request with its `operations`.
+ * @typedef {{method: string, path: string, query: Record<string, string>, body: any,
+ *   kind?: string, args?: any[], operations?: object[]}} RecordedRequest
+ */
+/**
+ * An error as the client throws it for a refusal: `status`, and the
+ * server's answer as `responseData`.
+ * @param {number} status
+ * @param {object} [responseData]
+ * @returns {Error & {status: number, responseData: object}}
+ */
+export function refusal(status: number, responseData?: object): Error & {
+    status: number;
+    responseData: object;
+};
+/**
+ * What a request is answered with when `answer` gives nothing: the id a
+ * create minted (or a new one), the ids of a bulk create, an empty page for a
+ * read, and `{}` for anything else.
+ * @param {{kind?: string, method: string, body?: any}} request
+ * @returns {object}
+ */
+export function defaultAnswer({ kind, method, body }: {
+    kind?: string;
+    method: string;
+    body?: any;
+}): object;
+/**
+ * A real PlaidClient on a recording transport (see the module's note).
+ *
+ * `answer(request)` answers each request, `request` being `{kind, args,
+ * method, path, query, body, batched}`: the bundle call that made it (`kind`
+ * and `args`, any batch refs in them filled in, undefined for a request no
+ * bundle call made), and the request as the server reads it. It returns the
+ * answer as the client hands it back (camelCase), or a promise of it, or
+ * undefined for `defaultAnswer`'s. To refuse, it throws (see `refusal`). A
+ * refusal of any op of a batch refuses the whole batch, as the server's
+ * transaction does.
+ *
+ * @param {{answer?: (request: FakeRequest) => any,
+ *   onRequest?: (request: RecordedRequest) => void, baseUrl?: string}} [options]
+ * @returns {PlaidClient & {calls: Array<{kind: string, args: any[]}>,
+ *   requests: RecordedRequest[], operations: Array<{message: string, kind?: string, ref?: string}>}}
+ */
+export function fakeClient({ answer, onRequest, baseUrl, }?: {
+    answer?: (request: FakeRequest) => any;
+    onRequest?: (request: RecordedRequest) => void;
+    baseUrl?: string;
+}): PlaidClient & {
+    calls: Array<{
+        kind: string;
+        args: any[];
+    }>;
+    requests: RecordedRequest[];
+    operations: Array<{
+        message: string;
+        kind?: string;
+        ref?: string;
+    }>;
+};
+/**
+ * Runs `f` and gives its value and the milliseconds it took. With `warm`,
+ * runs it that many times first, untimed, so the engine has compiled it.
+ * With `runs`, times that many runs and keeps the quickest, which a pause for
+ * garbage collection or another process touches least. Only for an `f` that
+ * can run again.
+ * @template T
+ * @param {() => T} f
+ * @param {{warm?: number, runs?: number}} [options]
+ * @returns {[T, number]}
+ */
+export function timed<T>(f: () => T, { warm, runs }?: {
+    warm?: number;
+    runs?: number;
+}): [T, number];
+/**
+ * Throws unless `bigMs` is under `factor` times `smallMs`, two cases timed on
+ * the same machine in the same run. A loaded runner slows both, so the bound
+ * holds where a fixed number of milliseconds fails. Pick the cases so that
+ * the fault the test guards against grows the ratio well past `factor`: a
+ * scan of every row per row goes from 10 to 100 when the big case is ten
+ * times the small one. `smallMs` counts as at least `floorMs` (default 1),
+ * so a case too quick to time cannot make the bound nothing.
+ * @param {number} factor
+ * @param {number} smallMs
+ * @param {number} bigMs
+ * @param {{floorMs?: number, label?: string}} [options]
+ * @returns {number} `bigMs`
+ */
+export function withinFactorOf(factor: number, smallMs: number, bigMs: number, { floorMs, label }?: {
+    floorMs?: number;
+    label?: string;
+}): number;
+/**
+ * A request as `answer` is asked it: the bundle call that made it (`kind` and
+ * `args`), and the request as the server reads it.
+ */
+export type FakeRequest = {
+    kind?: string;
+    args: any[];
+    method: string;
+    path: string;
+    query: Record<string, string>;
+    body: any;
+    batched: boolean;
+};
+/**
+ * A round trip as `requests` holds it and `onRequest` hears it: a request,
+ * or a batch request with its `operations`.
+ */
+export type RecordedRequest = {
+    method: string;
+    path: string;
+    query: Record<string, string>;
+    body: any;
+    kind?: string;
+    args?: any[];
+    operations?: object[];
+};
+import { PlaidClient } from "./client.js";

package/src/testing.js

@@ -0,0 +1,379 @@
+/**
+ * A PlaidClient for tests, with no server. The twin of plaid-client-py's
+ * `plaid_client.testing`, shipped as `@larc-iu/plaid-client/testing`.
+ *
+ *   import { fakeClient } from "@larc-iu/plaid-client/testing";
+ *
+ *   const client = fakeClient({
+ *     answer: ({ kind, args }) =>
+ *       kind === "documents.get" ? aDocument : undefined,
+ *   });
+ *   await editor.run(client);
+ *   assert.deepEqual(client.calls.map((c) => c.kind), ["beginOperation", "tokens.create", "batch.submit"]);
+ *
+ * It is the real client: its bundles, its batch (the queue, the refs, the
+ * split past MAX_BATCH_OPS, the refusal of a write on a batch already sent and
+ * of a nested batch) and its logical operations (the closed list of kinds,
+ * nesting, the relabel sent only when a write joined) are the ones an app
+ * runs. Only the transport is replaced: each request is recorded and
+ * answered by `answer` instead of going out, so a test passes only on calls
+ * the real client makes.
+ *
+ * What it records, in order, under `client.calls` as `{kind, args}`:
+ * - each call of a bundle method (`"tokens.create"`, `"query"`) whose request
+ *   is not a read, with the arguments it was given, when it is made (on the
+ *   client or queued on a batch);
+ * - `"beginOperation"`, when an outermost logical operation begins, its args
+ *   `[message]`, or `[message, {kind, ref}]` when either was given;
+ * - `"batch.submit"`, args `[]`, each time a batch is submitted.
+ *
+ * `client.requests` is each round trip as it would have gone out:
+ * `{method, path, query, body, kind, args}`, the body as the server reads it
+ * (kebab keys) and the call that made it, and one `{method: "POST", path:
+ * "/api/v1/batch", operations}` per batch request. `onRequest`, when given,
+ * hears each as it goes. `client.operations` is each outermost operation
+ * begun, as `{message, kind, ref}`. A batch's own `queued` lists the
+ * `{kind, args}` of the writes queued on it.
+ *
+ * What it does not do: keep any state. A write is answered, not applied, and
+ * a later read answers what `answer` says. Nor does it learn document
+ * versions, lose a lock, retry, or check that an id exists.
+ *
+ * `timed` and `withinFactorOf` bound a slow case against a small one timed
+ * in the same run, where a fixed number of milliseconds fails on a loaded
+ * runner. Their twins are `timed` and `within_factor_of` in
+ * `plaid_client.testing` and in plaid-core's `plaid.test-helpers`.
+ */
+
+import { BatchRef } from "./batchRef.js";
+import { PlaidClient } from "./client.js";
+import { prepareRequest } from "./http.js";
+import { uuidv7 } from "./ids.js";
+import { applyMetadataOps } from "./metadataOps.js";
+
+/**
+ * A request as `answer` is asked it: the bundle call that made it (`kind` and
+ * `args`), and the request as the server reads it.
+ * @typedef {{kind?: string, args: any[], method: string, path: string,
+ *   query: Record<string, string>, body: any, batched: boolean}} FakeRequest
+ */
+
+/**
+ * A round trip as `requests` holds it and `onRequest` hears it: a request,
+ * or a batch request with its `operations`.
+ * @typedef {{method: string, path: string, query: Record<string, string>, body: any,
+ *   kind?: string, args?: any[], operations?: object[]}} RecordedRequest
+ */
+
+/**
+ * An error as the client throws it for a refusal: `status`, and the
+ * server's answer as `responseData`.
+ * @param {number} status
+ * @param {object} [responseData]
+ * @returns {Error & {status: number, responseData: object}}
+ */
+export function refusal(status, responseData = {}) {
+  const error = /** @type {any} */ (
+    new Error(`HTTP ${status} ${responseData.error || responseData.message || "Refused"}`)
+  );
+  error.status = status;
+  error.responseData = responseData;
+  return error;
+}
+
+// What the server refuses whoever sends it: a metadata patch, alone or as an
+// entry of a bulk update, that is not a list of ops.
+function checkMetadataOps(ops) {
+  if (!Array.isArray(ops)) throw refusal(400, { error: "metadata ops must be an array" });
+  applyMetadataOps({}, ops);
+}
+
+function serverChecks(kind, args) {
+  if (!kind) return;
+  if (kind.endsWith(".patchMetadata")) checkMetadataOps(args[1]);
+  if (kind.endsWith(".bulkUpdate")) {
+    for (const entry of args[0] || []) {
+      if (entry?.metadata !== undefined) checkMetadataOps(entry.metadata);
+    }
+  }
+}
+
+/**
+ * What a request is answered with when `answer` gives nothing: the id a
+ * create minted (or a new one), the ids of a bulk create, an empty page for a
+ * read, and `{}` for anything else.
+ * @param {{kind?: string, method: string, body?: any}} request
+ * @returns {object}
+ */
+export function defaultAnswer({ kind, method, body }) {
+  if (kind?.endsWith(".bulkCreate") && Array.isArray(body)) {
+    return { ids: body.map((entry) => entry?.id ?? uuidv7()) };
+  }
+  if (/\.(create|copy|split)$/.test(kind ?? "")) return { id: body?.id ?? uuidv7() };
+  if (method === "GET") return { entries: [], nextCursor: null };
+  return {};
+}
+
+const isPlainObject = (v) => {
+  if (v === null || typeof v !== "object") return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+};
+
+// The id a ref stands for, read off the results its batch has so far.
+const refId = (results, ref) => {
+  const body = results[ref.$ref]?.body;
+  return ref.index === undefined ? body?.id : body?.ids?.[ref.index];
+};
+
+// `args` with each BatchRef in it replaced by the id it stands for.
+const fillArgs = (args, results) => {
+  const fill = (v) => {
+    if (v instanceof BatchRef) return refId(results, v);
+    if (Array.isArray(v)) return v.map(fill);
+    if (isPlainObject(v)) return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, fill(x)]));
+    return v;
+  };
+  return args.map(fill);
+};
+
+// A queued op's body with the ids its `refs` name put in, as the server does.
+const fillRefs = (body, refs, results) => {
+  if (!refs) return body;
+  const out = structuredClone(body);
+  for (const { at, op, index } of refs) {
+    let holder = out;
+    for (const key of at.slice(0, -1)) holder = holder[key];
+    holder[at.at(-1)] = refId(results, { $ref: op, index });
+  }
+  return out;
+};
+
+const split = (url, baseUrl) => {
+  const u = new URL(url.startsWith("http") ? url : `${baseUrl}${url}`);
+  return { path: u.pathname, query: Object.fromEntries(u.searchParams) };
+};
+
+// What goes over the wire is JSON: a value that cannot be (a BatchRef sent
+// anywhere but a queued body) throws here as it would there.
+const wire = (body) => (body === undefined ? undefined : JSON.parse(JSON.stringify(body)));
+
+/**
+ * A real PlaidClient on a recording transport (see the module's note).
+ *
+ * `answer(request)` answers each request, `request` being `{kind, args,
+ * method, path, query, body, batched}`: the bundle call that made it (`kind`
+ * and `args`, any batch refs in them filled in, undefined for a request no
+ * bundle call made), and the request as the server reads it. It returns the
+ * answer as the client hands it back (camelCase), or a promise of it, or
+ * undefined for `defaultAnswer`'s. To refuse, it throws (see `refusal`). A
+ * refusal of any op of a batch refuses the whole batch, as the server's
+ * transaction does.
+ *
+ * @param {{answer?: (request: FakeRequest) => any,
+ *   onRequest?: (request: RecordedRequest) => void, baseUrl?: string}} [options]
+ * @returns {PlaidClient & {calls: Array<{kind: string, args: any[]}>,
+ *   requests: RecordedRequest[], operations: Array<{message: string, kind?: string, ref?: string}>}}
+ */
+export function fakeClient({
+  answer = () => undefined,
+  onRequest = () => {},
+  baseUrl = "http://plaid.test",
+} = {}) {
+  // A token of its own: each fake client is a login of its own, so nothing
+  // kept per login (a cache an app keeps by token) is shared between tests.
+  const token = `test-token-${uuidv7()}`;
+  const client = /** @type {any} */ (new PlaidClient(baseUrl, token, { retryDelaysMs: [] }));
+  const calls = [];
+  const requests = [];
+  const operations = [];
+  client.calls = calls;
+  client.requests = requests;
+  client.operations = operations;
+
+  // The bundle call being made, while its request is formed.
+  let current = null;
+  // Each queued op's call and batch, read when the batch is sent.
+  const callOf = new WeakMap();
+  // Each batch's results so far, for the refs its later ops hold.
+  const resultsOf = new WeakMap();
+
+  const respond = async (request) => {
+    serverChecks(request.kind, request.args);
+    const given = await answer(request);
+    return given === undefined ? defaultAnswer(request) : given;
+  };
+
+  // The call being made sees its request: it is recorded when the request
+  // is no read.
+  const seen = (method) => {
+    if (!current || current.recorded) return current;
+    current.recorded = true;
+    if (method !== "GET") calls.push({ kind: current.kind, args: current.args });
+    return current;
+  };
+
+  client._request = async (method, path, options = {}) => {
+    // What the real client refuses before anything goes (a write on a lock
+    // that lapsed) is refused here, and was never made.
+    const { url, requestBody, stampedGroup } = prepareRequest(client, method, path, options);
+    const call = seen(method);
+    const body = options.formData ? requestBody : wire(requestBody);
+    const request = { method, ...split(url, baseUrl), body, kind: call?.kind, args: call?.args ?? [] };
+    requests.push(request);
+    onRequest(request);
+    const answered = await respond({ ...request, batched: false });
+    // The server took it, so the operation's group exists.
+    if (stampedGroup) stampedGroup.written = true;
+    return answered;
+  };
+
+  client._postBatch = async (url, chunk) => {
+    const sent = wire(chunk);
+    const request = { method: "POST", ...split(url, baseUrl), body: undefined, operations: sent };
+    requests.push(request);
+    onRequest(request);
+    const answered = [];
+    for (let i = 0; i < chunk.length; i++) {
+      const op = chunk[i];
+      const { call, batch } = callOf.get(op) ?? callOf.get(op.body) ?? {};
+      const results = (batch && resultsOf.get(batch)) ?? [];
+      const body = fillRefs(sent[i].body, op.refs, answered);
+      const result = await respond({
+        kind: call?.kind,
+        args: call ? fillArgs(call.args, results) : [],
+        method: op.method,
+        ...split(op.path, baseUrl),
+        body,
+        batched: true,
+      });
+      const entry = { status: 200, headers: {}, body: result };
+      answered.push(entry);
+      results.push(entry);
+    }
+    return answered;
+  };
+
+  // Each bundle method on `view` (the client, or a batch) tells the
+  // transport which call is being made.
+  const instrument = (view) => {
+    const queued = [];
+    for (const [name, bundle] of Object.entries(view)) {
+      if (name === "client" || !isPlainObject(bundle)) continue;
+      for (const [method, fn] of Object.entries(bundle)) {
+        if (typeof fn !== "function") continue;
+        bundle[method] = tracked(view, `${name}.${method}`, fn, queued);
+      }
+    }
+    if (typeof view.query === "function") view.query = tracked(view, "query", view.query, queued);
+    return queued;
+  };
+
+  function tracked(view, kind, fn, queued) {
+    return function (...args) {
+      const call = { kind, args, recorded: false };
+      const ops = view === client ? null : view.operations;
+      const before = ops?.length;
+      const outer = current;
+      current = call;
+      try {
+        return fn.apply(this, args);
+      } finally {
+        current = outer;
+        // A write the call queued on a batch.
+        if (ops && ops.length > before) {
+          if (!call.recorded) {
+            call.recorded = true;
+            calls.push({ kind, args });
+          }
+          queued.push({ kind, args });
+          for (const op of ops.slice(before)) {
+            callOf.set(op, { call, batch: view });
+            if (op.body && typeof op.body === "object") callOf.set(op.body, { call, batch: view });
+          }
+        }
+      }
+    };
+  }
+
+  instrument(client);
+
+  client.batch = (options) => {
+    const b = PlaidClient.prototype.batch.call(client, options);
+    resultsOf.set(b, []);
+    b.queued = instrument(b);
+    const submit = b.submit;
+    b.submit = () => {
+      calls.push({ kind: "batch.submit", args: [] });
+      return submit();
+    };
+    return b;
+  };
+
+  client.beginOperation = function (message, opts = {}) {
+    if (!this.operationGroup) {
+      const tags = {
+        ...(opts.kind ? { kind: opts.kind } : {}),
+        ...(opts.ref ? { ref: opts.ref } : {}),
+      };
+      const id = PlaidClient.prototype.beginOperation.call(this, message, opts);
+      calls.push({
+        kind: "beginOperation",
+        args: Object.keys(tags).length ? [message, tags] : [message],
+      });
+      operations.push({ message, kind: opts.kind, ref: opts.ref });
+      return id;
+    }
+    return PlaidClient.prototype.beginOperation.call(this, message, opts);
+  };
+
+  return client;
+}
+
+/**
+ * Runs `f` and gives its value and the milliseconds it took. With `warm`,
+ * runs it that many times first, untimed, so the engine has compiled it.
+ * With `runs`, times that many runs and keeps the quickest, which a pause for
+ * garbage collection or another process touches least. Only for an `f` that
+ * can run again.
+ * @template T
+ * @param {() => T} f
+ * @param {{warm?: number, runs?: number}} [options]
+ * @returns {[T, number]}
+ */
+export function timed(f, { warm = 0, runs = 1 } = {}) {
+  for (let i = 0; i < warm; i++) f();
+  /** @type {[T, number] | null} */
+  let best = null;
+  for (let i = 0; i < runs; i++) {
+    const t = performance.now();
+    const value = f();
+    const ms = performance.now() - t;
+    if (!best || ms < best[1]) best = [value, ms];
+  }
+  return /** @type {[T, number]} */ (best);
+}
+
+/**
+ * Throws unless `bigMs` is under `factor` times `smallMs`, two cases timed on
+ * the same machine in the same run. A loaded runner slows both, so the bound
+ * holds where a fixed number of milliseconds fails. Pick the cases so that
+ * the fault the test guards against grows the ratio well past `factor`: a
+ * scan of every row per row goes from 10 to 100 when the big case is ten
+ * times the small one. `smallMs` counts as at least `floorMs` (default 1),
+ * so a case too quick to time cannot make the bound nothing.
+ * @param {number} factor
+ * @param {number} smallMs
+ * @param {number} bigMs
+ * @param {{floorMs?: number, label?: string}} [options]
+ * @returns {number} `bigMs`
+ */
+export function withinFactorOf(factor, smallMs, bigMs, { floorMs = 1, label } = {}) {
+  if (!(bigMs < factor * Math.max(smallMs, floorMs))) {
+    throw new Error(
+      `${label ? `${label}: ` : ""}${Math.round(bigMs)} ms, not under ${factor} times ` +
+        `the small case's ${Math.round(smallMs)} ms`,
+    );
+  }
+  return bigMs;
+}