npm package: @minkyumdev/zustand-mmkv-storage
Description: Fast MMKV storage adapter for Zustand persist middleware in React Native - 30x faster than AsyncStorage with encryption support
Author: minkyumdev
Latest version: 1.0.1

# @minkyumdev/zustand-mmkv-storage

MMKV storage adapter for Zustand persist middleware in React Native.

## Features

- **Blazing Fast**: MMKV is ~30x faster than AsyncStorage
- **Lazy Loading**: Dynamically imports MMKV only when needed
- **Instance Caching**: Reuses MMKV instances across calls
- **Encryption Support**: Built-in encryption for sensitive data
- **Direct Access**: Access underlying MMKV instance for debugging
- **TypeScript Support**: Fully typed
- **Zero Dependencies**: Only peer dependencies (Zustand, react-native-mmkv)

## Installation

```bash
npm install @minkyumdev/zustand-mmkv-storage

# Peer dependencies
npm install zustand react-native-mmkv
```

For iOS, run `cd ios && pod install` after installation.

## Usage

### Basic (Recommended)

```typescript
import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'
import { mmkvStorage } from '@minkyumdev/zustand-mmkv-storage'

const useStore = create(
  persist(
    (set) => ({
      count: 0,
      increment: () => set((state) => ({ count: state.count + 1 })),
    }),
    {
      name: 'my-store',
      storage: createJSONStorage(() => mmkvStorage),
    }
  )
)
```

### With Custom ID

Use different IDs to separate storage namespaces:

```typescript
import { createMMKVStorage } from '@minkyumdev/zustand-mmkv-storage'

// User store
storage: createJSONStorage(() => createMMKVStorage({ id: 'user-storage' }))

// Settings store
storage: createJSONStorage(() => createMMKVStorage({ id: 'settings-storage' }))
```

### With Encryption

For sensitive data like tokens:

```typescript
storage: createJSONStorage(() => createMMKVStorage({
  id: 'secure-storage',
  encryptionKey: 'your-secret-key',
}))
```

### Hydration Handling

Prevent flash of initial state on app startup:

```typescript
interface StoreState {
  user: User | null
  hasHydrated: boolean
}

const useStore = create<StoreState>()(
  persist(
    (set) => ({
      user: null,
      hasHydrated: false,
    }),
    {
      name: 'user-store',
      storage: createJSONStorage(() => mmkvStorage),
      onRehydrateStorage: () => (state) => {
        if (state) {
          state.hasHydrated = true
        }
      },
    }
  )
)

// In component
const { user, hasHydrated } = useStore()
if (!hasHydrated) return <Loading />
```

### Direct MMKV Access

Access the underlying MMKV instance for debugging or manual operations:

```typescript
import { getMMKVInstance } from '@minkyumdev/zustand-mmkv-storage'

const mmkv = getMMKVInstance('user-storage')

// Clear all data
mmkv.clearAll()

// Get all keys
const keys = mmkv.getAllKeys()
```

## API

### `mmkvStorage`

Pre-configured default storage instance. Use this for simple cases.

### `createMMKVStorage(options?)`

Creates a custom storage adapter.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `id` | `string` | `'default'` | MMKV instance ID |
| `encryptionKey` | `string` | - | Encryption key for secure storage |

### `getMMKVInstance(id?, encryptionKey?)`

Returns the MMKV instance for direct access. Instances are cached as singletons.

## Error Handling

If `react-native-mmkv` is not installed, a helpful error message with installation instructions will be thrown.

## License

MIT