react-native-nitro-storage 0.5.0 → 0.5.2

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/react-native-nitro-storage)](https://www.npmjs.com/package/react-native-nitro-storage)
 [![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![React Native](https://img.shields.io/badge/react--native-%3E%3D0.75-61dafb)](https://reactnative.dev/)
-[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.35.4-black)](https://nitro.margelo.com/)
+[![Nitro Modules](https://img.shields.io/badge/nitro--modules-%3E%3D0.35.5-black)](https://nitro.margelo.com/)
 
 One storage layer for render-time state, persisted app state, and native secrets.
 
@@ -42,6 +42,7 @@ Use it when you want one storage API for React Native and web, with fast synchro
 | Move existing MMKV data           | `migrateFromMMKV`                                             |
 | Persist storage on web            | `setWebDiskStorageBackend` or `createIndexedDBBackend`        |
 | Inspect secure backend state      | `getSecurityCapabilities`, `getSecureMetadata`, metadata APIs |
+| Connect external state/debug code | `subscribeNamespace`, `subscribePrefix`, `setEventObserver`   |
 
 ## Use It When
 
@@ -56,7 +57,7 @@ Use a database or server-state cache instead when you need relational queries, c
 - Three scopes: in-memory session state, persisted disk state, and platform secure storage.
 - Secure storage backed by iOS Keychain and Android Keystore/EncryptedSharedPreferences.
 - React hooks without providers: `useStorage`, `useStorageSelector`, and `useSetStorage`.
-- Batch reads/writes, namespace cleanup, raw import/export, transactions, and migrations.
+- Batch reads/writes, namespace cleanup, raw import/export, event subscriptions, transactions, and migrations.
 - Web parity with configurable Disk/Secure backends and an IndexedDB backend.
 - MMKV migration helper for moving existing keys without rewriting app code first.
 
@@ -188,6 +189,37 @@ runTransaction(StorageScope.Disk, (tx) => {
 });
 ```
 
+Create a raw snapshot for backups or test fixtures, then restore it later:
+
+```ts
+import { StorageScope, storage } from "react-native-nitro-storage";
+
+const snapshot = storage.export(StorageScope.Disk);
+
+storage.import(snapshot, StorageScope.Disk);
+```
+
+`storage.export(StorageScope.Secure)` returns raw secret values. Do not log Secure exports or include them in diagnostics, analytics, crash reports, or support bundles.
+
+Subscribe to storage changes outside React:
+
+```ts
+import { StorageScope, storage } from "react-native-nitro-storage";
+
+const unsubscribe = storage.subscribeNamespace(
+  "settings",
+  StorageScope.Disk,
+  (event) => {
+    if (event.type === "batch") {
+      console.log("settings changed", event.changes.length);
+      return;
+    }
+
+    console.log(event.key, event.operation);
+  },
+);
+```
+
 ## Storage Scopes
 
 | Scope                 | Backing store                                                                 | Best for                                         |
@@ -243,7 +275,7 @@ import {
 The main building blocks are:
 
 - `createStorageItem<T>(config)` for typed values.
-- `storage` for raw reads, namespace cleanup, secure metadata, metrics, and runtime capability checks.
+- `storage` for raw reads, namespace cleanup, events, secure metadata, metrics, and runtime capability checks.
 - `getBatch`, `setBatch`, and `removeBatch` for multi-key work.
 - `runTransaction` for synchronous rollback on failure.
 - `registerMigration` and `migrateToLatest` for versioned local data migrations.
@@ -265,7 +297,7 @@ Peer dependencies:
 
 - `react >=18.2.0`
 - `react-native >=0.75.0`
-- `react-native-nitro-modules >=0.35.4`
+- `react-native-nitro-modules >=0.35.5`
 
 ## Security Model
 
@@ -355,9 +387,11 @@ 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:coverage -- --filter=react-native-nitro-storage
 bun run test:cpp -- --filter=react-native-nitro-storage
-bun run --cwd packages/react-native-nitro-storage check:pack
-npm publish --dry-run
+bun run test:cpp:coverage -- --filter=react-native-nitro-storage
+(cd packages/react-native-nitro-storage && bun run check:pack)
+bun run publish-package:dry -- --yes --with-coverage
 ```
 
 ## Development
@@ -377,8 +411,8 @@ Release checks:
 ```sh
 bun run build -- --filter=react-native-nitro-storage
 bun run benchmark -- --filter=react-native-nitro-storage
-bun run --cwd packages/react-native-nitro-storage check:pack
-npm publish --dry-run
+(cd packages/react-native-nitro-storage && bun run check:pack)
+bun run publish-package:dry -- --yes
 ```
 
 ## License

package/docs/api-reference.md

@@ -44,9 +44,20 @@ const item = createStorageItem<T>({
 | `delete()`                     | Remove the key.                                             |
 | `has()`                        | Check whether the key exists.                               |
 | `subscribe(callback)`          | Subscribe to item changes. Returns an unsubscribe function. |
+| `subscribeSelector(...)`       | Subscribe to a selected value with an equality check.       |
 | `serialize(value)`             | Serialize a value with the item encoder.                    |
 | `deserialize(value)`           | Deserialize a raw string with the item decoder.             |
 
+```ts
+const unsubscribe = profileItem.subscribeSelector(
+  (profile) => profile.name,
+  (name, previousName) => {
+    console.log("Profile name changed", { name, previousName });
+  },
+  { fireImmediately: true },
+);
+```
+
 ## React Hooks
 
 ```ts
@@ -61,37 +72,84 @@ See [react-hooks.md](react-hooks.md).
 
 `storage` exposes raw and cross-item utilities:
 
-| Method                             | Purpose                                                       |
-| ---------------------------------- | ------------------------------------------------------------- |
-| `clear(scope)`                     | Clear one scope.                                              |
-| `clearAll()`                       | Clear Memory, Disk, and Secure scopes.                        |
-| `clearNamespace(namespace, scope)` | Remove keys under `namespace:`.                               |
-| `clearBiometric()`                 | Clear biometric Secure entries.                               |
-| `has(key, scope)`                  | Check for a raw key.                                          |
-| `getAllKeys(scope)`                | List raw keys.                                                |
-| `getKeysByPrefix(prefix, scope)`   | List raw keys with a prefix.                                  |
-| `getByPrefix(prefix, scope)`       | Read raw string values by prefix.                             |
-| `getAll(scope)`                    | Read all raw string values in a scope.                        |
-| `size(scope)`                      | Return approximate scope entry count.                         |
-| `setAccessControl(accessControl)`  | Set the default Secure access control level.                  |
-| `setSecureWritesAsync(enabled)`    | Toggle Android secure writes between sync and async modes.    |
-| `setDiskWritesAsync(enabled)`      | Toggle coalesced Disk write behavior.                         |
-| `flushDiskWrites()`                | Flush pending Disk writes.                                    |
-| `flushSecureWrites()`              | Flush pending Secure writes.                                  |
-| `setKeychainAccessGroup(group)`    | Configure iOS Keychain access group.                          |
-| `setMetricsObserver(observer)`     | Receive operation timing events.                              |
-| `getMetricsSnapshot()`             | Read aggregated metrics.                                      |
-| `resetMetrics()`                   | Clear metrics counters.                                       |
-| `getCapabilities()`                | Read runtime storage capabilities.                            |
-| `getSecurityCapabilities()`        | Read secure backend capability metadata.                      |
-| `getSecureMetadata(key)`           | Read secure metadata for one key without returning its value. |
-| `getAllSecureMetadata()`           | Read secure metadata for all secure keys without values.      |
-| `getString(key, scope)`            | Read a raw string.                                            |
-| `setString(key, value, scope)`     | Write a raw string.                                           |
-| `deleteString(key, scope)`         | Remove a raw key.                                             |
-| `import(data, scope)`              | Bulk import raw strings.                                      |
-
-Raw string APIs bypass item serialization and validation. Prefer `StorageItem<T>` unless you are migrating, importing, or writing a custom integration.
+| Method                                           | Purpose                                                       |
+| ------------------------------------------------ | ------------------------------------------------------------- |
+| `clear(scope)`                                   | Clear one scope.                                              |
+| `clearAll()`                                     | Clear Memory, Disk, and Secure scopes.                        |
+| `clearNamespace(namespace, scope)`               | Remove keys under `namespace:`.                               |
+| `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.            |
+| `subscribeNamespace(namespace, scope, listener)` | Subscribe to raw events for `namespace:` keys.                |
+| `setEventObserver(observer)`                     | Receive all change events for devtools or logging.            |
+| `clearBiometric()`                               | Clear biometric Secure entries.                               |
+| `has(key, scope)`                                | Check for a raw key.                                          |
+| `getAllKeys(scope)`                              | List raw keys.                                                |
+| `getKeysByPrefix(prefix, scope)`                 | List raw keys with a prefix.                                  |
+| `getByPrefix(prefix, scope)`                     | Read raw string values by prefix.                             |
+| `getAll(scope)`                                  | Read all raw string values in a scope.                        |
+| `size(scope)`                                    | Return approximate scope entry count.                         |
+| `setAccessControl(accessControl)`                | Set the default Secure access control level.                  |
+| `setSecureWritesAsync(enabled)`                  | Toggle Android secure writes between sync and async modes.    |
+| `setDiskWritesAsync(enabled)`                    | Toggle coalesced Disk write behavior.                         |
+| `flushDiskWrites()`                              | Flush pending Disk writes.                                    |
+| `flushSecureWrites()`                            | Flush pending Secure writes.                                  |
+| `setKeychainAccessGroup(group)`                  | Configure iOS Keychain access group.                          |
+| `setMetricsObserver(observer)`                   | Receive operation timing events.                              |
+| `getMetricsSnapshot()`                           | Read aggregated metrics.                                      |
+| `resetMetrics()`                                 | Clear metrics counters.                                       |
+| `getCapabilities()`                              | Read runtime storage capabilities.                            |
+| `getSecurityCapabilities()`                      | Read secure backend capability metadata.                      |
+| `getSecureMetadata(key)`                         | Read secure metadata for one key without returning its value. |
+| `getAllSecureMetadata()`                         | Read secure metadata for all secure keys without values.      |
+| `getString(key, scope)`                          | Read a raw string.                                            |
+| `setString(key, value, scope)`                   | Write a raw string.                                           |
+| `deleteString(key, scope)`                       | Remove a raw key.                                             |
+| `export(scope)`                                  | Snapshot raw strings from one scope.                          |
+| `import(data, scope)`                            | Bulk import raw strings.                                      |
+
+Raw string APIs bypass item serialization and validation. Prefer `StorageItem<T>` unless you are migrating, exporting/importing, or writing a custom integration.
+
+```ts
+const diskSnapshot = storage.export(StorageScope.Disk);
+storage.import(diskSnapshot, StorageScope.Disk);
+```
+
+Secure exports contain raw secret values. Do not log `storage.export(StorageScope.Secure)` output or attach it to diagnostics, analytics, crash reports, or support bundles.
+
+## Event Subscriptions
+
+Use raw subscriptions when integrating Nitro Storage with state managers, sync engines, debug tooling, or non-React code.
+
+```ts
+const unsubscribe = storage.subscribeNamespace(
+  "auth",
+  StorageScope.Secure,
+  (event) => {
+    if (event.type === "batch") {
+      console.log(
+        "Auth keys changed",
+        event.changes.map((change) => change.key),
+      );
+      return;
+    }
+
+    console.log("Auth key changed", event.key, event.operation);
+  },
+);
+```
+
+For whole-app debug tooling, install one observer:
+
+```ts
+storage.setEventObserver((event) => {
+  if (event.scope !== StorageScope.Secure) {
+    console.log(event);
+  }
+});
+```
+
+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.
 
 ## Batch Operations
 
@@ -201,6 +259,12 @@ Common public types:
 - `StorageMetricsEvent`
 - `StorageMetricsObserver`
 - `StorageMetricSummary`
+- `StorageChangeEvent`
+- `StorageKeyChangeEvent`
+- `StorageBatchChangeEvent`
+- `StorageChangeOperation`
+- `StorageChangeSource`
+- `StorageEventListener`
 - `MigrationContext`
 - `Migration`
 - `TransactionContext`

package/docs/batch-transactions-migrations.md

@@ -44,6 +44,22 @@ setBatch(
 
 Memory-scope batch writes are two-phase: all values are written first, then listeners are notified. Items with validation or TTL fall back to per-item writes so those rules still run.
 
+Scope and prefix subscriptions receive one batch event for raw batch writes and removes:
+
+```ts
+const unsubscribe = storage.subscribePrefix(
+  StorageScope.Disk,
+  "settings:",
+  (event) => {
+    if (event.type === "batch") {
+      event.changes.forEach((change) => {
+        console.log(change.key, change.operation);
+      });
+    }
+  },
+);
+```
+
 ## Batch Removes
 
 ```ts
@@ -52,24 +68,22 @@ import { removeBatch, StorageScope } from "react-native-nitro-storage";
 removeBatch([themeItem, localeItem], StorageScope.Disk);
 ```
 
-## Raw Import
+## Raw Import and Export
 
-`storage.import(data, scope)` writes raw strings. It does not serialize values.
+`storage.export(scope)` returns raw strings, and `storage.import(data, scope)` writes raw strings. These APIs do not serialize values.
 
 ```ts
 import { storage, StorageScope } from "react-native-nitro-storage";
 
-storage.import(
-  {
-    "flags:newOnboarding": "true",
-    "flags:paywall": "control",
-  },
-  StorageScope.Disk,
-);
+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.
 
+Secure exports contain raw secret values. Do not log them or include them in diagnostics, analytics, crash reports, or support bundles.
+
 ## Transactions
 
 Use `runTransaction(scope, callback)` when several raw or item writes should roll back together if the callback throws.

package/docs/benchmarks.md

@@ -30,7 +30,7 @@ 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
-bun run --cwd packages/react-native-nitro-storage check:pack
+(cd packages/react-native-nitro-storage && bun run check:pack)
 npm publish --dry-run
 ```
 

package/docs/recipes.md

@@ -205,19 +205,15 @@ tokenItem.set("token");
 storage.flushSecureWrites();
 ```
 
-## Raw Import
+## Raw Import and Export
 
 ```ts
-storage.import(
-  {
-    "settings:theme": "dark",
-    "settings:locale": "en-US",
-  },
-  StorageScope.Disk,
-);
+const snapshot = storage.export(StorageScope.Disk);
+
+storage.import(snapshot, StorageScope.Disk);
 ```
 
-Raw import writes strings exactly as provided. It does not run item serializers.
+Raw export/import reads and writes strings exactly as stored. It does not run item serializers. Secure exports contain raw secret values, so do not log them or attach them to diagnostics.
 
 ## Snapshot and Cleanup
 
@@ -259,6 +255,31 @@ const snapshot = storage.getMetricsSnapshot();
 storage.resetMetrics();
 ```
 
+## Event Logging
+
+```ts
+const unsubscribe = storage.subscribePrefix(
+  StorageScope.Disk,
+  "settings:",
+  (event) => {
+    if (event.type === "batch") {
+      console.log("settings changed", event.changes.length);
+      return;
+    }
+
+    console.log(event.key, event.operation);
+  },
+);
+
+storage.setEventObserver((event) => {
+  if (event.scope !== StorageScope.Secure) {
+    console.log(event.type, event.operation);
+  }
+});
+```
+
+Use `subscribePrefix()` or `subscribeNamespace()` for targeted integrations. Use `setEventObserver()` for devtools-style logging. Secure events can include raw secret values, so filter them out of logs.
+
 ## Capability Checks
 
 ```ts

package/docs/secure-storage.md

@@ -114,6 +114,25 @@ const allKeys = storage.getAllSecureMetadata();
 
 `getSecureMetadata()` and `getAllSecureMetadata()` never return stored secret values. They report key existence, storage kind, backend name, access-control metadata, and whether a metadata path accidentally exposed a value.
 
+## Secure Export Warning
+
+`storage.export(StorageScope.Secure)` returns raw secret values so it can round-trip with `storage.import(data, StorageScope.Secure)`.
+
+```ts
+import { storage, StorageScope } from "react-native-nitro-storage";
+
+const secureSnapshot = storage.export(StorageScope.Secure);
+storage.import(secureSnapshot, StorageScope.Secure);
+```
+
+Only keep Secure exports in memory for the shortest possible workflow. Do not log them or include them in diagnostics, analytics, crash reports, or support bundles.
+
+## Secure Event Warning
+
+Secure scope event subscriptions and `storage.setEventObserver()` can receive raw secret values in `oldValue`, `newValue`, or batch `changes`.
+
+Use Secure events for in-memory coordination only. Do not log Secure event payloads or send them to analytics, crash reporting, support bundles, or devtools sessions that persist outside the device.
+
 ## Locked Keychain Errors
 
 ```ts
@@ -165,7 +184,7 @@ Before releasing secure-storage changes, run:
 ```sh
 bun run test -- --filter=react-native-nitro-storage
 bun run test:cpp -- --filter=react-native-nitro-storage
-bun run --cwd packages/react-native-nitro-storage check:pack
+(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.