@larc-iu/plaid-client 0.2.0-alpha.18 → 0.2.0-alpha.20

package/src/replayed.js

@@ -0,0 +1,27 @@
+// A write sent under an Idempotency-Key whose request the server had already
+// run (its first answer was lost, and the client sent it again) is answered
+// from what that first send stored, with `Idempotent-Replayed: true`, and
+// writes nothing. The client resends on its own (retryUnknown), so the header
+// never reaches the caller. It is marked on the answer instead: `replayed`,
+// true and not enumerable, so the answer reads, compares and serializes as it
+// would unmarked. Only an answer with a JSON object or list body can carry it.
+// Imports nothing.
+
+/** `value` marked as replayed, when it is an object or a list. */
+export function markReplayed(value) {
+  if (value !== null && typeof value === "object") {
+    Object.defineProperty(value, "replayed", {
+      value: true,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+  return value;
+}
+
+/** Whether a client answer was replayed from its key's first send. */
+export const wasReplayed = (answer) =>
+  answer !== null &&
+  typeof answer === "object" &&
+  Object.getOwnPropertyDescriptor(answer, "replayed")?.enumerable === false &&
+  answer.replayed === true;

package/src/roles.js

@@ -34,6 +34,23 @@ export const ROLE_KEY = 'role';
  */
 export const PRESERVE_ON_SPLIT_KEY = 'preserveOnSplit';
 
+/**
+ * Layer config key (true) asking Plaid to take a text edit plainly on the
+ * layer: an edit inside a token, or touching its edge with no whitespace
+ * between, grows or shrinks it, a typed space never splits it, a deleted one
+ * never joins two, and only a token whose whole text is deleted goes. See the
+ * manual's `Changing a text's body`.
+ */
+export const PLAIN_EDITS_KEY = 'plainEdits';
+
+/**
+ * Layer config key (true), beside PLAIN_EDITS_KEY: a space typed inside a
+ * token of the text's words splits it, the token going on the half sharing
+ * more letters with it. Declared on a word layer another app shares, it holds
+ * for the whole text.
+ */
+export const SPLIT_ON_SPACE_KEY = 'splitOnSpace';
+
 export const ROLES = Object.freeze({
   BASELINE: 'baseline',
   SENTENCE: 'sentence',

package/src/services.js

@@ -30,6 +30,50 @@ const redact = (text, secrets) => {
   return out.trim();
 };
 
+/** A write sent to the server whose answer never came back. */
+export const UNKNOWN_OUTCOME =
+  'The Plaid server did not answer. This change may or may not have been saved.';
+
+/** The server was never reached, so nothing was sent. */
+export const UNREACHABLE = 'The Plaid server could not be reached.';
+
+// A few reads travel as a POST, and saved nothing either way (the Python twin
+// and plaid-ui's errors.js keep the same list).
+const READ_POSTS = /\/api\/v1\/(?:query|login|invites\/lookup)(?:[?#]|$)/;
+
+// Node's fetch (undici) names a connection that never opened by its code: a
+// refused port, a name that did not resolve, a connect timeout. Nothing was
+// sent then. A browser's fetch says only "Failed to fetch", which cannot be
+// told apart from a reset, so it counts as sent.
+const NEVER_CONNECTED = new Set([
+  'ECONNREFUSED',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'UND_ERR_CONNECT_TIMEOUT',
+]);
+
+const neverConnected = (error) => {
+  const seen = new Set();
+  let cause = error && error.originalError;
+  while (cause && typeof cause === 'object' && !seen.has(cause)) {
+    seen.add(cause);
+    if (NEVER_CONNECTED.has(cause.code)) return true;
+    cause = cause.cause;
+  }
+  return false;
+};
+
+const networkFailure = (error) => {
+  const method = String(error.method || '').toUpperCase();
+  if (neverConnected(error)) return UNREACHABLE;
+  if (method && method !== 'GET' && method !== 'HEAD' && !READ_POSTS.test(String(error.url || ''))) {
+    return UNKNOWN_OUTCOME;
+  }
+  return 'The Plaid server did not answer.';
+};
+
 /**
  * One line about a failure that is safe to show the person who asked.
  *
@@ -38,13 +82,17 @@ const redact = (text, secrets) => {
  * own error text). The whole error still goes to the operator's console: this
  * is the requester's half only. The Python twin is `requester_message`.
  *
+ * Only a connection that never opened is "could not be reached". A write whose
+ * answer never came (a reset, a timeout) may have been saved, and says so
+ * (`UNKNOWN_OUTCOME`).
+ *
  * @param {any} error
  * @param {string[]} [secrets]
  * @returns {string}
  */
 export function requesterMessage(error, secrets = []) {
   if (error && typeof error.status === 'number') {
-    if (!error.status) return 'The Plaid server could not be reached.';
+    if (!error.status) return networkFailure(error);
     let text = String(error.message || '');
     if (error.url) text = text.split(` at ${error.url}`).join('').split(error.url).join('');
     text = text.trim().replace(/[\s,:;]+$/, '');

package/src/textEdits.js

@@ -0,0 +1,191 @@
+/**
+ * Text edit operations: composing a stream of ops into the net change.
+ *
+ * An op is one of the shapes `PATCH /texts/:id` takes:
+ *
+ *   { type: 'insert',  index, value: string }
+ *   { type: 'delete',  index, value: count }
+ *   { type: 'replace', index, length, value: string }
+ *
+ * Every index and count is in Unicode CODE POINTS (see ./codepoint.js), and
+ * the ops are in running coordinates: each op's `index` is in the body as the
+ * ops before it left it.
+ *
+ * A GAP is `{ start, end, value }` in the OLD body's coordinates: old
+ * [start, end) gives way to `value`. `composeTextEdits` turns any op stream
+ * into gaps that depend only on the net change, never on how the keystrokes
+ * came, which is also how the server reads an edit. The Python client's
+ * `plaid_client.text_edits` is the twin of this module.
+ */
+
+const codePoints = (s) => [...s];
+
+function opName(op) {
+  return JSON.stringify(op);
+}
+
+/**
+ * The op's type after checking its shape and bounds against a body of `len`
+ * code points, as the server checks it. Throws an Error otherwise.
+ */
+function checkOp(op, len) {
+  const type = op && op.type;
+  const { index, value, length } = op || {};
+  const int = Number.isInteger;
+  const wellFormed =
+    (type === 'insert' && int(index) && typeof value === 'string') ||
+    (type === 'delete' && int(index) && int(value)) ||
+    (type === 'replace' && int(index) && int(length) && typeof value === 'string');
+  if (!wellFormed) {
+    throw new Error(
+      `Malformed text edit operation: ${opName(op)}. Expected {type: "insert", index: int, ` +
+        `value: string}, {type: "delete", index: int, value: int} or {type: "replace", ` +
+        `index: int, length: int, value: string}`,
+    );
+  }
+  const inBounds =
+    type === 'insert'
+      ? index >= 0 && index <= len
+      : type === 'delete'
+        ? index >= 0 && value >= 0 && index + value <= len
+        : index >= 0 && length >= 0 && index + length <= len;
+  if (!inBounds) {
+    throw new Error(
+      `Text edit operation out of bounds: ${opName(op)} (text length is ${len} code points)`,
+    );
+  }
+  return type;
+}
+
+// How many code points an op removes and what it types.
+function opParts(type, op) {
+  if (type === 'insert') return [0, op.value];
+  if (type === 'delete') return [op.value, ''];
+  return [op.length, op.value];
+}
+
+const segLength = (seg) => (seg.old ? seg.end - seg.start : seg.chars.length);
+
+// The segment list of the new text, cut so that a segment boundary falls at
+// code point `at`. Returns the index of the first segment at or after `at`.
+function cutAt(segs, at) {
+  let pos = 0;
+  for (let i = 0; i < segs.length; i += 1) {
+    const seg = segs[i];
+    const n = segLength(seg);
+    if (at === pos) return i;
+    if (at < pos + n) {
+      const k = at - pos;
+      const left = seg.old
+        ? { old: true, start: seg.start, end: seg.start + k }
+        : { old: false, chars: seg.chars.slice(0, k) };
+      const right = seg.old
+        ? { old: true, start: seg.start + k, end: seg.end }
+        : { old: false, chars: seg.chars.slice(k) };
+      segs.splice(i, 1, left, right);
+      return i + 1;
+    }
+    pos += n;
+  }
+  return segs.length;
+}
+
+/**
+ * The net change of `ops` applied in turn to `body`, as gaps in the old
+ * body's code points: sorted, and never touching (at least one old code point
+ * is kept between two gaps). Old text deleted and typed back is typed text,
+ * and a gap whose value is the old text it removes is dropped. Throws on a
+ * malformed or out-of-bounds op.
+ */
+export function composeTextEdits(body, ops) {
+  const old = codePoints(body);
+  let segs = old.length ? [{ old: true, start: 0, end: old.length }] : [];
+  let len = old.length;
+  for (const op of ops) {
+    const type = checkOp(op, len);
+    const [del, typed] = opParts(type, op);
+    const chars = codePoints(typed);
+    const from = cutAt(segs, op.index);
+    const to = cutAt(segs, op.index + del);
+    const inserted = chars.length ? [{ old: false, chars }] : [];
+    segs.splice(from, to - from, ...inserted);
+    len += chars.length - del;
+    segs = mergeTyped(segs);
+  }
+
+  const gaps = [];
+  let kept = 0; // the old position the last kept run ended at
+  let typed = [];
+  const close = (next) => {
+    if (next > kept || typed.length) {
+      const value = typed.join('');
+      if (value !== old.slice(kept, next).join('')) gaps.push({ start: kept, end: next, value });
+    }
+    typed = [];
+  };
+  for (const seg of segs) {
+    if (seg.old) {
+      close(seg.start);
+      kept = seg.end;
+    } else {
+      typed.push(...seg.chars);
+    }
+  }
+  close(old.length);
+  return gaps;
+}
+
+// Neighbouring typed segments as one, and neighbouring old ranges as one.
+function mergeTyped(segs) {
+  const out = [];
+  for (const seg of segs) {
+    const last = out[out.length - 1];
+    if (last && !last.old && !seg.old) {
+      out[out.length - 1] = { old: false, chars: last.chars.concat(seg.chars) };
+    } else if (last && last.old && seg.old && last.end === seg.start) {
+      out[out.length - 1] = { old: true, start: last.start, end: seg.end };
+    } else if (segLength(seg) > 0) {
+      out.push(seg);
+    }
+  }
+  return out;
+}
+
+/**
+ * Gaps (old-body coordinates, sorted, not overlapping) as running ops: an
+ * insert where a gap removes nothing, a delete where it types nothing, and a
+ * replace otherwise.
+ */
+export function gapsToOps(gaps) {
+  const ops = [];
+  let shift = 0;
+  for (const { start, end, value } of gaps) {
+    const index = start + shift;
+    const typed = codePoints(value).length;
+    if (start === end) {
+      if (typed) ops.push({ type: 'insert', index, value });
+    } else if (!typed) {
+      ops.push({ type: 'delete', index, value: end - start });
+    } else {
+      ops.push({ type: 'replace', index, length: end - start, value });
+    }
+    shift += typed - (end - start);
+  }
+  return ops;
+}
+
+/**
+ * `body` with `ops` applied in turn (running coordinates, code points).
+ * Throws on a malformed or out-of-bounds op.
+ */
+export function applyTextOps(body, ops) {
+  let chars = codePoints(body);
+  for (const op of ops) {
+    const type = checkOp(op, chars.length);
+    const [del, typed] = opParts(type, op);
+    chars = chars
+      .slice(0, op.index)
+      .concat(codePoints(typed), chars.slice(op.index + del));
+  }
+  return chars.join('');
+}

package/src/transforms.js

@@ -1,3 +1,5 @@
+import { BatchRef } from "./batchRef.js";
+
 /**
  * Convert kebab-case/namespaced key to camelCase.
  * 'layer-id' -> 'layerId'
@@ -39,6 +41,8 @@ const isOpaque = (key, value) =>
  */
 export function transformRequest(obj) {
   if (obj === null || obj === undefined) return obj;
+  // A batch ref is taken out whole when its write is queued.
+  if (obj instanceof BatchRef) return obj;
   if (Array.isArray(obj)) return obj.map(item => transformRequest(item));
   if (typeof obj !== 'object') return obj;