@buoy-gg/storage 1.7.2

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

@@ -0,0 +1,157 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.objectDiff = objectDiff;
+/**
+ * Type guard to check if a value is a plain object (not array or null)
+ * 
+ * @param obj - Value to check
+ * @returns True if the value is a plain object
+ */
+function isObject(obj) {
+  return obj !== null && typeof obj === "object" && !Array.isArray(obj);
+}
+
+/**
+ * Type guard to check if a value is an array
+ * 
+ * @param obj - Value to check
+ * @returns True if the value is an array
+ */
+function isArray(obj) {
+  return Array.isArray(obj);
+}
+
+/**
+ * Recursively compare two values and collect differences
+ * 
+ * This function handles deep comparison of objects, arrays, and primitive values,
+ * building a comprehensive diff that tracks the exact path of each change.
+ * 
+ * @param oldVal - The original value to compare from
+ * @param newVal - The new value to compare to
+ * @param path - Current path in the object structure (for nested properties)
+ * @param diffs - Array to collect difference items
+ * 
+ * @performance Uses recursive traversal with path tracking for memory efficiency
+ * @performance Handles large nested structures without stack overflow concerns for typical use cases
+ */
+function compareValues(oldVal, newVal, path, diffs) {
+  // Both are objects
+  if (isObject(oldVal) && isObject(newVal)) {
+    const allKeys = new Set([...Object.keys(oldVal), ...Object.keys(newVal)]);
+    for (const key of allKeys) {
+      const newPath = [...path, key];
+      if (!(key in oldVal)) {
+        // Key was added
+        diffs.push({
+          type: "CREATE",
+          path: newPath,
+          value: newVal[key]
+        });
+      } else if (!(key in newVal)) {
+        // Key was removed
+        diffs.push({
+          type: "REMOVE",
+          path: newPath,
+          oldValue: oldVal[key]
+        });
+      } else {
+        // Key exists in both, compare values
+        compareValues(oldVal[key], newVal[key], newPath, diffs);
+      }
+    }
+  }
+  // Both are arrays
+  else if (isArray(oldVal) && isArray(newVal)) {
+    const maxLength = Math.max(oldVal.length, newVal.length);
+    for (let i = 0; i < maxLength; i++) {
+      const newPath = [...path, i];
+      if (i >= oldVal.length) {
+        // Item was added
+        diffs.push({
+          type: "CREATE",
+          path: newPath,
+          value: newVal[i]
+        });
+      } else if (i >= newVal.length) {
+        // Item was removed
+        diffs.push({
+          type: "REMOVE",
+          path: newPath,
+          oldValue: oldVal[i]
+        });
+      } else {
+        // Item exists in both, compare values
+        compareValues(oldVal[i], newVal[i], newPath, diffs);
+      }
+    }
+  }
+  // Values are different types or primitives
+  else if (oldVal !== newVal) {
+    diffs.push({
+      type: "CHANGE",
+      path,
+      oldValue: oldVal,
+      value: newVal
+    });
+  }
+}
+
+/**
+ * Generate a comprehensive diff between two objects or values
+ * 
+ * This function performs a deep comparison between two values and returns
+ * a detailed list of all differences, including additions, removals, and changes.
+ * Each difference includes the exact path where the change occurred.
+ * 
+ * @param oldObj - The original object/value to compare from
+ * @param newObj - The new object/value to compare to
+ * @returns Array of DiffItem objects describing all differences
+ * 
+ * @example
+ * ```typescript
+ * const oldData = { user: { name: "John", age: 30 }, items: [1, 2] };
+ * const newData = { user: { name: "Jane", age: 30 }, items: [1, 2, 3] };
+ * 
+ * const diffs = objectDiff(oldData, newData);
+ * // Returns:
+ * // [
+ * //   { type: "CHANGE", path: ["user", "name"], oldValue: "John", value: "Jane" },
+ * //   { type: "CREATE", path: ["items", 2], value: 3 }
+ * // ]
+ * ```
+ * 
+ * @performance Handles circular references and deep nesting efficiently
+ * @performance Uses Set for key deduplication to optimize comparison speed
+ */
+function objectDiff(oldObj, newObj) {
+  const diffs = [];
+
+  // Handle null/undefined cases
+  if (oldObj === newObj) {
+    return diffs;
+  }
+  if (oldObj === null || oldObj === undefined) {
+    if (newObj !== null && newObj !== undefined) {
+      diffs.push({
+        type: "CREATE",
+        path: [],
+        value: newObj
+      });
+    }
+    return diffs;
+  }
+  if (newObj === null || newObj === undefined) {
+    diffs.push({
+      type: "REMOVE",
+      path: [],
+      oldValue: oldObj
+    });
+    return diffs;
+  }
+  compareValues(oldObj, newObj, [], diffs);
+  return diffs;
+}

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

@@ -0,0 +1,140 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getAsyncStorageInstance = getAsyncStorageInstance;
+exports.isAsyncStorageAvailable = isAsyncStorageAvailable;
+exports.safeAsyncStorage = void 0;
+/**
+ * Safe AsyncStorage wrapper that handles missing dependencies gracefully.
+ *
+ * This wrapper allows the storage dev tools to work even when
+ * @react-native-async-storage/async-storage is not installed in the host app.
+ *
+ * When AsyncStorage is not available:
+ * - All operations return empty results or no-ops
+ * - No errors are thrown
+ * - The dev tools can still load (but storage features will be limited)
+ */
+
+let AsyncStorage = null;
+let isAvailable = false;
+let checkedAvailability = false;
+let checkError = null;
+
+/**
+ * Check if AsyncStorage is available in the host app
+ * This handles three cases:
+ * 1. Package not installed (module not found)
+ * 2. Package installed but native module not linked (native module null)
+ * 3. Package installed and working
+ */
+function checkAsyncStorageAvailability() {
+  if (checkedAvailability) {
+    return isAvailable;
+  }
+  try {
+    // Attempt to require AsyncStorage
+    // This might throw if:
+    // - Package is not installed (module not found)
+    // - Native module is not linked (RCTAsyncStorage is null)
+    const AsyncStorageModule = require("@react-native-async-storage/async-storage");
+    AsyncStorage = AsyncStorageModule?.default || AsyncStorageModule;
+
+    // Verify it's actually usable (has the methods we need)
+    if (AsyncStorage && typeof AsyncStorage.getItem === "function") {
+      isAvailable = true;
+    } else {
+      isAvailable = false;
+      AsyncStorage = null;
+    }
+  } catch (error) {
+    // Catch ALL errors:
+    // - Module not found (package not installed)
+    // - Native module errors (package installed but native not linked)
+    // - Any other initialization errors
+    checkError = error;
+    isAvailable = false;
+    AsyncStorage = null;
+  }
+  checkedAvailability = true;
+  return isAvailable;
+}
+
+/**
+ * Returns true if AsyncStorage is available in the host app
+ */
+function isAsyncStorageAvailable() {
+  return checkAsyncStorageAvailability();
+}
+
+/**
+ * No-op AsyncStorage implementation for when the package is not installed
+ */
+const noOpAsyncStorage = {
+  getItem: async _key => null,
+  setItem: async (_key, _value) => {},
+  removeItem: async _key => {},
+  getAllKeys: async () => [],
+  multiGet: async _keys => [],
+  multiSet: async _keyValuePairs => {},
+  multiRemove: async _keys => {},
+  clear: async () => {},
+  mergeItem: async (_key, _value) => {},
+  multiMerge: async _keyValuePairs => {}
+};
+
+/**
+ * Safe AsyncStorage wrapper that provides no-op fallbacks when unavailable.
+ *
+ * Usage:
+ * ```ts
+ * import { safeAsyncStorage } from './utils/safeAsyncStorage';
+ *
+ * // This will work even if AsyncStorage is not installed
+ * const value = await safeAsyncStorage.getItem('myKey');
+ * ```
+ */
+const safeAsyncStorage = exports.safeAsyncStorage = new Proxy(noOpAsyncStorage, {
+  get(_target, prop) {
+    // Avoid triggering check for React internal properties or symbols
+    if (typeof prop === "symbol" || prop.startsWith("_") || prop.startsWith("$$")) {
+      return noOpAsyncStorage[prop];
+    }
+
+    // Only check availability when actually accessing AsyncStorage methods
+    try {
+      checkAsyncStorageAvailability();
+      if (isAvailable && AsyncStorage) {
+        return AsyncStorage[prop];
+      }
+    } catch (error) {
+      // If check throws for any reason, fall back to no-op
+    }
+
+    // Return no-op implementation
+    return noOpAsyncStorage[prop];
+  }
+});
+
+/**
+ * Get the actual AsyncStorage instance if available, or null if not.
+ * Use this when you need to check if AsyncStorage is available before using it.
+ *
+ * @example
+ * ```ts
+ * const storage = getAsyncStorageInstance();
+ * if (storage) {
+ *   // AsyncStorage is available
+ *   await storage.setItem('key', 'value');
+ * } else {
+ *   // AsyncStorage is not available, handle gracefully
+ *   console.warn('AsyncStorage not available');
+ * }
+ * ```
+ */
+function getAsyncStorageInstance() {
+  checkAsyncStorageAvailability();
+  return isAvailable ? AsyncStorage : null;
+}

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

@@ -0,0 +1,46 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.translateStorageAction = translateStorageAction;
+/**
+ * Translates storage action types to human-readable labels
+ */
+function translateStorageAction(action) {
+  switch (action) {
+    // AsyncStorage actions
+    case "setItem":
+      return "SET";
+    case "removeItem":
+      return "REMOVE";
+    case "mergeItem":
+      return "MERGE";
+    case "clear":
+      return "CLEAR";
+    case "multiSet":
+      return "MULTI SET";
+    case "multiRemove":
+      return "MULTI REMOVE";
+    case "multiMerge":
+      return "MULTI MERGE";
+
+    // MMKV actions - simplified to match AsyncStorage
+    case "set.string":
+    case "set.number":
+    case "set.boolean":
+    case "set.buffer":
+      return "SET";
+    case "delete":
+      return "REMOVE";
+    case "clearAll":
+      return "CLEAR";
+    case "get.string":
+    case "get.number":
+    case "get.boolean":
+    case "get.buffer":
+      return "GET";
+    default:
+      return "UNKNOWN ACTION";
+  }
+}

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

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getStorageTypeHexColor = getStorageTypeHexColor;
+exports.getStorageTypeLabel = getStorageTypeLabel;
+var _sharedUi = require("@buoy-gg/shared-ui");
+/** Human readable label for a storage type id. */
+function getStorageTypeLabel(storageType) {
+  switch (storageType) {
+    case "mmkv":
+      return "MMKV";
+    case "async":
+      return "Async";
+    case "secure":
+      return "Secure";
+    default:
+      return storageType;
+  }
+}
+
+/** Preferred color token for rendering a given storage type. */
+function getStorageTypeHexColor(storageType) {
+  switch (storageType) {
+    case "mmkv":
+      return _sharedUi.gameUIColors.info;
+    case "async":
+      return _sharedUi.gameUIColors.warning;
+    case "secure":
+      return _sharedUi.gameUIColors.success;
+    default:
+      return _sharedUi.gameUIColors.muted;
+  }
+}

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

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getValueTypeLabel = getValueTypeLabel;
+/** Return a concise string describing the JavaScript type of the provided value. */
+function getValueTypeLabel(value) {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (Array.isArray(value)) return "array";
+  const type = typeof value;
+  if (type === "object") return "object";
+  if (type === "boolean") return "boolean";
+  if (type === "number") return "number";
+  if (type === "string") return "string";
+  return "unknown";
+}

package/lib/module/index.js

@@ -0,0 +1,7 @@
+"use strict";
+
+// Export preset configuration (easiest way to add to FloatingDevTools!)
+export { storageToolPreset, createStorageTool } from "./preset";
+
+// Export all storage utilities and components
+export * from "./storage";

package/lib/module/preset.js

@@ -0,0 +1,89 @@
+"use strict";
+
+/**
+ * Pre-configured AsyncStorage browser tool for FloatingDevTools
+ *
+ * This preset provides a zero-config way to add AsyncStorage inspection to your dev tools.
+ * Just import and add it to your apps array!
+ *
+ * @example
+ * ```tsx
+ * import { storageToolPreset } from '@buoy-gg/storage';
+ *
+ * const installedApps = [
+ *   storageToolPreset, // That's it!
+ *   // ...other tools
+ * ];
+ * ```
+ */
+
+import { StorageIcon } from "@buoy-gg/floating-tools-core";
+import { StorageModalWithTabs } from "./storage/components/StorageModalWithTabs";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Pre-configured AsyncStorage browser tool for FloatingDevTools.
+ * Includes:
+ * - Browse all AsyncStorage keys and values
+ * - Edit, delete, and add storage items
+ * - Live storage event monitoring
+ * - Required key validation
+ */
+export const storageToolPreset = {
+  id: "storage",
+  name: "STORAGE",
+  description: "AsyncStorage browser",
+  slot: "both",
+  icon: ({
+    size
+  }) => /*#__PURE__*/_jsx(StorageIcon, {
+    size: size
+  }),
+  component: StorageModalWithTabs,
+  props: {
+    requiredStorageKeys: [],
+    enableSharedModalDimensions: false
+  }
+};
+
+/**
+ * Create a custom AsyncStorage browser tool configuration.
+ * Use this if you want to override default settings or provide required storage keys.
+ *
+ * @example
+ * ```tsx
+ * import { createStorageTool } from '@buoy-gg/storage';
+ *
+ * const requiredStorageKeys = [
+ *   {
+ *     key: "@app/session",
+ *     expectedType: "string",
+ *     description: "User session token",
+ *     storageType: "async",
+ *   },
+ * ];
+ *
+ * const myStorageTool = createStorageTool({
+ *   requiredStorageKeys,
+ *   colorPreset: "purple",
+ *   enableSharedModalDimensions: true,
+ * });
+ * ```
+ */
+export function createStorageTool(options) {
+  return {
+    id: options?.id || "storage",
+    name: options?.name || "STORAGE",
+    description: options?.description || "AsyncStorage browser",
+    slot: "both",
+    icon: ({
+      size
+    }) => /*#__PURE__*/_jsx(StorageIcon, {
+      size: size
+    }),
+    component: StorageModalWithTabs,
+    props: {
+      requiredStorageKeys: options?.requiredStorageKeys || [],
+      enableSharedModalDimensions: options?.enableSharedModalDimensions !== undefined ? options.enableSharedModalDimensions : false
+    }
+  };
+}