Merge pull request #14 from JoaoPauloCMarra/codex/prepare-0-4-5-release

feat: prepare 0.4.5 release

Author: JoaoPauloCMarra

CHANGELOG.md

@@ -4,7 +4,17 @@ All notable changes to this project are documented in this file.
 
 The format follows Keep a Changelog and the project adheres to SemVer.
 
-## 0.4.4 - 2026-04-08
+## 0.4.5 - 2026-04-14
+
+### Added
+
+- Add configurable web Disk backend hooks: `setWebDiskStorageBackend()`, `getWebDiskStorageBackend()`, and `flushWebStorageBackends()`.
+- Extend the web backend contract with optional batch, sizing, subscription, and flush hooks for higher-performance custom backends.
+- Add IndexedDB backend support for `getMany`, `setMany`, `removeMany`, `size`, `flush`, and `BroadcastChannel`-based cross-tab sync.
+- Expand regression coverage for web backend overrides, backend subscription-driven cache invalidation, backend flush hooks, IndexedDB broadcast sync, and IndexedDB error surfacing.
+- Add Disk write buffering APIs: `coalesceDiskWrites`, `storage.setDiskWritesAsync()`, `storage.flushDiskWrites()`, and `storage.getCapabilities()`.
+- Add structured storage error classification via `getStorageErrorCode()` while keeping `isKeychainLockedError()` as the convenience helper, and tag native bridge errors with stable `[nitro-error:<code>]` markers.
+- Extend the example app and smoke runner to cover runtime capabilities, structured error codes, and Disk write buffering flows.
 
 ### Changed
 
@@ -14,6 +24,8 @@ The format follows Keep a Changelog and the project adheres to SemVer.
 - Refresh root tooling to current patch releases for linting, testing, and workspace orchestration.
 - Align the example app to `react-native-nitro-modules 0.35.4`.
 - Add an example-only Expo config plugin that patches the generated iOS `fmt` pod during `pod install`, keeping clean prebuilds working on Xcode 26.4.
+- Switch web operation timing to `performance.now()` when available for tighter metrics on fast paths.
+- Keep the example smoke runner aligned with the expanded web backend API surface, including backend override and flush coverage on web.
 
 ## 0.4.2/0.4.3 - 2026-03-05
 

README.md

@@ -40,7 +40,11 @@ Every feature in this package is documented with at least one runnable example i
 - Prefix utilities (`getKeysByPrefix`, `getByPrefix`) — see Prefix Queries and Namespace Inspection
 - Versioned item API (`getWithVersion`, `setIfVersion`) — see Optimistic Versioned Writes
 - Metrics API (`setMetricsObserver`, `getMetricsSnapshot`, `resetMetrics`) — see Storage Metrics Instrumentation
+- Runtime capability introspection (`storage.getCapabilities()`) — see Global utility examples
+- Structured storage error codes (`getStorageErrorCode`, `isKeychainLockedError`) — see Error Classification
+- Web disk backend override (`setWebDiskStorageBackend`, `getWebDiskStorageBackend`) — see Custom Web Disk and Secure Backends
 - Web secure backend override (`setWebSecureStorageBackend`, `getWebSecureStorageBackend`) — see Custom Web Secure Backend
+- Web backend durability (`flushWebStorageBackends`) — see Custom Web Disk and Secure Backends
 - IndexedDB backend factory (`createIndexedDBBackend`) — see IndexedDB Backend for Web
 - Bulk import (`storage.import`) — see Bulk Data Import
 - Batch APIs (`getBatch`, `setBatch`, `removeBatch`) — see Batch Operations and Bulk Bootstrap with Batch APIs
@@ -196,6 +200,7 @@ function createStorageItem<T = undefined>(
 | `expiration`           | `{ ttlMs: number }`              | —              | Time-to-live in milliseconds                                   |
 | `onExpired`            | `(key: string) => void`          | —              | Callback fired when a TTL value expires on read                |
 | `readCache`            | `boolean`                        | `false`        | Cache deserialized values in JS (avoids repeated native reads) |
+| `coalesceDiskWrites`   | `boolean`                        | `false`        | Batch same-tick Disk writes per key until `flushDiskWrites()`  |
 | `coalesceSecureWrites` | `boolean`                        | `false`        | Batch same-tick Secure writes per key                          |
 | `namespace`            | `string`                         | —              | Prefix key as `namespace:key` for isolation                    |
 | `biometric`            | `boolean`                        | `false`        | Require biometric auth (Secure scope only)                     |
@@ -278,7 +283,10 @@ import { storage, StorageScope } from "react-native-nitro-storage";
 | `storage.getByPrefix(prefix, scope)`     | Get raw key-value pairs for keys matching a prefix                           |
 | `storage.getAll(scope)`                  | Get all key-value pairs as `Record<string, string>`                          |
 | `storage.size(scope)`                    | Number of stored keys                                                        |
+| `storage.getCapabilities()`              | Read runtime backend metadata and buffering support                          |
 | `storage.setAccessControl(level)`        | Set default secure access control for subsequent secure writes (native only) |
+| `storage.setDiskWritesAsync(enabled)`    | Buffer raw Disk writes in JS until flushed (all platforms)                   |
+| `storage.flushDiskWrites()`              | Force flush queued Disk writes from raw APIs / coalesced items               |
 | `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)                      |
@@ -290,6 +298,14 @@ import { storage, StorageScope } from "react-native-nitro-storage";
 | `storage.getMetricsSnapshot()`           | Get aggregate counters/latency stats keyed by operation                      |
 | `storage.resetMetrics()`                 | Reset in-memory metrics counters                                             |
 
+| Web helper                             | Description                                                          |
+| -------------------------------------- | -------------------------------------------------------------------- |
+| `setWebDiskStorageBackend(backend?)`   | Override the web Disk backend (web only)                             |
+| `getWebDiskStorageBackend()`           | Read the active web Disk backend (web only)                          |
+| `setWebSecureStorageBackend(backend?)` | Override the web Secure backend (web only)                           |
+| `getWebSecureStorageBackend()`         | Read the active web Secure backend (web only)                        |
+| `flushWebStorageBackends()`            | Await optional backend durability hooks for Disk + Secure (web only) |
+
 > `storage.getAll(StorageScope.Secure)` returns regular secure entries. Biometric-protected values are not included in this snapshot API.
 
 #### Global utility examples
@@ -307,6 +323,7 @@ storage.getKeysByPrefix("user-42:", StorageScope.Disk);
 storage.getByPrefix("user-42:", StorageScope.Disk);
 storage.getAll(StorageScope.Disk);
 storage.size(StorageScope.Disk);
+storage.getCapabilities();
 
 storage.clearNamespace("user-42", StorageScope.Disk);
 storage.clearBiometric();
@@ -318,6 +335,32 @@ storage.clear(StorageScope.Memory);
 storage.clearAll();
 ```
 
+#### Disk write buffering
+
+Disk writes can now be buffered in JS, similar to secure write coalescing, which is useful when you are doing bursty persistence and want an explicit durability boundary.
+
+```ts
+import {
+  createStorageItem,
+  storage,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+const bufferedDraft = createStorageItem({
+  key: "draft",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+  coalesceDiskWrites: true,
+});
+
+bufferedDraft.set("hello");
+storage.setDiskWritesAsync(true);
+storage.setString("draft:raw", "value", StorageScope.Disk);
+
+storage.flushDiskWrites(); // commit queued Disk writes
+storage.setDiskWritesAsync(false);
+```
+
 #### Android secure write mode
 
 `storage.setSecureWritesAsync(true)` switches secure writes from synchronous `commit()` to asynchronous `apply()` on Android.  
@@ -335,25 +378,63 @@ storage.setSecureWritesAsync(true);
 storage.flushSecureWrites(); // deterministic durability boundary
 ```
 
-#### Custom web secure backend
+#### Custom Web Disk and Secure Backends
+
+By default, web Disk and Secure scopes use `localStorage`. Disk excludes Nitro's secure prefixes, and Secure stores under `__secure_` / `__bio_` prefixes.
 
-By default, web Secure scope uses `localStorage` with `__secure_` key prefixing. You can replace it with a custom backend (for example encrypted IndexedDB adapter).
+You can replace either backend with a custom implementation. The minimal backend contract is:
+
+```ts
+type WebStorageBackend = {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+  clear(): void;
+  getAllKeys(): string[];
+  getMany?: (keys: string[]) => (string | null)[];
+  setMany?: (entries: ReadonlyArray<readonly [string, string]>) => void;
+  removeMany?: (keys: string[]) => void;
+  size?: () => number;
+  subscribe?: (
+    listener: (event: { key: string | null; newValue: string | null }) => void,
+  ) => () => void;
+  flush?: () => Promise<void>;
+  name?: string;
+};
+```
+
+Optional hooks are used for faster batch operations, custom cross-tab sync, and explicit durability boundaries.
 
 ```ts
 import {
+  flushWebStorageBackends,
+  getWebDiskStorageBackend,
   getWebSecureStorageBackend,
+  setWebDiskStorageBackend,
   setWebSecureStorageBackend,
 } from "react-native-nitro-storage";
 
+setWebDiskStorageBackend({
+  getItem: (key) => diskStore.get(key) ?? null,
+  setItem: (key, value) => diskStore.set(key, value),
+  removeItem: (key) => diskStore.delete(key),
+  clear: () => diskStore.clear(),
+  getAllKeys: () => Array.from(diskStore.keys()),
+});
+
 setWebSecureStorageBackend({
   getItem: (key) => encryptedStore.get(key) ?? null,
   setItem: (key, value) => encryptedStore.set(key, value),
   removeItem: (key) => encryptedStore.delete(key),
   clear: () => encryptedStore.clear(),
-  getAllKeys: () => encryptedStore.keys(),
+  getAllKeys: () => Array.from(encryptedStore.keys()),
 });
 
+await flushWebStorageBackends();
+
+const diskBackend = getWebDiskStorageBackend();
 const backend = getWebSecureStorageBackend();
+console.log("custom disk backend active:", diskBackend !== undefined);
 console.log("custom backend active:", backend !== undefined);
 ```
 
@@ -376,12 +457,24 @@ setWebSecureStorageBackend(backend);
 
 - **Async init**: `createIndexedDBBackend()` opens (or creates) the IndexedDB database and hydrates an in-memory cache from all stored entries before resolving.
 - **Synchronous reads**: all `getItem` calls are served from the in-memory cache — no async overhead after init.
-- **Fire-and-forget writes**: `setItem`, `removeItem`, and `clear` update the cache synchronously, then persist to IndexedDB in the background. The cache is always the authoritative source.
+- **Queued writes + durability**: writes update the cache synchronously, persist in the background, and can be awaited via `await backend.flush()` or `await flushWebStorageBackends()`.
+- **Cross-tab sync**: backend instances on the same `dbName`/`storeName` coordinate through `BroadcastChannel` so cache invalidation reaches other tabs.
 - **Custom database/store**: optionally pass `dbName` and `storeName` to isolate databases per environment or tenant.
 
 ```ts
 const backend = await createIndexedDBBackend("my-app-db", "secure-kv");
 setWebSecureStorageBackend(backend);
+await backend.flush?.();
+```
+
+You can also pass an optional third argument to receive async persistence failures:
+
+```ts
+const backend = await createIndexedDBBackend("my-app-db", "secure-kv", {
+  onError: (error) => {
+    console.error("indexeddb persistence failed", error);
+  },
+});
 ```
 
 ---
@@ -530,16 +623,23 @@ These are synchronous and go directly to the native backend without any serializ
 
 ---
 
-### `isKeychainLockedError(err)`
+### Error Classification
 
-Utility to detect iOS Keychain locked errors and Android key invalidation errors in secure storage operations. Returns `true` if the error was caused by a locked keychain (device locked, first unlock not yet performed, etc.) or an Android `KeyPermanentlyInvalidatedException` / `InvalidKeyException`. Always returns `false` on web.
+`getStorageErrorCode(err)` returns a stable classification for common native/web storage failures. Native bridges now emit stable `[nitro-error:<code>]` tags so the classification path does not depend on platform exception wording alone.
+`isKeychainLockedError(err)` remains the convenience helper for retry-after-unlock flows and now delegates to the structured code path.
 
 ```ts
-import { isKeychainLockedError } from "react-native-nitro-storage";
+import {
+  getStorageErrorCode,
+  isKeychainLockedError,
+} from "react-native-nitro-storage";
 
 try {
   secureItem.get();
 } catch (err) {
+  const code = getStorageErrorCode(err);
+  // "keychain_locked" | "authentication_required" | ...
+
   if (isKeychainLockedError(err)) {
     // device is locked — retry after unlock
   }

apps/example/app/index.tsx

@@ -4,6 +4,7 @@ import {
   createSecureAuthStorage,
   createStorageItem,
   getBatch,
+  getStorageErrorCode,
   migrateToLatest,
   registerMigration,
   removeBatch,
@@ -137,6 +138,13 @@ const batch3 = createStorageItem({
   defaultValue: "-",
 });
 
+const bufferedDiskItem = createStorageItem({
+  key: "disk-buffered-item",
+  scope: StorageScope.Disk,
+  defaultValue: "",
+  coalesceDiskWrites: true,
+});
+
 // ─── Component ────────────────────────────────────────────────────────────────
 
 const HOOK_LABELS = ["initial", "alpha", "beta", "gamma", "delta"];
@@ -222,6 +230,10 @@ export default function HomeScreen() {
   // 17. Prefix & Keys
   const [prefixKeys, setPrefixKeys] = useState<string[]>([]);
   const [allMemoryKeys, setAllMemoryKeys] = useState<string[]>([]);
+  const [diskBufferingEnabled, setDiskBufferingEnabled] = useState(false);
+  const [diskBufferedPreview, setDiskBufferedPreview] = useState("(empty)");
+  const [classifiedErrorCode, setClassifiedErrorCode] = useState("(none)");
+  const capabilities = storage.getCapabilities();
 
   return (
     <Page title="Nitro Storage" subtitle="Complete feature showcase">
@@ -1002,6 +1014,123 @@ export default function HomeScreen() {
         />
       </Card>
 
+      <Card
+        title="Runtime Capabilities"
+        subtitle="Backend metadata and structured error codes"
+        indicatorColor={Colors.secure}
+      >
+        <StatusRow
+          testID="capabilities-platform"
+          label="Platform"
+          value={capabilities.platform}
+        />
+        <StatusRow
+          testID="capabilities-disk-backend"
+          label="Disk backend"
+          value={capabilities.backend.disk}
+        />
+        <StatusRow
+          testID="capabilities-secure-backend"
+          label="Secure backend"
+          value={capabilities.backend.secure}
+        />
+        <StatusRow
+          testID="capabilities-buffering"
+          label="Write buffering"
+          value={`disk=${String(capabilities.writeBuffering.disk)} secure=${String(capabilities.writeBuffering.secure)}`}
+        />
+        <StatusRow
+          testID="capabilities-error-code"
+          label="Sample error code"
+          value={classifiedErrorCode}
+        />
+        <Button
+          testID="classify-storage-error"
+          title="Classify Tagged Error"
+          onPress={() => {
+            setClassifiedErrorCode(
+              getStorageErrorCode(
+                new Error(
+                  "[nitro-error:authentication_required] NitroStorage: auth required",
+                ),
+              ) ?? "(none)",
+            );
+          }}
+          size="sm"
+        />
+      </Card>
+
+      <Card
+        title="Disk Write Buffering"
+        subtitle="Buffered disk writes with explicit flush"
+        indicatorColor={Colors.disk}
+      >
+        <StatusRow
+          testID="disk-buffer-enabled"
+          label="Global buffering"
+          value={diskBufferingEnabled ? "enabled" : "disabled"}
+        />
+        <StatusRow
+          testID="disk-buffer-preview"
+          label="Buffered preview"
+          value={diskBufferedPreview}
+        />
+        <View style={styles.row}>
+          <Button
+            testID="disk-buffer-toggle"
+            title={diskBufferingEnabled ? "Disable" : "Enable"}
+            onPress={() => {
+              const next = !diskBufferingEnabled;
+              storage.setDiskWritesAsync(next);
+              setDiskBufferingEnabled(next);
+            }}
+            style={styles.flex1}
+          />
+          <Button
+            testID="disk-buffer-raw"
+            title="Queue Raw"
+            variant="secondary"
+            onPress={() => {
+              storage.setString(
+                "disk-buffer-raw",
+                "buffered-raw",
+                StorageScope.Disk,
+              );
+              setDiskBufferedPreview(
+                storage.getString("disk-buffer-raw", StorageScope.Disk) ??
+                  "(empty)",
+              );
+            }}
+            style={styles.flex1}
+          />
+        </View>
+        <View style={styles.row}>
+          <Button
+            testID="disk-buffer-item"
+            title="Queue Item"
+            variant="secondary"
+            onPress={() => {
+              bufferedDiskItem.set("buffered-item");
+              setDiskBufferedPreview(bufferedDiskItem.get() || "(empty)");
+            }}
+            style={styles.flex1}
+          />
+          <Button
+            testID="disk-buffer-flush"
+            title="Flush"
+            onPress={() => {
+              storage.flushDiskWrites();
+              setDiskBufferedPreview(
+                storage.getString("disk-buffer-raw", StorageScope.Disk) ??
+                  bufferedDiskItem.get() ??
+                  "(empty)",
+              );
+            }}
+            style={styles.flex1}
+          />
+        </View>
+      </Card>
+
       {/* Smoke Test Runner */}
       <SmokeTestRunner />
     </Page>