react-native-nitro-storage 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -2,9 +2,51 @@
 
 All notable changes to this project are documented in this file.
 
-The format follows Keep a Changelog and the project adheres to SemVer.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Breaking changes are always listed first in each release section.
 
-## 0.9.0 - 2026-08-20
+## [0.10.0] - 2026-08-25
+
+### Breaking changes
+
+- None when upgrading from `0.9.x`. Direct upgrades from `0.8.x` or earlier
+  still require Nitro Modules `0.37.x` and a native rebuild as described in
+  the `0.9.0` entry. This release restores the previous set-item type and
+  secure-write defaults for existing consumers.
+
+### Added
+
+- Added `isStorageError(error, code)` to select recovery behavior from an exact
+  stable storage error code on native and web.
+
+### Changed
+
+- Restored `SetStorageItem.get()` and its `item` property to the original
+  `Record<string, true>` compatibility shape. Added `getTyped()` for new code
+  that wants `Partial<Record<TMember, true>>` without forcing a type migration.
+- Restored synchronous Android Secure writes by default. Asynchronous
+  `apply()` writes remain available through the explicit
+  `storage.setSecureWritesAsync(true)` opt-in and can be drained with
+  `storage.flushSecureWrites()`.
+- Enabled raw read-cache lookups now reuse cached missing values in single and
+  batch reads without per-item fallback calls.
+
+### Deprecated
+
+- Deprecated `isKeychainLockedError()`. It remains backward compatible but
+  groups `keychain_locked`, `authentication_required`, and `key_invalidated`;
+  use `isStorageError()` when deciding whether to retry, authenticate, or
+  rebuild a credential.
+
+### Documentation
+
+- Documented secure-storage recovery semantics and warned against cached
+  fallback for authentication tokens unless stale credentials are an explicit
+  application policy.
+- Clarified isolated web benchmark limits and corrected capability/API examples.
+
+## [0.9.0] - 2026-08-20
 
 ### Breaking changes
 
@@ -14,6 +56,10 @@ The format follows Keep a Changelog and the project adheres to SemVer.
 - `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.
+- Android Secure writes now default to asynchronous `apply()`. Call
+  `storage.setSecureWritesAsync(false)` when existing code depends on
+  synchronous `commit()` durability, or call `storage.flushSecureWrites()` at
+  deterministic persistence boundaries.
 
 ### Changed
 
@@ -22,11 +68,25 @@ The format follows Keep a Changelog and the project adheres to SemVer.
 - 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.
+- Secure write flushes now retain failed and unattempted last-write-wins entries
+  for retry instead of silently dropping them.
+- iOS legacy Disk migration is conservative and retryable. A valid registry is
+  copied into the suite domain and each `standardUserDefaults` source is
+  removed only after target persistence is verified; malformed registries,
+  fallback or same-domain stores, conflicts, and failed persistence leave the
+  source and registry available for recovery.
+
+### Fixed
+
+- `storage.clearBiometric()` flushes pending Secure writes, clears the JS raw
+  cache before listener notification, uses a durable Android biometric clear,
+  surfaces failures, and emits the same Secure-scope `clear` event as a Secure
+  clear after success.
+- Android biometric corruption is checked and recovered at preference-store
+  initialization instead of probing the full encrypted store on each
+  existence or deletion hot path.
 
-## 0.8.0 - 2026-08-12
+## [0.8.0] - 2026-08-12
 
 ### Breaking changes
 
@@ -58,7 +118,7 @@ The format follows Keep a Changelog and the project adheres to SemVer.
 - 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
+## [0.7.0] - 2026-07-30
 
 ### Changes
 
@@ -69,7 +129,7 @@ The format follows Keep a Changelog and the project adheres to SemVer.
 - Enforce Android biometric policy levels with distinct Keystore keys, propagate locked or invalidated biometric failures, and keep secure preference files excluded from backup.
 - Preflight biometric store access before aggregate secure mutations and surface native commit or corruption-recovery failures.
 
-## 0.6.0 - 2026-06-15
+## [0.6.0] - 2026-06-15
 
 ### Added
 
@@ -97,7 +157,7 @@ type changes can affect advanced consumers:
 - `StorageChangeOperation` gained the `"expire"` and `"clearGroup"` members. Exhaustive `switch` statements over a change event's `operation` need cases for the new members.
 - `useStorage()` now returns a three-element tuple `[value, setter, actions]` (was two). Array destructuring such as `const [value, setStore] = useStorage(item)` is unaffected; only code that annotated the result with an explicit two-element tuple type needs to widen the annotation.
 
-## 0.5.9 - 2026-06-11
+## [0.5.9] - 2026-06-11
 
 ### Fixed
 
@@ -108,7 +168,7 @@ type changes can affect advanced consumers:
 
 - Included `CHANGELOG.md` in the packed package docs.
 
-## 0.5.8 - 2026-06-11
+## [0.5.8] - 2026-06-11
 
 ### Changed
 
@@ -119,7 +179,7 @@ type changes can affect advanced consumers:
 
 - Regenerate Nitrogen output and package build artifacts before pack-content audits so clean release and CI environments validate the actual published tarball.
 
-## 0.5.7 - 2026-06-10
+## [0.5.7] - 2026-06-10
 
 ### Added
 
@@ -137,7 +197,7 @@ type changes can affect advanced consumers:
 - Keep native and web public TypeScript entrypoints aligned so IDEs infer storage setters and batch tuple results consistently across React Native and web imports.
 - Keep the README, issue template, package metadata, and release notes aligned with the current `0.5.7` package surface.
 
-## 0.5.6 - 2026-05-22
+## [0.5.6] - 2026-05-22
 
 ### Added
 
@@ -159,7 +219,7 @@ type changes can affect advanced consumers:
 - Remove package-owned Android native log spam for expected unavailable biometric storage paths.
 - Modernize Android Gradle assignment syntax to avoid package-owned Gradle warnings.
 
-## 0.5.4 - 2026-05-13
+## [0.5.4] - 2026-05-13
 
 ### Fixed
 
@@ -170,7 +230,7 @@ type changes can affect advanced consumers:
 - Publish GitHub Releases to npm through a Trusted Publishing/OIDC workflow.
 - Resolve the package build's TypeScript binary lookup warning during release checks.
 
-## 0.5.2 - 2026-04-27
+## [0.5.2] - 2026-04-27
 
 ### Fixed
 
@@ -178,7 +238,7 @@ type changes can affect advanced consumers:
 - Stabilize the release benchmark gate by sampling each benchmark three times while keeping the same regression thresholds.
 - Correct package content check commands in the release documentation for current Bun.
 
-## 0.5.1 - 2026-04-24
+## [0.5.1] - 2026-04-24
 
 ### Added
 
@@ -196,7 +256,7 @@ type changes can affect advanced consumers:
 - Document raw import/export workflows and warn that Secure exports expose secret values.
 - Refactor the publish script to validate release docs, report check timings, support coverage gates, and avoid redundant pack dry-runs.
 
-## 0.5.0 - 2026-04-18
+## [0.5.0] - 2026-04-18
 
 ### Added
 
@@ -213,7 +273,7 @@ type changes can affect advanced consumers:
 - Expand npm package description and keywords around React Native secure storage, biometric storage, Keychain, Android Keystore, Nitro Modules, MMKV migration, Expo SecureStore, Zustand/Jotai, and IndexedDB.
 - Harden publish dry-runs, package docs syncing, and npm pack content validation.
 
-## 0.4.5 - 2026-04-14
+## [0.4.5] - 2026-04-14
 
 ### Added
 
@@ -258,7 +318,7 @@ type changes can affect advanced consumers:
 - Fix web `import()` for Secure scope skipping `flushSecureWrites()` and `setSecureAccessControl()` before writing.
 - Expand ProGuard/R8 keep rules with explicit method-signature patterns so JNI-callable methods survive aggressive R8 shrinking in release builds.
 
-## 0.4.1 - 2026-03-04
+## [0.4.1] - 2026-03-04
 
 ### Added
 
@@ -277,7 +337,7 @@ type changes can affect advanced consumers:
 - Bump to **React 19.2.0** and **React Native 0.83.2** across workspace and example.
 - Add `--provenance` flag to `npm publish` for npm supply-chain attestation.
 
-## 0.4.0 - 2026-02-25
+## [0.4.0] - 2026-02-25
 
 ### Added
 
@@ -297,7 +357,7 @@ type changes can affect advanced consumers:
 - Keep iOS secure keychain cache/index behavior aligned with new prefix query and biometric-level paths.
 - Expand README/API docs to cover the new public API surface with concrete TypeScript use-case snippets.
 
-## 0.3.2 - 2026-02-22
+## [0.3.2] - 2026-02-22
 
 ### Added
 
@@ -320,7 +380,7 @@ type changes can affect advanced consumers:
 - Expand benchmark coverage to include Disk and Secure scope throughput checks and tighten regression thresholds.
 - Expand README coverage so every public feature has a concrete TypeScript use-case example, including secure write flush, biometric/access-control usage, batch bootstrap, and storage utility workflows.
 
-## 0.3.1 - 2026-02-16
+## [0.3.1] - 2026-02-16
 
 ### Changed
 
@@ -337,7 +397,7 @@ type changes can affect advanced consumers:
 - Fix global `storage.setAccessControl(...)` handling so non-item raw secure writes keep the configured level instead of being forced back to default.
 - Fix Android secure key enumeration to return deduplicated key sets when secure and biometric stores share key names.
 
-## 0.3.0 - 2026-02-15
+## [0.3.0] - 2026-02-15
 
 ### Added
 
@@ -354,7 +414,7 @@ type changes can affect advanced consumers:
 - Route native batch calls through true adapter-level batch APIs (HybridStorage + iOS/Android adapters) instead of per-key loops.
 - Add read-through cache invalidation on scoped/key change events and native/web clear paths.
 
-## 0.2.1 - 2026-02-15
+## [0.2.1] - 2026-02-15
 
 ### Added
 
@@ -375,7 +435,7 @@ type changes can affect advanced consumers:
 
 - Raise `react` peer dependency floor to `>=18.2.0`.
 
-## 0.2.0 - 2026-02-15
+## [0.2.0] - 2026-02-15
 
 ### Added
 
@@ -398,7 +458,7 @@ type changes can affect advanced consumers:
 - Expand README with complete API behavior/throws documentation.
 - Strengthen native and web test coverage for validation, TTL, migrations, and transactions.
 
-## 0.1.4 - 2026-02-09
+## [0.1.4] - 2026-02-09
 
 ### Added
 
@@ -412,13 +472,13 @@ type changes can affect advanced consumers:
 
 - Bump react-native-nitro-modules to the latest version and raise the peer dependency floor.
 
-## 0.1.3 - 2026-01-22
+## [0.1.3] - 2026-01-22
 
 ### Fixed
 
 - Prevent ProGuard from stripping the JNI class in release builds.
 
-## 0.1.2 - 2026-01-07
+## [0.1.2] - 2026-01-07
 
 ### Added
 
@@ -429,7 +489,7 @@ type changes can affect advanced consumers:
 
 - Point types to the correct path and simplify bob targets.
 
-## 0.1.1 - 2025-12-15
+## [0.1.1] - 2025-12-15
 
 ### Added
 
@@ -442,7 +502,7 @@ type changes can affect advanced consumers:
 - Update README screenshots.
 - Add tests for memory item deletion and MMKV migration, and simplify the README.
 
-## 0.1.0 - 2025-12-15
+## [0.1.0] - 2025-12-15
 
 ### Added
 

package/README.md

@@ -4,7 +4,7 @@
 [![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-0.87.0-61dafb)](https://reactnative.dev/docs/0.87/getting-started-without-a-framework)
+[![React Native](https://img.shields.io/badge/react--native-0.86.2-61dafb)](https://reactnative.dev/docs/0.86/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/)
@@ -24,6 +24,7 @@ pagination, conflict resolution, or remote synchronization.
 ## Contents
 
 - [Install](#install)
+- [Requirements and compatibility](#requirements-and-compatibility)
 - [Expo Config](#expo-config)
 - [Quick Start](#quick-start)
 - [Auth Tokens](#auth-tokens)
@@ -52,6 +53,8 @@ pagination, conflict resolution, or remote synchronization.
 bun add react-native-nitro-storage react-native-nitro-modules
 ```
 
+## Requirements and compatibility
+
 Peer dependencies:
 
 | Package                      | Version            |
@@ -62,24 +65,26 @@ Peer dependencies:
 
 Nitro peer requirement: `react-native-nitro-modules >=0.37.0 <0.38.0`.
 
-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
+The package gate uses React Native `0.86.2` and the Strict TypeScript API.
+`check:ci` also compiles the public source against React Native `0.87.0`'s
+Strict TypeScript API; this does not change the runtime baseline. The Expo
+example uses Expo SDK `57.0.16`, 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:
+When upgrading from 0.8.x or 0.9.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
+bun add react-native-nitro-modules@0.37.0 react-native-nitro-storage@0.10.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.
+`SetStorageItem.get()` retains its original `Record<string, true>` compatibility
+shape. At runtime, absent members are still absent, so use `set.has(member)` for
+membership checks. New code that wants a precise member union can use
+`set.getTyped()`, which returns `Partial<Record<TMember, true>>`.
 
 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.
@@ -171,7 +176,7 @@ const auth = createSecureAuthStorage(
     accessToken: { renameFrom: "authToken" },
     refreshToken: { renameFrom: "refreshToken" },
   },
-  { namespace: "auth", fallbackToCacheOnReadError: true },
+  { namespace: "auth" },
 );
 
 auth.accessToken.set("access-token");
@@ -183,6 +188,11 @@ Keep `getString` facades only when the app owns a storage architecture
 boundary. `createSecureAuthStorage` already namespaces keys, notifies
 subscribers, and migrates legacy keys.
 
+Do not enable `fallbackToCacheOnReadError` for access or refresh tokens unless
+the application explicitly accepts stale or revoked credentials. Handle
+temporary secure-storage errors and retry from application lifecycle state
+instead.
+
 ## Typed Storage Items
 
 `createStorageItem<T>()` is the recommended API for application code. It keeps
@@ -248,9 +258,11 @@ loginMethod.setOrDelete(maybeMethod); // null/undefined deletes, value sets
 ## Set Items
 
 `createSetItem()` models set-membership state (seen ids, dismissed prompts)
-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.
+without hand-rolling membership helpers. Its compatibility `get()` result is a
+`Record<string, true>`; absent members are still not stored at runtime. Use
+`getTyped()` when a precise `Partial<Record<TMember, true>>` result is useful.
+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";
@@ -386,7 +398,7 @@ import {
   StorageScope,
   createSecureAuthStorage,
   createStorageItem,
-  isKeychainLockedError,
+  isStorageError,
   storage,
 } from "react-native-nitro-storage";
 
@@ -417,7 +429,7 @@ const auth = createSecureAuthStorage({
 try {
   recoveryCode.get();
 } catch (error) {
-  if (isKeychainLockedError(error)) {
+  if (isStorageError(error, "keychain_locked")) {
     storage.getSecurityCapabilities();
   }
 }
@@ -429,6 +441,15 @@ 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 }`.
 
+Android secure writes default to synchronous `commit()` durability. Call
+`storage.setSecureWritesAsync(true)` only when asynchronous `apply()` writes are
+acceptable. After opting into async writes, call `storage.flushSecureWrites()`
+before a deterministic persistence boundary. A failed secure flush throws and
+keeps failed or unattempted queued writes available for retry.
+`storage.clearBiometric()`
+flushes pending Secure writes before clearing biometric entries and surfaces
+native clear failures.
+
 On Android 11 and newer, `BiometricLevel.BiometryOnly` and
 `BiometricLevel.BiometryOrPasscode` use separate Keystore policies. Android 10
 and older support `BiometryOrPasscode`; `BiometryOnly` throws
@@ -436,9 +457,11 @@ and older support `BiometryOrPasscode`; `BiometryOnly` throws
 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.
+can also throw when a protected store is locked or its key is invalidated. Use
+`isStorageError()` to choose the correct recovery path: retry
+`keychain_locked` after unlock, request user interaction for
+`authentication_required`, and rebuild the affected credential for
+`key_invalidated`.
 
 ## Batch Operations
 
@@ -446,7 +469,9 @@ behavior is appropriate.
 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.
+entries as `undefined` while reading the batch. With `readCache: true`, item and
+batch reads reuse raw cache entries, including cached missing values, until a
+write, delete, clear, or external change invalidates the entry.
 
 ```ts
 import { getBatch, removeBatch, setBatch } from "react-native-nitro-storage";
@@ -569,6 +594,11 @@ setWebDiskStorageBackend(backend);
 setWebSecureStorageBackend(backend);
 ```
 
+Web reads and mutations stay synchronous against the backend's in-memory
+contract; use `flushWebStorageBackends()` for asynchronous persistence
+boundaries. The native entry keeps the web backend setters, getters, and flush
+function as typed no-ops for cross-platform code.
+
 Browser storage cannot provide iOS Keychain or Android Keystore guarantees. Web
 Secure scope is only as strong as the backend you configure.
 
@@ -597,6 +627,28 @@ beforeEach(() => {
 const { storage, memoryItem } = createNitroStorageMock();
 ```
 
+## API
+
+The package exposes named `storage`, `createStorageItem`, the scoped item
+factories, `createSetItem`, batch operations, migration and transaction helpers,
+secure-auth storage, React hooks, and web backend utilities. Values are bound to
+`Memory`, `Disk`, or `Secure` and support typed single-key operations, raw
+inspection, events and observers, cache and write-flush controls, secure
+metadata, transactional migrations with rename/rollback, and configurable web
+backends. The full reference lives in
+[docs/api-reference.md](docs/api-reference.md).
+
+## Error Contract
+
+Native and web adapters tag classified failures with stable error codes. Use
+`getStorageErrorCode(error)` or `isStorageError(error, code)` to branch on them:
+`keychain_locked` reports a locked Keychain that a retry can recover after
+authentication, secure-scope write or biometric failures carry their own
+codes, and invalid inputs (bad scope, malformed keys, numeric guard
+violations) are rejected before reaching native storage. Errors never swallow
+the underlying cause silently: the original platform message is preserved on
+the error for diagnostics.
+
 ## Platform Support
 
 | Platform               | Status                                             |
@@ -650,9 +702,14 @@ bun run example:android
 bun run example:ios
 ```
 
-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.
+Run native example builds locally before release when changing plugin, native,
+Nitro, secure storage, or packaging files. GitHub CI does not build the Android
+or iOS example. The package release path also validates package contents and
+dry-run publish behavior.
+
+`bun run benchmark` measures only the built web entry with an isolated private
+localStorage implementation; it is not a native Disk or Secure benchmark. See
+[docs/benchmarks.md](docs/benchmarks.md) for sampling and interpretation limits.
 
 ## License
 

package/android/src/main/cpp/AndroidStorageAdapterCpp.cpp

@@ -40,8 +40,11 @@ std::vector<std::string> fromJavaStringArray(alias_ref<JavaStringArray> values)
     result.reserve(size);
     for (jsize i = 0; i < size; ++i) {
         auto currentValue = values->getElement(i);
-        // Preserve null as empty string to maintain index alignment with caller
-        result.push_back(currentValue ? currentValue->toStdString() : std::string());
+        // Null entries are dropped so a missing key can never surface as the
+        // empty-string clear sentinel used by change listeners.
+        if (currentValue) {
+            result.push_back(currentValue->toStdString());
+        }
     }
     return result;
 }