react-native-nitro-storage 0.5.5 → 0.5.7

package/README.md

@@ -1,81 +1,73 @@
 # react-native-nitro-storage
 
-[![npm](https://img.shields.io/npm/v/react-native-nitro-storage)](https://www.npmjs.com/package/react-native-nitro-storage)
-[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/react-native-nitro-storage?color=f97316&label=npm)](https://www.npmjs.com/package/react-native-nitro-storage)
+[![npm downloads](https://img.shields.io/npm/dm/react-native-nitro-storage?color=22c55e&label=downloads)](https://www.npmjs.com/package/react-native-nitro-storage)
+[![CI](https://github.com/JoaoPauloCMarra/react-native-nitro-storage/actions/workflows/ci.yml/badge.svg)](https://github.com/JoaoPauloCMarra/react-native-nitro-storage/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/react-native-nitro-storage?color=007ec6)](https://github.com/JoaoPauloCMarra/react-native-nitro-storage/blob/main/LICENSE)
 [![React Native](https://img.shields.io/badge/react--native-%3E%3D0.75-61dafb)](https://reactnative.dev/)
-[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.35.6-black)](https://nitro.margelo.com/)
+[![Expo](https://img.shields.io/badge/expo-SDK%2056-000020)](https://docs.expo.dev/)
+[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.35.7-black)](https://nitro.margelo.com/)
 
-One storage layer for render-time state, persisted app state, and native secrets.
+Synchronous Memory, Disk, and Secure storage for React Native, Expo development
+builds, and web. Nitro Storage is powered by
+[Nitro Modules](https://nitro.margelo.com/) and JSI, with typed storage items,
+React hooks, batch operations, event subscriptions, migrations, biometric secure
+values, MMKV migration helpers, and configurable web backends.
 
-Nitro Storage is a synchronous React Native storage library built on Nitro Modules and JSI. It exposes typed Memory, Disk, and Secure storage with React hooks, batch APIs, transactions, migrations, biometric access control, MMKV migration helpers, and a web IndexedDB backend.
-
-Use it when you want one storage API for React Native and web, with fast synchronous reads and native secure storage instead of mixing AsyncStorage, SecureStore, Keychain wrappers, MMKV adapters, and custom React state glue.
+Use it for startup state, preferences, feature flags, local auth state, secure
+tokens, biometric-protected values, optimistic writes, app migrations, and
+state-library persistence where a synchronous API is the right fit. Use a
+database or server-state cache instead for relational queries, large collections,
+pagination, conflict resolution, or remote synchronization.
 
 ## Contents
 
-- [At a Glance](#at-a-glance)
-- [Use It When](#use-it-when)
-- [Why Nitro Storage](#why-nitro-storage)
 - [Install](#install)
+- [Expo Config](#expo-config)
 - [Quick Start](#quick-start)
+- [Typed Storage Items](#typed-storage-items)
+- [React Hooks](#react-hooks)
 - [Storage Scopes](#storage-scopes)
-- [Docs](#docs)
-- [TypeScript And IDE Safety](#typescript-and-ide-safety)
+- [Secure Storage](#secure-storage)
+- [Batch Operations](#batch-operations)
+- [Events And Observability](#events-and-observability)
+- [Migrations And Transactions](#migrations-and-transactions)
+- [Web Backends](#web-backends)
 - [Platform Support](#platform-support)
-- [Security Model](#security-model)
-- [Migration Paths](#migration-paths)
-- [Choosing a Storage Library](#choosing-a-storage-library)
-- [Production Checklist](#production-checklist)
+- [Documentation](#documentation)
+- [Troubleshooting](#troubleshooting)
 - [Development](#development)
 
-## At a Glance
-
-| Need                              | API or feature                                                |
-| --------------------------------- | ------------------------------------------------------------- |
-| Read preferences during startup   | `createStorageItem` with `StorageScope.Disk`                  |
-| Keep session-only state           | `StorageScope.Memory`                                         |
-| Store auth tokens or secrets      | `StorageScope.Secure`                                         |
-| Protect a value with biometrics   | `biometric: true` and `biometricLevel`                        |
-| Bind storage to React             | `useStorage`, `useStorageSelector`, `useSetStorage`           |
-| Bootstrap several values at once  | `getBatch`, `setBatch`, `removeBatch`                         |
-| Roll back local writes on failure | `runTransaction`                                              |
-| Upgrade local schemas             | `registerMigration` and `migrateToLatest`                     |
-| Move existing MMKV data           | `migrateFromMMKV`                                             |
-| Persist storage on web            | `setWebDiskStorageBackend` or `createIndexedDBBackend`        |
-| Inspect secure backend state      | `getSecurityCapabilities`, `getSecureMetadata`, metadata APIs |
-| Connect external state/debug code | `subscribeNamespace`, `subscribePrefix`, `setEventObserver`   |
-
-## Use It When
-
-Nitro Storage is a good fit when your app needs synchronous local reads and a typed API across preferences, auth state, feature flags, and secrets. It is especially useful for startup gates, theme or locale preferences, persisted onboarding state, refresh tokens, biometric-protected values, and React state that should survive reloads.
-
-Use a database or server-state cache instead when you need relational queries, conflict resolution, large collections, sync protocols, pagination, or cache invalidation from remote APIs.
-
-## Why Nitro Storage
-
-- Synchronous reads for startup state, render-time preferences, and auth boundaries.
-- Typed `StorageItem<T>` values with custom serialization, validation, TTL, optimistic writes, and subscriptions.
-- Three scopes: in-memory session state, persisted disk state, and platform secure storage.
-- Secure storage backed by iOS Keychain and Android Keystore/EncryptedSharedPreferences.
-- React hooks without providers: `useStorage`, `useStorageSelector`, and `useSetStorage`.
-- Batch reads/writes, namespace cleanup, raw import/export, event subscriptions, transactions, and migrations.
-- Web parity with configurable Disk/Secure backends and an IndexedDB backend.
-- MMKV migration helper for moving existing keys without rewriting app code first.
-
 ## Install
 
 ```sh
 bun add react-native-nitro-storage react-native-nitro-modules
 ```
 
-Use the equivalent command for npm, Yarn, or pnpm if your app does not use Bun.
+Peer dependencies:
+
+| Package                      | Version    |
+| ---------------------------- | ---------- |
+| `react`                      | `>=18.2.0` |
+| `react-native`               | `>=0.75.0` |
+| `react-native-nitro-modules` | `>=0.35.7` |
+
+Nitro peer requirement: `react-native-nitro-modules >=0.35.7`.
 
-For Expo projects, install the native packages, add the config plugin, and prebuild:
+For Expo development builds:
 
 ```sh
 bunx expo install react-native-nitro-storage react-native-nitro-modules
+bunx expo prebuild
 ```
 
+Expo Go cannot load Nitro native modules. Use an Expo development build or a
+bare React Native app.
+
+## Expo Config
+
+Add the config plugin before prebuilding native iOS and Android projects:
+
 ```json
 {
   "expo": {
@@ -83,8 +75,8 @@ bunx expo install react-native-nitro-storage react-native-nitro-modules
       [
         "react-native-nitro-storage",
         {
-          "faceIDPermission": "Allow $(PRODUCT_NAME) to protect your secure data with Face ID",
-          "addBiometricPermissions": true,
+          "faceIDPermission": "Allow $(PRODUCT_NAME) to unlock secure storage.",
+          "addBiometricPermissions": false,
           "configureAndroidBackup": true
         }
       ]
@@ -93,160 +85,115 @@ bunx expo install react-native-nitro-storage react-native-nitro-modules
 }
 ```
 
-```sh
-bunx expo prebuild
-```
-
-The Expo plugin sets `NSFaceIDUsageDescription`, can opt into Android biometric permissions, initializes the Android storage adapter in `MainApplication`, and writes Android backup rules that exclude Nitro Storage secure preference files from cloud backup and device transfer. Set `configureAndroidBackup: false` only when you maintain equivalent backup rules yourself.
-
-Bare React Native projects should install pods after adding the package:
-
-```sh
-cd ios && pod install
-```
-
-Bare Android apps must initialize the adapter from `MainApplication` before using native storage:
+| Option                    | Default                  | What it does                                                   |
+| ------------------------- | ------------------------ | -------------------------------------------------------------- |
+| `faceIDPermission`        | Built-in Face ID message | Sets `NSFaceIDUsageDescription`.                               |
+| `addBiometricPermissions` | `false`                  | Adds Android biometric and fingerprint permissions.            |
+| `configureAndroidBackup`  | `true`                   | Writes Android backup rules that exclude secure storage files. |
 
-```kt
-import com.nitrostorage.AndroidStorageAdapter
-
-override fun onCreate() {
-  super.onCreate()
-  AndroidStorageAdapter.init(this)
-}
-```
+The plugin also initializes the Android storage adapter in `MainApplication`.
+Set `configureAndroidBackup: false` only when your app maintains equivalent
+backup and device-transfer exclusions for Nitro Storage secure files.
 
 ## Quick Start
 
-Create storage items outside React render functions, then use them from anywhere.
-
 ```ts
 import {
-  createStorageItem,
   StorageScope,
-  useStorage,
+  createStorageItem,
+  storage,
 } from "react-native-nitro-storage";
 
-type Theme = "system" | "light" | "dark";
-
-export const themeItem = createStorageItem<Theme>({
+const themeItem = createStorageItem<"light" | "dark">({
   key: "theme",
+  namespace: "settings",
   scope: StorageScope.Disk,
-  defaultValue: "system",
-  validate: (value): value is Theme =>
-    value === "system" || value === "light" || value === "dark",
+  defaultValue: "light",
 });
 
-export function ThemeButton() {
-  const [theme, setTheme] = useStorage(themeItem);
+themeItem.set("dark");
 
-  return (
-    <Button
-      title={`Theme: ${theme}`}
-      onPress={() => setTheme(theme === "dark" ? "light" : "dark")}
-    />
-  );
-}
+const theme = themeItem.get();
+const raw = storage.getString("settings:theme", StorageScope.Disk);
 ```
 
-Secure values use the same item API:
-
-```ts
-import {
-  AccessControl,
-  BiometricLevel,
-  createStorageItem,
-  StorageScope,
-} from "react-native-nitro-storage";
-
-export const refreshTokenItem = createStorageItem<string>({
-  key: "refreshToken",
-  namespace: "auth",
-  scope: StorageScope.Secure,
-  defaultValue: "",
-  biometric: true,
-  biometricLevel: BiometricLevel.BiometryOrPasscode,
-  accessControl: AccessControl.AfterFirstUnlockThisDeviceOnly,
-});
+## Typed Storage Items
 
-refreshTokenItem.set("opaque-refresh-token");
-```
-
-Bootstrap several values in one synchronous call:
+`createStorageItem<T>()` is the recommended API for application code. It keeps
+serialization, validation, default values, TTL, namespace, access-control, and
+React hook types attached to the key.
 
 ```ts
-import { StorageScope, getBatch } from "react-native-nitro-storage";
-
-const [theme] = getBatch([themeItem], StorageScope.Disk);
-```
+type Preferences = {
+  theme: "system" | "light" | "dark";
+  compactMode: boolean;
+};
 
-Keep multi-step local writes reversible:
+const preferencesItem = createStorageItem<Preferences>({
+  key: "preferences",
+  namespace: "settings",
+  scope: StorageScope.Disk,
+  defaultValue: { theme: "system", compactMode: false },
+  validate: (value): value is Preferences =>
+    typeof value === "object" && value !== null && "theme" in value,
+});
 
-```ts
-import { StorageScope, runTransaction } from "react-native-nitro-storage";
+preferencesItem.set((previous) => ({
+  ...previous,
+  compactMode: !previous.compactMode,
+}));
 
-runTransaction(StorageScope.Disk, (tx) => {
-  tx.setItem(themeItem, "dark");
-  tx.setRaw("onboarding:complete", "true");
+const snapshot = preferencesItem.getWithVersion();
+const didWrite = preferencesItem.setIfVersion(snapshot.version, {
+  ...snapshot.value,
+  theme: "dark",
 });
 ```
 
-Create a raw snapshot for backups or test fixtures, then restore it later:
+The package exports `StorageItem`, `StorageItemConfig`, `StorageSetter`,
+`VersionedValue`, `StorageBatchSetItem`, web backend types, event types, secure
+metadata types, and capability types for IDE-safe integrations.
 
-```ts
-import { StorageScope, storage } from "react-native-nitro-storage";
-
-const snapshot = storage.export(StorageScope.Disk);
+## React Hooks
 
-storage.import(snapshot, StorageScope.Disk);
-```
+```tsx
+import { Switch } from "react-native";
+import { useSetStorage, useStorage } from "react-native-nitro-storage";
 
-`storage.export(StorageScope.Secure)` throws unless you pass `{ includeSecureValues: true }`. Prefer `storage.exportSecureUnsafe()` only for short-lived in-memory secure migration workflows. Do not log Secure exports or include them in diagnostics, analytics, crash reports, or support bundles.
+export function ThemeToggle() {
+  const [theme] = useStorage(themeItem);
+  const setTheme = useSetStorage(themeItem);
 
-Subscribe to storage changes outside React:
+  return (
+    <Switch
+      value={theme === "dark"}
+      onValueChange={(enabled) => setTheme(enabled ? "dark" : "light")}
+    />
+  );
+}
+```
 
-```ts
-import { StorageScope, storage } from "react-native-nitro-storage";
+Use `useStorageSelector()` when a component needs a derived value instead of the
+whole stored object.
 
-const unsubscribe = storage.subscribeNamespace(
-  "settings",
-  StorageScope.Disk,
-  (event) => {
-    if (event.type === "batch") {
-      console.log("settings changed", event.changes.length);
-      return;
-    }
+```tsx
+import { useStorageSelector } from "react-native-nitro-storage";
 
-    console.log(event.key, event.operation);
-  },
+const [compactMode] = useStorageSelector(
+  preferencesItem,
+  (preferences) => preferences.compactMode,
 );
 ```
 
 ## Storage Scopes
 
-| Scope                 | Backing store                                                                 | Best for                                         |
-| --------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------ |
-| `StorageScope.Memory` | JS memory                                                                     | Session flags, wizard state, optimistic UI cache |
-| `StorageScope.Disk`   | UserDefaults on iOS, SharedPreferences on Android, web Disk backend           | Preferences, feature flags, non-secret app state |
-| `StorageScope.Secure` | iOS Keychain, Android Keystore/EncryptedSharedPreferences, web Secure backend | Tokens, credentials, device-bound secrets        |
-
-Use Secure scope only for secrets. Disk scope is faster and easier to inspect, but it is not a secret store.
-
-## Docs
+| Scope                 | Backing store                                          | Use it for                                                                   |
+| --------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `StorageScope.Memory` | In-process memory                                      | Session-only state, fast counters, and render-time caches.                   |
+| `StorageScope.Disk`   | UserDefaults on iOS, SharedPreferences on Android, web | Preferences, feature flags, onboarding state, and non-secret persisted data. |
+| `StorageScope.Secure` | Keychain on iOS, Android Keystore-backed preferences   | Refresh tokens, credentials, API tokens, and biometric-protected values.     |
 
-| Task                                        | Start here                                                                     |
-| ------------------------------------------- | ------------------------------------------------------------------------------ |
-| Learn the public API                        | [docs/api-reference.md](docs/api-reference.md)                                 |
-| Bind storage to React                       | [docs/react-hooks.md](docs/react-hooks.md)                                     |
-| Store tokens or biometric secrets           | [docs/secure-storage.md](docs/secure-storage.md)                               |
-| Use batch APIs, transactions, or migrations | [docs/batch-transactions-migrations.md](docs/batch-transactions-migrations.md) |
-| Configure web Disk/Secure storage           | [docs/web-backends.md](docs/web-backends.md)                                   |
-| Migrate from `react-native-mmkv`            | [docs/mmkv-migration.md](docs/mmkv-migration.md)                               |
-| Copy working snippets                       | [docs/recipes.md](docs/recipes.md)                                             |
-| Run or interpret benchmarks                 | [docs/benchmarks.md](docs/benchmarks.md)                                       |
-| Report a vulnerability                      | [SECURITY.md](SECURITY.md)                                                     |
-
-## API Snapshot
+## Secure Storage
 
 ```ts
 import {
@@ -255,209 +202,209 @@ import {
   StorageScope,
   createSecureAuthStorage,
   createStorageItem,
-  flushWebStorageBackends,
-  getBatch,
-  getStorageErrorCode,
   isKeychainLockedError,
-  migrateFromMMKV,
-  migrateToLatest,
-  registerMigration,
-  removeBatch,
-  runTransaction,
-  setBatch,
-  setWebDiskStorageBackend,
-  setWebSecureStorageBackend,
   storage,
-  useSetStorage,
-  useStorage,
-  useStorageSelector,
 } from "react-native-nitro-storage";
-```
 
-The main building blocks are:
-
-- `createStorageItem<T>(config)` for typed values.
-- `storage` for raw reads, namespace cleanup, events, secure metadata, metrics, and runtime capability checks.
-- `getBatch`, `setBatch`, and `removeBatch` for multi-key work.
-- `runTransaction` for synchronous rollback on failure.
-- `registerMigration` and `migrateToLatest` for versioned local data migrations.
-- `createSecureAuthStorage` for a compact secure-token item map.
-- `setWebDiskStorageBackend`, `setWebSecureStorageBackend`, and `createIndexedDBBackend` for web persistence.
-
-See the full [API reference](docs/api-reference.md).
-
-## TypeScript And IDE Safety
-
-The public API is designed around typed storage items. Define the value type, default value, serializer, parser, and validator in one place so reads, writes, React hooks, batch APIs, migrations, and transactions all share the same contract.
+const refreshToken = createStorageItem<string>({
+  key: "refreshToken",
+  namespace: "auth",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  accessControl: AccessControl.AfterFirstUnlockThisDeviceOnly,
+});
 
-```ts
-type Preferences = {
-  theme: "system" | "light" | "dark";
-  compactMode: boolean;
-};
+const recoveryCode = createStorageItem<string>({
+  key: "recoveryCode",
+  namespace: "auth",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  biometric: true,
+  biometricLevel: BiometricLevel.BiometryOrPasscode,
+});
 
-const preferencesItem = createStorageItem<Preferences>({
-  key: "preferences",
-  scope: StorageScope.Disk,
-  defaultValue: { theme: "system", compactMode: false },
-  validate: (value): value is Preferences =>
-    typeof value === "object" &&
-    value !== null &&
-    ["system", "light", "dark"].includes(
-      (value as Partial<Preferences>).theme ?? "",
-    ) &&
-    typeof (value as Partial<Preferences>).compactMode === "boolean",
+const auth = createSecureAuthStorage({
+  accessToken: { ttlMs: 15 * 60_000 },
+  refreshToken: {
+    accessControl: AccessControl.AfterFirstUnlockThisDeviceOnly,
+  },
 });
 
-preferencesItem.set((current) => ({
-  ...current,
-  compactMode: !current.compactMode,
-}));
+try {
+  recoveryCode.get();
+} catch (error) {
+  if (isKeychainLockedError(error)) {
+    storage.getSecurityCapabilities();
+  }
+}
 ```
 
-For web backend overrides, import the backend contracts instead of using loose object shapes:
-
-```ts
-import type {
-  WebDiskStorageBackend,
-  WebSecureStorageBackend,
-} from "react-native-nitro-storage";
-```
+Secure scope uses iOS Keychain and Android Keystore-backed
+EncryptedSharedPreferences. Keep secure values small, do not log them, and avoid
+exporting secure values unless you are intentionally doing a short-lived
+in-memory migration. `storage.export(StorageScope.Secure)` throws unless you
+explicitly opt into `{ includeSecureValues: true }`.
 
-## Platform Support
+## Batch Operations
 
-| Platform | Status    | Notes                                                                                                  |
-| -------- | --------- | ------------------------------------------------------------------------------------------------------ |
-| iOS      | Supported | Disk uses app-suite `UserDefaults`; Secure uses Keychain.                                              |
-| Android  | Supported | Disk uses SharedPreferences; Secure uses Keystore-backed EncryptedSharedPreferences.                   |
-| Expo     | Supported | Add the included config plugin before prebuild.                                                        |
-| Web      | Supported | Defaults to localStorage-style backends; IndexedDB backend is available for persistent Secure storage. |
-
-Peer dependencies:
-
-- `react >=18.2.0`
-- `react-native >=0.75.0`
-- `react-native-nitro-modules >=0.35.6`
-
-## Security Model
-
-Secure scope stores values in native secure storage on iOS and Android. Biometric items are stored through separate biometric paths and can require biometric or passcode access on each read.
+`getBatch()` preserves tuple value types, so IDEs infer each result from the
+matching item.
 
 ```ts
-const capabilities = storage.getSecurityCapabilities();
-const metadata = storage.getSecureMetadata("auth:refreshToken");
-```
-
-Security metadata APIs never return stored values. They are intended for diagnostics, inventory screens, and support tooling that needs to understand which secure backend is active without exposing secrets.
+import { getBatch, removeBatch, setBatch } from "react-native-nitro-storage";
 
-Important boundaries:
+const localeItem = createStorageItem({
+  key: "locale",
+  namespace: "settings",
+  scope: StorageScope.Disk,
+  defaultValue: "en-US",
+});
 
-- Disk and Memory scopes are not secret stores.
-- Web Secure storage depends on the backend you configure; browser storage cannot provide iOS Keychain or Android Keystore guarantees.
-- Hardware-backed secure storage is reported as `unknown` unless the platform can prove it through the native backend.
-- Secret values should not be logged, exported in diagnostics, or copied into crash reports.
+const [theme, locale] = getBatch(
+  [themeItem, localeItem] as const,
+  StorageScope.Disk,
+);
 
-Read [docs/secure-storage.md](docs/secure-storage.md) and [SECURITY.md](SECURITY.md) before using Secure scope for production auth tokens.
+setBatch(
+  [
+    { item: themeItem, value: "dark" },
+    { item: localeItem, value: "en-US" },
+  ],
+  StorageScope.Disk,
+);
 
-## Migration Paths
+removeBatch([themeItem, localeItem], StorageScope.Disk);
+```
 
-From `react-native-mmkv`, migrate existing keys in place and keep your typed item API as the destination:
+## Events And Observability
 
 ```ts
-import { migrateFromMMKV } from "react-native-nitro-storage";
-
-migrateFromMMKV(mmkv, themeItem, true);
-migrateFromMMKV(mmkv, refreshTokenItem, true);
-```
+const unsubscribe = storage.subscribeNamespace("settings", (event) => {
+  console.log(event.key, event.operation, event.source);
+});
 
-From `AsyncStorage`, `expo-secure-store`, Keychain wrappers, or a custom storage adapter, run a one-time startup migration: read the old value, validate it, write it through the matching `StorageItem`, then stop reading the old key after the migration ships broadly.
+storage.setEventObserver((event) => {
+  console.log(event.type, event.scope);
+});
 
-```ts
-const oldTheme = await AsyncStorage.getItem("theme");
+storage.setMetricsObserver((event) => {
+  console.log(event.operation, event.durationMs);
+});
 
-if (oldTheme === "light" || oldTheme === "dark" || oldTheme === "system") {
-  themeItem.set(oldTheme);
-  await AsyncStorage.removeItem("theme");
-}
+const metrics = storage.getMetricsSnapshot();
+storage.resetMetrics();
+unsubscribe();
 ```
 
-For versioned local data, keep migrations explicit and repeatable:
+Secure event observer values are redacted by default. Pass
+`{ redactSecureValues: false }` only in trusted debug tooling where raw values
+are safe to inspect.
+
+## Migrations And Transactions
 
 ```ts
 import {
-  StorageScope,
+  migrateFromMMKV,
   migrateToLatest,
   registerMigration,
+  runTransaction,
 } from "react-native-nitro-storage";
 
-registerMigration(2, ({ getRaw, setRaw }) => {
-  if (getRaw("theme") === "auto") {
-    setRaw("theme", "system");
+registerMigration(2, ({ getRaw, setRaw, removeRaw }) => {
+  const oldTheme = getRaw("legacyTheme");
+
+  if (oldTheme) {
+    setRaw("settings:theme", oldTheme);
+    removeRaw("legacyTheme");
   }
 });
 
 migrateToLatest(StorageScope.Disk);
-```
 
-See [docs/mmkv-migration.md](docs/mmkv-migration.md) and [docs/batch-transactions-migrations.md](docs/batch-transactions-migrations.md) for the full flows.
+runTransaction(() => {
+  themeItem.set("dark");
+  localeItem.set("en-US");
+});
 
-## Choosing a Storage Library
+migrateFromMMKV(mmkvInstance, themeItem);
+```
 
-| Need                                                            | Good fit                                    |
-| --------------------------------------------------------------- | ------------------------------------------- |
-| Fast synchronous typed state plus secure storage in one package | `react-native-nitro-storage`                |
-| Existing MMKV-only app with no secure storage requirement       | `react-native-mmkv` can still be enough     |
-| Async key/value persistence only                                | `@react-native-async-storage/async-storage` |
-| Expo-only secure token storage with async calls                 | `expo-secure-store`                         |
-| Keychain/Keystore credentials only                              | A focused Keychain wrapper may be simpler   |
+Transactions roll back local writes if the callback throws.
 
-Nitro Storage is strongest when the app needs synchronous reads, React bindings, typed values, secure storage, and migration utilities together. It is not trying to replace databases, query caches, or server-state libraries.
+## Web Backends
 
-## Production Checklist
+```ts
+import {
+  setWebDiskStorageBackend,
+  setWebSecureStorageBackend,
+} from "react-native-nitro-storage";
+import { createIndexedDBBackend } from "react-native-nitro-storage/indexeddb-backend";
 
-- Use `StorageScope.Secure` only for secrets and tokens.
-- Keep secrets out of logs, exports, analytics, and crash reports.
-- Test biometric and Keychain/Keystore flows on real iOS and Android devices.
-- Configure a web Secure backend intentionally; browser storage does not provide native Keychain or Keystore guarantees.
-- Run the full package gate before release:
+const backend = await createIndexedDBBackend({
+  dbName: "app-storage",
+  storeName: "kv",
+});
 
-```sh
-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 -- --filter=react-native-nitro-storage
-bun run test:coverage -- --filter=react-native-nitro-storage
-bun run test:cpp -- --filter=react-native-nitro-storage
-bun run test:cpp:coverage -- --filter=react-native-nitro-storage
-(cd packages/react-native-nitro-storage && bun run check:pack)
-bun run publish-package:dry -- --yes --with-coverage
+setWebDiskStorageBackend(backend);
+setWebSecureStorageBackend(backend);
 ```
 
-Publishing a GitHub Release tagged `v<package.version>` triggers the npm workflow.
-The npm package must trust `.github/workflows/npm-publish.yml` in npm package settings.
+Browser storage cannot provide iOS Keychain or Android Keystore guarantees. Web
+Secure scope is only as strong as the backend you configure.
+
+## Platform Support
+
+| Platform | Status                                             |
+| -------- | -------------------------------------------------- |
+| iOS      | Memory, Disk, and Keychain-backed Secure storage.  |
+| Android  | Memory, Disk, and Keystore-backed Secure storage.  |
+| Web      | Memory plus configurable Disk and Secure backends. |
+| Expo     | Development builds with the config plugin.         |
+
+## Documentation
+
+| Topic                               | File                                                                           |
+| ----------------------------------- | ------------------------------------------------------------------------------ |
+| API reference                       | [docs/api-reference.md](docs/api-reference.md)                                 |
+| React hooks                         | [docs/react-hooks.md](docs/react-hooks.md)                                     |
+| Secure storage                      | [docs/secure-storage.md](docs/secure-storage.md)                               |
+| Web backends                        | [docs/web-backends.md](docs/web-backends.md)                                   |
+| Batch, transactions, and migrations | [docs/batch-transactions-migrations.md](docs/batch-transactions-migrations.md) |
+| MMKV migration                      | [docs/mmkv-migration.md](docs/mmkv-migration.md)                               |
+| Recipes                             | [docs/recipes.md](docs/recipes.md)                                             |
+| Benchmarks                          | [docs/benchmarks.md](docs/benchmarks.md)                                       |
+| Security policy                     | [SECURITY.md](SECURITY.md)                                                     |
+
+## Troubleshooting
+
+- **Expo Go error:** build a development client; Expo Go cannot load Nitro
+  modules.
+- **Secure values fail after Android restore:** keep `configureAndroidBackup:
+true` or provide equivalent backup exclusions.
+- **Biometric prompt does not appear:** set `biometric: true` on the item and
+  add native biometric permissions when your app needs them.
+- **Web secure storage is unavailable:** configure a secure backend before using
+  Secure scope on web.
+- **TypeScript cannot infer `getBatch()` tuple values:** pass readonly tuples
+  with `as const`, or keep batch items in a `const` tuple.
 
 ## Development
 
 ```sh
 bun install
-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 -- --filter=react-native-nitro-storage
-bun run test:cpp -- --filter=react-native-nitro-storage
+bun run check
+bun run test:cpp:asan
+bun run test:cpp:ubsan
+bun run test:cpp:tsan
+bun run release:preflight
+bun run example:android
+bun run example:ios
 ```
 
-Release checks:
-
-```sh
-bun run build -- --filter=react-native-nitro-storage
-bun run benchmark -- --filter=react-native-nitro-storage
-(cd packages/react-native-nitro-storage && bun run check:pack)
-bun run publish-package:dry -- --yes
-```
+Run native example builds before release when changing plugin, native, Nitro,
+secure storage, or packaging files. The package release path also validates
+package contents and dry-run publish behavior.
 
 ## License
 
-MIT
+[MIT](LICENSE)