@buoy-gg/storage 5.0.0 → 6.0.1

package/README.md

@@ -1,607 +1,80 @@
-# @buoy/storage
+# @buoy-gg/storage
 
-[![npm](https://img.shields.io/npm/v/@buoy%2Fstorage)](https://www.npmjs.com/package/@buoy/storage)
+[![npm version](https://img.shields.io/npm/v/@buoy-gg/storage?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/storage) [![npm downloads](https://img.shields.io/npm/dm/@buoy-gg/storage?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/storage)
 
-Storage browser and monitoring tool for React Native development. Supports both AsyncStorage and MMKV.
+**Browse and edit every key-value pair your React Native app persists — AsyncStorage, MMKV, and SecureStore in one explorer with real-time updates.**
 
-## Features
+Part of [Buoy](https://github.com/Buoy-gg/buoy) — devtools that live inside your React Native app. Install it and it auto-appears in the floating menu from [`@buoy-gg/core`](https://www.npmjs.com/package/@buoy-gg/core).
 
-- **Storage Browser**: Browse all AsyncStorage and MMKV keys and values
-- **MMKV Support**: Monitor and debug MMKV instances (including encrypted storage)
-- **Multiple Storage Types**: Support for AsyncStorage, MMKV, and multiple MMKV instances
-- **Live Event Monitoring**: Track all storage operations in real-time
-- **Edit & Delete**: Modify or remove storage items directly
-- **Add New Items**: Create new storage entries
-- **Required Key Validation**: Define and validate required storage keys
-- **Type Checking**: Validate storage value types
-- **Value Validation**: Check if values match expected patterns
-- **Search & Filter**: Search through keys and filter by status
-- **Copy Functionality**: Easily copy keys and values
-- **Beautiful UI**: Modern, game-themed interface matching other React Buoy tools
+![Storage Explorer demo](https://github.com/user-attachments/assets/80ef1c60-d20c-4d8b-97e6-f37b21b315ea)
 
-## Installation
-
-This package is part of the React Buoy monorepo and is automatically available to other packages and the example app.
-
-For external projects:
-
-```bash
-# Required: Core storage package and AsyncStorage
-npm install @buoy/storage @react-native-async-storage/async-storage
-
-# Optional: MMKV support (recommended for better performance)
-npm install react-native-mmkv
-```
-
-Or with pnpm/yarn:
+## Install
 
 ```bash
-# Required
-pnpm add @buoy/storage @react-native-async-storage/async-storage
-
-# Optional: MMKV support
-pnpm add react-native-mmkv
-```
-
-## Quick Start
-
-### Simplest Setup - Just 1 Line!
-
-**Import the preset and add it to your tools array. Done!**
-
-```typescript
-import { storageToolPreset } from '@buoy/storage';
-import { FloatingDevTools } from '@buoy/core';
-
-const installedApps = [
-  storageToolPreset, // That's it! One line.
-  // ...your other tools
-];
-
-function App() {
-  return (
-    <FloatingDevTools
-      apps={installedApps}
-      environment="local"
-      userRole="admin"
-    />
-  );
-}
-```
-
-**Done!** The preset automatically:
-- ✅ Browses all AsyncStorage keys
-- ✅ Monitors storage operations
-- ✅ Provides edit/delete/add functionality
-- ✅ No configuration required
-
-### Custom Configuration
-
-If you need to validate specific storage keys:
-
-```typescript
-import { createStorageTool } from '@buoy/storage';
-
-const requiredStorageKeys = [
-  {
-    key: "@app/session",
-    expectedType: "string",
-    description: "User session token",
-    storageType: "async",
-  },
-  {
-    key: "@app/settings:theme",
-    expectedValue: "dark",
-    description: "Preferred theme",
-    storageType: "async",
-  },
-];
-
-const myStorageTool = createStorageTool({
-  requiredStorageKeys,
-  colorPreset: "purple",
-  enableSharedModalDimensions: true,
-});
-
-const installedApps = [
-  myStorageTool,
-  // ...other tools
-];
+npm install @buoy-gg/core @buoy-gg/storage
 ```
 
-### Alternative: Manual Setup
-
-If you're not using FloatingDevTools or want more control:
+## Quick start
 
-```typescript
-import { StorageModalWithTabs } from '@buoy/storage';
+AsyncStorage works out of the box. Render the floating menu once — the Storage Explorer is auto-discovered as soon as this package is installed:
 
-const requiredStorageKeys = [
-  {
-    key: "@app/session",
-    expectedType: "string",
-    description: "User session token",
-    storageType: "async",
-  },
-];
-
-function App() {
-  const [showStorage, setShowStorage] = useState(false);
+```tsx
+import { FloatingDevTools } from "@buoy-gg/core";
 
+export default function App() {
   return (
     <>
-      <Button onPress={() => setShowStorage(true)}>
-        Open Storage Browser
-      </Button>
-
-      <StorageModalWithTabs
-        visible={showStorage}
-        onClose={() => setShowStorage(false)}
-        requiredStorageKeys={requiredStorageKeys}
-      />
+      {/* your app */}
+      <FloatingDevTools />
     </>
   );
 }
 ```
 
-## MMKV Support
-
-React Buoy Storage fully supports [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv), a fast, efficient storage solution for React Native.
-
-### Why MMKV?
-
-- **10x faster** than AsyncStorage
-- **Synchronous API** - no async/await needed
-- **Encryption support** - built-in AES encryption
-- **Multi-process support** - share data between extensions
-- **Small bundle size** - ~30KB
-
-### Setup Requirements
-
-**⚠️ IMPORTANT:** Manual registration is **required** for MMKV v4. Auto-detection is not possible due to Metro bundler and ES6 module limitations.
-
-You must call `registerMMKVInstance()` for each MMKV instance you want to monitor in the DevTools.
-
-### Basic MMKV Setup
-
-```typescript
-import { createMMKV } from 'react-native-mmkv';
-import { registerMMKVInstance } from '@buoy/storage';
-
-// 1. Create your MMKV instance
-export const storage = createMMKV({
-  id: 'mmkv.default'
-});
-
-// 2. Register it with DevTools (required!)
-registerMMKVInstance('mmkv.default', storage);
-```
-
-**That's it!** Your MMKV instance is now visible in the Storage DevTools.
-
-### Encrypted MMKV Setup
-
-```typescript
-import { createMMKV } from 'react-native-mmkv';
-import { registerMMKVInstance } from '@buoy/storage';
-
-// Create encrypted instance
-export const secureStorage = createMMKV({
-  id: 'secure-storage',
-  encryptionKey: 'my-encryption-key'
-});
-
-// Register with encrypted flag
-registerMMKVInstance('secure-storage', secureStorage, {
-  encrypted: true
-});
-```
-
-### Multiple MMKV Instances
-
-You can create and monitor multiple MMKV instances for different purposes:
-
-```typescript
-import { createMMKV } from 'react-native-mmkv';
-import { registerMMKVInstance } from '@buoy/storage';
-
-// User preferences
-export const userPrefs = createMMKV({ id: 'user-prefs' });
-registerMMKVInstance('user-prefs', userPrefs);
-
-// API cache
-export const apiCache = createMMKV({ id: 'api-cache' });
-registerMMKVInstance('api-cache', apiCache);
-
-// Secure auth storage
-export const authStorage = createMMKV({
-  id: 'auth',
-  encryptionKey: process.env.ENCRYPTION_KEY
-});
-registerMMKVInstance('auth', authStorage, { encrypted: true });
-```
-
-### MMKV with FloatingDevTools
-
-Once registered, MMKV instances automatically appear in the Storage Browser:
-
-```typescript
-import { FloatingDevTools } from '@buoy/core';
-import { storageToolPreset } from '@buoy/storage';
-import './mmkv-setup'; // Import your MMKV setup file
-
-function App() {
-  return (
-    <FloatingDevTools
-      apps={[storageToolPreset]}
-      environment="local"
-      userRole="admin"
-    />
-  );
-}
-```
-
-The Storage Browser will show:
-- All your MMKV instances (default, user-prefs, api-cache, auth, etc.)
-- All AsyncStorage keys
-- Real-time updates when data changes
-- Ability to edit, delete, and add keys
-
-### MMKV Registration API
-
-#### `registerMMKVInstance(id, instance, config?)`
-
-Register an MMKV instance with DevTools for monitoring and debugging.
-
-**Parameters:**
-- `id` (string) - Unique identifier for this instance (should match the `id` used in `createMMKV`)
-- `instance` (MMKV) - The MMKV instance returned from `createMMKV()`
-- `config` (optional) - Configuration object
-  - `encrypted` (boolean) - Set to `true` if instance uses encryption
-
-**Returns:** `void`
-
-**Example:**
-```typescript
-import { createMMKV } from 'react-native-mmkv';
-import { registerMMKVInstance } from '@buoy/storage';
-
-const storage = createMMKV({ id: 'my-storage' });
-registerMMKVInstance('my-storage', storage);
-```
-
-#### `unregisterMMKVInstance(id)`
-
-Unregister an MMKV instance from DevTools monitoring. Typically not needed unless you're dynamically creating/destroying instances.
-
-**Parameters:**
-- `id` (string) - The instance ID to unregister
-
-**Returns:** `void`
-
-**Example:**
-```typescript
-import { unregisterMMKVInstance } from '@buoy/storage';
-
-unregisterMMKVInstance('my-storage');
-```
-
-### Why Manual Registration?
-
-Auto-detection is fundamentally impossible for MMKV v4 due to:
-
-1. **ES6 Module Exports are Sealed** - Cannot monkey-patch `createMMKV` function
-2. **Metro Bundler Limitations** - No access to `require.cache` or module interception
-3. **Nitro Modules Architecture** - MMKV instances created in native C++ layer
-
-Manual registration is a simple one-line call per instance and provides explicit control over what's monitored.
-
-### MMKV Best Practices
-
-**Recommended structure:**
-
-```typescript
-// utils/storage.ts
-import { createMMKV } from 'react-native-mmkv';
-import { registerMMKVInstance } from '@buoy/storage';
-
-export const storage = createMMKV({ id: 'mmkv.default' });
-export const secureStorage = createMMKV({
-  id: 'secure',
-  encryptionKey: 'your-key'
-});
-
-if (__DEV__) {
-  registerMMKVInstance('mmkv.default', storage);
-  registerMMKVInstance('secure', secureStorage, { encrypted: true });
-}
-```
-
-Then import in your app:
-
-```typescript
-import { storage, secureStorage } from './utils/storage';
-
-// Use anywhere in your app
-storage.set('user.name', 'John Doe');
-secureStorage.set('auth.token', 'secret-token');
-```
-
-## API Reference
-
-### Presets
-
-#### `storageToolPreset`
-
-Pre-configured AsyncStorage browser tool ready to use with FloatingDevTools.
-
-**Example:**
-```typescript
-import { storageToolPreset } from '@buoy/storage';
-
-const installedApps = [storageToolPreset];
-```
-
-#### `createStorageTool(options?)`
-
-Create a custom AsyncStorage browser tool configuration.
-
-**Options:**
-```typescript
-{
-  /** Tool name (default: "STORAGE") */
-  name?: string;
-  /** Tool description */
-  description?: string;
-  /** Icon color preset (default: "green") */
-  colorPreset?: "orange" | "cyan" | "purple" | "pink" | "yellow" | "green";
-  /** Custom tool ID (default: "storage") */
-  id?: string;
-  /** Array of required storage keys to validate */
-  requiredStorageKeys?: RequiredStorageKey[];
-  /** Enable shared modal dimensions */
-  enableSharedModalDimensions?: boolean;
-}
-```
-
-**Example:**
-```typescript
-import { createStorageTool } from '@buoy/storage';
-
-const requiredStorageKeys = [
-  {
-    key: "@app/session",
-    expectedType: "string",
-    description: "User session token",
-    storageType: "async",
-  },
-];
-
-const myStorageTool = createStorageTool({
-  name: "APP STORAGE",
-  requiredStorageKeys,
-  colorPreset: "cyan",
-  enableSharedModalDimensions: true,
-});
-```
-
-### Components
-
-#### `StorageModalWithTabs`
-
-Main modal component with two tabs: Browser and Events.
-
-**Props:**
-```typescript
-interface StorageModalWithTabsProps {
-  /** Whether the modal is visible */
-  visible: boolean;
-  /** Callback when modal is closed */
-  onClose: () => void;
-  /** Optional back button handler */
-  onBack?: () => void;
-  /** Whether to use shared modal dimensions */
-  enableSharedModalDimensions?: boolean;
-  /** Array of required storage keys to validate */
-  requiredStorageKeys?: RequiredStorageKey[];
-}
-```
-
-**Example:**
-```typescript
-<StorageModalWithTabs
-  visible={isVisible}
-  onClose={handleClose}
-  requiredStorageKeys={requiredKeys}
-  enableSharedModalDimensions={true}
-/>
-```
-
-### Types
-
-#### `RequiredStorageKey`
-
-```typescript
-interface RequiredStorageKey {
-  /** Storage key to validate */
-  key: string;
-  /** Optional description of the key */
-  description?: string;
-  /** Expected value type */
-  expectedType?: "string" | "number" | "boolean" | "object" | "array";
-  /** Expected value */
-  expectedValue?: any;
-  /** Storage type: "async" for AsyncStorage, "mmkv" for MMKV, "secure" for Secure Storage */
-  storageType: "async" | "mmkv" | "secure";
-  /** Whether the key is required */
-  required?: boolean;
-}
-```
-
-#### `AsyncStorageEvent`
-
-```typescript
-interface AsyncStorageEvent {
-  /** Unique event ID */
-  id: string;
-  /** Event type (set, get, remove, clear, etc.) */
-  type: "set" | "get" | "remove" | "clear" | "multiGet" | "multiSet" | "multiRemove";
-  /** Storage key(s) involved */
-  key?: string | string[];
-  /** Value (for set operations) */
-  value?: any;
-  /** Timestamp of the event */
-  timestamp: number;
-  /** Whether the operation succeeded */
-  success: boolean;
-  /** Error message if operation failed */
-  error?: string;
-}
-```
-
-## Use Cases
-
-### Session Management
-
-Monitor and validate user session storage:
-
-```typescript
-import { createStorageTool } from '@buoy/storage';
-
-const requiredStorageKeys = [
-  {
-    key: "@app/session:token",
-    expectedType: "string",
-    description: "JWT auth token",
-    storageType: "async",
-    required: true,
-  },
-  {
-    key: "@app/session:userId",
-    expectedType: "string",
-    description: "Current user ID",
-    storageType: "async",
-    required: true,
-  },
-];
-
-const storageTool = createStorageTool({ requiredStorageKeys });
-```
-
-### App Settings
+**MMKV** — register each instance once so the explorer can see it (required for MMKV v4; Metro can't auto-detect instances):
 
-Validate app configuration storage:
+```ts
+import { createMMKV } from "react-native-mmkv";
+import { registerMMKVInstance } from "@buoy-gg/storage";
 
-```typescript
-const requiredStorageKeys = [
-  {
-    key: "@app/settings:theme",
-    expectedValue: "dark",
-    description: "UI theme preference",
-    storageType: "async",
-  },
-  {
-    key: "@app/settings:notifications",
-    expectedType: "boolean",
-    description: "Notifications enabled",
-    storageType: "async",
-  },
-  {
-    key: "@app/settings:language",
-    expectedType: "string",
-    description: "User language preference",
-    storageType: "async",
-  },
-];
+export const storage = createMMKV({ id: "mmkv.default" });
+registerMMKVInstance("mmkv.default", storage);
 ```
 
-### Cache Management
+**SecureStore** — the iOS Keychain / Android KeyStore has no key-listing API, so register the keys you want visible:
 
-Monitor cached data:
+```ts
+import * as SecureStore from "expo-secure-store";
+import { registerSecureStoreKeys } from "@buoy-gg/storage";
 
-```typescript
-const requiredStorageKeys = [
-  {
-    key: "@app/cache:userData",
-    expectedType: "object",
-    description: "Cached user profile data",
-    storageType: "async",
-  },
-  {
-    key: "@app/cache:timestamp",
-    expectedType: "number",
-    description: "Cache timestamp",
-    storageType: "async",
-  },
-];
+registerSecureStoreKeys(SecureStore, [
+  "auth.accessToken",
+  { key: "session", keychainService: "com.myapp.auth" },
+  // Biometric-protected keys are listed but never auto-read (no surprise Face ID prompts)
+  { key: "pin", requireAuthentication: true },
+]);
 ```
 
-## Features in Detail
+## What you get
 
-### Browser Tab
+- **Three backends, one explorer** — AsyncStorage, MMKV (multiple instances, including encrypted), and Expo SecureStore, with per-instance key counts and an instance switcher.
+- **Edit in place** — modify, delete, and add keys directly; bulk-select to delete or export many at once.
+- **Live events** — watch storage reads and writes stream in as your app runs.
+- **Pin and hide** — pin the keys you're watching to the top (persists across sessions); one tap hides noisy keys non-destructively.
+- **Inline previews** — short values show on the card (`number · 42`, `string · "en"`), booleans get color-coded true/false badges, and valid JSON is auto pretty-printed.
+- **Biometric keys stay safe** — SecureStore keys behind Face ID / fingerprint are listed but never auto-read.
+- **Required-key validation** — declare keys with expected types or values via `createStorageTool({ requiredStorageKeys })` and see what's missing or wrong.
 
-- **View All Keys**: See all AsyncStorage keys and their values
-- **Search**: Search through keys by name
-- **Filter**: Filter by validation status (all, missing, issues)
-- **Edit**: Modify existing values directly
-- **Delete**: Remove storage entries
-- **Add**: Create new storage entries
-- **Copy**: Copy keys and values to clipboard
-- **Validation**: See which required keys are missing or invalid
-
-### Events Tab
-
-- **Live Monitoring**: Watch all storage operations in real-time
-- **Event Types**: Track set, get, remove, clear, and multi-operations
-- **Filtering**: Filter events by type or key
-- **Search**: Search through event history
-- **Timeline**: See chronological order of operations
-- **Pause/Resume**: Control event capture
-- **Clear**: Clear event history
-
-### Validation
-
-Required storage keys can be validated for:
-- **Existence**: Check if the key exists
-- **Type**: Validate the value type (string, number, boolean, object, array)
-- **Value**: Check if the value matches an expected value
-- **Custom Validation**: Implement custom validation logic
-
-## Dependencies
-
-- `@buoy/shared-ui` - Common UI components and utilities
-- `@react-native-async-storage/async-storage` - AsyncStorage implementation (peer dependency; supports v2 and v3 — `^2.0.0 || ^3.1.0`. Avoid 3.0.x, which has an Android build issue fixed upstream in 3.1.0.)
-- `react-native-mmkv` - MMKV storage implementation (optional peer dependency)
-- React and React Native (peer dependencies)
-
-## Development
-
-### Building
-
-```bash
-pnpm build
-```
-
-### Type Checking
-
-```bash
-pnpm typecheck
-```
-
-### Clean Build
-
-```bash
-pnpm clean
-```
+## Desktop & AI
 
-## License
+The same live session streams to [Buoy Desktop](https://github.com/Buoy-gg/Buoy-Desktop) (free, macOS/Windows/Linux) and to Claude Code or Cursor via the [Buoy MCP server](https://buoy.gg/buoy/latest/docs/mcp).
 
-MIT
+## Free vs Pro
 
-## Contributing
+Every tool is free. [Pro](https://buoy.gg/pricing) unlocks production builds, the MCP server, and unlimited capture. Every weekend, Pro features unlock free for everyone.
 
-See the main repository [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines.
+---
 
-## Support
+📚 [Full docs](https://buoy.gg/buoy/latest/docs/tools/storage) · [All Buoy tools](https://github.com/Buoy-gg/buoy)
 
-For issues and feature requests, please visit the [GitHub repository](https://github.com/LovesWorking/react-native-buoy/issues).
+Proprietary software. © Buoy LLC. [Terms](https://buoy.gg/terms)

package/lib/commonjs/index.js

@@ -147,6 +147,12 @@ Object.defineProperty(exports, "registerMMKVInstance", {
     return _MMKVInstanceRegistry.registerMMKVInstance;
   }
 });
+Object.defineProperty(exports, "registerSecureStoreKeys", {
+  enumerable: true,
+  get: function () {
+    return _SecureStoreRegistry.registerSecureStoreKeys;
+  }
+});
 Object.defineProperty(exports, "storageEventStore", {
   enumerable: true,
   get: function () {
@@ -177,6 +183,12 @@ Object.defineProperty(exports, "unregisterMMKVInstance", {
     return _MMKVInstanceRegistry.unregisterMMKVInstance;
   }
 });
+Object.defineProperty(exports, "unregisterSecureStoreKey", {
+  enumerable: true,
+  get: function () {
+    return _SecureStoreRegistry.unregisterSecureStoreKey;
+  }
+});
 Object.defineProperty(exports, "useAsyncStorageKeys", {
   enumerable: true,
   get: function () {
@@ -240,5 +252,6 @@ var _mmkvAvailability = require("./storage/utils/mmkvAvailability");
 var _mmkvTypeDetection = require("./storage/utils/mmkvTypeDetection");
 var _storageTimeTravelUtils = require("./storage/utils/storageTimeTravelUtils");
 var _MMKVInstanceRegistry = require("./storage/utils/MMKVInstanceRegistry");
+var _SecureStoreRegistry = require("./storage/utils/SecureStoreRegistry");
 var _storageSyncAdapter = require("./storage/sync/storageSyncAdapter");
 var _storageEventStore = require("./storage/stores/storageEventStore");