react-native-nitro-storage 0.10.3 → 0.10.4

package/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 Breaking changes are always listed first in each release section.
 
+## [0.10.4] - 2026-09-27
+
+### Breaking changes
+
+- None.
+
+### Fixed
+
+- Disk prefix queries and namespace removal now distinguish ASCII case, so clearing `user` does not remove `User` keys.
+- Android Disk and Secure storage preserve embedded NUL characters in keys and values across scalar and batch operations, preventing truncated-key collisions.
+- iOS Secure storage preserves embedded NUL keys and values, and legacy Disk migration no longer aliases a shorter host-app defaults key when a key contains NUL.
+- Memory prefix reads return the original raw string, including values beginning with the reserved internal prefix.
+- Raw enumeration, export, and set items preserve arbitrary keys such as `__proto__`, `constructor`, and `toString` as own properties.
+
 ## [0.10.3] - 2026-09-18
 
 ### Breaking changes

package/README.md

@@ -35,6 +35,7 @@ pagination, conflict resolution, or remote synchronization.
 - [Legacy Key Migration And Secure Resilience](#legacy-key-migration-and-secure-resilience)
 - [React Hooks](#react-hooks)
 - [Storage Scopes](#storage-scopes)
+- [Prefix Queries](#prefix-queries)
 - [Secure Storage](#secure-storage)
 - [Batch Operations](#batch-operations)
 - [Events And Observability](#events-and-observability)
@@ -68,7 +69,7 @@ Nitro peer requirement: `react-native-nitro-modules >=0.37.0 <0.38.0`.
 The package gate uses React Native `0.86.3` and the Strict TypeScript API.
 `check:ci` also compiles the public source against React Native `0.87.0`'s
 Strict TypeScript API; this does not change the runtime baseline. The Expo
-example uses Expo SDK `57.0.24`, React Native
+example uses Expo SDK `57.0.25`, React Native
 `0.86.3`, React `19.2.3`, and Nitro Modules `0.37.1`, which is the React Native
 version supported by that Expo SDK. Do not override Expo's React Native version.
 
@@ -77,7 +78,7 @@ before installing this package, then rebuild the native app so the generated
 Nitro bindings and native runtime use the same major-minor version:
 
 ```sh
-bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.10.3
+bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.10.4
 bunx expo prebuild
 ```
 
@@ -393,6 +394,26 @@ const tokenActions = useStorageActions(tokenItem); // { set, merge, reset, remov
 | `StorageScope.Disk`   | SQLite WAL on iOS/Android (imports UserDefaults / SharedPreferences once); configured web backend | Preferences, feature flags, onboarding state, and non-secret persisted data. |
 | `StorageScope.Secure` | Keychain on iOS, Android Keystore-backed preferences                                              | Refresh tokens, credentials, API tokens, and biometric-protected values.     |
 
+## Prefix Queries
+
+Prefix queries use literal, case-sensitive matching on every backend. `User::`
+and `user::` are separate namespaces; `%`, `_`, and `\\` are literal characters.
+Raw enumeration returns the original strings and preserves arbitrary keys as own
+properties on an ordinary object, including `__proto__`.
+
+Disk and Secure strings preserve embedded NUL characters in keys and values,
+including batch operations. Earlier versions could truncate strings at Android
+JNI or iOS Foundation boundaries; this fix cannot reconstruct previously lost
+suffixes. iOS legacy Disk migration also preserves full keys without aliasing
+shorter host-app defaults keys.
+
+```ts
+storage.setString("User::theme", "dark", StorageScope.Disk);
+storage.setString("user::theme", "light", StorageScope.Disk);
+const settings = storage.getByPrefix("User::", StorageScope.Disk);
+// settings["User::theme"] === "dark"; no lowercase namespace entries.
+```
+
 ## Secure Storage
 
 ```ts

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

@@ -1,5 +1,8 @@
 #include "AndroidStorageAdapterCpp.hpp"
 
+#include <limits>
+#include <stdexcept>
+
 namespace NitroStorage {
 
 using namespace facebook::jni;
@@ -7,10 +10,25 @@ using JavaStringArray = JArrayClass<jstring>;
 
 namespace {
 
+local_ref<JString> toJavaString(const std::string& value) {
+    // fbjni's std::string overload uses c_str(), which truncates embedded NUL.
+    if (value.find('\0') == std::string::npos) return make_jstring(value);
+    if (value.size() > static_cast<size_t>(std::numeric_limits<jsize>::max())) {
+        throw std::length_error("Storage string exceeds the Java array limit");
+    }
+    const auto size = static_cast<jsize>(value.size());
+    auto bytes = JArrayByte::newArray(size);
+    bytes->setRegion(0, size, reinterpret_cast<const jbyte*>(value.data()));
+    static auto constructor = JString::javaClassStatic()->getConstructor<
+        jstring(jbyteArray, jstring)>();
+    auto charset = make_jstring("UTF-8");
+    return JString::javaClassStatic()->newObject(constructor, bytes.get(), charset.get());
+}
+
 local_ref<JavaStringArray> toJavaStringArray(const std::vector<std::string>& values) {
     auto javaArray = JavaStringArray::newArray(static_cast<jsize>(values.size()));
     for (size_t i = 0; i < values.size(); ++i) {
-        auto javaValue = make_jstring(values[i]);
+        auto javaValue = toJavaString(values[i]);
         javaArray->setElement(static_cast<jsize>(i), javaValue.get());
     }
     return javaArray;
@@ -61,25 +79,25 @@ AndroidStorageAdapterCpp::~AndroidStorageAdapterCpp() = default;
 // --- Disk ---
 
 void AndroidStorageAdapterCpp::setDisk(const std::string& key, const std::string& value) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(std::string, std::string)>("setDisk");
-    method(AndroidStorageAdapterJava::javaClassStatic(), key, value);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(alias_ref<JString>, alias_ref<JString>)>("setDisk");
+    method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key), toJavaString(value));
 }
 
 std::optional<std::string> AndroidStorageAdapterCpp::getDisk(const std::string& key) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jstring(std::string)>("getDisk");
-    auto result = method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jstring(alias_ref<JString>)>("getDisk");
+    auto result = method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key));
     if (!result) return std::nullopt;
     return result->toStdString();
 }
 
 void AndroidStorageAdapterCpp::deleteDisk(const std::string& key) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(std::string)>("deleteDisk");
-    method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(alias_ref<JString>)>("deleteDisk");
+    method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key));
 }
 
 bool AndroidStorageAdapterCpp::hasDisk(const std::string& key) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jboolean(std::string)>("hasDisk");
-    return method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jboolean(alias_ref<JString>)>("hasDisk");
+    return method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key));
 }
 
 std::vector<std::string> AndroidStorageAdapterCpp::getAllKeysDisk() {
@@ -92,9 +110,9 @@ std::vector<std::string> AndroidStorageAdapterCpp::getAllKeysDisk() {
 
 std::vector<std::string> AndroidStorageAdapterCpp::getKeysByPrefixDisk(const std::string& prefix) {
     static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<
-        local_ref<JavaStringArray>(std::string)
+        local_ref<JavaStringArray>(alias_ref<JString>)
     >("getKeysByPrefixDisk");
-    auto keys = method(AndroidStorageAdapterJava::javaClassStatic(), prefix);
+    auto keys = method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(prefix));
     return fromJavaStringArray(keys);
 }
 
@@ -145,25 +163,25 @@ void AndroidStorageAdapterCpp::clearDisk() {
 // --- Secure ---
 
 void AndroidStorageAdapterCpp::setSecure(const std::string& key, const std::string& value) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(std::string, std::string)>("setSecure");
-    method(AndroidStorageAdapterJava::javaClassStatic(), key, value);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(alias_ref<JString>, alias_ref<JString>)>("setSecure");
+    method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key), toJavaString(value));
 }
 
 std::optional<std::string> AndroidStorageAdapterCpp::getSecure(const std::string& key) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jstring(std::string)>("getSecure");
-    auto result = method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jstring(alias_ref<JString>)>("getSecure");
+    auto result = method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key));
     if (!result) return std::nullopt;
     return result->toStdString();
 }
 
 void AndroidStorageAdapterCpp::deleteSecure(const std::string& key) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(std::string)>("deleteSecure");
-    method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(alias_ref<JString>)>("deleteSecure");
+    method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key));
 }
 
 bool AndroidStorageAdapterCpp::hasSecure(const std::string& key) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jboolean(std::string)>("hasSecure");
-    return method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jboolean(alias_ref<JString>)>("hasSecure");
+    return method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key));
 }
 
 std::vector<std::string> AndroidStorageAdapterCpp::getAllKeysSecure() {
@@ -176,9 +194,9 @@ std::vector<std::string> AndroidStorageAdapterCpp::getAllKeysSecure() {
 
 std::vector<std::string> AndroidStorageAdapterCpp::getKeysByPrefixSecure(const std::string& prefix) {
     static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<
-        local_ref<JavaStringArray>(std::string)
+        local_ref<JavaStringArray>(alias_ref<JString>)
     >("getKeysByPrefixSecure");
-    auto keys = method(AndroidStorageAdapterJava::javaClassStatic(), prefix);
+    auto keys = method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(prefix));
     return fromJavaStringArray(keys);
 }
 
@@ -242,25 +260,25 @@ void AndroidStorageAdapterCpp::setSecureBiometric(const std::string& key, const
 }
 
 void AndroidStorageAdapterCpp::setSecureBiometricWithLevel(const std::string& key, const std::string& value, int level) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(std::string, std::string, jint)>("setSecureBiometricWithLevel");
-    method(AndroidStorageAdapterJava::javaClassStatic(), key, value, level);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(alias_ref<JString>, alias_ref<JString>, jint)>("setSecureBiometricWithLevel");
+    method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key), toJavaString(value), level);
 }
 
 std::optional<std::string> AndroidStorageAdapterCpp::getSecureBiometric(const std::string& key) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jstring(std::string)>("getSecureBiometric");
-    auto result = method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jstring(alias_ref<JString>)>("getSecureBiometric");
+    auto result = method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key));
     if (!result) return std::nullopt;
     return result->toStdString();
 }
 
 void AndroidStorageAdapterCpp::deleteSecureBiometric(const std::string& key) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(std::string)>("deleteSecureBiometric");
-    method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<void(alias_ref<JString>)>("deleteSecureBiometric");
+    method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key));
 }
 
 bool AndroidStorageAdapterCpp::hasSecureBiometric(const std::string& key) {
-    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jboolean(std::string)>("hasSecureBiometric");
-    return method(AndroidStorageAdapterJava::javaClassStatic(), key);
+    static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jboolean(alias_ref<JString>)>("hasSecureBiometric");
+    return method(AndroidStorageAdapterJava::javaClassStatic(), toJavaString(key));
 }
 
 void AndroidStorageAdapterCpp::clearSecureBiometric() {

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

@@ -103,9 +103,9 @@ internal class DiskSqliteStore(
     fun getKeysByPrefix(prefix: String): Array<String> {
         val pattern = buildString {
             for (character in prefix) {
-                if (character == '%' || character == '_' || character == '\\') {
-                    append('\\')
-                }
+                // LIKE stops at NUL; startsWith below checks the complete prefix.
+                if (character == '\u0000') break
+                if (character == '%' || character == '_' || character == '\\') append('\\')
                 append(character)
             }
             append('%')
@@ -116,7 +116,10 @@ internal class DiskSqliteStore(
         ).use { cursor ->
             val keys = ArrayList<String>(cursor.count)
             while (cursor.moveToNext()) {
-                keys.add(cursor.getString(0))
+                val key = cursor.getString(0)
+                if (key.startsWith(prefix)) {
+                    keys.add(key)
+                }
             }
             return keys.toTypedArray()
         }

package/cpp/core/SqliteDiskStore.cpp

@@ -44,12 +44,14 @@ void bindText(sqlite3_stmt* stmt, int index, const std::string& value) {
 
 std::string escapeLikePrefix(const std::string& prefix) {
     std::string escaped;
-    escaped.reserve(prefix.size());
-    for (const unsigned char character : prefix) {
+    escaped.reserve(prefix.size() + 1);
+    for (const char character : prefix) {
+        // SQLite LIKE stops at NUL; exact filtering below handles the full key.
+        if (character == '\0') break;
         if (character == '%' || character == '_' || character == '\\') {
             escaped.push_back('\\');
         }
-        escaped.push_back(static_cast<char>(character));
+        escaped.push_back(character);
     }
     escaped.push_back('%');
     return escaped;
@@ -336,8 +338,7 @@ std::vector<std::string> SqliteDiskStore::getKeysByPrefix(const std::string& pre
     std::lock_guard<std::mutex> lock(mutex_);
     sqlite3_reset(prefixStmt_);
     sqlite3_clear_bindings(prefixStmt_);
-    const std::string pattern = escapeLikePrefix(prefix);
-    bindText(prefixStmt_, 1, pattern);
+    bindText(prefixStmt_, 1, escapeLikePrefix(prefix));
     std::vector<std::string> keys;
     while (true) {
         const int rc = sqlite3_step(prefixStmt_);
@@ -350,10 +351,13 @@ std::vector<std::string> SqliteDiskStore::getKeysByPrefix(const std::string& pre
         }
         const unsigned char* text = sqlite3_column_text(prefixStmt_, 0);
         const int bytes = sqlite3_column_bytes(prefixStmt_, 0);
-        keys.emplace_back(
+        std::string key(
             text != nullptr ? reinterpret_cast<const char*>(text) : "",
             static_cast<size_t>(bytes)
         );
+        if (key.compare(0, prefix.size(), prefix) == 0) {
+            keys.push_back(std::move(key));
+        }
     }
     sqlite3_reset(prefixStmt_);
     return keys;

package/docs/benchmarks.md

@@ -44,3 +44,40 @@ bun run --cwd packages/react-native-nitro-storage check:pack
 ```
 
 Keep the dry-publish output in the release notes when validating a version locally.
+
+## 2026-09-27 Memory enumeration experiment
+
+Command: `bun run benchmark:enumeration`. The smoke form, `bun run benchmark:enumeration -- --smoke`, validates fixture execution only.
+
+Host: Apple M4 Pro, darwin 27.0.0, Bun 1.4.2. This uses the actual web Memory implementation, not native SQLite or JSI. Each run contains five batches of 30 warm samples per operation and size. Every output key/value is checked outside the timed interval.
+
+The comparison starts from the correctness-fixed implementation, not the original release, whose arbitrary-key behavior failed the fixture. It therefore does not establish an overall speedup over the published version.
+
+The accepted iteration change removes the repeated Map lookup in `getAll` and the intermediate prefix-key array. Two separate process runs produced these median changes versus the corrected baseline (negative is faster):
+
+| Keys    | Operation     | Run 1  | Run 2  |
+| ------- | ------------- | ------ | ------ |
+| 1,000   | `getAll`      | -10.6% | -14.2% |
+| 1,000   | `getByPrefix` | -8.4%  | -3.7%  |
+| 10,000  | `getAll`      | -10.4% | -7.4%  |
+| 10,000  | `getByPrefix` | -10.2% | -9.7%  |
+| 100,000 | `getAll`      | -47.5% | -47.8% |
+| 100,000 | `getByPrefix` | -12.2% | -6.9%  |
+
+Only the 100k-key `getAll` result clearly and repeatedly exceeds the proposed 10% target: median improved about 47%, with median batch p95 improving 43–48%. Smaller results vary and do not establish repeatable gains above the target.
+
+Peak process RSS was 318/339 MB for the corrected baseline and 400/340 MB for the candidate (decimal MB). This high-water metric was noisy and triggers review; source review found no added retained collection or cache. It does not prove equal allocation cost. Native/device performance and retained-memory profiling remain separate acceptance evidence.
+
+An earlier ordinary-property shortcut was reverted after a 10k-key regression. An entry-tuple iteration candidate was replaced after elevated peak RSS.
+
+Fixture SHA-256: `1ec2feb7ff55d5c61f33e4f70948336ca97d0a7746a77d9c295d7ae4417463f6`. Lockfile SHA-256: `1a6a54f48038afa313fb8a8316611f2091edf8a133bcc16173836599f1831492`. Corrected core SHA-256: `f7e8687b69d93a0fec8318877e6227b8b42ee617b68a257a17e33f83f4492b17`. Candidate core SHA-256: `e8b68c5bb3305b07eeaaff609381ec28ab564424a8fdbb53a8014f6460b6c86e`.
+
+Raw reports and environment: `/tmp/nitro-implementation.GbjgqhYj/storage-enumeration-v2-{corrected,candidate3}{,-repeat}.json` and `storage-enumeration-environment.json` on the execution host. These temporary receipts are not portable release artifacts; the table above preserves the selected results. No device or universal speed claim is made.
+
+### Original-release control and rejected prefix experiment
+
+The additional `--ordinary` mode omits the special prototype key so the original 0.10.3 source and the corrected source can produce identical valid output. Two quiet process comparisons against the archived original revision measured 100k-key `getAll` median improvement of about 42%, with batch p95 improving 43–45%. This is a host web-Memory result only. The correctness-fixed `getByPrefix` was 17–20% slower at 100k keys and 15–23% slower at 1k; no overall prefix speedup is claimed.
+
+A subsequent direct prefix scan preserved the observer path and passed independent source review, but was rejected: although 100k prefix medians improved 26–28% against the original, 1k medians regressed 66–67%. The final implementation retains the prior iteration change. The observer mutation/order regression test remains as coverage. Correctness and predictable small-workload behavior take priority over the large-workload result.
+
+Original-control receipts: `storage-ordinary-{original,final}{,-repeat}.json` in the evidence directory above (`final` denotes retained candidate3). Rejected-experiment receipts: `storage-ordinary-candidate4{,-repeat}.json`. The ordinary-mode harness extends the fixture; its hash differs from the default-only fixture recorded above. Neither these comparisons nor peak process RSS establish native latency, retained-memory equivalence, or a universal improvement.