react-native-nitro-sqlite 9.8.1 → 10.0.0

package/src/operations/session.ts

@@ -11,95 +11,186 @@ import type {
 } from '../types'
 import { executeAsyncManaged, executeManaged } from './execute'
 import { executeBatch, executeBatchAsync } from './executeBatch'
+import { prepare } from './prepare'
 import NitroSQLiteError from '../NitroSQLiteError'
 import {
   closeDatabaseQueue,
+  getDatabaseQueue,
   isDatabaseOpen,
   openDatabaseQueue,
-  queueOperationAsync,
+  queueStatementAsync,
   startOperationSync,
 } from '../DatabaseQueue'
+import type { DatabaseQueueKey } from '../DatabaseQueue'
 
+/**
+ * Open a database and return a managed connection. The default connection is
+ * addressed by its name, and opening it twice throws. Set `connection` to
+ * `'independent'` to open another native handle to the same file. Async calls
+ * on each connection run in call order.
+ * @param options Database name, optional directory, connection mode, and read-only setting.
+ * @returns A connection bound to the opened native handle.
+ */
 export function open(
   options: NitroSQLiteConnectionOptions,
 ): NitroSQLiteConnection {
-  openDatabaseQueue(options.name)
+  const { name, location: databaseLocation, connection, readOnly } = options
+  const { connectionId, queueKey } = openNativeConnection(options)
+  const connectionQueue = getDatabaseQueue(queueKey)
 
-  try {
-    HybridNitroSQLite.open(options.name, options.location)
-  } catch (error) {
-    closeDatabaseQueue(options.name)
-    throw NitroSQLiteError.fromError(error)
+  const assertCurrentConnection = () => {
+    if (
+      !isDatabaseOpen(queueKey) ||
+      getDatabaseQueue(queueKey) !== connectionQueue
+    ) {
+      throw new NitroSQLiteError(
+        `Database ${name} is not open. There is no connection to the database.`,
+      )
+    }
+  }
+
+  const assertNoReplacement = () => {
+    if (
+      isDatabaseOpen(queueKey) &&
+      getDatabaseQueue(queueKey) !== connectionQueue
+    ) {
+      throw new NitroSQLiteError(
+        `Database ${name} has been reopened with another connection.`,
+      )
+    }
+  }
+
+  const runSyncOperation = <Result>(callback: () => Result): Result => {
+    try {
+      assertCurrentConnection()
+      return startOperationSync(queueKey, callback)
+    } catch (error) {
+      throw NitroSQLiteError.fromError(error)
+    }
+  }
+
+  const runOperation = <Result>(callback: () => Result): Result => {
+    assertCurrentConnection()
+    return callback()
   }
 
   return {
     close: () => {
-      try {
-        startOperationSync(options.name, () =>
-          HybridNitroSQLite.close(options.name),
-        )
-        closeDatabaseQueue(options.name)
-      } catch (error) {
-        throw NitroSQLiteError.fromError(error)
-      }
+      runSyncOperation(() => HybridNitroSQLite.close(connectionId))
+      closeDatabaseQueue(queueKey)
     },
     delete: () => {
+      if (readOnly) {
+        throw new NitroSQLiteError(`Cannot delete read-only database ${name}.`)
+      }
+
+      let dropFailed = false
       try {
-        if (!isDatabaseOpen(options.name)) {
-          HybridNitroSQLite.drop(options.name, options.location)
+        assertNoReplacement()
+        const drop = () => {
+          try {
+            if (connection === 'independent') {
+              HybridNitroSQLite.drop(name, databaseLocation, connectionId)
+            } else {
+              HybridNitroSQLite.drop(name, databaseLocation)
+            }
+          } catch (error) {
+            dropFailed = true
+            throw error
+          }
+        }
+
+        if (!isDatabaseOpen(queueKey)) {
+          drop()
           return
         }
 
-        startOperationSync(options.name, () =>
-          HybridNitroSQLite.drop(options.name, options.location),
-        )
-        closeDatabaseQueue(options.name)
+        startOperationSync(queueKey, drop)
+        closeDatabaseQueue(queueKey)
       } catch (error) {
+        if (
+          dropFailed &&
+          isDatabaseOpen(queueKey) &&
+          getDatabaseQueue(queueKey) === connectionQueue &&
+          !HybridNitroSQLite.isConnectionOpen(connectionId)
+        ) {
+          closeDatabaseQueue(queueKey)
+        }
         throw NitroSQLiteError.fromError(error)
       }
     },
     attach: (dbNameToAttach: string, alias: string, location?: string) =>
-      runSyncOperation(options.name, () =>
-        HybridNitroSQLite.attach(options.name, dbNameToAttach, alias, location),
+      runSyncOperation(() =>
+        HybridNitroSQLite.attach(connectionId, dbNameToAttach, alias, location),
       ),
     detach: (alias: string) =>
-      runSyncOperation(options.name, () =>
-        HybridNitroSQLite.detach(options.name, alias),
-      ),
-    transaction: <Result = void>(fn: (tx: Transaction) => Promise<Result>) =>
-      transaction(options.name, fn),
+      runSyncOperation(() => HybridNitroSQLite.detach(connectionId, alias)),
+    transaction: async <Result = void>(
+      fn: (tx: Transaction) => Promise<Result>,
+    ) => runOperation(() => transaction(connectionId, fn, false, queueKey)),
     execute: <Row extends QueryResultRow = never>(
       query: string,
       params?: SQLiteQueryParams,
-    ): QueryResult<Row> => executeManaged(options.name, query, params),
-    executeAsync: <Row extends QueryResultRow = never>(
+    ): QueryResult<Row> =>
+      runOperation(() => executeManaged(connectionId, query, params, queueKey)),
+    executeAsync: async <Row extends QueryResultRow = never>(
       query: string,
       params?: SQLiteQueryParams,
     ): Promise<QueryResult<Row>> =>
-      executeAsyncManaged(options.name, query, params),
+      runOperation(() =>
+        executeAsyncManaged(connectionId, query, params, queueKey),
+      ),
+    prepare: (query: string) =>
+      runOperation(() => prepare(connectionId, query, queueKey)),
     executeBatch: (commands: BatchQueryCommand[]) =>
-      executeBatch(options.name, commands),
-    executeBatchAsync: (commands: BatchQueryCommand[]) =>
-      executeBatchAsync(options.name, commands),
+      runOperation(() => executeBatch(connectionId, commands, queueKey)),
+    executeBatchAsync: async (commands: BatchQueryCommand[]) =>
+      runOperation(() => executeBatchAsync(connectionId, commands, queueKey)),
     loadFile: (location: string) =>
-      runSyncOperation(options.name, () =>
-        HybridNitroSQLite.loadFile(options.name, location),
+      runSyncOperation(() =>
+        HybridNitroSQLite.loadFile(connectionId, location),
       ),
     loadFileAsync: (location: string) =>
-      queueOperationAsync(options.name, async () => {
-        try {
-          return await HybridNitroSQLite.loadFileAsync(options.name, location)
-        } catch (error) {
-          throw NitroSQLiteError.fromError(error)
-        }
-      }),
+      runOperation(() =>
+        queueStatementAsync(queueKey, async () => {
+          try {
+            return await HybridNitroSQLite.loadFileAsync(connectionId, location)
+          } catch (error) {
+            throw NitroSQLiteError.fromError(error)
+          }
+        }),
+      ),
   }
 }
 
-function runSyncOperation<Result>(dbName: string, callback: () => Result) {
+function openNativeConnection(options: NitroSQLiteConnectionOptions): {
+  connectionId: string
+  queueKey: DatabaseQueueKey
+} {
+  if (options.connection === 'independent') {
+    let connectionId: string
+    try {
+      connectionId = options.readOnly
+        ? HybridNitroSQLite.openConnection(options.name, options.location, true)
+        : HybridNitroSQLite.openConnection(options.name, options.location)
+      const queueKey = Symbol(options.name)
+      openDatabaseQueue(queueKey)
+      return { connectionId, queueKey }
+    } catch (error) {
+      throw NitroSQLiteError.fromError(error)
+    }
+  }
+
+  openDatabaseQueue(options.name)
   try {
-    return startOperationSync(dbName, callback)
+    if (options.readOnly) {
+      HybridNitroSQLite.open(options.name, options.location, true)
+    } else {
+      HybridNitroSQLite.open(options.name, options.location)
+    }
   } catch (error) {
+    closeDatabaseQueue(options.name)
     throw NitroSQLiteError.fromError(error)
   }
+  return { connectionId: options.name, queueKey: options.name }
 }

package/src/operations/transaction.ts

@@ -7,15 +7,35 @@ import type {
 } from '../types'
 import { executeAsyncNative, executeNative } from './execute'
 import NitroSQLiteError from '../NitroSQLiteError'
+import type { DatabaseQueueKey } from '../DatabaseQueue'
 
+/** Queue a transaction for an open managed connection.
+ * Use only the supplied `tx` for work on this database inside the callback.
+ * A successful callback commits unless it explicitly committed or rolled back;
+ * a thrown error rolls back unless the transaction was already finalized.
+ * @param dbName Name of the open database.
+ * @param transactionCallback Async callback receiving the transaction handle.
+ * @param isExclusive Begin an exclusive transaction when true.
+ * @returns The callback's result after the transaction finishes.
+ */
 export const transaction = async <Result = void>(
   dbName: string,
   transactionCallback: (tx: Transaction) => Promise<Result>,
   isExclusive = false,
+  queueKey: DatabaseQueueKey = dbName,
 ) => {
-  throwIfDatabaseIsNotOpen(dbName)
+  throwIfDatabaseIsNotOpen(queueKey)
 
   let isFinished = false
+  const pendingAsyncStatements = new Set<Promise<unknown>>()
+
+  const throwIfAsyncPending = () => {
+    if (pendingAsyncStatements.size > 0) {
+      throw new NitroSQLiteError(
+        `Cannot run synchronous operation on transaction ${dbName} while async queries are pending. Await all tx.executeAsync calls first.`,
+      )
+    }
+  }
 
   const executeOnTransaction = <Row extends QueryResultRow = never>(
     query: string,
@@ -26,6 +46,7 @@ export const transaction = async <Result = void>(
         `Cannot execute query on finalized transaction: ${dbName}`,
       )
     }
+    throwIfAsyncPending()
     return executeNative(dbName, query, params)
   }
 
@@ -38,7 +59,13 @@ export const transaction = async <Result = void>(
         `Cannot execute query on finalized transaction: ${dbName}`,
       )
     }
-    return executeAsyncNative(dbName, query, params)
+    const pending = executeAsyncNative<Row>(dbName, query, params)
+    pendingAsyncStatements.add(pending)
+    pending.then(
+      () => pendingAsyncStatements.delete(pending),
+      () => pendingAsyncStatements.delete(pending),
+    )
+    return pending
   }
 
   const commit = () => {
@@ -47,6 +74,7 @@ export const transaction = async <Result = void>(
         `Cannot execute commit on finalized transaction: ${dbName}`,
       )
     }
+    throwIfAsyncPending()
     isFinished = true
     return executeNative(dbName, 'COMMIT')
   }
@@ -57,11 +85,12 @@ export const transaction = async <Result = void>(
         `Cannot execute rollback on finalized transaction: ${dbName}`,
       )
     }
+    throwIfAsyncPending()
     isFinished = true
     return executeNative(dbName, 'ROLLBACK')
   }
 
-  return await queueOperationAsync(dbName, async () => {
+  return await queueOperationAsync(queueKey, async () => {
     try {
       await executeAsyncNative(
         dbName,
@@ -80,8 +109,12 @@ export const transaction = async <Result = void>(
       return result
     } catch (executionError) {
       if (!isFinished) {
+        isFinished = true
+        // All queued native calls must finish before ROLLBACK can run
+        // synchronously on this connection.
+        await Promise.allSettled(pendingAsyncStatements)
         try {
-          rollback()
+          executeNative(dbName, 'ROLLBACK')
         } catch (rollbackError) {
           throw NitroSQLiteError.fromError(rollbackError)
         }

package/src/specs/NitroSQLite.nitro.ts

@@ -6,37 +6,119 @@ import type {
   SQLiteQueryParams,
 } from '../types'
 import type { NitroSQLiteQueryResult } from './NitroSQLiteQueryResult.nitro'
+import type { NitroSQLitePreparedStatement } from './NitroSQLitePreparedStatement.nitro'
 
+/** Native database operations exposed through `NitroSQLite.native`.
+ * These calls bypass the managed connection queue. Coordinate them with any
+ * transaction or pending operation on the same database yourself.
+ */
 export interface NitroSQLite
   extends HybridObject<{
     ios: 'c++'
     android: 'c++'
   }> {
-  open(dbName: string, location?: string): void
+  /** Open a name-based default connection, creating the database unless `readOnly` is true.
+   * @param dbName Database file name and default connection key.
+   * @param location Directory relative to the platform database directory.
+   * @param readOnly Open an existing database without write access.
+   */
+  open(dbName: string, location?: string, readOnly?: boolean): void
+  /** Open a separate native handle, even when the database file is already open.
+   * Independent connections require a thread-safe SQLite build.
+   * @param dbName Database file name.
+   * @param location Directory relative to the platform database directory.
+   * @param readOnly Open an existing database without write access.
+   * @returns An opaque ID to pass to native connection operations.
+   */
+  openConnection(dbName: string, location?: string, readOnly?: boolean): string
+  /** Check whether a native connection ID is still open.
+   * @param connectionId ID returned by `openConnection`.
+   */
+  isConnectionOpen(connectionId: string): boolean
+  /** Close a default connection by name or an independent connection by ID. */
   close(dbName: string): void
-  drop(dbName: string, location?: string): void
+  /** Delete a database and close the indicated connection if open.
+   * Deletion fails while another connection or attachment uses the database file.
+   * @param dbName Database file name.
+   * @param location Directory relative to the platform database directory.
+   * @param connectionId Optional ID of the independent connection to close.
+   */
+  drop(dbName: string, location?: string, connectionId?: string): void
+  /** Attach a database file to an open main database under an SQL schema alias.
+   * @param mainDbName Name of the open main database.
+   * @param dbNameToAttach File name of the database to attach.
+   * @param alias SQL schema name for the attached database.
+   * @param location Directory relative to the platform database directory.
+   */
+
   attach(
     mainDbName: string,
     dbNameToAttach: string,
     alias: string,
     location?: string,
   ): void
+  /** Detach an attached database by its alias.
+   * @param mainDbName Name of the open main database.
+   * @param alias SQL schema name used when attaching.
+   */
   detach(mainDbName: string, alias: string): void
+  /** Execute one SQL statement synchronously on the calling thread.
+   * @param dbName Name of an open database.
+   * @param query SQL statement with optional positional placeholders.
+   * @param params Positional values bound to SQL placeholders.
+   * @returns Native query rows, affected row count, insert ID, and metadata.
+   */
   execute(
     dbName: string,
     query: string,
     params?: SQLiteQueryParams,
   ): NitroSQLiteQueryResult
+  /** Execute one SQL statement on a background thread.
+   * @param dbName Name of an open database.
+   * @param query SQL statement with optional positional placeholders.
+   * @param params Positional values bound to SQL placeholders.
+   * @returns A promise of the native query result.
+   */
   executeAsync(
     dbName: string,
     query: string,
     params?: SQLiteQueryParams,
   ): Promise<NitroSQLiteQueryResult>
+  /** Prepare one SQL statement on an open native connection for repeated execution.
+   * Finalize the returned statement before closing its connection.
+   * @param dbName Name or ID of an open database connection.
+   * @param query SQL statement with optional positional placeholders.
+   * @returns A native statement with synchronous and asynchronous execution methods.
+   */
+  prepare(dbName: string, query: string): NitroSQLitePreparedStatement
+  /** Execute commands in one exclusive transaction on the calling thread.
+   * An empty batch throws; a failed command rolls back the batch.
+   * @param dbName Name of an open database.
+   * @param commands SQL commands and optional parameter sets.
+   * @returns Total affected row count.
+   */
   executeBatch(dbName: string, commands: BatchQueryCommand[]): BatchQueryResult
+  /** Execute commands in one exclusive transaction on a background thread.
+   * An empty batch rejects; a failed command rolls back the batch.
+   * @param dbName Name of an open database.
+   * @param commands SQL commands and optional parameter sets.
+   * @returns A promise of the total affected row count.
+   */
   executeBatchAsync(
     dbName: string,
     commands: BatchQueryCommand[],
   ): Promise<BatchQueryResult>
+  /** Import a SQL file in one exclusive transaction on the calling thread.
+   * Each non-empty line is treated as one statement.
+   * @param dbName Name of an open database.
+   * @param location Path to the SQL file.
+   * @returns Number of executed commands and affected rows.
+   */
   loadFile(dbName: string, location: string): FileLoadResult
+  /** Import a SQL file on a background thread.
+   * @param dbName Name of an open database.
+   * @param location Path to the SQL file.
+   * @returns A promise of the command and affected row counts.
+   */
   loadFileAsync(dbName: string, location: string): Promise<FileLoadResult>
 }

package/src/specs/NitroSQLitePreparedStatement.nitro.ts

@@ -0,0 +1,28 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { SQLiteQueryParams } from '../types'
+import type { NitroSQLiteQueryResult } from './NitroSQLiteQueryResult.nitro'
+
+/** Native prepared statement returned by `NitroSQLite.native.prepare()`. */
+export interface NitroSQLitePreparedStatement
+  extends HybridObject<{
+    ios: 'c++'
+    android: 'c++'
+  }> {
+  /** Whether the native statement has been finalized. */
+  readonly isFinalized: boolean
+
+  /** Execute on the calling thread, replacing the previous parameter bindings.
+   * Throws after finalization or connection closure.
+   * @param params Values bound to positional placeholders.
+   * @returns Native query rows, affected row count, insert ID, and metadata.
+   */
+  execute(params?: SQLiteQueryParams): NitroSQLiteQueryResult
+  /** Execute on a background thread, replacing the previous parameter bindings.
+   * Rejects after finalization or connection closure.
+   * @param params Values bound to positional placeholders.
+   * @returns A promise of the native query result.
+   */
+  executeAsync(params?: SQLiteQueryParams): Promise<NitroSQLiteQueryResult>
+  /** Release the native statement. Repeated calls are safe. */
+  finalize(): void
+}

package/src/specs/NitroSQLiteQueryResult.nitro.ts

@@ -1,28 +1,21 @@
 import type { HybridObject } from 'react-native-nitro-modules'
 import type { ColumnType, SQLiteValue } from '../types'
 
-/**
- * Object returned by SQL Query executions {
- *  insertId: Represent the auto-generated row id if applicable
- *  rowsAffected: Number of affected rows if result of a update query
- *  message: if status === 1, here you will find error description
- *  rows: if status is undefined or 0 this object will contain the query results
- * }
- *
- * @interface QueryResult
- */
+/** Native result of one SQL statement. The managed API also adds a `rows` adapter. */
 export interface NitroSQLiteQueryResult
   extends HybridObject<{
     ios: 'c++'
     android: 'c++'
   }> {
+  /** SQLite's latest row change count. For a read-only query it may reflect an earlier write. */
   readonly rowsAffected: number
+  /** Last insert row ID for this connection. It may refer to an earlier statement. */
   readonly insertId?: number
 
-  /** Query results */
+  /** Rows keyed by result column names. */
   readonly results: Record<string, SQLiteValue>[]
 
-  /** Table metadata */
+  /** Column metadata keyed by result column name, when available. */
   readonly metadata?: Record<string, NitroSQLiteQueryColumnMetadata>
 }
 
@@ -33,13 +26,14 @@ export interface NitroSQLiteQueryResult
 
 // type NitroQueryResultRow = Record<string, SQLiteValue>
 
+/** Name, declared type, and position of a result column. */
 export type NitroSQLiteQueryColumnMetadata = {
-  /** The name used for this column for this result set */
+  /** Name used for this column in the result set. */
   name: string
 
-  /** The declared column type for this column, when fetched directly from a table or a View resulting from a table column. "UNKNOWN" for dynamic values, like function returned ones. */
+  /** Native type category derived from the column declaration. */
   type: ColumnType
 
-  /** The index for this column for this result set */
+  /** Zero-based position in the result set. */
   index: number
 }

package/src/typeORM.ts

@@ -13,29 +13,40 @@ import type {
 } from './types'
 import * as Operations from './operations/session'
 
+/** Callback-oriented connection returned to TypeORM. */
 interface TypeOrmNitroSQLiteConnection {
+  /** Execute SQL asynchronously and report the result through a callback. */
   executeSql: <RowData extends QueryResultRow = never>(
     sql: string,
     params: SQLiteQueryParams | undefined,
     okExecute: (res: QueryResult<RowData>) => void,
     failExecute: (msg: string) => void,
   ) => Promise<void>
+  /** Run TypeORM work in a managed transaction. */
   transaction: (fn: (tx: Transaction) => Promise<void>) => Promise<void>
+  /** Close the connection and report completion through callbacks. */
   close: (okClose: () => void, failClose: (e: unknown) => void) => void
+  /** Attach another database and invoke `callback` after it succeeds. */
   attach: (
     dbNameToAttach: string,
     alias: string,
     location: string | undefined,
     callback: () => void,
   ) => void
+  /** Detach an attached database and invoke `callback` after it succeeds. */
   detach: (alias: string, callback: () => void) => void
 }
 
-/**
- * DO NOT USE THIS! THIS IS MEANT FOR TYPEORM
- * If you are looking for a convenience wrapper use `connect`
+/** Adapter for TypeORM's React Native driver. Application code should use `open()`.
+ * `openDatabase` reports success or failure through callbacks and returns the
+ * connection on success, or `null` when opening fails.
  */
 export const typeORMDriver = {
+  /** Open a database for TypeORM.
+   * @param options Database name and optional relative directory.
+   * @param ok Receives the adapter connection on success.
+   * @param fail Receives the opening error on failure.
+   */
   openDatabase: (
     options: {
       name: string