react-native-nitro-storage 0.3.1 → 0.3.2

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

package/android/CMakeLists.txt

@@ -11,6 +11,8 @@ file(GLOB SOURCES
   "../cpp/core/*.cpp"
   "./src/main/cpp/*.cpp"
 )
+# Unit/integration C++ tests define `main()` and must never be linked into the Android shared library.
+list(FILTER SOURCES EXCLUDE REGEX ".*/[^/]*Test\\.cpp$")
 
 # 2. Create the library target
 add_library(

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

@@ -213,6 +213,10 @@ void AndroidStorageAdapterCpp::clearSecure() {
 // --- Config (no-ops on Android; access control / groups are iOS-specific) ---
 
 void AndroidStorageAdapterCpp::setSecureAccessControl(int /*level*/) {}
+void AndroidStorageAdapterCpp::setSecureWritesAsync(bool enabled) {
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(jboolean)>("setSecureWritesAsync");
+    method(AndroidStorageAdapterJava::javaClassStatic(), enabled);
+}
 void AndroidStorageAdapterCpp::setKeychainAccessGroup(const std::string& /*group*/) {}
 
 // --- Biometric ---

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

@@ -49,6 +49,7 @@ public:
     void clearSecure() override;
 
     void setSecureAccessControl(int level) override;
+    void setSecureWritesAsync(bool enabled) override;
     void setKeychainAccessGroup(const std::string& group) override;
 
     void setSecureBiometric(const std::string& key, const std::string& value) override;

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

@@ -33,6 +33,9 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             encryptedPreferences
         }
     }
+
+    @Volatile
+    private var secureWritesAsync = false
     
     private fun initializeEncryptedPreferences(name: String, key: MasterKey): SharedPreferences {
         return try {
@@ -90,6 +93,14 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             }
         }
     }
+
+    private fun applySecureEditor(editor: SharedPreferences.Editor) {
+        if (secureWritesAsync) {
+            editor.apply()
+        } else {
+            editor.commit()
+        }
+    }
     
     companion object {
         @Volatile
@@ -118,6 +129,11 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             return getInstanceOrThrow().context
         }
 
+        @JvmStatic
+        fun setSecureWritesAsync(enabled: Boolean) {
+            getInstanceOrThrow().secureWritesAsync = enabled
+        }
+
         // --- Disk ---
         
         @JvmStatic
@@ -182,21 +198,24 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
             getInstanceOrThrow().sharedPreferences.edit().clear().apply()
         }
 
-        // --- Secure (uses commit for reliability) ---
+        // --- Secure (sync commit by default, async apply when enabled) ---
         
         @JvmStatic
         fun setSecure(key: String, value: String) {
-            getInstanceOrThrow().encryptedPreferences.edit().putString(key, value).commit()
+            val inst = getInstanceOrThrow()
+            val editor = inst.encryptedPreferences.edit().putString(key, value)
+            inst.applySecureEditor(editor)
         }
 
         @JvmStatic
         fun setSecureBatch(keys: Array<String>, values: Array<String>) {
-            val editor = getInstanceOrThrow().encryptedPreferences.edit()
+            val inst = getInstanceOrThrow()
+            val editor = inst.encryptedPreferences.edit()
             val count = minOf(keys.size, values.size)
             for (index in 0 until count) {
                 editor.putString(keys[index], values[index])
             }
-            editor.commit()
+            inst.applySecureEditor(editor)
         }
         
         @JvmStatic
@@ -215,8 +234,8 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         @JvmStatic
         fun deleteSecure(key: String) {
             val inst = getInstanceOrThrow()
-            inst.encryptedPreferences.edit().remove(key).commit()
-            inst.biometricPreferences.edit().remove(key).commit()
+            inst.applySecureEditor(inst.encryptedPreferences.edit().remove(key))
+            inst.applySecureEditor(inst.biometricPreferences.edit().remove(key))
         }
 
         @JvmStatic
@@ -228,8 +247,8 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
                 secureEditor.remove(key)
                 biometricEditor.remove(key)
             }
-            secureEditor.commit()
-            biometricEditor.commit()
+            inst.applySecureEditor(secureEditor)
+            inst.applySecureEditor(biometricEditor)
         }
 
         @JvmStatic
@@ -255,15 +274,17 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         @JvmStatic
         fun clearSecure() {
             val inst = getInstanceOrThrow()
-            inst.encryptedPreferences.edit().clear().commit()
-            inst.biometricPreferences.edit().clear().commit()
+            inst.applySecureEditor(inst.encryptedPreferences.edit().clear())
+            inst.applySecureEditor(inst.biometricPreferences.edit().clear())
         }
 
         // --- Biometric (separate encrypted store, requires recent biometric auth on Android) ---
 
         @JvmStatic
         fun setSecureBiometric(key: String, value: String) {
-            getInstanceOrThrow().biometricPreferences.edit().putString(key, value).commit()
+            val inst = getInstanceOrThrow()
+            val editor = inst.biometricPreferences.edit().putString(key, value)
+            inst.applySecureEditor(editor)
         }
 
         @JvmStatic
@@ -273,7 +294,8 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
 
         @JvmStatic
         fun deleteSecureBiometric(key: String) {
-            getInstanceOrThrow().biometricPreferences.edit().remove(key).commit()
+            val inst = getInstanceOrThrow()
+            inst.applySecureEditor(inst.biometricPreferences.edit().remove(key))
         }
 
         @JvmStatic
@@ -283,7 +305,8 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
 
         @JvmStatic
         fun clearSecureBiometric() {
-            getInstanceOrThrow().biometricPreferences.edit().clear().commit()
+            val inst = getInstanceOrThrow()
+            inst.applySecureEditor(inst.biometricPreferences.edit().clear())
         }
     }
 }

package/cpp/bindings/HybridStorage.cpp

@@ -1,12 +1,14 @@
 #include "HybridStorage.hpp"
 #include <stdexcept>
 
+#ifndef NITRO_STORAGE_DISABLE_PLATFORM_ADAPTER
 #if __APPLE__
 #include "../../ios/IOSStorageAdapterCpp.hpp"
 #elif __ANDROID__
 #include "../../android/src/main/cpp/AndroidStorageAdapterCpp.hpp"
 #include <fbjni/fbjni.h>
 #endif
+#endif
 
 namespace margelo::nitro::NitroStorage {
 
@@ -16,12 +18,14 @@ constexpr auto kBatchMissingSentinel = "__nitro_storage_batch_missing__::v1";
 
 HybridStorage::HybridStorage()
     : HybridObject(TAG), HybridStorageSpec() {
+#ifndef NITRO_STORAGE_DISABLE_PLATFORM_ADAPTER
 #if __APPLE__
     nativeAdapter_ = std::make_shared<::NitroStorage::IOSStorageAdapterCpp>();
 #elif __ANDROID__
     auto context = ::NitroStorage::AndroidStorageAdapterJava::getContext();
     nativeAdapter_ = std::make_shared<::NitroStorage::AndroidStorageAdapterCpp>(context);
 #endif
+#endif
 }
 
 HybridStorage::HybridStorage(std::shared_ptr<::NitroStorage::NativeStorageAdapter> adapter)
@@ -298,8 +302,10 @@ void HybridStorage::setBatch(const std::vector<std::string>& keys, const std::ve
             break;
     }
 
+    const auto scopeValue = static_cast<int>(s);
+    const auto listeners = copyListenersForScope(scopeValue);
     for (size_t i = 0; i < keys.size(); ++i) {
-        notifyListeners(static_cast<int>(s), keys[i], values[i]);
+        notifyListeners(listeners, keys[i], values[i]);
     }
 }
 
@@ -392,11 +398,34 @@ void HybridStorage::removeBatch(const std::vector<std::string>& keys, double sco
             break;
     }
 
+    const auto scopeValue = static_cast<int>(s);
+    const auto listeners = copyListenersForScope(scopeValue);
     for (const auto& key : keys) {
-        notifyListeners(static_cast<int>(s), key, std::nullopt);
+        notifyListeners(listeners, key, std::nullopt);
     }
 }
 
+void HybridStorage::removeByPrefix(const std::string& prefix, double scope) {
+    if (prefix.empty()) {
+        return;
+    }
+
+    const auto keys = getAllKeys(scope);
+    std::vector<std::string> prefixedKeys;
+    prefixedKeys.reserve(keys.size());
+    for (const auto& key : keys) {
+        if (key.rfind(prefix, 0) == 0) {
+            prefixedKeys.push_back(key);
+        }
+    }
+
+    if (prefixedKeys.empty()) {
+        return;
+    }
+
+    removeBatch(prefixedKeys, scope);
+}
+
 // --- Configuration ---
 
 void HybridStorage::setSecureAccessControl(double level) {
@@ -404,6 +433,11 @@ void HybridStorage::setSecureAccessControl(double level) {
     nativeAdapter_->setSecureAccessControl(static_cast<int>(level));
 }
 
+void HybridStorage::setSecureWritesAsync(bool enabled) {
+    ensureAdapter();
+    nativeAdapter_->setSecureWritesAsync(enabled);
+}
+
 void HybridStorage::setKeychainAccessGroup(const std::string& group) {
     ensureAdapter();
     nativeAdapter_->setKeychainAccessGroup(group);
@@ -457,11 +491,7 @@ void HybridStorage::clearSecureBiometric() {
 
 // --- Internal ---
 
-void HybridStorage::notifyListeners(
-    int scope,
-    const std::string& key,
-    const std::optional<std::string>& value
-) {
+std::vector<HybridStorage::Listener> HybridStorage::copyListenersForScope(int scope) {
     std::vector<Listener> listenersCopy;
     {
         std::lock_guard<std::mutex> lock(listenersMutex_);
@@ -471,8 +501,15 @@ void HybridStorage::notifyListeners(
             listenersCopy = it->second;
         }
     }
-    
-    for (const auto& listener : listenersCopy) {
+    return listenersCopy;
+}
+
+void HybridStorage::notifyListeners(
+    const std::vector<Listener>& listeners,
+    const std::string& key,
+    const std::optional<std::string>& value
+) {
+    for (const auto& listener : listeners) {
         try {
             listener.callback(key, value);
         } catch (...) {
@@ -481,6 +518,15 @@ void HybridStorage::notifyListeners(
     }
 }
 
+void HybridStorage::notifyListeners(
+    int scope,
+    const std::string& key,
+    const std::optional<std::string>& value
+) {
+    const auto listeners = copyListenersForScope(scope);
+    notifyListeners(listeners, key, value);
+}
+
 void HybridStorage::ensureAdapter() const {
     if (!nativeAdapter_) {
         throw std::runtime_error("NitroStorage: Native adapter not initialized");

package/cpp/bindings/HybridStorage.hpp

@@ -3,6 +3,7 @@
 #include "HybridStorageSpec.hpp"
 #include "../core/NativeStorageAdapter.hpp"
 #include <unordered_map>
+#include <map>
 #include <mutex>
 #include <functional>
 #include <memory>
@@ -10,6 +11,14 @@
 
 namespace margelo::nitro::NitroStorage {
 
+#ifdef NITRO_STORAGE_USE_ORDERED_MAP_FOR_TESTS
+template <typename Key, typename Value>
+using HybridStorageMap = std::map<Key, Value>;
+#else
+template <typename Key, typename Value>
+using HybridStorageMap = std::unordered_map<Key, Value>;
+#endif
+
 class HybridStorage : public HybridStorageSpec {
 public:
     HybridStorage();
@@ -26,11 +35,13 @@ public:
     void setBatch(const std::vector<std::string>& keys, const std::vector<std::string>& values, double scope) override;
     std::vector<std::string> getBatch(const std::vector<std::string>& keys, double scope) override;
     void removeBatch(const std::vector<std::string>& keys, double scope) override;
+    void removeByPrefix(const std::string& prefix, double scope) override;
     std::function<void()> addOnChange(
         double scope,
         const std::function<void(const std::string&, const std::optional<std::string>&)>& callback
     ) override;
     void setSecureAccessControl(double level) override;
+    void setSecureWritesAsync(bool enabled) override;
     void setKeychainAccessGroup(const std::string& group) override;
     void setSecureBiometric(const std::string& key, const std::string& value) override;
     std::optional<std::string> getSecureBiometric(const std::string& key) override;
@@ -50,15 +61,21 @@ private:
         std::function<void(const std::string&, const std::optional<std::string>&)> callback;
     };
 
-    std::unordered_map<std::string, std::string> memoryStore_;
+    HybridStorageMap<std::string, std::string> memoryStore_;
     std::mutex memoryMutex_;
     
     std::shared_ptr<::NitroStorage::NativeStorageAdapter> nativeAdapter_;
     
-    std::unordered_map<int, std::vector<Listener>> listeners_;
+    HybridStorageMap<int, std::vector<Listener>> listeners_;
     std::mutex listenersMutex_;
     size_t nextListenerId_ = 0;
 
+    std::vector<Listener> copyListenersForScope(int scope);
+    void notifyListeners(
+        const std::vector<Listener>& listeners,
+        const std::string& key,
+        const std::optional<std::string>& value
+    );
     void notifyListeners(int scope, const std::string& key, const std::optional<std::string>& value);
     void ensureAdapter() const;
     Scope toScope(double scopeValue);

package/cpp/core/NativeStorageAdapter.hpp

@@ -34,6 +34,7 @@ public:
     virtual void clearSecure() = 0;
 
     virtual void setSecureAccessControl(int level) = 0;
+    virtual void setSecureWritesAsync(bool enabled) = 0;
     virtual void setKeychainAccessGroup(const std::string& group) = 0;
 
     virtual void setSecureBiometric(const std::string& key, const std::string& value) = 0;

package/ios/IOSStorageAdapterCpp.hpp

@@ -33,6 +33,7 @@ public:
     void clearSecure() override;
 
     void setSecureAccessControl(int level) override;
+    void setSecureWritesAsync(bool enabled) override;
     void setKeychainAccessGroup(const std::string& group) override;
 
     void setSecureBiometric(const std::string& key, const std::string& value) override;

package/ios/IOSStorageAdapterCpp.mm

@@ -3,6 +3,7 @@
 #import <Security/Security.h>
 #import <LocalAuthentication/LocalAuthentication.h>
 #include <algorithm>
+#include <unordered_set>
 
 namespace NitroStorage {
 
@@ -222,9 +223,10 @@ bool IOSStorageAdapterCpp::hasSecure(const std::string& key) {
 std::vector<std::string> IOSStorageAdapterCpp::getAllKeysSecure() {
     NSString* group = keychainAccessGroup_.empty() ? nil : [NSString stringWithUTF8String:keychainAccessGroup_.c_str()];
     std::vector<std::string> keys = keychainAccountsForService(kKeychainService, group);
+    std::unordered_set<std::string> seen(keys.begin(), keys.end());
     const std::vector<std::string> biometricKeys = keychainAccountsForService(kBiometricKeychainService, group);
     for (const auto& key : biometricKeys) {
-        if (std::find(keys.begin(), keys.end(), key) == keys.end()) {
+        if (seen.insert(key).second) {
             keys.push_back(key);
         }
     }
@@ -288,6 +290,10 @@ void IOSStorageAdapterCpp::setSecureAccessControl(int level) {
     accessControlLevel_ = level;
 }
 
+void IOSStorageAdapterCpp::setSecureWritesAsync(bool /*enabled*/) {
+    // iOS writes are synchronous by design; keep behavior unchanged.
+}
+
 void IOSStorageAdapterCpp::setKeychainAccessGroup(const std::string& group) {
     keychainAccessGroup_ = group;
 }