@buoy-gg/shared-ui 1.7.2

package/lib/module/utils/persistentStorage.js

@@ -0,0 +1,588 @@
+"use strict";
+
+/**
+ * Persistent Storage for React Buoy DevTools
+ *
+ * This module provides a storage abstraction that persists independently of AsyncStorage.
+ * When expo-file-system is available, it uses file-based storage that survives
+ * AsyncStorage.clear() calls (e.g., during logout flows).
+ *
+ * Fallback hierarchy:
+ * 1. FileSystem (expo-file-system) - persistent, survives AsyncStorage.clear()
+ * 2. AsyncStorage - standard React Native storage
+ * 3. Memory - in-memory fallback when nothing else works
+ */
+
+import { devToolsStorageKeys } from "../storage/devToolsStorageKeys.js";
+
+// Web globals type declarations (for cross-platform compatibility)
+// These allow TypeScript to compile in React Native where window/localStorage don't exist
+
+// Types
+
+// Storage backend state
+
+let storageBackend = null;
+let initPromise = null;
+let initWarningShown = false;
+
+// Cached modules
+let FileSystem = null;
+let AsyncStorage = null;
+
+// Memory fallback
+const memoryStore = new Map();
+
+// Check if we're in a web environment with localStorage
+function isWebEnvironment() {
+  return typeof window !== "undefined" && window?.localStorage !== undefined;
+}
+
+// Constants
+const STORAGE_DIR_NAME = "react-buoy";
+const HEALTH_CHECK_FILE_NAME = ".health-check";
+function getStorageDir() {
+  if (!FileSystem?.documentDirectory) return null;
+  return `${FileSystem.documentDirectory}${STORAGE_DIR_NAME}/`;
+}
+function getFilePath(key) {
+  const dir = getStorageDir();
+  if (!dir) return null;
+  return `${dir}${encodeURIComponent(key)}.json`;
+}
+
+/**
+ * Try to load expo-file-system
+ *
+ * Note: We try the legacy import first (expo-file-system/legacy) for v19+ compatibility,
+ * then fall back to the main import for older versions.
+ */
+function loadFileSystem() {
+  if (FileSystem) return FileSystem;
+
+  // Try legacy import first (v19+ moved legacy functions here)
+  try {
+    const mod = require("expo-file-system/legacy");
+    FileSystem = mod?.default || mod;
+    if (FileSystem && FileSystem.documentDirectory) {
+      return FileSystem;
+    }
+    FileSystem = null;
+  } catch {
+    // Not available, try main import
+  }
+
+  // Fall back to main import (older versions or if legacy path doesn't exist)
+  try {
+    const mod = require("expo-file-system");
+    FileSystem = mod?.default || mod;
+    if (FileSystem && FileSystem.documentDirectory) {
+      return FileSystem;
+    }
+    FileSystem = null;
+  } catch {
+    // Not installed or not available
+  }
+  return null;
+}
+
+/**
+ * Try to load AsyncStorage
+ */
+function loadAsyncStorage() {
+  if (AsyncStorage) return AsyncStorage;
+  try {
+    const mod = require("@react-native-async-storage/async-storage");
+    AsyncStorage = mod?.default || mod;
+    if (AsyncStorage && typeof AsyncStorage.getItem === "function") {
+      return AsyncStorage;
+    }
+    AsyncStorage = null;
+  } catch {
+    // Not installed or not available
+  }
+  return null;
+}
+
+/**
+ * Test if FileSystem works with CRUD operations
+ */
+async function testFileSystem() {
+  const fs = loadFileSystem();
+  if (!fs || !fs.documentDirectory) {
+    return false;
+  }
+  const storageDir = getStorageDir();
+  if (!storageDir) return false;
+  const healthCheckFile = `${storageDir}${HEALTH_CHECK_FILE_NAME}`;
+  try {
+    // Ensure directory exists
+    const dirInfo = await fs.getInfoAsync(storageDir);
+    if (!dirInfo.exists) {
+      await fs.makeDirectoryAsync(storageDir, {
+        intermediates: true
+      });
+    }
+
+    // Test write
+    const testData = `health-check-${Date.now()}`;
+    await fs.writeAsStringAsync(healthCheckFile, testData);
+
+    // Test read
+    const readBack = await fs.readAsStringAsync(healthCheckFile);
+    if (readBack !== testData) {
+      return false;
+    }
+
+    // Test delete
+    await fs.deleteAsync(healthCheckFile, {
+      idempotent: true
+    });
+    return true;
+  } catch (error) {
+    console.warn("[React Buoy] FileSystem health check failed:", error);
+    return false;
+  }
+}
+
+/**
+ * Migrate existing AsyncStorage keys to FileSystem
+ */
+async function migrateFromAsyncStorage() {
+  const asyncStorage = loadAsyncStorage();
+  if (!asyncStorage) return;
+  try {
+    const allKeys = await asyncStorage.getAllKeys();
+    const buoyKeys = allKeys.filter(k => k.startsWith(devToolsStorageKeys.base));
+    if (buoyKeys.length === 0) {
+      return; // Nothing to migrate
+    }
+    const pairs = await asyncStorage.multiGet(buoyKeys);
+    let migratedCount = 0;
+    for (const [fullKey, value] of pairs) {
+      if (value !== null) {
+        // Store in file system (key already has the prefix)
+        await fileSystemStorage.setItem(fullKey, value);
+        migratedCount++;
+      }
+    }
+
+    // Migration complete - count is ${migratedCount} items
+    void migratedCount;
+
+    // Optionally: clean up old AsyncStorage keys after successful migration
+    // await asyncStorage.multiRemove(buoyKeys);
+  } catch (error) {
+    console.warn("[React Buoy] Migration failed:", error);
+    // Continue anyway - not critical
+  }
+}
+
+// File system storage implementation
+const fileSystemStorage = {
+  async getItem(key) {
+    const fs = loadFileSystem();
+    if (!fs) return null;
+    const filePath = getFilePath(key);
+    if (!filePath) return null;
+    try {
+      // Check if file exists before reading (best practice from Expo docs)
+      const fileInfo = await fs.getInfoAsync(filePath);
+      if (!fileInfo.exists) {
+        return null;
+      }
+      const content = await fs.readAsStringAsync(filePath);
+      return content;
+    } catch {
+      return null; // File doesn't exist or read failed
+    }
+  },
+  async setItem(key, value) {
+    const fs = loadFileSystem();
+    if (!fs) return;
+    const storageDir = getStorageDir();
+    const filePath = getFilePath(key);
+    if (!storageDir || !filePath) return;
+    try {
+      // Ensure directory exists
+      const dirInfo = await fs.getInfoAsync(storageDir);
+      if (!dirInfo.exists) {
+        await fs.makeDirectoryAsync(storageDir, {
+          intermediates: true
+        });
+      }
+      await fs.writeAsStringAsync(filePath, value);
+    } catch (error) {
+      console.warn("[React Buoy] FileSystem write failed:", error);
+    }
+  },
+  async removeItem(key) {
+    const fs = loadFileSystem();
+    if (!fs) return;
+    const filePath = getFilePath(key);
+    if (!filePath) return;
+    try {
+      await fs.deleteAsync(filePath, {
+        idempotent: true
+      });
+    } catch {
+      // Ignore if doesn't exist
+    }
+  },
+  async getAllKeys() {
+    const fs = loadFileSystem();
+    if (!fs) return [];
+    const storageDir = getStorageDir();
+    if (!storageDir) return [];
+    try {
+      const dirInfo = await fs.getInfoAsync(storageDir);
+      if (!dirInfo.exists) return [];
+      const files = await fs.readDirectoryAsync(storageDir);
+      return files.filter(f => f.endsWith(".json")).map(f => decodeURIComponent(f.replace(".json", "")));
+    } catch {
+      return [];
+    }
+  },
+  async multiGet(keys) {
+    const results = [];
+    for (const key of keys) {
+      const value = await this.getItem(key);
+      results.push([key, value]);
+    }
+    return results;
+  },
+  async multiRemove(keys) {
+    for (const key of keys) {
+      await this.removeItem(key);
+    }
+  },
+  async clear() {
+    const fs = loadFileSystem();
+    if (!fs) return;
+    const storageDir = getStorageDir();
+    if (!storageDir) return;
+    try {
+      await fs.deleteAsync(storageDir, {
+        idempotent: true
+      });
+    } catch {
+      // Ignore
+    }
+  }
+};
+
+// AsyncStorage adapter
+const asyncStorageAdapter = {
+  async getItem(key) {
+    const storage = loadAsyncStorage();
+    if (!storage) return memoryStore.get(key) ?? null;
+    try {
+      return await storage.getItem(key);
+    } catch {
+      return memoryStore.get(key) ?? null;
+    }
+  },
+  async setItem(key, value) {
+    const storage = loadAsyncStorage();
+    if (!storage) {
+      memoryStore.set(key, value);
+      return;
+    }
+    try {
+      await storage.setItem(key, value);
+    } catch {
+      memoryStore.set(key, value);
+    }
+  },
+  async removeItem(key) {
+    const storage = loadAsyncStorage();
+    memoryStore.delete(key);
+    if (!storage) return;
+    try {
+      await storage.removeItem(key);
+    } catch {
+      // Ignore
+    }
+  },
+  async getAllKeys() {
+    const storage = loadAsyncStorage();
+    if (!storage) return Array.from(memoryStore.keys());
+    try {
+      const keys = await storage.getAllKeys();
+      return keys.filter(k => k.startsWith(devToolsStorageKeys.base));
+    } catch {
+      return Array.from(memoryStore.keys());
+    }
+  },
+  async multiGet(keys) {
+    const storage = loadAsyncStorage();
+    if (!storage) {
+      return keys.map(k => [k, memoryStore.get(k) ?? null]);
+    }
+    try {
+      const results = await storage.multiGet(keys);
+      return results;
+    } catch {
+      return keys.map(k => [k, memoryStore.get(k) ?? null]);
+    }
+  },
+  async multiRemove(keys) {
+    keys.forEach(k => memoryStore.delete(k));
+    const storage = loadAsyncStorage();
+    if (!storage) return;
+    try {
+      await storage.multiRemove(keys);
+    } catch {
+      // Ignore
+    }
+  },
+  async clear() {
+    memoryStore.clear();
+    const storage = loadAsyncStorage();
+    if (!storage) return;
+    try {
+      const allKeys = await storage.getAllKeys();
+      const buoyKeys = allKeys.filter(k => k.startsWith(devToolsStorageKeys.base));
+      if (buoyKeys.length > 0) {
+        await storage.multiRemove(buoyKeys);
+      }
+    } catch {
+      // Ignore
+    }
+  }
+};
+
+// localStorage adapter (for web environments)
+const localStorageAdapter = {
+  async getItem(key) {
+    if (!isWebEnvironment()) return memoryStore.get(key) ?? null;
+    try {
+      return window.localStorage.getItem(key);
+    } catch {
+      return memoryStore.get(key) ?? null;
+    }
+  },
+  async setItem(key, value) {
+    if (!isWebEnvironment()) {
+      memoryStore.set(key, value);
+      return;
+    }
+    try {
+      window.localStorage.setItem(key, value);
+    } catch {
+      memoryStore.set(key, value);
+    }
+  },
+  async removeItem(key) {
+    memoryStore.delete(key);
+    if (!isWebEnvironment()) return;
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+      // Ignore
+    }
+  },
+  async getAllKeys() {
+    if (!isWebEnvironment()) return Array.from(memoryStore.keys());
+    try {
+      const keys = [];
+      const storage = window.localStorage;
+      for (let i = 0; i < storage.length; i++) {
+        const key = storage.key(i);
+        if (key && key.startsWith(devToolsStorageKeys.base)) {
+          keys.push(key);
+        }
+      }
+      return keys;
+    } catch {
+      return Array.from(memoryStore.keys());
+    }
+  },
+  async multiGet(keys) {
+    const results = [];
+    for (const key of keys) {
+      const value = await this.getItem(key);
+      results.push([key, value]);
+    }
+    return results;
+  },
+  async multiRemove(keys) {
+    for (const key of keys) {
+      await this.removeItem(key);
+    }
+  },
+  async clear() {
+    memoryStore.clear();
+    if (!isWebEnvironment()) return;
+    try {
+      const keys = await this.getAllKeys();
+      const storage = window.localStorage;
+      for (const key of keys) {
+        storage.removeItem(key);
+      }
+    } catch {
+      // Ignore
+    }
+  }
+};
+
+// Memory-only storage
+const memoryStorage = {
+  async getItem(key) {
+    return memoryStore.get(key) ?? null;
+  },
+  async setItem(key, value) {
+    memoryStore.set(key, value);
+  },
+  async removeItem(key) {
+    memoryStore.delete(key);
+  },
+  async getAllKeys() {
+    return Array.from(memoryStore.keys());
+  },
+  async multiGet(keys) {
+    return keys.map(k => [k, memoryStore.get(k) ?? null]);
+  },
+  async multiRemove(keys) {
+    keys.forEach(k => memoryStore.delete(k));
+  },
+  async clear() {
+    memoryStore.clear();
+  }
+};
+
+/**
+ * Initialize storage - determines which backend to use
+ *
+ * Fallback hierarchy:
+ * 1. FileSystem (expo-file-system) - persistent, survives AsyncStorage.clear()
+ * 2. AsyncStorage - standard React Native storage
+ * 3. localStorage - web browser storage
+ * 4. Memory - in-memory fallback when nothing else works
+ */
+async function initStorage() {
+  // Only run once
+  if (storageBackend !== null) return;
+
+  // Test FileSystem first (React Native with expo-file-system)
+  const fileSystemWorks = await testFileSystem();
+  if (fileSystemWorks) {
+    // Check if we need to migrate from AsyncStorage
+    const existingFiles = await fileSystemStorage.getAllKeys();
+    if (existingFiles.length === 0) {
+      // Empty file storage - check for AsyncStorage data to migrate
+      await migrateFromAsyncStorage();
+    }
+    storageBackend = "filesystem";
+  } else {
+    // Try AsyncStorage (React Native)
+    const asyncStorage = loadAsyncStorage();
+    if (asyncStorage) {
+      storageBackend = "asyncstorage";
+      if (!initWarningShown) {
+        initWarningShown = true;
+        console.warn("[React Buoy] Using AsyncStorage fallback. " + "Settings may be lost if AsyncStorage is cleared. " + "Install expo-file-system for persistent storage.");
+      }
+    } else if (isWebEnvironment()) {
+      // Try localStorage (Web)
+      storageBackend = "localstorage";
+    } else {
+      storageBackend = "memory";
+      if (!initWarningShown) {
+        initWarningShown = true;
+        console.warn("[React Buoy] Using in-memory storage. " + "Settings will be lost on app restart.");
+      }
+    }
+  }
+}
+
+/**
+ * Ensure init runs before any storage operation
+ */
+function ensureInit() {
+  if (!initPromise) {
+    initPromise = initStorage();
+  }
+  return initPromise;
+}
+
+/**
+ * Get the current storage implementation based on detected backend
+ */
+function getStorage() {
+  switch (storageBackend) {
+    case "filesystem":
+      return fileSystemStorage;
+    case "asyncstorage":
+      return asyncStorageAdapter;
+    case "localstorage":
+      return localStorageAdapter;
+    case "memory":
+    default:
+      return memoryStorage;
+  }
+}
+
+/**
+ * Persistent storage for React Buoy DevTools
+ *
+ * Uses FileSystem when available (survives AsyncStorage.clear()),
+ * falls back to AsyncStorage, then localStorage (web), then memory.
+ *
+ * Same API as AsyncStorage for easy migration.
+ */
+export const persistentStorage = {
+  async getItem(key) {
+    await ensureInit();
+    return getStorage().getItem(key);
+  },
+  async setItem(key, value) {
+    await ensureInit();
+    return getStorage().setItem(key, value);
+  },
+  async removeItem(key) {
+    await ensureInit();
+    return getStorage().removeItem(key);
+  },
+  async getAllKeys() {
+    await ensureInit();
+    return getStorage().getAllKeys();
+  },
+  async multiGet(keys) {
+    await ensureInit();
+    return getStorage().multiGet(keys);
+  },
+  async multiRemove(keys) {
+    await ensureInit();
+    return getStorage().multiRemove(keys);
+  },
+  async clear() {
+    await ensureInit();
+    return getStorage().clear();
+  }
+};
+
+/**
+ * Check if persistent storage (FileSystem) is being used
+ */
+export async function isUsingPersistentStorage() {
+  await ensureInit();
+  return storageBackend === "filesystem";
+}
+
+/**
+ * Get the current storage backend type
+ */
+export async function getStorageBackendType() {
+  await ensureInit();
+  return storageBackend ?? "memory";
+}
+
+/**
+ * Force re-initialization of storage (useful for testing)
+ */
+export function resetStorageInit() {
+  storageBackend = null;
+  initPromise = null;
+  initWarningShown = false;
+}

package/lib/module/utils/safeAsyncStorage.js

@@ -0,0 +1,64 @@
+"use strict";
+
+// Safe storage wrapper that uses persistent file storage when available,
+// falling back to AsyncStorage, then in-memory store.
+//
+// This module re-exports the persistentStorage API with the legacy function names
+// (safeGetItem, safeSetItem, safeRemoveItem) for backwards compatibility.
+
+import { useEffect, useMemo, useState } from "react";
+import { persistentStorage, isUsingPersistentStorage } from "./persistentStorage.js";
+
+/**
+ * Read a value from persistent storage (FileSystem > AsyncStorage > Memory)
+ *
+ * @deprecated Use `persistentStorage.getItem()` directly for new code
+ */
+export async function safeGetItem(key) {
+  return persistentStorage.getItem(key);
+}
+
+/**
+ * Persist a value to storage (FileSystem > AsyncStorage > Memory)
+ *
+ * @deprecated Use `persistentStorage.setItem()` directly for new code
+ */
+export async function safeSetItem(key, value) {
+  return persistentStorage.setItem(key, value);
+}
+
+/**
+ * Remove an item from storage
+ *
+ * @deprecated Use `persistentStorage.removeItem()` directly for new code
+ */
+export async function safeRemoveItem(key) {
+  return persistentStorage.removeItem(key);
+}
+
+/**
+ * Check if persistent storage (FileSystem) is being used
+ * Returns true if FileSystem storage is available and working
+ */
+export async function isPersistentStorageAvailable() {
+  return isUsingPersistentStorage();
+}
+
+/**
+ * React hook exposing storage APIs backed by persistent storage
+ *
+ * @deprecated Use `persistentStorage` directly for new code
+ */
+export function useSafeAsyncStorage() {
+  const [isPersistent, setIsPersistent] = useState(false);
+  useEffect(() => {
+    // Check if persistent storage is available
+    isUsingPersistentStorage().then(setIsPersistent);
+  }, []);
+  return useMemo(() => ({
+    getItem: safeGetItem,
+    setItem: safeSetItem,
+    removeItem: safeRemoveItem,
+    isPersistent
+  }), [isPersistent]);
+}