react-native-nitro-storage 0.4.0 → 0.4.3

package/README.md

@@ -18,6 +18,8 @@ Synchronous Memory, Disk, and Secure storage in one unified API — powered by [
 - **Versioned writes** — optimistic concurrency with `item.getWithVersion()` and `item.setIfVersion(...)`
 - **Performance metrics** — observe operation timings and aggregate snapshots
 - **Web secure backend override** — plug custom secure storage backend on web
+- **IndexedDB backend** — drop-in `createIndexedDBBackend` factory for persistent web Secure storage with large payloads
+- **Bulk import** — load a raw `Record<string, string>` into any scope atomically with `storage.import`
 - **Transactions** — grouped writes with automatic rollback on error
 - **Migrations** — versioned data migrations with `registerMigration` / `migrateToLatest`
 - **MMKV migration** — drop-in `migrateFromMMKV` for painless migration from MMKV
@@ -39,10 +41,14 @@ Every feature in this package is documented with at least one runnable example i
 - Versioned item API (`getWithVersion`, `setIfVersion`) — see Optimistic Versioned Writes
 - Metrics API (`setMetricsObserver`, `getMetricsSnapshot`, `resetMetrics`) — see Storage Metrics Instrumentation
 - Web secure backend override (`setWebSecureStorageBackend`, `getWebSecureStorageBackend`) — see Custom Web Secure Backend
+- 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
 - Transactions — see Transactions and Atomic Balance Transfer
 - Migrations (`registerMigration`, `migrateToLatest`) — see Migrations
 - MMKV migration (`migrateFromMMKV`) — see MMKV Migration and Migrating From MMKV
+- Raw string API (`getString`, `setString`, `deleteString`) — see Raw String API
+- Keychain locked detection (`isKeychainLockedError`) — see `isKeychainLockedError(err)`
 - Auth storage factory (`createSecureAuthStorage`) — see Auth Token Management
 
 ## Requirements
@@ -276,6 +282,10 @@ import { storage, StorageScope } from "react-native-nitro-storage";
 | `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.getString(key, scope)`          | Read a raw string value directly (bypasses serialization)                    |
+| `storage.setString(key, value, scope)`   | Write a raw string value directly (bypasses serialization)                   |
+| `storage.deleteString(key, scope)`       | Delete a raw string value by key                                             |
+| `storage.import(data, scope)`            | Bulk-load a `Record<string, string>` of raw key/value pairs into a scope     |
 | `storage.setMetricsObserver(observer?)`  | Subscribe to per-operation timing events                                     |
 | `storage.getMetricsSnapshot()`           | Get aggregate counters/latency stats keyed by operation                      |
 | `storage.resetMetrics()`                 | Reset in-memory metrics counters                                             |
@@ -349,6 +359,33 @@ console.log("custom backend active:", backend !== undefined);
 
 ---
 
+### IndexedDB Backend for Web
+
+The default web Secure backend uses `localStorage`, which is synchronous and size-limited. For large payloads or when you need true persistence across tab reloads, use the built-in IndexedDB-backed factory.
+
+```ts
+import { setWebSecureStorageBackend } from "react-native-nitro-storage";
+import { createIndexedDBBackend } from "react-native-nitro-storage/indexeddb-backend";
+
+// call once at app startup, before rendering any components that read secure items
+const backend = await createIndexedDBBackend();
+setWebSecureStorageBackend(backend);
+```
+
+**How it works:**
+
+- **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.
+- **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);
+```
+
+---
+
 ### `createSecureAuthStorage<K>(config, options?)`
 
 One-liner factory for authentication flows. Creates multiple `StorageItem<string>` entries in Secure scope.
@@ -477,6 +514,40 @@ const migrated = migrateFromMMKV(mmkv, myStorageItem, true);
 
 ---
 
+### Raw String API
+
+For cases where you want to bypass `createStorageItem` serialization entirely and work with raw key/value strings:
+
+```ts
+import { storage, StorageScope } from "react-native-nitro-storage";
+
+storage.setString("raw-key", "raw-value", StorageScope.Disk);
+const value = storage.getString("raw-key", StorageScope.Disk); // "raw-value" | undefined
+storage.deleteString("raw-key", StorageScope.Disk);
+```
+
+These are synchronous and go directly to the native backend without any serialize/deserialize step.
+
+---
+
+### `isKeychainLockedError(err)`
+
+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.
+
+```ts
+import { isKeychainLockedError } from "react-native-nitro-storage";
+
+try {
+  secureItem.get();
+} catch (err) {
+  if (isKeychainLockedError(err)) {
+    // device is locked — retry after unlock
+  }
+}
+```
+
+---
+
 ### Enums
 
 #### `AccessControl`
@@ -755,6 +826,25 @@ sessionToken.set("token-v2");
 storage.flushSecureWrites();
 ```
 
+### Bulk Data Import
+
+Load server-fetched data into storage in one atomic call. All keys become visible simultaneously before any listener fires.
+
+```ts
+import { storage, StorageScope } from "react-native-nitro-storage";
+
+// seed local cache from a server response
+const serverData = await fetchInitialData(); // Record<string, string>
+storage.import(serverData, StorageScope.Disk);
+
+// all imported keys are immediately readable
+const value = storage.has("remote-config", StorageScope.Disk);
+```
+
+> `storage.import` writes raw string values directly — serialization is bypassed. Use it for bootstrapping data that was already serialized by the server or exported via `storage.getAll`.
+
+---
+
 ### Storage Snapshots and Cleanup
 
 ```ts

package/android/build.gradle

@@ -14,19 +14,11 @@ def reactNativeArchitectures() {
   return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
 }
 
-def isNewArchitectureEnabled() {
-  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
-}
-
 apply plugin: "com.android.library"
 apply plugin: "org.jetbrains.kotlin.android"
 // Apply autolinking script for Nitro
 apply from: "../nitrogen/generated/android/NitroStorage+autolinking.gradle"
 
-if (isNewArchitectureEnabled()) {
-  apply plugin: "com.facebook.react"
-}
-
 def getExtOrDefault(name) {
   return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroStorage_" + name]
 }
@@ -45,7 +37,6 @@ android {
   defaultConfig {
     minSdkVersion getExtOrIntegerDefault("minSdkVersion")
     targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
-    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
     consumerProguardFiles "consumer-rules.pro"
 
     externalNativeBuild {
@@ -76,9 +67,6 @@ android {
   sourceSets {
     main {
       java.srcDirs += ["src/main/java"]
-      if (isNewArchitectureEnabled()) {
-        java.srcDirs += ["${project.buildDir}/generated/source/codegen/java"]
-      }
     }
   }
 }

package/android/consumer-rules.pro

@@ -1,4 +1,26 @@
-# Keep AndroidStorageAdapter and all its methods - accessed via JNI reflection
--keep class com.nitrostorage.AndroidStorageAdapter { *; }
--keepclassmembers class com.nitrostorage.AndroidStorageAdapter { *; }
--keepclassmembers class com.nitrostorage.AndroidStorageAdapter$Companion { *; }
+# NitroStorage - JNI-callable methods must survive R8/ProGuard shrinking
+
+-keep class com.nitrostorage.AndroidStorageAdapter {
+    public static *** set*(...);
+    public static *** get*(...);
+    public static *** delete*(...);
+    public static *** has*(...);
+    public static *** clear*(...);
+    public static *** size*(...);
+    public static *** flush*(...);
+    public static void init(android.content.Context);
+    public static void setSecureWritesAsync(boolean);
+    public static void setSecureAccessControl(int);
+    public static void removeByPrefix(java.lang.String, int);
+}
+-keep class com.nitrostorage.AndroidStorageAdapter$Companion {
+    public <methods>;
+}
+-keep class com.nitrostorage.NitroStoragePackage {
+    <init>();
+    <clinit>();
+    *;
+}
+-keep class com.nitrostorage.NitroStoragePackage$Companion {
+    *;
+}

package/android/src/main/cpp/AndroidStorageAdapterCpp.cpp

@@ -34,26 +34,23 @@ std::vector<std::optional<std::string>> fromNullableJavaStringArray(alias_ref<Ja
 }
 
 std::vector<std::string> fromJavaStringArray(alias_ref<JavaStringArray> values) {
+    if (!values) return {};
+    const jsize size = values->size();
     std::vector<std::string> result;
-    if (!values) return result;
-
-    const jsize size = static_cast<jsize>(values->size());
     result.reserve(size);
     for (jsize i = 0; i < size; ++i) {
         auto currentValue = values->getElement(i);
-        if (currentValue) {
-            result.push_back(currentValue->toStdString());
-        }
+        // Preserve null as empty string to maintain index alignment with caller
+        result.push_back(currentValue ? currentValue->toStdString() : std::string());
     }
     return result;
 }
 
 } // namespace
 
-AndroidStorageAdapterCpp::AndroidStorageAdapterCpp(alias_ref<JObject> context) {
-    if (!context) [[unlikely]] {
-        throw std::runtime_error("NitroStorage: Android Context is null");
-    }
+AndroidStorageAdapterCpp::AndroidStorageAdapterCpp(alias_ref<JObject> /*context*/) {
+    // Context is validated by AndroidStorageAdapter.getContext() on the Java side.
+    // The adapter calls static Java methods directly via fbjni.
 }
 
 AndroidStorageAdapterCpp::~AndroidStorageAdapterCpp() = default;

package/android/src/main/cpp/AndroidStorageAdapterCpp.hpp

@@ -6,10 +6,6 @@
 
 namespace NitroStorage {
 
-struct JContext : facebook::jni::JavaClass<JContext> {
-  static constexpr auto kJavaDescriptor = "Landroid/content/Context;";
-};
-
 struct AndroidStorageAdapterJava : facebook::jni::JavaClass<AndroidStorageAdapterJava> {
   static constexpr auto kJavaDescriptor = "Lcom/nitrostorage/AndroidStorageAdapter;";
   

package/android/src/main/cpp/cpp-adapter.cpp

@@ -3,5 +3,7 @@
 #include "../../../nitrogen/generated/android/NitroStorageOnLoad.hpp"
 
 JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
-  return margelo::nitro::NitroStorage::initialize(vm);
+  return facebook::jni::initialize(vm, []() {
+    margelo::nitro::NitroStorage::registerAllNatives();
+  });
 }