react-native-nitro-storage 0.10.2 → 0.10.4

package/CHANGELOG.md

@@ -6,6 +6,51 @@ 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
+
+- None.
+
+### Added
+
+- `storage.getCacheMetrics()` reports live Disk/Secure raw-cache hits, misses,
+  entries, and estimated bytes. The cache stays unbounded; reset zeros the
+  counters only.
+- Example integrity, keychain, and Disk/Secure stress labs at
+  `nitrostorage://e2e-integrity`, `nitrostorage://e2e-keychain`, and
+  `nitrostorage://e2e-stress`.
+- Native Disk now uses SQLite WAL (`SqliteDiskStore` on iOS, `DiskSqliteStore`
+  on Android). Existing UserDefaults suite keys and `NitroStorage`
+  SharedPreferences values are imported once. See
+  [docs/native-libraries.md](docs/native-libraries.md).
+
+### Changed
+
+- The example Expo pin follows SDK 57.0.24 (`expo-doctor` / `expo install --check`).
+  React Native stays `0.86.3`.
+- The example iOS host uses a `SceneDelegate` so the app can present a window on
+  iOS 27 physical devices.
+
+### Fixed
+
+- Android Disk no longer crashes on first open when enabling SQLite WAL:
+  `PRAGMA journal_mode=WAL` is applied with `rawQuery` instead of `execSQL`.
+
 ## [0.10.2] - 2026-09-10
 
 ### 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.21`, 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.2
+bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.10.4
 bunx expo prebuild
 ```
 
@@ -387,11 +388,31 @@ const tokenActions = useStorageActions(tokenItem); // { set, merge, reset, remov
 
 ## Storage Scopes
 
-| Scope                 | Backing store                                          | Use it for                                                                   |
-| --------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
-| `StorageScope.Memory` | In-process memory                                      | Session-only state, fast counters, and render-time caches.                   |
-| `StorageScope.Disk`   | UserDefaults on iOS, SharedPreferences on Android, web | 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.     |
+| Scope                 | Backing store                                                                                     | Use it for                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `StorageScope.Memory` | In-process memory                                                                                 | Session-only state, fast counters, and render-time caches.                   |
+| `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
 
@@ -520,13 +541,21 @@ storage.setMetricsObserver((event) => {
 
 const metrics = storage.getMetricsSnapshot();
 const scopedMetrics = storage.getScopedMetricsSnapshot();
+const cacheMetrics = storage.getCacheMetrics();
 storage.resetMetrics();
 unsubscribe();
 ```
 
 `getMetricsSnapshot()` aggregates each operation across scopes for backward
 compatibility. `getScopedMetricsSnapshot()` adds the numeric scope suffix for
-per-scope analysis, for example `item:set:1`.
+per-scope analysis, for example `item:set:1`. `getCacheMetrics()` reports live
+Disk/Secure raw-cache hits, misses, entries, and estimated bytes. The cache is
+unbounded; `resetMetrics()` zeros the hit/miss counters and leaves entries in
+place.
+
+The example app includes hidden integrity, keychain, and Disk/Secure stress
+labs at `nitrostorage://e2e-integrity`, `nitrostorage://e2e-keychain`, and
+`nitrostorage://e2e-stress`.
 
 Secure event observer values are redacted by default. Pass
 `{ redactSecureValues: false }` only in trusted debug tooling where raw values
@@ -674,6 +703,7 @@ the error for diagnostics.
 | Web backends                        | [docs/web-backends.md](docs/web-backends.md)                                   |
 | Batch, transactions, and migrations | [docs/batch-transactions-migrations.md](docs/batch-transactions-migrations.md) |
 | MMKV migration                      | [docs/mmkv-migration.md](docs/mmkv-migration.md)                               |
+| Native libraries                    | [docs/native-libraries.md](docs/native-libraries.md)                           |
 | Recipes                             | [docs/recipes.md](docs/recipes.md)                                             |
 | Benchmarks                          | [docs/benchmarks.md](docs/benchmarks.md)                                       |
 | Security policy                     | [SECURITY.md](SECURITY.md)                                                     |

package/android/CMakeLists.txt

@@ -13,6 +13,8 @@ file(GLOB SOURCES
 )
 # Unit/integration C++ tests define `main()` and must never be linked into the Android shared library.
 list(FILTER SOURCES EXCLUDE REGEX ".*/[^/]*Test\\.cpp$")
+# iOS/macOS Disk SQLite lives in this translation unit; Android uses DiskSqliteStore.kt.
+list(FILTER SOURCES EXCLUDE REGEX ".*/SqliteDiskStore\\.cpp$")
 
 # 2. Create the library target
 add_library(

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/AndroidStorageAdapter.kt

@@ -61,6 +61,7 @@ private fun Throwable.wrapStorageException(
 class AndroidStorageAdapter private constructor(private val context: Context) {
     private val sharedPreferences: SharedPreferences =
         context.getSharedPreferences("NitroStorage", Context.MODE_PRIVATE)
+    private val diskStore: DiskSqliteStore = DiskSqliteStore(context, sharedPreferences)
 
     private val masterKeyAlias = "${context.packageName}.nitro_storage.master_key"
 
@@ -519,71 +520,57 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
 
         @JvmStatic
         fun setDisk(key: String, value: String) {
-            getInstanceOrThrow().sharedPreferences.edit().putString(key, value).apply()
+            getInstanceOrThrow().diskStore.set(key, value)
         }
 
         @JvmStatic
         fun setDiskBatch(keys: Array<String>, values: Array<String>) {
-            val editor = getInstanceOrThrow().sharedPreferences.edit()
-            val count = minOf(keys.size, values.size)
-            for (index in 0 until count) {
-                editor.putString(keys[index], values[index])
-            }
-            editor.apply()
+            getInstanceOrThrow().diskStore.setBatch(keys, values)
         }
 
         @JvmStatic
         fun getDisk(key: String): String? {
-            return getInstanceOrThrow().sharedPreferences.getString(key, null)
+            return getInstanceOrThrow().diskStore.get(key)
         }
 
         @JvmStatic
         fun getDiskBatch(keys: Array<String>): Array<String?> {
-            val prefs = getInstanceOrThrow().sharedPreferences
-            return Array(keys.size) { index ->
-                prefs.getString(keys[index], null)
-            }
+            return getInstanceOrThrow().diskStore.getBatch(keys)
         }
 
         @JvmStatic
         fun deleteDisk(key: String) {
-            getInstanceOrThrow().sharedPreferences.edit().remove(key).apply()
+            getInstanceOrThrow().diskStore.remove(key)
         }
 
         @JvmStatic
         fun deleteDiskBatch(keys: Array<String>) {
-            val editor = getInstanceOrThrow().sharedPreferences.edit()
-            for (key in keys) {
-                editor.remove(key)
-            }
-            editor.apply()
+            getInstanceOrThrow().diskStore.removeBatch(keys)
         }
 
         @JvmStatic
         fun hasDisk(key: String): Boolean {
-            return getInstanceOrThrow().sharedPreferences.contains(key)
+            return getInstanceOrThrow().diskStore.has(key)
         }
 
         @JvmStatic
         fun getAllKeysDisk(): Array<String> {
-            return getInstanceOrThrow().sharedPreferences.all.keys.toTypedArray()
+            return getInstanceOrThrow().diskStore.getAllKeys()
         }
 
         @JvmStatic
         fun getKeysByPrefixDisk(prefix: String): Array<String> {
-            return getInstanceOrThrow().sharedPreferences.all.keys
-                .filter { it.startsWith(prefix) }
-                .toTypedArray()
+            return getInstanceOrThrow().diskStore.getKeysByPrefix(prefix)
         }
 
         @JvmStatic
         fun sizeDisk(): Int {
-            return getInstanceOrThrow().sharedPreferences.all.size
+            return getInstanceOrThrow().diskStore.size()
         }
 
         @JvmStatic
         fun clearDisk() {
-            getInstanceOrThrow().sharedPreferences.edit().clear().apply()
+            getInstanceOrThrow().diskStore.clear()
         }
 
         // --- Secure (async apply by default, sync commit when requested) ---

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

@@ -0,0 +1,174 @@
+package com.nitrostorage
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.database.sqlite.SQLiteDatabase
+import java.io.File
+
+internal class DiskSqliteStore(
+    context: Context,
+    private val legacyPreferences: SharedPreferences,
+) {
+    private val db: SQLiteDatabase
+
+    init {
+        val file = File(context.filesDir, DATABASE_NAME)
+        db = SQLiteDatabase.openOrCreateDatabase(file, null)
+        // PRAGMA journal_mode returns a row; Android forbids result-bearing SQL on execSQL.
+        db.rawQuery("PRAGMA journal_mode=WAL", null).close()
+        db.execSQL("PRAGMA synchronous=NORMAL")
+        db.execSQL(
+            "CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY NOT NULL, value TEXT NOT NULL)",
+        )
+        db.execSQL(
+            "CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY NOT NULL, v TEXT NOT NULL)",
+        )
+        migrateLegacyPreferences()
+    }
+
+    @Synchronized
+    fun set(key: String, value: String) {
+        db.execSQL(
+            "INSERT OR REPLACE INTO kv(key, value) VALUES(?, ?)",
+            arrayOf(key, value),
+        )
+    }
+
+    @Synchronized
+    fun get(key: String): String? {
+        db.rawQuery("SELECT value FROM kv WHERE key = ? LIMIT 1", arrayOf(key)).use { cursor ->
+            return if (cursor.moveToFirst()) cursor.getString(0) else null
+        }
+    }
+
+    @Synchronized
+    fun remove(key: String) {
+        db.execSQL("DELETE FROM kv WHERE key = ?", arrayOf(key))
+    }
+
+    @Synchronized
+    fun has(key: String): Boolean {
+        db.rawQuery("SELECT 1 FROM kv WHERE key = ? LIMIT 1", arrayOf(key)).use { cursor ->
+            return cursor.moveToFirst()
+        }
+    }
+
+    @Synchronized
+    fun setBatch(keys: Array<String>, values: Array<String>) {
+        val count = minOf(keys.size, values.size)
+        db.beginTransaction()
+        try {
+            for (index in 0 until count) {
+                db.execSQL(
+                    "INSERT OR REPLACE INTO kv(key, value) VALUES(?, ?)",
+                    arrayOf(keys[index], values[index]),
+                )
+            }
+            db.setTransactionSuccessful()
+        } finally {
+            db.endTransaction()
+        }
+    }
+
+    @Synchronized
+    fun getBatch(keys: Array<String>): Array<String?> {
+        return Array(keys.size) { index -> get(keys[index]) }
+    }
+
+    @Synchronized
+    fun removeBatch(keys: Array<String>) {
+        db.beginTransaction()
+        try {
+            for (key in keys) {
+                db.execSQL("DELETE FROM kv WHERE key = ?", arrayOf(key))
+            }
+            db.setTransactionSuccessful()
+        } finally {
+            db.endTransaction()
+        }
+    }
+
+    @Synchronized
+    fun getAllKeys(): Array<String> {
+        db.rawQuery("SELECT key FROM kv", null).use { cursor ->
+            val keys = ArrayList<String>(cursor.count)
+            while (cursor.moveToNext()) {
+                keys.add(cursor.getString(0))
+            }
+            return keys.toTypedArray()
+        }
+    }
+
+    @Synchronized
+    fun getKeysByPrefix(prefix: String): Array<String> {
+        val pattern = buildString {
+            for (character in prefix) {
+                // LIKE stops at NUL; startsWith below checks the complete prefix.
+                if (character == '\u0000') break
+                if (character == '%' || character == '_' || character == '\\') append('\\')
+                append(character)
+            }
+            append('%')
+        }
+        db.rawQuery(
+            "SELECT key FROM kv WHERE key LIKE ? ESCAPE '\\'",
+            arrayOf(pattern),
+        ).use { cursor ->
+            val keys = ArrayList<String>(cursor.count)
+            while (cursor.moveToNext()) {
+                val key = cursor.getString(0)
+                if (key.startsWith(prefix)) {
+                    keys.add(key)
+                }
+            }
+            return keys.toTypedArray()
+        }
+    }
+
+    @Synchronized
+    fun size(): Int {
+        db.rawQuery("SELECT COUNT(*) FROM kv", null).use { cursor ->
+            return if (cursor.moveToFirst()) cursor.getInt(0) else 0
+        }
+    }
+
+    @Synchronized
+    fun clear() {
+        db.execSQL("DELETE FROM kv")
+    }
+
+    private fun migrateLegacyPreferences() {
+        db.rawQuery(
+            "SELECT v FROM meta WHERE k = ? LIMIT 1",
+            arrayOf(PREFS_MIGRATION_KEY),
+        ).use { cursor ->
+            if (cursor.moveToFirst() && cursor.getString(0) == "1") {
+                return
+            }
+        }
+
+        db.beginTransaction()
+        try {
+            for ((key, value) in legacyPreferences.all) {
+                if (value is String) {
+                    db.execSQL(
+                        "INSERT OR IGNORE INTO kv(key, value) VALUES(?, ?)",
+                        arrayOf(key, value),
+                    )
+                }
+            }
+            db.execSQL(
+                "INSERT OR REPLACE INTO meta(k, v) VALUES(?, ?)",
+                arrayOf(PREFS_MIGRATION_KEY, "1"),
+            )
+            db.setTransactionSuccessful()
+        } finally {
+            db.endTransaction()
+        }
+    }
+
+    private companion object {
+        const val DATABASE_NAME = "nitro-storage-disk.sqlite"
+        const val PREFS_MIGRATION_KEY = "prefs_v1"
+    }
+}