Merge pull request #16 from JoaoPauloCMarra/release/0.5.1

feat: prepare storage 0.5.1 release

Author: JoaoPauloCMarra

CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project are documented in this file.
 
 The format follows Keep a Changelog and the project adheres to SemVer.
 
+## 0.5.1 - 2026-04-24
+
+### Added
+
+- Add `storage.export(scope)` for raw string snapshots that can be restored with `storage.import(data, scope)`.
+- Add event subscriptions with `storage.subscribe`, `storage.subscribeKey`, `storage.subscribePrefix`, and `storage.subscribeNamespace`.
+- Add `StorageItem#subscribeSelector()` for selector-based subscriptions with equality checks.
+- Add `storage.setEventObserver()` for devtools and storage event logging integrations.
+- Add enforced JS/TS and C++ coverage gates for the package release path.
+- Extend the example smoke runner to cover the full public API surface and show unsupported platform checks as skipped.
+
+### Changed
+
+- Improve Memory namespace clear notification fan-out so subscribers under the cleared namespace are notified consistently.
+- Improve web key-index fast paths when the active backend exposes indexed key operations.
+- Emit batch change envelopes for raw import/export-adjacent workflows and batch writes/removes.
+- Document raw import/export workflows and warn that Secure exports expose secret values.
+- Align the Expo example and workspace dependency pins with Expo Doctor recommendations.
+- 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
 
 ### Added

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 test:cpp:coverage -- --filter=react-native-nitro-storage
 bun run --cwd packages/react-native-nitro-storage check:pack
-npm publish --dry-run
+bun run publish-package:dry -- --yes --with-coverage
 ```
 
 ## Development
@@ -378,7 +412,7 @@ Release checks:
 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
+bun run publish-package:dry -- --yes
 ```
 
 ## License

apps/example/.maestro/main.yaml

@@ -4,13 +4,14 @@ name: "Nitro Storage - Smoke Test"
 - launchApp:
     clearState: true
 
-# Scroll to the Smoke Test runner at the bottom
-- scrollUntilVisible:
-    element:
-      id: "smoke-run-all"
-    direction: DOWN
-    timeout: 20000
-    speed: 80
+# Scroll to the Smoke Test runner at the bottom. Fixed swipes are more stable
+# on iOS because the button is exposed as accessibility text/resource-id but
+# scrollUntilVisible can miss it inside the nested Expo scroll view.
+- repeat:
+    times: 7
+    commands:
+      - swipe:
+          direction: UP
 
 # Tap "Run All" to execute every smoke test
 - tapOn:
@@ -20,7 +21,6 @@ name: "Nitro Storage - Smoke Test"
 - extendedWaitUntil:
     visible:
       text: "Run All"
-      id: "smoke-run-all"
     timeout: 30000
 
 # Assert no test failed