react-native-nitro-storage 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to this project are documented in this file.
 
 The format follows Keep a Changelog and the project adheres to SemVer.
 
+## 0.9.0 - 2026-08-20
+
+### Breaking changes
+
+- `react-native-nitro-modules` now has a peer range of `>=0.37.0 <0.38.0`.
+  Upgrade Nitro Modules and rebuild the native app before using Nitro Storage
+  0.9.0; the previous 0.36.x range is not supported.
+- `SetStorageItem.get()` now returns `Partial<Record<TMember, true>>`. Use
+  `has()` for membership checks or handle an indexed value as `true | undefined`
+  instead of assuming every member exists.
+
+### Changed
+
+- Regenerated the shipped Nitro bindings with Nitro Modules and Nitrogen 0.37.0
+  while preserving synchronous JSI storage behavior across native platforms.
+- Native batch reads now preserve missing entries as `undefined`, matching the
+  TypeScript contract and allowing stored values that match the old internal
+  sentinel string.
+- The standalone package development and type baseline is now React Native
+  0.87.0. The Expo SDK 57 example remains on its supported React Native 0.86.2
+  baseline.
+
+## 0.8.0 - 2026-08-12
+
+### Breaking changes
+
+- None. `getMetricsSnapshot()` keeps its unscoped, cross-scope aggregate keys.
+  Use the new `getScopedMetricsSnapshot()` when per-scope counters are needed.
+
+### Added
+
+- Exported `PlatformStorage` and `PlatformScope` types from the native, web,
+  and testing entrypoints so shared consumer code can verify platform parity
+  without duplicating the package contract.
+- Added `getScopedMetricsSnapshot()` with keys such as `item:set:1`, without
+  changing established dashboards that consume `getMetricsSnapshot()`.
+
+### Fixed
+
+- **Data-loss prevention:** `storage.import()` now flushes pending coalesced Disk and Secure writes before writing, so a later scheduled flush can never overwrite imported values.
+- **Biometric parity:** promoting a value to biometric storage removes the plain secure copy on iOS and web, matching Android; plain reads can no longer return stale values after promotion.
+- **iOS legacy disk data:** Disk enumeration, size, prefix queries, and clear now cover both the suite domain and legacy `standardUserDefaults` values, so deleted legacy values cannot reappear.
+- **Failure-atomic migrations:** each migration step runs in its own transaction with its version marker; a failed step rolls back its data and marker, and rerunning `migrateToLatest()` retries from the last completed version.
+- **Transaction events:** failed transactions emit exactly one typed `rollback` batch event with pre-rollback and restored raw values.
+- **Atomic memory batch removes:** `removeBatch()` in Memory scope mutates all keys first and emits a single `removeBatch` event.
+- **Stable error classification:** storage error codes now come only from `[nitro-error:<code>]` tags produced by the native and web adapters; message-text scraping was removed and every public code has a producer.
+- **Encoding collisions:** reserved primitive tokens and the native batch missing sentinel are escaped in the stored encoding; legacy reads are preserved and raw API round-trips are unchanged.
+
+### Changed
+
+- `getCapabilities().writeBuffering` now reports real per-mode durability: native Secure writes report buffering only while `setSecureWritesAsync(true)` is active on Android, and web backends report buffering only for IndexedDB-based backends.
+- The IndexedDB backend reports affected keys when `flush()` fails and starts a best-effort flush on `pagehide` and hidden visibility changes.
+- `setIfVersion()` is documented as optimistic (no backend-level atomicity); CAS guarantees are covered by race tests.
+
 ## 0.7.0 - 2026-07-30
 
 ### Changes

package/README.md

@@ -4,9 +4,9 @@
 [![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/)
-[![Expo](https://img.shields.io/badge/expo-SDK%2057-000020)](https://docs.expo.dev/versions/latest/)
-[![Nitro Modules](https://img.shields.io/badge/nitro--modules-0.36.x-black)](https://nitro.margelo.com/)
+[![React Native](https://img.shields.io/badge/react--native-0.87.0-61dafb)](https://reactnative.dev/docs/0.87/getting-started-without-a-framework)
+[![Expo](https://img.shields.io/badge/expo-SDK%2057%20%28RN%200.86.2%29-000020)](https://docs.expo.dev/versions/v57.0.0/)
+[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.37.0%20%3C0.38.0-black)](https://nitro.margelo.com/)
 [![TypeScript](https://img.shields.io/badge/typescript-6.0-3178c6)](https://www.typescriptlang.org/)
 
 Synchronous Memory, Disk, and Secure storage for React Native, Expo development
@@ -26,6 +26,7 @@ pagination, conflict resolution, or remote synchronization.
 - [Install](#install)
 - [Expo Config](#expo-config)
 - [Quick Start](#quick-start)
+- [Auth Tokens](#auth-tokens)
 - [Typed Storage Items](#typed-storage-items)
 - [Item Ergonomics](#item-ergonomics)
 - [Set Items](#set-items)
@@ -57,12 +58,31 @@ Peer dependencies:
 | ---------------------------- | ------------------ |
 | `react`                      | `>=18.2.0`         |
 | `react-native`               | `>=0.75.0`         |
-| `react-native-nitro-modules` | `>=0.36.4 <0.37.0` |
+| `react-native-nitro-modules` | `>=0.37.0 <0.38.0` |
 
-Nitro peer requirement: `react-native-nitro-modules >=0.36.4 <0.37.0`.
+Nitro peer requirement: `react-native-nitro-modules >=0.37.0 <0.38.0`.
 
-Validated example baseline: Expo SDK 57, React Native 0.86.2, React 19.2.3,
-and Nitro Modules 0.36.4.
+The standalone package gate uses React Native `0.87.0` and the Strict
+TypeScript API. The Expo example uses Expo SDK `57.0.15`, React Native
+`0.86.2`, React `19.2.3`, and Nitro Modules `0.37.0`, which is the React Native
+version supported by that Expo SDK. Do not override Expo's React Native version.
+
+When upgrading from 0.8.x, upgrade Nitro Modules to the 0.37.x range before
+installing this package, then rebuild the native app so the generated Nitro
+bindings and native runtime use the same major-minor version:
+
+```sh
+bun add react-native-nitro-modules@0.37.0 react-native-nitro-storage@0.9.0
+bunx expo prebuild
+```
+
+`SetStorageItem.get()` now returns a partial membership map because a member can
+be absent. Use `set.has(member)` for membership checks, or handle an indexed
+value as `true | undefined`; code that assigned the result to
+`Record<string, true>` must update its type.
+
+Nitro Storage requires an Expo development build or a bare React Native app;
+Expo Go and native Windows, macOS, and tvOS targets are not supported.
 
 For Expo development builds:
 
@@ -129,6 +149,40 @@ const theme = themeItem.get();
 const raw = storage.getString("settings:theme", StorageScope.Disk);
 ```
 
+`storage.getString` / `setString` remain the raw API. Prefer typed items for
+application state.
+
+Native storage calls are synchronous JSI operations. Keep values and batches
+small enough for the JavaScript event loop; native and configured web-backend
+failures throw errors. Secure cache fallback is opt-in through
+`fallbackToCacheOnReadError`.
+
+## Auth Tokens
+
+Use `createSecureAuthStorage` for access and refresh tokens. `renameFrom`
+copies a legacy key on first read and deletes it, so you do not need a custom
+migration helper.
+
+```ts
+import { createSecureAuthStorage } from "react-native-nitro-storage";
+
+const auth = createSecureAuthStorage(
+  {
+    accessToken: { renameFrom: "authToken" },
+    refreshToken: { renameFrom: "refreshToken" },
+  },
+  { namespace: "auth", fallbackToCacheOnReadError: true },
+);
+
+auth.accessToken.set("access-token");
+const current = auth.accessToken.get();
+auth.accessToken.subscribe(() => {});
+```
+
+Keep `getString` facades only when the app owns a storage architecture
+boundary. `createSecureAuthStorage` already namespaces keys, notifies
+subscribers, and migrates legacy keys.
+
 ## Typed Storage Items
 
 `createStorageItem<T>()` is the recommended API for application code. It keeps
@@ -183,7 +237,7 @@ const config = diskItem<{ theme: "light" | "dark"; compact: boolean }>({
 });
 
 config.merge({ compact: true }); // shallow object update
-config.reset(); // back to the default value
+config.reset(); // deletes the stored key; the next read returns the default value
 const loginMethod = memoryItem<string | null>({
   key: "loginMethod",
   defaultValue: null,
@@ -194,8 +248,9 @@ loginMethod.setOrDelete(maybeMethod); // null/undefined deletes, value sets
 ## Set Items
 
 `createSetItem()` models set-membership state (seen ids, dismissed prompts)
-without hand-rolling `Record<string, true>` helpers. Adding an existing member
-or deleting an absent one is a no-op, so subscribers do not re-render.
+without hand-rolling membership helpers. Its `get()` result is a partial map,
+because absent members are not stored. Adding an existing member or deleting an
+absent one is a no-op, so subscribers do not re-render.
 
 ```ts
 import { createSetItem, StorageScope } from "react-native-nitro-storage";
@@ -378,7 +433,9 @@ On Android 11 and newer, `BiometricLevel.BiometryOnly` and
 `BiometricLevel.BiometryOrPasscode` use separate Keystore policies. Android 10
 and older support `BiometryOrPasscode`; `BiometryOnly` throws
 `biometric_unavailable` because those releases cannot safely enforce the
-biometric-only distinction. Secure existence, discovery, and cleanup operations
+biometric-only distinction. Promoting a value to biometric storage removes the
+plain secure copy on every platform, so plain reads cannot return a stale
+value. Secure existence, discovery, and cleanup operations
 can also throw when a protected store is locked or its key is invalidated. Catch
 those failures and use `isKeychainLockedError()` when authentication-aware retry
 behavior is appropriate.
@@ -388,6 +445,8 @@ behavior is appropriate.
 `getBatch()` preserves tuple value types, so IDEs infer each result from the
 matching item. `setBatch()` validates every item/value pair independently,
 including heterogeneous batches.
+Missing keys use each item's `defaultValue`; the native bridge preserves missing
+entries as `undefined` while reading the batch.
 
 ```ts
 import { getBatch, removeBatch, setBatch } from "react-native-nitro-storage";
@@ -431,10 +490,15 @@ storage.setMetricsObserver((event) => {
 });
 
 const metrics = storage.getMetricsSnapshot();
+const scopedMetrics = storage.getScopedMetricsSnapshot();
 storage.resetMetrics();
 unsubscribe();
 ```
 
+`getMetricsSnapshot()` aggregates each operation across scopes for backward
+compatibility. `getScopedMetricsSnapshot()` adds the numeric scope suffix for
+per-scope analysis, for example `item:set:1`.
+
 Secure event observer values are redacted by default. Pass
 `{ redactSecureValues: false }` only in trusted debug tooling where raw values
 are safe to inspect.
@@ -484,7 +548,11 @@ migrateFromMMKV(mmkvInstance, themeItem);
 ```
 
 `runTransaction(scope, callback)` rolls back every write made through the `tx`
-context if the callback throws.
+context if the callback throws, then emits one typed `rollback` batch event.
+
+Each migration step runs in its own transaction with its version marker, so a
+failed step leaves the scope on the last completed version and rerunning
+`migrateToLatest()` retries deterministically.
 
 ## Web Backends
 
@@ -495,10 +563,7 @@ import {
 } from "react-native-nitro-storage";
 import { createIndexedDBBackend } from "react-native-nitro-storage/indexeddb-backend";
 
-const backend = await createIndexedDBBackend({
-  dbName: "app-storage",
-  storeName: "kv",
-});
+const backend = await createIndexedDBBackend("app-storage", "kv");
 
 setWebDiskStorageBackend(backend);
 setWebSecureStorageBackend(backend);
@@ -534,12 +599,14 @@ const { storage, memoryItem } = createNitroStorageMock();
 
 ## 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.         |
+| 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 build | Supported with the config plugin.                  |
+| Expo Go                | Not supported for Nitro native modules.            |
+| Windows, macOS, tvOS   | Not supported by this package.                     |
 
 ## Documentation
 

package/SECURITY.md

@@ -6,8 +6,8 @@ Security fixes are shipped for the latest published `0.x` release line.
 
 | Version | Supported |
 | ------- | --------- |
-| `0.5.x` | Yes       |
-| `<0.5`  | No        |
+| `0.8.x` | Yes       |
+| `<0.8`  | No        |
 
 ## Reporting a Vulnerability
 

package/cpp/bindings/HybridStorage.cpp

@@ -14,7 +14,6 @@
 namespace margelo::nitro::NitroStorage {
 
 namespace {
-constexpr auto kBatchMissingSentinel = "__nitro_storage_batch_missing__::v1";
 constexpr int kDefaultBiometricLevel = 2;
 } // namespace
 
@@ -388,8 +387,8 @@ void HybridStorage::setBatch(const std::vector<std::string>& keys, const std::ve
     }
 }
 
-std::vector<std::string> HybridStorage::getBatch(const std::vector<std::string>& keys, double scope) {
-    std::vector<std::string> results;
+std::vector<std::optional<std::string>> HybridStorage::getBatch(const std::vector<std::string>& keys, double scope) {
+    std::vector<std::optional<std::string>> results;
     results.reserve(keys.size());
 
     Scope s = toScope(scope);
@@ -402,7 +401,7 @@ std::vector<std::string> HybridStorage::getBatch(const std::vector<std::string>&
                 if (it != memoryStore_.end()) {
                     results.push_back(it->second);
                 } else {
-                    results.push_back(kBatchMissingSentinel);
+                    results.push_back(std::nullopt);
                 }
             }
             return results;
@@ -418,10 +417,7 @@ std::vector<std::string> HybridStorage::getBatch(const std::vector<std::string>&
                 throw std::runtime_error("NitroStorage: Disk getBatch failed (unknown error)");
             }
 
-            for (const auto& value : values) {
-                results.push_back(value.has_value() ? *value : std::string(kBatchMissingSentinel));
-            }
-            return results;
+            return values;
         }
         case Scope::Secure: {
             ensureAdapter();
@@ -434,10 +430,7 @@ std::vector<std::string> HybridStorage::getBatch(const std::vector<std::string>&
                 throw std::runtime_error("NitroStorage: Secure getBatch failed (unknown error)");
             }
 
-            for (const auto& value : values) {
-                results.push_back(value.has_value() ? *value : std::string(kBatchMissingSentinel));
-            }
-            return results;
+            return values;
         }
     }
 

package/cpp/bindings/HybridStorage.hpp

@@ -39,7 +39,7 @@ public:
     std::vector<std::string> getKeysByPrefix(const std::string& prefix, double scope) override;
     double size(double scope) override;
     void setBatch(const std::vector<std::string>& keys, const std::vector<std::string>& values, double scope) override;
-    std::vector<std::string> getBatch(const std::vector<std::string>& keys, double scope) override;
+    std::vector<std::optional<std::string>> getBatch(const std::vector<std::string>& keys, double scope) override;
     void removeBatch(const std::vector<std::string>& keys, double scope) override;
     void removeByPrefix(const std::string& prefix, double scope) override;
     std::function<void()> addOnChange(

package/docs/api-reference.md

@@ -152,7 +152,7 @@ storage.setEventObserver((event) => {
 
 `setEventObserver()` redacts Secure `oldValue` and `newValue` fields by default. Pass `{ redactSecureValues: false }` only for in-memory debugging paths that never persist logs. Raw `subscribe*()` APIs preserve values for state integrations.
 
-Local batch APIs emit one `type: "batch"` envelope to scope and prefix/namespace listeners. Key subscribers receive the matching per-key change so direct key integrations do not need to unpack batch envelopes. Secure events can include raw secret values; do not log Secure event payloads in production.
+Local batch APIs emit one `type: "batch"` envelope to scope and prefix/namespace listeners. Key subscribers receive the matching per-key change so direct key integrations do not need to unpack batch envelopes. Failed transactions emit one batch envelope with `operation: "rollback"` whose changes carry the pre-rollback and restored raw values. Secure events can include raw secret values; do not log Secure event payloads in production.
 
 ## Batch Operations
 
@@ -280,5 +280,15 @@ Common public types:
 - `WebSecureStorageBackend`
 - `WebStorageChangeEvent`
 - `WebStorageScope`
+- `PlatformStorage`
+- `PlatformScope`
+- `WebBackendCapabilities`
+
+`getCapabilities().writeBuffering` describes real per-mode durability:
+
+- Native: Disk writes are buffered by the platform (`SharedPreferences.apply()` on Android, `NSUserDefaults` on iOS). Secure writes are buffered only when `setSecureWritesAsync(true)` is active on Android; iOS Keychain writes are synchronous.
+- Web: buffering follows the configured backend; IndexedDB backends are buffered, localStorage backends are synchronous.
+
+`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`.

package/docs/batch-transactions-migrations.md

@@ -80,7 +80,7 @@ const snapshot = storage.export(StorageScope.Disk);
 storage.import(snapshot, StorageScope.Disk);
 ```
 
-For Memory scope, import is atomic: all keys are written before listeners fire. For Disk and Secure, import delegates to native or web batch paths.
+For Memory scope, import is atomic: all keys are written before listeners fire. Disk and Secure imports flush pending coalesced writes first, so the imported snapshot cannot be overwritten by an earlier pending flush, then delegate to native or web batch paths.
 
 Secure exports contain raw secret values. `storage.export(StorageScope.Secure)` requires `{ includeSecureValues: true }`; `storage.exportSecureUnsafe()` is the explicit equivalent. Do not log Secure exports or include them in diagnostics, analytics, crash reports, or support bundles.
 
@@ -124,7 +124,9 @@ Transaction context methods:
 - `setItem(item, value)`
 - `removeItem(item)`
 
-If the callback throws, Nitro Storage restores the keys it changed during that transaction.
+If the callback throws, Nitro Storage restores the keys it changed during that transaction and emits exactly one typed `rollback` batch event so observers and the global event observer can react to the rollback.
+
+Memory-scope batch removes are atomic: all keys are deleted before listeners fire, and scope, key, and prefix subscribers receive a single `removeBatch` event.
 
 ## Migrations
 
@@ -157,6 +159,8 @@ migrateToLatest(StorageScope.Disk);
 
 Migration context methods work with raw strings. Use item serializers manually when migrating structured data.
 
+Each migration step runs inside its own transaction together with the version marker write. A step that throws rolls back both its data changes and the version marker, so the scope stays on the last completed version and rerunning `migrateToLatest()` retries deterministically.
+
 ```ts
 registerMigration(3, (ctx) => {
   const raw = ctx.getRaw("settings");
@@ -198,3 +202,5 @@ const didWrite = themeItem.setIfVersion(
 ```
 
 `setIfVersion()` returns `false` if another write changed the item after `getWithVersion()`.
+
+Compare-and-set is optimistic: the version is read, compared, and written without backend-level atomicity. Two writers on different runtimes can both pass the check between their reads and writes, so use it for single-runtime coordination or last-writer-wins-tolerant flows. There is no native compare-and-swap primitive.

package/docs/benchmarks.md

@@ -2,36 +2,40 @@
 
 Benchmarks are release checks, not product promises. Use them to catch regressions on the local machine and CI image used by this repo.
 
-Run:
+Run from the repo root:
 
 ```sh
-bun run benchmark -- --filter=react-native-nitro-storage
+bun run build
+bun run benchmark
 ```
 
-The benchmark script checks representative synchronous read/write paths and fails when results drift beyond the configured threshold.
+## Scope: Web Only
+
+`benchmark` loads `lib/commonjs/index.web.js` and measures the web entry against the localStorage backend. The `disk:` and `secure:` labels describe web scopes, not native Disk or Secure storage.
+
+Native Disk/Secure baselines require a device or simulator run and are not part of this gate. Do not compare these numbers against native storage.
 
 ## Interpreting Results
 
 - Compare results on the same machine and Node/Bun version.
-- Treat large deltas as a prompt to inspect recent storage-runtime, serialization, native bridge, or cache changes.
+- Treat large deltas as a prompt to inspect recent storage-runtime, serialization, cache, or event changes.
 - Do not compare web backend numbers against native secure storage numbers; they measure different systems.
-- Secure storage performance depends on platform state, device lock state, biometric prompts, and Keystore/Keychain behavior.
 
 ## Release Checklist
 
 Before publishing:
 
 ```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:cpp -- --filter=react-native-nitro-storage
-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)
-npm publish --dry-run
+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
 ```
 
 Keep the dry-publish output in the release notes when validating a version locally.

package/docs/web-backends.md

@@ -38,7 +38,7 @@ Optional methods improve performance and observability:
 
 `subscribe(listener)` should report `{ key, newValue }` changes. Use `key: null` when the whole backend is cleared.
 
-`close()` should release backend-owned resources such as database handles or broadcast channels. Nitro Storage calls it when a configured Disk or Secure backend is replaced.
+`close()` should release backend-owned resources such as database handles or broadcast channels. A replaced backend is retired instead of closed on the spot: `flushWebStorageBackends()` flushes it and then closes it, so queued async writes can commit before the connection goes away. Backends without `flush()` are closed immediately on replacement, and a retired backend whose flush fails stays retired for a later explicit retry.
 
 ## Disk Backend
 
@@ -100,6 +100,23 @@ Reads are synchronous because they are served from memory after initial load. Wr
 
 The IndexedDB backend exposes `close()` and rejects later synchronous operations after it is closed.
 
+### 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.
+
+```ts
+const backend = await createIndexedDBBackend("app-secure", "keyvalue", {
+  onError: (error) => {
+    console.error("IndexedDB secure storage failed", error);
+  },
+});
+
+// Before assertions, navigation, or lifecycle boundaries:
+await flushWebStorageBackends();
+```
+
+Treat IndexedDB persistence as best-effort under abrupt termination: keep a durable copy of critical values elsewhere if they must survive an immediate page close.
+
 ## Cross-tab Updates
 
 The IndexedDB backend uses `BroadcastChannel` when available. Other tabs receive cache invalidation events and update their in-memory copy.