fix: load Mocha browser runtime after upgrading to v12

Author: chrispader

.github/workflows/release.yml

@@ -96,6 +96,12 @@ jobs:
           }
           NODE
 
+      - name: Generate release notes
+        run: node scripts/generate-release-notes.ts "$RELEASE_VERSION" "$RUNNER_TEMP/release-notes.md"
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_VERSION: ${{ inputs.version }}
+
       - name: Publish prepared release
         run: ./scripts/release.sh --publish-prepared "$RELEASE_VERSION"
         env:
@@ -110,14 +116,7 @@ jobs:
           if [[ "${version%%.*}" == 9 ]]; then
             latest=false
           fi
-          notes="docs/releases/v${version}.md"
-          args=("v${version}" --target "$(git rev-parse HEAD)" --title "NitroSQLite ${version}" --latest="$latest")
-          if [ -f "$notes" ]; then
-            args+=(--notes-file "$notes")
-          else
-            args+=(--generate-notes)
-          fi
-          gh release create "${args[@]}"
+          gh release create "v${version}" --target "$(git rev-parse HEAD)" --title "NitroSQLite ${version}" --latest="$latest" --notes-file "$RUNNER_TEMP/release-notes.md"
         env:
           GH_TOKEN: ${{ github.token }}
           RELEASE_VERSION: ${{ inputs.version }}

.github/workflows/test-harness-ios.yml

@@ -60,6 +60,25 @@ jobs:
       - name: Select Xcode 26.2
         run: sudo xcode-select -s "/Applications/Xcode_26.2.app/Contents/Developer"
 
+      - name: Start iOS simulator
+        run: |
+          set -euo pipefail
+
+          simulator="$(xcrun simctl list devices available --json | node -e '
+            const { readFileSync } = require("node:fs")
+            const runtime = `com.apple.CoreSimulator.SimRuntime.iOS-${process.env.IOS_SIMULATOR_OS.replaceAll(".", "-")}`
+            const devices = JSON.parse(readFileSync(0, "utf8")).devices[runtime] ?? []
+            const device = devices.find((candidate) => candidate.name === process.env.IOS_SIMULATOR_NAME && candidate.isAvailable)
+            if (!device) throw new Error(`Simulator ${process.env.IOS_SIMULATOR_NAME} on ${runtime} is unavailable`)
+            console.log(`${device.udid} ${device.state}`)
+          ')"
+          read -r simulator_udid simulator_state <<< "$simulator"
+          echo "IOS_SIMULATOR_UDID=$simulator_udid" >> "$GITHUB_ENV"
+
+          if [[ "$simulator_state" == "Shutdown" ]]; then
+            xcrun simctl boot "$simulator_udid"
+          fi
+
       - name: Install Pods
         working-directory: example
         run: bun pods
@@ -80,8 +99,14 @@ jobs:
             build \
             CODE_SIGNING_ALLOWED=NO
 
+      - name: Wait for iOS simulator
+        timeout-minutes: 10
+        run: xcrun simctl bootstatus "$IOS_SIMULATOR_UDID" -b
+
       - name: Run react-native-harness on iOS
         uses: callstackincubator/react-native-harness@v1.5.0
+        env:
+          HARNESS_DEBUG: "1"
         with:
           app: ios/build/Build/Products/Debug-iphonesimulator/NitroSQLiteExample.app
           runner: ios

README.md

@@ -10,6 +10,8 @@
 
 Nitro SQLite is a SQLite library for React Native on iOS, macOS, visionOS, and Android, built with [Nitro Modules](https://nitro.margelo.com/). It provides synchronous and asynchronous queries, transactions, and batch operations.
 
+The bundled SQLite build enables [R\*Tree indexes](https://sqlite.margelo.com/docs/concepts/queries-and-indexes#query-spatial-ranges) by default on Apple platforms and Android. Set `nitroSQLite.enableRTree` to `false` in your app's `package.json` to omit it from the native build.
+
 **[Read the documentation](https://sqlite.margelo.com/docs)** for setup, guides, integrations, and the API reference.
 
 If you use a coding agent, give it the [NitroSQLite skill](https://github.com/margelo/react-native-skills/blob/nitro-sqlite/skills/react-native-nitro-sqlite/SKILL.md). It links to focused guidance for connections, queries, transactions, concurrency, and migration. See the [AI agent guide](https://sqlite.margelo.com/docs/guides/ai-agents) for what to check in generated code.

bun.lock

@@ -33,3 +33,44 @@ db.close()
 ```
 
 Bind application values with `?`; placeholders cannot stand in for table or column names. Add an index for a query you actually run, then inspect its plan with representative data. [Parameters and results](/docs/guides/parameters-and-results) describes returned rows, and the [performance guide](/docs/guides/performance) covers keeping large reads bounded.
+
+## Query spatial ranges
+
+An R\*Tree index stores bounding boxes and finds those that overlap a query box. Use it for queries such as finding places inside a map viewport or events that overlap a time interval. A normal B-tree index orders values by its columns; an R\*Tree can narrow a search across several independent coordinate ranges. Bounding boxes can include candidates outside an object's exact geometry, so apply an exact check when your query requires one. See [SQLite's R\*Tree documentation](https://www.sqlite.org/rtree.html).
+
+Nitro SQLite's bundled build includes `rtree` and `rtree_i32` by default. You still create the virtual table and populate it explicitly. Enabling the module does not create indexes or change queries against ordinary tables.
+
+```ts
+import { open } from 'react-native-nitro-sqlite'
+
+const db = open({ name: 'places.sqlite' })
+
+await db.executeAsync(`
+  CREATE VIRTUAL TABLE IF NOT EXISTS place_bounds USING rtree(
+    id,
+    minLongitude, maxLongitude,
+    minLatitude, maxLatitude
+  )
+`)
+await db.executeAsync(
+  'INSERT OR REPLACE INTO place_bounds VALUES (?, ?, ?, ?, ?)',
+  [1, 16.36, 16.38, 48.2, 48.22],
+)
+
+const { rows } = await db.executeAsync<{ id: number }>(
+  `SELECT id FROM place_bounds
+   WHERE minLongitude <= ? AND maxLongitude >= ?
+     AND minLatitude <= ? AND maxLatitude >= ?`,
+  [16.4, 16.35, 48.23, 48.19],
+)
+console.log(rows._array) // [{ id: 1 }]
+db.close()
+```
+
+If you store the same objects in an ordinary table, keep their bounding boxes in sync through triggers or updates in the same transaction. R\*Tree data takes storage and adds work to writes. Its storage and index maintenance apply to the tables you create, rather than every database opened by an app that includes the module.
+
+`rtree` stores coordinates as 32-bit floats and rounds lower bounds down and upper bounds up. Overlap queries can return extra candidates. Containment queries can miss an entry at an edge unless you expand the query box as described in [SQLite's roundoff guidance](https://www.sqlite.org/rtree.html#roundoff_error). Use `rtree_i32` for signed 32-bit integer coordinates. Both support one to five dimensions.
+
+A write can restructure an active R\*Tree scan and fail with `SQLITE_LOCKED`. Nitro SQLite's execution methods, including prepared statement execution, read the complete result before returning, so a completed read does not leave that scan open.
+
+For apps that do not need R\*Tree, set `nitroSQLite.enableRTree` to `false` in the app's `package.json` and rebuild the native app. See [Apple configuration](/docs/configuration/ios#rtree-support) or [Android configuration](/docs/configuration/android#rtree-support). Disabling it makes R\*Tree tables unavailable. Queries and schema migrations involving those tables can fail with `no such module: rtree`, including a rename of an ordinary table referenced by a view that also uses R\*Tree. System SQLite support depends on the operating system's build.

docs/content/docs/concepts/queries-and-indexes.mdx

@@ -19,15 +19,31 @@ Set `nitroSqliteFlags` in the app's `android/gradle.properties` to pass definiti
 nitroSqliteFlags="-DSQLITE_ENABLE_FTS5=1"
 ```
 
-These are SQLite compile definitions, so they affect the bundled source when the native library is rebuilt. Android does not use the iOS `nitroSQLite` package settings or the `NITRO_SQLITE_USE_PHONE_VERSION` pod switch.
+These are SQLite compile definitions, so they affect the bundled source when the native library is rebuilt. The Apple `NITRO_SQLITE_USE_PHONE_VERSION` pod switch does not apply to Android.
 
 To use the licensed SQLite Encryption Extension, follow [encrypt a database](/docs/guides/encryption) for the matching source files, symbol prefix, and `SQLITE_ENABLE_SEE` flag.
 
+## RTree support
+
+R\*Tree indexes find bounding boxes that overlap a spatial or time range. The bundled SQLite build includes `rtree` and `rtree_i32` by default. See [query spatial ranges](/docs/concepts/queries-and-indexes#query-spatial-ranges) for SQL examples and limitations.
+
+To omit R\*Tree from the bundled build, set this boolean in your app's `package.json` and rebuild the native app:
+
+```json
+{
+  "nitroSQLite": {
+    "enableRTree": false
+  }
+}
+```
+
+`enableRTree` defaults to `true` independently of `performanceMode`. A non-boolean value fails Gradle configuration. Disabling it omits the default `SQLITE_ENABLE_RTREE` definition. Do not add `-DSQLITE_ENABLE_RTREE=0` to `nitroSqliteFlags` to disable it: SQLite checks whether the macro is defined, so that value still enables the module. Custom compile definitions can enable the module even when the package setting is `false`.
+
 ## Threading
 
 The native library opens each database with `SQLITE_OPEN_FULLMUTEX` and serializes calls on each handle. The JavaScript connection helper coordinates work per managed connection and rejects conflicting synchronous work. `nitroSqliteFlags` can change compile-time SQLite behavior, including `SQLITE_THREADSAFE`. Nitro SQLite rejects [independent connections](/docs/guides/multiple-connections) when SQLite was built with `SQLITE_THREADSAFE=0`; other database handles can still run concurrently, so an app disabling mutexes must serialize SQLite calls across the process.
 
-Android has no separate `performanceMode` Gradle property. Its native build always applies its CMake compiler options, including `-O2`. The iOS `performanceMode` package key does not configure Android.
+The app's `nitroSQLite.threadSafe` and `nitroSQLite.performanceMode` settings also configure Android's SQLite defaults. Custom `nitroSqliteFlags` override individual defaults. The native build additionally applies its CMake compiler options, including `-O2`.
 
 ## Vector search
 

docs/content/docs/configuration/android.mdx

@@ -39,6 +39,22 @@ NITRO_SQLITE_USE_PHONE_VERSION=1 npx pod-install
 
 The bundled source is where the pod's compile settings apply. Changing the pod's `SQLITE_THREADSAFE` or performance flags cannot change how the system library was built.
 
+## RTree support
+
+R\*Tree indexes find bounding boxes that overlap a spatial or time range. The bundled SQLite build includes `rtree` and `rtree_i32` by default on iOS, macOS, and visionOS. See [query spatial ranges](/docs/concepts/queries-and-indexes#query-spatial-ranges) for SQL examples and limitations.
+
+To omit R\*Tree from the bundled build, set this boolean in your app's `package.json`, install Pods again, and rebuild:
+
+```json
+{
+  "nitroSQLite": {
+    "enableRTree": false
+  }
+}
+```
+
+`enableRTree` defaults to `true` independently of `performanceMode`. A non-boolean value fails Pod installation. Disabling it omits `SQLITE_ENABLE_RTREE`; defining that macro as `0` still enables SQLite's module. This setting cannot change system SQLite's capabilities when you use `NITRO_SQLITE_USE_PHONE_VERSION=1`.
+
 ## Thread safety and performance mode
 
 The bundled SQLite build defaults to `SQLITE_THREADSAFE=1` and enables the project's performance compile flags. Set either option in the app's `package.json`:

docs/content/docs/configuration/ios.mdx

@@ -17,4 +17,4 @@ The repository's macOS example targets macOS 14 or later with React Native macOS
 
 To keep Metro in a separate terminal, run the `start` script in `example/macos` and launch the `macos` script with `--no-packager`. Pass `--mode Release --no-packager` to build and launch the production bundle.
 
-The [iOS configuration guide](/docs/configuration/ios) describes the shared Apple build flags for bundled SQLite, thread safety, performance mode, and vector search. Run CocoaPods from `macos` when applying those settings to a macOS app.
+The [iOS configuration guide](/docs/configuration/ios) describes the shared Apple build flags for bundled SQLite, R\*Tree, thread safety, performance mode, and vector search. Run CocoaPods from `macos` when applying those settings to a macOS app.

docs/content/docs/configuration/macos.mdx

@@ -0,0 +1,21 @@
+NitroSQLite 10.1.0 adds opt-in SQLite SEE encryption support and a Node.js mock backed by better-sqlite3. We've improved repeated batch execution and query-result conversion, upgraded bundled SQLite to 3.53.4, and enabled RTree indexes by default. This release includes the connection ownership fix shipped in 10.0.1, along with the newer changes on main.
+
+## Encryption and Node.js testing
+
+You can now pass an encryption key when opening a database built with the licensed SQLite Encryption Extension. SEE source is not bundled with NitroSQLite; enabling it requires your licensed source and a native rebuild. See the [encryption guide](https://sqlite.margelo.com/docs/guides/encryption) for setup and key handling. [#410](https://github.com/margelo/react-native-nitro-sqlite/pull/410)
+
+The new `react-native-nitro-sqlite/mock` entry point runs against better-sqlite3 in Node.js. It supports independent connections, prepared statements, transactions, and batches for tests that need a real SQLite engine. Install better-sqlite3 separately when using the mock. [#395](https://github.com/margelo/react-native-nitro-sqlite/pull/395), [#420](https://github.com/margelo/react-native-nitro-sqlite/pull/420)
+
+## Query performance and SQLite support
+
+Grouped batch parameters reuse a prepared statement for repeated executions of the same SQL. Query results also avoid an extra native row copy during conversion to JavaScript. [#387](https://github.com/margelo/react-native-nitro-sqlite/pull/387), [#389](https://github.com/margelo/react-native-nitro-sqlite/pull/389)
+
+Bundled SQLite is now 3.53.4, and its symbols are isolated from other SQLite engines linked into the same app. RTree is enabled by default for spatial and range indexes. See the [queries and indexes guide](https://sqlite.margelo.com/docs/concepts/queries-and-indexes). [#392](https://github.com/margelo/react-native-nitro-sqlite/pull/392), [#390](https://github.com/margelo/react-native-nitro-sqlite/pull/390), [#425](https://github.com/margelo/react-native-nitro-sqlite/pull/425)
+
+## Reliability and upgrading
+
+Connections close with the NitroSQLite owner that opened them, so replacing a runtime can reopen the same database. We've also improved transaction cleanup and error reporting, restored `undefined` parameters as SQL NULL, preserved embedded NUL bytes in text results, and corrected column metadata types. Android temporary files now use the app cache. The changelog below links each fix.
+
+Update both packages to 10.1.0 if you use sqlite-vec, install Pods again on Apple platforms, and rebuild your native app. SQLite 3.53 changes floating-point-to-text conversion from 15 to 17 significant digits, so check code that depends on exact SQL text formatting. The TypeORM dependency is now 1.1.1. [#426](https://github.com/margelo/react-native-nitro-sqlite/pull/426)
+
+The [documentation website](https://sqlite.margelo.com/docs) now includes guides and a generated API reference.

docs/releases/v10.1.0.md

@@ -2222,8 +2222,8 @@ SPEC CHECKSUMS:
   ReactCommon: 749169e12aa3461a3df3656a00e48dbe0456b2d6
   ReactNativeDependencies: 94c922c39e0e6150ee9ad05e2ca1946e0ef55783
   RNCClipboard: e706ef7ccbbfd69f829c1b683f893bc7668c9fdb
-  RNNitroSQLite: 7a3bc04bf9db485a4b88f308f5c0de186b39dfb0
-  RNNitroSqliteVec: b776070e72840e921c4c66ff264f035191d86b78
+  RNNitroSQLite: 119ba2dae35083ed5306594ad99cf5d4d7e100c0
+  RNNitroSqliteVec: 0c255fb910dbcea6c77ab22a9b9b2e10cefdc7f0
   RNScreens: 3c977859fd13e67dc4ebfc24afb4d7c2e894db61
   SocketRocket: 37aec555668fb852ec12e3c0de59a86ca58f0871
   Yoga: d1c536142c5ff8ec8cd856ab2a7c227a1d875c8e