react-native-nitro-storage 0.8.0 → 0.10.0

package/docs/api-reference.md

@@ -14,24 +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`                        | Cache parsed values in memory.                                   |
-| `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.                           |
+| 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.          |
 
 `StorageItem<T>`:
 
@@ -41,6 +45,9 @@ const item = createStorageItem<T>({
 | `getWithVersion()`             | Return `{ value, version }` for optimistic writes.          |
 | `set(value)`                   | Store a value. Accepts direct values or updater functions.  |
 | `setIfVersion(version, value)` | Store only when the current version still matches.          |
+| `merge(partial)`               | Shallow-merge an object value.                              |
+| `reset()`                      | Delete the key so the next read returns the default.        |
+| `setOrDelete(value)`           | Set a value or delete for `null`/`undefined`.               |
 | `delete()`                     | Remove the key.                                             |
 | `has()`                        | Check whether the key exists.                               |
 | `subscribe(callback)`          | Subscribe to item changes. Returns an unsubscribe function. |
@@ -58,6 +65,23 @@ const unsubscribe = profileItem.subscribeSelector(
 );
 ```
 
+## createSetItem
+
+```ts
+const flags = createSetItem<"beta" | "compact">({
+  key: "flags",
+  scope: StorageScope.Memory,
+  defaultValue: ["compact"],
+});
+
+flags.add("beta");
+flags.has("compact");
+flags.getTyped();
+```
+
+`get()` retains the compatibility shape `Record<string, true>`. Use
+`getTyped()` when a precise member union is useful.
+
 ## React Hooks
 
 ```ts
@@ -74,9 +98,14 @@ See [react-hooks.md](react-hooks.md).
 
 | Method                                           | Purpose                                                                                   |
 | ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
-| `clear(scope)`                                   | Clear one scope.                                                                          |
+| `clear(scope, options?)`                         | Clear one scope, optionally preserving selected keys.                                     |
 | `clearAll()`                                     | Clear Memory, Disk, and Secure scopes.                                                    |
 | `clearNamespace(namespace, scope)`               | Remove keys under `namespace:`.                                                           |
+| `clearGroup(group)`                              | Remove registered items in a group across their scopes.                                   |
+| `getGroupItems(group)`                           | List registered items in a group.                                                         |
+| `subscribeExpired(scope, listener)`              | Receive item events caused by TTL expiry.                                                 |
+| `findDuplicateKeys()`                            | Find duplicate registered `(scope, key)` definitions.                                     |
+| `getRegisteredKeys()`                            | List registered `(scope, key)` definitions.                                               |
 | `subscribe(scope, listener)`                     | Subscribe to raw scope-level change events.                                               |
 | `subscribeKey(scope, key, listener)`             | Subscribe to raw events for one key.                                                      |
 | `subscribePrefix(scope, prefix, listener)`       | Subscribe to raw events for matching key prefixes.                                        |
@@ -97,6 +126,7 @@ See [react-hooks.md](react-hooks.md).
 | `setKeychainAccessGroup(group)`                  | Configure iOS Keychain access group.                                                      |
 | `setMetricsObserver(observer)`                   | Receive operation timing events.                                                          |
 | `getMetricsSnapshot()`                           | Read aggregated metrics.                                                                  |
+| `getScopedMetricsSnapshot()`                     | Read metrics grouped by storage scope.                                                    |
 | `resetMetrics()`                                 | Clear metrics counters.                                                                   |
 | `getCapabilities()`                              | Read runtime storage capabilities.                                                        |
 | `getSecurityCapabilities()`                      | Read secure backend capability metadata.                                                  |
@@ -170,6 +200,11 @@ setBatch(
 removeBatch([themeItem, localeItem], StorageScope.Disk);
 ```
 
+`getBatch()` reuses enabled raw cache entries, including cached missing values,
+and returns each item's default for a missing raw value without issuing a
+per-item fallback read. Items that need validation, expiration, or migration
+use their item-level read path to preserve those rules.
+
 See [batch-transactions-migrations.md](batch-transactions-migrations.md).
 
 ## Transactions
@@ -211,6 +246,23 @@ auth.accessToken.set("token");
 
 The returned object is a typed record of secure string `StorageItem`s.
 
+## Storage Error Classification
+
+```ts
+if (isStorageError(error, "keychain_locked")) {
+  scheduleRetryAfterUnlock();
+}
+```
+
+`getStorageErrorCode(error)` returns the stable `StorageErrorCode` embedded by
+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.
+
+`isKeychainLockedError(error)` is deprecated. It remains available for
+compatibility and returns `true` for `keychain_locked`,
+`authentication_required`, and `key_invalidated`.
+
 ## Web Backend APIs
 
 ```ts
@@ -221,6 +273,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.
+
 See [web-backends.md](web-backends.md).
 
 ## Enums

package/docs/benchmarks.md

@@ -11,13 +11,18 @@ bun run benchmark
 
 ## 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.
+`benchmark` loads only this package's `lib/commonjs/index.web.js` entry and measures it against a private localStorage implementation created for that process. The `web:disk-scope:` and `web:secure-scope:` 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
 
+- Each run reports the package name/version, runtime, architecture, warmups,
+  sample count, median, and p95. It does not use another package's artifact or
+  ambient browser storage.
 - Compare results on the same machine and Node/Bun version.
+- The benchmark uses seven measured samples after two warmups and reports the
+  median for throughput. It does not select the best sample.
 - 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.
 

package/docs/keychain-lifecycle-testing.md

@@ -0,0 +1,36 @@
+# Physical-Device Keychain Lifecycle Test
+
+Use this protocol for iOS Keychain behavior and stable error classification.
+A simulator cannot prove protected-data behavior.
+
+## Preconditions
+
+- Use a physical iPhone or iPad with a passcode enabled.
+- Build the example app from the package checkout under test.
+- Do not enter a real token or credential. The probe stores a fixed non-secret
+  sentinel under `WhenUnlockedThisDeviceOnly` access control.
+
+## Lock And Resume
+
+1. Open the example app and find **Keychain Lifecycle Probe**.
+2. Press **Seed** and confirm the status changes to `seeded`.
+3. Press **Arm**.
+4. Lock the device, wait for the screen to turn off, then unlock it and return
+   to the example app.
+5. Record both probe rows without logging or inspecting the stored value.
+6. Press **Wipe** after the run.
+
+The strongest passing result is:
+
+- Lock transition: `keychain_locked`.
+- Resume transition: `readable`.
+
+If the lock transition says `readable`, the app sampled before iOS made
+protected data unavailable. Repeat the run; treat repeated readable results as
+inconclusive, not as proof that locked reads work. Any resume result other than
+`readable` fails the recovery contract.
+
+## Release Evidence
+
+Record the physical model, iOS version, package version, build configuration,
+and the two displayed result codes. Do not capture or publish secure values.

package/docs/recipes.md

@@ -283,10 +283,9 @@ Use `subscribePrefix()` or `subscribeNamespace()` for targeted integrations. Use
 ## Capability Checks
 
 ```ts
-const capabilities = storage.getCapabilities();
 const security = storage.getSecurityCapabilities();
 
-if (security.secureStorage !== "available") {
+if (security.secureStorage.encrypted !== "available") {
   console.warn("Secure storage is not available on this runtime");
 }
 ```

package/docs/secure-storage.md

@@ -98,7 +98,7 @@ import { storage } from "react-native-nitro-storage";
 
 const capabilities = storage.getSecurityCapabilities();
 
-if (capabilities.secureStorage === "available") {
+if (capabilities.secureStorage.encrypted === "available") {
   // Secure scope is backed by the configured native or web secure backend.
 }
 ```
@@ -148,35 +148,70 @@ Android secure storage uses encrypted SharedPreferences. Restored encrypted pref
 
 If you disable `configureAndroidBackup` or maintain custom Android backup XML, add equivalent exclusions for both cloud backup and device transfer.
 
-## Locked Keychain Errors
+## Secure Storage Error Recovery
 
 ```ts
-import { isKeychainLockedError } from "react-native-nitro-storage";
+import { isStorageError } from "react-native-nitro-storage";
 
 try {
   refreshTokenItem.get();
 } catch (error) {
-  if (isKeychainLockedError(error)) {
+  if (isStorageError(error, "keychain_locked")) {
     // Defer token refresh until the device is unlocked.
   }
 }
 ```
 
-The helper recognizes iOS locked Keychain cases and Android invalidated/locked key cases surfaced by the native bridge.
+Recovery depends on the exact stable code:
+
+| Code                      | Meaning                                   | Consumer action                                     |
+| ------------------------- | ----------------------------------------- | --------------------------------------------------- |
+| `keychain_locked`         | Protected data is temporarily unavailable | Retry after the device unlocks and the app resumes. |
+| `authentication_required` | The secure item requires user interaction | Start the application's authentication flow.        |
+| `key_invalidated`         | The platform key can no longer decrypt it | Remove and recreate the affected credential safely. |
+
+`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.
+
+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.
 
 ## Android Secure Write Mode
 
-Android secure writes default to synchronous persistence. Enable async writes when write throughput is more important than immediate durability:
+Android secure writes default to synchronous `SharedPreferences.commit()` for
+the established durability contract. If asynchronous
+`SharedPreferences.apply()` is acceptable, opt into async mode explicitly:
 
 ```ts
 import { storage } from "react-native-nitro-storage";
 
 storage.setSecureWritesAsync(true);
 refreshTokenItem.set("opaque-refresh-token");
-storage.flushSecureWrites();
 ```
 
-Call `flushSecureWrites()` before assertions, namespace clears, or any boundary that requires deterministic persistence.
+Coalesced secure item writes remain in a last-write-wins queue until the next
+microtask or an explicit `flushSecureWrites()`. A failed flush throws and keeps
+failed and unattempted writes queued for a later retry. Call
+`flushSecureWrites()` before assertions, namespace clears, or any boundary that
+requires deterministic persistence. `storage.clearBiometric()` is also a
+durability barrier: it flushes pending Secure writes before clearing biometric
+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
+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
+manually while an upgrade is in progress.
 
 ## Web Secure Backend
 
@@ -202,4 +237,5 @@ bun run test:cpp -- --filter=react-native-nitro-storage
 (cd packages/react-native-nitro-storage && bun run check:pack)
 ```
 
-Also run an end-to-end auth flow on a locked/unlocked real device when changing biometric or Keychain behavior.
+Also run the [physical-device Keychain lifecycle protocol](keychain-lifecycle-testing.md)
+when changing biometric, Keychain, or error-classification behavior.