react-native-nitro-storage 0.3.0 → 0.3.2

package/README.md

@@ -1,12 +1,49 @@
 # react-native-nitro-storage
 
-Synchronous storage for React Native with a unified API for memory, disk, and secure data.
+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.
+
+## Highlights
+
+- **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)
+
+## Feature Coverage
+
+Every feature in this package is documented with at least one runnable example in this README:
+
+- Core item API (`createStorageItem`, `get/set/delete/has/subscribe`) — see Quick Start and Low-level subscription use case
+- Hooks (`useStorage`, `useStorageSelector`, `useSetStorage`) — see Quick Start and Persisted User Preferences
+- Scopes (`Memory`, `Disk`, `Secure`) — see Storage Scopes and multiple use cases
+- Namespaces — see Multi-Tenant / Namespaced Storage
+- TTL expiration + callbacks — see OTP / Temporary Codes
+- Validation + recovery — see Feature Flags with Validation
+- Biometric + access control — see Biometric-protected Secrets
+- Global storage utilities (`clear*`, `has`, `getAll*`, `size`, secure write settings) — see Global utility examples and Storage Snapshots and Cleanup
+- Batch APIs (`getBatch`, `setBatch`, `removeBatch`) — see Batch Operations and Bulk Bootstrap with Batch APIs
+- Transactions — see Transactions and Atomic Balance Transfer
+- Migrations (`registerMigration`, `migrateToLatest`) — see Migrations
+- MMKV migration (`migrateFromMMKV`) — see MMKV Migration and Migrating From MMKV
+- Auth storage factory (`createSecureAuthStorage`) — see Auth Token Management
 
 ## Requirements
 
-- `react-native >= 0.75.0`
-- `react-native-nitro-modules >= 0.33.9`
-- `react >= 18.2.0`
+| Dependency                   | Version     |
+| ---------------------------- | ----------- |
+| `react-native`               | `>= 0.75.0` |
+| `react-native-nitro-modules` | `>= 0.33.9` |
+| `react`                      | `>= 18.2.0` |
 
 ## Installation
 
@@ -14,13 +51,19 @@ Synchronous storage for React Native with a unified API for memory, disk, and se
 bun add react-native-nitro-storage react-native-nitro-modules
 ```
 
+or:
+
+```bash
+npm install react-native-nitro-storage react-native-nitro-modules
+```
+
 ### Expo
 
 ```bash
 bunx expo install react-native-nitro-storage react-native-nitro-modules
 ```
 
-`app.json`:
+Add the config plugin to `app.json`:
 
 ```json
 {
@@ -38,12 +81,9 @@ bunx expo install react-native-nitro-storage react-native-nitro-modules
 }
 ```
 
-Notes:
-
-- If `faceIDPermission` is omitted, the plugin sets a default only when `NSFaceIDUsageDescription` is missing.
-- Android biometric permissions are opt-in via `addBiometricPermissions: true`.
+> `faceIDPermission` sets `NSFaceIDUsageDescription` only when missing. Android biometric permissions are opt-in via `addBiometricPermissions: true`.
 
-Then:
+Then run:
 
 ```bash
 bunx expo prebuild
@@ -51,13 +91,13 @@ bunx expo prebuild
 
 ### Bare React Native
 
-iOS:
+**iOS:**
 
 ```bash
 cd ios && pod install
 ```
 
-Android (`MainApplication.kt`):
+**Android** — initialize the native adapter in `MainApplication.kt`:
 
 ```kotlin
 import com.nitrostorage.AndroidStorageAdapter
@@ -70,11 +110,14 @@ class MainApplication : Application() {
 }
 ```
 
+---
+
 ## Quick Start
 
 ```ts
 import { createStorageItem, StorageScope, useStorage } from "react-native-nitro-storage";
 
+// define a storage item outside of components
 const counterItem = createStorageItem({
   key: "counter",
   scope: StorageScope.Memory,
@@ -93,369 +136,673 @@ export function Counter() {
 }
 ```
 
-## What Is Exported
-
-- `StorageScope`
-- `storage`
-- `createStorageItem`
-- `useStorage`
-- `useStorageSelector`
-- `useSetStorage`
-- `getBatch`
-- `setBatch`
-- `removeBatch`
-- `registerMigration`
-- `migrateToLatest`
-- `runTransaction`
-- `migrateFromMMKV`
-
-Exported types:
-
-- `Storage`
-- `StorageItemConfig<T>`
-- `StorageItem<T>`
-- `StorageBatchSetItem<T>`
-- `Validator<T>`
-- `ExpirationConfig`
-- `MigrationContext`
-- `Migration`
-- `TransactionContext`
-- `MMKVLike`
+---
+
+## Storage Scopes
+
+| 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       |
+
+```ts
+import { StorageScope } from "react-native-nitro-storage";
+
+StorageScope.Memory; // 0 — ephemeral, fastest
+StorageScope.Disk; // 1 — persistent, fast
+StorageScope.Secure; // 2 — encrypted, slightly slower
+```
+
+---
 
 ## API Reference
 
-### `StorageScope`
+### `createStorageItem<T>(config)`
+
+The core factory. Creates a reactive storage item that can be used standalone or with hooks.
 
 ```ts
-enum StorageScope {
-  Memory = 0,
-  Disk = 1,
-  Secure = 2,
-}
+function createStorageItem<T = undefined>(
+  config: StorageItemConfig<T>,
+): StorageItem<T>;
 ```
 
-### `Storage` (low-level native/web adapter type)
+**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)       |
+
+**Non-React subscription example:**
 
 ```ts
-type Storage = {
-  set(key: string, value: string, scope: number): void;
-  get(key: string, scope: number): string | undefined;
-  remove(key: string, scope: number): void;
-  clear(scope: number): void;
-  setBatch(keys: string[], values: string[], scope: number): void;
-  getBatch(keys: string[], scope: number): (string | undefined)[];
-  removeBatch(keys: string[], scope: number): void;
-  addOnChange(
-    scope: number,
-    callback: (key: string, value: string | undefined) => void
-  ): () => void;
-};
+const unsubscribe = sessionItem.subscribe(() => {
+  console.log("session changed:", sessionItem.get());
+});
+
+sessionItem.set("next-session");
+unsubscribe();
 ```
 
-Notes:
+---
+
+### React Hooks
 
-- Exported for typing/integration use cases.
-- Most app code should use `createStorageItem` + hooks instead of this low-level API.
+#### `useStorage(item)`
 
-### `StorageItemConfig<T>`
+Full reactive binding. Re-renders when the value changes.
 
 ```ts
-type StorageItemConfig<T> = {
-  key: string;
-  scope: StorageScope;
-  defaultValue?: T;
-  serialize?: (value: T) => string;
-  deserialize?: (value: string) => T;
-  validate?: Validator<T>;
-  onValidationError?: (invalidValue: unknown) => T;
-  expiration?: ExpirationConfig;
-  readCache?: boolean;
-  coalesceSecureWrites?: boolean;
-};
+const [value, setValue] = useStorage(item);
 ```
 
-### `StorageItem<T>`
+#### `useStorageSelector(item, selector, isEqual?)`
+
+Subscribe to a derived slice. Only re-renders when the selected value changes.
 
 ```ts
-type StorageItem<T> = {
-  get: () => T;
-  set: (value: T | ((prev: T) => T)) => void;
-  delete: () => void;
-  subscribe: (callback: () => void) => () => void;
-  serialize: (value: T) => string;
-  deserialize: (value: string) => T;
-  _triggerListeners: () => void;
-  scope: StorageScope;
-  key: string;
-};
+const [theme, setSettings] = useStorageSelector(settingsItem, (s) => s.theme);
 ```
 
-### `createStorageItem<T>(config)`
+#### `useSetStorage(item)`
+
+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");
+```
+
+---
+
+### `storage` — Global Utilities
 
 ```ts
-function createStorageItem<T = undefined>(config: StorageItemConfig<T>): StorageItem<T>
+import { storage, StorageScope } from "react-native-nitro-storage";
 ```
 
-Notes:
+| 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.setSecureWritesAsync(enabled)` | Toggle async secure writes on Android (`false` by default)                   |
+| `storage.flushSecureWrites()`           | Force flush of queued secure writes when coalescing is enabled               |
+| `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.
+
+#### Global utility examples
 
-- `Memory` stores values directly.
-- `Disk` and `Secure` store serialized values.
-- Default serialization uses a primitive fast path for strings/numbers/booleans/null/undefined and JSON for objects/arrays.
-- If `expiration` is enabled, values are wrapped internally and expired lazily on read.
-- `readCache` is opt-in for `Disk`/`Secure` and can be enabled per item.
-- `coalesceSecureWrites` is opt-in and batches same-tick secure writes per key.
-- If `validate` fails on a stored value, fallback is:
-1. `onValidationError(invalidValue)` if provided
-2. `defaultValue` otherwise
-- Fallback values are written back only when the source was stored data and the resolved fallback also passes `validate`.
+```ts
+import { AccessControl, storage, StorageScope } from "react-native-nitro-storage";
+
+storage.has("session", StorageScope.Disk);
+storage.getAllKeys(StorageScope.Disk);
+storage.getAll(StorageScope.Disk);
+storage.size(StorageScope.Disk);
+
+storage.clearNamespace("user-42", StorageScope.Disk);
+storage.clearBiometric();
+
+storage.setAccessControl(AccessControl.WhenUnlockedThisDeviceOnly);
+storage.setKeychainAccessGroup("group.com.example.shared");
+
+storage.clear(StorageScope.Memory);
+storage.clearAll();
+```
 
-Throws:
+#### Android secure write mode
 
-- `Error("expiration.ttlMs must be greater than 0.")` when `expiration.ttlMs <= 0`.
+`storage.setSecureWritesAsync(true)` switches secure writes from synchronous `commit()` to asynchronous `apply()` on Android.  
+Use this for non-critical secure writes when lower latency matters more than immediate durability.
 
-### `useStorage(item)`
+Call `storage.flushSecureWrites()` when you need deterministic persistence boundaries (for example before namespace clears, process handoff, or strict test assertions).
 
 ```ts
-function useStorage<T>(
-  item: StorageItem<T>
-): [T, (value: T | ((prev: T) => T)) => void]
+import { storage } from "react-native-nitro-storage";
+
+storage.setSecureWritesAsync(true);
+
+// ...multiple secure writes happen (including coalesced item writes)
+
+storage.flushSecureWrites(); // deterministic durability boundary
 ```
 
-### `useStorageSelector(item, selector, isEqual?)`
+---
+
+### `createSecureAuthStorage<K>(config, options?)`
+
+One-liner factory for authentication flows. Creates multiple `StorageItem<string>` entries in Secure scope.
 
 ```ts
-function useStorageSelector<T, TSelected>(
-  item: StorageItem<T>,
-  selector: (value: T) => TSelected,
-  isEqual?: (prev: TSelected, next: TSelected) => boolean
-): [TSelected, (value: T | ((prev: T) => T)) => void]
+function createSecureAuthStorage<K extends string>(
+  config: SecureAuthStorageConfig<K>,
+  options?: { namespace?: string },
+): Record<K, StorageItem<string>>;
 ```
 
-Use this to subscribe to a derived slice of a storage value and avoid rerenders when that slice does not change.
+- Default namespace: `"auth"`
+- Each key is a separate `StorageItem<string>` with `StorageScope.Secure`
+- Supports per-key TTL, biometric, and access control
+
+---
 
-### `useSetStorage(item)`
+### Batch Operations
+
+Atomic multi-key operations. Uses native batch APIs for best performance.
 
 ```ts
-function useSetStorage<T>(
-  item: StorageItem<T>
-): (value: T | ((prev: T) => T)) => void
+import { getBatch, setBatch, removeBatch } from "react-native-nitro-storage";
+
+// Read multiple items at once
+const [a, b, c] = getBatch([itemA, itemB, itemC], StorageScope.Disk);
+
+// Write multiple items atomically
+setBatch(
+  [
+    { item: itemA, value: "hello" },
+    { item: itemB, value: "world" },
+  ],
+  StorageScope.Disk,
+);
+
+// Remove multiple items
+removeBatch([itemA, itemB], StorageScope.Disk);
 ```
 
-### `storage`
+> All items in a batch must share the same scope. Items with `validate` or `expiration` automatically use per-item paths to preserve semantics.
+
+---
+
+### Transactions
+
+Grouped writes with automatic rollback on error.
 
 ```ts
-const storage: {
-  clear: (scope: StorageScope) => void;
-  clearAll: () => void;
-};
+import { runTransaction, StorageScope } 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()}`);
+
+  if (balance - 50 < 0) throw new Error("Insufficient funds");
+  // if this throws, both writes are rolled back
+});
 ```
 
-Behavior:
+**TransactionContext methods:**
 
-- `clear(scope)` clears all keys in a single scope.
-- `clearAll()` clears `Memory`, `Disk`, and `Secure`.
+| 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              |
 
-### Batch Operations
+---
+
+### Migrations
+
+Versioned, sequential data migrations.
 
 ```ts
-type StorageBatchSetItem<T> = {
-  item: StorageItem<T>;
-  value: T;
-};
+import {
+  registerMigration,
+  migrateToLatest,
+  StorageScope,
+} from "react-native-nitro-storage";
 
-function getBatch(
-  items: readonly Pick<StorageItem<unknown>, "key" | "scope" | "get" | "deserialize">[],
-  scope: StorageScope
-): unknown[];
+registerMigration(1, ({ setRaw }) => {
+  setRaw("onboarding-complete", "false");
+});
 
-function setBatch<T>(
-  items: readonly StorageBatchSetItem<T>[],
-  scope: StorageScope
-): void;
+registerMigration(2, ({ getRaw, setRaw, removeRaw }) => {
+  const raw = getRaw("legacy-key");
+  if (raw) {
+    setRaw("new-key", raw);
+    removeRaw("legacy-key");
+  }
+});
 
-function removeBatch(
-  items: readonly Pick<StorageItem<unknown>, "key" | "scope" | "delete">[],
-  scope: StorageScope
-): void;
+// apply all pending migrations (runs once per scope)
+migrateToLatest(StorageScope.Disk);
 ```
 
-Rules:
+- 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
 
-- All items must match the batch `scope`.
-- Items using `validate` or `expiration` automatically run via per-item `get()`/`set()` paths to preserve validation and TTL behavior.
-- Mixed-scope calls throw:
-  - `Batch scope mismatch for "<key>": expected <Scope>, received <Scope>.`
+---
 
-### Migrations
+### MMKV Migration
+
+Drop-in helper for migrating from `react-native-mmkv`.
 
 ```ts
-type MigrationContext = {
-  scope: StorageScope;
-  getRaw: (key: string) => string | undefined;
-  setRaw: (key: string, value: string) => void;
-  removeRaw: (key: string) => void;
-};
+import { migrateFromMMKV } from "react-native-nitro-storage";
+import { MMKV } from "react-native-mmkv";
 
-type Migration = (context: MigrationContext) => void;
+const mmkv = new MMKV();
 
-function registerMigration(version: number, migration: Migration): void;
-function migrateToLatest(scope?: StorageScope): number;
+const migrated = migrateFromMMKV(mmkv, myStorageItem, true);
+// true  → value found and copied, original deleted from MMKV
+// false → no matching key in MMKV
 ```
 
-Behavior:
+- Read priority: `getString` → `getNumber` → `getBoolean`
+- Uses `item.set()` so validation still applies
+- Only deletes from MMKV when migration succeeds
 
-- Versions must be positive integers.
-- Duplicate versions throw.
-- Migration version is tracked per scope using key `__nitro_storage_migration_version__`.
-- `migrateToLatest` applies pending migrations in ascending version order and returns applied/latest version.
+---
 
-Throws:
+### Enums
 
-- `registerMigration`: throws when version is not a positive integer.
-- `registerMigration`: throws when version is already registered.
-- `migrateToLatest`: throws on invalid scope.
+#### `AccessControl`
 
-### Transactions
+Controls keychain item access requirements (iOS Keychain / Android Keystore). No-op on web.
 
 ```ts
-type TransactionContext = {
-  scope: StorageScope;
-  getRaw: (key: string) => string | undefined;
-  setRaw: (key: string, value: string) => void;
-  removeRaw: (key: string) => void;
-  getItem: <T>(item: Pick<StorageItem<T>, "scope" | "key" | "get">) => T;
-  setItem: <T>(item: Pick<StorageItem<T>, "scope" | "key" | "set">, value: T) => void;
-  removeItem: (item: Pick<StorageItem<unknown>, "scope" | "key" | "delete">) => void;
-};
+enum AccessControl {
+  WhenUnlocked = 0,
+  AfterFirstUnlock = 1,
+  WhenPasscodeSetThisDeviceOnly = 2,
+  WhenUnlockedThisDeviceOnly = 3,
+  AfterFirstUnlockThisDeviceOnly = 4,
+}
+```
+
+#### `BiometricLevel`
 
-function runTransaction<T>(
-  scope: StorageScope,
-  transaction: (context: TransactionContext) => T
-): T;
+```ts
+enum BiometricLevel {
+  None = 0,
+  BiometryOrPasscode = 1,
+  BiometryOnly = 2,
+}
 ```
 
-Behavior:
+---
 
-- On exception, it rolls back keys modified in that transaction.
-- Rollback is best-effort within process lifetime.
-- `setItem`/`removeItem` prefer item methods when available, so validation/TTL/cache semantics stay consistent.
+## Use Cases
 
-Throws:
+### Persisted User Preferences
 
-- Throws on invalid scope.
-- Rethrows any error thrown by the transaction callback after rollback.
+```ts
+type UserPreferences = {
+  theme: "light" | "dark" | "system";
+  language: string;
+  notifications: boolean;
+};
 
-### Validation and Expiration Types
+const prefsItem = createStorageItem<UserPreferences>({
+  key: "prefs",
+  scope: StorageScope.Disk,
+  defaultValue: { theme: "system", language: "en", notifications: true },
+});
+
+// in a component — only re-renders when theme changes
+const [theme, setPrefs] = useStorageSelector(prefsItem, (p) => p.theme);
+```
+
+### Auth Token Management
 
 ```ts
-type Validator<T> = (value: unknown) => value is T;
+const auth = createSecureAuthStorage(
+  {
+    accessToken: { ttlMs: 15 * 60_000, biometric: true },
+    refreshToken: { ttlMs: 7 * 24 * 60 * 60_000 },
+    idToken: {},
+  },
+  { namespace: "myapp-auth" },
+);
+
+// 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
+}
 
-type ExpirationConfig = {
-  ttlMs: number;
-};
+// logout
+storage.clearNamespace("myapp-auth", StorageScope.Secure);
 ```
 
-### MMKV Migration
+### Feature Flags with Validation
 
 ```ts
-type MMKVLike = {
-  getString: (key: string) => string | undefined;
-  getNumber: (key: string) => number | undefined;
-  getBoolean: (key: string) => boolean | undefined;
-  contains: (key: string) => boolean;
-  delete: (key: string) => void;
-  getAllKeys: () => string[];
+type FeatureFlags = {
+  darkMode: boolean;
+  betaFeature: boolean;
+  maxUploadMb: number;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isFeatureFlags = (value: unknown): value is FeatureFlags => {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.darkMode === "boolean" &&
+    typeof value.betaFeature === "boolean" &&
+    typeof value.maxUploadMb === "number"
+  );
 };
 
-function migrateFromMMKV<T>(
-  mmkv: MMKVLike,
-  item: StorageItem<T>,
-  deleteFromMMKV?: boolean
-): boolean;
+const flagsItem = createStorageItem<FeatureFlags>({
+  key: "feature-flags",
+  scope: StorageScope.Disk,
+  defaultValue: { darkMode: false, betaFeature: false, maxUploadMb: 10 },
+  validate: isFeatureFlags,
+  onValidationError: () => ({
+    darkMode: false,
+    betaFeature: false,
+    maxUploadMb: 10,
+  }),
+  expiration: { ttlMs: 60 * 60_000 }, // refresh from server every hour
+  onExpired: () => fetchAndStoreFlags(),
+});
+```
+
+### Biometric-protected Secrets
+
+```ts
+import { AccessControl, createStorageItem, StorageScope } from "react-native-nitro-storage";
+
+const paymentPin = createStorageItem<string>({
+  key: "payment-pin",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  biometric: true,
+  accessControl: AccessControl.WhenPasscodeSetThisDeviceOnly,
+});
+
+paymentPin.set("4829");
+const pin = paymentPin.get();
+paymentPin.delete();
 ```
 
-Behavior:
+### 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}`,
+    }),
+  };
+}
+
+// clear all data for a specific user
+storage.clearNamespace("user-123", StorageScope.Disk);
+```
+
+### OTP / Temporary Codes
+
+```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`);
+  },
+});
+
+// store the code
+otpItem.set("482917");
+
+// later — returns "" if expired
+const code = otpItem.get();
+```
+
+### Bulk Bootstrap with Batch APIs
+
+```ts
+import {
+  createStorageItem,
+  getBatch,
+  removeBatch,
+  setBatch,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+const firstName = createStorageItem({
+  key: "first-name",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+});
+const lastName = createStorageItem({
+  key: "last-name",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+});
 
-- Returns `true` when a value is found and copied, `false` otherwise.
-- Read priority is: `getString` -> `getNumber` -> `getBoolean`.
-- Uses `item.set(...)`, so schema validation on the target item still applies.
-- If `deleteFromMMKV` is `true`, deletes only when migration succeeds.
+setBatch(
+  [
+    { item: firstName, value: "Ada" },
+    { item: lastName, value: "Lovelace" },
+  ],
+  StorageScope.Disk,
+);
 
-## Examples
+const [first, last] = getBatch([firstName, lastName], StorageScope.Disk);
+removeBatch([firstName, lastName], StorageScope.Disk);
+```
 
-### Schema Validation + Fallback
+### Atomic Balance Transfer
 
 ```ts
-const userIdItem = createStorageItem<number>({
-  key: "user-id",
+const fromBalance = createStorageItem({
+  key: "from",
+  scope: StorageScope.Disk,
+  defaultValue: 100,
+});
+const toBalance = createStorageItem({
+  key: "to",
   scope: StorageScope.Disk,
   defaultValue: 0,
-  validate: (v): v is number => typeof v === "number" && v > 0,
-  onValidationError: () => 1,
 });
+
+function transfer(amount: number) {
+  runTransaction(StorageScope.Disk, (tx) => {
+    const from = tx.getItem(fromBalance);
+    if (from < amount) throw new Error("Insufficient funds");
+
+    tx.setItem(fromBalance, from - amount);
+    tx.setItem(toBalance, tx.getItem(toBalance) + amount);
+  });
+}
 ```
 
-### TTL
+### Custom Binary Codec
 
 ```ts
-const otpItem = createStorageItem<string | undefined>({
-  key: "otp",
-  scope: StorageScope.Secure,
-  expiration: { ttlMs: 60_000 },
+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" };
+  },
 });
 ```
 
-### Transaction
+### Coalesced Secure Writes with Deterministic Flush
 
 ```ts
-runTransaction(StorageScope.Disk, (tx) => {
-  tx.setRaw("a", JSON.stringify(1));
-  tx.setRaw("b", JSON.stringify(2));
+import { createStorageItem, storage, StorageScope } from "react-native-nitro-storage";
+
+const sessionToken = createStorageItem<string>({
+  key: "session-token",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  coalesceSecureWrites: true,
 });
+
+sessionToken.set("token-v1");
+sessionToken.set("token-v2");
+
+// force pending secure writes to native persistence
+storage.flushSecureWrites();
 ```
 
-### Versioned Migrations
+### Storage Snapshots and Cleanup
 
 ```ts
-registerMigration(1, ({ setRaw }) => {
-  setRaw("seed", JSON.stringify({ ready: true }));
+import { storage, StorageScope } from "react-native-nitro-storage";
+
+const diskKeys = storage.getAllKeys(StorageScope.Disk);
+const diskValues = storage.getAll(StorageScope.Disk);
+const secureCount = storage.size(StorageScope.Secure);
+
+if (storage.has("legacy-flag", StorageScope.Disk)) {
+  storage.clearNamespace("legacy", StorageScope.Disk);
+}
+
+storage.clearBiometric();
+```
+
+### Low-level Subscription (outside React)
+
+```ts
+import { createStorageItem, StorageScope } from "react-native-nitro-storage";
+
+const notificationsItem = createStorageItem<boolean>({
+  key: "notifications-enabled",
+  scope: StorageScope.Disk,
+  defaultValue: true,
 });
 
-registerMigration(2, ({ getRaw, setRaw }) => {
-  const raw = getRaw("seed");
-  if (!raw) return;
-  const value = JSON.parse(raw) as { ready: boolean };
-  setRaw("seed", JSON.stringify({ ...value, migrated: true }));
+const unsubscribe = notificationsItem.subscribe(() => {
+  console.log("notifications changed:", notificationsItem.get());
 });
 
-migrateToLatest(StorageScope.Disk);
+notificationsItem.set(false);
+unsubscribe();
 ```
 
-## Scope Semantics
+### Migrating From MMKV
+
+```ts
+import { MMKV } from "react-native-mmkv";
+
+const mmkv = new MMKV();
+
+const usernameItem = createStorageItem({
+  key: "username",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+});
+
+// run once at app startup
+migrateFromMMKV(mmkv, usernameItem, true); // true = delete from MMKV after
+```
+
+---
+
+## Exported Types
+
+```ts
+import type {
+  Storage,
+  StorageItemConfig,
+  StorageItem,
+  StorageBatchSetItem,
+  Validator,
+  ExpirationConfig,
+  MigrationContext,
+  Migration,
+  TransactionContext,
+  MMKVLike,
+  SecureAuthStorageConfig,
+} from "react-native-nitro-storage";
+```
 
-- `Memory`: in-memory only, not persisted.
-- `Disk`: App-scoped UserDefaults suite (iOS), SharedPreferences (Android), `localStorage` (web).
-- `Secure`: Keychain (iOS), EncryptedSharedPreferences (Android), `sessionStorage` fallback (web).
+---
 
 ## Dev Commands
 
-From repo root:
+From repository root:
 
 ```bash
 bun run test -- --filter=react-native-nitro-storage
+bun run lint -- --filter=react-native-nitro-storage
+bun run format:check -- --filter=react-native-nitro-storage
 bun run typecheck -- --filter=react-native-nitro-storage
+bun run test:types -- --filter=react-native-nitro-storage
+bun run test:cpp -- --filter=react-native-nitro-storage
 bun run build -- --filter=react-native-nitro-storage
-bun run benchmark
 ```
 
-Inside package:
+Inside `packages/react-native-nitro-storage`:
 
 ```bash
-bun run test
-bun run test:coverage
-bun run typecheck
-bun run build
-bun run benchmark
+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 test:types      # public type-level API tests
+bun run test:cpp        # C++ binding/core tests
+bun run check:pack      # npm pack content guard
+bun run build           # bob build
+bun run benchmark       # performance benchmarks
 ```
 
 ## License