@buoy-gg/storage 6.0.0 → 7.0.0

package/README.md

@@ -1,651 +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 AsyncStorage, MMKV, and Expo SecureStore.
+**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, MMKV, and SecureStore keys and values
-- **MMKV Support**: Monitor and debug MMKV instances (including encrypted storage)
-- **SecureStore Support**: Browse and delete Expo SecureStore values (registered keys — see below)
-- **Multiple Storage Types**: Support for AsyncStorage, MMKV (multiple instances), and SecureStore
-- **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
-- **Pin & Hide**: Pin keys you're watching to the top (persisted); hide noisy keys into the filter store with one tap
-- **Inline Value Previews**: Short values and color-coded boolean badges visible without expanding cards
-- **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:
+## Install
 
 ```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:
-
-```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:
+**MMKV** — register each instance once so the explorer can see it (required for MMKV v4; Metro can't auto-detect instances):
 
-```typescript
-import { storage, secureStorage } from './utils/storage';
+```ts
+import { createMMKV } from "react-native-mmkv";
+import { registerMMKVInstance } from "@buoy-gg/storage";
 
-// Use anywhere in your app
-storage.set('user.name', 'John Doe');
-secureStorage.set('auth.token', 'secret-token');
+export const storage = createMMKV({ id: "mmkv.default" });
+registerMMKVInstance("mmkv.default", storage);
 ```
 
-## Expo SecureStore Support
+**SecureStore** — the iOS Keychain / Android KeyStore has no key-listing API, so register the keys you want visible:
 
-The Storage Explorer can browse and delete Expo SecureStore values (iOS Keychain / Android KeyStore).
-
-### Setup Requirements
-
-SecureStore has **no key-enumeration API** — there is no way to ask the Keychain "what's stored?". So, like MMKV instances, you register the keys you want visible. You pass the `expo-secure-store` module in, so this package has zero dependency on it (bare RN apps without Expo are unaffected).
-
-```typescript
-import * as SecureStore from 'expo-secure-store';
-import { registerSecureStoreKeys } from '@buoy/storage';
+```ts
+import * as SecureStore from "expo-secure-store";
+import { registerSecureStoreKeys } from "@buoy-gg/storage";
 
 registerSecureStoreKeys(SecureStore, [
-  // Bare key names
-  'auth.accessToken',
-  'auth.refreshToken',
-
-  // Keys written with options must register the SAME options,
-  // or the Keychain returns null on read
-  { key: 'session.deviceKey', keychainService: 'com.myapp.auth' },
-
-  // Biometric-protected keys are listed but NEVER auto-read,
-  // so DevTools won't trigger surprise Face ID / fingerprint prompts
-  { key: 'secure.pin', requireAuthentication: true },
+  "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 },
 ]);
 ```
 
-### `registerSecureStoreKeys(module, keys)`
-
-| Param | Type | Description |
-|---|---|---|
-| `module` | `SecureStoreLike` | The `expo-secure-store` module (`import * as SecureStore`) |
-| `keys` | `(string \| { key, keychainService?, requireAuthentication?, description? })[]` | Keys to expose, with the options they were written with |
-
-Registered keys that have no stored value show up as **Missing** — handy for spotting initialization bugs. Use `unregisterSecureStoreKey(key)` to remove one from the tool (the stored value is untouched).
-
-### Platform notes
-
-- iOS Keychain values **persist across app uninstalls** (same bundle ID); Android values don't.
-- Values are read with the exact options each key was registered with — a `keychainService` mismatch reads as missing.
-
-## 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
+## What you get
 
-#### `StorageModalWithTabs`
+- **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.
 
-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
-
-Validate app configuration 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",
-  },
-];
-```
-
-### Cache Management
-
-Monitor cached data:
-
-```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",
-  },
-];
-```
-
-## Features in Detail
-
-### Browser Tab
-
-- **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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@buoy-gg/storage",
-  "version": "6.0.0",
-  "description": "storage package",
+  "version": "7.0.0",
+  "description": "Browse & edit AsyncStorage, MMKV & SecureStore inside your React Native app, with change history. Part of Buoy devtools.",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "types": "lib/typescript/index.d.ts",
@@ -26,11 +26,11 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@buoy-gg/floating-tools-core": "6.0.0",
-    "@buoy-gg/shared-ui": "6.0.0"
+    "@buoy-gg/floating-tools-core": "7.0.0",
+    "@buoy-gg/shared-ui": "7.0.0"
   },
   "peerDependencies": {
-    "@buoy-gg/license": "6.0.0",
+    "@buoy-gg/license": "7.0.0",
     "@react-native-async-storage/async-storage": "^2.0.0 || ^3.1.0",
     "react": "*",
     "react-native": "*"
@@ -40,7 +40,7 @@
     "@types/react": "^19.1.0",
     "@types/react-native": "^0.73.0",
     "typescript": "~5.8.3",
-    "@buoy-gg/license": "6.0.0"
+    "@buoy-gg/license": "7.0.0"
   },
   "react-native-builder-bob": {
     "source": "src",
@@ -63,17 +63,28 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/LovesWorking/react-native-buoy.git",
+    "url": "https://github.com/Buoy-gg/buoy.git",
     "directory": "packages/storage"
   },
   "bugs": {
     "url": "https://github.com/LovesWorking/react-native-buoy/issues"
   },
-  "homepage": "https://github.com/LovesWorking/react-native-buoy/tree/main/packages/storage#readme",
+  "homepage": "https://buoy.gg/tools/storage",
   "publishConfig": {
     "access": "public",
     "tag": "latest"
   },
+  "keywords": [
+    "react-native",
+    "expo",
+    "devtools",
+    "debugging",
+    "react-native-devtools",
+    "flipper-alternative",
+    "async-storage",
+    "mmkv",
+    "storage-inspector"
+  ],
   "scripts": {
     "build": "bob build",
     "typecheck": "tsc --noEmit",