react-native-nitro-storage 0.4.4 → 0.4.5

package/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
   }

package/android/src/main/java/com/nitrostorage/AndroidStorageAdapter.kt

@@ -1,11 +1,15 @@
 package com.nitrostorage
 
 import android.content.Context
+import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.UserNotAuthenticatedException
 import android.content.SharedPreferences
 import android.util.Log
 import androidx.security.crypto.EncryptedSharedPreferences
 import androidx.security.crypto.MasterKey
+import java.security.InvalidKeyException
 import java.security.KeyStore
+import java.security.KeyStoreException
 import javax.crypto.AEADBadTagException
 
 private fun Throwable.hasCause(type: Class<*>): Boolean {
@@ -17,6 +21,30 @@ private fun Throwable.hasCause(type: Class<*>): Boolean {
     return false
 }
 
+private fun Throwable.storageErrorCode(): String? {
+    return when {
+        hasCause(AEADBadTagException::class.java) -> "storage_corruption"
+        hasCause(UserNotAuthenticatedException::class.java) ||
+            hasCause(KeyStoreException::class.java) -> "authentication_required"
+        hasCause(KeyPermanentlyInvalidatedException::class.java) ||
+            hasCause(InvalidKeyException::class.java) -> "key_invalidated"
+        else -> null
+    }
+}
+
+private fun Throwable.wrapStorageException(
+    defaultMessage: String,
+    defaultCode: String? = null,
+): RuntimeException {
+    val code = storageErrorCode() ?: defaultCode
+    val message = if (code != null) {
+        "[nitro-error:$code] $defaultMessage"
+    } else {
+        defaultMessage
+    }
+    return RuntimeException(message, this)
+}
+
 class AndroidStorageAdapter private constructor(private val context: Context) {
     private val sharedPreferences: SharedPreferences =
         context.getSharedPreferences("NitroStorage", Context.MODE_PRIVATE)
@@ -44,8 +72,11 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             initializeEncryptedPreferences("NitroStorageBiometric", bioKey)
         } catch (e: Exception) {
             Log.e("NitroStorage", "Biometric storage unavailable: ${e.message}")
-            throw RuntimeException("NitroStorage: Biometric storage is not available on this device. " +
-                "Ensure biometric hardware is present and credentials are enrolled.", e)
+            throw e.wrapStorageException(
+                "NitroStorage: Biometric storage is not available on this device. " +
+                    "Ensure biometric hardware is present and credentials are enrolled.",
+                defaultCode = "biometric_unavailable",
+            )
         }
     }
 
@@ -83,14 +114,17 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                             EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
                         )
                     } catch (retryEx: Exception) {
-                        throw RuntimeException("NitroStorage: Unrecoverable storage corruption in $name", retryEx)
+                        throw retryEx.wrapStorageException(
+                            "NitroStorage: Unrecoverable storage corruption in $name",
+                            defaultCode = "storage_corruption",
+                        )
                     }
                 }
                 else -> {
                     // Don't wipe on non-corruption failures (e.g., locked keystore)
-                    throw RuntimeException(
+                    throw e.wrapStorageException(
                         "NitroStorage: Failed to initialize $name (${e::class.simpleName}). " +
-                        "This may be a temporary keystore issue. If it persists, clear app data.", e
+                            "This may be a temporary keystore issue. If it persists, clear app data.",
                     )
                 }
             }
@@ -136,7 +170,9 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 editor.commit()
             }
         } catch (e: Exception) {
-            throw RuntimeException("NitroStorage: Failed to write to secure storage: ${e.message}", e)
+            throw e.wrapStorageException(
+                "NitroStorage: Failed to write to secure storage: ${e.message}",
+            )
         }
     }
 
@@ -303,14 +339,26 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         @JvmStatic
         fun getSecure(key: String): String? {
             val inst = getInstanceOrThrow()
-            return inst.getSecureSafe(inst.encryptedPreferences, key)
+            return try {
+                inst.getSecureSafe(inst.encryptedPreferences, key)
+            } catch (e: Exception) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Failed to read secure storage: ${e.message}",
+                )
+            }
         }
 
         @JvmStatic
         fun getSecureBatch(keys: Array<String>): Array<String?> {
             val inst = getInstanceOrThrow()
-            return Array(keys.size) { index ->
-                inst.getSecureSafe(inst.encryptedPreferences, keys[index])
+            return try {
+                Array(keys.size) { index ->
+                    inst.getSecureSafe(inst.encryptedPreferences, keys[index])
+                }
+            } catch (e: Exception) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Failed to read secure storage batch: ${e.message}",
+                )
             }
         }
 
@@ -406,7 +454,10 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 inst.applySecureEditor(editor)
                 inst.invalidateSecureKeysCache()
             } catch (e: Exception) {
-                throw RuntimeException("NitroStorage: Biometric storage unavailable on this device", e)
+                throw e.wrapStorageException(
+                    "NitroStorage: Biometric storage unavailable on this device",
+                    defaultCode = "biometric_unavailable",
+                )
             }
         }
 

package/ios/IOSStorageAdapterCpp.mm

@@ -9,6 +9,12 @@ static NSString* const kKeychainService = @"com.nitrostorage.keychain";
 static NSString* const kBiometricKeychainService = @"com.nitrostorage.biometric";
 static NSString* const kDiskSuiteName = @"com.nitrostorage.disk";
 
+static std::runtime_error taggedStorageError(const char* code, const std::string& message) {
+    return std::runtime_error(
+        std::string("[nitro-error:") + code + "] " + message
+    );
+}
+
 static NSUserDefaults* NitroDiskDefaults() {
     static NSUserDefaults* defaults = [[NSUserDefaults alloc] initWithSuiteName:kDiskSuiteName];
     return defaults ?: [NSUserDefaults standardUserDefaults];
@@ -191,7 +197,8 @@ static std::vector<std::string> keychainAccountsForService(NSString* service, NS
     std::vector<std::string> keys;
     OSStatus status = SecItemCopyMatching((__bridge CFDictionaryRef)query, &result);
     if (status == errSecInteractionNotAllowed) {
-        throw std::runtime_error(
+        throw taggedStorageError(
+            "keychain_locked",
             "NitroStorage: Keychain is locked (errSecInteractionNotAllowed). "
             "The item is not accessible until the device is unlocked."
         );
@@ -247,7 +254,8 @@ void IOSStorageAdapterCpp::setSecure(const std::string& key, const std::string&
         const OSStatus addStatus = SecItemAdd((__bridge CFDictionaryRef)query, NULL);
         if (addStatus != errSecSuccess) {
             if (addStatus == errSecInteractionNotAllowed) {
-                throw std::runtime_error(
+                throw taggedStorageError(
+                    "keychain_locked",
                     "NitroStorage: Keychain is locked (errSecInteractionNotAllowed). "
                     "The item is not accessible until the device is unlocked."
                 );
@@ -261,7 +269,8 @@ void IOSStorageAdapterCpp::setSecure(const std::string& key, const std::string&
     }
 
     if (status == errSecInteractionNotAllowed) {
-        throw std::runtime_error(
+        throw taggedStorageError(
+            "keychain_locked",
             "NitroStorage: Keychain is locked (errSecInteractionNotAllowed). "
             "The item is not accessible until the device is unlocked."
         );
@@ -292,7 +301,8 @@ std::optional<std::string> IOSStorageAdapterCpp::getSecure(const std::string& ke
         if (str) return std::string([str UTF8String]);
     }
     if (status == errSecInteractionNotAllowed) {
-        throw std::runtime_error(
+        throw taggedStorageError(
+            "keychain_locked",
             "NitroStorage: Keychain is locked (errSecInteractionNotAllowed). "
             "The item is not accessible until the device is unlocked."
         );
@@ -312,7 +322,8 @@ void IOSStorageAdapterCpp::deleteSecure(const std::string& key) {
     NSMutableDictionary* secureQuery = baseKeychainQuery(nsKey, kKeychainService, group);
     OSStatus secureStatus = SecItemDelete((__bridge CFDictionaryRef)secureQuery);
     if (secureStatus == errSecInteractionNotAllowed) {
-        throw std::runtime_error(
+        throw taggedStorageError(
+            "keychain_locked",
             "NitroStorage: Keychain is locked (errSecInteractionNotAllowed). "
             "The item is not accessible until the device is unlocked."
         );
@@ -321,7 +332,8 @@ void IOSStorageAdapterCpp::deleteSecure(const std::string& key) {
     NSMutableDictionary* biometricQuery = baseKeychainQuery(nsKey, kBiometricKeychainService, group);
     OSStatus biometricStatus = SecItemDelete((__bridge CFDictionaryRef)biometricQuery);
     if (biometricStatus == errSecInteractionNotAllowed) {
-        throw std::runtime_error(
+        throw taggedStorageError(
+            "keychain_locked",
             "NitroStorage: Keychain is locked (errSecInteractionNotAllowed). "
             "The item is not accessible until the device is unlocked."
         );
@@ -427,7 +439,10 @@ void IOSStorageAdapterCpp::clearSecure() {
     OSStatus secStatus = SecItemDelete((__bridge CFDictionaryRef)secureQuery);
     if (secStatus != errSecSuccess && secStatus != errSecItemNotFound) {
         if (secStatus == errSecInteractionNotAllowed) {
-            throw std::runtime_error("NitroStorage: Cannot clear secure storage: keychain is locked (errSecInteractionNotAllowed)");
+            throw taggedStorageError(
+                "keychain_locked",
+                "NitroStorage: Cannot clear secure storage: keychain is locked (errSecInteractionNotAllowed)"
+            );
         }
         throw std::runtime_error(
             std::string("NitroStorage: clearSecure failed with status ") + std::to_string(secStatus));
@@ -443,7 +458,10 @@ void IOSStorageAdapterCpp::clearSecure() {
     OSStatus bioStatus = SecItemDelete((__bridge CFDictionaryRef)biometricQuery);
     if (bioStatus != errSecSuccess && bioStatus != errSecItemNotFound) {
         if (bioStatus == errSecInteractionNotAllowed) {
-            throw std::runtime_error("NitroStorage: Cannot clear biometric storage: keychain is locked (errSecInteractionNotAllowed)");
+            throw taggedStorageError(
+                "keychain_locked",
+                "NitroStorage: Cannot clear biometric storage: keychain is locked (errSecInteractionNotAllowed)"
+            );
         }
         throw std::runtime_error(
             std::string("NitroStorage: clearSecureBiometric failed with status ") + std::to_string(bioStatus));
@@ -533,7 +551,10 @@ void IOSStorageAdapterCpp::setSecureBiometricWithLevel(const std::string& key, c
     if (error || !access) {
         if (access) CFRelease(access);
         if (error) CFRelease(error);
-        throw std::runtime_error("NitroStorage: Failed to create biometric access control");
+        throw taggedStorageError(
+            "biometric_unavailable",
+            "NitroStorage: Failed to create biometric access control"
+        );
     }
 
     NSMutableDictionary* attrs = baseKeychainQuery(nsKey, kBiometricKeychainService, group);
@@ -546,14 +567,16 @@ void IOSStorageAdapterCpp::setSecureBiometricWithLevel(const std::string& key, c
             try {
                 setSecure(key, *backup);
             } catch (const std::exception& restoreEx) {
-                throw std::runtime_error(
+                throw taggedStorageError(
+                    "biometric_unavailable",
                     std::string("NitroStorage: Biometric set failed with status ") +
                     std::to_string(addStatus) +
                     " and previous value restoration also failed: " + restoreEx.what());
             }
         }
         if (addStatus == errSecInteractionNotAllowed) {
-            throw std::runtime_error(
+            throw taggedStorageError(
+                "keychain_locked",
                 "NitroStorage: Keychain is locked (errSecInteractionNotAllowed). "
                 "The item is not accessible until the device is unlocked."
             );
@@ -586,13 +609,17 @@ std::optional<std::string> IOSStorageAdapterCpp::getSecureBiometric(const std::s
         if (str) return std::string([str UTF8String]);
     }
     if (status == errSecInteractionNotAllowed) {
-        throw std::runtime_error(
+        throw taggedStorageError(
+            "keychain_locked",
             "NitroStorage: Keychain is locked (errSecInteractionNotAllowed). "
             "The item is not accessible until the device is unlocked."
         );
     }
     if (status == errSecUserCanceled || status == errSecAuthFailed) {
-        throw std::runtime_error("NitroStorage: Biometric authentication failed");
+        throw taggedStorageError(
+            "authentication_required",
+            "NitroStorage: Biometric authentication failed"
+        );
     }
     return std::nullopt;
 }
@@ -640,7 +667,10 @@ void IOSStorageAdapterCpp::clearSecureBiometric() {
     OSStatus status = SecItemDelete((__bridge CFDictionaryRef)query);
     if (status != errSecSuccess && status != errSecItemNotFound) {
         if (status == errSecInteractionNotAllowed) {
-            throw std::runtime_error("NitroStorage: Cannot clear biometric storage: keychain is locked (errSecInteractionNotAllowed)");
+            throw taggedStorageError(
+                "keychain_locked",
+                "NitroStorage: Cannot clear biometric storage: keychain is locked (errSecInteractionNotAllowed)"
+            );
         }
         throw std::runtime_error(
             std::string("NitroStorage: clearSecureBiometric failed with status ") + std::to_string(status));