@buoy-gg/storage 1.7.2

package/lib/module/storage/utils/MMKVListener.js

@@ -0,0 +1,367 @@
+"use strict";
+
+/**
+ * MMKVListener - Hybrid Monitoring Strategy
+ *
+ * This module provides comprehensive monitoring for MMKV storage instances using
+ * a hybrid approach that combines:
+ *
+ * 1. MMKV's built-in addOnValueChangedListener() - for write operations
+ * 2. Method wrapping - for read operations and type detection
+ *
+ * Why Hybrid Strategy?
+ * - MMKV listeners only fire on writes (set/delete), not reads
+ * - MMKV listeners don't provide value type information
+ * - Method wrapping captures ALL operations with full context
+ * - Combining both gives complete observability
+ *
+ * Key Differences from AsyncStorage:
+ * - Synchronous API (no async/await needed)
+ * - Multi-instance support (track multiple MMKV instances)
+ * - Native types (string, number, boolean, buffer)
+ * - Built-in listener support (MMKV.addOnValueChangedListener)
+ *
+ * @see AsyncStorageListener.ts for AsyncStorage equivalent
+ */
+
+// Use 'any' type for MMKV to avoid hard dependency on react-native-mmkv
+
+import { detectMMKVType } from "./mmkvTypeDetection";
+
+// MMKV method signatures
+
+/**
+ * Event types for MMKV operations
+ */
+
+/**
+ * Instance tracking for MMKV monitoring
+ */
+
+/**
+ * Singleton class for monitoring MMKV operations across multiple instances
+ *
+ * Uses a hybrid monitoring strategy:
+ * 1. MMKV's built-in listener API for write notifications
+ * 2. Method wrapping for read operations and type information
+ *
+ * @example
+ * ```typescript
+ * import { MMKV } from 'react-native-mmkv';
+ * import { mmkvListener } from './MMKVListener';
+ *
+ * const storage = new MMKV();
+ *
+ * // Start monitoring this instance
+ * mmkvListener.addInstance(storage, 'mmkv.default');
+ *
+ * // Add listener for all MMKV events
+ * const unsubscribe = mmkvListener.addListener((event) => {
+ *   console.log(`[${event.instanceId}] ${event.action}:`, event.data);
+ * });
+ *
+ * // Cleanup
+ * unsubscribe();
+ * mmkvListener.removeInstance('mmkv.default');
+ * ```
+ */
+class MMKVListener {
+  listeners = [];
+  instances = new Map();
+
+  // Keys to ignore to prevent dev tools from triggering self-events
+  ignoredKeys = new Set(["@react_buoy_storage_event_filters", "@react_buoy_storage_key_filters", "@react_buoy_storage_is_monitoring", "REACT_QUERY_OFFLINE_CACHE"]);
+
+  /**
+   * Determines if a storage key should be ignored
+   */
+  shouldIgnoreKey(key) {
+    if (this.ignoredKeys.has(key)) return true;
+    for (const ignoredKey of this.ignoredKeys) {
+      if (key.startsWith(ignoredKey)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Emit an MMKV event to all registered listeners
+   */
+  emit(event) {
+    if (this.listeners.length === 0) return;
+    this.listeners.forEach(listener => {
+      try {
+        listener(event);
+      } catch (error) {
+        // Error in MMKV event listener - continuing with others
+      }
+    });
+  }
+
+  /**
+   * Add an MMKV instance for monitoring
+   *
+   * This method sets up both native MMKV listeners and method wrapping
+   * to provide complete observability.
+   *
+   * @param instance - MMKV instance to monitor
+   * @param instanceId - Unique identifier for this instance
+   *
+   * @example
+   * ```typescript
+   * const storage = new MMKV();
+   * mmkvListener.addInstance(storage, 'mmkv.default');
+   *
+   * const secureStorage = new MMKV({ id: 'secure', encryptionKey: key });
+   * mmkvListener.addInstance(secureStorage, 'secure');
+   * ```
+   */
+  addInstance(instance, instanceId) {
+    // Check if already monitoring this instance
+    if (this.instances.has(instanceId)) {
+      return;
+    }
+
+    // v4 COMPATIBILITY: Use ONLY native listener (no method wrapping)
+    // react-native-mmkv v4 instances have frozen/read-only methods that cannot be wrapped
+    // The native listener (addOnValueChangedListener) is sufficient for monitoring writes
+
+    let nativeListenerUnsubscribe;
+    if (typeof instance.addOnValueChangedListener === "function") {
+      try {
+        nativeListenerUnsubscribe = instance.addOnValueChangedListener(key => {
+          // Ignore dev tools keys
+          if (this.shouldIgnoreKey(key)) return;
+
+          // Detect the value type
+          const {
+            value,
+            type
+          } = detectMMKVType(instance, key);
+
+          // Determine action: if value is undefined/unknown, it was deleted
+          const isDelete = type === "unknown" || value === undefined;
+          if (isDelete) {
+            // Key was deleted
+            const event = {
+              action: "delete",
+              timestamp: new Date(),
+              instanceId,
+              data: {
+                key,
+                success: true
+              }
+            };
+            this.emit(event);
+          } else {
+            // Key was set/updated
+            const action = type === "string" ? "set.string" : type === "number" ? "set.number" : type === "boolean" ? "set.boolean" : type === "buffer" ? "set.buffer" : "set.string"; // fallback
+
+            const event = {
+              action,
+              timestamp: new Date(),
+              instanceId,
+              data: {
+                key,
+                value,
+                valueType: type,
+                success: true
+              }
+            };
+            this.emit(event);
+          }
+        });
+      } catch (error) {
+        // Could not add native listener
+      }
+    }
+
+    // Store instance tracking (no originalMethods needed for v4)
+    this.instances.set(instanceId, {
+      instance,
+      instanceId,
+      originalMethods: {},
+      // Not used in v4
+      nativeListenerUnsubscribe
+    });
+  }
+
+  /**
+   * Remove an MMKV instance from monitoring
+   *
+   * Restores original methods and removes native listener.
+   *
+   * @param instanceId - Identifier of instance to stop monitoring
+   */
+  removeInstance(instanceId) {
+    const tracked = this.instances.get(instanceId);
+    if (!tracked) {
+      return;
+    }
+    const {
+      nativeListenerUnsubscribe
+    } = tracked;
+
+    // Remove native listener
+    if (nativeListenerUnsubscribe) {
+      nativeListenerUnsubscribe();
+    }
+
+    // Remove from tracking
+    this.instances.delete(instanceId);
+  }
+
+  /**
+   * Remove all monitored instances
+   */
+  removeAllInstances() {
+    const instanceIds = Array.from(this.instances.keys());
+    instanceIds.forEach(id => this.removeInstance(id));
+  }
+
+  /**
+   * Add a listener for MMKV events across all monitored instances
+   *
+   * @param listener - Callback function to handle MMKV events
+   * @returns Unsubscribe function to remove the listener
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = mmkvListener.addListener((event) => {
+   *   console.log(`[${event.instanceId}] ${event.action}:`, event.data);
+   * });
+   *
+   * // Later, remove the listener
+   * unsubscribe();
+   * ```
+   */
+  addListener(listener) {
+    this.listeners.push(listener);
+
+    // Return unsubscribe function
+    return () => {
+      const index = this.listeners.indexOf(listener);
+      if (index > -1) {
+        this.listeners.splice(index, 1);
+      }
+    };
+  }
+
+  /**
+   * Remove all registered event listeners
+   */
+  removeAllListeners() {
+    this.listeners = [];
+  }
+
+  /**
+   * Check if an instance is currently being monitored
+   */
+  hasInstance(instanceId) {
+    return this.instances.has(instanceId);
+  }
+
+  /**
+   * Get list of all monitored instance IDs
+   */
+  getMonitoredInstances() {
+    return Array.from(this.instances.keys());
+  }
+
+  /**
+   * Get the number of currently monitored instances
+   */
+  get instanceCount() {
+    return this.instances.size;
+  }
+
+  /**
+   * Get the number of currently registered event listeners
+   */
+  get listenerCount() {
+    return this.listeners.length;
+  }
+
+  /**
+   * Check if any instances are being monitored
+   */
+  get isActive() {
+    return this.instances.size > 0;
+  }
+}
+
+/**
+ * Singleton instance of MMKVListener
+ *
+ * This ensures only one listener manager exists across the entire application.
+ */
+export const mmkvListener = new MMKVListener();
+
+/**
+ * Add an MMKV instance for monitoring
+ *
+ * @param instance - MMKV instance to monitor
+ * @param instanceId - Unique identifier for this instance
+ *
+ * @example
+ * ```typescript
+ * import { MMKV } from 'react-native-mmkv';
+ * import { addMMKVInstance } from '@buoy-gg/storage';
+ *
+ * const storage = new MMKV();
+ * addMMKVInstance(storage, 'mmkv.default');
+ * ```
+ */
+export const addMMKVInstance = (instance, instanceId) => mmkvListener.addInstance(instance, instanceId);
+
+/**
+ * Remove an MMKV instance from monitoring
+ */
+export const removeMMKVInstance = instanceId => mmkvListener.removeInstance(instanceId);
+
+/**
+ * Remove all monitored MMKV instances
+ */
+export const removeAllMMKVInstances = () => mmkvListener.removeAllInstances();
+
+/**
+ * Add an event listener for MMKV operations
+ *
+ * @param listener - Callback function to handle events
+ * @returns Unsubscribe function to remove the listener
+ */
+export const addMMKVListener = listener => mmkvListener.addListener(listener);
+
+/**
+ * Remove all registered event listeners
+ */
+export const removeAllMMKVListeners = () => mmkvListener.removeAllListeners();
+
+/**
+ * Check if an MMKV instance is currently being monitored
+ */
+export const isMMKVInstanceMonitored = instanceId => mmkvListener.hasInstance(instanceId);
+
+/**
+ * Get list of all monitored MMKV instance IDs
+ */
+export const getMonitoredMMKVInstances = () => mmkvListener.getMonitoredInstances();
+
+/**
+ * Get the current number of monitored MMKV instances
+ */
+export const getMMKVInstanceCount = () => mmkvListener.instanceCount;
+
+/**
+ * Get the current number of registered event listeners
+ */
+export const getMMKVListenerCount = () => mmkvListener.listenerCount;
+
+/**
+ * Check if any MMKV instances are being monitored
+ */
+export const isMMKVListening = () => mmkvListener.isActive;
+
+/**
+ * Export the singleton instance for advanced usage
+ */
+export default mmkvListener;

package/lib/module/storage/utils/clearAllStorage.js

@@ -0,0 +1,42 @@
+"use strict";
+
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { isDevToolsStorageKey } from "@buoy-gg/shared-ui";
+
+/**
+ * Clear all storage data except dev tools keys
+ * This preserves dev tool settings while clearing app data
+ */
+export async function clearAllAppStorage() {
+  // Get all keys
+  const allKeys = await AsyncStorage.getAllKeys();
+  if (!allKeys || allKeys.length === 0) {
+    // No keys to clear
+    return;
+  }
+
+  // Filter out dev tool keys - we don't want to clear those
+  const keysToRemove = allKeys.filter(key => !isDevToolsStorageKey(key));
+  if (keysToRemove.length === 0) {
+    // No app keys to clear (only dev tool keys found)
+    return;
+  }
+
+  // Clearing ${keysToRemove.length} app storage keys
+
+  // Remove all non-dev-tool keys
+  await AsyncStorage.multiRemove(keysToRemove);
+
+  // Successfully cleared app storage
+}
+
+/**
+ * Clear absolutely all storage data including dev tools
+ * Use with caution - this will reset all dev tool settings
+ */
+export async function clearAllStorageIncludingDevTools() {
+  // Clear everything
+  await AsyncStorage.clear();
+
+  // Successfully cleared all storage including dev tools
+}

package/lib/module/storage/utils/index.js

@@ -0,0 +1,22 @@
+"use strict";
+
+// Storage utilities
+export { clearAllAppStorage } from "./clearAllStorage";
+
+// MMKV Availability
+export { isMMKVAvailable, getMMKVClass, getMMKVUnavailableMessage } from "./mmkvAvailability";
+
+// AsyncStorage Event Listener
+export { startListening, stopListening, addListener, removeAllListeners, isListening, getListenerCount } from "./AsyncStorageListener";
+
+// Re-export default listener instance
+export { default as asyncStorageListener } from "./AsyncStorageListener";
+
+// MMKV Instance Registry
+export { registerMMKVInstance, unregisterMMKVInstance, mmkvInstanceRegistry } from "./MMKVInstanceRegistry";
+
+// MMKV Listener
+export { addMMKVInstance, removeMMKVInstance, removeAllMMKVInstances, addMMKVListener, removeAllMMKVListeners, isMMKVInstanceMonitored, getMonitoredMMKVInstances, getMMKVInstanceCount, getMMKVListenerCount, isMMKVListening, mmkvListener } from "./MMKVListener";
+
+// MMKV Type Detection
+export { detectMMKVType, formatMMKVValue, isTypeMatch } from "./mmkvTypeDetection";