@buoy-gg/storage 1.7.2

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

@@ -0,0 +1,362 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useMMKVKeys = useMMKVKeys;
+exports.useMultiMMKVKeys = useMultiMMKVKeys;
+var _react = require("react");
+var _mmkvAvailability = require("../utils/mmkvAvailability");
+/**
+ * useMMKVKeys Hook
+ *
+ * Fetch and validate MMKV keys from a specific MMKV instance.
+ * Equivalent to useAsyncStorageKeys but for MMKV storage.
+ *
+ * Key Differences from AsyncStorage:
+ * - Synchronous API (getAllKeys(), getString(), etc.)
+ * - Native types (string, number, boolean, buffer) vs string-only
+ * - Multi-instance support (requires instanceId parameter)
+ * - No multiGet - must fetch keys individually
+ */
+
+// Conditionally import MMKV types
+// Use 'any' to avoid hard dependency on react-native-mmkv
+
+// Conditionally import utilities only if MMKV is available
+let detectMMKVType;
+let isTypeMatch;
+if ((0, _mmkvAvailability.isMMKVAvailable)()) {
+  const typeDetection = require('../utils/mmkvTypeDetection');
+  detectMMKVType = typeDetection.detectMMKVType;
+  isTypeMatch = typeDetection.isTypeMatch;
+}
+/**
+ * Hook to fetch and monitor keys from an MMKV instance
+ *
+ * @param instance - MMKV instance to monitor
+ * @param instanceId - Unique identifier for this instance (e.g., "mmkv.default", "secure")
+ * @param requiredStorageKeys - Optional array of required keys for validation
+ *
+ * @example
+ * ```typescript
+ * import { MMKV } from 'react-native-mmkv';
+ * import { useMMKVKeys } from '@buoy-gg/storage';
+ *
+ * const storage = new MMKV();
+ *
+ * function MyComponent() {
+ *   const { storageKeys, isLoading, error, refresh } = useMMKVKeys(
+ *     storage,
+ *     'mmkv.default',
+ *     [
+ *       'user.token',
+ *       { key: 'user.id', expectedType: 'number' },
+ *       { key: 'app.theme', expectedValue: 'dark' }
+ *     ]
+ *   );
+ *
+ *   if (isLoading) return <LoadingSpinner />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *
+ *   return (
+ *     <View>
+ *       {storageKeys.map(keyInfo => (
+ *         <StorageKeyCard key={keyInfo.key} keyInfo={keyInfo} />
+ *       ))}
+ *       <Button onPress={refresh}>Refresh</Button>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
+  // State management
+  const [storageKeys, setStorageKeys] = (0, _react.useState)([]);
+  const [isLoading, setIsLoading] = (0, _react.useState)(true);
+  const [error, setError] = (0, _react.useState)(null);
+
+  // Fetch all keys and values from MMKV instance
+  const fetchStorageData = (0, _react.useCallback)(() => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      // Guard: Check if MMKV is available
+      if (!(0, _mmkvAvailability.isMMKVAvailable)()) {
+        setStorageKeys([]);
+        setIsLoading(false);
+        return; // Silently return empty when MMKV not available
+      }
+
+      // Guard: Check if instance is provided
+      if (!instance) {
+        setStorageKeys([]);
+        setIsLoading(false);
+        return; // Silently return empty when no instance
+      }
+
+      // 1. Get all keys from MMKV (synchronous)
+      const allKeys = instance.getAllKeys();
+      if (!allKeys || allKeys.length === 0) {
+        // Still need to check for missing required keys
+        const missingRequiredKeys = requiredStorageKeys.map(req => {
+          const key = typeof req === 'string' ? req : req.key;
+          const description = typeof req === 'object' && 'description' in req ? req.description : undefined;
+          const expectedValue = typeof req === 'object' && 'expectedValue' in req ? req.expectedValue : undefined;
+          const expectedType = typeof req === 'object' && 'expectedType' in req ? req.expectedType : undefined;
+          return {
+            key,
+            value: undefined,
+            valueType: undefined,
+            storageType: 'mmkv',
+            instanceId,
+            status: 'required_missing',
+            category: 'required',
+            description,
+            expectedValue,
+            expectedType
+          };
+        });
+        setStorageKeys(missingRequiredKeys);
+        setIsLoading(false);
+        return;
+      }
+
+      // 2. Process each key to get value and type
+      const allStorageKeys = [];
+      allKeys.forEach(key => {
+        // Detect value and type using type detection utility
+        const {
+          value,
+          type
+        } = detectMMKVType(instance, key);
+
+        // Check if this is a required key
+        const requiredConfig = requiredStorageKeys.find(req => {
+          if (typeof req === 'string') return req === key;
+          return req.key === key;
+        });
+
+        // Determine status based on validation rules
+        let status = 'optional_present';
+        if (requiredConfig) {
+          if (value === undefined) {
+            status = 'required_missing';
+          } else if (typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig) {
+            // Value validation
+            status = String(value) === String(requiredConfig.expectedValue) ? 'required_present' : 'required_wrong_value';
+          } else if (typeof requiredConfig === 'object' && 'expectedType' in requiredConfig) {
+            // Type validation
+            status = isTypeMatch(type, requiredConfig.expectedType) ? 'required_present' : 'required_wrong_type';
+          } else {
+            // Key exists and is required (no specific validation)
+            status = 'required_present';
+          }
+        }
+
+        // Build StorageKeyInfo object
+        const keyInfo = {
+          key,
+          value,
+          valueType: type !== 'unknown' ? type : undefined,
+          storageType: 'mmkv',
+          instanceId,
+          status,
+          category: requiredConfig ? 'required' : 'optional',
+          lastUpdated: new Date(),
+          ...(typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig && {
+            expectedValue: requiredConfig.expectedValue
+          }),
+          ...(typeof requiredConfig === 'object' && 'expectedType' in requiredConfig && {
+            expectedType: requiredConfig.expectedType
+          }),
+          ...(typeof requiredConfig === 'object' && 'description' in requiredConfig && {
+            description: requiredConfig.description
+          })
+        };
+        allStorageKeys.push(keyInfo);
+      });
+
+      // 3. Add missing required keys that weren't found in storage
+      requiredStorageKeys.forEach(req => {
+        const key = typeof req === 'string' ? req : req.key;
+        const exists = allStorageKeys.some(k => k.key === key);
+        if (!exists) {
+          allStorageKeys.push({
+            key,
+            value: undefined,
+            valueType: undefined,
+            storageType: 'mmkv',
+            instanceId,
+            status: 'required_missing',
+            category: 'required',
+            ...(typeof req === 'object' && 'expectedValue' in req && {
+              expectedValue: req.expectedValue
+            }),
+            ...(typeof req === 'object' && 'expectedType' in req && {
+              expectedType: req.expectedType
+            }),
+            ...(typeof req === 'object' && 'description' in req && {
+              description: req.description
+            })
+          });
+        }
+      });
+      setStorageKeys(allStorageKeys);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to fetch MMKV storage data'));
+      setStorageKeys([]);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [instance, instanceId, requiredStorageKeys]);
+
+  // Initial fetch
+  (0, _react.useEffect)(() => {
+    fetchStorageData();
+  }, [fetchStorageData]);
+  return {
+    storageKeys,
+    isLoading,
+    error,
+    refresh: fetchStorageData
+  };
+}
+
+/**
+ * Hook to fetch keys from multiple MMKV instances
+ *
+ * @param instances - Array of MMKV instances with their IDs
+ * @param requiredStorageKeys - Optional array of required keys for validation
+ *
+ * @example
+ * ```typescript
+ * import { MMKV } from 'react-native-mmkv';
+ * import { useMultiMMKVKeys } from '@buoy-gg/storage';
+ *
+ * const defaultStorage = new MMKV();
+ * const secureStorage = new MMKV({ id: 'secure', encryptionKey: key });
+ *
+ * function MyComponent() {
+ *   const { storageKeys, isLoading, error } = useMultiMMKVKeys(
+ *     [
+ *       { instance: defaultStorage, id: 'mmkv.default' },
+ *       { instance: secureStorage, id: 'secure' }
+ *     ],
+ *     ['user.token', 'app.theme']
+ *   );
+ *
+ *   // storageKeys will contain keys from both instances
+ *   // with instanceId field to identify which instance each key belongs to
+ * }
+ * ```
+ */
+function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
+  const [storageKeys, setStorageKeys] = (0, _react.useState)([]);
+  const [isLoading, setIsLoading] = (0, _react.useState)(true);
+  const [error, setError] = (0, _react.useState)(null);
+  const fetchStorageData = (0, _react.useCallback)(() => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const allStorageKeys = [];
+
+      // Fetch keys from each instance
+      instances.forEach(({
+        instance,
+        id
+      }) => {
+        const allKeys = instance.getAllKeys();
+        if (!allKeys || allKeys.length === 0) {
+          return;
+        }
+        allKeys.forEach(key => {
+          const {
+            value,
+            type
+          } = detectMMKVType(instance, key);
+          const requiredConfig = requiredStorageKeys.find(req => {
+            if (typeof req === 'string') return req === key;
+            return req.key === key;
+          });
+          let status = 'optional_present';
+          if (requiredConfig) {
+            if (value === undefined) {
+              status = 'required_missing';
+            } else if (typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig) {
+              status = String(value) === String(requiredConfig.expectedValue) ? 'required_present' : 'required_wrong_value';
+            } else if (typeof requiredConfig === 'object' && 'expectedType' in requiredConfig) {
+              status = isTypeMatch(type, requiredConfig.expectedType) ? 'required_present' : 'required_wrong_type';
+            } else {
+              status = 'required_present';
+            }
+          }
+          const keyInfo = {
+            key,
+            value,
+            valueType: type !== 'unknown' ? type : undefined,
+            storageType: 'mmkv',
+            instanceId: id,
+            status,
+            category: requiredConfig ? 'required' : 'optional',
+            lastUpdated: new Date(),
+            ...(typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig && {
+              expectedValue: requiredConfig.expectedValue
+            }),
+            ...(typeof requiredConfig === 'object' && 'expectedType' in requiredConfig && {
+              expectedType: requiredConfig.expectedType
+            }),
+            ...(typeof requiredConfig === 'object' && 'description' in requiredConfig && {
+              description: requiredConfig.description
+            })
+          };
+          allStorageKeys.push(keyInfo);
+        });
+      });
+
+      // Add missing required keys
+      requiredStorageKeys.forEach(req => {
+        const key = typeof req === 'string' ? req : req.key;
+        const exists = allStorageKeys.some(k => k.key === key);
+        if (!exists) {
+          // Add missing key for first instance (or all instances?)
+          // For now, add to first instance
+          const firstInstanceId = instances[0]?.id || 'mmkv.default';
+          allStorageKeys.push({
+            key,
+            value: undefined,
+            valueType: undefined,
+            storageType: 'mmkv',
+            instanceId: firstInstanceId,
+            status: 'required_missing',
+            category: 'required',
+            ...(typeof req === 'object' && 'expectedValue' in req && {
+              expectedValue: req.expectedValue
+            }),
+            ...(typeof req === 'object' && 'expectedType' in req && {
+              expectedType: req.expectedType
+            }),
+            ...(typeof req === 'object' && 'description' in req && {
+              description: req.description
+            })
+          });
+        }
+      });
+      setStorageKeys(allStorageKeys);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to fetch multi-MMKV storage data'));
+      setStorageKeys([]);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [instances, requiredStorageKeys]);
+  (0, _react.useEffect)(() => {
+    fetchStorageData();
+  }, [fetchStorageData]);
+  return {
+    storageKeys,
+    isLoading,
+    error,
+    refresh: fetchStorageData
+  };
+}

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

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useTickEverySecond = useTickEverySecond;
+var _react = require("react");
+/**
+ * Hook that forces a re-render every second
+ * Used to update relative timestamps (e.g., "2s ago", "1m ago")
+ */
+function useTickEverySecond(enabled = true) {
+  const [, setTick] = (0, _react.useState)(0);
+  (0, _react.useEffect)(() => {
+    if (!enabled) return;
+    const interval = setInterval(() => {
+      setTick(prev => prev + 1);
+    }, 1000);
+    return () => clearInterval(interval);
+  }, [enabled]);
+}

package/lib/commonjs/storage/index.js

@@ -0,0 +1,148 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _exportNames = {
+  StorageSection: true,
+  StorageModalWithTabs: true,
+  StorageKeyCard: true,
+  StorageKeyStatsSection: true,
+  StorageKeySection: true,
+  StorageBrowserMode: true,
+  StorageEventsSection: true,
+  useAsyncStorageKeys: true,
+  useMMKVKeys: true,
+  useMultiMMKVKeys: true,
+  useMMKVInstances: true,
+  useMMKVInstance: true,
+  useMMKVInstanceExists: true,
+  MMKVInstanceSelector: true,
+  MMKVInstanceInfoPanel: true
+};
+Object.defineProperty(exports, "MMKVInstanceInfoPanel", {
+  enumerable: true,
+  get: function () {
+    return _MMKVInstanceInfoPanel.MMKVInstanceInfoPanel;
+  }
+});
+Object.defineProperty(exports, "MMKVInstanceSelector", {
+  enumerable: true,
+  get: function () {
+    return _MMKVInstanceSelector.MMKVInstanceSelector;
+  }
+});
+Object.defineProperty(exports, "StorageBrowserMode", {
+  enumerable: true,
+  get: function () {
+    return _StorageBrowserMode.StorageBrowserMode;
+  }
+});
+Object.defineProperty(exports, "StorageEventsSection", {
+  enumerable: true,
+  get: function () {
+    return _StorageEventsSection.StorageEventsSection;
+  }
+});
+Object.defineProperty(exports, "StorageKeyCard", {
+  enumerable: true,
+  get: function () {
+    return _StorageKeyCard.StorageKeyCard;
+  }
+});
+Object.defineProperty(exports, "StorageKeySection", {
+  enumerable: true,
+  get: function () {
+    return _StorageKeySection.StorageKeySection;
+  }
+});
+Object.defineProperty(exports, "StorageKeyStatsSection", {
+  enumerable: true,
+  get: function () {
+    return _StorageKeyStats.StorageKeyStatsSection;
+  }
+});
+Object.defineProperty(exports, "StorageModalWithTabs", {
+  enumerable: true,
+  get: function () {
+    return _StorageModalWithTabs.StorageModalWithTabs;
+  }
+});
+Object.defineProperty(exports, "StorageSection", {
+  enumerable: true,
+  get: function () {
+    return _StorageSection.StorageSection;
+  }
+});
+Object.defineProperty(exports, "useAsyncStorageKeys", {
+  enumerable: true,
+  get: function () {
+    return _useAsyncStorageKeys.useAsyncStorageKeys;
+  }
+});
+Object.defineProperty(exports, "useMMKVInstance", {
+  enumerable: true,
+  get: function () {
+    return _useMMKVInstances.useMMKVInstance;
+  }
+});
+Object.defineProperty(exports, "useMMKVInstanceExists", {
+  enumerable: true,
+  get: function () {
+    return _useMMKVInstances.useMMKVInstanceExists;
+  }
+});
+Object.defineProperty(exports, "useMMKVInstances", {
+  enumerable: true,
+  get: function () {
+    return _useMMKVInstances.useMMKVInstances;
+  }
+});
+Object.defineProperty(exports, "useMMKVKeys", {
+  enumerable: true,
+  get: function () {
+    return _useMMKVKeys.useMMKVKeys;
+  }
+});
+Object.defineProperty(exports, "useMultiMMKVKeys", {
+  enumerable: true,
+  get: function () {
+    return _useMMKVKeys.useMultiMMKVKeys;
+  }
+});
+var _StorageSection = require("./components/StorageSection");
+var _StorageModalWithTabs = require("./components/StorageModalWithTabs");
+var _StorageKeyCard = require("./components/StorageKeyCard");
+var _StorageKeyStats = require("./components/StorageKeyStats");
+var _StorageKeySection = require("./components/StorageKeySection");
+var _StorageBrowserMode = require("./components/StorageBrowserMode");
+var _StorageEventsSection = require("./components/StorageEventsSection");
+var _useAsyncStorageKeys = require("./hooks/useAsyncStorageKeys");
+var _useMMKVKeys = require("./hooks/useMMKVKeys");
+var _useMMKVInstances = require("./hooks/useMMKVInstances");
+var _MMKVInstanceSelector = require("./components/MMKVInstanceSelector");
+var _MMKVInstanceInfoPanel = require("./components/MMKVInstanceInfoPanel");
+var _types = require("./types");
+Object.keys(_types).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _types[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _types[key];
+    }
+  });
+});
+var _utils = require("./utils");
+Object.keys(_utils).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _utils[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _utils[key];
+    }
+  });
+});

package/lib/commonjs/storage/types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});