From 51ed4eb3ad536898de75a8faa976977800249f53 Mon Sep 17 00:00:00 2001 From: Christoph Pader Date: Mon, 16 Nov 2026 16:25:29 +0100 Subject: [PATCH] perf: send row batches to one registered handler Every managed executeAsync passed a new onRows callback to native code, even though native only calls it for results of 256 rows or more. Nitro converts each callback to a native function and keeps a weak reference to it in its JSI cache, which is never pruned. The managed API now sets one handler with setRowBatchHandler and passes a numeric row batch ID per query. Native builds without the handler still get a callback per query. Co-Authored-By: Claude Opus 5.5 --- docs/content/docs/guides/sync-and-async.mdx | 2 +- .../cpp/hybridObjects/HybridNitroSQLite.cpp | 16 ++++- .../cpp/hybridObjects/HybridNitroSQLite.hpp | 11 ++- .../shared/c++/HybridNitroSQLiteSpec.cpp | 1 + .../shared/c++/HybridNitroSQLiteSpec.hpp | 3 +- .../src/__mocks__/nitro.ts | 1 + .../src/__tests__/execute.test.ts | 55 +++++++++++++-- .../src/__tests__/session.test.ts | 9 ++- .../src/__tests__/transaction.test.ts | 6 +- .../src/operations/execute.ts | 68 ++++++++++++++++--- .../src/specs/NitroSQLite.nitro.ts | 13 ++++ 11 files changed, 157 insertions(+), 28 deletions(-) diff --git a/docs/content/docs/guides/sync-and-async.mdx b/docs/content/docs/guides/sync-and-async.mdx index 02428332..b0bbdf66 100644 --- a/docs/content/docs/guides/sync-and-async.mdx +++ b/docs/content/docs/guides/sync-and-async.mdx @@ -51,7 +51,7 @@ Global queries join the default connection's JavaScript queue when the name was Without a default managed connection, global `execute`, `executeAsync`, `executeRaw`, and `executeRawAsync` call the native methods directly and still need an open native database handle. Global `prepare`, batches, and transactions need a default connection opened through `open()`. -`NitroSQLite.native` exposes the underlying [`NitroSQLiteNative` hybrid object](/api/react-native-nitro-sqlite/hybrid-objects/NitroSQLiteNative). Its methods take a database name and return raw results without the connection helper's `rows` container. They also throw native errors without converting them to `NitroSQLiteError`. Its `executeAsync()` accepts an optional `onRows` callback that receives leading rows in batches, in order; the resolved `results` then holds only the rows after the last batch. +`NitroSQLite.native` exposes the underlying [`NitroSQLiteNative` hybrid object](/api/react-native-nitro-sqlite/hybrid-objects/NitroSQLiteNative). Its methods take a database name and return raw results without the connection helper's `rows` container. They also throw native errors without converting them to `NitroSQLiteError`. Its `executeAsync()` accepts an optional `onRows` callback that receives leading rows in batches, in order; the resolved `results` then holds only the rows after the last batch. The managed API sends those batches to one handler set with `setRowBatchHandler()` instead of passing a callback per query, so don't replace that handler while you also use the managed API. ```ts import { NitroSQLite } from 'react-native-nitro-sqlite' diff --git a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp index 342ba201..c8d531ee 100644 --- a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp +++ b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.cpp @@ -185,7 +185,8 @@ NitroSQLiteQueryResult HybridNitroSQLite::execute(const std::string& dbName, con std::shared_ptr> HybridNitroSQLite::executeAsync(const std::string& dbName, const std::string& query, const std::optional& params, - const std::optional& onRows) { + const std::optional& onRows, + std::optional rowBatchId) { const auto copiedParams = copyArrayBufferParamsForBackground(params); SQLiteConnectionPtr connection; try { @@ -194,12 +195,21 @@ std::shared_ptr> HybridNitroSQLite::executeAsync return Promise::rejected(std::current_exception()); } + SQLiteRowBatchHandler rowBatches = onRows.value_or(nullptr); + if (!rowBatches && rowBatchId && _rowBatchHandler) { + rowBatches = [handler = _rowBatchHandler, id = *rowBatchId](SQLiteQueryResults rows) { (*handler)(id, std::move(rows)); }; + } + return enqueueConnectionOperation( - connection, [connection, query, copiedParams, onRows = onRows.value_or(nullptr)]() -> NitroSQLiteQueryResult { - return sqliteExecute(connection, query, copiedParams, onRows); + connection, [connection, query, copiedParams, rowBatches = std::move(rowBatches)]() -> NitroSQLiteQueryResult { + return sqliteExecute(connection, query, copiedParams, rowBatches); }); }; +void HybridNitroSQLite::setRowBatchHandler(const std::function& handler) { + _rowBatchHandler = std::make_shared>(handler); +} + NitroSQLiteRawQueryResult HybridNitroSQLite::executeRaw(const std::string& dbName, const std::string& query, const std::optional& params) { return sqliteExecuteRaw(_connections.get(dbName), query, params); diff --git a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.hpp b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.hpp index 72c9f6f2..a87c2f54 100644 --- a/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.hpp +++ b/packages/react-native-nitro-sqlite/cpp/hybridObjects/HybridNitroSQLite.hpp @@ -25,6 +25,8 @@ class HybridNitroSQLite : public HybridNitroSQLiteSpec { private: DatabaseConnections _connections; + // Set and read on the JavaScript thread; queries copy the pointer for their worker. + std::shared_ptr> _rowBatchHandler; public: // Methods @@ -66,12 +68,17 @@ class HybridNitroSQLite : public HybridNitroSQLiteSpec { NitroSQLiteQueryResult execute(const std::string& dbName, const std::string& query, const std::optional& params) override; - /** Execute one SQL statement on a background thread. + /** Execute one SQL statement on a background thread. Leading row batches go to @p onRows, or else to + * the handler from setRowBatchHandler, tagged with @p rowBatchId. * @return A promise of the native query result. */ std::shared_ptr> executeAsync(const std::string& dbName, const std::string& query, const std::optional& params, - const std::optional& onRows) override; + const std::optional& onRows, + std::optional rowBatchId) override; + + /** Set the handler that receives row batches for executeAsync calls made with a row batch ID. */ + void setRowBatchHandler(const std::function& handler) override; /** Execute one SQL statement on the calling thread, returning rows as arrays of column values. */ NitroSQLiteRawQueryResult executeRaw(const std::string& dbName, const std::string& query, diff --git a/packages/react-native-nitro-sqlite/nitrogen/generated/shared/c++/HybridNitroSQLiteSpec.cpp b/packages/react-native-nitro-sqlite/nitrogen/generated/shared/c++/HybridNitroSQLiteSpec.cpp index 43140bc7..b41c08bd 100644 --- a/packages/react-native-nitro-sqlite/nitrogen/generated/shared/c++/HybridNitroSQLiteSpec.cpp +++ b/packages/react-native-nitro-sqlite/nitrogen/generated/shared/c++/HybridNitroSQLiteSpec.cpp @@ -23,6 +23,7 @@ namespace margelo::nitro::rnnitrosqlite { prototype.registerHybridMethod("detach", &HybridNitroSQLiteSpec::detach); prototype.registerHybridMethod("execute", &HybridNitroSQLiteSpec::execute); prototype.registerHybridMethod("executeAsync", &HybridNitroSQLiteSpec::executeAsync); + prototype.registerHybridMethod("setRowBatchHandler", &HybridNitroSQLiteSpec::setRowBatchHandler); prototype.registerHybridMethod("executeRaw", &HybridNitroSQLiteSpec::executeRaw); prototype.registerHybridMethod("executeRawAsync", &HybridNitroSQLiteSpec::executeRawAsync); prototype.registerHybridMethod("prepare", &HybridNitroSQLiteSpec::prepare); diff --git a/packages/react-native-nitro-sqlite/nitrogen/generated/shared/c++/HybridNitroSQLiteSpec.hpp b/packages/react-native-nitro-sqlite/nitrogen/generated/shared/c++/HybridNitroSQLiteSpec.hpp index 6d57a01f..60200821 100644 --- a/packages/react-native-nitro-sqlite/nitrogen/generated/shared/c++/HybridNitroSQLiteSpec.hpp +++ b/packages/react-native-nitro-sqlite/nitrogen/generated/shared/c++/HybridNitroSQLiteSpec.hpp @@ -82,7 +82,8 @@ namespace margelo::nitro::rnnitrosqlite { virtual void attach(const std::string& mainDbName, const std::string& dbNameToAttach, const std::string& alias, const std::optional& location) = 0; virtual void detach(const std::string& mainDbName, const std::string& alias) = 0; virtual NitroSQLiteQueryResult execute(const std::string& dbName, const std::string& query, const std::optional, std::string, double>>>>& params) = 0; - virtual std::shared_ptr> executeAsync(const std::string& dbName, const std::string& query, const std::optional, std::string, double>>>>& params, const std::optional>& onRows) = 0; + virtual std::shared_ptr> executeAsync(const std::string& dbName, const std::string& query, const std::optional, std::string, double>>>>& params, const std::optional>& onRows, std::optional rowBatchId) = 0; + virtual void setRowBatchHandler(const std::function& handler) = 0; virtual NitroSQLiteRawQueryResult executeRaw(const std::string& dbName, const std::string& query, const std::optional, std::string, double>>>>& params) = 0; virtual std::shared_ptr> executeRawAsync(const std::string& dbName, const std::string& query, const std::optional, std::string, double>>>>& params) = 0; virtual std::shared_ptr prepare(const std::string& dbName, const std::string& query) = 0; diff --git a/packages/react-native-nitro-sqlite/src/__mocks__/nitro.ts b/packages/react-native-nitro-sqlite/src/__mocks__/nitro.ts index 9309d54f..091289f0 100644 --- a/packages/react-native-nitro-sqlite/src/__mocks__/nitro.ts +++ b/packages/react-native-nitro-sqlite/src/__mocks__/nitro.ts @@ -8,6 +8,7 @@ export const HybridNitroSQLite = { detach: jest.fn(), execute: jest.fn(), executeAsync: jest.fn(), + setRowBatchHandler: jest.fn(), executeRaw: jest.fn(), executeRawAsync: jest.fn(), prepare: jest.fn(), diff --git a/packages/react-native-nitro-sqlite/src/__tests__/execute.test.ts b/packages/react-native-nitro-sqlite/src/__tests__/execute.test.ts index 80fc2476..1fc57b01 100644 --- a/packages/react-native-nitro-sqlite/src/__tests__/execute.test.ts +++ b/packages/react-native-nitro-sqlite/src/__tests__/execute.test.ts @@ -16,6 +16,16 @@ const dbName = 'execute-test' const query = 'SELECT ? AS value' const params = [7] +// The managed API registers its row batch handler on the first async query. +let deliverRowBatch: + | Parameters[0] + | undefined +jest + .mocked(HybridNitroSQLite.setRowBatchHandler) + .mockImplementation((handler) => { + deliverRowBatch = handler + }) + beforeEach(() => jest.clearAllMocks()) afterEach(() => { @@ -101,7 +111,8 @@ describe('execute', () => { dbName, query, params, - expect.any(Function), + undefined, + expect.any(Number), ) expect(HybridNitroSQLite.executeAsync).toHaveBeenCalledTimes(3) }) @@ -109,11 +120,13 @@ describe('execute', () => { it('joins rows delivered in batches before the remaining result rows', async () => { jest .mocked(HybridNitroSQLite.executeAsync) - .mockImplementationOnce(async (_dbName, _query, _params, onRows) => { - onRows?.([{ value: 1 }, { value: 2 }]) - onRows?.([{ value: 3 }]) - return nativeResult([{ value: 4 }]) - }) + .mockImplementationOnce( + async (_dbName, _query, _params, _onRows, rowBatchId) => { + deliverRowBatch!(rowBatchId!, [{ value: 1 }, { value: 2 }]) + deliverRowBatch!(rowBatchId!, [{ value: 3 }]) + return nativeResult([{ value: 4 }]) + }, + ) const result = await executeAsync(dbName, query, params) expect(result.results).toEqual([ @@ -127,6 +140,36 @@ describe('execute', () => { expect(result.rows.item(3)).toEqual({ value: 4 }) }) + it('passes a row callback to native builds without setRowBatchHandler', async () => { + let olderNative = HybridNitroSQLite + let olderExecuteAsync = executeAsync + jest.isolateModules(() => { + olderNative = + jest.requireMock( + '../nitro', + ).HybridNitroSQLite + delete (olderNative as Partial).setRowBatchHandler + olderExecuteAsync = jest.requireActual< + typeof import('../operations/execute') + >('../operations/execute').executeAsync + }) + jest + .mocked(olderNative.executeAsync) + .mockImplementationOnce(async (_dbName, _query, _params, onRows) => { + onRows?.([{ value: 1 }]) + return nativeResult([{ value: 2 }]) + }) + + const result = await olderExecuteAsync(dbName, query) + expect(result.results).toEqual([{ value: 1 }, { value: 2 }]) + expect(olderNative.executeAsync).toHaveBeenCalledWith( + dbName, + query, + undefined, + expect.any(Function), + ) + }) + it('keeps the native rows when no batch was delivered', async () => { const native = nativeResult([{ value: 7 }]) jest.mocked(HybridNitroSQLite.executeAsync).mockResolvedValueOnce(native) diff --git a/packages/react-native-nitro-sqlite/src/__tests__/session.test.ts b/packages/react-native-nitro-sqlite/src/__tests__/session.test.ts index 25091a5f..97a01ce5 100644 --- a/packages/react-native-nitro-sqlite/src/__tests__/session.test.ts +++ b/packages/react-native-nitro-sqlite/src/__tests__/session.test.ts @@ -81,7 +81,8 @@ describe('open', () => { dbName, 'SELECT 2', undefined, - expect.any(Function), + undefined, + expect.any(Number), ) db.close() @@ -376,13 +377,15 @@ describe('open', () => { 'transaction-2', 'SELECT 3', undefined, - expect.any(Function), + undefined, + expect.any(Number), ) expect(HybridNitroSQLite.executeAsync).not.toHaveBeenCalledWith( 'transaction-1', 'SELECT 2', undefined, - expect.any(Function), + undefined, + expect.any(Number), ) gate.resolve() diff --git a/packages/react-native-nitro-sqlite/src/__tests__/transaction.test.ts b/packages/react-native-nitro-sqlite/src/__tests__/transaction.test.ts index 3f092400..5208fb83 100644 --- a/packages/react-native-nitro-sqlite/src/__tests__/transaction.test.ts +++ b/packages/react-native-nitro-sqlite/src/__tests__/transaction.test.ts @@ -61,7 +61,8 @@ describe('transaction', () => { dbName, 'SELECT ?', [2], - expect.any(Function), + undefined, + expect.any(Number), ) expect(HybridNitroSQLite.execute).toHaveBeenLastCalledWith( dbName, @@ -222,7 +223,8 @@ describe('transaction', () => { dbName, 'BEGIN EXCLUSIVE TRANSACTION', undefined, - expect.any(Function), + undefined, + expect.any(Number), ) expect(HybridNitroSQLite.execute).toHaveBeenCalledTimes(1) expect(HybridNitroSQLite.execute).toHaveBeenCalledWith( diff --git a/packages/react-native-nitro-sqlite/src/operations/execute.ts b/packages/react-native-nitro-sqlite/src/operations/execute.ts index 79468c7b..c37ef6ba 100644 --- a/packages/react-native-nitro-sqlite/src/operations/execute.ts +++ b/packages/react-native-nitro-sqlite/src/operations/execute.ts @@ -93,30 +93,78 @@ export function executeAsyncNative( ): Promise> { // Not `async`: every extra promise layer is a measurable part of a short query's cost. // Large results arrive in batches, so rows are converted while SQLite reads the rest. - let leadingRows: Row[] | undefined + if (!hasRowBatchHandler) { + return executeAsyncWithRowCallback(dbName, query, params) + } + const rowBatchId = nextRowBatchId() let nativeResult: Promise try { nativeResult = HybridNitroSQLite.executeAsync( dbName, query, params, - (rows) => { - if (leadingRows === undefined) { - leadingRows = rows as Row[] - } else { - Array.prototype.push.apply(leadingRows, rows as Row[]) - } - }, + undefined, + rowBatchId, ) } catch (error) { return Promise.reject(NitroSQLiteError.fromError(error)) } return nativeResult.then( - (result) => buildJSQueryResult(result, leadingRows), - rejectWithNitroSQLiteError, + (result) => + buildJSQueryResult(result, takeLeadingRows(rowBatchId)), + (error: unknown) => { + leadingRowBatches.delete(rowBatchId) + return rejectWithNitroSQLiteError(error) + }, ) } +// Leading row batches of async queries in flight, by row batch ID. One handler, set on the first +// query, receives every batch, so a query passes a number to native code instead of a new callback. +const leadingRowBatches = new Map() +// Older native builds have no handler and get a callback per query instead. +const hasRowBatchHandler = + typeof HybridNitroSQLite.setRowBatchHandler === 'function' +let lastRowBatchId = 0 + +function nextRowBatchId(): number { + if (lastRowBatchId === 0) { + HybridNitroSQLite.setRowBatchHandler((rowBatchId, rows) => { + leadingRowBatches.set( + rowBatchId, + appendRows(leadingRowBatches.get(rowBatchId), rows), + ) + }) + } + lastRowBatchId++ + return lastRowBatchId +} + +function takeLeadingRows(rowBatchId: number): Row[] | undefined { + const rows = leadingRowBatches.get(rowBatchId) + if (rows !== undefined) leadingRowBatches.delete(rowBatchId) + return rows as Row[] | undefined +} + +function executeAsyncWithRowCallback( + dbName: string, + query: string, + params?: SQLiteQueryParams, +): Promise> { + let leadingRows: Row[] | undefined + return callNativeAsync(() => + HybridNitroSQLite.executeAsync(dbName, query, params, (rows) => { + leadingRows = appendRows(leadingRows, rows as Row[]) + }), + ).then((result) => buildJSQueryResult(result, leadingRows)) +} + +function appendRows(leadingRows: Row[] | undefined, rows: Row[]): Row[] { + if (leadingRows === undefined) return rows + Array.prototype.push.apply(leadingRows, rows) + return leadingRows +} + /** Execute one SQL statement synchronously by database name, returning rows as arrays. * Uses the default managed connection's queue when the database was opened through `open()`. * Otherwise, calls the open native database directly. diff --git a/packages/react-native-nitro-sqlite/src/specs/NitroSQLite.nitro.ts b/packages/react-native-nitro-sqlite/src/specs/NitroSQLite.nitro.ts index a9bd407f..f4f08ef8 100644 --- a/packages/react-native-nitro-sqlite/src/specs/NitroSQLite.nitro.ts +++ b/packages/react-native-nitro-sqlite/src/specs/NitroSQLite.nitro.ts @@ -101,6 +101,9 @@ export interface NitroSQLite * @param onRows Receives leading rows in batches, in order, while SQLite still reads the rest, so * JavaScript can convert a batch while the next one is read. Batched rows are not repeated in the * result's `results`, which then holds only the rows after the last batch. + * @param rowBatchId Without `onRows`, sends the same batches to the handler set with + * `setRowBatchHandler`, tagged with this ID. Unlike `onRows`, no function crosses to native code + * for each query. * @returns A promise of the native query result. */ executeAsync( @@ -108,7 +111,17 @@ export interface NitroSQLite query: string, params?: SQLiteQueryParams, onRows?: (rows: NitroSQLiteQueryRows) => void, + rowBatchId?: number, ): Promise + /** Set the function that receives row batches for `executeAsync` calls made with a `rowBatchId`. + * The managed API sets it on its first async query and relies on it, so replacing it drops leading + * rows from managed async results. + * @param handler Receives the query's row batch ID and its next batch of leading rows, in order, + * before that query's promise settles. + */ + setRowBatchHandler( + handler: (rowBatchId: number, rows: NitroSQLiteQueryRows) => void, + ): void /** Execute one SQL statement synchronously on the calling thread, returning rows as arrays of column values. * @param dbName Name of an open database. * @param query SQL statement with optional positional placeholders.