react-native-storage-inspector 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 react-native-storage-inspector contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# react-native-storage-inspector
+
+react-native-storage-inspector is a plug-and-play developer tool that empowers you to browse, search, and edit all your app’s persisted data.
+
+## Supported libraries
+
+Tabs appear only when the corresponding package is installed (optional peer dependencies).
+
+| Library                                                                      | Package                                     | Storage      |
+| ---------------------------------------------------------------------------- | ------------------------------------------- | ------------ |
+| [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv)           | `react-native-mmkv`                         | MMKV         |
+| [Async Storage](https://github.com/react-native-async-storage/async-storage) | `@react-native-async-storage/async-storage` | AsyncStorage |
+| [react-native-keychain](https://github.com/oblador/react-native-keychain)    | `react-native-keychain`                     | Keychain     |
+| [expo-secure-store](https://docs.expo.dev/versions/latest/sdk/securestore/)  | `expo-secure-store`                         | Secure Store |
+
+## Installation
+
+Install the inspector and at least one storage library you use:
+
+```bash
+npm install react-native-storage-inspector
+# And one or more:
+npm install react-native-mmkv
+npm install @react-native-async-storage/async-storage
+npm install react-native-keychain
+npm install expo-secure-store
+```
+
+## Usage
+
+Use `StorageInspector` as a **full-page component**. It renders only the content area, no header, back button, or status bar. The consumer screen must handle those.
+
+Put it in a screen with `flex: 1`, and wrap with `SafeAreaView` (or your nav's safe area) so it respects status bar and notches.
+
+```tsx
+import { SafeAreaView } from 'react-native';
+import { StorageInspector } from 'react-native-storage-inspector';
+
+export function StorageInspectorScreen() {
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <StorageInspector />
+    </SafeAreaView>
+  );
+}
+```
+
+The component fills its container. The consumer is responsible for header, back button, and status bar (via SafeAreaView or your navigation setup).
+
+### Props
+
+| Prop              | Type                | Description                                                                                                                   |
+| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `mmkvInstances`   | `MMKV[]`            | **Required for MMKV.** Pass your MMKV instances to inspect.                                                                   |
+| `secureStoreKeys` | `string[]`          | **Required for Secure Store.** Keys to list (no list API).                                                                    |
+| `keychainKeys`    | `string[]`          | Optional. Only for internet credentials (no list API). Generic passwords auto-discovered via `getAllGenericPasswordServices`. |
+| `customAdapters`  | `IStorageAdapter[]` | Optional. Custom adapters for other storages.                                                                                 |
+
+## Expo
+
+- **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`.
+
+## API (for custom adapters)
+
+Implement `IStorageAdapter` and pass it via `customAdapters`:
+
+```ts
+interface IStorageAdapter {
+  type: string;
+  name: string;
+  getAllKeys(): Promise<string[]>;
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+  isAvailable(): boolean;
+}
+```
+
+## Development
+
+```bash
+npm run format       # Format all files with Prettier
+npm run format:check # Check formatting (fails if any file is unformatted)
+npm run lint         # Same as format:check
+npm test             # Run tests
+npm run build        # Build src/ to dist/
+```
+
+- **Formatting:** No auto-format. Run `npm run format` to fix. **Pre-commit** runs `format:check`; **pre-push** runs `format:check`, `test`, and `build`.
+- **Commits:** Use [Conventional Commits](https://www.conventionalcommits.org/) (enforced by `commit-msg` hook).
+- **Before publish:** `prepublishOnly` runs `format:check`, `test`, and `build`.
+
+### Publishing
+
+1. Run `npm version patch` (or `minor`/`major`).
+2. Run `npm publish` (prepublishOnly will run checks and build).
+
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for full guidelines. [Code of Conduct](docs/CODE_OF_CONDUCT.md).
+
+For AI assistants: see [ai/PRIMER.md](ai/PRIMER.md).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,111 @@
+import React from 'react';
+
+type StorageType = 'mmkv' | 'async-storage' | 'keychain' | 'expo-secure-store';
+
+interface StorageItem {
+    key: string;
+    value: string;
+}
+interface IStorageAdapter {
+    type: StorageType;
+    name: string;
+    getAllKeys(): Promise<string[]>;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    isAvailable(): boolean;
+}
+
+interface StorageInspectorProps {
+    mmkvInstances?: Array<{
+        getAllKeys(): string[];
+        getString(k: string): string | undefined;
+        set(k: string, v: string | number | boolean): void;
+        delete(k: string): void;
+    }>;
+    keychainKeys?: string[];
+    secureStoreKeys?: string[];
+    customAdapters?: IStorageAdapter[];
+}
+declare function StorageInspector({ mmkvInstances, keychainKeys: keychainKeysProp, secureStoreKeys: secureStoreKeysProp, customAdapters, }: StorageInspectorProps): React.JSX.Element;
+
+/**
+ * Centralized user-facing text for the storage inspector.
+ * Enables localization and consistent messaging.
+ */
+declare const strings: {
+    readonly noAdapterAvailable: "No storage adapter available. Install at least one of: react-native-mmkv, @react-native-async-storage/async-storage, react-native-keychain, expo-secure-store";
+    readonly keychainHint: "No generic password items yet. Add a key using + above, or pass keychainKeys for internet credentials.";
+    readonly secureStoreHint: "Secure Store has no list API. Pass secureStoreKeys prop with known keys, or add a key using + above.";
+    readonly loading: "Loading…";
+    readonly noItems: "No items";
+    readonly valueLabel: "Value";
+    readonly emptyValue: "(empty)";
+    readonly charCount: (n: number) => string;
+    readonly deleteItemTitle: (key: string) => string;
+    readonly deleteItemMessage: (key: string) => string;
+    readonly clearAllTitle: (name: string) => string;
+    readonly clearAllMessage: (count: number, name: string) => string;
+    readonly storageNotAvailable: "This storage is not available.";
+    readonly keychainHintShort: "No items yet. Add a key below, or pass keychainKeys for internet credentials.";
+    readonly edit: "Edit";
+    readonly delete: "Delete";
+    readonly addItem: "Add item";
+    readonly keyRequired: "Key is required";
+    readonly saveFailed: "Save failed";
+    readonly editItemTitle: (key: string) => string;
+    readonly addItemTitle: (storageName: string) => string;
+    readonly storageTypeLabel: (name: string) => string;
+    readonly keyLabel: "Key";
+    readonly enterKeyPlaceholder: "Enter key";
+    readonly enterValuePlaceholder: "Enter value";
+    readonly cancel: "Cancel";
+    readonly saving: "Saving…";
+    readonly save: "Save";
+    readonly add: "Add";
+    readonly confirmDelete: "Yes, delete";
+    readonly cancelKeep: "No, keep it";
+};
+
+/**
+ * Theme: minimalistic black and white palette.
+ * All colors centralized here - no direct hex values in components.
+ */
+declare const theme: {
+    readonly colors: {
+        readonly background: "#ffffff";
+        readonly backgroundSecondary: "#f5f5f5";
+        readonly backgroundTertiary: "#eeeeee";
+        readonly border: "#e0e0e0";
+        readonly borderLight: "#ebebeb";
+        readonly text: "#000000";
+        readonly textSecondary: "#666666";
+        readonly textMuted: "#999999";
+        readonly inverted: "#ffffff";
+    };
+};
+type Theme = typeof theme;
+
+type MMKVInstance = {
+    getAllKeys(): string[];
+    getString(key: string): string | undefined;
+    set(key: string, value: string | number | boolean): void;
+    delete(key: string): void;
+};
+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 };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import React from 'react';
+
+type StorageType = 'mmkv' | 'async-storage' | 'keychain' | 'expo-secure-store';
+
+interface StorageItem {
+    key: string;
+    value: string;
+}
+interface IStorageAdapter {
+    type: StorageType;
+    name: string;
+    getAllKeys(): Promise<string[]>;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    isAvailable(): boolean;
+}
+
+interface StorageInspectorProps {
+    mmkvInstances?: Array<{
+        getAllKeys(): string[];
+        getString(k: string): string | undefined;
+        set(k: string, v: string | number | boolean): void;
+        delete(k: string): void;
+    }>;
+    keychainKeys?: string[];
+    secureStoreKeys?: string[];
+    customAdapters?: IStorageAdapter[];
+}
+declare function StorageInspector({ mmkvInstances, keychainKeys: keychainKeysProp, secureStoreKeys: secureStoreKeysProp, customAdapters, }: StorageInspectorProps): React.JSX.Element;
+
+/**
+ * Centralized user-facing text for the storage inspector.
+ * Enables localization and consistent messaging.
+ */
+declare const strings: {
+    readonly noAdapterAvailable: "No storage adapter available. Install at least one of: react-native-mmkv, @react-native-async-storage/async-storage, react-native-keychain, expo-secure-store";
+    readonly keychainHint: "No generic password items yet. Add a key using + above, or pass keychainKeys for internet credentials.";
+    readonly secureStoreHint: "Secure Store has no list API. Pass secureStoreKeys prop with known keys, or add a key using + above.";
+    readonly loading: "Loading…";
+    readonly noItems: "No items";
+    readonly valueLabel: "Value";
+    readonly emptyValue: "(empty)";
+    readonly charCount: (n: number) => string;
+    readonly deleteItemTitle: (key: string) => string;
+    readonly deleteItemMessage: (key: string) => string;
+    readonly clearAllTitle: (name: string) => string;
+    readonly clearAllMessage: (count: number, name: string) => string;
+    readonly storageNotAvailable: "This storage is not available.";
+    readonly keychainHintShort: "No items yet. Add a key below, or pass keychainKeys for internet credentials.";
+    readonly edit: "Edit";
+    readonly delete: "Delete";
+    readonly addItem: "Add item";
+    readonly keyRequired: "Key is required";
+    readonly saveFailed: "Save failed";
+    readonly editItemTitle: (key: string) => string;
+    readonly addItemTitle: (storageName: string) => string;
+    readonly storageTypeLabel: (name: string) => string;
+    readonly keyLabel: "Key";
+    readonly enterKeyPlaceholder: "Enter key";
+    readonly enterValuePlaceholder: "Enter value";
+    readonly cancel: "Cancel";
+    readonly saving: "Saving…";
+    readonly save: "Save";
+    readonly add: "Add";
+    readonly confirmDelete: "Yes, delete";
+    readonly cancelKeep: "No, keep it";
+};
+
+/**
+ * Theme: minimalistic black and white palette.
+ * All colors centralized here - no direct hex values in components.
+ */
+declare const theme: {
+    readonly colors: {
+        readonly background: "#ffffff";
+        readonly backgroundSecondary: "#f5f5f5";
+        readonly backgroundTertiary: "#eeeeee";
+        readonly border: "#e0e0e0";
+        readonly borderLight: "#ebebeb";
+        readonly text: "#000000";
+        readonly textSecondary: "#666666";
+        readonly textMuted: "#999999";
+        readonly inverted: "#ffffff";
+    };
+};
+type Theme = typeof theme;
+
+type MMKVInstance = {
+    getAllKeys(): string[];
+    getString(key: string): string | undefined;
+    set(key: string, value: string | number | boolean): void;
+    delete(key: string): void;
+};
+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 };