react-native-nitro-storage 0.10.2 → 0.10.3

package/CHANGELOG.md

@@ -6,6 +6,37 @@ 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.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

@@ -68,7 +68,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.24`, 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 +77,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.3
 bunx expo prebuild
 ```
 
@@ -387,11 +387,11 @@ 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.     |
 
 ## Secure Storage
 
@@ -520,13 +520,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 +682,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/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,171 @@
+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) {
+                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()) {
+                keys.add(cursor.getString(0))
+            }
+            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"
+    }
+}