@buoy-gg/shared-ui 7.0.40 → 7.0.42

package/lib/commonjs/sync/typedEdit.js

@@ -1,228 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.findKeyPath = findKeyPath;
-exports.refusalText = refusalText;
-exports.shapeKind = shapeKind;
-exports.suggestedPatch = suggestedPatch;
-exports.typedEditViolations = typedEditViolations;
-/**
- * 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. */
-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.
- */
-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.
- */
-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.
- */
-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.
- */
-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)}` : "");
-}
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.findKeyPath=findKeyPath;exports.refusalText=refusalText;exports.shapeKind=shapeKind;exports.suggestedPatch=suggestedPatch;exports.typedEditViolations=typedEditViolations;const isPlainObject=e=>!!e&&typeof e==="object"&&!Array.isArray(e);function shapeKind(e){if(Array.isArray(e))return"array";if(e===null)return"null";if(typeof e==="object")return"object";return typeof e}const SCALARS=["string","number","boolean"];function findKeyPath(e,s,i=2e3){const n=[{node:e,path:""}];let a=0;while(n.length&&a<i){const{node:t,path:o}=n.shift();a++;if(Array.isArray(t)){t.slice(0,20).forEach((d,f)=>n.push({node:d,path:`${o}[${f}]`}))}else if(isPlainObject(t)){for(const[d,f]of Object.entries(t)){const l=o?`${o}.${d}`:d;if(d===s&&o)return l;if(isPlainObject(f)||Array.isArray(f))n.push({node:f,path:l})}}}return void 0}function typedEditViolations(e,s,i={},n=e,a="",t=[]){const o=i.noun??"data";const d=a||"(root)";if(Array.isArray(s)){if(!Array.isArray(e)){t.push({path:d,kind:"type-change",detail:`${shapeKind(e)} \u2192 array`});return t}const r=e.length?e[0]:void 0;if(r!==void 0&&(isPlainObject(r)||Array.isArray(r))){s.forEach((c,u)=>{const h=`${a}[${u}]`;if(isPlainObject(r)&&isPlainObject(c)){for(const y of Object.keys(r)){if(!(y in c)){t.push({path:`${h}.${y}`,kind:"missing-key",detail:`list items need \`${y}\` \u2014 the items already in the list have it`})}}}typedEditViolations(r,c,i,n,h,t)})}return t}if(isPlainObject(s)){if(!isPlainObject(e)){t.push({path:d,kind:"type-change",detail:`${shapeKind(e)} \u2192 object`});return t}for(const[r,c]of Object.entries(s)){const u=a?`${a}.${r}`:r;if(!(r in e)){const h=findKeyPath(n,r);t.push({path:u,kind:"add-key",detail:h?`no such field here \u2014 did you mean \`${h}\`?`:`no field named \`${r}\` exists in this ${o}`,...h?{movedTo:h}:{}})}else{typedEditViolations(e[r],c,i,n,u,t)}}return t}const f=shapeKind(e);const l=shapeKind(s);const p=f==="null"&&SCALARS.includes(l);const g=l==="null"&&SCALARS.includes(f);if(f!==l&&!p&&!g){t.push({path:d,kind:"type-change",detail:`${f} \u2192 ${l}`})}return t}function suggestedPatch(e,s){if(!s.length||!s.every(n=>n.kind==="add-key"&&n.movedTo))return void 0;const i={};for(const n of s){const a=getAtDotted(e,n.path);if(a===void 0)return void 0;if(n.movedTo.includes("["))return void 0;let t=i;const o=n.movedTo.split(".");o.slice(0,-1).forEach(d=>{t[d]??={};t=t[d]});t[o[o.length-1]]=a}return i}function getAtDotted(e,s){let i=e;for(const n of s.split(".")){if(!isPlainObject(i))return void 0;i=i[n]}return i}function refusalText(e,s,i){const n=e.slice(0,6).map(t=>`\`${t.path}\`: ${t.detail}`).join("; ");const a=e.length>6?`; +${e.length-6} more`:"";return`Refused: this isn't a same-type edit of existing fields (the rule the React Query devtools enforces). ${n}${a}. You can only change the VALUE of a field that already exists, to the same type \u2014 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 ${s}. Use force:true only to deliberately break that.`+(i?` This is the same edit at the right depth \u2014 send it as the patch: ${JSON.stringify(i)}`:"")}

package/lib/commonjs/sync/valuePath.js

@@ -1,337 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.parsePath = parsePath;
-exports.patchFromPath = patchFromPath;
-exports.readPath = readPath;
-var _keyedArrays = require("./keyedArrays.js");
-/**
- * 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.
- */
-
-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.
- */
-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. */
-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.
- */
-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 = (0, _keyedArrays.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)";
-}
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.parsePath=parsePath;exports.patchFromPath=patchFromPath;exports.readPath=readPath;var _keyedArrays=require("./keyedArrays.js");const isPlainObject=r=>typeof r==="object"&&r!==null&&!Array.isArray(r);function findFieldPath(r,o,n=2e3){const e=[{node:r,path:""}];let d=0;while(e.length&&d<n){const{node:i,path:t}=e.shift();d++;if(Array.isArray(i)){i.slice(0,20).forEach((s,l)=>e.push({node:s,path:`${t}[${l}]`}))}else if(isPlainObject(i)){for(const[s,l]of Object.entries(i)){const f=t?`${t}.${s}`:s;if(s===o)return f;if(isPlainObject(l)||Array.isArray(l))e.push({node:l,path:f})}}}return void 0}function missingFieldError(r,o,n,e,d){const i=findFieldPath(r,d??n);const t=e.slice(0,12).join(", ")||"(no fields)";return i?`No field "${n}" at "${o}" \u2014 did you mean path "${i}"? "${o}" has: ${t}.`:`No field "${n}" at "${o}". It has: ${t}.`}function fieldOf(r,o){let n=r;for(const e of o.split(".")){if(!isPlainObject(n))return void 0;n=n[e]}return n}function parsePath(r){if(!r.trim())return void 0;const o=[];let n=0;while(n<r.length){if(r[n]==="."){n++;continue}if(r[n]==="["){const i=r.indexOf("]",n);if(i===-1)return void 0;const t=r.slice(n+1,i);if(/^\d+$/.test(t))o.push({kind:"index",index:Number(t)});else{const s=t.indexOf("=");if(s<=0)return void 0;o.push({kind:"match",field:t.slice(0,s).trim(),value:t.slice(s+1).trim()})}n=i+1;continue}let e=n;while(e<r.length&&r[e]!=="."&&r[e]!=="[")e++;const d=r.slice(n,e);if(!d)return void 0;o.push({kind:"key",key:d});n=e}return o.length?o:void 0}function readPath(r,o){const n=parsePath(o);if(!n)return{ok:false,error:`Could not read the path "${o}". Use dotted keys with optional [0] or [field=value], like "item.name" or "lines[lineId=seed-1].qty".`};let e=r;const d=[];for(const i of n){if(e===null||e===void 0){return{ok:false,error:`"${d.join(".")||"(root)"}" is ${e===null?"null":"not set"}, so there is nothing at "${o}".`}}if(i.kind==="key"){if(!isPlainObject(e))return{ok:false,error:`"${d.join(".")||"(root)"}" is not an object, so it has no field "${i.key}".`};if(!(i.key in e)){const t=n[n.length-1];return{ok:false,error:missingFieldError(r,d.join(".")||"(root)",i.key,Object.keys(e),t?.kind==="key"?t.key:void 0)}}e=e[i.key];d.push(i.key)}else if(i.kind==="index"){if(!Array.isArray(e))return{ok:false,error:`"${d.join(".")||"(root)"}" is not a list, so [${i.index}] means nothing.`};e=e[i.index];d.push(`[${i.index}]`)}else{if(!Array.isArray(e))return{ok:false,error:`"${d.join(".")||"(root)"}" is not a list, so [${i.field}=${i.value}] means nothing.`};const t=e.find(s=>isPlainObject(s)&&String(fieldOf(s,i.field))===i.value);if(t===void 0)return{ok:false,error:`No item with ${i.field}="${i.value}" in "${d.join(".")||"(root)"}".`};e=t;d.push(`[${i.field}=${i.value}]`)}}return{ok:true,value:e}}function patchFromPath(r,o,n){const e=parsePath(o);if(!e)return{ok:false,error:`Could not read the path "${o}". Use dotted keys with optional [0] or [field=value], like "item.name" or "lines[lineId=seed-1].qty".`};if(e[0]?.kind!=="key")return{ok:false,error:`A path must start with a field name, not a list index \u2014 "${o}" does not say which list.`};const d=(t,s)=>{if(s>=e.length)return{ok:true,patch:n};const l=e[s];if(l.kind==="key"){if(isPlainObject(t)&&!(l.key in t)&&s+1<e.length){const y=e[e.length-1];return{ok:false,error:missingFieldError(r,pathUpTo(e,s),l.key,Object.keys(t),y?.kind==="key"?y.key:void 0)}}const u=isPlainObject(t)?t[l.key]:void 0;const h=d(u,s+1);return h.ok?{ok:true,patch:{[l.key]:h.patch}}:h}if(!Array.isArray(t)){return{ok:false,error:`"${pathUpTo(e,s)}" is not a list, so "${o}" cannot be resolved. Read it first \u2014 \`shape\` on the read says what each field holds.`}}const f=l.kind==="index"?l.index:t.findIndex(u=>isPlainObject(u)&&String(fieldOf(u,l.field))===l.value);const a=f>=0?t[f]:void 0;const p=l.kind==="index"?f<0||f>=t.length:f<0;if(p){return{ok:false,error:l.kind==="index"?`"${pathUpTo(e,s)}" has ${t.length} item(s), so there is nothing at [${l.index}].`:`No item with ${l.field}="${l.value}" in "${pathUpTo(e,s)}".`}}if(!isPlainObject(a)){if(s<e.length-1){return{ok:false,error:`"${pathUpTo(e,s)}[${l.kind==="index"?l.index:`${l.field}=${l.value}`}]" holds ${a===null?"null":typeof a}, not an object, so "${o}" cannot go any deeper. Set the item itself.`}}const u=t.slice();u[f]=n;return{ok:true,patch:u}}const c=d(a,s+1);if(!c.ok)return c;const k=(0,_keyedArrays.identityField)(t);if(k)return{ok:true,patch:{[String(a[k])]:c.patch}};const $=t.slice();$[f]=isPlainObject(c.patch)?{...a,...c.patch}:c.patch;return{ok:true,patch:$}};const i=d(r,0);if(!i.ok)return i;return{ok:true,patch:i.patch}}function pathUpTo(r,o){return r.slice(0,o).map(n=>n.kind==="key"?n.key:n.kind==="index"?`[${n.index}]`:`[${n.field}=${n.value}]`).join(".").replace(/\.\[/g,"[")||"(root)"}