react-native-storage-inspector 1.0.0 → 1.0.1

package/README.md

@@ -61,6 +61,18 @@ The component fills its container. The consumer is responsible for header, back
 - **Expo Go**: Async Storage and Expo Secure Store work. MMKV and Keychain need native code and are not available in Expo Go.
 - **Development build**: All four storages work with `expo-dev-client`.
 
+## Troubleshooting
+
+If you see **"Requiring unknown module"** for optional storage packages (AsyncStorage, Keychain, Secure Store), add to your `metro.config.js`:
+
+```js
+const { getDefaultConfig } = require('expo/metro-config');
+const config = getDefaultConfig(__dirname);
+config.transformer ??= {};
+config.transformer.allowOptionalDependencies = true;
+module.exports = config;
+```
+
 ## API (for custom adapters)
 
 Implement `IStorageAdapter` and pass it via `customAdapters`:

package/dist/index.d.mts

@@ -16,6 +16,81 @@ interface IStorageAdapter {
     isAvailable(): boolean;
 }
 
+/**
+ * AsyncStorage-compatible module interface.
+ * Pass your AsyncStorage instance to avoid Metro "unknown module" errors in Expo:
+ * @example
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * createAsyncStorageAdapter(AsyncStorage)
+ */
+type AsyncStorageModule = {
+    getAllKeys(): Promise<string[]>;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+};
+/**
+ * Creates an AsyncStorage adapter. Pass the AsyncStorage instance for reliable
+ * bundling in Expo/Metro (avoids "unknown module" errors):
+ *
+ * @example
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * createAsyncStorageAdapter(AsyncStorage)
+ */
+declare function createAsyncStorageAdapter(instance?: AsyncStorageModule | null): IStorageAdapter;
+
+/**
+ * Keychain-compatible module. Pass your keychain instance to avoid Metro
+ * "unknown module" errors in Expo.
+ */
+type KeychainModule = {
+    getAllGenericPasswordServices?(options?: object): Promise<string[]>;
+    getGenericPassword?(options?: {
+        service?: string;
+    }): Promise<{
+        password: string;
+    } | false>;
+    setGenericPassword?(username: string, password: string, options?: {
+        service?: string;
+    }): Promise<{
+        storage: string;
+    } | false>;
+    resetGenericPassword?(options?: {
+        service?: string;
+    }): Promise<void>;
+    setInternetCredentials(server: string, username: string, password: string): Promise<{
+        storage: string;
+    } | false>;
+    getInternetCredentials(server: string): Promise<{
+        username: string;
+        password: string;
+    } | null>;
+    resetInternetCredentials(server: string): Promise<void>;
+};
+/**
+ * Keychain adapter. Pass the keychain instance for reliable bundling in Expo:
+ * @example import * as Keychain from 'react-native-keychain';
+ * createKeychainAdapter([], Keychain)
+ */
+declare function createKeychainAdapter(knownKeys?: string[], instance?: KeychainModule | null): IStorageAdapter;
+
+/**
+ * expo-secure-store compatible module. Pass the module to avoid Metro
+ * "unknown module" errors in Expo.
+ */
+type SecureStoreModule = {
+    getItemAsync(key: string): Promise<string | null>;
+    setItemAsync(key: string, value: string): Promise<void>;
+    deleteItemAsync(key: string): Promise<void>;
+};
+/**
+ * expo-secure-store has no API to list all keys. Pass knownKeys to inspect
+ * those entries. Pass the module for reliable bundling in Expo:
+ * @example import * as SecureStore from 'expo-secure-store';
+ * createSecureStoreAdapter([], SecureStore)
+ */
+declare function createSecureStoreAdapter(knownKeys?: string[], instance?: SecureStoreModule | null): IStorageAdapter;
+
 interface StorageInspectorProps {
     mmkvInstances?: Array<{
         getAllKeys(): string[];
@@ -23,11 +98,17 @@ interface StorageInspectorProps {
         set(k: string, v: string | number | boolean): void;
         delete(k: string): void;
     }>;
+    /** Pass AsyncStorage to avoid Metro "unknown module" in Expo. */
+    asyncStorageInstance?: AsyncStorageModule | null;
     keychainKeys?: string[];
+    /** Pass Keychain module to avoid Metro "unknown module" in Expo. */
+    keychainInstance?: KeychainModule | null;
     secureStoreKeys?: string[];
+    /** Pass SecureStore module to avoid Metro "unknown module" in Expo. */
+    secureStoreInstance?: SecureStoreModule | null;
     customAdapters?: IStorageAdapter[];
 }
-declare function StorageInspector({ mmkvInstances, keychainKeys: keychainKeysProp, secureStoreKeys: secureStoreKeysProp, customAdapters, }: StorageInspectorProps): React.JSX.Element;
+declare function StorageInspector({ mmkvInstances, asyncStorageInstance, keychainKeys: keychainKeysProp, keychainInstance, secureStoreKeys: secureStoreKeysProp, secureStoreInstance, customAdapters, }: StorageInspectorProps): React.JSX.Element;
 
 /**
  * Centralized user-facing text for the storage inspector.
@@ -94,18 +175,4 @@ type MMKVInstance = {
 };
 declare function createMMKVAdapter(instance: MMKVInstance, name?: string): IStorageAdapter;
 
-declare function createAsyncStorageAdapter(): IStorageAdapter;
-
-/**
- * Keychain adapter. Auto-discovers keys via getAllGenericPasswordServices() (generic passwords).
- * Pass knownKeys only if you also store data with setInternetCredentials – those cannot be listed.
- */
-declare function createKeychainAdapter(knownKeys?: string[]): IStorageAdapter;
-
-/**
- * expo-secure-store has no API to list all keys. Pass knownKeys to inspect
- * those entries, or keys will appear after the user adds them via the inspector.
- */
-declare function createSecureStoreAdapter(knownKeys?: string[]): IStorageAdapter;
-
-export { type IStorageAdapter, StorageInspector, type StorageInspectorProps, type StorageItem, type Theme, createAsyncStorageAdapter, createKeychainAdapter, createMMKVAdapter, createSecureStoreAdapter, strings, theme };
+export { type AsyncStorageModule, type IStorageAdapter, type KeychainModule, type SecureStoreModule, StorageInspector, type StorageInspectorProps, type StorageItem, type Theme, createAsyncStorageAdapter, createKeychainAdapter, createMMKVAdapter, createSecureStoreAdapter, strings, theme };

package/dist/index.d.ts

@@ -16,6 +16,81 @@ interface IStorageAdapter {
     isAvailable(): boolean;
 }
 
+/**
+ * AsyncStorage-compatible module interface.
+ * Pass your AsyncStorage instance to avoid Metro "unknown module" errors in Expo:
+ * @example
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * createAsyncStorageAdapter(AsyncStorage)
+ */
+type AsyncStorageModule = {
+    getAllKeys(): Promise<string[]>;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+};
+/**
+ * Creates an AsyncStorage adapter. Pass the AsyncStorage instance for reliable
+ * bundling in Expo/Metro (avoids "unknown module" errors):
+ *
+ * @example
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * createAsyncStorageAdapter(AsyncStorage)
+ */
+declare function createAsyncStorageAdapter(instance?: AsyncStorageModule | null): IStorageAdapter;
+
+/**
+ * Keychain-compatible module. Pass your keychain instance to avoid Metro
+ * "unknown module" errors in Expo.
+ */
+type KeychainModule = {
+    getAllGenericPasswordServices?(options?: object): Promise<string[]>;
+    getGenericPassword?(options?: {
+        service?: string;
+    }): Promise<{
+        password: string;
+    } | false>;
+    setGenericPassword?(username: string, password: string, options?: {
+        service?: string;
+    }): Promise<{
+        storage: string;
+    } | false>;
+    resetGenericPassword?(options?: {
+        service?: string;
+    }): Promise<void>;
+    setInternetCredentials(server: string, username: string, password: string): Promise<{
+        storage: string;
+    } | false>;
+    getInternetCredentials(server: string): Promise<{
+        username: string;
+        password: string;
+    } | null>;
+    resetInternetCredentials(server: string): Promise<void>;
+};
+/**
+ * Keychain adapter. Pass the keychain instance for reliable bundling in Expo:
+ * @example import * as Keychain from 'react-native-keychain';
+ * createKeychainAdapter([], Keychain)
+ */
+declare function createKeychainAdapter(knownKeys?: string[], instance?: KeychainModule | null): IStorageAdapter;
+
+/**
+ * expo-secure-store compatible module. Pass the module to avoid Metro
+ * "unknown module" errors in Expo.
+ */
+type SecureStoreModule = {
+    getItemAsync(key: string): Promise<string | null>;
+    setItemAsync(key: string, value: string): Promise<void>;
+    deleteItemAsync(key: string): Promise<void>;
+};
+/**
+ * expo-secure-store has no API to list all keys. Pass knownKeys to inspect
+ * those entries. Pass the module for reliable bundling in Expo:
+ * @example import * as SecureStore from 'expo-secure-store';
+ * createSecureStoreAdapter([], SecureStore)
+ */
+declare function createSecureStoreAdapter(knownKeys?: string[], instance?: SecureStoreModule | null): IStorageAdapter;
+
 interface StorageInspectorProps {
     mmkvInstances?: Array<{
         getAllKeys(): string[];
@@ -23,11 +98,17 @@ interface StorageInspectorProps {
         set(k: string, v: string | number | boolean): void;
         delete(k: string): void;
     }>;
+    /** Pass AsyncStorage to avoid Metro "unknown module" in Expo. */
+    asyncStorageInstance?: AsyncStorageModule | null;
     keychainKeys?: string[];
+    /** Pass Keychain module to avoid Metro "unknown module" in Expo. */
+    keychainInstance?: KeychainModule | null;
     secureStoreKeys?: string[];
+    /** Pass SecureStore module to avoid Metro "unknown module" in Expo. */
+    secureStoreInstance?: SecureStoreModule | null;
     customAdapters?: IStorageAdapter[];
 }
-declare function StorageInspector({ mmkvInstances, keychainKeys: keychainKeysProp, secureStoreKeys: secureStoreKeysProp, customAdapters, }: StorageInspectorProps): React.JSX.Element;
+declare function StorageInspector({ mmkvInstances, asyncStorageInstance, keychainKeys: keychainKeysProp, keychainInstance, secureStoreKeys: secureStoreKeysProp, secureStoreInstance, customAdapters, }: StorageInspectorProps): React.JSX.Element;
 
 /**
  * Centralized user-facing text for the storage inspector.
@@ -94,18 +175,4 @@ type MMKVInstance = {
 };
 declare function createMMKVAdapter(instance: MMKVInstance, name?: string): IStorageAdapter;
 
-declare function createAsyncStorageAdapter(): IStorageAdapter;
-
-/**
- * Keychain adapter. Auto-discovers keys via getAllGenericPasswordServices() (generic passwords).
- * Pass knownKeys only if you also store data with setInternetCredentials – those cannot be listed.
- */
-declare function createKeychainAdapter(knownKeys?: string[]): IStorageAdapter;
-
-/**
- * expo-secure-store has no API to list all keys. Pass knownKeys to inspect
- * those entries, or keys will appear after the user adds them via the inspector.
- */
-declare function createSecureStoreAdapter(knownKeys?: string[]): IStorageAdapter;
-
-export { type IStorageAdapter, StorageInspector, type StorageInspectorProps, type StorageItem, type Theme, createAsyncStorageAdapter, createKeychainAdapter, createMMKVAdapter, createSecureStoreAdapter, strings, theme };
+export { type AsyncStorageModule, type IStorageAdapter, type KeychainModule, type SecureStoreModule, StorageInspector, type StorageInspectorProps, type StorageItem, type Theme, createAsyncStorageAdapter, createKeychainAdapter, createMMKVAdapter, createSecureStoreAdapter, strings, theme };

package/dist/index.js

@@ -42,62 +42,61 @@ function createMMKVAdapter(instance, name) {
 
 // src/adapters/async-storage.ts
 var asyncStorage = null;
-function getAsyncStorage() {
-  if (asyncStorage) return asyncStorage;
+function getAsyncStorageFromRequire() {
   try {
-    asyncStorage = __require("@react-native-async-storage/async-storage").default;
-    return asyncStorage;
+    const mod = require("@react-native-async-storage/async-storage");
+    return mod.default ?? mod;
   } catch {
     return null;
   }
 }
-function createAsyncStorageAdapter() {
+function createAsyncStorageAdapter(instance) {
+  const getStorage = () => instance ?? (asyncStorage ?? (asyncStorage = getAsyncStorageFromRequire()));
   return {
     type: "async-storage",
     name: "Async Storage",
     async getAllKeys() {
-      const storage = getAsyncStorage();
+      const storage = getStorage();
       if (!storage) return [];
       return storage.getAllKeys();
     },
     async getItem(key) {
-      const storage = getAsyncStorage();
+      const storage = getStorage();
       if (!storage) return null;
       return storage.getItem(key);
     },
     async setItem(key, value) {
-      const storage = getAsyncStorage();
+      const storage = getStorage();
       if (!storage) throw new Error("AsyncStorage is not available");
       await storage.setItem(key, value);
     },
     async removeItem(key) {
-      const storage = getAsyncStorage();
+      const storage = getStorage();
       if (!storage) throw new Error("AsyncStorage is not available");
       await storage.removeItem(key);
     },
     isAvailable() {
-      return getAsyncStorage() !== null;
+      return getStorage() !== null;
     }
   };
 }
 
 // src/adapters/keychain.ts
 var keychain = null;
-function getKeychain() {
-  if (keychain) return keychain;
+function getKeychainFromRequire() {
   try {
-    keychain = __require("react-native-keychain");
-    return keychain;
+    return require("react-native-keychain");
   } catch {
     return null;
   }
 }
-function createKeychainAdapter(knownKeys = []) {
+function createKeychainAdapter(knownKeys = [], instance) {
+  const getKc = () => instance ?? (keychain ?? (keychain = getKeychainFromRequire()));
   return {
     type: "keychain",
     name: "Keychain",
     async getAllKeys() {
-      const kc = getKeychain();
+      const kc = getKc();
       if (!kc) return [...knownKeys];
       const genericServices = [];
       if (typeof kc.getAllGenericPasswordServices === "function") {
@@ -111,7 +110,7 @@ function createKeychainAdapter(knownKeys = []) {
       return Array.from(merged);
     },
     async getItem(key) {
-      const kc = getKeychain();
+      const kc = getKc();
       if (!kc) return null;
       if (typeof kc.getGenericPassword === "function") {
         try {
@@ -126,7 +125,7 @@ function createKeychainAdapter(knownKeys = []) {
       return creds?.password ?? null;
     },
     async setItem(key, value) {
-      const kc = getKeychain();
+      const kc = getKc();
       if (!kc) throw new Error("react-native-keychain is not available");
       if (typeof kc.setGenericPassword === "function") {
         const result2 = await kc.setGenericPassword(key, value, { service: key });
@@ -137,7 +136,7 @@ function createKeychainAdapter(knownKeys = []) {
       if (result === false) throw new Error("Keychain set failed");
     },
     async removeItem(key) {
-      const kc = getKeychain();
+      const kc = getKc();
       if (!kc) throw new Error("react-native-keychain is not available");
       if (typeof kc.resetGenericPassword === "function") {
         await kc.resetGenericPassword({ service: key });
@@ -145,23 +144,22 @@ function createKeychainAdapter(knownKeys = []) {
       await kc.resetInternetCredentials(key);
     },
     isAvailable() {
-      return getKeychain() !== null;
+      return getKc() !== null;
     }
   };
 }
 
 // src/adapters/secure-store.ts
 var secureStore = null;
-function getSecureStore() {
-  if (secureStore) return secureStore;
+function getSecureStoreFromRequire() {
   try {
-    secureStore = __require("expo-secure-store");
-    return secureStore;
+    return require("expo-secure-store");
   } catch {
     return null;
   }
 }
-function createSecureStoreAdapter(knownKeys = []) {
+function createSecureStoreAdapter(knownKeys = [], instance) {
+  const getStore = () => instance ?? (secureStore ?? (secureStore = getSecureStoreFromRequire()));
   return {
     type: "expo-secure-store",
     name: "Secure Store",
@@ -169,22 +167,22 @@ function createSecureStoreAdapter(knownKeys = []) {
       return [...knownKeys];
     },
     async getItem(key) {
-      const store = getSecureStore();
+      const store = getStore();
       if (!store) return null;
       return store.getItemAsync(key);
     },
     async setItem(key, value) {
-      const store = getSecureStore();
+      const store = getStore();
       if (!store) throw new Error("expo-secure-store is not available");
       await store.setItemAsync(key, value);
     },
     async removeItem(key) {
-      const store = getSecureStore();
+      const store = getStore();
       if (!store) throw new Error("expo-secure-store is not available");
       await store.deleteItemAsync(key);
     },
     isAvailable() {
-      return getSecureStore() !== null;
+      return getStore() !== null;
     }
   };
 }
@@ -1134,8 +1132,11 @@ function StorageSection({
 // src/components/StorageInspector.tsx
 function StorageInspector({
   mmkvInstances = [],
+  asyncStorageInstance,
   keychainKeys: keychainKeysProp,
+  keychainInstance,
   secureStoreKeys: secureStoreKeysProp,
+  secureStoreInstance,
   customAdapters = []
 }) {
   const [keychainKeysAdded, setKeychainKeysAdded] = React6.useState([]);
@@ -1158,15 +1159,26 @@ function StorageInspector({
         createMMKVAdapter(inst, mmkvInstances.length > 1 ? `MMKV ${i + 1}` : "MMKV")
       );
     });
-    const asyncAdapter = createAsyncStorageAdapter();
+    const asyncAdapter = createAsyncStorageAdapter(asyncStorageInstance);
     if (asyncAdapter.isAvailable()) list.push(asyncAdapter);
-    const keychainAdapter = createKeychainAdapter(keychainKeys);
+    const keychainAdapter = createKeychainAdapter(keychainKeys, keychainInstance);
     if (keychainAdapter.isAvailable()) list.push(keychainAdapter);
-    const secureStoreAdapter = createSecureStoreAdapter(secureStoreKeys);
+    const secureStoreAdapter = createSecureStoreAdapter(
+      secureStoreKeys,
+      secureStoreInstance
+    );
     if (secureStoreAdapter.isAvailable()) list.push(secureStoreAdapter);
     list.push(...customAdapters);
     return list;
-  }, [mmkvInstances, keychainKeys, secureStoreKeys, customAdapters]);
+  }, [
+    mmkvInstances,
+    asyncStorageInstance,
+    keychainKeys,
+    keychainInstance,
+    secureStoreKeys,
+    secureStoreInstance,
+    customAdapters
+  ]);
   const handleKeychainKeyAdded = (key) => {
     setKeychainKeysAdded(
       (prev) => prev.includes(key) ? prev : [...prev, key]