@larc-iu/plaid-client 0.2.0-alpha.22 → 0.2.0-alpha.26

package/src/documentLock.js

@@ -1,4 +1,5 @@
 import { isUnknownOutcome, retryUnknown } from "./http.js";
+import { uuidv4 } from "./ids.js";
 
 /**
  * Keeping a document lock alive for as long as a `locked()` block runs.
@@ -38,10 +39,18 @@ import { isUnknownOutcome, retryUnknown } from "./http.js";
  * landed while the lock was gone.
  */
 export class DocumentLockLost extends Error {
+  /**
+   * @param {string} message
+   * @param {string} documentId
+   * @param {unknown} [cause]
+   */
   constructor(message, documentId, cause) {
     super(message);
+    /** @type {"DocumentLockLost"} */
     this.name = "DocumentLockLost";
+    /** @type {string} */
     this.documentId = documentId;
+    /** @type {unknown} */
     this.cause = cause;
   }
 }
@@ -100,7 +109,10 @@ export class LockKeeper {
     this._stopped = false;
     this._wake = null;
     this._running = null;
-    /** The `DocumentLockLost` this keeper raised, or null. */
+    /**
+     * The `DocumentLockLost` this keeper raised, or null.
+     * @type {DocumentLockLost | null}
+     */
     this.lost = null;
   }
 
@@ -192,18 +204,31 @@ export class LockKeeper {
  * between steps of work that has not written anything yet.
  */
 export class DocumentLock {
+  /**
+   * @param {string} documentId
+   * @param {LockKeeper | null} keeper
+   * @param {string | null} [lockId]
+   */
   constructor(documentId, keeper, lockId = null) {
+    /** @type {string} */
     this.documentId = documentId;
-    /** The holder id the acquire answered with. */
+    /**
+     * The holder id the acquire answered with.
+     * @type {string | null}
+     */
     this.lockId = lockId;
     this._keeper = keeper;
   }
 
-  /** The `DocumentLockLost` if the lock lapsed, else null. */
+  /**
+   * The `DocumentLockLost` if the lock lapsed, else null.
+   * @returns {DocumentLockLost | null}
+   */
   get lost() {
     return this._keeper ? this._keeper.lost : null;
   }
 
+  /** Throw if the lock lapsed. Call it between steps that have not written. */
   raiseIfLost() {
     if (this.lost) throw this.lost;
   }
@@ -216,7 +241,7 @@ export class DocumentLock {
 export const LOCK_ACQUIRE_RETRY_MS = 500;
 
 function mintLockId() {
-  return globalThis.crypto.randomUUID();
+  return uuidv4();
 }
 
 /**

package/src/events.d.ts

@@ -0,0 +1,60 @@
+/** The page's recorder for `client`'s server. */
+export function recorderFor(client: any): any;
+/** Forget every recorder (tests). */
+export function resetEventRecorders(): void;
+/** Every event type the server accepts. */
+export const EVENT_TYPES: readonly string[];
+export const FLUSH_INTERVAL_MS: 10000;
+export const FLUSH_AT: 50;
+export const FLAG_TTL_MS: 10000;
+export const FLAG_OFF_TTL_MS: 60000;
+export class EventRecorder {
+    /**
+     * @param {object} [opts]
+     * @param {function} [opts.now] - Clock, for tests
+     * @param {object} [opts.window] - Where `pagehide` fires (default globalThis)
+     */
+    constructor({ now, window }?: {
+        now?: Function;
+        window?: object;
+    });
+    client: any;
+    buffer: any[];
+    timer: number;
+    now: Function;
+    flags: Map<any, any>;
+    seen: Set<any>;
+    _onPageHide: () => void;
+    window: any;
+    /** Tell the recorder a project's switch, e.g. right after changing it. */
+    setEnabled(projectId: any, on: any): void;
+    /**
+     * Record one event. Returns true when it was buffered, false when it was
+     * not (switch off, a repeat "shown", an unknown type, no project).
+     * @param {any} client
+     * @param {string} type
+     * @param {{projectId?: string, documentId?: string, targetId?: string, data?: Record<string, any>}} [fields]
+     * @returns {boolean}
+     */
+    record(client: any, type: string, { projectId, documentId, targetId, data }?: {
+        projectId?: string;
+        documentId?: string;
+        targetId?: string;
+        data?: Record<string, any>;
+    }): boolean;
+    /**
+     * Send what is buffered for every project whose switch is known to be on,
+     * drop what is buffered for one known to be off, and keep the rest until
+     * the switch is known. With `keepalive` (the page is going away) nothing is
+     * kept.
+     */
+    flush({ keepalive }?: {
+        keepalive?: boolean;
+    }): void;
+    /** Stop listening for `pagehide` and forget everything (tests). */
+    close(): void;
+    _schedule(): void;
+    _drop(projectId: any): void;
+    _flag(projectId: any): any;
+    _send(projectId: any, events: any, keepalive: any): void;
+}

package/src/events.js

@@ -1,8 +1,8 @@
 import { transformRequest } from "./transforms.js";
 
 // ---------------------------------------------------------------------------
-// Client events: the opt-in research telemetry of a project (core manual,
-// "Research telemetry").
+// Client events: the opt-in research telemetry of a project (defined in
+// plaid-core sql/client_event.clj).
 //
 // `client.events.record(type, fields)` is a fire-and-forget recorder. It
 // buffers events and sends them every FLUSH_INTERVAL_MS or FLUSH_AT events,
@@ -51,7 +51,7 @@ const PER_REQUEST = FLUSH_AT;
 // A suggested or written value is a gloss, not prose. A long one is cut, in
 // code points as the server counts them, so no character is split in two.
 // The server refuses a value past this length, and a key its type does not
-// take (core manual, "Research telemetry").
+// take (plaid-core sql/client_event.clj).
 const MAX_VALUE_CHARS = 200;
 
 const clip = (v) => {
@@ -92,6 +92,10 @@ export class EventRecorder {
   /**
    * Record one event. Returns true when it was buffered, false when it was
    * not (switch off, a repeat "shown", an unknown type, no project).
+   * @param {any} client
+   * @param {string} type
+   * @param {{projectId?: string, documentId?: string, targetId?: string, data?: Record<string, any>}} [fields]
+   * @returns {boolean}
    */
   record(client, type, { projectId, documentId, targetId, data } = {}) {
     try {

package/src/http.d.ts

@@ -0,0 +1,212 @@
+/**
+ * The timeout for a query: the client's own, raised to
+ * DEFAULT_QUERY_TIMEOUT_MS when it is shorter. A disabled timeout (0, null)
+ * stays disabled.
+ */
+export function queryTimeout(client: any): any;
+/**
+ * Note how far the server's clock is from this machine's, from a response's
+ * Date header, for `client.serverNow()`. A time the server stamped (an audit
+ * entry's `ts`) has to be judged against the server's clock: a browser clock
+ * minutes off would misjudge it. A response with no readable Date header
+ * leaves the last offset as it was.
+ */
+export function noteServerClock(client: any, headers: any): void;
+/**
+ * Extract and update document versions from response headers and body.
+ *
+ * `historical` marks a read made with `as-of`: its body carries the version
+ * the document HAD then, which is not what a strict-mode write must claim
+ * next, so the body is ignored and only the header (always the live
+ * version) is learned from. Without this, viewing an old state and then
+ * writing 409s on a version that stopped being current long ago.
+ */
+export function extractDocumentVersions(client: any, responseHeaders: any, responseBody?: any, { historical }?: {
+    historical?: boolean;
+}): void;
+/**
+ * `held` with `learned` merged in. A replayed answer only raises a version:
+ * it is what the document was right after the first send.
+ */
+export function mergeVersions(held: any, learned: any, replayed?: boolean): any;
+/**
+ * Read a failed response's body as parsed JSON, falling back to text.
+ */
+export function parseErrorBody(response: any): Promise<any>;
+/**
+ * Create an enriched error from a failed HTTP response.
+ */
+export function makeHttpError(response: any, errorData: any, url: any, method: any): Error;
+/**
+ * Create a network error (status 0). Timeout aborts get a clearer message.
+ */
+export function makeNetworkError(originalError: any, url: any, method: any): Error;
+/**
+ * Run `attempt`, retrying while it rejects with a 503. Exponential backoff
+ * with full jitter, so two clients that collide don't march in lockstep and
+ * collide again on every retry.
+ *
+ * `attempt` must perform the whole request, not just await a prepared one:
+ * a fetch body and an AbortSignal.timeout are both single-use.
+ * @param {() => Promise<any>} attempt
+ * @param {{retries?: number, baseDelayMs?: number, onRetry?: (info: object) => void}} [options]
+ */
+export function retryWhileBusy(attempt: () => Promise<any>, { retries, baseDelayMs, onRetry }?: {
+    retries?: number;
+    baseDelayMs?: number;
+    onRetry?: (info: object) => void;
+}): Promise<any>;
+/**
+ * Whether `error` leaves the outcome unknown: no response came (status 0),
+ * or a proxy answered for the server (502, 504). The write may have landed.
+ */
+export function isUnknownOutcome(error: any): boolean;
+/**
+ * Whether a create refused with `status` and body `data` was made by an
+ * earlier send of the same work: `409 id-taken` for an id in `minted` (a Set
+ * of the ids the work minted for its creates), and not for a row deleted
+ * since (there is nothing to go on with). The one rule for a lost answer's
+ * create. The Python twin is `minted_taken`.
+ */
+export function mintedTaken(status: any, data: any, minted: any): boolean;
+/**
+ * Run `attempt`, sending it again after each delay in `delaysMs` while it
+ * fails with an unknown outcome. Only for a keyed write, whose resend is
+ * answered from the first send when that one landed. Not when the browser
+ * says it is offline: then the request never left, and the caller waits for
+ * the network instead. Full jitter, as retryWhileBusy.
+ * @param {() => Promise<any>} attempt
+ * @param {{delaysMs?: number[], onRetry?: (info: object) => void}} [options]
+ */
+export function retryUnknown(attempt: () => Promise<any>, { delaysMs, onRetry }?: {
+    delaysMs?: number[];
+    onRetry?: (info: object) => void;
+}): Promise<any>;
+/**
+ * The key for the next keyed request, and the strict-mode stamp it must
+ * claim when an earlier run of its operation already sent it. `joins` says
+ * whether the request joins the open logical operation.
+ * Returns `{ key, pin, record }`: `pin` is undefined when nothing is pinned,
+ * and `record(version)` pins what this request claimed, the first time.
+ */
+export function nextIdempotencyKey(client: any, joins: any): {
+    key: string;
+    pin: any;
+    record: (version: any) => void;
+};
+/**
+ * Build a fetch AbortSignal that fires after `timeout` ms, or undefined when
+ * timeouts are disabled / unsupported.
+ */
+export function timeoutSignal(timeout: any): AbortSignal;
+/**
+ * Send a request through XMLHttpRequest so the caller can watch the bytes go
+ * up: fetch cannot report upload progress. Resolves to a Response, so the rest
+ * of the pipeline is the same either way. The timeout is a STALL timeout,
+ * re-armed by every progress event, so a large file on a slow link is never
+ * cut off while it is still moving, only once nothing has moved for `timeout`
+ * ms. Rejects the way fetch does: a TypeError for a network failure, an error
+ * named TimeoutError for a stall.
+ * @param {string} url
+ * @param {{method: string, headers: Record<string, string>, body: any}} request
+ * @param {{onUploadProgress?: (progress: {loaded: number, total: number | null}) => void, timeout?: number | null}} [options]
+ */
+export function xhrSend(url: string, { method, headers, body }: {
+    method: string;
+    headers: Record<string, string>;
+    body: any;
+}, { onUploadProgress, timeout }?: {
+    onUploadProgress?: (progress: {
+        loaded: number;
+        total: number | null;
+    }) => void;
+    timeout?: number | null;
+}): Promise<any>;
+/**
+ * Everything a request is before it goes anywhere: the URL with its query
+ * params and the stamps strict mode, a per-call audit message and an open
+ * logical operation add, plus the transformed body. Shared by the wire path
+ * (`makeRequest`) and the batch path (`queueRequest`), so a queued op is
+ * exactly the request that would have gone out. Strict mode stamps every
+ * write, queued or not, and `stampedDocument` names the document it stamped
+ * for (null when it stamped nothing). `stampedGroup` is the open logical
+ * operation it joined, if any, for `makeRequest` to mark written once the
+ * server has taken the request.
+ */
+export function prepareRequest(client: any, method: any, path: any, options?: {}): {
+    url: string;
+    requestBody: any;
+    stampedDocument: any;
+    stampedVersion: any;
+    stampedGroup: any;
+};
+/**
+ * Whether a write joins the open logical operation (see prepareRequest).
+ */
+export function joinsOperation(client: any, method: any, options?: {}): boolean;
+/**
+ * Whether a call made on the client goes out with an Idempotency-Key.
+ */
+export function takesIdempotencyKey(method: any, options?: {}): boolean;
+/**
+ * `path` with its strict-mode `document-version` claim replaced by `version`,
+ * or dropped when `version` is unknown. For the later requests of a batch
+ * split past MAX_BATCH_OPS: each op was stamped with the version the document
+ * had when it was queued, and every request before it has since moved the
+ * document on.
+ */
+export function restampDocumentVersion(path: any, version: any): any;
+/**
+ * A call made on a batch (see `PlaidClient#batch`). A write of project data is
+ * queued as one operation of the batch and answers `{ batched: true }`; its
+ * result is the matching entry of what `submit()` resolves to. A read, and a
+ * signal marked `outOfBand`, is the client's to make and goes over the wire
+ * now, exactly as if it had been made on the client.
+ */
+export function queueRequest(batch: any, method: any, path: any, options?: {}): Promise<any>;
+/**
+ * Generic request method handling all fetch logic.
+ *
+ * Options:
+ *   body            - Object body, run through transformRequest
+ *   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 made on a batch. Only for calls a
+ *                     batch cannot carry at all (see the note at the
+ *                     top of this file); never for a read.
+ *   outOfBand       - If true, the call is a signal rather than a write of
+ *                     project data: made on a batch it still goes over the
+ *                     wire, and it never joins an open logical operation (see
+ *                     the note at the top of this file).
+ *   noOperation     - If true, the call never joins an open logical operation
+ *                     but still queues on a batch like a write. For a
+ *                     broadcast message, which is never audited.
+ *   versioned       - If false, strict mode does not stamp the call with the
+ *                     document version. For a write that carries its own
+ *                     precondition (a text edit with `base`).
+ *   skipResponseTransform - Return raw parsed JSON (no transformResponse)
+ *   noAuth          - Skip Authorization header
+ *   binaryResponse  - Return arrayBuffer instead of JSON/text
+ *   noBusyRetry     - If true, a 503 is not retried. For a query: core
+ *                     answers 503 when its queue of large queries stays full
+ *                     until the query's deadline, and asking again at once
+ *                     only joins the same queue.
+ *   timeout         - Per-request timeout in ms overriding client.timeout
+ *                     for this call (0/null disables). Used for known-long
+ *                     ops like project delete.
+ *   onUploadProgress - Called with `{ loaded, total }` (bytes; total null when
+ *                     unknown) as the request body goes up. In a browser the
+ *                     request then travels by XMLHttpRequest (see xhrSend),
+ *                     where the timeout only fires when the upload stalls;
+ *                     elsewhere the callback is ignored and fetch is used.
+ */
+export function makeRequest(client: any, method: any, path: any, options?: {}): Promise<any>;
+export const DEFAULT_TIMEOUT_MS: 30000;
+export const DEFAULT_BATCH_TIMEOUT_MS: 180000;
+export const DEFAULT_QUERY_TIMEOUT_MS: 35000;
+export const BUSY_RETRIES: 4;
+export const BUSY_BACKOFF_MS: 250;
+export const IDEMPOTENCY_HEADER: "Idempotency-Key";
+export const REPLAYED_HEADER: "Idempotent-Replayed";
+export const UNKNOWN_RETRY_DELAYS_MS: number[];

package/src/http.js

@@ -239,6 +239,8 @@ export const BUSY_BACKOFF_MS = 250;
  *
  * `attempt` must perform the whole request, not just await a prepared one:
  * a fetch body and an AbortSignal.timeout are both single-use.
+ * @param {() => Promise<any>} attempt
+ * @param {{retries?: number, baseDelayMs?: number, onRetry?: (info: object) => void}} [options]
  */
 export async function retryWhileBusy(
   attempt,
@@ -315,6 +317,8 @@ export function mintedTaken(status, data, minted) {
  * answered from the first send when that one landed. Not when the browser
  * says it is offline: then the request never left, and the caller waits for
  * the network instead. Full jitter, as retryWhileBusy.
+ * @param {() => Promise<any>} attempt
+ * @param {{delaysMs?: number[], onRetry?: (info: object) => void}} [options]
  */
 export async function retryUnknown(
   attempt,
@@ -381,6 +385,9 @@ export function timeoutSignal(timeout) {
  * cut off while it is still moving, only once nothing has moved for `timeout`
  * ms. Rejects the way fetch does: a TypeError for a network failure, an error
  * named TimeoutError for a stall.
+ * @param {string} url
+ * @param {{method: string, headers: Record<string, string>, body: any}} request
+ * @param {{onUploadProgress?: (progress: {loaded: number, total: number | null}) => void, timeout?: number | null}} [options]
  */
 export function xhrSend(
   url,

package/src/ids.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A fresh UUIDv7, later than every one this page minted before it.
+ * @returns {string}
+ */
+export function uuidv7(): string;
+/**
+ * A random UUIDv4, for ids that need no order (an operation group, a lock
+ * holder). Built on `crypto.getRandomValues`, since `crypto.randomUUID`
+ * exists only in a secure context and a page served over plain HTTP from
+ * another host than localhost is not one.
+ * @returns {string}
+ */
+export function uuidv4(): string;
+/**
+ * A user id as the server stores it. A user's id is their email address,
+ * trimmed of every whitespace, control and format character at either end
+ * and lowercased, in NFC before and after (a capital with no composed form,
+ * such as J̌, lowercases to one that has one, ǰ), so `Ana@Example.org` and
+ * `ana@example.org` name one account. Compare a typed address with an id
+ * through this. The rule is core's (`plaid.sql.user/normalize-id`), checked
+ * against its case table.
+ * Anything but a string comes back unchanged.
+ * @param {string} id
+ * @returns {string}
+ */
+export function normalizeUserId(id: string): string;

package/src/ids.js

@@ -52,3 +52,45 @@ export function uuidv7() {
   }
   return s;
 }
+
+/**
+ * A random UUIDv4, for ids that need no order (an operation group, a lock
+ * holder). Built on `crypto.getRandomValues`, since `crypto.randomUUID`
+ * exists only in a secure context and a page served over plain HTTP from
+ * another host than localhost is not one.
+ * @returns {string}
+ */
+export function uuidv4() {
+  const b = new Uint8Array(16);
+  crypto.getRandomValues(b);
+  b[6] = (b[6] & 0x0f) | 0x40;
+  b[8] = (b[8] & 0x3f) | 0x80;
+  let s = "";
+  for (let i = 0; i < 16; i++) {
+    s += hex[b[i]];
+    if (i === 3 || i === 5 || i === 7 || i === 9) s += "-";
+  }
+  return s;
+}
+
+// Whitespace, control and format characters at either end of an id (NBSP,
+// the BOM, zero-width and bidi marks as well as ASCII blanks), as core trims.
+const ID_EDGES = /^[\p{Z}\p{Cc}\p{Cf}]+|[\p{Z}\p{Cc}\p{Cf}]+$/gu;
+
+/**
+ * A user id as the server stores it. A user's id is their email address,
+ * trimmed of every whitespace, control and format character at either end
+ * and lowercased, in NFC before and after (a capital with no composed form,
+ * such as J̌, lowercases to one that has one, ǰ), so `Ana@Example.org` and
+ * `ana@example.org` name one account. Compare a typed address with an id
+ * through this. The rule is core's (`plaid.sql.user/normalize-id`), checked
+ * against its case table.
+ * Anything but a string comes back unchanged.
+ * @param {string} id
+ * @returns {string}
+ */
+export function normalizeUserId(id) {
+  return typeof id === "string"
+    ? id.normalize("NFC").replace(ID_EDGES, "").toLowerCase().normalize("NFC")
+    : id;
+}