react-native-nitro-storage 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -2,9 +2,91 @@
 
 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.8.0 - 2026-08-12
+## [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
+
+- `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.
+- 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
+
+- 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.
+- 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
 
 ### Breaking changes
 
@@ -36,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
 
@@ -47,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
 
@@ -75,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
 
@@ -86,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
 
@@ -97,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
 
@@ -115,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
 
@@ -137,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
 
@@ -148,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
 
@@ -156,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
 
@@ -174,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
 
@@ -191,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
 
@@ -236,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
 
@@ -255,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
 
@@ -275,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
 
@@ -298,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
 
@@ -315,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
 
@@ -332,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
 
@@ -353,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
 
@@ -376,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
 
@@ -390,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
 
@@ -407,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
 
@@ -420,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,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/docs/0.86/getting-started-without-a-framework)
-[![Expo](https://img.shields.io/badge/expo-SDK%2057-000020)](https://docs.expo.dev/versions/v57.0.0/)
-[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.36.5%20%3C0.37.0-black)](https://nitro.margelo.com/)
+[![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/)
 
 Synchronous Memory, Disk, and Secure storage for React Native, Expo development
@@ -24,8 +24,10 @@ 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)
 - [Typed Storage Items](#typed-storage-items)
 - [Item Ergonomics](#item-ergonomics)
 - [Set Items](#set-items)
@@ -51,18 +53,41 @@ pagination, conflict resolution, or remote synchronization.
 bun add react-native-nitro-storage react-native-nitro-modules
 ```
 
+## Requirements and compatibility
+
 Peer dependencies:
 
 | Package                      | Version            |
 | ---------------------------- | ------------------ |
 | `react`                      | `>=18.2.0`         |
 | `react-native`               | `>=0.75.0`         |
-| `react-native-nitro-modules` | `>=0.36.5 <0.37.0` |
+| `react-native-nitro-modules` | `>=0.37.0 <0.38.0` |
+
+Nitro peer requirement: `react-native-nitro-modules >=0.37.0 <0.38.0`.
 
-Nitro peer requirement: `react-native-nitro-modules >=0.36.5 <0.37.0`.
+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.
 
-Validated example baseline: Expo SDK 57, React Native 0.86.2, React 19.2.3,
-and Nitro Modules 0.36.5.
+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.10.0
+bunx expo prebuild
+```
+
+`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.
 
 For Expo development builds:
 
@@ -129,6 +154,45 @@ 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" },
+);
+
+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.
+
+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
@@ -194,8 +258,11 @@ 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 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";
@@ -331,7 +398,7 @@ import {
   StorageScope,
   createSecureAuthStorage,
   createStorageItem,
-  isKeychainLockedError,
+  isStorageError,
   storage,
 } from "react-native-nitro-storage";
 
@@ -362,7 +429,7 @@ const auth = createSecureAuthStorage({
 try {
   recoveryCode.get();
 } catch (error) {
-  if (isKeychainLockedError(error)) {
+  if (isStorageError(error, "keychain_locked")) {
     storage.getSecurityCapabilities();
   }
 }
@@ -374,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
@@ -381,15 +457,21 @@ 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
 
 `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. 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";
@@ -506,15 +588,17 @@ 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);
 ```
 
+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.
 
@@ -543,14 +627,38 @@ 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                                             |
-| -------- | -------------------------------------------------- |
-| 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
 
@@ -594,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;
 }