@buoy-gg/shared-ui 7.0.34 → 7.0.36

package/lib/module/sync/typedEdit.js

@@ -0,0 +1,220 @@
+"use strict";
+
+/**
+ * The typed-edit guard — ONE implementation, for every surface that takes a
+ * merge patch from a remote caller.
+ *
+ * The rule, which is the React Query devtools value-editor rule: you may change
+ * the VALUE of a field that already exists, to the same kind of thing. You may
+ * not add a field, change a field's type, or null a list or object the screen
+ * renders. A list may grow or shrink — carts are lists you add to — but every
+ * item in it must have the same fields as the items already there, because an
+ * item missing a field the others have is what crashes the list on render.
+ *
+ * WHY IT LIVES HERE. This existed twice, once in the zustand adapter and once in
+ * react-query, drifting slightly (one said "the ones already in the list", the
+ * other "the items"; only one had the did-you-mean hint). Jotai had NO copy at
+ * all, so `setAtom` accepted a string over a number or a one-item array over a
+ * fifty-item one with nothing to stop it. Three copies of a data-destroying
+ * safety rule is two more than anyone can keep in step — the same argument
+ * `keyedArrays.ts` makes about the expansion it owns.
+ *
+ * The one behavioural knob is `noun`: what to call the thing being edited in a
+ * refusal ("this store", "this data", "this atom"). Everything else is shared,
+ * deliberately — a rule that differs per surface is a rule nobody can state.
+ */
+
+const isPlainObject = v => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** The shape category the screen depends on: array vs object vs the rest. */
+export function shapeKind(v) {
+  if (Array.isArray(v)) return "array";
+  if (v === null) return "null";
+  if (typeof v === "object") return "object";
+  return typeof v;
+}
+const SCALARS = ["string", "number", "boolean"];
+
+/**
+ * Where a key actually lives in a nested value, as a dotted path — first match,
+ * breadth-first, capped so a huge payload cannot stall the walk.
+ *
+ * This is what turns "you put `name` at the top" into "`name` lives at
+ * `item.name`", which is the difference between a caller that gives up and one
+ * that fixes it. Ten of eleven measured `query` write failures were this exact
+ * mistake.
+ */
+export function findKeyPath(obj, key, maxNodes = 2000) {
+  const queue = [{
+    node: obj,
+    path: ""
+  }];
+  let seen = 0;
+  while (queue.length && seen < maxNodes) {
+    const {
+      node,
+      path
+    } = queue.shift();
+    seen++;
+    if (Array.isArray(node)) {
+      node.slice(0, 20).forEach((v, i) => queue.push({
+        node: v,
+        path: `${path}[${i}]`
+      }));
+    } else if (isPlainObject(node)) {
+      for (const [k, v] of Object.entries(node)) {
+        const p = path ? `${path}.${k}` : k;
+        if (k === key && path) return p; // path set => nested, not the top level
+        if (isPlainObject(v) || Array.isArray(v)) queue.push({
+          node: v,
+          path: p
+        });
+      }
+    }
+  }
+  return undefined;
+}
+/**
+ * Every way this patch would break the value it is merged into. Empty means the
+ * edit is safe to apply.
+ */
+export function typedEditViolations(current, patch, opts = {}, root = current, path = "", out = []) {
+  const noun = opts.noun ?? "data";
+  const here = path || "(root)";
+  if (Array.isArray(patch)) {
+    if (!Array.isArray(current)) {
+      out.push({
+        path: here,
+        kind: "type-change",
+        detail: `${shapeKind(current)} → array`
+      });
+      return out;
+    }
+    // Length may change — a cart is a list you add to and remove from — but each
+    // item must match the shape of the ones already there. The first item is the
+    // template; an added item missing a field the others have is what makes the
+    // list throw when it renders that field.
+    const template = current.length ? current[0] : undefined;
+    if (template !== undefined && (isPlainObject(template) || Array.isArray(template))) {
+      patch.forEach((el, i) => {
+        const ep = `${path}[${i}]`;
+        if (isPlainObject(template) && isPlainObject(el)) {
+          for (const k of Object.keys(template)) {
+            if (!(k in el)) {
+              out.push({
+                path: `${ep}.${k}`,
+                kind: "missing-key",
+                detail: `list items need \`${k}\` — the items already in the list have it`
+              });
+            }
+          }
+        }
+        typedEditViolations(template, el, opts, root, ep, out);
+      });
+    }
+    return out;
+  }
+  if (isPlainObject(patch)) {
+    if (!isPlainObject(current)) {
+      out.push({
+        path: here,
+        kind: "type-change",
+        detail: `${shapeKind(current)} → object`
+      });
+      return out;
+    }
+    for (const [k, v] of Object.entries(patch)) {
+      const p = path ? `${path}.${k}` : k;
+      if (!(k in current)) {
+        const elsewhere = findKeyPath(root, k);
+        out.push({
+          path: p,
+          kind: "add-key",
+          detail: elsewhere ? `no such field here — did you mean \`${elsewhere}\`?` : `no field named \`${k}\` exists in this ${noun}`,
+          ...(elsewhere ? {
+            movedTo: elsewhere
+          } : {})
+        });
+      } else {
+        typedEditViolations(current[k], v, opts, root, p, out);
+      }
+    }
+    return out;
+  }
+
+  // A leaf: the edit itself.
+  const ck = shapeKind(current);
+  const pk = shapeKind(patch);
+  // Filling an empty field and CLEARING one are the same kind of edit, and this
+  // guard used to allow only the first. That asymmetry had a cost: "take the
+  // promo off my bag" is `string → null`, the refusal named `force: true` as the
+  // only way through, and a model that anticipated it wrote the forced call
+  // pre-emptively — reaching for the one parameter that bypasses EVERY
+  // protection in order to do something completely ordinary. Measured on
+  // `cart/take-promo-off`: an S1 on an otherwise correct flow.
+  //
+  // Nulling a LIST or OBJECT the screen renders stays refused. That is the crash
+  // this guard exists for (`sizes.map` on null); a null scalar renders as empty.
+  const fillingNull = ck === "null" && SCALARS.includes(pk);
+  const clearingScalar = pk === "null" && SCALARS.includes(ck);
+  if (ck !== pk && !fillingNull && !clearingScalar) {
+    out.push({
+      path: here,
+      kind: "type-change",
+      detail: `${ck} → ${pk}`
+    });
+  }
+  return out;
+}
+
+/**
+ * The patch the caller should have sent, when every problem was a field written
+ * at the wrong DEPTH.
+ *
+ * The guard already worked out where each field really lives in order to say
+ * "did you mean `item.name`?", so it can rebuild the patch instead of leaving
+ * the caller to re-derive it from prose. Returns undefined unless EVERY
+ * violation is a relocatable add-key: a partial suggestion that silently drops
+ * the parts we could not fix would be worse than none, because the caller would
+ * send it, be refused again, and learn nothing.
+ */
+export function suggestedPatch(patch, violations) {
+  if (!violations.length || !violations.every(v => v.kind === "add-key" && v.movedTo)) return undefined;
+  const out = {};
+  for (const v of violations) {
+    const value = getAtDotted(patch, v.path);
+    if (value === undefined) return undefined;
+    // `movedTo` can name a list element (`results[0].name`); a merge patch
+    // cannot address one by index, and rewriting it to the id-addressed form
+    // needs the list itself. Leave those to the prose rather than suggest
+    // something that will not apply.
+    if (v.movedTo.includes("[")) return undefined;
+    let node = out;
+    const segs = v.movedTo.split(".");
+    segs.slice(0, -1).forEach(seg => {
+      node[seg] ??= {};
+      node = node[seg];
+    });
+    node[segs[segs.length - 1]] = value;
+  }
+  return out;
+}
+function getAtDotted(obj, path) {
+  let cur = obj;
+  for (const seg of path.split(".")) {
+    if (!isPlainObject(cur)) return undefined;
+    cur = cur[seg];
+  }
+  return cur;
+}
+
+/**
+ * The sentence a refusal ends with. Shared so every surface refuses in the same
+ * words — a caller that learns the rule on one tool should recognise it on the
+ * next.
+ */
+export function refusalText(violations, noun, suggestion) {
+  const listed = violations.slice(0, 6).map(v => `\`${v.path}\`: ${v.detail}`).join("; ");
+  const more = violations.length > 6 ? `; +${violations.length - 6} more` : "";
+  return `Refused: this isn't a same-type edit of existing fields (the rule the React Query devtools enforces). ${listed}${more}. ` + `You can only change the VALUE of a field that already exists, to the same type — you can't add fields, change a field's type, ` + `or null a list/object the screen renders. Clearing a scalar to null is fine. Send just the field(s) you're changing, nested to ` + `match the current shape of this ${noun}. Use force:true only to deliberately break that.` + (suggestion ? ` This is the same edit at the right depth — send it as the patch: ${JSON.stringify(suggestion)}` : "");
+}

package/lib/module/sync/valuePath.js

@@ -0,0 +1,330 @@
+"use strict";
+
+/**
+ * Addressing a single value inside cached data or a store — one implementation,
+ * shared by every adapter that reads or merges.
+ *
+ * WHY. The most common measured write failure is not a wrong value, it is a
+ * wrong DEPTH: ten of eleven `query` failures on the bench sent `{name: "x"}`
+ * for a payload shaped `{item: {name}}`. That is not a missing instruction — the
+ * system prompt says, verbatim, "if the value is {item:{name}} send
+ * {"item":{"name":"test123"}}, never {name}" — and models that had just called
+ * `getQueryData` still flattened it. The rule is being read past, not missed.
+ *
+ * So stop asking. `path: "item.name", value: "x"` has no depth to get wrong:
+ * there is exactly one way to write it and the adapter builds the nested patch.
+ * The same syntax on the READ side returns one slice instead of a payload that
+ * gets cut off at the engine's 24,000-character cap, which is the other half of
+ * the same problem — a caller cannot write a shape it was never able to see.
+ *
+ * Lists are addressed by IDENTITY, never by position. `lines[0]` is resolved to
+ * the id of whatever is at index 0 right now and rewritten as an id-addressed
+ * edit, because between the read and the write an item may have been removed and
+ * index 0 is then a different row. A list whose items carry no stable id is
+ * refused rather than guessed at — see keyedArrays.ts for why silently picking a
+ * row is the failure mode that loses data.
+ */
+import { identityField } from "./keyedArrays.js";
+const isPlainObject = v => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * Where a field of this name actually lives, as a dotted path — breadth-first,
+ * capped so a big payload cannot stall the walk.
+ *
+ * A wrong `path` is not the same mistake as a wrong depth, and `path` does not
+ * prevent it. Measured on TWO cases in one run: grok wrote
+ * `path: "item.name"` against the flat PokéAPI payload `{name, id, stats, …}`,
+ * having generalised the shape from a different screen it had seen. The value it
+ * wanted was at `name`, one segment, right there. A refusal that says so is a
+ * one-turn recovery; a refusal that only lists the available fields makes the
+ * caller re-derive it.
+ */
+function findFieldPath(obj, key, maxNodes = 2000) {
+  const queue = [{
+    node: obj,
+    path: ""
+  }];
+  let seen = 0;
+  while (queue.length && seen < maxNodes) {
+    const {
+      node,
+      path
+    } = queue.shift();
+    seen++;
+    if (Array.isArray(node)) {
+      node.slice(0, 20).forEach((v, i) => queue.push({
+        node: v,
+        path: `${path}[${i}]`
+      }));
+    } else if (isPlainObject(node)) {
+      for (const [k, v] of Object.entries(node)) {
+        const p = path ? `${path}.${k}` : k;
+        if (k === key) return p;
+        if (isPlainObject(v) || Array.isArray(v)) queue.push({
+          node: v,
+          path: p
+        });
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * "No field X here" plus, when the field exists somewhere else, the path that
+ * would have worked. `leaf` is the segment the caller was ultimately after.
+ */
+function missingFieldError(root, at, key, available, leaf) {
+  const elsewhere = findFieldPath(root, leaf ?? key);
+  const has = available.slice(0, 12).join(", ") || "(no fields)";
+  return elsewhere ? `No field "${key}" at "${at}" — did you mean path "${elsewhere}"? "${at}" has: ${has}.` : `No field "${key}" at "${at}". It has: ${has}.`;
+}
+
+/** Read a dotted field path inside one list item. */
+function fieldOf(item, field) {
+  let cur = item;
+  for (const seg of field.split(".")) {
+    if (!isPlainObject(cur)) return undefined;
+    cur = cur[seg];
+  }
+  return cur;
+}
+
+/**
+ * `lines[0].addonIds`, `item.name`, `results[name=pikachu].url` → segments.
+ *
+ * Returns undefined for syntax it does not understand rather than doing
+ * something approximate with it.
+ */
+export function parsePath(path) {
+  if (!path.trim()) return undefined;
+  const out = [];
+  // Walk the string rather than splitting on ".", because a [field=value]
+  // selector may legitimately contain a dot ("results[url=a.b/c]").
+  let i = 0;
+  while (i < path.length) {
+    if (path[i] === ".") {
+      i++;
+      continue;
+    }
+    if (path[i] === "[") {
+      const end = path.indexOf("]", i);
+      if (end === -1) return undefined;
+      const inner = path.slice(i + 1, end);
+      if (/^\d+$/.test(inner)) out.push({
+        kind: "index",
+        index: Number(inner)
+      });else {
+        const eq = inner.indexOf("=");
+        if (eq <= 0) return undefined;
+        out.push({
+          kind: "match",
+          field: inner.slice(0, eq).trim(),
+          value: inner.slice(eq + 1).trim()
+        });
+      }
+      i = end + 1;
+      continue;
+    }
+    let j = i;
+    while (j < path.length && path[j] !== "." && path[j] !== "[") j++;
+    const key = path.slice(i, j);
+    if (!key) return undefined;
+    out.push({
+      kind: "key",
+      key
+    });
+    i = j;
+  }
+  return out.length ? out : undefined;
+}
+
+/** Read the value at `path`, or undefined if any step of it does not exist. */
+export function readPath(value, path) {
+  const segs = parsePath(path);
+  if (!segs) return {
+    ok: false,
+    error: `Could not read the path "${path}". Use dotted keys with optional [0] or [field=value], like "item.name" or "lines[lineId=seed-1].qty".`
+  };
+  let cur = value;
+  const walked = [];
+  for (const seg of segs) {
+    if (cur === null || cur === undefined) {
+      return {
+        ok: false,
+        error: `"${walked.join(".") || "(root)"}" is ${cur === null ? "null" : "not set"}, so there is nothing at "${path}".`
+      };
+    }
+    if (seg.kind === "key") {
+      if (!isPlainObject(cur)) return {
+        ok: false,
+        error: `"${walked.join(".") || "(root)"}" is not an object, so it has no field "${seg.key}".`
+      };
+      if (!(seg.key in cur)) {
+        const leafSeg = segs[segs.length - 1];
+        return {
+          ok: false,
+          error: missingFieldError(value, walked.join(".") || "(root)", seg.key, Object.keys(cur), leafSeg?.kind === "key" ? leafSeg.key : undefined)
+        };
+      }
+      cur = cur[seg.key];
+      walked.push(seg.key);
+    } else if (seg.kind === "index") {
+      if (!Array.isArray(cur)) return {
+        ok: false,
+        error: `"${walked.join(".") || "(root)"}" is not a list, so [${seg.index}] means nothing.`
+      };
+      cur = cur[seg.index];
+      walked.push(`[${seg.index}]`);
+    } else {
+      if (!Array.isArray(cur)) return {
+        ok: false,
+        error: `"${walked.join(".") || "(root)"}" is not a list, so [${seg.field}=${seg.value}] means nothing.`
+      };
+      const hit = cur.find(el => isPlainObject(el) && String(fieldOf(el, seg.field)) === seg.value);
+      if (hit === undefined) return {
+        ok: false,
+        error: `No item with ${seg.field}="${seg.value}" in "${walked.join(".") || "(root)"}".`
+      };
+      cur = hit;
+      walked.push(`[${seg.field}=${seg.value}]`);
+    }
+  }
+  return {
+    ok: true,
+    value: cur
+  };
+}
+
+/**
+ * Build the merge patch that sets `path` to `value`, against the data as it is
+ * now.
+ *
+ * The result is an ordinary merge patch, so it goes through the SAME typed-edit
+ * guard as a hand-written one and gains no new powers — `path` is a way to say
+ * the same thing without being able to get the depth wrong, not a way around
+ * the rules. A list step becomes the id-addressed form, so the write stays
+ * proof against a truncated read.
+ */
+export function patchFromPath(current, path, value) {
+  const segs = parsePath(path);
+  if (!segs) return {
+    ok: false,
+    error: `Could not read the path "${path}". Use dotted keys with optional [0] or [field=value], like "item.name" or "lines[lineId=seed-1].qty".`
+  };
+  if (segs[0]?.kind !== "key") return {
+    ok: false,
+    error: `A path must start with a field name, not a list index — "${path}" does not say which list.`
+  };
+  const build = (node, at) => {
+    if (at >= segs.length) return {
+      ok: true,
+      patch: value
+    };
+    const seg = segs[at];
+    if (seg.kind === "key") {
+      // A field that does not exist is left for the typed-edit guard, which owns
+      // that decision — EXCEPT when there are more segments to walk, because
+      // then the caller is describing a shape that is not there at all and the
+      // guard's message ("no field named `item`") would not say where the value
+      // it wanted actually lives.
+      if (isPlainObject(node) && !(seg.key in node) && at + 1 < segs.length) {
+        const leafSeg = segs[segs.length - 1];
+        return {
+          ok: false,
+          error: missingFieldError(current, pathUpTo(segs, at), seg.key, Object.keys(node), leafSeg?.kind === "key" ? leafSeg.key : undefined)
+        };
+      }
+      const child = isPlainObject(node) ? node[seg.key] : undefined;
+      const inner = build(child, at + 1);
+      return inner.ok ? {
+        ok: true,
+        patch: {
+          [seg.key]: inner.patch
+        }
+      } : inner;
+    }
+    if (!Array.isArray(node)) {
+      return {
+        ok: false,
+        error: `"${pathUpTo(segs, at)}" is not a list, so "${path}" cannot be resolved. Read it first — \`shape\` on the read says what each field holds.`
+      };
+    }
+    const index = seg.kind === "index" ? seg.index : node.findIndex(el => isPlainObject(el) && String(fieldOf(el, seg.field)) === seg.value);
+    const item = index >= 0 ? node[index] : undefined;
+    const missing = seg.kind === "index" ? index < 0 || index >= node.length : index < 0;
+    if (missing) {
+      return {
+        ok: false,
+        error: seg.kind === "index" ? `"${pathUpTo(segs, at)}" has ${node.length} item(s), so there is nothing at [${seg.index}].` : `No item with ${seg.field}="${seg.value}" in "${pathUpTo(segs, at)}".`
+      };
+    }
+    /**
+     * A list of PRIMITIVES, addressed by index — `tags[0]` on
+     * `["alpha","beta"]`.
+     *
+     * The guard below used to be `!isPlainObject(item)`, which folded this in
+     * with a genuinely out-of-range index and answered `"tags" has 2 item(s),
+     * so there is nothing at [0]` — a sentence that contradicts itself, for the
+     * commonest index there is. A model reading the data, seeing two items and
+     * being told [0] and [1] are both empty has nowhere left to go.
+     *
+     * There is nothing to descend into on a string, so the index IS the leaf:
+     * rebuild the list with that one element replaced, exactly as the no-stable-id
+     * branch below does. Anything deeper genuinely cannot be resolved, and says so.
+     */
+    if (!isPlainObject(item)) {
+      if (at < segs.length - 1) {
+        return {
+          ok: false,
+          error: `"${pathUpTo(segs, at)}[${seg.kind === "index" ? seg.index : `${seg.field}=${seg.value}`}]" holds ${item === null ? "null" : typeof item}, not an object, so "${path}" cannot go any deeper. Set the item itself.`
+        };
+      }
+      const replaced = node.slice();
+      replaced[index] = value;
+      return {
+        ok: true,
+        patch: replaced
+      };
+    }
+    const inner = build(item, at + 1);
+    if (!inner.ok) return inner;
+    const idField = identityField(node);
+    // Positions move; ids do not. Prefer the addressed form whichever way the
+    // caller named the row.
+    if (idField) return {
+      ok: true,
+      patch: {
+        [String(item[idField])]: inner.patch
+      }
+    };
+
+    // No stable id — a Pokémon's `stats` are `{stat: {name}, base_stat}`, with
+    // nothing flat and unique on the item itself, and that is an ordinary shape
+    // rather than a broken one. Rebuild the whole list here instead of refusing.
+    //
+    // This is safe in a way the SAME array coming from a model is not: we are
+    // holding the current list in memory, so nothing is being reconstructed from
+    // a truncated read and no row can be dropped by omission. The caller still
+    // only named one value. What it cannot be is proof against the list changing
+    // between this call and the write, which addressing by id would be — so the
+    // id form stays preferred wherever one exists.
+    const next = node.slice();
+    next[index] = isPlainObject(inner.patch) ? {
+      ...item,
+      ...inner.patch
+    } : inner.patch;
+    return {
+      ok: true,
+      patch: next
+    };
+  };
+  const built = build(current, 0);
+  if (!built.ok) return built;
+  return {
+    ok: true,
+    patch: built.patch
+  };
+}
+function pathUpTo(segs, at) {
+  return segs.slice(0, at).map(s => s.kind === "key" ? s.key : s.kind === "index" ? `[${s.index}]` : `[${s.field}=${s.value}]`).join(".").replace(/\.\[/g, "[") || "(root)";
+}