@buoy-gg/storage 3.0.1 → 4.0.1

package/README.md

@@ -570,7 +570,7 @@ Required storage keys can be validated for:
 ## Dependencies
 
 - `@buoy/shared-ui` - Common UI components and utilities
-- `@react-native-async-storage/async-storage` - AsyncStorage implementation (peer dependency)
+- `@react-native-async-storage/async-storage` - AsyncStorage implementation (peer dependency; supports v2 and v3 — `^2.0.0 || ^3.1.0`. Avoid 3.0.x, which has an Android build issue fixed upstream in 3.1.0.)
 - `react-native-mmkv` - MMKV storage implementation (optional peer dependency)
 - React and React Native (peer dependencies)
 

package/lib/commonjs/index.js

@@ -153,6 +153,12 @@ Object.defineProperty(exports, "storageEventStore", {
     return _storageEventStore.storageEventStore;
   }
 });
+Object.defineProperty(exports, "storageSyncAdapter", {
+  enumerable: true,
+  get: function () {
+    return _storageSyncAdapter.storageSyncAdapter;
+  }
+});
 Object.defineProperty(exports, "storageToolPreset", {
   enumerable: true,
   get: function () {
@@ -234,4 +240,5 @@ var _mmkvAvailability = require("./storage/utils/mmkvAvailability");
 var _mmkvTypeDetection = require("./storage/utils/mmkvTypeDetection");
 var _storageTimeTravelUtils = require("./storage/utils/storageTimeTravelUtils");
 var _MMKVInstanceRegistry = require("./storage/utils/MMKVInstanceRegistry");
+var _storageSyncAdapter = require("./storage/sync/storageSyncAdapter");
 var _storageEventStore = require("./storage/stores/storageEventStore");

package/lib/commonjs/storage/components/GameUIStorageBrowser.js

@@ -63,7 +63,9 @@ function GameUIStorageBrowser({
   storageDataRef,
   eventCountByKey,
   onViewHistory,
-  enabledStorageTypes
+  enabledStorageTypes,
+  pinnedKeys,
+  onTogglePin
 }) {
   const isPro = (0, _license.useIsPro)();
   const [showUpgradeModal, setShowUpgradeModal] = (0, _react.useState)(false);
@@ -173,6 +175,15 @@ function GameUIStorageBrowser({
     refresh();
   }, [refresh]);
 
+  // Hide the selected keys by adding each to the ignored-pattern filter store,
+  // then exit selection mode. Non-destructive — keys can be unhidden from the
+  // filters UI.
+  const handleHideKeys = (0, _react.useCallback)(keys => {
+    keys.forEach(k => onAddPattern?.(k.key));
+    setSelectedKeyIds(new Set());
+    setIsSelectMode(false);
+  }, [onAddPattern]);
+
   // Memoized export data for copy functionality
   const copyExportData = (0, _react.useMemo)(() => {
     const allKeys = allStorageKeys;
@@ -395,8 +406,14 @@ function GameUIStorageBrowser({
     // NOTE: MMKV instance filtering is now handled in mmkvStorageKeys memo (line 128)
     // No need to filter again here
 
+    // Float pinned keys to the top (stable — preserves existing order otherwise)
+    if (pinnedKeys && pinnedKeys.size > 0) {
+      const pinned = keys.filter(k => pinnedKeys.has(k.key));
+      const rest = keys.filter(k => !pinnedKeys.has(k.key));
+      keys = [...pinned, ...rest];
+    }
     return keys;
-  }, [sortedKeys, activeFilter, activeStorageType, ignoredPatterns, searchQuery, selectedMMKVInstance, enabledStorageTypes]);
+  }, [sortedKeys, activeFilter, activeStorageType, ignoredPatterns, searchQuery, selectedMMKVInstance, enabledStorageTypes, pinnedKeys]);
 
   // For free users, limit visible keys to FREE_TIER_KEY_LIMIT
   const visibleKeys = (0, _react.useMemo)(() => {
@@ -618,6 +635,7 @@ function GameUIStorageBrowser({
           instance: inst.instance
         })),
         onDeleteComplete: handleDeleteComplete,
+        onHideKeys: handleHideKeys,
         onSelectAll: handleSelectAll,
         onClearSelection: handleClearSelection,
         totalVisibleKeys: visibleKeys.length
@@ -630,7 +648,10 @@ function GameUIStorageBrowser({
         selectedKeys: selectedKeyIds,
         onSelectionChange: handleSelectionChange,
         eventCountByKey: eventCountByKey,
-        onViewHistory: onViewHistory
+        onViewHistory: onViewHistory,
+        onHideKey: key => handleHideKeys([key]),
+        pinnedKeys: pinnedKeys,
+        onTogglePin: onTogglePin
       }), hasLockedKeys && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.TouchableOpacity, {
         style: styles.limitBanner,
         onPress: () => setShowUpgradeModal(true),
@@ -684,7 +705,7 @@ const styles = _reactNative.StyleSheet.create({
     paddingBottom: 32
   },
   backgroundGrid: {
-    ..._reactNative.StyleSheet.absoluteFillObject,
+    ..._sharedUi.absoluteFill,
     opacity: 0.006,
     backgroundColor: _sharedUi.gameUIColors.info
   },

package/lib/commonjs/storage/components/GameUIStorageStats.js

@@ -517,7 +517,7 @@ const styles = _reactNative.StyleSheet.create({
     shadowRadius: 8
   },
   healthGridOverlay: {
-    ..._reactNative.StyleSheet.absoluteFillObject,
+    ..._sharedUi.absoluteFill,
     opacity: 0.1,
     borderWidth: 1,
     borderColor: "rgba(255, 255, 255, 0.1)",
@@ -540,7 +540,7 @@ const styles = _reactNative.StyleSheet.create({
     backgroundColor: "rgba(255, 0, 0, 0.02)"
   },
   cardGlow: {
-    ..._reactNative.StyleSheet.absoluteFillObject,
+    ..._sharedUi.absoluteFill,
     opacity: 0.3
   },
   cardHeader: {

package/lib/commonjs/storage/components/SelectionActionBar.js

@@ -8,13 +8,13 @@ var _react = require("react");
 var _reactNative = require("react-native");
 var _sharedUi = require("@buoy-gg/shared-ui");
 var _license = require("@buoy-gg/license");
-var _asyncStorage = _interopRequireDefault(require("@react-native-async-storage/async-storage"));
+var _asyncStorageCompat = require("../utils/asyncStorageCompat");
 var _jsxRuntime = require("react/jsx-runtime");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 function SelectionActionBar({
   selectedKeys,
   mmkvInstances,
   onDeleteComplete,
+  onHideKeys,
   onSelectAll,
   onClearSelection,
   totalVisibleKeys
@@ -45,6 +45,12 @@ function SelectionActionBar({
     };
   };
 
+  // Hide selected keys (adds them to the filter store; non-destructive)
+  const handleHideSelected = () => {
+    if (selectedCount === 0) return;
+    onHideKeys?.(selectedKeys);
+  };
+
   // Handle delete selected keys
   const handleDeleteSelected = () => {
     if (selectedCount === 0) return;
@@ -68,7 +74,7 @@ function SelectionActionBar({
 
           // Delete AsyncStorage keys
           if (asyncKeys.length > 0) {
-            await _asyncStorage.default.multiRemove(asyncKeys.map(k => k.key));
+            await (0, _asyncStorageCompat.removeMany)(asyncKeys.map(k => k.key));
           }
 
           // Delete MMKV keys
@@ -131,6 +137,13 @@ function SelectionActionBar({
           success: _sharedUi.macOSColors.semantic.success,
           error: _sharedUi.macOSColors.semantic.error
         }
+      }), onHideKeys && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
+        style: styles.actionButton,
+        onPress: handleHideSelected,
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.EyeOff, {
+          size: 14,
+          color: _sharedUi.macOSColors.semantic.warning
+        })
       }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
         style: styles.actionButton,
         onPress: handleDeleteSelected,

package/lib/commonjs/storage/components/StorageBrowserMode.js

@@ -20,7 +20,9 @@ function StorageBrowserMode({
   storageDataRef,
   eventCountByKey,
   onViewHistory,
-  enabledStorageTypes
+  enabledStorageTypes,
+  pinnedKeys,
+  onTogglePin
 }) {
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_GameUIStorageBrowser.GameUIStorageBrowser, {
     requiredStorageKeys: requiredStorageKeys,
@@ -32,6 +34,8 @@ function StorageBrowserMode({
     storageDataRef: storageDataRef,
     eventCountByKey: eventCountByKey,
     onViewHistory: onViewHistory,
-    enabledStorageTypes: enabledStorageTypes
+    enabledStorageTypes: enabledStorageTypes,
+    pinnedKeys: pinnedKeys,
+    onTogglePin: onTogglePin
   });
 }

package/lib/commonjs/storage/components/StorageEventDetailContent.js

@@ -241,7 +241,7 @@ function StorageEventDetailContent({
           children: "CURRENT VALUE"
         }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
           style: styles.valueHeaderBadges,
-          children: [action && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+          children: [action ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
             style: [styles.actionBadge, {
               backgroundColor: `${actionColor}20`
             }],
@@ -251,7 +251,7 @@ function StorageEventDetailContent({
               }],
               children: (0, _storageActionHelpers.translateStorageAction)(action)
             })
-          }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+          }) : null, /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
             style: styles.typeBadge,
             children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
               style: styles.typeText,

package/lib/commonjs/storage/components/StorageKeyCard.js

@@ -150,10 +150,10 @@ function StorageKeyCard({
           children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
             style: styles.storageKeyText,
             children: storageKey.key
-          }), storageKey.description && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          }), storageKey.description ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
             style: styles.descriptionText,
             children: storageKey.description
-          }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+          }) : null, /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
             style: styles.cardHeaderMeta,
             children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
               style: [styles.statusBadge, {
@@ -282,13 +282,13 @@ function StorageKeyCard({
           style: styles.typeHelperText,
           children: ["Current type: ", (0, _valueType.getValueTypeLabel)(storageKey.value)]
         })]
-      }), storageKey.lastUpdated && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      }), storageKey.lastUpdated ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
         style: styles.metaInfo,
         children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.Text, {
           style: styles.metaLabel,
-          children: ["Last updated123: ", storageKey.lastUpdated.toLocaleString()]
+          children: ["Last updated: ", storageKey.lastUpdated.toLocaleString()]
         })
-      })]
+      }) : null]
     }), isExpanded && !hasValue && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
       style: styles.cardBody,
       children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {

package/lib/commonjs/storage/components/StorageKeyRow.js

@@ -81,11 +81,18 @@ function StorageKeyRow({
   isSelected = false,
   onSelectionChange,
   eventCount,
-  onViewHistory
+  onViewHistory,
+  onHideKey,
+  isPinned = false,
+  onTogglePin
 }) {
   const config = getStatusConfig(storageKey.status);
   const hasValue = storageKey.value !== undefined && storageKey.value !== null;
 
+  // Booleans get a dedicated colored badge instead of an inline text preview so
+  // their value is scannable at a glance.
+  const isBoolean = hasValue && typeof storageKey.value === "boolean";
+
   // Format primary text - show the key
   const primaryText = storageKey.key;
 
@@ -189,7 +196,7 @@ function StorageKeyRow({
         style: styles.expandedExpected,
         children: String(storageKey.expectedValue)
       })]
-    }), storageKey.description && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+    }), storageKey.description ? /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
       style: styles.expandedRow,
       children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
         style: styles.expandedLabel,
@@ -198,7 +205,46 @@ function StorageKeyRow({
         style: styles.expandedDescription,
         children: storageKey.description
       })]
-    })]
+    }) : null, onTogglePin || onHideKey ? /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+      style: styles.actionRow,
+      children: [onTogglePin ? /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.TouchableOpacity, {
+        style: [styles.actionChip, isPinned && styles.actionChipActive],
+        onPress: () => onTogglePin(storageKey.key),
+        hitSlop: {
+          top: 6,
+          bottom: 6,
+          left: 6,
+          right: 6
+        },
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Pin, {
+          size: 12,
+          color: _sharedUi.macOSColors.semantic.info
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: [styles.actionChipText, {
+            color: _sharedUi.macOSColors.semantic.info
+          }],
+          children: isPinned ? "Unpin" : "Pin to top"
+        })]
+      }) : null, onHideKey ? /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.TouchableOpacity, {
+        style: styles.actionChip,
+        onPress: () => onHideKey(storageKey),
+        hitSlop: {
+          top: 6,
+          bottom: 6,
+          left: 6,
+          right: 6
+        },
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.EyeOff, {
+          size: 12,
+          color: _sharedUi.macOSColors.semantic.warning
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: [styles.actionChipText, {
+            color: _sharedUi.macOSColors.semantic.warning
+          }],
+          children: "Hide from list"
+        })]
+      }) : null]
+    }) : null]
   });
 
   // Handle checkbox press in select mode
@@ -233,17 +279,28 @@ function StorageKeyRow({
         statusLabel: config.label,
         statusSublabel: config.sublabel,
         primaryText: primaryText,
-        secondaryText: hasValue ? (0, _valueType.getValueTypeLabel)(storageKey.value) : undefined,
+        secondaryText: hasValue ? isBoolean ? (0, _valueType.getValueTypeLabel)(storageKey.value) : (0, _valueType.getValueTypeWithPreview)(storageKey.value) : undefined,
+        secondaryAccessory: isBoolean ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.PillBadge, {
+          size: "sm",
+          color: storageKey.value ? _sharedUi.macOSColors.semantic.success : _sharedUi.macOSColors.semantic.error,
+          children: storageKey.value ? "true" : "false"
+        }) : undefined,
         expandedContent: expandedContent,
         isExpanded: isExpanded,
         expandedGlowColor: config.color,
-        customBadge: /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.PillBadge, {
-          color: getStorageTypeColor(storageKey.storageType),
-          children: storageTypeLabel
+        customBadge: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+          style: styles.badgeRow,
+          children: [isPinned && /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Pin, {
+            size: 12,
+            color: _sharedUi.macOSColors.semantic.info
+          }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.PillBadge, {
+            color: getStorageTypeColor(storageKey.storageType),
+            children: storageTypeLabel
+          })]
         }),
         showChevron: !isSelectMode,
         onPress: isSelectMode ? handleCheckboxPress : onPress ? () => onPress(storageKey) : undefined
-      }), eventCount != null && eventCount > 0 && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      }), eventCount != null && eventCount > 1 && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
         style: [styles.absCountBadge, {
           backgroundColor: _sharedUi.macOSColors.semantic.warning + "22",
           borderColor: _sharedUi.macOSColors.semantic.warning + "55"
@@ -272,6 +329,11 @@ const getStorageTypeColor = storageType => {
   }
 };
 const styles = _reactNative.StyleSheet.create({
+  badgeRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6
+  },
   expandedContainer: {
     gap: 8
   },
@@ -345,6 +407,33 @@ const styles = _reactNative.StyleSheet.create({
     fontWeight: "700",
     fontFamily: "monospace"
   },
+  actionRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    flexWrap: "wrap",
+    gap: 8,
+    marginTop: 4
+  },
+  actionChip: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+    paddingVertical: 6,
+    paddingHorizontal: 10,
+    borderRadius: 6,
+    backgroundColor: _sharedUi.macOSColors.background.card,
+    borderWidth: 1,
+    borderColor: _sharedUi.macOSColors.border.default
+  },
+  actionChipActive: {
+    backgroundColor: _sharedUi.macOSColors.semantic.info + "15",
+    borderColor: _sharedUi.macOSColors.semantic.info + "44"
+  },
+  actionChipText: {
+    fontSize: 11,
+    fontWeight: "600",
+    fontFamily: "monospace"
+  },
   viewHistoryButton: {
     marginLeft: 4
   },

package/lib/commonjs/storage/components/StorageKeySection.js

@@ -27,7 +27,10 @@ function StorageKeySection({
   selectedKeys = new Set(),
   onSelectionChange,
   eventCountByKey,
-  onViewHistory
+  onViewHistory,
+  onHideKey,
+  pinnedKeys,
+  onTogglePin
 }) {
   const [expandedKey, setExpandedKey] = (0, _react.useState)(null);
   const handleKeyPress = (0, _react.useCallback)(storageKey => {
@@ -60,14 +63,14 @@ function StorageKeySection({
   if (keys.length === 0) return null;
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
     style: styles.sectionContainer,
-    children: [title && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_sharedUi.SectionHeader, {
+    children: [title ? /*#__PURE__*/(0, _jsxRuntime.jsxs)(_sharedUi.SectionHeader, {
       children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.SectionHeader.Title, {
         children: title
       }), count >= 0 && /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.SectionHeader.Badge, {
         count: count,
         color: headerColor
       })]
-    }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    }) : null, /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
       style: styles.sectionContent,
       children: keys.map(storageKey => {
         // Create unique key by combining storage type, instance ID (if present), and key name
@@ -80,7 +83,10 @@ function StorageKeySection({
           isSelected: selectedKeys.has(uniqueKey),
           onSelectionChange: onSelectionChange,
           eventCount: eventCountByKey?.[storageKey.key],
-          onViewHistory: onViewHistory ? () => onViewHistory(storageKey.key) : undefined
+          onViewHistory: onViewHistory ? () => onViewHistory(storageKey.key) : undefined,
+          onHideKey: onHideKey,
+          isPinned: pinnedKeys?.has(storageKey.key),
+          onTogglePin: onTogglePin
         }, uniqueKey);
       })
     })]

package/lib/commonjs/storage/components/StorageModalWithTabs.js

@@ -60,8 +60,10 @@ function StorageModalWithTabs({
   );
   const [enabledStorageTypes, setEnabledStorageTypes] = (0, _react.useState)(new Set(['async', 'mmkv', 'secure']) // All enabled by default
   );
+  const [pinnedKeys, setPinnedKeys] = (0, _react.useState)(new Set());
   const lastEventRef = (0, _react.useRef)(null);
   const hasLoadedFilters = (0, _react.useRef)(false);
+  const hasLoadedPins = (0, _react.useRef)(false);
   const hasLoadedTabState = (0, _react.useRef)(false);
   const hasLoadedMonitoringState = (0, _react.useRef)(false);
 
@@ -176,6 +178,37 @@ function StorageModalWithTabs({
     saveFilters();
   }, [ignoredPatterns]);
 
+  // Load persisted pinned keys on mount
+  (0, _react.useEffect)(() => {
+    if (!visible || hasLoadedPins.current) return;
+    const loadPins = async () => {
+      try {
+        const stored = await _asyncStorage.default.getItem(_sharedUi.devToolsStorageKeys.storage.pinnedKeys());
+        if (stored) {
+          setPinnedKeys(new Set(JSON.parse(stored)));
+        }
+        hasLoadedPins.current = true;
+      } catch (error) {
+        // Failed to load pinned keys
+      }
+    };
+    loadPins();
+  }, [visible]);
+
+  // Save pinned keys when they change
+  (0, _react.useEffect)(() => {
+    if (!hasLoadedPins.current) return; // Don't save on initial load
+
+    const savePins = async () => {
+      try {
+        await _asyncStorage.default.setItem(_sharedUi.devToolsStorageKeys.storage.pinnedKeys(), JSON.stringify(Array.from(pinnedKeys)));
+      } catch (error) {
+        // Failed to save pinned keys
+      }
+    };
+    savePins();
+  }, [pinnedKeys]);
+
   // Event listener setup - now handled by useStorageEvents hook
   // The hook subscribes to the centralized storageEventStore
 
@@ -210,6 +243,17 @@ function StorageModalWithTabs({
   const handleAddPattern = (0, _react.useCallback)(pattern => {
     setIgnoredPatterns(prev => new Set([...prev, pattern]));
   }, []);
+  const handleTogglePin = (0, _react.useCallback)(key => {
+    setPinnedKeys(prev => {
+      const next = new Set(prev);
+      if (next.has(key)) {
+        next.delete(key);
+      } else {
+        next.add(key);
+      }
+      return next;
+    });
+  }, []);
   const handleToggleFilters = (0, _react.useCallback)(() => {
     setShowFilters(!showFilters);
   }, [showFilters]);
@@ -508,7 +552,9 @@ function StorageModalWithTabs({
         storageDataRef: storageDataRef,
         eventCountByKey: eventCountByKey,
         onViewHistory: handleViewHistoryFromBrowser,
-        enabledStorageTypes: enabledStorageTypes
+        enabledStorageTypes: enabledStorageTypes,
+        pinnedKeys: pinnedKeys,
+        onTogglePin: handleTogglePin
       });
     }
 

package/lib/commonjs/storage/hooks/useAsyncStorageKeys.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.useAsyncStorageKeys = useAsyncStorageKeys;
 var _react = require("react");
 var _asyncStorage = _interopRequireDefault(require("@react-native-async-storage/async-storage"));
+var _asyncStorageCompat = require("../utils/asyncStorageCompat");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 function useAsyncStorageKeys(requiredStorageKeys = []) {
   // State management
@@ -13,8 +14,18 @@ function useAsyncStorageKeys(requiredStorageKeys = []) {
   const [isLoading, setIsLoading] = (0, _react.useState)(true);
   const [error, setError] = (0, _react.useState)(null);
 
+  // Callers routinely pass a fresh array literal (or rely on the `= []`
+  // default, which is a new array every render). Depending on its identity
+  // would recreate `fetchStorageData` each render, re-fire the effect, and
+  // loop AsyncStorage.getAllKeys/multiGet forever. Depend on a stable content
+  // signature instead, and read the latest array via a ref inside the fetch.
+  const requiredSignature = JSON.stringify(requiredStorageKeys);
+  const requiredRef = (0, _react.useRef)(requiredStorageKeys);
+  requiredRef.current = requiredStorageKeys;
+
   // Fetch all keys and values from AsyncStorage
   const fetchStorageData = (0, _react.useCallback)(async () => {
+    const requiredStorageKeys = requiredRef.current;
     setIsLoading(true);
     setError(null);
     try {
@@ -26,8 +37,8 @@ function useAsyncStorageKeys(requiredStorageKeys = []) {
         return;
       }
 
-      // 2. Get all values using multiGet
-      const allKeyValuePairs = await _asyncStorage.default.multiGet(allKeys);
+      // 2. Get all values (compat helper normalizes v2 multiGet / v3 getMany)
+      const allKeyValuePairs = await (0, _asyncStorageCompat.readMany)(allKeys);
 
       // 3. Process keys into StorageKeyInfo format
       const allStorageKeys = [];
@@ -111,7 +122,8 @@ function useAsyncStorageKeys(requiredStorageKeys = []) {
     } finally {
       setIsLoading(false);
     }
-  }, [requiredStorageKeys]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [requiredSignature]);
 
   // Initial fetch
   (0, _react.useEffect)(() => {

package/lib/commonjs/storage/hooks/useMMKVKeys.js

@@ -76,8 +76,16 @@ function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
   const [isLoading, setIsLoading] = (0, _react.useState)(true);
   const [error, setError] = (0, _react.useState)(null);
 
+  // Depend on a stable content signature rather than the array identity — a
+  // fresh `requiredStorageKeys` literal each render would otherwise loop the
+  // fetch effect. Read the latest array via ref inside the fetch.
+  const requiredSignature = JSON.stringify(requiredStorageKeys);
+  const requiredRef = (0, _react.useRef)(requiredStorageKeys);
+  requiredRef.current = requiredStorageKeys;
+
   // Fetch all keys and values from MMKV instance
   const fetchStorageData = (0, _react.useCallback)(() => {
+    const requiredStorageKeys = requiredRef.current;
     setIsLoading(true);
     setError(null);
     try {
@@ -209,7 +217,8 @@ function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
     } finally {
       setIsLoading(false);
     }
-  }, [instance, instanceId, requiredStorageKeys]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [instance, instanceId, requiredSignature]);
 
   // Initial fetch
   (0, _react.useEffect)(() => {
@@ -255,7 +264,15 @@ function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
   const [storageKeys, setStorageKeys] = (0, _react.useState)([]);
   const [isLoading, setIsLoading] = (0, _react.useState)(true);
   const [error, setError] = (0, _react.useState)(null);
+
+  // Depend on a stable content signature rather than the array identity — a
+  // fresh `requiredStorageKeys` literal each render would otherwise loop the
+  // fetch effect. Read the latest array via ref inside the fetch.
+  const requiredSignature = JSON.stringify(requiredStorageKeys);
+  const requiredRef = (0, _react.useRef)(requiredStorageKeys);
+  requiredRef.current = requiredStorageKeys;
   const fetchStorageData = (0, _react.useCallback)(() => {
+    const requiredStorageKeys = requiredRef.current;
     setIsLoading(true);
     setError(null);
     try {
@@ -349,7 +366,8 @@ function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
     } finally {
       setIsLoading(false);
     }
-  }, [instances, requiredStorageKeys]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [instances, requiredSignature]);
   (0, _react.useEffect)(() => {
     fetchStorageData();
   }, [fetchStorageData]);