react-native-nitro-storage 0.5.9 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to this project are documented in this file.
 
 The format follows Keep a Changelog and the project adheres to SemVer.
 
+## 0.7.0 - 2026-07-30
+
+### Changes
+
+- **Breaking change:** Android secure key discovery, existence checks, and cleanup now surface locked, unavailable, or invalidated biometric-store errors instead of treating inaccessible protected values as absent. Catch storage errors around these operations and use `isKeychainLockedError()` when retrying after device authentication is appropriate.
+- Upgrade the validated package baseline to Expo SDK 57, React Native 0.86.2, and Nitro Modules/Nitrogen 0.36.4.
+- Preserve each item/value relationship in heterogeneous `setBatch()` calls so TypeScript rejects values assigned to the wrong storage item.
+- Serialize native key-index hydration with concurrent mutations so `has`, `size`, and key queries cannot remain stale after a racing write.
+- 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
+
+### Added
+
+- Object-state ergonomics on `StorageItem<T>`: `item.merge(partial)` for shallow object updates, `item.reset()` to return to the default value, and `item.setOrDelete(value)` which deletes on `null`/`undefined` and sets otherwise.
+- Scoped item factories `memoryItem`, `diskItem`, and `secureItem` so call sites no longer repeat `scope: StorageScope.X`.
+- `createSetItem()` for set-membership state backed by storage, with `add`/`delete`/`has`/`toggle`/`values`/`size`/`clear`/`reset` and no-op-safe writes (no event/render churn when adding an existing member or deleting an absent one).
+- Lifecycle helpers: `storage.clear(scope, { except })` to wipe a scope while preserving listed keys/items, per-item `group` config plus `storage.clearGroup(group)` and `storage.getGroupItems(group)` (which compose for "clear all except a group").
+- Declarative legacy migration: `renameFrom` on items (and per-key on `createSecureAuthStorage`) copies a legacy key to the new key on first read and removes the legacy entry. `createSecureAuthStorage` also accepts `group` and `fallbackToCacheOnReadError`.
+- Secure read resilience: `fallbackToCacheOnReadError` returns the last cached value when a secure read throws a locked-keychain error, plus an `onReadError` hook.
+- Global expiration events: TTL expiry now emits a `"expire"` change event (memory and disk) routed through the event bus, with `storage.subscribeExpired(scope, listener)`.
+- Hook ergonomics: `useStorage` now returns a third, render-stable `actions` element (`set`/`merge`/`reset`/`remove`/`setOrDelete`); new `useStorageValue` (read-only) and `useStorageActions` hooks.
+- Dev introspection: `storage.findDuplicateKeys()` and `storage.getRegisteredKeys()` to audit accidental `(scope, key)` collisions at startup.
+- New `react-native-nitro-storage/testing` entrypoint: a faithful in-memory implementation of the full public surface plus `createNitroStorageMock()` and `resetNitroStorageMock()` for Jest/Storybook without native modules.
+
+### Changed
+
+- Faster writes when nothing is subscribed: the native write/notify path now takes a lock-free fast path (per-scope atomic listener counts) and skips locking and copying the listener vector when a scope has no listeners. Applies to both iOS and Android via the shared C++ `HybridStorage`, and is thread-safe (verified under the C++ AddressSanitizer, ThreadSanitizer, and UndefinedBehaviorSanitizer suites).
+
+### Breaking Changes
+
+All new APIs are additive — existing code keeps working. These behavior and
+type changes can affect advanced consumers:
+
+- TTL expiry now emits a `"expire"` change event instead of `"remove"`. Previously, a disk/secure value expiring on read emitted `operation: "remove"` and an expiring memory value emitted no event at all. If you subscribe to storage events and branch on `operation === "remove"` to detect expiry, also handle `"expire"` (or use the new `storage.subscribeExpired()`).
+- `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
 
 ### Fixed

package/README.md

@@ -5,8 +5,8 @@
 [![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%2056-000020)](https://docs.expo.dev/)
-[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.35.7-black)](https://nitro.margelo.com/)
+[![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/)
 [![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
@@ -27,6 +27,10 @@ pagination, conflict resolution, or remote synchronization.
 - [Expo Config](#expo-config)
 - [Quick Start](#quick-start)
 - [Typed Storage Items](#typed-storage-items)
+- [Item Ergonomics](#item-ergonomics)
+- [Set Items](#set-items)
+- [Groups And Lifecycle](#groups-and-lifecycle)
+- [Legacy Key Migration And Secure Resilience](#legacy-key-migration-and-secure-resilience)
 - [React Hooks](#react-hooks)
 - [Storage Scopes](#storage-scopes)
 - [Secure Storage](#secure-storage)
@@ -34,10 +38,12 @@ pagination, conflict resolution, or remote synchronization.
 - [Events And Observability](#events-and-observability)
 - [Migrations And Transactions](#migrations-and-transactions)
 - [Web Backends](#web-backends)
+- [Testing](#testing)
 - [Platform Support](#platform-support)
 - [Documentation](#documentation)
 - [Troubleshooting](#troubleshooting)
 - [Development](#development)
+- [License](#license)
 
 ## Install
 
@@ -47,13 +53,16 @@ bun add react-native-nitro-storage react-native-nitro-modules
 
 Peer dependencies:
 
-| Package                      | Version    |
-| ---------------------------- | ---------- |
-| `react`                      | `>=18.2.0` |
-| `react-native`               | `>=0.75.0` |
-| `react-native-nitro-modules` | `>=0.35.7` |
+| Package                      | Version            |
+| ---------------------------- | ------------------ |
+| `react`                      | `>=18.2.0`         |
+| `react-native`               | `>=0.75.0`         |
+| `react-native-nitro-modules` | `>=0.36.4 <0.37.0` |
 
-Nitro peer requirement: `react-native-nitro-modules >=0.35.7`.
+Nitro peer requirement: `react-native-nitro-modules >=0.36.4 <0.37.0`.
+
+Validated example baseline: Expo SDK 57, React Native 0.86.2, React 19.2.3,
+and Nitro Modules 0.36.4.
 
 For Expo development builds:
 
@@ -153,9 +162,108 @@ const didWrite = preferencesItem.setIfVersion(snapshot.version, {
 });
 ```
 
-The package exports `StorageItem`, `StorageItemConfig`, `StorageSetter`,
-`VersionedValue`, `StorageBatchSetItem`, web backend types, event types, secure
-metadata types, and capability types for IDE-safe integrations.
+The package ships its own TypeScript types, so editors and AI tools catch
+mistakes before they reach the runtime. It exports `StorageItem`,
+`StorageItemConfig`, `StorageSetter`, `StorageActions`, `VersionedValue`,
+`StorageBatchSetItem`, `StorageClearOptions`, `StorageKeyRef`, `SetItemConfig`,
+`SetStorageItem`, plus web backend, event, secure-metadata, and capability types.
+
+## Item Ergonomics
+
+`merge`, `reset`, and `setOrDelete` cover the most common object-state edits
+without re-reading or hand-writing compare-and-swap loops. Scoped factories
+(`memoryItem`, `diskItem`, `secureItem`) drop the repeated `scope` field.
+
+```ts
+import { diskItem, memoryItem } from "react-native-nitro-storage";
+
+const config = diskItem<{ theme: "light" | "dark"; compact: boolean }>({
+  key: "config",
+  defaultValue: { theme: "light", compact: false },
+});
+
+config.merge({ compact: true }); // shallow object update
+config.reset(); // back to the default value
+const loginMethod = memoryItem<string | null>({
+  key: "loginMethod",
+  defaultValue: null,
+});
+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.
+
+```ts
+import { createSetItem, StorageScope } from "react-native-nitro-storage";
+
+const dismissedTips = createSetItem({
+  key: "dismissedTips",
+  scope: StorageScope.Disk,
+});
+
+dismissedTips.add("welcome");
+dismissedTips.has("welcome"); // true
+dismissedTips.toggle("welcome"); // false (removed)
+dismissedTips.values(); // string[]
+```
+
+## Groups And Lifecycle
+
+Tag items with a `group` to clear related state in one call, or keep specific
+keys while wiping the rest of a scope. This replaces manual snapshot-and-restore
+logout flows.
+
+```ts
+import { secureItem, storage, StorageScope } from "react-native-nitro-storage";
+
+const accessToken = secureItem<string>({
+  key: "accessToken",
+  defaultValue: "",
+  group: "session",
+});
+
+// Wipe everything tied to the session.
+storage.clearGroup("session");
+
+// Wipe Disk but keep a few opt-in preferences.
+storage.clear(StorageScope.Disk, {
+  except: [apiEnvironmentItem, "onboardingComplete"],
+});
+```
+
+## Legacy Key Migration And Secure Resilience
+
+`renameFrom` migrates an old key to a new one on first read and deletes the
+legacy entry. Secure items can fall back to the last cached value when the
+keychain is locked instead of throwing.
+
+```ts
+import {
+  secureItem,
+  createSecureAuthStorage,
+} from "react-native-nitro-storage";
+
+const accessToken = secureItem<string>({
+  key: "accessToken",
+  namespace: "auth",
+  defaultValue: "",
+  renameFrom: "authToken", // copied + cleaned up on first read
+  fallbackToCacheOnReadError: true,
+  onReadError: (error) => reportSecureReadError(error),
+});
+
+const auth = createSecureAuthStorage(
+  {
+    accessToken: { renameFrom: "authToken" },
+    refreshToken: { renameFrom: "refreshToken" },
+  },
+  { namespace: "auth", group: "session", fallbackToCacheOnReadError: true },
+);
+```
 
 ## React Hooks
 
@@ -188,6 +296,24 @@ const [compactMode] = useStorageSelector(
 );
 ```
 
+`useStorage` also returns a render-stable `actions` object as a third element,
+and `useStorageValue` / `useStorageActions` split read and write concerns.
+
+```tsx
+import {
+  useStorage,
+  useStorageActions,
+  useStorageValue,
+} from "react-native-nitro-storage";
+
+const [config, setConfig, actions] = useStorage(configItem);
+actions.merge({ compact: true });
+actions.reset();
+
+const theme = useStorageValue(themeItem); // read-only, no setter
+const tokenActions = useStorageActions(tokenItem); // { set, merge, reset, remove, setOrDelete }
+```
+
 ## Storage Scopes
 
 | Scope                 | Backing store                                          | Use it for                                                                   |
@@ -248,10 +374,20 @@ 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 }`.
 
+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
+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.
+
 ## Batch Operations
 
 `getBatch()` preserves tuple value types, so IDEs infer each result from the
-matching item.
+matching item. `setBatch()` validates every item/value pair independently,
+including heterogeneous batches.
 
 ```ts
 import { getBatch, removeBatch, setBatch } from "react-native-nitro-storage";
@@ -303,6 +439,21 @@ Secure event observer values are redacted by default. Pass
 `{ redactSecureValues: false }` only in trusted debug tooling where raw values
 are safe to inspect.
 
+TTL expiry emits a dedicated `"expire"` change event. Use
+`storage.subscribeExpired()` to react to keys that lapse on read.
+
+```ts
+const unsubscribeExpired = storage.subscribeExpired(
+  StorageScope.Disk,
+  (event) => {
+    console.log("expired", event.key);
+  },
+);
+```
+
+`storage.findDuplicateKeys()` and `storage.getRegisteredKeys()` help audit
+accidental `(scope, key)` collisions; call them once at startup in development.
+
 ## Migrations And Transactions
 
 ```ts
@@ -324,15 +475,16 @@ registerMigration(2, ({ getRaw, setRaw, removeRaw }) => {
 
 migrateToLatest(StorageScope.Disk);
 
-runTransaction(() => {
-  themeItem.set("dark");
-  localeItem.set("en-US");
+runTransaction(StorageScope.Disk, (tx) => {
+  tx.setItem(themeItem, "dark");
+  tx.setItem(localeItem, "en-US");
 });
 
 migrateFromMMKV(mmkvInstance, themeItem);
 ```
 
-Transactions roll back local writes if the callback throws.
+`runTransaction(scope, callback)` rolls back every write made through the `tx`
+context if the callback throws.
 
 ## Web Backends
 
@@ -355,6 +507,31 @@ setWebSecureStorageBackend(backend);
 Browser storage cannot provide iOS Keychain or Android Keystore guarantees. Web
 Secure scope is only as strong as the backend you configure.
 
+## Testing
+
+The `react-native-nitro-storage/testing` entrypoint is a faithful in-memory
+implementation of the full public surface, so unit tests and Storybook run
+without native modules. Mock the package with it, or use it directly.
+
+```ts
+import {
+  createNitroStorageMock,
+  resetNitroStorageMock,
+} from "react-native-nitro-storage/testing";
+
+// Jest: swap the real module for the in-memory implementation.
+jest.mock("react-native-nitro-storage", () =>
+  require("react-native-nitro-storage/testing"),
+);
+
+beforeEach(() => {
+  resetNitroStorageMock();
+});
+
+// Or build an isolated instance per test file.
+const { storage, memoryItem } = createNitroStorageMock();
+```
+
 ## Platform Support
 
 | Platform | Status                                             |