@buoy-gg/storage 1.7.2

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

@@ -0,0 +1,380 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.removeMMKVInstance = exports.removeAllMMKVListeners = exports.removeAllMMKVInstances = exports.mmkvListener = exports.isMMKVListening = exports.isMMKVInstanceMonitored = exports.getMonitoredMMKVInstances = exports.getMMKVListenerCount = exports.getMMKVInstanceCount = exports.default = exports.addMMKVListener = exports.addMMKVInstance = void 0;
+var _mmkvTypeDetection = require("./mmkvTypeDetection");
+/**
+ * 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
+
+// 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
+          } = (0, _mmkvTypeDetection.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.
+ */
+const mmkvListener = exports.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');
+ * ```
+ */
+const addMMKVInstance = (instance, instanceId) => mmkvListener.addInstance(instance, instanceId);
+
+/**
+ * Remove an MMKV instance from monitoring
+ */
+exports.addMMKVInstance = addMMKVInstance;
+const removeMMKVInstance = instanceId => mmkvListener.removeInstance(instanceId);
+
+/**
+ * Remove all monitored MMKV instances
+ */
+exports.removeMMKVInstance = removeMMKVInstance;
+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
+ */
+exports.removeAllMMKVInstances = removeAllMMKVInstances;
+const addMMKVListener = listener => mmkvListener.addListener(listener);
+
+/**
+ * Remove all registered event listeners
+ */
+exports.addMMKVListener = addMMKVListener;
+const removeAllMMKVListeners = () => mmkvListener.removeAllListeners();
+
+/**
+ * Check if an MMKV instance is currently being monitored
+ */
+exports.removeAllMMKVListeners = removeAllMMKVListeners;
+const isMMKVInstanceMonitored = instanceId => mmkvListener.hasInstance(instanceId);
+
+/**
+ * Get list of all monitored MMKV instance IDs
+ */
+exports.isMMKVInstanceMonitored = isMMKVInstanceMonitored;
+const getMonitoredMMKVInstances = () => mmkvListener.getMonitoredInstances();
+
+/**
+ * Get the current number of monitored MMKV instances
+ */
+exports.getMonitoredMMKVInstances = getMonitoredMMKVInstances;
+const getMMKVInstanceCount = () => mmkvListener.instanceCount;
+
+/**
+ * Get the current number of registered event listeners
+ */
+exports.getMMKVInstanceCount = getMMKVInstanceCount;
+const getMMKVListenerCount = () => mmkvListener.listenerCount;
+
+/**
+ * Check if any MMKV instances are being monitored
+ */
+exports.getMMKVListenerCount = getMMKVListenerCount;
+const isMMKVListening = () => mmkvListener.isActive;
+
+/**
+ * Export the singleton instance for advanced usage
+ */
+exports.isMMKVListening = isMMKVListening;
+var _default = exports.default = mmkvListener;

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

@@ -0,0 +1,47 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.clearAllAppStorage = clearAllAppStorage;
+exports.clearAllStorageIncludingDevTools = clearAllStorageIncludingDevTools;
+var _asyncStorage = _interopRequireDefault(require("@react-native-async-storage/async-storage"));
+var _sharedUi = require("@buoy-gg/shared-ui");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Clear all storage data except dev tools keys
+ * This preserves dev tool settings while clearing app data
+ */
+async function clearAllAppStorage() {
+  // Get all keys
+  const allKeys = await _asyncStorage.default.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 => !(0, _sharedUi.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.default.multiRemove(keysToRemove);
+
+  // Successfully cleared app storage
+}
+
+/**
+ * Clear absolutely all storage data including dev tools
+ * Use with caution - this will reset all dev tool settings
+ */
+async function clearAllStorageIncludingDevTools() {
+  // Clear everything
+  await _asyncStorage.default.clear();
+
+  // Successfully cleared all storage including dev tools
+}

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

@@ -0,0 +1,180 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "addListener", {
+  enumerable: true,
+  get: function () {
+    return _AsyncStorageListener.addListener;
+  }
+});
+Object.defineProperty(exports, "addMMKVInstance", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.addMMKVInstance;
+  }
+});
+Object.defineProperty(exports, "addMMKVListener", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.addMMKVListener;
+  }
+});
+Object.defineProperty(exports, "asyncStorageListener", {
+  enumerable: true,
+  get: function () {
+    return _AsyncStorageListener.default;
+  }
+});
+Object.defineProperty(exports, "clearAllAppStorage", {
+  enumerable: true,
+  get: function () {
+    return _clearAllStorage.clearAllAppStorage;
+  }
+});
+Object.defineProperty(exports, "detectMMKVType", {
+  enumerable: true,
+  get: function () {
+    return _mmkvTypeDetection.detectMMKVType;
+  }
+});
+Object.defineProperty(exports, "formatMMKVValue", {
+  enumerable: true,
+  get: function () {
+    return _mmkvTypeDetection.formatMMKVValue;
+  }
+});
+Object.defineProperty(exports, "getListenerCount", {
+  enumerable: true,
+  get: function () {
+    return _AsyncStorageListener.getListenerCount;
+  }
+});
+Object.defineProperty(exports, "getMMKVClass", {
+  enumerable: true,
+  get: function () {
+    return _mmkvAvailability.getMMKVClass;
+  }
+});
+Object.defineProperty(exports, "getMMKVInstanceCount", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.getMMKVInstanceCount;
+  }
+});
+Object.defineProperty(exports, "getMMKVListenerCount", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.getMMKVListenerCount;
+  }
+});
+Object.defineProperty(exports, "getMMKVUnavailableMessage", {
+  enumerable: true,
+  get: function () {
+    return _mmkvAvailability.getMMKVUnavailableMessage;
+  }
+});
+Object.defineProperty(exports, "getMonitoredMMKVInstances", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.getMonitoredMMKVInstances;
+  }
+});
+Object.defineProperty(exports, "isListening", {
+  enumerable: true,
+  get: function () {
+    return _AsyncStorageListener.isListening;
+  }
+});
+Object.defineProperty(exports, "isMMKVAvailable", {
+  enumerable: true,
+  get: function () {
+    return _mmkvAvailability.isMMKVAvailable;
+  }
+});
+Object.defineProperty(exports, "isMMKVInstanceMonitored", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.isMMKVInstanceMonitored;
+  }
+});
+Object.defineProperty(exports, "isMMKVListening", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.isMMKVListening;
+  }
+});
+Object.defineProperty(exports, "isTypeMatch", {
+  enumerable: true,
+  get: function () {
+    return _mmkvTypeDetection.isTypeMatch;
+  }
+});
+Object.defineProperty(exports, "mmkvInstanceRegistry", {
+  enumerable: true,
+  get: function () {
+    return _MMKVInstanceRegistry.mmkvInstanceRegistry;
+  }
+});
+Object.defineProperty(exports, "mmkvListener", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.mmkvListener;
+  }
+});
+Object.defineProperty(exports, "registerMMKVInstance", {
+  enumerable: true,
+  get: function () {
+    return _MMKVInstanceRegistry.registerMMKVInstance;
+  }
+});
+Object.defineProperty(exports, "removeAllListeners", {
+  enumerable: true,
+  get: function () {
+    return _AsyncStorageListener.removeAllListeners;
+  }
+});
+Object.defineProperty(exports, "removeAllMMKVInstances", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.removeAllMMKVInstances;
+  }
+});
+Object.defineProperty(exports, "removeAllMMKVListeners", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.removeAllMMKVListeners;
+  }
+});
+Object.defineProperty(exports, "removeMMKVInstance", {
+  enumerable: true,
+  get: function () {
+    return _MMKVListener.removeMMKVInstance;
+  }
+});
+Object.defineProperty(exports, "startListening", {
+  enumerable: true,
+  get: function () {
+    return _AsyncStorageListener.startListening;
+  }
+});
+Object.defineProperty(exports, "stopListening", {
+  enumerable: true,
+  get: function () {
+    return _AsyncStorageListener.stopListening;
+  }
+});
+Object.defineProperty(exports, "unregisterMMKVInstance", {
+  enumerable: true,
+  get: function () {
+    return _MMKVInstanceRegistry.unregisterMMKVInstance;
+  }
+});
+var _clearAllStorage = require("./clearAllStorage");
+var _mmkvAvailability = require("./mmkvAvailability");
+var _AsyncStorageListener = _interopRequireWildcard(require("./AsyncStorageListener"));
+var _MMKVInstanceRegistry = require("./MMKVInstanceRegistry");
+var _MMKVListener = require("./MMKVListener");
+var _mmkvTypeDetection = require("./mmkvTypeDetection");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }