@buoy-gg/zustand 7.0.33 → 7.0.34

package/lib/module/zustand/hooks/useZustandStateChanges.js

@@ -3,51 +3,39 @@
 /**
  * Hook for consuming Zustand state changes from the store
  *
- * Mirrors useReduxActions.ts from @buoy-gg/redux
+ * The subscribe / filter / pause / clear plumbing is shared `useChangeLog`;
+ * this file owns the zustand-specific filter, stats and store registry.
  */
 
-import { useState, useEffect, useMemo, useCallback } from "react";
+import { useCallback, useMemo } from "react";
+import { useChangeLog, useSubscribedValue } from "@buoy-gg/shared-ui";
 import { zustandStateStore } from "../utils/zustandStateStore";
+function filterChanges(changes, filter) {
+  let filtered = changes;
+  if (filter.searchText) {
+    const search = filter.searchText.toLowerCase();
+    filtered = filtered.filter(c => c.storeName.toLowerCase().includes(search) || c.partialPreview.toLowerCase().includes(search) || c.changedKeys.some(k => k.toLowerCase().includes(search)));
+  }
+  if (filter.storeNames && filter.storeNames.length > 0) {
+    filtered = filtered.filter(c => filter.storeNames.includes(c.storeName));
+  }
+  if (filter.onlyWithChanges) {
+    filtered = filtered.filter(c => c.hasStateChange);
+  }
+  return filtered;
+}
+const readStores = () => zustandStateStore.getStores();
+const subscribeToStores = listener => zustandStateStore.subscribeToStores(listener);
 export function useZustandStateChanges() {
-  const [stateChanges, setStateChanges] = useState(() => zustandStateStore.getStateChanges());
-  const [stores, setStores] = useState(() => zustandStateStore.getStores());
-  const [filter, setFilter] = useState({});
-  const [isEnabled, setIsEnabled] = useState(() => zustandStateStore.getEnabled());
-
-  // Subscribe to state changes
-  useEffect(() => {
-    const unsubChanges = zustandStateStore.subscribe(newChanges => {
-      setStateChanges(newChanges);
-    });
-    const unsubStores = zustandStateStore.subscribeToStores(newStores => {
-      setStores(newStores);
-    });
-    return () => {
-      unsubChanges();
-      unsubStores();
-    };
-  }, []);
-
-  // Filter state changes — derive directly from state to avoid stale reads
-  const filteredChanges = useMemo(() => {
-    let filtered = stateChanges;
-    if (filter.searchText) {
-      const search = filter.searchText.toLowerCase();
-      filtered = filtered.filter(c => c.storeName.toLowerCase().includes(search) || c.partialPreview.toLowerCase().includes(search) || c.changedKeys.some(k => k.toLowerCase().includes(search)));
-    }
-    if (filter.storeNames && filter.storeNames.length > 0) {
-      filtered = filtered.filter(c => filter.storeNames.includes(c.storeName));
-    }
-    if (filter.onlyWithChanges) {
-      filtered = filtered.filter(c => c.hasStateChange);
-    }
-    return filtered;
-  }, [stateChanges, filter]);
+  const log = useChangeLog(zustandStateStore, {
+    filterItems: filterChanges
+  });
+  const stores = useSubscribedValue(readStores, subscribeToStores);
 
   // Get stats — derive directly from state
   const stats = useMemo(() => {
-    const total = stateChanges.length;
-    const withChanges = stateChanges.filter(c => c.hasStateChange).length;
+    const total = log.items.length;
+    const withChanges = log.items.filter(c => c.hasStateChange).length;
     return {
       totalChanges: total,
       changesWithStateChange: withChanges,
@@ -55,33 +43,25 @@ export function useZustandStateChanges() {
       storeCount: stores.length,
       averageDuration: 0
     };
-  }, [stateChanges, stores]);
+  }, [log.items, stores]);
 
   // Get unique store names
   const storeNames = useMemo(() => {
     return zustandStateStore.getUniqueStoreNames();
   }, [stores]);
-  const clearChanges = useCallback(() => {
-    zustandStateStore.clearStateChanges();
-  }, []);
-  const toggleCapture = useCallback(() => {
-    const newEnabled = !isEnabled;
-    zustandStateStore.setEnabled(newEnabled);
-    setIsEnabled(newEnabled);
-  }, [isEnabled]);
   const getChangeById = useCallback(id => {
     return zustandStateStore.getStateChangeById(id);
   }, []);
   return {
-    stateChanges,
-    filteredChanges,
-    filter,
-    setFilter,
+    stateChanges: log.items,
+    filteredChanges: log.filteredItems,
+    filter: log.filter,
+    setFilter: log.setFilter,
     stats,
     stores,
-    clearChanges,
-    isEnabled,
-    toggleCapture,
+    clearChanges: log.clear,
+    isEnabled: log.isEnabled,
+    toggleCapture: log.toggleCapture,
     storeNames,
     getChangeById
   };

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

@@ -1,25 +1,17 @@
 "use strict";
 
 import { zustandStateStore } from "../utils/zustandStateStore";
-import { isJsonSerializable, isOverWireBudget } from "@buoy-gg/shared-ui";
+import { WIRE_DETAIL_LIMIT_BYTES, createSyncAdapter, detailByIdAction, isJsonSerializable, isOverWireBudget, memoByIdentity, onDeviceMarker, readParams, toWire, truncatedNote } from "@buoy-gg/shared-ui";
 
 /**
  * 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`.
  */
-export const STATE_ON_DEVICE = Object.freeze({
-  __buoyStateOnDevice: true,
-  note: "State trees stay on the device — fetched on demand via getChangeDetail / getStoreState."
-});
+export const STATE_ON_DEVICE = 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). */
-export const PAYLOAD_ON_DEVICE = Object.freeze({
-  __buoyPayloadOnDevice: true,
-  note: "Partial stays on the device — fetched on demand via getChangeDetail."
-});
-const MAX_CHANGE_DETAIL_BYTES = 8 * 1024 * 1024;
-const MAX_WIRE_PAYLOAD_BYTES = 16 * 1024;
+export const PAYLOAD_ON_DEVICE = onDeviceMarker("Payload", "Partial stays on the device — fetched on demand via getChangeDetail.");
 /** 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;
@@ -30,31 +22,17 @@ function topLevelKeys(state) {
  * 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 changeCache = new WeakMap();
-function toWireChange(change) {
-  const cached = changeCache.get(change);
-  if (cached) return cached;
-  const wire = {
-    ...change,
-    prevState: STATE_ON_DEVICE,
-    nextState: STATE_ON_DEVICE,
-    partial: toWirePartial(change.partial)
-  };
-  changeCache.set(change, wire);
-  return wire;
-}
-function toWirePartial(value) {
-  if (value === undefined) return value;
-  return isOverWireBudget(value, MAX_WIRE_PAYLOAD_BYTES) ? PAYLOAD_ON_DEVICE : value;
-}
-function toWireState(value) {
-  return isOverWireBudget(value, MAX_WIRE_PAYLOAD_BYTES) ? STATE_ON_DEVICE : value;
-}
+const toWireChange = memoByIdentity(change => ({
+  ...change,
+  prevState: STATE_ON_DEVICE,
+  nextState: STATE_ON_DEVICE,
+  partial: toWire(change.partial, PAYLOAD_ON_DEVICE)
+}));
+const toWireState = value => toWire(value, STATE_ON_DEVICE);
 
 /**
  * Sync adapter for the zustand tool, consumed by @buoy-gg/external-sync's
- * `useExternalSync` (structurally matches its ToolSyncAdapter interface so
- * this package doesn't need a dependency on it).
+ * `useExternalSync`.
  *
  * State changes are captured by the middleware (watchStores/buoyDevTools),
  * independent of whether a dashboard is watching — subscribing here only
@@ -69,7 +47,7 @@ function toWireState(value) {
  *
  * The `setState` action powers remote time-travel/reset from the dashboard.
  */
-export const zustandSyncAdapter = {
+export const zustandSyncAdapter = createSyncAdapter({
   version: 2,
   getSnapshot: () => ({
     changes: zustandStateStore.getStateChanges().map(toWireChange),
@@ -78,14 +56,7 @@ export const zustandSyncAdapter = {
       currentState: toWireState(store.currentState)
     }))
   }),
-  subscribe: onChange => {
-    const unsubscribeChanges = zustandStateStore.subscribe(onChange);
-    const unsubscribeStores = zustandStateStore.subscribeToStores(onChange);
-    return () => {
-      unsubscribeChanges();
-      unsubscribeStores();
-    };
-  },
+  subscribe: [onChange => zustandStateStore.subscribe(onChange), onChange => zustandStateStore.subscribeToStores(onChange)],
   actions: {
     clearEvents: () => {
       zustandStateStore.clearStateChanges();
@@ -95,32 +66,11 @@ export const zustandSyncAdapter = {
      * The per-snapshot stream stays tree-free; this is the explicit,
      * size-guarded channel for the detail pane.
      */
-    getChangeDetail: params => {
-      const {
-        id
-      } = params ?? {};
-      if (!id) return {
-        found: false,
-        reason: "missing id"
-      };
-      const change = zustandStateStore.getStateChangeById(id);
-      if (!change) return {
-        found: false,
-        reason: "unknown id"
-      };
-      const cappedNote = {
-        __buoyTruncated: true,
-        note: `Exceeds the ${MAX_CHANGE_DETAIL_BYTES / (1024 * 1024)}MB detail limit — inspect it on-device.`
-      };
-      const cap = value => isOverWireBudget(value, MAX_CHANGE_DETAIL_BYTES) ? cappedNote : value;
-      return {
-        found: true,
-        id,
-        prevState: cap(change.prevState),
-        nextState: cap(change.nextState),
-        partial: cap(change.partial)
-      };
-    },
+    getChangeDetail: detailByIdAction(id => 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.
@@ -128,7 +78,7 @@ export const zustandSyncAdapter = {
     getStoreState: params => {
       const {
         storeName
-      } = params ?? {};
+      } = readParams(params);
       if (!storeName) return {
         found: false,
         reason: "missing storeName"
@@ -144,11 +94,7 @@ export const zustandSyncAdapter = {
       } catch {
         currentState = undefined;
       }
-      const cappedNote = {
-        __buoyTruncated: true,
-        note: `Exceeds the ${MAX_CHANGE_DETAIL_BYTES / (1024 * 1024)}MB detail limit — inspect it on-device.`
-      };
-      if (!isOverWireBudget(currentState, MAX_CHANGE_DETAIL_BYTES)) {
+      if (!isOverWireBudget(currentState, WIRE_DETAIL_LIMIT_BYTES)) {
         return {
           found: true,
           storeName,
@@ -158,7 +104,7 @@ export const zustandSyncAdapter = {
       return {
         found: true,
         storeName,
-        currentState: isJsonSerializable(currentState) ? cappedNote : STATE_ON_DEVICE
+        currentState: isJsonSerializable(currentState) ? truncatedNote(WIRE_DETAIL_LIMIT_BYTES) : STATE_ON_DEVICE
       };
     },
     /**
@@ -171,7 +117,7 @@ export const zustandSyncAdapter = {
       const {
         includeValues = false,
         limit
-      } = params ?? {};
+      } = readParams(params);
       const all = zustandStateStore.getStoreSnapshots();
       const capped = typeof limit === "number" && limit > 0 ? all.slice(0, limit) : all;
       const stores = capped.map(s => ({
@@ -198,7 +144,7 @@ export const zustandSyncAdapter = {
         storeName,
         state,
         replace
-      } = params ?? {};
+      } = readParams(params);
       if (!storeName) return {
         ok: false,
         error: "Missing storeName."
@@ -237,7 +183,7 @@ export const zustandSyncAdapter = {
     rehydrate: async params => {
       const {
         storeName
-      } = params ?? {};
+      } = readParams(params);
       if (!storeName) return {
         ok: false,
         error: "Missing storeName."
@@ -267,4 +213,4 @@ export const zustandSyncAdapter = {
       };
     }
   }
-};
+});

package/lib/module/zustand/utils/snapshotProvider.js

@@ -13,8 +13,7 @@
  * strips functions (recording where they were), and restore re-grafts the
  * LIVE store's functions onto the snapshot before replacing.
  */
-import { registerStateSnapshotProvider } from "@buoy-gg/shared-ui";
-import { boundedDeepEqual, jsonLikelyLargerThan } from "@buoy-gg/shared-ui/dataViewer";
+import { classifyPreviewItem, createRestoreScope, emptyRestoreResult, failedRestore, registerStateSnapshotProvider, unionKeys } from "@buoy-gg/shared-ui";
 import { zustandStateStore } from "./zustandStateStore";
 import { isPlainObjectLike, stripFunctions, STRIP_MAX_DEPTH } from "./editableState";
 
@@ -93,29 +92,13 @@ async function capture() {
 }
 async function restore(data, options) {
   const snapshot = data;
-  const excludedSet = new Set(options?.excludeKeys ?? []);
-  const includedSet = options?.includeKeys ? new Set(options.includeKeys) : null;
-  const touch = key => !excludedSet.has(key) && (!includedSet || includedSet.has(key));
-  let excludedHits = 0;
-  const result = {
-    ok: true,
-    applied: 0,
-    skipped: [],
-    warnings: []
-  };
+  const scope = createRestoreScope(options);
+  const result = emptyRestoreResult();
   if (!snapshot?.stores) {
-    return {
-      ok: false,
-      applied: 0,
-      skipped: [],
-      warnings: ["empty zustand snapshot"]
-    };
+    return failedRestore("empty zustand snapshot");
   }
   for (const [name, envelope] of Object.entries(snapshot.stores)) {
-    if (!touch(name)) {
-      excludedHits += 1;
-      continue;
-    }
+    if (!scope.allows(name)) continue;
     const info = zustandStateStore.getStore(name);
     if (!info) {
       result.skipped.push({
@@ -142,12 +125,10 @@ async function restore(data, options) {
       result.ok = false;
     }
   }
-  if (excludedHits > 0) {
-    result.warnings.push(`${excludedHits} store(s) excluded by you`);
-  }
+  const excludedWarning = scope.excludedWarning("store(s)");
+  if (excludedWarning) result.warnings.push(excludedWarning);
   return result;
 }
-const ITEM_RENDER_BYTE_LIMIT = 256 * 1024;
 
 /**
  * Per-store restore preview. Both sides are function-stripped through the
@@ -176,8 +157,7 @@ async function previewItems(target, base) {
   const items = [];
   const notes = [];
   let preservedFns = 0;
-  const names = new Set([...Object.keys(baseStores), ...Object.keys(targetStores)]);
-  for (const name of names) {
+  for (const name of unionKeys(baseStores, targetStores)) {
     const inTarget = name in targetStores;
     const inBase = name in baseStores;
     if (!inTarget) {
@@ -200,39 +180,16 @@ async function previewItems(target, base) {
       });
       continue;
     }
-    if (!inBase) {
-      items.push({
-        key: name,
-        label: name,
-        verdict: "added",
-        newValue: targetStores[name].state
-      });
-      continue;
-    }
-    const oldState = baseStores[name].state;
-    const newState = targetStores[name].state;
-    if (boundedDeepEqual(oldState, newState)) {
-      items.push({
-        key: name,
-        label: name,
-        verdict: "unchanged"
-      });
-    } else if (jsonLikelyLargerThan(oldState, ITEM_RENDER_BYTE_LIMIT) || jsonLikelyLargerThan(newState, ITEM_RENDER_BYTE_LIMIT)) {
-      items.push({
-        key: name,
-        label: name,
-        verdict: "too-large",
-        reason: "store too large to render a diff — restore still applies it"
-      });
-    } else {
-      items.push({
-        key: name,
-        label: name,
-        verdict: "changed",
-        oldValue: oldState,
-        newValue: newState
-      });
-    }
+    items.push(classifyPreviewItem({
+      key: name,
+      label: name,
+      oldValue: baseStores[name]?.state,
+      newValue: targetStores[name].state,
+      inOld: inBase,
+      inNew: true
+    }, {
+      tooLargeReason: "store too large to render a diff — restore still applies it"
+    }));
   }
   if (preservedFns > 0) {
     notes.push(`${preservedFns} store action function${preservedFns === 1 ? "" : "s"} preserved on restore (not diffed)`);