@buoy-gg/zustand 7.0.41 → 7.0.43

package/lib/commonjs/zustand/sync/zustandSyncAdapter.js

@@ -1,418 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.zustandSyncAdapter = exports.STATE_ON_DEVICE = exports.PAYLOAD_ON_DEVICE = void 0;
-var _sharedUi = require("@buoy-gg/shared-ui");
-var _zustandStateStore = require("../utils/zustandStateStore");
-const isPlainRecord = v => typeof v === "object" && v !== null && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
-
-/**
- * Merge `patch` into `base` object by object. Anything that is not a plain object
- * on both sides (arrays, primitives, class instances, functions) is taken from
- * the patch as is.
- */
-function deepMergeInto(base, patch) {
-  if (!isPlainRecord(base) || !isPlainRecord(patch)) return patch;
-  const out = {
-    ...base
-  };
-  for (const [k, v] of Object.entries(patch)) out[k] = k in base ? deepMergeInto(base[k], v) : v;
-  return out;
-}
-
-/**
- * Sentinel used in WIRE-FORM snapshots in place of raw prevState/nextState.
- * Same hazard as redux: up to 200 changes × 2 full trees on every snapshot
- * freeze/OOM-killed large apps. Dashboards fetch trees via `getChangeDetail`.
- */
-const STATE_ON_DEVICE = exports.STATE_ON_DEVICE = (0, _sharedUi.onDeviceMarker)("State", "State trees stay on the device — fetched on demand via getChangeDetail / getStoreState.");
-
-/** Wire-form sentinel for an oversized `partial` (replace can carry a whole tree). */
-const PAYLOAD_ON_DEVICE = exports.PAYLOAD_ON_DEVICE = (0, _sharedUi.onDeviceMarker)("Payload", "Partial stays on the device — fetched on demand via getChangeDetail.");
-const isPlainObject = v => !!v && typeof v === "object" && !Array.isArray(v);
-/**
- * Does this patch write into the list at `path`? Only then is an unchecked-shape
- * warning about that list worth saying — a patch that changes `promoCode` should
- * not be told about an empty `lines`.
- */
-function touchesList(patch, path) {
-  let cur = patch;
-  for (const seg of path.split(".")) {
-    if (!cur || typeof cur !== "object" || Array.isArray(cur)) return false;
-    if (!(seg in cur)) return false;
-    cur = cur[seg];
-  }
-  // An empty list stays empty; there is no new item to be unsure about.
-  return Array.isArray(cur) ? cur.length > 0 : !!cur && typeof cur === "object";
-}
-
-/** Top-level keys of an object state, for the compact (no-values) view. */
-function topLevelKeys(state) {
-  return state && typeof state === "object" && !Array.isArray(state) ? Object.keys(state) : undefined;
-}
-
-/**
- * Per-change wire cache. The store prepends and never mutates a recorded
- * change, so keying on identity is correct and self-invalidating — without it
- * every `partial` in the list is re-measured on all ~5 snapshots per second.
- */
-const toWireChange = (0, _sharedUi.memoByIdentity)(change => ({
-  ...change,
-  prevState: STATE_ON_DEVICE,
-  nextState: STATE_ON_DEVICE,
-  partial: (0, _sharedUi.toWire)(change.partial, PAYLOAD_ON_DEVICE)
-}));
-const toWireState = value => (0, _sharedUi.toWire)(value, STATE_ON_DEVICE);
-
-/**
- * Sync adapter for the zustand tool, consumed by @buoy-gg/external-sync's
- * `useExternalSync`.
- *
- * State changes are captured by the middleware (watchStores/buoyDevTools),
- * independent of whether a dashboard is watching — subscribing here only
- * streams what the store already records. The snapshot carries both the
- * change timeline and the store registry (with each store's current state)
- * so the dashboard can render the store browser.
- *
- * v2: change-log prevState/nextState are replaced with on-device markers
- * (see STATE_ON_DEVICE). Dashboards fetch trees via `getChangeDetail`.
- * Oversized / unserializable `stores[].currentState` uses the same marker
- * and is fetched via `getStoreState`.
- *
- * The `setState` action powers remote time-travel/reset from the dashboard.
- */
-const zustandSyncAdapter = exports.zustandSyncAdapter = (0, _sharedUi.createSyncAdapter)({
-  version: 2,
-  getSnapshot: () => ({
-    changes: _zustandStateStore.zustandStateStore.getStateChanges().map(toWireChange),
-    stores: _zustandStateStore.zustandStateStore.getStoreSnapshots().map(store => ({
-      ...store,
-      currentState: toWireState(store.currentState)
-    }))
-  }),
-  subscribe: [onChange => _zustandStateStore.zustandStateStore.subscribe(onChange), onChange => _zustandStateStore.zustandStateStore.subscribeToStores(onChange)],
-  actions: {
-    clearEvents: () => {
-      _zustandStateStore.zustandStateStore.clearStateChanges();
-    },
-    /**
-     * On-demand detail: one change's real prevState/nextState/partial.
-     * The per-snapshot stream stays tree-free; this is the explicit,
-     * size-guarded channel for the detail pane.
-     */
-    getChangeDetail: (0, _sharedUi.detailByIdAction)(id => _zustandStateStore.zustandStateStore.getStateChangeById(id), (change, cap) => ({
-      prevState: cap(change.prevState),
-      nextState: cap(change.nextState),
-      partial: cap(change.partial)
-    })),
-    /**
-     * On-demand current state for one store. Wire-form snapshots replace
-     * oversized / unserializable `currentState` with STATE_ON_DEVICE.
-     */
-    getStoreState: params => {
-      const {
-        storeName,
-        path
-      } = (0, _sharedUi.readParams)(params);
-      if (!storeName) return {
-        found: false,
-        reason: "missing storeName"
-      };
-      const store = _zustandStateStore.zustandStateStore.getStore(storeName);
-      if (!store) return {
-        found: false,
-        reason: "unknown storeName"
-      };
-      let currentState;
-      try {
-        currentState = store.api.getState();
-      } catch {
-        currentState = undefined;
-      }
-      // One slice instead of the whole store. The reason to want it is the
-      // engine's 24,000-character result cap: a caller that never saw the field
-      // it means to edit is left inventing a shape, which is the failure this
-      // whole surface keeps producing.
-      if (path) {
-        const at = (0, _sharedUi.readPath)(currentState, path);
-        if (!at.ok) return {
-          found: false,
-          reason: at.error
-        };
-        return {
-          found: true,
-          storeName,
-          path,
-          shape: (0, _sharedUi.shapeSummary)(at.value),
-          currentState: at.value
-        };
-      }
-      // The sketch goes BEFORE currentState, deliberately. The engine truncates
-      // a result by slicing the encoded string at 24,000 characters, so whatever
-      // is serialised first is what survives — and the reads most in need of a
-      // shape are exactly the long ones that get cut. It costs ~150 characters
-      // and does not grow with the data.
-      const shape = (0, _sharedUi.shapeSummary)(currentState);
-      if (!(0, _sharedUi.isOverWireBudget)(currentState, _sharedUi.WIRE_DETAIL_LIMIT_BYTES)) {
-        return {
-          found: true,
-          storeName,
-          ...(shape ? {
-            shape
-          } : {}),
-          currentState
-        };
-      }
-      return {
-        found: true,
-        storeName,
-        ...(shape ? {
-          shape
-        } : {}),
-        currentState: (0, _sharedUi.isJsonSerializable)(currentState) ? (0, _sharedUi.truncatedNote)(_sharedUi.WIRE_DETAIL_LIMIT_BYTES) : STATE_ON_DEVICE
-      };
-    },
-    /**
-     * Compact current-state reader for a remote driver (MCP/LLM): the registered
-     * stores with light metadata; each store's full `currentState` object stays
-     * on the device unless `includeValues` is set (compact view returns just the
-     * top-level `keys` so the shape is visible cheaply).
-     */
-    listStores: params => {
-      const {
-        includeValues = false,
-        limit
-      } = (0, _sharedUi.readParams)(params);
-      const all = _zustandStateStore.zustandStateStore.getStoreSnapshots();
-      const capped = typeof limit === "number" && limit > 0 ? all.slice(0, limit) : all;
-      const stores = capped.map(s => ({
-        name: s.name,
-        changes: s.stateChangeCount,
-        isPersisted: s.isPersisted,
-        persistName: s.persistName,
-        canRehydrate: s.canRehydrate,
-        ...(includeValues ? {
-          currentState: s.currentState
-        } : {
-          keys: topLevelKeys(s.currentState)
-        }),
-        // Cheap enough to always include: this is the compact view a caller
-        // reaches for precisely because it does not want to pull the data, and
-        // the item shape of a list is the one thing it cannot infer without it.
-        ...((0, _sharedUi.shapeSummary)(s.currentState) ? {
-          shape: (0, _sharedUi.shapeSummary)(s.currentState)
-        } : {})
-      }));
-      return {
-        stores,
-        total: all.length,
-        returned: stores.length,
-        includedValues: includeValues
-      };
-    },
-    setState: params => {
-      const {
-        storeName,
-        state,
-        replace,
-        force,
-        path,
-        value
-      } = (0, _sharedUi.readParams)(params);
-      let effective = state;
-      let keyedNotes = [];
-      let unchecked = [];
-      if (!storeName) return {
-        ok: false,
-        error: "Missing storeName."
-      };
-      const store = _zustandStateStore.zustandStateStore.getStore(storeName);
-      if (!store) return {
-        ok: false,
-        error: `No store named "${storeName}".`
-      };
-      // `path` is sugar over a merge: it can only ever produce a patch, which
-      // then goes through the guard below like any other. Its value is that
-      // there is no nesting depth for the caller to get wrong.
-      // `state` is no longer schema-required, because `path`+`value` is a valid
-      // alternative — so the handler has to be the thing that rejects NEITHER.
-      // Without this, `state` arrives undefined and falls through to
-      // `setState(undefined, true)`, which is zustand's whole-state replace: the
-      // store's data AND its action functions, gone, from a call that looks like
-      // a typo. This is the most destructive thing in this file.
-      if (state === undefined && path === undefined) {
-        return {
-          ok: false,
-          error: `Refused: no change was described. Send \`state\` with the fields to merge, or \`path\` and \`value\` to set one value.`
-        };
-      }
-      let pathed = false;
-      if (path !== undefined) {
-        if (value === undefined) {
-          return {
-            ok: false,
-            error: `Refused: sent \`path\` without \`value\`. Say what to set "${path}" to; if you mean to clear it, send value:null and the field must already be nullable.`
-          };
-        }
-        let currentForPath;
-        try {
-          currentForPath = store.api.getState();
-        } catch {
-          currentForPath = undefined;
-        }
-        const built = (0, _sharedUi.patchFromPath)(currentForPath, path, value);
-        if (!built.ok) return {
-          ok: false,
-          error: `Refused: ${built.error}`
-        };
-        effective = built.patch;
-        pathed = true;
-      }
-      // On a MERGE (replace:false), constrain it to a typed edit so a remote
-      // caller can't hand the store a field of the wrong type or a malformed
-      // new list item — the same protection the query cache has. A replace
-      // (whole-store reset) and an explicit `force` skip this.
-      if (!force && (replace === false || pathed)) {
-        let current;
-        try {
-          current = store.api.getState();
-        } catch {
-          current = undefined;
-        }
-        // Expand id-addressed list edits BEFORE validating, so the typed-edit
-        // guard below sees a real array and every existing protection still
-        // applies to the result.
-        if (current !== undefined) {
-          const expanded = (0, _sharedUi.expandKeyedArrays)(current, effective);
-          // See keyedArrays.ts: an added item whose id disagrees with the key
-          // it was sent under is ambiguous, and only this layer can say so.
-          if (expanded.error) {
-            return {
-              ok: false,
-              error: `Refused: ${expanded.error}`
-            };
-          }
-          effective = expanded.patch;
-          keyedNotes = expanded.notes;
-        }
-        // The guard builds its template from `list[0]`, so a list that is EMPTY
-        // has no template and an added item is written with nothing to check it
-        // against. That is not a rare corner: it is every "add the first thing"
-        // flow, and it is where models invent shapes, because on an empty list
-        // the item shape genuinely exists nowhere in the running app. We cannot
-        // refuse it — refusing would break adding the first item to anything —
-        // so we say so instead of letting the guess through unremarked.
-        if (current !== undefined) {
-          unchecked = (0, _sharedUi.unshapedLists)(current).filter(path => touchesList(effective, path));
-        }
-        if (current !== undefined) {
-          const violations = (0, _sharedUi.typedEditViolations)(current, effective, {
-            noun: "store"
-          });
-          if (violations.length > 0) {
-            return {
-              ok: false,
-              error: (0, _sharedUi.refusalText)(violations, "store", (0, _sharedUi.suggestedPatch)(effective, violations)),
-              ...((0, _sharedUi.suggestedPatch)(effective, violations) ? {
-                suggestedState: (0, _sharedUi.suggestedPatch)(effective, violations)
-              } : {}),
-              violations
-            };
-          }
-        }
-      }
-      // A pathed write is a merge by construction — it names one value, so it
-      // must never fall through to zustand's default whole-state replace.
-      const merging = pathed || replace === false;
-      if (merging) {
-        // zustand's own merge is shallow: `setState({ member: { crowns } }, false)`
-        // swaps the whole `member` object for `{ crowns }`. A path write always
-        // arrives in that nested form, and so does any merge that edits inside a
-        // top-level object, so fold each nested object into what the store holds
-        // now before handing it over. Arrays still replace (keyed edits were
-        // already expanded to whole arrays above).
-        let current;
-        try {
-          current = store.api.getState();
-        } catch {
-          current = undefined;
-        }
-        if (isPlainRecord(current) && isPlainRecord(effective)) {
-          const folded = {};
-          for (const [k, v] of Object.entries(effective)) folded[k] = k in current ? deepMergeInto(current[k], v) : v;
-          effective = folded;
-        }
-      }
-      store.api.setState(effective, merging ? false : replace ?? true);
-      // Say what an addressed edit resolved to. A caller that meant to change one
-      // line and sees "17 item(s) remain" has caught its own mistake.
-      return {
-        ok: true,
-        ...(path !== undefined ? {
-          path
-        } : {}),
-        ...(keyedNotes.length ? {
-          keyed: keyedNotes
-        } : {}),
-        ...(unchecked.length ? {
-          unchecked: unchecked.map(path => `\`${path}\` was empty, so nothing in the app knows what its items look like and the shape of what you added was NOT checked. If the app renders a field you left out, it will render undefined — read the store back and compare against how the screen uses it.`)
-        } : {})
-      };
-    },
-    /**
-     * Re-read a persisted store's saved value and merge it into the live store.
-     *
-     * This is what makes editing a store's storage key mean anything. The app
-     * reads that key once at startup and then holds the state in memory, so an
-     * outside write — the Storage tool, a scenario, an agent — changes the disk
-     * and nothing else, and the next time the store saves it writes its own
-     * copy straight back over the edit.
-     *
-     * `persist.rehydrate()` is plain zustand, not a devtools hook, so unlike
-     * reloading the app this also works in a release build. It merges the saved
-     * value OVER current state (zustand's default merge is
-     * `{...current, ...persisted}`), so the store's action functions survive,
-     * and it does not write back to storage unless a version migration ran —
-     * the edit stays exactly as it was typed.
-     *
-     * Two honest limits, both inherent to persist rather than to this action:
-     * a key the store's `partialize` excludes is not in the saved value and so
-     * cannot be applied, and because the merge is shallow, DELETING a top-level
-     * key from the saved JSON does not remove it from the live store.
-     */
-    rehydrate: async params => {
-      const {
-        storeName
-      } = (0, _sharedUi.readParams)(params);
-      if (!storeName) return {
-        ok: false,
-        error: "Missing storeName."
-      };
-      const store = _zustandStateStore.zustandStateStore.getStore(storeName);
-      if (!store) return {
-        ok: false,
-        error: `No store named "${storeName}".`
-      };
-      if (!store.isPersisted) {
-        return {
-          ok: false,
-          error: `"${storeName}" is not a persisted store — it has no saved copy to re-read.`
-        };
-      }
-      if (!store.rehydrate) {
-        return {
-          ok: false,
-          error: `"${storeName}" is persisted but Buoy has no rehydrate handle for it. It was probably registered before the app's persist middleware attached.`
-        };
-      }
-      await store.rehydrate();
-      return {
-        ok: true,
-        storeName,
-        persistName: store.persistName
-      };
-    }
-  }
-});
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.zustandSyncAdapter=exports.STATE_ON_DEVICE=exports.PAYLOAD_ON_DEVICE=void 0;var _sharedUi=require("@buoy-gg/shared-ui");var _zustandStateStore=require("../utils/zustandStateStore");const isPlainRecord=e=>typeof e==="object"&&e!==null&&!Array.isArray(e)&&Object.getPrototypeOf(e)===Object.prototype;function deepMergeInto(e,r){if(!isPlainRecord(e)||!isPlainRecord(r))return r;const t={...e};for(const[s,i]of Object.entries(r))t[s]=s in e?deepMergeInto(e[s],i):i;return t}const STATE_ON_DEVICE=exports.STATE_ON_DEVICE=(0,_sharedUi.onDeviceMarker)("State","State trees stay on the device \u2014 fetched on demand via getChangeDetail / getStoreState.");const PAYLOAD_ON_DEVICE=exports.PAYLOAD_ON_DEVICE=(0,_sharedUi.onDeviceMarker)("Payload","Partial stays on the device \u2014 fetched on demand via getChangeDetail.");const isPlainObject=e=>!!e&&typeof e==="object"&&!Array.isArray(e);function touchesList(e,r){let t=e;for(const s of r.split(".")){if(!t||typeof t!=="object"||Array.isArray(t))return false;if(!(s in t))return false;t=t[s]}return Array.isArray(t)?t.length>0:!!t&&typeof t==="object"}function topLevelKeys(e){return e&&typeof e==="object"&&!Array.isArray(e)?Object.keys(e):void 0}const toWireChange=(0,_sharedUi.memoByIdentity)(e=>({...e,prevState:STATE_ON_DEVICE,nextState:STATE_ON_DEVICE,partial:(0,_sharedUi.toWire)(e.partial,PAYLOAD_ON_DEVICE)}));const toWireState=e=>(0,_sharedUi.toWire)(e,STATE_ON_DEVICE);const zustandSyncAdapter=exports.zustandSyncAdapter=(0,_sharedUi.createSyncAdapter)({version:2,getSnapshot:()=>({changes:_zustandStateStore.zustandStateStore.getStateChanges().map(toWireChange),stores:_zustandStateStore.zustandStateStore.getStoreSnapshots().map(e=>({...e,currentState:toWireState(e.currentState)}))}),subscribe:[e=>_zustandStateStore.zustandStateStore.subscribe(e),e=>_zustandStateStore.zustandStateStore.subscribeToStores(e)],actions:{clearEvents:()=>{_zustandStateStore.zustandStateStore.clearStateChanges()},getChangeDetail:(0,_sharedUi.detailByIdAction)(e=>_zustandStateStore.zustandStateStore.getStateChangeById(e),(e,r)=>({prevState:r(e.prevState),nextState:r(e.nextState),partial:r(e.partial)})),getStoreState:e=>{const{storeName:r,path:t}=(0,_sharedUi.readParams)(e);if(!r)return{found:false,reason:"missing storeName"};const s=_zustandStateStore.zustandStateStore.getStore(r);if(!s)return{found:false,reason:"unknown storeName"};let i;try{i=s.api.getState()}catch{i=void 0}if(t){const o=(0,_sharedUi.readPath)(i,t);if(!o.ok)return{found:false,reason:o.error};return{found:true,storeName:r,path:t,shape:(0,_sharedUi.shapeSummary)(o.value),currentState:o.value}}const d=(0,_sharedUi.shapeSummary)(i);if(!(0,_sharedUi.isOverWireBudget)(i,_sharedUi.WIRE_DETAIL_LIMIT_BYTES)){return{found:true,storeName:r,...d?{shape:d}:{},currentState:i}}return{found:true,storeName:r,...d?{shape:d}:{},currentState:(0,_sharedUi.isJsonSerializable)(i)?(0,_sharedUi.truncatedNote)(_sharedUi.WIRE_DETAIL_LIMIT_BYTES):STATE_ON_DEVICE}},listStores:e=>{const{includeValues:r=false,limit:t}=(0,_sharedUi.readParams)(e);const s=_zustandStateStore.zustandStateStore.getStoreSnapshots();const i=typeof t==="number"&&t>0?s.slice(0,t):s;const d=i.map(o=>({name:o.name,changes:o.stateChangeCount,isPersisted:o.isPersisted,persistName:o.persistName,canRehydrate:o.canRehydrate,...r?{currentState:o.currentState}:{keys:topLevelKeys(o.currentState)},...(0,_sharedUi.shapeSummary)(o.currentState)?{shape:(0,_sharedUi.shapeSummary)(o.currentState)}:{}}));return{stores:d,total:s.length,returned:d.length,includedValues:r}},setState:e=>{const{storeName:r,state:t,replace:s,force:i,path:d,value:o}=(0,_sharedUi.readParams)(e);let u=t;let f=[];let l=[];if(!r)return{ok:false,error:"Missing storeName."};const c=_zustandStateStore.zustandStateStore.getStore(r);if(!c)return{ok:false,error:`No store named "${r}".`};if(t===void 0&&d===void 0){return{ok:false,error:`Refused: no change was described. Send \`state\` with the fields to merge, or \`path\` and \`value\` to set one value.`}}let S=false;if(d!==void 0){if(o===void 0){return{ok:false,error:`Refused: sent \`path\` without \`value\`. Say what to set "${d}" to; if you mean to clear it, send value:null and the field must already be nullable.`}}let a;try{a=c.api.getState()}catch{a=void 0}const n=(0,_sharedUi.patchFromPath)(a,d,o);if(!n.ok)return{ok:false,error:`Refused: ${n.error}`};u=n.patch;S=true}if(!i&&(s===false||S)){let a;try{a=c.api.getState()}catch{a=void 0}if(a!==void 0){const n=(0,_sharedUi.expandKeyedArrays)(a,u);if(n.error){return{ok:false,error:`Refused: ${n.error}`}}u=n.patch;f=n.notes}if(a!==void 0){l=(0,_sharedUi.unshapedLists)(a).filter(n=>touchesList(u,n))}if(a!==void 0){const n=(0,_sharedUi.typedEditViolations)(a,u,{noun:"store"});if(n.length>0){return{ok:false,error:(0,_sharedUi.refusalText)(n,"store",(0,_sharedUi.suggestedPatch)(u,n)),...(0,_sharedUi.suggestedPatch)(u,n)?{suggestedState:(0,_sharedUi.suggestedPatch)(u,n)}:{},violations:n}}}}const h=S||s===false;if(h){let a;try{a=c.api.getState()}catch{a=void 0}if(isPlainRecord(a)&&isPlainRecord(u)){const n={};for(const[p,y]of Object.entries(u))n[p]=p in a?deepMergeInto(a[p],y):y;u=n}}c.api.setState(u,h?false:s??true);return{ok:true,...d!==void 0?{path:d}:{},...f.length?{keyed:f}:{},...l.length?{unchecked:l.map(a=>`\`${a}\` was empty, so nothing in the app knows what its items look like and the shape of what you added was NOT checked. If the app renders a field you left out, it will render undefined \u2014 read the store back and compare against how the screen uses it.`)}:{}}},rehydrate:async e=>{const{storeName:r}=(0,_sharedUi.readParams)(e);if(!r)return{ok:false,error:"Missing storeName."};const t=_zustandStateStore.zustandStateStore.getStore(r);if(!t)return{ok:false,error:`No store named "${r}".`};if(!t.isPersisted){return{ok:false,error:`"${r}" is not a persisted store \u2014 it has no saved copy to re-read.`}}if(!t.rehydrate){return{ok:false,error:`"${r}" is persisted but Buoy has no rehydrate handle for it. It was probably registered before the app's persist middleware attached.`}}await t.rehydrate();return{ok:true,storeName:r,persistName:t.persistName}}}});

package/lib/commonjs/zustand/types/index.js

@@ -1 +1 @@
-"use strict";
+"use strict";