npm package: @natify/storage-mmkv
Description: The **High Performance Storage Adapter** for the Natify Framework. This package implements the `IAsyncStorage` interface using [react-native-mmkv](https://www.google.com/search?q=https://github.com/mamous/react-native-mmkv), which is roughly **30x faster*
Latest version: 1.0.2

# @natify/storage-mmkv

The **High Performance Storage Adapter** for the Natify Framework.
This package implements the `IAsyncStorage` interface using [react-native-mmkv](https://www.google.com/search?q=https://github.com/mamous/react-native-mmkv), which is roughly **30x faster** than the standard AsyncStorage

**Architectural Note:** Although MMKV is synchronous by nature, this adapter wraps operations in Promises to maintain interchangeability with other `IAsyncStorage` implementations (like Keychain or filesystem-based storage).

## Installation

Since this is an adapter, you must install both the package and its native driver (Peer Dependency) in your application.

### Using pnpm (Recommended)

**Bash**

```
pnpm add @natify/storage-mmkv react-native-mmkv
```

### Using yarn

**Bash**

```
yarn add @natify/storage-mmkv react-native-mmkv
```

### Native Linking (Required)

After installation, you must install the pods for iOS and rebuild your application since MMKV uses C++ JSI bindings.

**Bash**

```
cd ios && pod install && cd ..
# Rebuild the app
pnpm run android # or pnpm run ios
```

---

## Setup & Integration

Register this adapter in your `NatifyProvider` configuration at the root of your application (`App.tsx`).

**TypeScript**

```
import { NatifyProvider } from '@natify/core';
import { MMKVAdapter } from '@natify/storage-mmkv';
import { AxiosHttpAdapter } from '@natify/http-axios';

// 1. Instantiate the adapter
// Optional: You can pass an instance ID for data isolation
const fastStorage = new MMKVAdapter('user-preferences');

// 2. Register in the config container
const config = {
  // Register by specific name (recommended)
  'storage-fast': fastStorage,

  // Or register as the default 'storage' capability
  'storage': fastStorage,

  // ... other adapters
  'http': new AxiosHttpAdapter()
};

export default function App() {
  return (
    <NatifyProvider config={config}>
      <YourMainNavigator />
    </NatifyProvider>
  );
}
```

---

## Usage

Consume the storage anywhere in your components using the `useAdapter` hook. You don't need to import this package directly in your UI components, just use the Core interfaces.

### By Capability Name (Generic)

Get the first available adapter that handles `'storage'`.

**TypeScript**

```
import { useAdapter } from '@natify/core';
import { IAsyncStorage } from '@natify/core/interfaces';

const SettingsScreen = () => {
  // Returns the default storage adapter
  const storage = useAdapter<IAsyncStorage>('storage');

  const saveTheme = async () => {
    await storage.setItem('theme', 'dark');
  };
};
```

### By Instance Name (Specific)

If you registered it as `'storage-fast'` in the config.

**TypeScript**

```
import { useAdapter } from '@natify/core';
import { IAsyncStorage } from '@natify/core/interfaces';

const CacheManager = () => {
  // Explicitly request the fast storage (MMKV)
  const fastStorage = useAdapter<IAsyncStorage>('storage-fast');

  const clearCache = async () => {
    await fastStorage.clear();
  };
};
```

---

## API Reference

This adapter fully implements `IAsyncStorage`.

| **Method**   | **Signature**                                      | **Description**                                   |
| ------------ | -------------------------------------------------- | ------------------------------------------------- |
| `getItem`    | `getItem<T>(key: string): Promise<T \| null>`      | Retrieves a value. Auto-parses JSON if possible.  |
| `setItem`    | `setItem<T>(key: string, value: T): Promise<void>` | Saves a value. Auto-stringifies objects/arrays.   |
| `removeItem` | `removeItem(key: string): Promise<void>`           | Deletes a single key.                             |
| `clear`      | `clear(): Promise<void>`                           | **Warning:**Wipes all data in this MMKV instance. |

### Capability Tag

- **Property:** `capability`
- **Value:** `'storage'`

---

## Troubleshooting

#### `Error: MMKV JSI bindings are not installed`

This means the native C++ code isn't linked.

1. Ensure you installed `react-native-mmkv` in your **App's** `package.json`.
2. Run `cd ios && pod install`.
3. Kill the Metro Bundler and restart with cache reset: `pnpm start --reset-cache`.
4. Rebuild the app binary (`pnpm run ios` / `pnpm run android`).

#### `Unable to resolve module react-native-mmkv`

If using a Monorepo, ensure `react-native-mmkv` is hoisted or installed in the app's dependencies, not just inside the adapter.