Merge pull request #9 from JoaoPauloCMarra/v0.3.2

v0.3.2

Author: JoaoPauloCMarra

.github/workflows/ci.yml

@@ -37,6 +37,9 @@ jobs:
       - name: Run type checking
         run: bun run typecheck
 
+      - name: Run type-level API tests
+        run: bun run test:types
+
       - name: Run JavaScript tests
         run: bun run test
 
@@ -71,6 +74,4 @@ jobs:
       - name: Test package packaging
         run: |
           cd packages/react-native-nitro-storage
-          # Test that npm pack works (dry run)
-          npm pack --dry-run > /dev/null 2>&1 || exit 1
-          echo "✅ Package can be packed for publishing"
+          bun run check:pack

CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this project are documented in this file.
 
 The format follows Keep a Changelog and the project adheres to SemVer.
 
+## 0.3.2 - 2026-02-22
+
+### Added
+
+- Add `storage.setSecureWritesAsync(enabled)` to toggle Android secure writes between synchronous `commit()` and asynchronous `apply()`.
+- Add `storage.flushSecureWrites()` for deterministic flush control of coalesced secure writes.
+- Add native `removeByPrefix(prefix, scope)` plumbing and route namespace clears through the native/web prefix path.
+- Add dedicated C++ binding tests for `HybridStorage` behavior (`cpp/bindings/HybridStorageTest.cpp`), wired into `test:cpp`.
+- Add type-level public API tests (`test:types`) and package content guard checks (`check:pack`).
+
+### Changed
+
+- Skip unnecessary read path on direct `item.set(value)` writes (still reads for updater functions).
+- Reuse TTL envelope parse results while entries remain unexpired to avoid repeated JSON parse/deserialization work.
+- Group secure raw batch writes by per-item access control so secure batch paths stay fast even with mixed access-control settings.
+- Optimize C++ batch listener dispatch by copying scoped listeners once per batch operation.
+- Avoid duplicate secure biometric clearing calls by relying on secure clear paths that already include biometric cleanup.
+- Optimize web secure/disk key bookkeeping with an indexed key cache (faster `size`, `getAllKeys`, and namespace clears without repeated `localStorage` scans).
+- Improve iOS secure key union performance by deduplicating with an `unordered_set`.
+- Extract shared React hooks into `src/storage-hooks.ts` to reduce native/web entrypoint duplication.
+- Expand benchmark coverage to include Disk and Secure scope throughput checks and tighten regression thresholds.
+- Refresh the Expo example app UI with a cleaner shared design system and add an Android secure write mode demo control.
+- Configure Expo iOS example builds to use React Native source builds under New Architecture and silence expected deprecated RN host warnings in the Android template wrapper.
+- Extend CI with Android/iOS example build jobs under New Architecture.
+- 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
 
 ### Added

README.md

@@ -19,6 +19,24 @@ Synchronous Memory, Disk, and Secure storage in one unified API — powered by [
 - **MMKV migration** — drop-in `migrateFromMMKV` for painless migration from MMKV
 - **Cross-platform** — iOS, Android, and web (`localStorage` fallback)
 
+## Feature Coverage
+
+Every feature in this package is documented with at least one runnable example in this README:
+
+- Core item API (`createStorageItem`, `get/set/delete/has/subscribe`) — see Quick Start and Low-level subscription use case
+- Hooks (`useStorage`, `useStorageSelector`, `useSetStorage`) — see Quick Start and Persisted User Preferences
+- Scopes (`Memory`, `Disk`, `Secure`) — see Storage Scopes and multiple use cases
+- Namespaces — see Multi-Tenant / Namespaced Storage
+- TTL expiration + callbacks — see OTP / Temporary Codes
+- Validation + recovery — see Feature Flags with Validation
+- Biometric + access control — see Biometric-protected Secrets
+- Global storage utilities (`clear*`, `has`, `getAll*`, `size`, secure write settings) — see Global utility examples and Storage Snapshots and Cleanup
+- Batch APIs (`getBatch`, `setBatch`, `removeBatch`) — see Batch Operations and Bulk Bootstrap with Batch APIs
+- Transactions — see Transactions and Atomic Balance Transfer
+- Migrations (`registerMigration`, `migrateToLatest`) — see Migrations
+- MMKV migration (`migrateFromMMKV`) — see MMKV Migration and Migrating From MMKV
+- Auth storage factory (`createSecureAuthStorage`) — see Auth Token Management
+
 ## Requirements
 
 | Dependency                   | Version     |
@@ -183,6 +201,17 @@ function createStorageItem<T = undefined>(
 | `scope`           | `StorageScope`                           | The item's scope                                   |
 | `key`             | `string`                                 | The resolved key (includes namespace prefix)       |
 
+**Non-React subscription example:**
+
+```ts
+const unsubscribe = sessionItem.subscribe(() => {
+  console.log("session changed:", sessionItem.get());
+});
+
+sessionItem.set("next-session");
+unsubscribe();
+```
+
 ---
 
 ### React Hooks
@@ -231,10 +260,49 @@ import { storage, StorageScope } from "react-native-nitro-storage";
 | `storage.getAll(scope)`                 | Get all key-value pairs as `Record<string, string>`                          |
 | `storage.size(scope)`                   | Number of stored keys                                                        |
 | `storage.setAccessControl(level)`       | Set default secure access control for subsequent secure writes (native only) |
+| `storage.setSecureWritesAsync(enabled)` | Toggle async secure writes on Android (`false` by default)                   |
+| `storage.flushSecureWrites()`           | Force flush of queued secure writes when coalescing is enabled               |
 | `storage.setKeychainAccessGroup(group)` | Set keychain access group for app sharing (native only)                      |
 
 > `storage.getAll(StorageScope.Secure)` returns regular secure entries. Biometric-protected values are not included in this snapshot API.
 
+#### Global utility examples
+
+```ts
+import { AccessControl, storage, StorageScope } from "react-native-nitro-storage";
+
+storage.has("session", StorageScope.Disk);
+storage.getAllKeys(StorageScope.Disk);
+storage.getAll(StorageScope.Disk);
+storage.size(StorageScope.Disk);
+
+storage.clearNamespace("user-42", StorageScope.Disk);
+storage.clearBiometric();
+
+storage.setAccessControl(AccessControl.WhenUnlockedThisDeviceOnly);
+storage.setKeychainAccessGroup("group.com.example.shared");
+
+storage.clear(StorageScope.Memory);
+storage.clearAll();
+```
+
+#### Android secure write mode
+
+`storage.setSecureWritesAsync(true)` switches secure writes from synchronous `commit()` to asynchronous `apply()` on Android.  
+Use this for non-critical secure writes when lower latency matters more than immediate durability.
+
+Call `storage.flushSecureWrites()` when you need deterministic persistence boundaries (for example before namespace clears, process handoff, or strict test assertions).
+
+```ts
+import { storage } from "react-native-nitro-storage";
+
+storage.setSecureWritesAsync(true);
+
+// ...multiple secure writes happen (including coalesced item writes)
+
+storage.flushSecureWrites(); // deterministic durability boundary
+```
+
 ---
 
 ### `createSecureAuthStorage<K>(config, options?)`
@@ -398,11 +466,11 @@ enum BiometricLevel {
 ### Persisted User Preferences
 
 ```ts
-interface UserPreferences {
+type UserPreferences = {
   theme: "light" | "dark" | "system";
   language: string;
   notifications: boolean;
-}
+};
 
 const prefsItem = createStorageItem<UserPreferences>({
   key: "prefs",
@@ -446,21 +514,29 @@ storage.clearNamespace("myapp-auth", StorageScope.Secure);
 ### Feature Flags with Validation
 
 ```ts
-interface FeatureFlags {
+type FeatureFlags = {
   darkMode: boolean;
   betaFeature: boolean;
   maxUploadMb: number;
-}
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isFeatureFlags = (value: unknown): value is FeatureFlags => {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.darkMode === "boolean" &&
+    typeof value.betaFeature === "boolean" &&
+    typeof value.maxUploadMb === "number"
+  );
+};
 
 const flagsItem = createStorageItem<FeatureFlags>({
   key: "feature-flags",
   scope: StorageScope.Disk,
   defaultValue: { darkMode: false, betaFeature: false, maxUploadMb: 10 },
-  validate: (v): v is FeatureFlags =>
-    typeof v === "object" &&
-    v !== null &&
-    typeof (v as any).darkMode === "boolean" &&
-    typeof (v as any).maxUploadMb === "number",
+  validate: isFeatureFlags,
   onValidationError: () => ({
     darkMode: false,
     betaFeature: false,
@@ -471,6 +547,24 @@ const flagsItem = createStorageItem<FeatureFlags>({
 });
 ```
 
+### Biometric-protected Secrets
+
+```ts
+import { AccessControl, createStorageItem, StorageScope } from "react-native-nitro-storage";
+
+const paymentPin = createStorageItem<string>({
+  key: "payment-pin",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  biometric: true,
+  accessControl: AccessControl.WhenPasscodeSetThisDeviceOnly,
+});
+
+paymentPin.set("4829");
+const pin = paymentPin.get();
+paymentPin.delete();
+```
+
 ### Multi-Tenant / Namespaced Storage
 
 ```ts
@@ -515,6 +609,40 @@ otpItem.set("482917");
 const code = otpItem.get();
 ```
 
+### Bulk Bootstrap with Batch APIs
+
+```ts
+import {
+  createStorageItem,
+  getBatch,
+  removeBatch,
+  setBatch,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+const firstName = createStorageItem({
+  key: "first-name",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+});
+const lastName = createStorageItem({
+  key: "last-name",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+});
+
+setBatch(
+  [
+    { item: firstName, value: "Ada" },
+    { item: lastName, value: "Lovelace" },
+  ],
+  StorageScope.Disk,
+);
+
+const [first, last] = getBatch([firstName, lastName], StorageScope.Disk);
+removeBatch([firstName, lastName], StorageScope.Disk);
+```
+
 ### Atomic Balance Transfer
 
 ```ts
@@ -555,6 +683,60 @@ const compactItem = createStorageItem<{ id: number; active: boolean }>({
 });
 ```
 
+### Coalesced Secure Writes with Deterministic Flush
+
+```ts
+import { createStorageItem, storage, StorageScope } from "react-native-nitro-storage";
+
+const sessionToken = createStorageItem<string>({
+  key: "session-token",
+  scope: StorageScope.Secure,
+  defaultValue: "",
+  coalesceSecureWrites: true,
+});
+
+sessionToken.set("token-v1");
+sessionToken.set("token-v2");
+
+// force pending secure writes to native persistence
+storage.flushSecureWrites();
+```
+
+### Storage Snapshots and Cleanup
+
+```ts
+import { storage, StorageScope } from "react-native-nitro-storage";
+
+const diskKeys = storage.getAllKeys(StorageScope.Disk);
+const diskValues = storage.getAll(StorageScope.Disk);
+const secureCount = storage.size(StorageScope.Secure);
+
+if (storage.has("legacy-flag", StorageScope.Disk)) {
+  storage.clearNamespace("legacy", StorageScope.Disk);
+}
+
+storage.clearBiometric();
+```
+
+### Low-level Subscription (outside React)
+
+```ts
+import { createStorageItem, StorageScope } from "react-native-nitro-storage";
+
+const notificationsItem = createStorageItem<boolean>({
+  key: "notifications-enabled",
+  scope: StorageScope.Disk,
+  defaultValue: true,
+});
+
+const unsubscribe = notificationsItem.subscribe(() => {
+  console.log("notifications changed:", notificationsItem.get());
+});
+
+notificationsItem.set(false);
+unsubscribe();
+```
+
 ### Migrating From MMKV
 
 ```ts
@@ -600,7 +782,11 @@ From repository root:
 
 ```bash
 bun run test -- --filter=react-native-nitro-storage
+bun run lint -- --filter=react-native-nitro-storage
+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:cpp -- --filter=react-native-nitro-storage
 bun run build -- --filter=react-native-nitro-storage
 ```
 
@@ -612,7 +798,10 @@ bun run test:coverage   # run tests with coverage
 bun run lint            # eslint (expo-magic rules)
 bun run format:check    # prettier check
 bun run typecheck       # tsc --noEmit
-bun run build           # tsup build
+bun run test:types      # public type-level API tests
+bun run test:cpp        # C++ binding/core tests
+bun run check:pack      # npm pack content guard
+bun run build           # bob build
 bun run benchmark       # performance benchmarks
 ```
 

apps/example/app.json

@@ -17,7 +17,14 @@
     },
     "plugins": [
       "expo-router",
-      "expo-build-properties",
+      [
+        "expo-build-properties",
+        {
+          "ios": {
+            "buildReactNativeFromSource": true
+          }
+        }
+      ],
       "react-native-nitro-storage"
     ],
     "experiments": {