@buoy-gg/storage 7.0.17 → 7.0.19

package/lib/commonjs/storage/utils/snapshotProvider.js

@@ -36,7 +36,9 @@ function status() {
     canRestore: true
   };
 }
-async function capture() {
+
+/** Shared by capture() and the live side of previewItems(). */
+async function captureStorageData() {
   const warnings = [];
   const appKeys = (await _asyncStorage.default.getAllKeys()).filter(k => !(0, _sharedUi.isDevToolsStorageKey)(k));
   const asyncPairs = (await (0, _asyncStorageCompat.readMany)(appKeys)).filter(pair => pair[1] !== null);
@@ -94,8 +96,23 @@ async function capture() {
     warnings
   };
 }
-async function restore(data) {
+async function capture() {
+  const {
+    data,
+    warnings
+  } = await captureStorageData();
+  return {
+    data,
+    warnings
+  };
+}
+async function restore(data, options) {
   const snapshot = data;
+  const excludedSet = new Set(options?.excludeKeys ?? []);
+  const includedSet = options?.includeKeys ? new Set(options.includeKeys) : null;
+  /** True when this item may be touched (scope + exclusions agree). */
+  const touch = key => !excludedSet.has(key) && (!includedSet || includedSet.has(key));
+  let excludedHits = 0;
   const result = {
     ok: true,
     applied: 0,
@@ -113,10 +130,11 @@ async function restore(data) {
 
   // ── AsyncStorage: delete app keys missing from the snapshot, write the rest ──
   try {
-    const snapPairs = (snapshot.async ?? []).filter(([k]) => !(0, _sharedUi.isDevToolsStorageKey)(k));
+    const snapPairs = (snapshot.async ?? []).filter(([k]) => !(0, _sharedUi.isDevToolsStorageKey)(k) && touch(`async:${k}`));
     const snapKeys = new Set(snapPairs.map(([k]) => k));
     const liveKeys = (await _asyncStorage.default.getAllKeys()).filter(k => !(0, _sharedUi.isDevToolsStorageKey)(k));
-    const toRemove = liveKeys.filter(k => !snapKeys.has(k));
+    const toRemove = liveKeys.filter(k => !snapKeys.has(k) && touch(`async:${k}`));
+    excludedHits += (snapshot.async ?? []).length - snapPairs.length;
     if (toRemove.length > 0) await (0, _asyncStorageCompat.removeMany)(toRemove);
     if (snapPairs.length > 0) await (0, _asyncStorageCompat.writeMany)(snapPairs);
     result.applied += snapPairs.length + toRemove.length;
@@ -149,6 +167,10 @@ async function restore(data) {
       const snapKeys = new Set(entries.map(e => e.key));
       const liveKeys = instance.getAllKeys().filter(key => !(0, _sharedUi.isDevToolsStorageKey)(key));
       for (const key of liveKeys) {
+        if (!touch(`mmkv:${id}/${key}`)) {
+          excludedHits += 1;
+          continue;
+        }
         if (!snapKeys.has(key)) {
           deleteMMKVKey(instance, key);
           result.applied += 1;
@@ -156,6 +178,7 @@ async function restore(data) {
       }
       for (const entry of entries) {
         if ((0, _sharedUi.isDevToolsStorageKey)(entry.key)) continue;
+        if (!touch(`mmkv:${id}/${entry.key}`)) continue;
         if (entry.valueType === "buffer") {
           result.skipped.push({
             id: `mmkv:${id}/${entry.key}`,
@@ -178,6 +201,10 @@ async function restore(data) {
     key,
     options
   } of _SecureStoreRegistry.secureStoreRegistry.getAll()) {
+    if (!touch(`secure:${key}`)) {
+      excludedHits += 1;
+      continue;
+    }
     if (options.requireAuthentication) {
       if (key in secureSnap) {
         result.skipped.push({
@@ -202,6 +229,7 @@ async function restore(data) {
     }
   }
   for (const key of Object.keys(secureSnap)) {
+    if (!touch(`secure:${key}`)) continue;
     if (!_SecureStoreRegistry.secureStoreRegistry.getAll().some(e => e.key === key)) {
       result.skipped.push({
         id: `secure:${key}`,
@@ -209,6 +237,9 @@ async function restore(data) {
       });
     }
   }
+  if (excludedHits > 0) {
+    result.warnings.push(`${excludedHits} item(s) excluded by you`);
+  }
   return result;
 }
 
@@ -269,11 +300,148 @@ async function clear() {
   }
   return result;
 }
+const ITEM_RENDER_CHAR_LIMIT = 256 * 1024;
+function classifyValue(key, label, oldValue, newValue, inOld, inNew) {
+  if (!inNew) return {
+    key,
+    label,
+    verdict: "removed",
+    oldValue
+  };
+  if (!inOld) return {
+    key,
+    label,
+    verdict: "added",
+    newValue
+  };
+  if (Object.is(oldValue, newValue)) return {
+    key,
+    label,
+    verdict: "unchanged"
+  };
+  const tooLarge = typeof oldValue === "string" && oldValue.length > ITEM_RENDER_CHAR_LIMIT || typeof newValue === "string" && newValue.length > ITEM_RENDER_CHAR_LIMIT;
+  if (tooLarge) {
+    return {
+      key,
+      label,
+      verdict: "too-large",
+      reason: "value too large to render a diff — restore still applies it"
+    };
+  }
+  return {
+    key,
+    label,
+    verdict: "changed",
+    oldValue,
+    newValue
+  };
+}
+
+/** Per-key restore preview across all three backends. */
+async function previewItems(target, base) {
+  const targetData = target ?? {
+    async: [],
+    mmkv: {},
+    secure: {}
+  };
+  const liveMode = base === undefined;
+  const baseData = liveMode ? (await captureStorageData()).data : base ?? {
+    async: [],
+    mmkv: {},
+    secure: {}
+  };
+  const items = [];
+  const notes = [];
+
+  // ── AsyncStorage ──
+  const oldAsync = new Map(baseData.async ?? []);
+  const newAsync = new Map(targetData.async ?? []);
+  for (const key of new Set([...oldAsync.keys(), ...newAsync.keys()])) {
+    if ((0, _sharedUi.isDevToolsStorageKey)(key)) continue;
+    items.push(classifyValue(`async:${key}`, key, oldAsync.get(key), newAsync.get(key), oldAsync.has(key), newAsync.has(key)));
+  }
+
+  // ── MMKV ──
+  const instanceIds = new Set([...Object.keys(baseData.mmkv ?? {}), ...Object.keys(targetData.mmkv ?? {})]);
+  for (const id of instanceIds) {
+    const registered = liveMode ? _MMKVInstanceRegistry.mmkvInstanceRegistry.get(id) : null;
+    const instanceUnavailable = liveMode && !registered;
+    const readOnly = liveMode && registered?.instance.isReadOnly === true;
+    const oldEntries = new Map((baseData.mmkv?.[id] ?? []).map(e => [e.key, e]));
+    const newEntries = new Map((targetData.mmkv?.[id] ?? []).map(e => [e.key, e]));
+    for (const key of new Set([...oldEntries.keys(), ...newEntries.keys()])) {
+      if ((0, _sharedUi.isDevToolsStorageKey)(key)) continue;
+      const itemKey = `mmkv:${id}/${key}`;
+      const label = `${id} · ${key}`;
+      const oldE = oldEntries.get(key);
+      const newE = newEntries.get(key);
+      let item = classifyValue(itemKey, label, oldE?.value, newE?.value, oldEntries.has(key), newEntries.has(key));
+      if (item.verdict !== "unchanged") {
+        if (instanceUnavailable) {
+          item = {
+            ...item,
+            verdict: "wont-apply",
+            reason: "MMKV instance not registered"
+          };
+        } else if (readOnly) {
+          item = {
+            ...item,
+            verdict: "wont-apply",
+            reason: "MMKV instance registered read-only"
+          };
+        } else if (newE?.valueType === "buffer" || oldE?.valueType === "buffer") {
+          item = {
+            ...item,
+            verdict: "wont-apply",
+            reason: "ArrayBuffer values cannot be restored"
+          };
+        }
+      }
+      items.push(item);
+    }
+  }
+
+  // ── SecureStore ──
+  const oldSecure = baseData.secure ?? {};
+  const newSecure = targetData.secure ?? {};
+  const registeredSecure = liveMode ? new Map(_SecureStoreRegistry.secureStoreRegistry.getAll().map(e => [e.key, e])) : null;
+  for (const key of new Set([...Object.keys(oldSecure), ...Object.keys(newSecure)])) {
+    let item = classifyValue(`secure:${key}`, key, oldSecure[key], newSecure[key], key in oldSecure, key in newSecure);
+    if (liveMode && item.verdict !== "unchanged") {
+      const entry = registeredSecure?.get(key);
+      if (!entry) {
+        item = {
+          ...item,
+          verdict: "wont-apply",
+          reason: "key no longer registered with registerSecureStoreKeys"
+        };
+      } else if (entry.options.requireAuthentication) {
+        item = {
+          ...item,
+          verdict: "wont-apply",
+          reason: "biometric-protected keys are never written"
+        };
+      }
+    }
+    items.push(item);
+  }
+  if (liveMode) {
+    const biometric = _SecureStoreRegistry.secureStoreRegistry.getAll().filter(e => e.options.requireAuthentication).length;
+    if (biometric > 0) {
+      notes.push(`${biometric} biometric-protected secure key(s) are never read or written`);
+    }
+  }
+  return {
+    items,
+    notes
+  };
+}
 (0, _sharedUi.registerStateSnapshotProvider)({
   id: "storage",
   label: "Storage",
   status,
   capture,
   restore,
-  clear
+  clear,
+  previewItems
 });

package/lib/commonjs/storage/utils/storageTimeTravelUtils.js

@@ -16,6 +16,10 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  * Provides jump and undo functionality for AsyncStorage operations.
  */
 
+function isOmittedStorageValue(value) {
+  return !!value && typeof value === "object" && value.__buoyValueOnDevice === true;
+}
+
 /**
  * Undo a single storage operation
  *
@@ -35,6 +39,9 @@ async function undoOperation(event) {
     action,
     data
   } = event;
+  if (isOmittedStorageValue(data?.prevValue) || isOmittedStorageValue(data?.prevPairs)) {
+    throw new Error("Cannot undo: previous value is still on the device — fetch getEventDetail first");
+  }
   {
     switch (action) {
       case "setItem":
@@ -113,6 +120,12 @@ async function jumpToState(events, targetEventIndex) {
   if (targetEventIndex < 0 || targetEventIndex >= events.length) {
     throw new Error(`Invalid event index: ${targetEventIndex}`);
   }
+  for (const event of events) {
+    const data = event.data;
+    if (isOmittedStorageValue(data?.value) || isOmittedStorageValue(data?.prevValue) || isOmittedStorageValue(data?.pairs) || isOmittedStorageValue(data?.prevPairs)) {
+      throw new Error("Cannot jump: some event values are still on the device — fetch getEventDetail first");
+    }
+  }
 
   // Build up the state by applying each event up to and including the target.
   // We use the final values from each event, not the operations themselves.
@@ -260,14 +273,15 @@ function canUndo(event) {
     case "setItem":
     case "mergeItem":
     case "removeItem":
-      // Can undo if we have the key
-      return !!data?.key;
+      // Can undo if we have the key — but not while prevValue is still a
+      // wire-form on-device marker (restoring that would write garbage).
+      return !!data?.key && !isOmittedStorageValue(data.prevValue);
     case "multiSet":
     case "multiRemove":
     case "multiMerge":
     case "clear":
       // Can undo if we have previous pairs
-      return !!data?.prevPairs && data.prevPairs.length > 0;
+      return !!data?.prevPairs && data.prevPairs.length > 0 && !isOmittedStorageValue(data.prevPairs);
     default:
       return false;
   }

package/lib/module/index.js

@@ -82,7 +82,12 @@ export { storageSyncAdapter } from "./storage/sync/storageSyncAdapter";
 // INTERNAL EXPORTS (For @buoy-gg/* packages only - not part of public API)
 // =============================================================================
 /** @internal */
-export { storageEventStore } from "./storage/stores/storageEventStore";
+export { storageEventStore,
+// Exported so remote mirrors (Buoy Desktop) can ask "did the device withhold
+// this value?" without re-deriving the wire contract — and, in the case of
+// `batchPairsOf`, without re-introducing the union-narrowing bug that reading
+// `pairs`/`prevPairs` off a StorageEvent invites.
+isValueOnDevice, batchPairsOf } from "./storage/stores/storageEventStore";
 /**
  * Tell a mounted storage browser to re-read every backend. Used by the desktop
  * dashboard, where local storage listeners are suppressed and device data