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

package/src/metadataOps.d.ts

@@ -0,0 +1,15 @@
+export function isReservedMetadataKey(key: string): boolean;
+export function metadataOps(fragment: object | null | undefined): MetadataOp[];
+export function applyMetadataOps(metadata: object | null | undefined, ops: MetadataOp[]): Record<string, any>;
+export function mergeMetadata(metadata: object | null | undefined, fragment: object | null | undefined): Record<string, any>;
+/**
+ * One metadata edit: the body of a metadata PATCH is a list of these.
+ */
+export type MetadataOp = {
+    op: "set";
+    path: string[];
+    value: any;
+} | {
+    op: "delete";
+    path: string[];
+};

package/src/metadataOps.js

@@ -0,0 +1,124 @@
+/**
+ * Metadata ops: the body of every metadata PATCH, and the `metadata` of a
+ * bulk update entry. An op is `{op: 'set', path, value}` or
+ * `{op: 'delete', path}`, where `path` is a non-empty array of keys into the
+ * nested metadata, the first a top-level key. See the manual, "Metadata".
+ */
+
+import { PLAID_NAMESPACE } from './roles.js';
+import { PROVENANCE_KEYS } from './provenance.js';
+
+/**
+ * One metadata edit: the body of a metadata PATCH is a list of these.
+ * @typedef {{op: "set", path: string[], value: any} | {op: "delete", path: string[]}} MetadataOp
+ */
+
+const RESERVED_KEYS = new Set([PLAID_NAMESPACE, ...PROVENANCE_KEYS]);
+
+/**
+ * True for a top-level metadata key Plaid keeps for itself: the shared `plaid`
+ * namespace (settings every app reads, such as the text direction) and the
+ * provenance keys. Neither is ever a user's metadata field, so an app neither
+ * lists it as one nor writes a field's value to it.
+ * @param {string} key
+ * @returns {boolean}
+ */
+export const isReservedMetadataKey = (key) => RESERVED_KEYS.has(key);
+
+// The longest top-level key the server takes, in UTF-16 code units (Java's
+// String length, which is what it counts).
+const MAX_KEY_LENGTH = 200;
+
+// Java's Character.isWhitespace, which the server's blank check uses: the
+// Unicode space separators except the three no-break spaces, and the ASCII
+// whitespace controls.
+const isJavaWhitespace = (c) =>
+  (/[\p{Zs}\p{Zl}\p{Zp}]/u.test(c) && c !== '\u00A0' && c !== '\u2007' && c !== '\u202F') ||
+  /[\t\n\u000B\f\r\u001C-\u001F]/.test(c);
+
+/**
+ * True when the server accepts `k` as a top-level metadata key: not blank,
+ * at most 200 UTF-16 code units, and no ASCII control character.
+ * @param {string} k
+ * @returns {boolean}
+ */
+const validMetadataKey = (k) =>
+  typeof k === 'string' &&
+  k.length <= MAX_KEY_LENGTH &&
+  !/[\u0000-\u001F\u007F]/.test(k) &&
+  ![...k].every(isJavaWhitespace);
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The ops that set each top-level key of `fragment`, deleting a key whose
+ * value is null. This is how a provenance fragment (verifyOnEdit,
+ * contributeOnEdit, ...) is sent as a patch.
+ * @param {object|null|undefined} fragment
+ * @returns {MetadataOp[]}
+ */
+export const metadataOps = (fragment) =>
+  Object.entries(fragment || {}).map(([k, v]) =>
+    v === null ? { op: 'delete', path: [k] } : { op: 'set', path: [k], value: v },
+  );
+
+const applyOp = (node, path, depth, o) => {
+  const [k, ...more] = path.slice(depth);
+  if (more.length === 0) {
+    const out = { ...node };
+    if (o.op === 'set') out[k] = o.value;
+    else delete out[k];
+    return out;
+  }
+  const child = Object.prototype.hasOwnProperty.call(node, k) ? node[k] : undefined;
+  if (child === undefined) {
+    return o.op === 'set' ? { ...node, [k]: applyOp({}, path, depth + 1, o) } : node;
+  }
+  if (!isObject(child)) {
+    throw new Error(
+      `Metadata path ${JSON.stringify(path.slice(0, depth + 1))} holds a value that is not an object`,
+    );
+  }
+  return { ...node, [k]: applyOp(child, path, depth + 1, o) };
+};
+
+/**
+ * Apply ops to a local copy of an entity's metadata the way the server does,
+ * for an optimistic update. Returns a new object and never mutates its input.
+ * Throws on part of what the server refuses: an empty path, an op other than
+ * set or delete, a path through a non-object, or a first key that is blank,
+ * over 200 characters or holds a control character. The server's caps on
+ * depth, key count, string length and size are not checked here.
+ * @param {object|null|undefined} metadata
+ * @param {MetadataOp[]} ops
+ * @returns {Record<string, any>}
+ */
+export const applyMetadataOps = (metadata, ops) =>
+  (ops || []).reduce((m, o) => {
+    if (!Array.isArray(o.path) || o.path.length === 0) {
+      throw new Error('A metadata op needs a non-empty path');
+    }
+    if (!validMetadataKey(o.path[0])) {
+      throw new Error('Invalid metadata key');
+    }
+    if (o.op !== 'set' && o.op !== 'delete') {
+      throw new Error(`Unknown metadata op '${o.op}': expected set or delete`);
+    }
+    if (o.op === 'set' && !('value' in o)) {
+      throw new Error('A set op needs a value');
+    }
+    return applyOp(m, o.path, 0, o);
+  }, { ...(metadata || {}) });
+
+/**
+ * Merge a top-level fragment into a local copy, a null value deleting the
+ * key: applyMetadataOps over metadataOps(fragment), so the same result as
+ * sending those ops, refused where the server would refuse them. How an app
+ * mirrors a provenance stamp (verifyOnEdit, contributeOnEdit, ...) on the row
+ * it shows. Returns a new object.
+ * @param {object|null|undefined} metadata
+ * @param {object|null|undefined} fragment
+ * @returns {Record<string, any>}
+ */
+export const mergeMetadata = (metadata, fragment) =>
+  applyMetadataOps(metadata, metadataOps(fragment));

package/src/operations.d.ts

@@ -0,0 +1,36 @@
+/**
+ * End the key frame `frame` of `group`, wherever it is among the frames open:
+ * the frame under it, or the one open over it, numbers from then on. A plain
+ * function, so a caller that borrows withOperation onto another object
+ * (test doubles do) keeps it.
+ */
+export function dropFrame(group: any, frame: any): void;
+/**
+ * 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;
+};
+/** See PlaidClient.beginOperation. */
+export function beginOperation(client: any, message: any, { groupId, kind, ref, keys, minted }?: {}): any;
+/** See PlaidClient.keySeed. */
+export function keySeed(): {
+    seed: string;
+    stamps: Map<any, any>;
+};
+/** See PlaidClient.endOperation. */
+export function endOperation(client: any, message: any): Promise<void>;
+/** See PlaidClient.withOperation. */
+export function withOperation(client: any, message: any, fn: any, { kind, ref, groupId, keys, minted }?: {}): Promise<any>;
+/**
+ * The kinds an operation may say it is (`?group-kind=`), the server's closed
+ * list (plaid.sql.operation-group/kinds). An operation of any other kind is
+ * refused when it begins, before it writes anything.
+ */
+export const OPERATION_KINDS: string[];

package/src/operations.js

@@ -0,0 +1,164 @@
+/**
+ * Logical operations: the audit-log group a run of writes is labelled with,
+ * its kind and reference, and the Idempotency-Keys that make a rerun send the
+ * same requests. The client's beginOperation, keySeed, endOperation and
+ * withOperation (whose notes say what each does) call these, with the client
+ * as `client`. The twin of plaid-client-py's operations.py.
+ */
+
+import { uuidv4, uuidv7 } from "./ids.js";
+
+/**
+ * The kinds an operation may say it is (`?group-kind=`), the server's closed
+ * list (plaid.sql.operation-group/kinds). An operation of any other kind is
+ * refused when it begins, before it writes anything.
+ */
+export const OPERATION_KINDS = [
+  "assistant-plan",
+  "service-run",
+  "import",
+  "bulk-edit",
+  "guess-adoption",
+  "repair",
+  "review",
+];
+
+/**
+ * End the key frame `frame` of `group`, wherever it is among the frames open:
+ * the frame under it, or the one open over it, numbers from then on. A plain
+ * function, so a caller that borrows withOperation onto another object
+ * (test doubles do) keeps it.
+ */
+export function dropFrame(group, frame) {
+  if (!group || !frame || group.frames[0] === frame) return;
+  group.frames = group.frames.filter((f) => f !== frame);
+}
+
+/**
+ * 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, joins) {
+  const frame = joins ? client.operationGroup?.frames.at(-1) : null;
+  const keys = frame?.keys;
+  if (!keys) return { key: uuidv7(), pin: undefined, record: () => {} };
+  const n = frame.count;
+  frame.count += 1;
+  const pinned = keys.stamps.has(n);
+  return {
+    key: `${keys.seed}.${n}`,
+    pin: pinned ? keys.stamps.get(n) : undefined,
+    record: (version) => {
+      if (!pinned) keys.stamps.set(n, version ?? null);
+    },
+  };
+}
+
+/** See PlaidClient.beginOperation. */
+export function beginOperation(client, message, { groupId, kind, ref, keys, minted } = {}) {
+  if (kind != null && !OPERATION_KINDS.includes(String(kind))) {
+    throw new Error(
+      `Unknown operation kind "${kind}". It is one of: ${OPERATION_KINDS.join(", ")}.`,
+    );
+  }
+  const frame = {
+    keys: keys || null,
+    count: 0,
+    // Any iterable of ids (a Set, an array).
+    minted: minted ? new Set(minted) : null,
+    depth: 1,
+  };
+  const open = client.operationGroup;
+  client._openedFrame = null;
+  if (open) {
+    // A nested operation joins the outer one. When it brings its own key
+    // seed or ids (a queued edit run inside a longer operation), it numbers
+    // the keys in a frame of its own until it ends, then the frame under it
+    // numbers again.
+    open.depth += 1;
+    if (keys || minted) {
+      frame.depth = open.depth;
+      open.frames.push(frame);
+      client._openedFrame = frame;
+    }
+    return open.id;
+  }
+  client.operationGroup = {
+    id: groupId ? String(groupId) : uuidv4(),
+    message: message == null ? null : String(message),
+    kind: kind == null ? null : String(kind),
+    ref: ref == null ? null : String(ref),
+    depth: 1,
+    written: false,
+    refined: undefined,
+    frames: [frame],
+  };
+  client._openedFrame = frame;
+  return client.operationGroup.id;
+}
+
+/** See PlaidClient.keySeed. */
+export function keySeed() {
+  return { seed: uuidv7(), stamps: new Map() };
+}
+
+/** See PlaidClient.endOperation. */
+export async function endOperation(client, message) {
+  const group = client.operationGroup;
+  if (!group) return;
+  if (group.depth > 1) {
+    // A frame begun at client depth by hand (beginOperation) ends here. One
+    // begun by withOperation is ended by that call itself (_dropFrame).
+    const top = group.frames.at(-1);
+    if (group.frames.length > 1 && !top.owned && top.depth === group.depth) {
+      group.frames.pop();
+    }
+    group.depth -= 1;
+    return;
+  }
+  client.operationGroup = null;
+  const refined = message !== undefined ? message : group.refined;
+  if (refined !== undefined && group.written) {
+    try {
+      await client.operationGroups.update(group.id, refined);
+    } catch (e) {
+      // 404: the group never materialized server-side (every tagged write
+      // failed or a batch was aborted). Nothing to relabel — not an error.
+      if (e.status !== 404) throw e;
+    }
+  }
+}
+
+/** See PlaidClient.withOperation. */
+export async function withOperation(client, message, fn, { kind, ref, groupId, keys, minted } = {}) {
+  client.beginOperation(message, { kind, ref, groupId, keys, minted });
+  const group = client.operationGroup;
+  // The key frame client call opened is ended by client call, whatever else
+  // began or ended meanwhile, not by whichever end comes at its depth.
+  const frame = client._openedFrame;
+  if (frame) frame.owned = true;
+  const setMessage = (msg) => {
+    if (group.depth === 1) group.refined = msg;
+  };
+  let result;
+  try {
+    result = await fn(setMessage);
+  } catch (e) {
+    // A relabel the server refuses (a token scoped to projects may not
+    // relabel a group, which names none) must not take the place of the
+    // error `fn` threw: the caller answers for that one.
+    dropFrame(group, frame);
+    try {
+      await client.endOperation();
+    } catch (relabel) {
+      console.warn('The operation was not relabelled:', relabel);
+    }
+    throw e;
+  }
+  dropFrame(group, frame);
+  await client.endOperation();
+  return result;
+}

package/src/pagination.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Fetch every page and return the full flat array of entries, transparently
+ * following `nextCursor` until it is null. This is what `.list()` calls.
+ *
+ * @param {object} client - PlaidClient instance
+ * @param {string} path - API path, e.g. '/api/v1/projects'
+ * @param {object} [opts]
+ * @param {number} [opts.pageSize=1000] - Per-request page size (limit)
+ * @param {object} [opts.query={}] - Extra query params (e.g. { 'as-of': asOf })
+ * @returns {Promise<Array>} The concatenated entries across all pages
+ */
+export function listAll(client: object, path: string, { pageSize, query }?: {
+    pageSize?: number;
+    query?: object;
+}): Promise<any[]>;
+/**
+ * Fetch a single page and return the raw envelope.
+ *
+ * @param {object} client - PlaidClient instance
+ * @param {string} path - API path
+ * @param {object} [opts]
+ * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+ * @param {string} [opts.cursor] - Opaque cursor from a previous page
+ * @param {object} [opts.query={}] - Extra query params
+ * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+ */
+export function listPage(client: object, path: string, { limit, cursor, query }?: {
+    limit?: number;
+    cursor?: string;
+    query?: object;
+}): Promise<{
+    entries: any[];
+    nextCursor: (string | null);
+}>;
+/**
+ * Async generator yielding each page's entries array in turn, following
+ * `nextCursor` until it is null.
+ *
+ * @param {object} client - PlaidClient instance
+ * @param {string} path - API path
+ * @param {object} [opts]
+ * @param {number} [opts.pageSize=1000] - Per-request page size (limit)
+ * @param {object} [opts.query={}] - Extra query params
+ * @yields {Array} The entries array for each page
+ */
+export function iterPages(client: object, path: string, { pageSize, query }?: {
+    pageSize?: number;
+    query?: object;
+}): AsyncGenerator<any, void, unknown>;

package/src/pagination.js

@@ -10,6 +10,10 @@
  * Each helper threads the client through to `client._request`, so auth
  * headers, base URL, and response transforms all apply exactly as for any
  * other request.
+ *
+ * A page is a read, so it goes over the wire even when the helper is handed a
+ * batch (see the note at the top of http.js): each page is answered from the
+ * pool, in order, against the state no batch has committed yet.
  */
 
 // Merge caller query params with paging params, dropping undefined/null so we
@@ -21,15 +25,21 @@ function buildQueryParams(query, limit, cursor) {
   return params;
 }
 
+// Every collection endpoint answers with the envelope. A bare array or any
+// other shape is a broken endpoint, so name it and stop rather than return a
+// silently truncated result.
+function entriesOf(response, path) {
+  if (!response || !Array.isArray(response.entries)) {
+    throw new Error(
+      `GET ${path} did not return a paginated envelope (no 'entries' array)`,
+    );
+  }
+  return response.entries;
+}
+
 /**
  * Fetch every page and return the full flat array of entries, transparently
- * following `nextCursor` until it is null. This is what `.list()` calls so it
- * stays backward compatible with the pre-pagination (bare-array) contract.
- *
- * NOTE: This auto-paginates and therefore CANNOT be used inside a batch — each
- * page's request needs the previous page's `nextCursor`, which doesn't exist
- * until the batch executes. It throws immediately when `client.isBatching` is
- * true. Use `listPage` for a single page inside a batch.
+ * following `nextCursor` until it is null. This is what `.list()` calls.
  *
  * @param {object} client - PlaidClient instance
  * @param {string} path - API path, e.g. '/api/v1/projects'
@@ -39,41 +49,8 @@ function buildQueryParams(query, limit, cursor) {
  * @returns {Promise<Array>} The concatenated entries across all pages
  */
 export async function listAll(client, path, { pageSize = 1000, query = {} } = {}) {
-  if (client.isBatching) {
-    throw new Error(
-      `Cannot auto-paginate ${path} inside a batch: list methods follow cursors across multiple requests, which a batch cannot do. Use listPage() for a single page inside a batch, or call list() outside the batch.`,
-    );
-  }
   const all = [];
-  let cursor = null;
-  let prevCursor;
-  do {
-    const response = await client._request('GET', path, {
-      queryParams: buildQueryParams(query, pageSize, cursor),
-    });
-    // Compatibility shim: a non-paginated server (or proxy) may return a bare
-    // array. Treat it as a terminal full result with no further paging.
-    if (Array.isArray(response)) {
-      all.push(...response);
-      break;
-    }
-    if (response && Array.isArray(response.entries)) {
-      all.push(...response.entries);
-    } else {
-      throw new Error(
-        "Unexpected list response shape (no 'entries'); server may be incompatible.",
-      );
-    }
-    prevCursor = cursor;
-    cursor = response.nextCursor;
-    // Guard against a buggy server/proxy that returns a constant non-null
-    // cursor, which would otherwise loop forever.
-    if (cursor !== null && cursor !== undefined && cursor === prevCursor) {
-      throw new Error(
-        'Pagination cursor did not advance; aborting to avoid an infinite loop.',
-      );
-    }
-  } while (cursor !== null && cursor !== undefined);
+  for await (const entries of iterPages(client, path, { pageSize, query })) all.push(...entries);
   return all;
 }
 
@@ -98,11 +75,6 @@ export async function listPage(client, path, { limit, cursor, query = {} } = {})
  * Async generator yielding each page's entries array in turn, following
  * `nextCursor` until it is null.
  *
- * NOTE: This auto-paginates and therefore CANNOT be used inside a batch — each
- * page's request needs the previous page's `nextCursor`, which doesn't exist
- * until the batch executes. It throws on first iteration when
- * `client.isBatching` is true. Use `listPage` for a single page inside a batch.
- *
  * @param {object} client - PlaidClient instance
  * @param {string} path - API path
  * @param {object} [opts]
@@ -111,18 +83,13 @@ export async function listPage(client, path, { limit, cursor, query = {} } = {})
  * @yields {Array} The entries array for each page
  */
 export async function* iterPages(client, path, { pageSize = 1000, query = {} } = {}) {
-  if (client.isBatching) {
-    throw new Error(
-      `Cannot auto-paginate ${path} inside a batch: list methods follow cursors across multiple requests, which a batch cannot do. Use listPage() for a single page inside a batch, or call list() outside the batch.`,
-    );
-  }
   let cursor = null;
   let prevCursor;
   do {
     const response = await client._request('GET', path, {
       queryParams: buildQueryParams(query, pageSize, cursor),
     });
-    const entries = (response && Array.isArray(response.entries)) ? response.entries : [];
+    const entries = entriesOf(response, path);
     // Suppress the trailing empty page that the server emits when a collection's
     // size is an exact multiple of the page size (a final full page with a
     // non-null cursor, then an empty page). Still follow the cursor below.
@@ -130,7 +97,7 @@ export async function* iterPages(client, path, { pageSize = 1000, query = {} } =
       yield entries;
     }
     prevCursor = cursor;
-    cursor = response ? response.nextCursor : null;
+    cursor = response.nextCursor;
     // Guard against a buggy server/proxy that returns a constant non-null
     // cursor, which would otherwise loop forever.
     if (cursor !== null && cursor !== undefined && cursor === prevCursor) {