refactor: reorganize storage logic and improve performance

- Moved utility functions and constants to a new internal module for better organization.
- Simplified storage operations by consolidating common logic into reusable functions.
- Enhanced caching mechanisms for raw values to reduce redundant storage access.
- Improved batch processing for storage operations, allowing for more efficient data handling.
- Updated type definitions and added new features for better type safety and clarity.
- Refactored listener management to streamline event handling across different storage scopes.
- Adjusted migration handling to ensure compatibility with new storage structures.
- Updated task dependencies in turbo.json to include code generation step before build.

Author: JoaoPauloCMarra

.github/workflows/ci.yml

@@ -13,15 +13,15 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: latest
+          bun-version: 1.3.9
 
       - name: Cache dependencies
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: |
             ~/.bun/install/cache
@@ -41,9 +41,10 @@ jobs:
         run: bun run test
 
       - name: Run JavaScript tests with coverage
-        run: |
-          cd packages/react-native-nitro-storage
-          bun run test:coverage
+        run: bun run test:coverage
+
+      - name: Run benchmark regression checks
+        run: bun run benchmark
 
       - name: Setup CMake (for C++ tests)
         run: |

CHANGELOG.md

@@ -4,6 +4,41 @@ 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.0 - 2026-02-15
+
+### Added
+- Add `useStorageSelector(item, selector, isEqual?)` to reduce rerenders from unrelated object updates.
+- Add opt-in `coalesceSecureWrites` and per-item `readCache` controls in `createStorageItem` config.
+- Add benchmark regression gate (`benchmark` task/script) and wire it into CI and publish checks.
+
+### Changed
+- Switch default serialization to a primitive fast path for primitives while preserving JSON compatibility for objects and legacy values.
+- Replace broad listener fan-out with key-indexed registries and automatic pruning for memory/native/web paths.
+- Rework Turbo task graph so `build` depends on `codegen`, `test`/`typecheck` run from source, and `codegen` can be cached.
+
+### Fixed
+- Route native batch calls through true adapter-level batch APIs (HybridStorage + iOS/Android adapters) instead of per-key loops.
+- Add read-through cache invalidation on scoped/key change events and native/web clear paths.
+
+## 0.2.1 - 2026-02-15
+
+### Added
+- Add explicit package `exports` for ESM/CJS/react-native/web resolution.
+
+### Fixed
+- Preserve validation and TTL semantics in batch APIs by falling back to per-item paths when needed.
+- Preserve item-level semantics in transaction `setItem`/`removeItem` by using item methods directly.
+- Decode native batch missing values correctly to avoid empty-string ambiguity on iOS/Android C++ bindings.
+- Avoid duplicate observer updates on native/web `setBatch` paths.
+- Scope iOS disk storage to a dedicated UserDefaults suite and avoid clearing unrelated app defaults.
+- Use a package-specific Android master-key alias for encrypted storage initialization and recovery.
+- Expo config plugin now preserves existing `NSFaceIDUsageDescription` values.
+- Expo config plugin makes Android biometric permissions opt-in.
+
+### Changed
+- Raise `react` peer dependency floor to `>=18.2.0`.
+- Update CI workflow action versions and Bun runtime pin to latest stable releases.
+
 ## 0.2.0 - 2026-02-15
 
 ### Added

README.md

@@ -6,7 +6,7 @@ Synchronous storage for React Native with a unified API for memory, disk, and se
 
 - `react-native >= 0.75.0`
 - `react-native-nitro-modules >= 0.33.9`
-- `react`
+- `react >= 18.2.0`
 
 ## Installation
 
@@ -25,11 +25,24 @@ bunx expo install react-native-nitro-storage react-native-nitro-modules
 ```json
 {
   "expo": {
-    "plugins": ["react-native-nitro-storage"]
+    "plugins": [
+      [
+        "react-native-nitro-storage",
+        {
+          "faceIDPermission": "Allow $(PRODUCT_NAME) to use Face ID for secure authentication",
+          "addBiometricPermissions": false
+        }
+      ]
+    ]
   }
 }
 ```
 
+Notes:
+
+- If `faceIDPermission` is omitted, the plugin sets a default only when `NSFaceIDUsageDescription` is missing.
+- Android biometric permissions are opt-in via `addBiometricPermissions: true`.
+
 Then:
 
 ```bash
@@ -86,6 +99,7 @@ export function Counter() {
 - `storage`
 - `createStorageItem`
 - `useStorage`
+- `useStorageSelector`
 - `useSetStorage`
 - `getBatch`
 - `setBatch`
@@ -155,6 +169,8 @@ type StorageItemConfig<T> = {
   validate?: Validator<T>;
   onValidationError?: (invalidValue: unknown) => T;
   expiration?: ExpirationConfig;
+  readCache?: boolean;
+  coalesceSecureWrites?: boolean;
 };
 ```
 
@@ -184,7 +200,10 @@ Notes:
 
 - `Memory` stores values directly.
 - `Disk` and `Secure` store serialized values.
+- Default serialization uses a primitive fast path for strings/numbers/booleans/null/undefined and JSON for objects/arrays.
 - If `expiration` is enabled, values are wrapped internally and expired lazily on read.
+- `readCache` is opt-in for `Disk`/`Secure` and can be enabled per item.
+- `coalesceSecureWrites` is opt-in and batches same-tick secure writes per key.
 - If `validate` fails on a stored value, fallback is:
 1. `onValidationError(invalidValue)` if provided
 2. `defaultValue` otherwise
@@ -202,6 +221,18 @@ function useStorage<T>(
 ): [T, (value: T | ((prev: T) => T)) => void]
 ```
 
+### `useStorageSelector(item, selector, isEqual?)`
+
+```ts
+function useStorageSelector<T, TSelected>(
+  item: StorageItem<T>,
+  selector: (value: T) => TSelected,
+  isEqual?: (prev: TSelected, next: TSelected) => boolean
+): [TSelected, (value: T | ((prev: T) => T)) => void]
+```
+
+Use this to subscribe to a derived slice of a storage value and avoid rerenders when that slice does not change.
+
 ### `useSetStorage(item)`
 
 ```ts
@@ -243,14 +274,15 @@ function setBatch<T>(
 ): void;
 
 function removeBatch(
-  items: readonly Pick<StorageItem<unknown>, "key" | "scope" | "delete" | "_triggerListeners">[],
+  items: readonly Pick<StorageItem<unknown>, "key" | "scope" | "delete">[],
   scope: StorageScope
 ): void;
 ```
 
 Rules:
 
 - All items must match the batch `scope`.
+- Items using `validate` or `expiration` automatically run via per-item `get()`/`set()` paths to preserve validation and TTL behavior.
 - Mixed-scope calls throw:
   - `Batch scope mismatch for "<key>": expected <Scope>, received <Scope>.`
 
@@ -292,11 +324,8 @@ type TransactionContext = {
   setRaw: (key: string, value: string) => void;
   removeRaw: (key: string) => void;
   getItem: <T>(item: Pick<StorageItem<T>, "scope" | "key" | "get">) => T;
-  setItem: <T>(
-    item: Pick<StorageItem<T>, "scope" | "key" | "serialize">,
-    value: T
-  ) => void;
-  removeItem: (item: Pick<StorageItem<unknown>, "scope" | "key">) => void;
+  setItem: <T>(item: Pick<StorageItem<T>, "scope" | "key" | "set">, value: T) => void;
+  removeItem: (item: Pick<StorageItem<unknown>, "scope" | "key" | "delete">) => void;
 };
 
 function runTransaction<T>(
@@ -309,6 +338,7 @@ Behavior:
 
 - On exception, it rolls back keys modified in that transaction.
 - Rollback is best-effort within process lifetime.
+- `setItem`/`removeItem` prefer item methods when available, so validation/TTL/cache semantics stay consistent.
 
 Throws:
 
@@ -404,7 +434,7 @@ migrateToLatest(StorageScope.Disk);
 ## Scope Semantics
 
 - `Memory`: in-memory only, not persisted.
-- `Disk`: UserDefaults (iOS), SharedPreferences (Android), `localStorage` (web).
+- `Disk`: App-scoped UserDefaults suite (iOS), SharedPreferences (Android), `localStorage` (web).
 - `Secure`: Keychain (iOS), EncryptedSharedPreferences (Android), `sessionStorage` fallback (web).
 
 ## Dev Commands
@@ -415,6 +445,7 @@ From repo root:
 bun run test -- --filter=react-native-nitro-storage
 bun run typecheck -- --filter=react-native-nitro-storage
 bun run build -- --filter=react-native-nitro-storage
+bun run benchmark
 ```
 
 Inside package:
@@ -424,6 +455,7 @@ bun run test
 bun run test:coverage
 bun run typecheck
 bun run build
+bun run benchmark
 ```
 
 ## License