react-native-nitro-storage 0.10.4 → 0.11.0

package/docs/api-reference.md

@@ -14,28 +14,28 @@ const item = createStorageItem<T>({
 
 `StorageItemConfig<T>`:
 
-| Field                        | Type                             | Purpose                                                             |
-| ---------------------------- | -------------------------------- | ------------------------------------------------------------------- |
-| `key`                        | `string`                         | Storage key. Combined with `namespace` when provided.               |
-| `scope`                      | `StorageScope`                   | Memory, Disk, or Secure.                                            |
-| `defaultValue`               | `T`                              | Value returned when no stored value exists.                         |
-| `serialize`                  | `(value: T) => string`           | Custom string encoder. Defaults to primitive/JSON serialization.    |
-| `deserialize`                | `(value: string) => T`           | Custom string decoder.                                              |
-| `validate`                   | `(value: unknown) => value is T` | Runtime guard for stored data.                                      |
-| `onValidationError`          | `(invalidValue: unknown) => T`   | Replacement value when validation fails.                            |
-| `expiration`                 | `{ ttlMs: number }`              | Time-to-live for the value.                                         |
-| `onExpired`                  | `(key: string) => void`          | Called when a read detects TTL expiry.                              |
-| `readCache`                  | `boolean`                        | Reuse raw cache entries for reads, including cached missing values. |
-| `coalesceDiskWrites`         | `boolean`                        | Buffer Disk writes until the next flush.                            |
-| `coalesceSecureWrites`       | `boolean`                        | Buffer Secure writes until the next flush.                          |
-| `namespace`                  | `string`                         | Prefix keys as `namespace:key`.                                     |
-| `biometric`                  | `boolean`                        | Store through biometric secure storage.                             |
-| `biometricLevel`             | `BiometricLevel`                 | Require biometric/passcode or biometric-only access.                |
-| `accessControl`              | `AccessControl`                  | Platform secure accessibility setting.                              |
-| `group`                      | `string`                         | Register the item for group cleanup and inspection.                 |
-| `renameFrom`                 | `string \| readonly string[]`    | Copy a legacy key on first read, then remove it.                    |
-| `fallbackToCacheOnReadError` | `boolean`                        | Return the last cached value when a backend read fails.             |
-| `onReadError`                | `(error: unknown) => void`       | Observe a backend read failure before fallback or rethrow.          |
+| Field                        | Type                             | Purpose                                                                                                                                                                               |
+| ---------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `key`                        | `string`                         | Storage key. Combined with `namespace` when provided. Must not be empty (`invalid_key`).                                                                                              |
+| `scope`                      | `StorageScope`                   | Memory, Disk, or Secure.                                                                                                                                                              |
+| `defaultValue`               | `T`                              | Value returned when no stored value exists.                                                                                                                                           |
+| `serialize`                  | `(value: T) => string`           | Custom string encoder. Defaults to primitive/JSON serialization.                                                                                                                      |
+| `deserialize`                | `(value: string) => T`           | Custom string decoder.                                                                                                                                                                |
+| `validate`                   | `(value: unknown) => value is T` | Runtime guard for stored data.                                                                                                                                                        |
+| `onValidationError`          | `(invalidValue: unknown) => T`   | Replacement value when validation fails.                                                                                                                                              |
+| `expiration`                 | `{ ttlMs: number }`              | Time-to-live for the value.                                                                                                                                                           |
+| `onExpired`                  | `(key: string) => void`          | Called when a read detects TTL expiry.                                                                                                                                                |
+| `readCache`                  | `boolean`                        | Reuse raw cache entries for reads, including cached missing values. Items without `readCache` or `fallbackToCacheOnReadError` do not fill the cache on read.                          |
+| `coalesceDiskWrites`         | `boolean`                        | Buffer Disk writes until the next flush.                                                                                                                                              |
+| `coalesceSecureWrites`       | `boolean`                        | Buffer Secure writes until the next flush.                                                                                                                                            |
+| `namespace`                  | `string`                         | Prefix keys as `namespace:key`.                                                                                                                                                       |
+| `biometric`                  | `boolean`                        | Store through biometric secure storage.                                                                                                                                               |
+| `biometricLevel`             | `BiometricLevel`                 | Require biometric/passcode or biometric-only access.                                                                                                                                  |
+| `accessControl`              | `AccessControl`                  | Platform secure accessibility setting.                                                                                                                                                |
+| `group`                      | `string`                         | Register the item for group cleanup and inspection.                                                                                                                                   |
+| `renameFrom`                 | `string \| readonly string[]`    | Copy a legacy key on first read, then remove it.                                                                                                                                      |
+| `fallbackToCacheOnReadError` | `boolean`                        | Return the last cached value when a backend read fails with `keychain_locked`. Other errors still throw. Only iOS reports `keychain_locked`, so this has no effect on Android or web. |
+| `onReadError`                | `(error: unknown) => void`       | Observe a backend read failure before fallback or rethrow.                                                                                                                            |
 
 `StorageItem<T>`:
 
@@ -65,6 +65,20 @@ const unsubscribe = profileItem.subscribeSelector(
 );
 ```
 
+## Scoped Item Factories
+
+`memoryItem(config)`, `diskItem(config)`, and `secureItem(config)` take the same
+config as `createStorageItem` without the `scope` field.
+
+```ts
+const draft = memoryItem<string>({ key: "draft", defaultValue: "" });
+const theme = diskItem<"light" | "dark">({
+  key: "theme",
+  defaultValue: "light",
+});
+const token = secureItem<string>({ key: "token", defaultValue: "" });
+```
+
 ## createSetItem
 
 ```ts
@@ -85,9 +99,11 @@ flags.getTyped();
 ## React Hooks
 
 ```ts
-const [value, setValue] = useStorage(item);
+const [value, setValue, actions] = useStorage(item);
 const [selected, setItem] = useStorageSelector(item, selector, isEqual);
 const setOnly = useSetStorage(item);
+const readOnly = useStorageValue(item);
+const writeOnly = useStorageActions(item);
 ```
 
 See [react-hooks.md](react-hooks.md).
@@ -128,7 +144,8 @@ See [react-hooks.md](react-hooks.md).
 | `getMetricsSnapshot()`                           | Read aggregated metrics.                                                                  |
 | `getScopedMetricsSnapshot()`                     | Read metrics grouped by storage scope.                                                    |
 | `resetMetrics()`                                 | Clear metrics counters.                                                                   |
-| `getCapabilities()`                              | Read runtime storage capabilities.                                                        |
+| `getCacheMetrics()`                              | Read raw-cache hits, misses, live entries, and estimated bytes.                           |
+| `getCapabilities()`                              | Read runtime storage capabilities. Native `backend.disk` is `"sqlite"`.                   |
 | `getSecurityCapabilities()`                      | Read secure backend capability metadata.                                                  |
 | `getSecureMetadata(key)`                         | Read secure metadata for one key without returning its value.                             |
 | `getAllSecureMetadata()`                         | Read secure metadata for all secure keys without values.                                  |
@@ -259,6 +276,21 @@ the native or web adapter. `isStorageError(error, code)` matches one exact code
 without parsing platform message text. See [secure-storage.md](secure-storage.md)
 for recovery semantics.
 
+| Code                          | Raised when                                                                                                             |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `keychain_locked`             | The protected store is locked.                                                                                          |
+| `authentication_required`     | The item needs user authentication, or the user cancelled the prompt.                                                   |
+| `key_invalidated`             | The protecting key was invalidated, for example by a biometric enrolment change.                                        |
+| `biometric_unavailable`       | The requested biometric level is not available on this device or OS version.                                            |
+| `storage_corruption`          | Stored secure data could not be decrypted, or (Android) the Secure master key or store cannot be created. Do not retry. |
+| `storage_compensation_failed` | A multi-step write failed and restoring the previous state also failed.                                                 |
+| `unsupported`                 | The operation is not available on this platform or environment.                                                         |
+| `invalid_key`                 | A storage key is empty.                                                                                                 |
+
+`StorageCompositeError` and `StorageCompensationError` describe errors that
+carry a primary failure plus secondary failures from reconciliation or
+compensation steps.
+
 `isKeychainLockedError(error)` is deprecated. It remains available for
 compatibility and returns `true` for `keychain_locked`,
 `authentication_required`, and `key_invalidated`.
@@ -273,9 +305,10 @@ getWebSecureStorageBackend();
 await flushWebStorageBackends();
 ```
 
-The web entry also exports `describeWebBackendCapabilities(backend)` and
-`isIndexedDBWebBackend(backend)`. The native entry keeps the web backend
-setters, getters, and flush function as typed no-ops for shared code.
+Every entry, including native and `/testing`, exports
+`describeWebBackendCapabilities(backend)` and `isIndexedDBWebBackend(backend)`.
+The native and testing entries keep the web backend setters, getters, and flush
+function as typed no-ops for shared code.
 
 See [web-backends.md](web-backends.md).
 
@@ -339,6 +372,18 @@ Common public types:
 - `PlatformStorage`
 - `PlatformScope`
 - `WebBackendCapabilities`
+- `StorageCapabilities`
+- `StorageCacheMetrics`
+- `StorageExportOptions`
+- `StorageEventObserverOptions`
+- `StorageCompositeError`
+- `StorageCompensationError`
+- `SetStorageItem<T>`
+- `SetItemConfig<T>`
+- `StorageClearOptions`
+- `StorageKeyRef`
+- `StorageActions<T>`
+- `StorageSetter<T>`
 
 `getCapabilities().writeBuffering` describes real per-mode durability:
 
@@ -350,4 +395,4 @@ Common public types:
 
 `describeWebBackendCapabilities(backend)` reports a backend's `buffered`, `flushable`, `closable`, and `subscribable` capabilities from the same typed contract used by the built-in backends.
 
-The IndexedDB subpath exports `createIndexedDBBackend()` and `IndexedDBBackendOptions`.
+The IndexedDB subpath exports `createIndexedDBBackend()` and `IndexedDBBackendOptions`. The root export of `createIndexedDBBackend` is deprecated; import it from `react-native-nitro-storage/indexeddb-backend`.

package/docs/benchmarks.md

@@ -28,22 +28,14 @@ Native Disk/Secure baselines require a device or simulator run and are not part
 
 ## Release Checklist
 
-Before publishing:
+Before publishing, run the full release gate:
 
 ```sh
-bun run codegen:check
-bun run lint:check
-bun run format:check
-bun run typecheck
-bun run test:types
-bun run test
-bun run test:cpp
-bun run build
-bun run benchmark
-bun run --cwd packages/react-native-nitro-storage check:pack
+bun run release:preflight
 ```
 
-Keep the dry-publish output in the release notes when validating a version locally.
+It runs `check:ci` (including the benchmark), the example checks, the package
+audit, and the publish dry run.
 
 ## 2026-09-27 Memory enumeration experiment
 

package/docs/mmkv-migration.md

@@ -4,12 +4,14 @@ Use `migrateFromMMKV(mmkv, item, deleteAfterMigration?)` when an app already sto
 
 The helper reads in this order:
 
-1. `mmkv.getString(key)`
+1. `mmkv.getString(key)`, then `JSON.parse` on the string. If parsing succeeds, the parsed value is written; otherwise the raw string is written.
 2. `mmkv.getNumber(key)`
 3. `mmkv.getBoolean(key)`
 
 It writes through `item.set()`, so custom serialization, validation, TTL behavior, and listeners remain active.
 
+Because of the `JSON.parse` step, a string item can receive a non-string value: MMKV strings such as `"12345"`, `"true"`, or `"null"` are written as a number, a boolean, or `null`, while the item type still says `string`. For string items, add `validate` with an `onValidationError` fallback, or copy the raw value with `storage.setString(key, mmkv.getString(key), scope)` instead.
+
 ## Basic Migration
 
 ```ts

package/docs/native-libraries.md

@@ -6,12 +6,18 @@ EncryptedSharedPreferences. Web Disk stays on the configured web backend
 
 ## Kept
 
-| Library    | Where                                            | Why                                                                                                                                                                     |
-| ---------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| SQLite WAL | iOS `SqliteDiskStore`, Android `DiskSqliteStore` | Transactional batch writes, prefix queries without loading a plist/XML map, and crash-safe persistence. Closest Disk engine to a dedicated mmap KV without adding MMKV. |
+| Library    | Where                                            | Why                                                                                                                                                    |
+| ---------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| SQLite WAL | iOS `SqliteDiskStore`, Android `DiskSqliteStore` | Transactional batch writes, literal prefix queries in SQL, and crash-safe persistence. Closest Disk engine to a dedicated mmap KV without adding MMKV. |
 
 Existing UserDefaults suite keys and Android `NitroStorage` preferences are
-copied into SQLite on first open. Later Disk reads and writes use SQLite.
+copied into SQLite once, on first open. A marker in the SQLite `meta` table
+(`suite_v1` on iOS, `prefs_v1` on Android) records completion, so later launches
+skip the import. On iOS the suite domain is kept for downgrade safety, and Disk
+key enumeration still merges its keys. On Android the legacy `NitroStorage`
+preferences are kept after the import for downgrade safety, like the iOS suite;
+Disk deletes remove the key from them and `clear(Disk)` clears them, so a logout
+wipe leaves no pre-SQLite copy behind. Later Disk reads and writes use SQLite.
 
 ## Evaluated and not shipped
 

package/docs/secure-storage.md

@@ -47,7 +47,14 @@ export const recoveryCodeItem = createStorageItem<string>({
 
 `BiometricLevel.BiometryOnly` does not allow passcode fallback. Use `BiometricLevel.BiometryOrPasscode` when passcode fallback is acceptable.
 
-On Android 11 and newer, the two levels use separate Android Keystore keys with distinct allowed authenticators. Android 10 and older support `BiometryOrPasscode`; `BiometryOnly` reports `biometric_unavailable` because the older Keystore API cannot enforce that distinction safely for this storage backend. Android authorization remains valid for a 30-second window after successful authentication.
+On Android 11 and newer, the two levels use separate Android Keystore keys with distinct allowed authenticators. Android 10 and older support `BiometryOrPasscode`; `BiometryOnly` reports `biometric_unavailable` because the older Keystore API cannot enforce that distinction safely for this storage backend.
+
+### Platform prompt behaviour
+
+- **iOS:** reading a biometric item runs `SecItemCopyMatching` with user interaction allowed. The system shows the Face ID, Touch ID, or passcode sheet, and the synchronous JSI call blocks the JavaScript thread until the user answers. JavaScript timers, JavaScript-driven animations, and other JSI calls wait during that time. Read biometric items from a user action, not during render. Deleting a biometric item does not read it first unless an event listener or an unredacted event observer needs the previous value, so a delete does not show a prompt.
+- **Android errors:** if the default Secure master key or store cannot be created (for example a Keystore key that exists but is unusable), Secure calls throw `storage_corruption`. This is not a temporary state: do not retry in a loop. Secure scope stays unavailable until the app data is cleared or the app is reinstalled; Memory and Disk keep working.
+- **Android:** Nitro Storage never shows a prompt. Each biometric level is an `EncryptedSharedPreferences` file whose Tink keyset is wrapped by an Android Keystore key that requires user authentication within the last 30 seconds. That key is used only when the store is first opened in a process: `EncryptedSharedPreferences` decrypts the keyset once and keeps it in memory, and later reads and writes in the same process do not check authentication again. After the first successful open, biometric values stay readable without authentication until the process ends.
+- **What Android apps must do:** run `androidx.biometric.BiometricPrompt` in the app before every read that must be gated, and treat the storage check as a one-time guard per process. Enable the config plugin option `addBiometricPermissions` so the app can declare `USE_BIOMETRIC` and `USE_FINGERPRINT` for its own prompt. Reading a `BiometryOrPasscode` item opens only the `BiometryOrPasscode` store, so a device-credential authentication is enough for that level.
 
 ## Access Control
 
@@ -61,6 +68,8 @@ On Android 11 and newer, the two levels use separate Android Keystore keys with
 | `AccessControl.WhenUnlockedThisDeviceOnly`     | The secret should not migrate through backup/restore.             |
 | `AccessControl.AfterFirstUnlockThisDeviceOnly` | Background refresh is needed, but migration is not allowed.       |
 
+On iOS the level applies on every write, including updates of an item that already exists, so changing `accessControl` or `storage.setAccessControl()` moves existing items to the new level on their next write. On iOS, `item.has()` and `storage.has(key, StorageScope.Secure)` throw `keychain_locked` while the keychain is locked, and a Keychain status error for any other unexpected status, instead of returning `false`. A biometric item that the Keychain reports as needing authentication counts as present, so `has()` on a biometric item returns `true` without a prompt; while the device is locked the same status also returns `true`. Listing, counting, and prefix queries on Secure keys throw a Keychain status error for unexpected statuses instead of returning an empty result.
+
 ## Secure Auth Item Map
 
 `createSecureAuthStorage()` creates a namespaced map of secure string items.
@@ -172,13 +181,16 @@ Recovery depends on the exact stable code:
 
 `isKeychainLockedError()` remains available for compatibility but is
 deprecated. It groups all three codes and must not be used to select retry
-behavior. The package does not block the synchronous JSI call, sleep, or retry
-internally; the application owns lifecycle scheduling and cancellation.
+behavior. The package does not sleep or retry internally; the application owns
+lifecycle scheduling and cancellation. Biometric reads on iOS block the
+synchronous JSI call while the system prompt is visible.
 
-Do not enable `fallbackToCacheOnReadError` for access or refresh tokens unless
-the application explicitly accepts stale or revoked credentials. A cached
-value can hide the distinction between temporary unavailability and credential
-recovery.
+`fallbackToCacheOnReadError` returns the last value read in this process only
+when a read fails with `keychain_locked`. Every other error still throws. Only
+iOS reports `keychain_locked`; Android and web never do, so the fallback has no
+effect there. Do not
+enable it for access or refresh tokens unless the application explicitly
+accepts stale credentials while the device is locked.
 
 ## Android Secure Write Mode
 
@@ -204,13 +216,13 @@ entries, and surfaces native clear failures.
 ## iOS Legacy Disk Migration
 
 Older releases tracked observed Disk keys in `standardUserDefaults`. On iOS,
-adapter initialization copies a valid registry into the Nitro suite domain and
+the first Disk operation copies a valid registry into the Nitro suite domain and
 removes each legacy source only after a target readback and synchronization
 check. `NSUserDefaults` is not transactional, so the migration stops on any
 failed synchronization or readback without deleting the source or registry.
 Malformed registries, same-domain or fallback stores, conflicting target
 values, and failed persistence therefore remain available for recovery. The
-migration is retryable on a later initialization; do not delete the registry
+migration is retryable on a later launch; do not delete the registry
 manually while an upgrade is in progress.
 
 After that cutover, suite string keys are imported into the SQLite WAL Disk
@@ -237,10 +249,12 @@ See [web-backends.md](web-backends.md) for backend contracts and IndexedDB setup
 Before releasing secure-storage changes, run:
 
 ```sh
-bun run test -- --filter=react-native-nitro-storage
-bun run test:cpp -- --filter=react-native-nitro-storage
-(cd packages/react-native-nitro-storage && bun run check:pack)
+bun run test
+bun run test:cpp
+bun run audit:package
 ```
 
+`bun run release:preflight` runs these checks together with the full release gate.
+
 Also run the [physical-device Keychain lifecycle protocol](keychain-lifecycle-testing.md)
 when changing biometric, Keychain, or error-classification behavior.

package/docs/web-backends.md

@@ -4,6 +4,8 @@ Nitro Storage runs on web through synchronous backend contracts. Disk and Secure
 
 The default web backend is localStorage-style. Configure custom backends when you need IndexedDB persistence, tests with isolated storage, cross-tab sync, or a platform-specific secret wrapper.
 
+Register a separate backend instance for each scope. If one instance is registered for both scopes, Disk enumeration skips the `__secure_` and `__bio_` keys that Secure scope writes, and each scope's `clear()` removes only its own keys, but separate stores keep the scopes fully isolated.
+
 ## Backend Contract
 
 ```ts
@@ -102,7 +104,7 @@ The IndexedDB backend exposes `close()` and rejects later synchronous operations
 
 ### Persistence Lifecycle
 
-IndexedDB transactions cannot block a page unload, so in-flight writes may be aborted when the page closes. The backend mitigates this by starting a flush on `pagehide` and on `visibilitychange` (hidden), and `flush()` awaits every pending transaction. When persistence fails, `flush()` throws an error that names the affected keys, and `onError` receives each individual failure.
+IndexedDB transactions cannot block a page unload, so in-flight writes may be aborted when the page closes. The backend does not install `pagehide` or `visibilitychange` handlers, because there is no synchronous way to finish a pending transaction there. `flush()` awaits every pending transaction. When persistence fails, `flush()` throws an error that names the affected keys, and `onError` receives each individual failure.
 
 ```ts
 const backend = await createIndexedDBBackend("app-secure", "keyvalue", {
@@ -119,7 +121,9 @@ Treat IndexedDB persistence as best-effort under abrupt termination: keep a dura
 
 ## Cross-tab Updates
 
-The IndexedDB backend uses `BroadcastChannel` when available. Other tabs receive cache invalidation events and update their in-memory copy.
+The IndexedDB backend uses `BroadcastChannel` when available. Other tabs receive cache invalidation events and update their in-memory copy. Messages that arrive while a new backend is still loading its snapshot are applied after the snapshot, so they are not overwritten.
+
+The window `storage` event updates a scope only while that scope uses the default `localStorage` backend, and only for events from `localStorage`. Custom backends must sync through `subscribe(listener)`.
 
 If you provide your own backend, implement `subscribe(listener)` to keep Nitro Storage caches aligned with external writes.
 

package/indexeddb-backend/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../lib/commonjs/indexeddb-backend.js",
+  "module": "../lib/module/indexeddb-backend.js",
+  "types": "../lib/typescript/indexeddb-backend.d.ts",
+  "sideEffects": false
+}

package/ios/IOSStorageAdapterCpp.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "../core/NativeStorageAdapter.hpp"
+#include <atomic>
 #include <mutex>
 #include <unordered_set>
 
@@ -55,7 +56,10 @@ private:
     std::unordered_set<std::string> secureKeysCache_;
     std::unordered_set<std::string> biometricKeysCache_;
     bool secureKeyCacheHydrated_{false};
+    std::mutex diskMigrationMutex_;
+    std::atomic<bool> diskMigrated_{false};
 
+    void ensureDiskMigrated();
     void ensureSecureKeyCacheHydrated();
     void markSecureKeySet(const std::string& key);
     void markSecureKeyRemoved(const std::string& key);