react-native-nitro-storage 0.1.4 → 0.3.1

package/README.md

@@ -1,83 +1,77 @@
-# react-native-nitro-storage 🗄️
+# react-native-nitro-storage
 
-> **The fastest, most complete storage solution for React Native.** Replace Zustand, MMKV, AsyncStorage, and Expo Secure Store with one lightning-fast, type-safe library.
+The fastest, most complete storage solution for React Native.
+Synchronous Memory, Disk, and Secure storage in one unified API — powered by [Nitro Modules](https://github.com/mrousavy/nitro) and JSI.
 
-[![npm version](https://img.shields.io/npm/v/react-native-nitro-storage?style=flat-square)](https://www.npmjs.com/package/react-native-nitro-storage)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Nitro Modules](https://img.shields.io/badge/Powered%20by-Nitro%20Modules-blueviolet?style=flat-square)](https://nitro.margelo.com)
+## Highlights
 
-**react-native-nitro-storage** unifies **Memory** (global state), **Disk** (persistence), and **Secure** (keychain) storage into a single, blazing-fast C++ library built with [Nitro Modules](https://nitro.margelo.com). All operations are **100% synchronous** via JSI—no promises, no bridge, no lag.
+- **Three storage scopes** — in-memory, persistent disk, and hardware-encrypted secure storage
+- **Synchronous reads & writes** — no `async/await`, no bridge, zero serialization overhead for primitives
+- **React hooks** — `useStorage`, `useStorageSelector`, `useSetStorage` with automatic re-renders
+- **Type-safe** — full TypeScript generics, custom serializers, schema validation with fallback
+- **Namespaces** — isolate keys by feature, user, or tenant with automatic prefixing
+- **TTL expiration** — time-based auto-expiry with optional `onExpired` callback
+- **Biometric storage** — hardware-backed biometric protection on iOS & Android
+- **Auth storage factory** — `createSecureAuthStorage` for multi-token auth flows
+- **Batch operations** — atomic multi-key get/set/remove via native batch APIs
+- **Transactions** — grouped writes with automatic rollback on error
+- **Migrations** — versioned data migrations with `registerMigration` / `migrateToLatest`
+- **MMKV migration** — drop-in `migrateFromMMKV` for painless migration from MMKV
+- **Cross-platform** — iOS, Android, and web (`localStorage` fallback)
 
-<p align="center">
-  <img src="./readme/ios.png" alt="iOS Benchmark" height="640" />
-  <img src="./readme/android.png" alt="Android Benchmark" height="640" />
-</p>
+## Requirements
 
-<p align="center">
-  <em>Real-world performance: 1,000 operations in milliseconds</em>
-</p>
+| Dependency                   | Version     |
+| ---------------------------- | ----------- |
+| `react-native`               | `>= 0.75.0` |
+| `react-native-nitro-modules` | `>= 0.33.9` |
+| `react`                      | `>= 18.2.0` |
 
----
-
-## ⚡ Why Nitro Storage?
-
-### **One Library, Three Storage Types**
-
-Stop juggling multiple packages. Get memory state, disk persistence, and secure storage in one unified API.
-
-### **Truly Synchronous**
-
-Every operation—read, write, delete—executes instantly. No `await`, no `.then()`, no bridge overhead.
-
-### **Jotai-Style Atoms**
-
-Familiar, elegant API with `createStorageItem` and `useStorage`. Works inside and outside React components.
-
-### **Production-Ready**
-
-Thread-safe C++ core, comprehensive test coverage, and battle-tested on iOS, Android, and **Web**.
+## Installation
 
-### **Web Support**
-
-Fully functional on the web via `localStorage` and `sessionStorage`. All hooks and storage atoms are fully reactive across all platforms.
-
----
+```bash
+bun add react-native-nitro-storage react-native-nitro-modules
+```
 
-## 📦 Installation
+or:
 
 ```bash
 npm install react-native-nitro-storage react-native-nitro-modules
-# or
-yarn add react-native-nitro-storage react-native-nitro-modules
-# or
-bun add react-native-nitro-storage react-native-nitro-modules
 ```
 
-### For Expo Projects
+### Expo
 
 ```bash
-npx expo install react-native-nitro-storage react-native-nitro-modules
+bunx expo install react-native-nitro-storage react-native-nitro-modules
 ```
 
-Add the plugin to your `app.json` or `app.config.js`:
+Add the config plugin to `app.json`:
 
 ```json
 {
   "expo": {
-    "plugins": ["react-native-nitro-storage"]
+    "plugins": [
+      [
+        "react-native-nitro-storage",
+        {
+          "faceIDPermission": "Allow $(PRODUCT_NAME) to use Face ID for secure authentication",
+          "addBiometricPermissions": false
+        }
+      ]
+    ]
   }
 }
 ```
 
+> `faceIDPermission` sets `NSFaceIDUsageDescription` only when missing. Android biometric permissions are opt-in via `addBiometricPermissions: true`.
+
 Then run:
 
 ```bash
-npx expo prebuild
+bunx expo prebuild
 ```
 
-The config plugin automatically handles Android initialization. No manual setup required!
-
-### For Bare React Native Projects
+### Bare React Native
 
 **iOS:**
 
@@ -85,9 +79,7 @@ The config plugin automatically handles Android initialization. No manual setup
 cd ios && pod install
 ```
 
-**Android:**
-
-Add initialization to your `MainApplication.kt` (or `.java`):
+**Android** — initialize the native adapter in `MainApplication.kt`:
 
 ```kotlin
 import com.nitrostorage.AndroidStorageAdapter
@@ -102,433 +94,528 @@ class MainApplication : Application() {
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
 
-```typescript
-import {
-  createStorageItem,
-  useStorage,
-  StorageScope,
-} from "react-native-nitro-storage";
+```ts
+import { createStorageItem, StorageScope, useStorage } from "react-native-nitro-storage";
 
-// Create a storage atom
-const counterAtom = createStorageItem({
+// define a storage item outside of components
+const counterItem = createStorageItem({
   key: "counter",
   scope: StorageScope.Memory,
   defaultValue: 0,
 });
 
-// Use in React
-function Counter() {
-  const [count, setCount] = useStorage(counterAtom);
+export function Counter() {
+  const [count, setCount] = useStorage(counterItem);
 
   return (
-    <View>
-      <Text>{count}</Text>
-      <Button title="+" onPress={() => setCount(count + 1)} />
-    </View>
+    <Button
+      title={`Count: ${count}`}
+      onPress={() => setCount((prev) => prev + 1)}
+    />
   );
 }
-
-// Use outside React
-counterAtom.set(42);
-const value = counterAtom.get(); // 42, instantly
 ```
 
 ---
 
-## 💾 Storage Scopes
-
-### **Memory Storage**
-
-_Replaces: Zustand, Jotai, Redux_
-
-Fast, in-memory state. **Now Pure JS** - can store complex objects, functions, and React nodes!
-
-```typescript
-// Store a function
-const callbackAtom = createStorageItem({
-  key: "on-click",
-  scope: StorageScope.Memory,
-  defaultValue: () => console.log("Clicked!"),
-});
+## Storage Scopes
 
-// Store a React Component
-const modalAtom = createStorageItem({
-  key: "active-modal",
-  scope: StorageScope.Memory,
-  defaultValue: <View />,
-});
-```
+| Scope    | Backend (iOS)            | Backend (Android)          | Backend (Web)                                    | Persisted |
+| -------- | ------------------------ | -------------------------- | ------------------------------------------------ | --------- |
+| `Memory` | In-process JS Map        | In-process JS Map          | In-process JS Map                                | No        |
+| `Disk`   | UserDefaults (app suite) | SharedPreferences          | `localStorage`                                   | Yes       |
+| `Secure` | Keychain (AES-256 GCM)   | EncryptedSharedPreferences | `localStorage` (`__secure_` + `__bio_` prefixes) | Yes       |
 
-**Performance:** < 0.001ms per operation (Zero JSI overhead)
+```ts
+import { StorageScope } from "react-native-nitro-storage";
 
-### **Disk Storage**
-
-_Replaces: MMKV, AsyncStorage_
-
-Persisted to disk. Survives app restarts.
-
-```typescript
-const settingsAtom = createStorageItem({
-  key: "app-settings",
-  scope: StorageScope.Disk,
-  defaultValue: { theme: "dark", notifications: true },
-});
+StorageScope.Memory; // 0 — ephemeral, fastest
+StorageScope.Disk; // 1 — persistent, fast
+StorageScope.Secure; // 2 — encrypted, slightly slower
 ```
 
-**Performance:** ~1-2ms per operation  
-**Storage:** UserDefaults (iOS), SharedPreferences (Android)
+---
 
-### **Secure Storage**
+## API Reference
 
-_Replaces: Expo Secure Store, react-native-keychain_
+### `createStorageItem<T>(config)`
 
-Encrypted storage for sensitive data like auth tokens.
+The core factory. Creates a reactive storage item that can be used standalone or with hooks.
 
-```typescript
-const tokenAtom = createStorageItem<string | undefined>({
-  key: "auth-token",
-  scope: StorageScope.Secure,
-});
+```ts
+function createStorageItem<T = undefined>(
+  config: StorageItemConfig<T>,
+): StorageItem<T>;
 ```
 
-**Performance:** ~2-5ms per operation  
-**Encryption:** Keychain (iOS), EncryptedSharedPreferences with AES256-GCM (Android)
+**Config options:**
+
+| Property               | Type                             | Default        | Description                                                    |
+| ---------------------- | -------------------------------- | -------------- | -------------------------------------------------------------- |
+| `key`                  | `string`                         | _required_     | Storage key identifier                                         |
+| `scope`                | `StorageScope`                   | _required_     | Where to store the data                                        |
+| `defaultValue`         | `T`                              | `undefined`    | Value returned when no data exists                             |
+| `serialize`            | `(value: T) => string`           | JSON fast path | Custom serialization                                           |
+| `deserialize`          | `(value: string) => T`           | JSON fast path | Custom deserialization                                         |
+| `validate`             | `(value: unknown) => value is T` | —              | Type guard run on every read                                   |
+| `onValidationError`    | `(invalidValue: unknown) => T`   | —              | Recovery function when validation fails                        |
+| `expiration`           | `{ ttlMs: number }`              | —              | Time-to-live in milliseconds                                   |
+| `onExpired`            | `(key: string) => void`          | —              | Callback fired when a TTL value expires on read                |
+| `readCache`            | `boolean`                        | `false`        | Cache deserialized values in JS (avoids repeated native reads) |
+| `coalesceSecureWrites` | `boolean`                        | `false`        | Batch same-tick Secure writes per key                          |
+| `namespace`            | `string`                         | —              | Prefix key as `namespace:key` for isolation                    |
+| `biometric`            | `boolean`                        | `false`        | Require biometric auth (Secure scope only)                     |
+| `accessControl`        | `AccessControl`                  | —              | Keychain access control level (native only)                    |
+
+**Returned `StorageItem<T>`:**
+
+| Method / Property | Type                                     | Description                                        |
+| ----------------- | ---------------------------------------- | -------------------------------------------------- |
+| `get()`           | `() => T`                                | Read current value (synchronous)                   |
+| `set(value)`      | `(value: T \| ((prev: T) => T)) => void` | Write a value or updater function                  |
+| `delete()`        | `() => void`                             | Remove the stored value (resets to `defaultValue`) |
+| `has()`           | `() => boolean`                          | Check if a value exists in storage                 |
+| `subscribe(cb)`   | `(cb: () => void) => () => void`         | Listen for changes, returns unsubscribe            |
+| `serialize`       | `(v: T) => string`                       | The item's serializer                              |
+| `deserialize`     | `(v: string) => T`                       | The item's deserializer                            |
+| `scope`           | `StorageScope`                           | The item's scope                                   |
+| `key`             | `string`                                 | The resolved key (includes namespace prefix)       |
 
 ---
 
-## 🎯 Advanced Usage
+### React Hooks
 
-### TypeScript Best Practices
+#### `useStorage(item)`
 
-**Nullable Types:**
-Use explicit generics for nullable values. `defaultValue` is optional and defaults to `undefined`.
+Full reactive binding. Re-renders when the value changes.
 
-```typescript
-// ✅ Clean - explicit generic
-const userAtom = createStorageItem<User | null>({
-  key: "current-user",
-  scope: StorageScope.Memory,
-  defaultValue: null,
-});
-
-// ✅ Optional value - no defaultValue needed
-const tokenAtom = createStorageItem<string | undefined>({
-  key: "auth-token",
-  scope: StorageScope.Secure,
-});
-
-// ❌ Avoid - type assertion
-const userAtom = createStorageItem({
-  key: "current-user",
-  scope: StorageScope.Memory,
-  defaultValue: null as User | null, // Not necessary
-});
+```ts
+const [value, setValue] = useStorage(item);
 ```
 
-**Non-nullable Types:**
-For required values, just specify the default.
+#### `useStorageSelector(item, selector, isEqual?)`
 
-```typescript
-const counterAtom = createStorageItem({
-  key: "counter",
-  scope: StorageScope.Memory,
-  defaultValue: 0, // Type inferred as number
-});
+Subscribe to a derived slice. Only re-renders when the selected value changes.
+
+```ts
+const [theme, setSettings] = useStorageSelector(settingsItem, (s) => s.theme);
 ```
 
-### Custom Serialization
+#### `useSetStorage(item)`
 
-```typescript
-const dateAtom = createStorageItem({
-  key: "last-login",
-  scope: StorageScope.Disk,
-  defaultValue: new Date(),
-  serialize: (date) => date.toISOString(),
-  deserialize: (str) => new Date(str),
-});
+Write-only hook. Useful when a component needs to update a value but doesn't depend on it.
+
+```ts
+const setToken = useSetStorage(tokenItem);
+setToken("new-token");
 ```
 
-### Complex Objects
+---
 
-```typescript
-interface User {
-  id: string;
-  name: string;
-  preferences: {
-    theme: "light" | "dark";
-    language: string;
-  };
-}
+### `storage` — Global Utilities
 
-const userAtom = createStorageItem<User>({
-  key: "user",
-  scope: StorageScope.Disk,
-  defaultValue: {
-    id: "",
-    name: "",
-    preferences: { theme: "dark", language: "en" },
-  },
-});
-
-// TypeScript knows the exact shape
-const user = userAtom.get();
-console.log(user.preferences.theme); // ✅ Type-safe
+```ts
+import { storage, StorageScope } from "react-native-nitro-storage";
 ```
 
-### Direct Access (Outside React)
+| Method                                  | Description                                                                  |
+| --------------------------------------- | ---------------------------------------------------------------------------- |
+| `storage.clear(scope)`                  | Clear all keys in a scope (`Secure` also clears biometric entries)           |
+| `storage.clearAll()`                    | Clear Memory + Disk + Secure                                                 |
+| `storage.clearNamespace(ns, scope)`     | Remove only keys matching a namespace                                        |
+| `storage.clearBiometric()`              | Remove all biometric-prefixed keys                                           |
+| `storage.has(key, scope)`               | Check if a key exists                                                        |
+| `storage.getAllKeys(scope)`             | Get all key names                                                            |
+| `storage.getAll(scope)`                 | Get all key-value pairs as `Record<string, string>`                          |
+| `storage.size(scope)`                   | Number of stored keys                                                        |
+| `storage.setAccessControl(level)`       | Set default secure access control for subsequent secure writes (native only) |
+| `storage.setKeychainAccessGroup(group)` | Set keychain access group for app sharing (native only)                      |
+
+> `storage.getAll(StorageScope.Secure)` returns regular secure entries. Biometric-protected values are not included in this snapshot API.
+
+---
 
-Perfect for API interceptors, middleware, or anywhere you need storage without React.
+### `createSecureAuthStorage<K>(config, options?)`
 
-```typescript
-// In an API interceptor
-axios.interceptors.request.use((config) => {
-  const token = tokenAtom.get();
-  if (token) {
-    config.headers.Authorization = `Bearer ${token}`;
-  }
-  return config;
-});
+One-liner factory for authentication flows. Creates multiple `StorageItem<string>` entries in Secure scope.
 
-// In a Redux middleware
-const authMiddleware = (store) => (next) => (action) => {
-  if (action.type === "AUTH_SUCCESS") {
-    tokenAtom.set(action.payload.token);
-  }
-  return next(action);
-};
+```ts
+function createSecureAuthStorage<K extends string>(
+  config: SecureAuthStorageConfig<K>,
+  options?: { namespace?: string },
+): Record<K, StorageItem<string>>;
 ```
 
-### Manual Subscriptions
+- Default namespace: `"auth"`
+- Each key is a separate `StorageItem<string>` with `StorageScope.Secure`
+- Supports per-key TTL, biometric, and access control
 
-```typescript
-const unsubscribe = counterAtom.subscribe(() => {
-  console.log("Counter changed:", counterAtom.get());
-});
-
-// Clean up
-unsubscribe();
-```
+---
 
 ### Batch Operations
 
-Read or write multiple items at once. This is highly optimized on the native side for minimum overhead.
+Atomic multi-key operations. Uses native batch APIs for best performance.
 
-```typescript
+```ts
 import { getBatch, setBatch, removeBatch } from "react-native-nitro-storage";
 
-// Write multiple items
+// Read multiple items at once
+const [a, b, c] = getBatch([itemA, itemB, itemC], StorageScope.Disk);
+
+// Write multiple items atomically
 setBatch(
   [
-    { item: item1, value: "v1" },
-    { item: item2, value: "v2" },
+    { item: itemA, value: "hello" },
+    { item: itemB, value: "world" },
   ],
-  StorageScope.Disk
+  StorageScope.Disk,
 );
 
-// Read multiple items
-const [v1, v2] = getBatch([item1, item2], StorageScope.Disk);
-
 // Remove multiple items
-removeBatch([item1, item2], StorageScope.Disk);
+removeBatch([itemA, itemB], StorageScope.Disk);
 ```
 
-### Functional Updates
+> All items in a batch must share the same scope. Items with `validate` or `expiration` automatically use per-item paths to preserve semantics.
 
-Update state based on the previous value, just like `useState`.
+---
 
-```typescript
-// Increment counter
-counterAtom.set((prev) => prev + 1);
-```
+### Transactions
 
-### Optimized Writes
+Grouped writes with automatic rollback on error.
 
-Use `useSetStorage` to set values without subscribing to updates (avoids re-renders).
+```ts
+import { runTransaction, StorageScope } from "react-native-nitro-storage";
 
-```typescript
-import { useSetStorage } from "react-native-nitro-storage";
+runTransaction(StorageScope.Disk, (tx) => {
+  const balance = tx.getItem(balanceItem);
+  tx.setItem(balanceItem, balance - 50);
+  tx.setItem(logItem, `Deducted 50 at ${new Date().toISOString()}`);
 
-function IncrementButton() {
-  const setCount = useSetStorage(counterAtom);
-  return <Button onPress={() => setCount((c) => c + 1)} title="+" />;
-}
+  if (balance - 50 < 0) throw new Error("Insufficient funds");
+  // if this throws, both writes are rolled back
+});
 ```
 
-### Clearing Data
+**TransactionContext methods:**
 
-Clear entire storage scopes at once.
+| Method                 | Description                 |
+| ---------------------- | --------------------------- |
+| `getItem(item)`        | Read a StorageItem's value  |
+| `setItem(item, value)` | Write a StorageItem's value |
+| `removeItem(item)`     | Delete a StorageItem        |
+| `getRaw(key)`          | Read raw string by key      |
+| `setRaw(key, value)`   | Write raw string by key     |
+| `removeRaw(key)`       | Delete raw key              |
 
-```typescript
-import { storage } from "react-native-nitro-storage";
+---
 
-// Clear all storage (all scopes)
-storage.clearAll();
+### Migrations
 
-// Clear specific scope
-storage.clear(StorageScope.Memory);
-storage.clear(StorageScope.Disk);
-storage.clear(StorageScope.Secure);
-```
+Versioned, sequential data migrations.
 
-### Migration from MMKV
+```ts
+import {
+  registerMigration,
+  migrateToLatest,
+  StorageScope,
+} from "react-native-nitro-storage";
 
-Easily migrate data from `react-native-mmkv` to Nitro Storage.
+registerMigration(1, ({ setRaw }) => {
+  setRaw("onboarding-complete", "false");
+});
 
-```typescript
-import { migrateFromMMKV } from "react-native-nitro-storage/src/migration";
+registerMigration(2, ({ getRaw, setRaw, removeRaw }) => {
+  const raw = getRaw("legacy-key");
+  if (raw) {
+    setRaw("new-key", raw);
+    removeRaw("legacy-key");
+  }
+});
 
-// Migrate 'user-settings' and delete from MMKV
-migrateFromMMKV(mmkvInstance, settingsAtom, true);
+// apply all pending migrations (runs once per scope)
+migrateToLatest(StorageScope.Disk);
 ```
 
----
+- Versions must be positive integers, registered in any order, applied ascending
+- Version state is tracked per scope via `__nitro_storage_migration_version__`
+- Duplicate versions throw at registration time
 
-## 📊 Performance Benchmarks
+---
 
-All operations are **100% synchronous** via JSI—no promises, no bridge, no lag.
+### MMKV Migration
 
-**Performance Metrics (1,000 operations per storage type):**
+Drop-in helper for migrating from `react-native-mmkv`.
 
-| Storage Type | Write | Read  | Avg/op       |
-| ------------ | ----- | ----- | ------------ |
-| Memory       | 0.5ms | 0.3ms | **0.0008ms** |
-| Disk         | 45ms  | 38ms  | **0.083ms**  |
-| Secure       | 120ms | 95ms  | **0.215ms**  |
+```ts
+import { migrateFromMMKV } from "react-native-nitro-storage";
+import { MMKV } from "react-native-mmkv";
 
-Run the benchmark yourself:
+const mmkv = new MMKV();
 
-```bash
-cd apps/example
-npm run ios  # or npm run android
-# Navigate to the "Benchmark" tab
+const migrated = migrateFromMMKV(mmkv, myStorageItem, true);
+// true  → value found and copied, original deleted from MMKV
+// false → no matching key in MMKV
 ```
 
----
+- Read priority: `getString` → `getNumber` → `getBoolean`
+- Uses `item.set()` so validation still applies
+- Only deletes from MMKV when migration succeeds
 
-## 🎯 API Reference
+---
 
-### `createStorageItem<T>(config)`
+### Enums
 
-Creates a storage atom.
+#### `AccessControl`
 
-**Parameters:**
+Controls keychain item access requirements (iOS Keychain / Android Keystore). No-op on web.
 
-- `key: string` - Unique identifier
-- `scope: StorageScope` - Memory, Disk, or Secure
-- `defaultValue: T` - Default value
-- `serialize?: (value: T) => string` - Custom serializer (default: JSON.stringify)
-- `deserialize?: (value: string) => T` - Custom deserializer (default: JSON.parse)
+```ts
+enum AccessControl {
+  WhenUnlocked = 0,
+  AfterFirstUnlock = 1,
+  WhenPasscodeSetThisDeviceOnly = 2,
+  WhenUnlockedThisDeviceOnly = 3,
+  AfterFirstUnlockThisDeviceOnly = 4,
+}
+```
 
-**Returns:** `StorageItem<T>`
+#### `BiometricLevel`
 
-### `StorageItem<T>`
+```ts
+enum BiometricLevel {
+  None = 0,
+  BiometryOrPasscode = 1,
+  BiometryOnly = 2,
+}
+```
 
-**Methods:**
+---
 
-- `get(): T` - Get current value (synchronous)
-- `set(value: T | ((prev: T) => T)): void` - Set new value (synchronous)
-- `delete(): void` - Remove value (synchronous)
-- `subscribe(callback: () => void): () => void` - Subscribe to changes
+## Use Cases
 
-### `useStorage<T>(item: StorageItem<T>)`
+### Persisted User Preferences
 
-React hook using `useSyncExternalStore` for automatic re-renders.
+```ts
+interface UserPreferences {
+  theme: "light" | "dark" | "system";
+  language: string;
+  notifications: boolean;
+}
 
-**Returns:** `[value: T, setValue: (value: T | ((prev: T) => T)) => void]`
+const prefsItem = createStorageItem<UserPreferences>({
+  key: "prefs",
+  scope: StorageScope.Disk,
+  defaultValue: { theme: "system", language: "en", notifications: true },
+});
 
-### `useSetStorage<T>(item: StorageItem<T>)`
+// in a component — only re-renders when theme changes
+const [theme, setPrefs] = useStorageSelector(prefsItem, (p) => p.theme);
+```
 
-Returns the setter function only. Does not subscribe to updates.
+### Auth Token Management
 
-**Returns:** `(value: T | ((prev: T) => T)) => void`
+```ts
+const auth = createSecureAuthStorage(
+  {
+    accessToken: { ttlMs: 15 * 60_000, biometric: true },
+    refreshToken: { ttlMs: 7 * 24 * 60 * 60_000 },
+    idToken: {},
+  },
+  { namespace: "myapp-auth" },
+);
 
-### `storage` Object
+// after login
+auth.accessToken.set(response.accessToken);
+auth.refreshToken.set(response.refreshToken);
+auth.idToken.set(response.idToken);
+
+// check if token exists and hasn't expired
+if (auth.accessToken.has()) {
+  const token = auth.accessToken.get();
+  // use token
+} else {
+  // refresh or re-login
+}
 
-- `clearAll()`: Clears all storage across all scopes.
-- `clear(scope)`: Clears a specific storage scope.
+// logout
+storage.clearNamespace("myapp-auth", StorageScope.Secure);
+```
 
-### Batch Operations
+### Feature Flags with Validation
 
-- `getBatch(items, scope)`: Returns an array of values for the given items.
-- `setBatch(items, scope)`: Sets multiple values at once.
-- `removeBatch(items, scope)`: Removes multiple items at once.
+```ts
+interface FeatureFlags {
+  darkMode: boolean;
+  betaFeature: boolean;
+  maxUploadMb: number;
+}
 
----
+const flagsItem = createStorageItem<FeatureFlags>({
+  key: "feature-flags",
+  scope: StorageScope.Disk,
+  defaultValue: { darkMode: false, betaFeature: false, maxUploadMb: 10 },
+  validate: (v): v is FeatureFlags =>
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as any).darkMode === "boolean" &&
+    typeof (v as any).maxUploadMb === "number",
+  onValidationError: () => ({
+    darkMode: false,
+    betaFeature: false,
+    maxUploadMb: 10,
+  }),
+  expiration: { ttlMs: 60 * 60_000 }, // refresh from server every hour
+  onExpired: () => fetchAndStoreFlags(),
+});
+```
 
-## 🔐 Security
+### Multi-Tenant / Namespaced Storage
+
+```ts
+function createUserStorage(userId: string) {
+  return {
+    cart: createStorageItem<string[]>({
+      key: "cart",
+      scope: StorageScope.Disk,
+      defaultValue: [],
+      namespace: `user-${userId}`,
+    }),
+    draft: createStorageItem<string>({
+      key: "draft",
+      scope: StorageScope.Disk,
+      defaultValue: "",
+      namespace: `user-${userId}`,
+    }),
+  };
+}
 
-### iOS
+// clear all data for a specific user
+storage.clearNamespace("user-123", StorageScope.Disk);
+```
 
-- **Disk:** `UserDefaults.standard`
-- **Secure:** Keychain with `kSecAttrAccessibleWhenUnlocked`
+### OTP / Temporary Codes
 
-### Android
+```ts
+const otpItem = createStorageItem<string>({
+  key: "otp-code",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  expiration: { ttlMs: 5 * 60_000 }, // 5 minutes
+  onExpired: (key) => {
+    console.log(`${key} expired — prompt user to request a new code`);
+  },
+});
 
-- **Disk:** `SharedPreferences`
-- **Secure:** `EncryptedSharedPreferences` with AES256-GCM encryption
+// store the code
+otpItem.set("482917");
 
-All secure operations use platform-native encryption. No data is stored in plain text.
+// later — returns "" if expired
+const code = otpItem.get();
+```
 
----
+### Atomic Balance Transfer
 
-## 🧪 Testing
+```ts
+const fromBalance = createStorageItem({
+  key: "from",
+  scope: StorageScope.Disk,
+  defaultValue: 100,
+});
+const toBalance = createStorageItem({
+  key: "to",
+  scope: StorageScope.Disk,
+  defaultValue: 0,
+});
 
-Comprehensive test coverage for both TypeScript and C++:
+function transfer(amount: number) {
+  runTransaction(StorageScope.Disk, (tx) => {
+    const from = tx.getItem(fromBalance);
+    if (from < amount) throw new Error("Insufficient funds");
 
-```bash
-# TypeScript/Jest tests
-npm test
+    tx.setItem(fromBalance, from - amount);
+    tx.setItem(toBalance, tx.getItem(toBalance) + amount);
+  });
+}
+```
 
-# Type checking
-npm run typecheck
+### Custom Binary Codec
 
-# Build verification
-npm run build
+```ts
+const compactItem = createStorageItem<{ id: number; active: boolean }>({
+  key: "compact",
+  scope: StorageScope.Disk,
+  defaultValue: { id: 0, active: false },
+  serialize: (v) => `${v.id}|${v.active ? "1" : "0"}`,
+  deserialize: (v) => {
+    const [id, flag] = v.split("|");
+    return { id: Number(id), active: flag === "1" };
+  },
+});
 ```
 
-**Test Coverage:**
+### Migrating From MMKV
 
-- ✅ All storage scopes (Memory, Disk, Secure)
-- ✅ Custom serialization
-- ✅ Complex objects
-- ✅ Subscription/unsubscription
-- ✅ Memory leak prevention
-- ✅ Thread safety (C++)
+```ts
+import { MMKV } from "react-native-mmkv";
 
----
+const mmkv = new MMKV();
 
-## 🏗️ Architecture
+const usernameItem = createStorageItem({
+  key: "username",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+});
 
-Built on [Nitro Modules](https://nitro.margelo.com) for maximum performance:
+// run once at app startup
+migrateFromMMKV(mmkv, usernameItem, true); // true = delete from MMKV after
+```
+
+---
 
-- **C++ Core:** Thread-safe storage implementation with mutex protection
-- **JSI Bridge:** Zero-copy, synchronous JavaScript ↔ C++ communication
-- **Platform Adapters:** Native iOS (Objective-C++) and Android (Kotlin + JNI) implementations
-- **React Integration:** `useSyncExternalStore` for optimal React 18+ compatibility
+## Exported Types
+
+```ts
+import type {
+  Storage,
+  StorageItemConfig,
+  StorageItem,
+  StorageBatchSetItem,
+  Validator,
+  ExpirationConfig,
+  MigrationContext,
+  Migration,
+  TransactionContext,
+  MMKVLike,
+  SecureAuthStorageConfig,
+} from "react-native-nitro-storage";
+```
 
 ---
 
-## 🆚 Comparison
+## Dev Commands
 
-| Feature          | Nitro Storage | MMKV | AsyncStorage | Zustand | Expo Secure Store |
-| ---------------- | ------------- | ---- | ------------ | ------- | ----------------- |
-| Synchronous      | ✅            | ✅   | ❌           | ✅      | ❌                |
-| Memory State     | ✅            | ❌   | ❌           | ✅      | ❌                |
-| Disk Persistence | ✅            | ✅   | ✅           | ❌      | ❌                |
-| Secure Storage   | ✅            | ❌   | ❌           | ❌      | ✅                |
-| Type-Safe        | ✅            | ⚠️   | ⚠️           | ✅      | ⚠️                |
-| Unified API      | ✅            | ❌   | ❌           | ❌      | ❌                |
-| React Hooks      | ✅            | ❌   | ❌           | ✅      | ❌                |
-| Web Support      | ✅            | ❌   | ✅           | ✅      | ❌                |
+From repository root:
 
----
+```bash
+bun run test -- --filter=react-native-nitro-storage
+bun run typecheck -- --filter=react-native-nitro-storage
+bun run build -- --filter=react-native-nitro-storage
+```
 
-## 📄 License
+Inside `packages/react-native-nitro-storage`:
 
-MIT
+```bash
+bun run test            # run tests
+bun run test:coverage   # run tests with coverage
+bun run lint            # eslint (expo-magic rules)
+bun run format:check    # prettier check
+bun run typecheck       # tsc --noEmit
+bun run build           # tsup build
+bun run benchmark       # performance benchmarks
+```
 
----
+## License
 
-**Keywords:** react-native storage, react-native state management, react-native keychain, react-native secure storage, react-native mmkv alternative, react-native async storage, synchronous storage react native, jsi storage, nitro modules, react native persistence
+MIT