react-native-nitro-sqlite 9.8.1 → 10.0.0

package/nitrogen/generated/shared/c++/HybridNitroSQLitePreparedStatementSpec.hpp

@@ -0,0 +1,73 @@
+///
+/// HybridNitroSQLitePreparedStatementSpec.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/HybridObject.hpp>)
+#include <NitroModules/HybridObject.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `HybridNitroSQLiteQueryResultSpec` to properly resolve imports.
+namespace margelo::nitro::rnnitrosqlite { class HybridNitroSQLiteQueryResultSpec; }
+
+#include <memory>
+#include "HybridNitroSQLiteQueryResultSpec.hpp"
+#include <NitroModules/Null.hpp>
+#include <NitroModules/ArrayBuffer.hpp>
+#include <string>
+#include <variant>
+#include <vector>
+#include <optional>
+#include <NitroModules/Promise.hpp>
+
+namespace margelo::nitro::rnnitrosqlite {
+
+  using namespace margelo::nitro;
+
+  /**
+   * An abstract base class for `NitroSQLitePreparedStatement`
+   * Inherit this class to create instances of `HybridNitroSQLitePreparedStatementSpec` in C++.
+   * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
+   * @example
+   * ```cpp
+   * class HybridNitroSQLitePreparedStatement: public HybridNitroSQLitePreparedStatementSpec {
+   * public:
+   *   HybridNitroSQLitePreparedStatement(...): HybridObject(TAG) { ... }
+   *   // ...
+   * };
+   * ```
+   */
+  class HybridNitroSQLitePreparedStatementSpec: public virtual HybridObject {
+    public:
+      // Constructor
+      explicit HybridNitroSQLitePreparedStatementSpec(): HybridObject(TAG) { }
+
+      // Destructor
+      ~HybridNitroSQLitePreparedStatementSpec() override = default;
+
+    public:
+      // Properties
+      virtual bool getIsFinalized() = 0;
+
+    public:
+      // Methods
+      virtual std::shared_ptr<HybridNitroSQLiteQueryResultSpec> execute(const std::optional<std::vector<std::variant<nitro::NullType, bool, std::shared_ptr<ArrayBuffer>, std::string, double>>>& params) = 0;
+      virtual std::shared_ptr<Promise<std::shared_ptr<HybridNitroSQLiteQueryResultSpec>>> executeAsync(const std::optional<std::vector<std::variant<nitro::NullType, bool, std::shared_ptr<ArrayBuffer>, std::string, double>>>& params) = 0;
+      virtual void finalize() = 0;
+
+    protected:
+      // Hybrid Setup
+      void loadHybridMethods() override;
+
+    protected:
+      // Tag for logging
+      static constexpr auto TAG = "NitroSQLitePreparedStatement";
+  };
+
+} // namespace margelo::nitro::rnnitrosqlite

package/nitrogen/generated/shared/c++/HybridNitroSQLiteSpec.cpp

@@ -15,12 +15,15 @@ namespace margelo::nitro::rnnitrosqlite {
     // load custom methods/properties
     registerHybrids(this, [](Prototype& prototype) {
       prototype.registerHybridMethod("open", &HybridNitroSQLiteSpec::open);
+      prototype.registerHybridMethod("openConnection", &HybridNitroSQLiteSpec::openConnection);
+      prototype.registerHybridMethod("isConnectionOpen", &HybridNitroSQLiteSpec::isConnectionOpen);
       prototype.registerHybridMethod("close", &HybridNitroSQLiteSpec::close);
       prototype.registerHybridMethod("drop", &HybridNitroSQLiteSpec::drop);
       prototype.registerHybridMethod("attach", &HybridNitroSQLiteSpec::attach);
       prototype.registerHybridMethod("detach", &HybridNitroSQLiteSpec::detach);
       prototype.registerHybridMethod("execute", &HybridNitroSQLiteSpec::execute);
       prototype.registerHybridMethod("executeAsync", &HybridNitroSQLiteSpec::executeAsync);
+      prototype.registerHybridMethod("prepare", &HybridNitroSQLiteSpec::prepare);
       prototype.registerHybridMethod("executeBatch", &HybridNitroSQLiteSpec::executeBatch);
       prototype.registerHybridMethod("executeBatchAsync", &HybridNitroSQLiteSpec::executeBatchAsync);
       prototype.registerHybridMethod("loadFile", &HybridNitroSQLiteSpec::loadFile);

package/nitrogen/generated/shared/c++/HybridNitroSQLiteSpec.hpp

@@ -15,6 +15,8 @@
 
 // Forward declaration of `HybridNitroSQLiteQueryResultSpec` to properly resolve imports.
 namespace margelo::nitro::rnnitrosqlite { class HybridNitroSQLiteQueryResultSpec; }
+// Forward declaration of `HybridNitroSQLitePreparedStatementSpec` to properly resolve imports.
+namespace margelo::nitro::rnnitrosqlite { class HybridNitroSQLitePreparedStatementSpec; }
 // Forward declaration of `BatchQueryResult` to properly resolve imports.
 namespace margelo::nitro::rnnitrosqlite { struct BatchQueryResult; }
 // Forward declaration of `BatchQueryCommand` to properly resolve imports.
@@ -31,6 +33,7 @@ namespace margelo::nitro::rnnitrosqlite { struct FileLoadResult; }
 #include <variant>
 #include <vector>
 #include <NitroModules/Promise.hpp>
+#include "HybridNitroSQLitePreparedStatementSpec.hpp"
 #include "BatchQueryResult.hpp"
 #include "BatchQueryCommand.hpp"
 #include "FileLoadResult.hpp"
@@ -66,13 +69,16 @@ namespace margelo::nitro::rnnitrosqlite {
 
     public:
       // Methods
-      virtual void open(const std::string& dbName, const std::optional<std::string>& location) = 0;
+      virtual void open(const std::string& dbName, const std::optional<std::string>& location, std::optional<bool> readOnly) = 0;
+      virtual std::string openConnection(const std::string& dbName, const std::optional<std::string>& location, std::optional<bool> readOnly) = 0;
+      virtual bool isConnectionOpen(const std::string& connectionId) = 0;
       virtual void close(const std::string& dbName) = 0;
-      virtual void drop(const std::string& dbName, const std::optional<std::string>& location) = 0;
+      virtual void drop(const std::string& dbName, const std::optional<std::string>& location, const std::optional<std::string>& connectionId) = 0;
       virtual void attach(const std::string& mainDbName, const std::string& dbNameToAttach, const std::string& alias, const std::optional<std::string>& location) = 0;
       virtual void detach(const std::string& mainDbName, const std::string& alias) = 0;
       virtual std::shared_ptr<HybridNitroSQLiteQueryResultSpec> execute(const std::string& dbName, const std::string& query, const std::optional<std::vector<std::variant<nitro::NullType, bool, std::shared_ptr<ArrayBuffer>, std::string, double>>>& params) = 0;
       virtual std::shared_ptr<Promise<std::shared_ptr<HybridNitroSQLiteQueryResultSpec>>> executeAsync(const std::string& dbName, const std::string& query, const std::optional<std::vector<std::variant<nitro::NullType, bool, std::shared_ptr<ArrayBuffer>, std::string, double>>>& params) = 0;
+      virtual std::shared_ptr<HybridNitroSQLitePreparedStatementSpec> prepare(const std::string& dbName, const std::string& query) = 0;
       virtual BatchQueryResult executeBatch(const std::string& dbName, const std::vector<BatchQueryCommand>& commands) = 0;
       virtual std::shared_ptr<Promise<BatchQueryResult>> executeBatchAsync(const std::string& dbName, const std::vector<BatchQueryCommand>& commands) = 0;
       virtual FileLoadResult loadFile(const std::string& dbName, const std::string& location) = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-sqlite",
-  "version": "9.8.1",
+  "version": "10.0.0",
   "description": "Fast SQLite library for React Native built using Nitro Modules",
   "main": "./lib/module/index",
   "module": "./lib/module/index",
@@ -9,6 +9,7 @@
   "react-native": "./src/index",
   "exports": {
     ".": {
+      "react-native": "./src/index.ts",
       "import": {
         "types": "./lib/typescript/module/index.d.ts",
         "default": "./lib/module/index.js"
@@ -50,13 +51,14 @@
     "sqlite",
     "nitro-modules",
     "ios",
+    "macos",
     "android"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/margelo/react-native-nitro-sqlite.git"
   },
-  "author": "Margelo <hello@margelo.com> (https://github.com/margelo)",
+  "author": "Christoph Pader",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/margelo/react-native-nitro-sqlite/issues"

package/src/DatabaseQueue.ts

@@ -1,6 +1,7 @@
 import NitroSQLiteError from './NitroSQLiteError'
 
 export interface QueuedOperation {
+  kind: 'statement' | 'exclusive'
   /**
    * Starts the operation
    */
@@ -10,44 +11,56 @@ export interface QueuedOperation {
 export type DatabaseQueue = {
   queue: QueuedOperation[]
   inProgress: boolean
+  activeStatements: number
+  draining: boolean
 }
 
-const databaseQueues = new Map<string, DatabaseQueue>()
+/** Identity of a managed connection's operation queue. Application code should
+ * omit the optional queue key on package helpers; connections choose it for you.
+ */
+export type DatabaseQueueKey = string | symbol
 
-export function openDatabaseQueue(dbName: string) {
+const databaseQueues = new Map<DatabaseQueueKey, DatabaseQueue>()
+
+export function openDatabaseQueue(dbName: DatabaseQueueKey) {
   if (isDatabaseOpen(dbName)) {
     throw new NitroSQLiteError(
-      `Database ${dbName} is already open. There is already a connection to the database.`,
+      `Database ${String(dbName)} is already open. There is already a connection to the database.`,
     )
   }
 
-  databaseQueues.set(dbName, { queue: [], inProgress: false })
+  databaseQueues.set(dbName, {
+    queue: [],
+    inProgress: false,
+    activeStatements: 0,
+    draining: false,
+  })
 }
 
-export function closeDatabaseQueue(dbName: string) {
+export function closeDatabaseQueue(dbName: DatabaseQueueKey) {
   const databaseQueue = getDatabaseQueue(dbName)
 
   if (databaseQueue.inProgress || databaseQueue.queue.length > 0) {
     throw new NitroSQLiteError(
-      `Cannot close database ${dbName}. The database is busy with another operation.`,
+      `Cannot close database ${String(dbName)}. The database is busy with another operation.`,
     )
   }
 
   databaseQueues.delete(dbName)
 }
 
-export function isDatabaseOpen(dbName: string) {
+export function isDatabaseOpen(dbName: DatabaseQueueKey) {
   return databaseQueues.has(dbName)
 }
 
-export function throwIfDatabaseIsNotOpen(dbName: string) {
+export function throwIfDatabaseIsNotOpen(dbName: DatabaseQueueKey) {
   if (!isDatabaseOpen(dbName))
     throw new NitroSQLiteError(
-      `Database ${dbName} is not open. There is no connection to the database.`,
+      `Database ${String(dbName)} is not open. There is no connection to the database.`,
     )
 }
 
-export function getDatabaseQueue(dbName: string) {
+export function getDatabaseQueue(dbName: DatabaseQueueKey) {
   throwIfDatabaseIsNotOpen(dbName)
 
   const queue = databaseQueues.get(dbName)!
@@ -55,9 +68,24 @@ export function getDatabaseQueue(dbName: string) {
 }
 
 export function queueOperationAsync<Result>(
-  dbName: string,
+  dbName: DatabaseQueueKey,
+  callback: () => Promise<Result>,
+): Promise<Result> {
+  return enqueueOperation(dbName, 'exclusive', callback)
+}
+
+export function queueStatementAsync<Result>(
+  dbName: DatabaseQueueKey,
+  callback: () => Promise<Result>,
+): Promise<Result> {
+  return enqueueOperation(dbName, 'statement', callback)
+}
+
+function enqueueOperation<Result>(
+  dbName: DatabaseQueueKey,
+  kind: QueuedOperation['kind'],
   callback: () => Promise<Result>,
-) {
+): Promise<Result> {
   const databaseQueue = getDatabaseQueue(dbName)
 
   return new Promise<Result>((resolve, reject) => {
@@ -68,36 +96,63 @@ export function queueOperationAsync<Result>(
       } catch (error) {
         reject(error)
       } finally {
-        databaseQueue.inProgress = false
-        startOperationAsync(databaseQueue)
+        if (kind === 'statement') {
+          databaseQueue.activeStatements--
+          if (databaseQueue.activeStatements === 0) {
+            databaseQueue.inProgress = false
+          }
+        } else {
+          databaseQueue.inProgress = false
+        }
+        startNextOperations(databaseQueue)
       }
     }
 
     const operation: QueuedOperation = {
+      kind,
       start,
     }
 
     databaseQueue.queue.push(operation)
-    startOperationAsync(databaseQueue)
+    startNextOperations(databaseQueue)
   })
 }
 
-function startOperationAsync(queue: DatabaseQueue) {
-  // Queue is empty or in progress. Bail out.
-  if (queue.inProgress || queue.queue.length === 0) {
+function startNextOperations(queue: DatabaseQueue) {
+  if (queue.draining || (queue.inProgress && queue.activeStatements === 0)) {
     return
   }
 
-  queue.inProgress = true
+  queue.draining = true
+  try {
+    while (queue.queue.length > 0) {
+      const exclusiveIndex = queue.queue.findIndex(
+        (operation) => operation.kind === 'exclusive',
+      )
+      const statementCount =
+        exclusiveIndex === -1 ? queue.queue.length : exclusiveIndex
+
+      if (statementCount > 0) {
+        const statements = queue.queue.splice(0, statementCount)
+        queue.inProgress = true
+        queue.activeStatements += statements.length
+        for (const statement of statements) statement.start()
+        continue
+      }
 
-  const operation = queue.queue.shift()!
-  setImmediate(() => {
-    operation.start()
-  })
+      if (queue.activeStatements > 0) return
+
+      queue.inProgress = true
+      queue.queue.shift()!.start()
+      return
+    }
+  } finally {
+    queue.draining = false
+  }
 }
 
 export function startOperationSync<Result>(
-  dbName: string,
+  dbName: DatabaseQueueKey,
   callback: () => Result,
 ): Result {
   const databaseQueue = getDatabaseQueue(dbName)
@@ -105,7 +160,7 @@ export function startOperationSync<Result>(
   // Database is busy - cannot execute synchronously
   if (databaseQueue.inProgress || databaseQueue.queue.length > 0) {
     throw new NitroSQLiteError(
-      `Cannot run synchronous operation on database. Database ${dbName} is busy with another operation.`,
+      `Cannot run synchronous operation on database. Database ${String(dbName)} is busy with another operation.`,
     )
   }
 
@@ -115,5 +170,6 @@ export function startOperationSync<Result>(
     return callback()
   } finally {
     databaseQueue.inProgress = false
+    startNextOperations(databaseQueue)
   }
 }

package/src/NitroSQLiteError.ts

@@ -1,10 +1,8 @@
 const NITRO_SQLITE_ERROR_NAME = 'NitroSQLiteError' as const
 
-/**
- * Custom error class for NitroSQLite operations
- * Extends the native Error class with proper prototype chain and error handling
- */
+/** Error thrown by managed NitroSQLite operations. Native errors are wrapped with this class. */
 export default class NitroSQLiteError extends Error {
+  /** Create an error with a message and optional cause. */
   constructor(message: string, options?: ErrorOptions) {
     super(message, options)
     this.name = NITRO_SQLITE_ERROR_NAME
@@ -13,9 +11,10 @@ export default class NitroSQLiteError extends Error {
     Object.setPrototypeOf(this, NitroSQLiteError.prototype)
   }
 
-  /**
-   * Converts an unknown error to a NitroSQLiteError
-   * Preserves stack traces and error causes when available
+  /** Convert an unknown thrown value to `NitroSQLiteError`.
+   * Existing instances pass through; `Error` values keep their stack and cause.
+   * @param error Value to normalize.
+   * @returns A NitroSQLiteError instance.
    */
   static fromError(error: unknown): NitroSQLiteError {
     if (error instanceof NitroSQLiteError) {

package/src/OnLoad.ts

@@ -1,2 +1,2 @@
-// NOOP on iOS
+// Apple platforms initialize the database directory from OnLoad.mm.
 export const init = () => {}

package/src/index.ts

@@ -2,21 +2,25 @@ import { transaction } from './operations/transaction'
 import { HybridNitroSQLite } from './nitro'
 import { open } from './operations/session'
 import { execute, executeAsync } from './operations/execute'
+import { prepare } from './operations/prepare'
 import { init } from './OnLoad'
 import { executeBatch, executeBatchAsync } from './operations/executeBatch'
 
 init()
 
+/** Database entry point. Prefer {@link open} for a managed connection.
+ * `native` exposes the Nitro object directly and bypasses the JavaScript queue.
+ */
 export const NitroSQLite = {
   ...HybridNitroSQLite,
   native: HybridNitroSQLite,
-  // Overwrite native `open` function with session-based JS abstraction,
-  // where the database name can be ommited once opened
+  // The managed open method returns a connection bound to its database name.
   open,
-  // More JS abstractions, that perform type casting and validation.
+  // Managed query methods add typed rows and normalize errors.
   transaction,
   execute,
   executeAsync,
+  prepare,
   executeBatch,
   executeBatchAsync,
 }

package/src/operations/execute.ts

@@ -4,10 +4,18 @@ import NitroSQLiteError from '../NitroSQLiteError'
 import type { NitroSQLiteQueryResult } from '../specs/NitroSQLiteQueryResult.nitro'
 import {
   isDatabaseOpen,
-  queueOperationAsync,
+  queueStatementAsync,
   startOperationSync,
 } from '../DatabaseQueue'
+import type { DatabaseQueueKey } from '../DatabaseQueue'
 
+/** Execute one SQL statement synchronously by database name.
+ * Uses the managed queue when the database has an open managed connection.
+ * @param dbName Name of an open native database.
+ * @param query SQL statement with optional positional placeholders.
+ * @param params Values bound to the placeholders.
+ * @returns The query result with typed rows.
+ */
 export function execute<Row extends QueryResultRow = never>(
   dbName: string,
   query: string,
@@ -24,8 +32,11 @@ export function executeManaged<Row extends QueryResultRow = never>(
   dbName: string,
   query: string,
   params?: SQLiteQueryParams,
+  queueKey: DatabaseQueueKey = dbName,
 ): QueryResult<Row> {
-  return startOperationSync(dbName, () => executeNative(dbName, query, params))
+  return startOperationSync(queueKey, () =>
+    executeNative(dbName, query, params),
+  )
 }
 
 export function executeNative<Row extends QueryResultRow = never>(
@@ -41,6 +52,13 @@ export function executeNative<Row extends QueryResultRow = never>(
   }
 }
 
+/** Execute one SQL statement asynchronously by database name.
+ * Uses the managed queue when the database has an open managed connection.
+ * @param dbName Name of an open native database.
+ * @param query SQL statement with optional positional placeholders.
+ * @param params Values bound to the placeholders.
+ * @returns A promise of the query result with typed rows.
+ */
 export async function executeAsync<Row extends QueryResultRow = never>(
   dbName: string,
   query: string,
@@ -57,8 +75,9 @@ export async function executeAsyncManaged<Row extends QueryResultRow = never>(
   dbName: string,
   query: string,
   params?: SQLiteQueryParams,
+  queueKey: DatabaseQueueKey = dbName,
 ): Promise<QueryResult<Row>> {
-  return queueOperationAsync(dbName, () =>
+  return queueStatementAsync(queueKey, () =>
     executeAsyncNative(dbName, query, params),
   )
 }

package/src/operations/executeBatch.ts

@@ -1,20 +1,28 @@
 import { HybridNitroSQLite } from '../nitro'
 import {
-  queueOperationAsync,
+  queueStatementAsync,
   startOperationSync,
   throwIfDatabaseIsNotOpen,
 } from '../DatabaseQueue'
 import NitroSQLiteError from '../NitroSQLiteError'
 import type { BatchQueryCommand, BatchQueryResult } from '../types'
+import type { DatabaseQueueKey } from '../DatabaseQueue'
 
+/** Execute a batch synchronously in one exclusive transaction.
+ * Requires an open managed connection; throws if it is busy or the batch is empty.
+ * @param dbName Name of the open database.
+ * @param commands SQL commands and optional parameter sets.
+ * @returns Total affected row count.
+ */
 export function executeBatch(
   dbName: string,
   commands: BatchQueryCommand[],
+  queueKey: DatabaseQueueKey = dbName,
 ): BatchQueryResult {
-  throwIfDatabaseIsNotOpen(dbName)
+  throwIfDatabaseIsNotOpen(queueKey)
 
   try {
-    return startOperationSync(dbName, () =>
+    return startOperationSync(queueKey, () =>
       HybridNitroSQLite.executeBatch(dbName, commands),
     )
   } catch (error) {
@@ -22,13 +30,20 @@ export function executeBatch(
   }
 }
 
+/** Queue a batch in one exclusive transaction.
+ * Requires an open managed connection; a failed command rolls back the batch.
+ * @param dbName Name of the open database.
+ * @param commands SQL commands and optional parameter sets.
+ * @returns A promise of the total affected row count.
+ */
 export async function executeBatchAsync(
   dbName: string,
   commands: BatchQueryCommand[],
+  queueKey: DatabaseQueueKey = dbName,
 ): Promise<BatchQueryResult> {
-  throwIfDatabaseIsNotOpen(dbName)
+  throwIfDatabaseIsNotOpen(queueKey)
 
-  return queueOperationAsync(dbName, async () => {
+  return queueStatementAsync(queueKey, async () => {
     try {
       return await HybridNitroSQLite.executeBatchAsync(dbName, commands)
     } catch (error) {

package/src/operations/prepare.ts

@@ -0,0 +1,69 @@
+import { HybridNitroSQLite } from '../nitro'
+import NitroSQLiteError from '../NitroSQLiteError'
+import type {
+  PreparedStatement,
+  QueryResult,
+  QueryResultRow,
+  SQLiteQueryParams,
+} from '../types'
+import { buildJSQueryResult } from './execute'
+import { queueOperationAsync, startOperationSync } from '../DatabaseQueue'
+import type { DatabaseQueueKey } from '../DatabaseQueue'
+
+/**
+ * Prepare one SQL statement on an open managed connection for repeated execution.
+ * Synchronous preparation throws if the connection is busy. Finalize the returned
+ * statement before closing the connection.
+ * @param dbName Database name or independent connection ID.
+ * @param query SQL statement with optional positional placeholders.
+ * @param queueKey Internal managed queue key; omit when using the public API.
+ * @returns A statement whose executions use the same connection queue.
+ */
+export function prepare(
+  dbName: string,
+  query: string,
+  queueKey: DatabaseQueueKey = dbName,
+): PreparedStatement {
+  try {
+    const nativeStatement = startOperationSync(queueKey, () =>
+      HybridNitroSQLite.prepare(dbName, query),
+    )
+
+    return {
+      get isFinalized() {
+        return nativeStatement.isFinalized
+      },
+      execute: <Row extends QueryResultRow = QueryResultRow>(
+        params?: SQLiteQueryParams,
+      ): QueryResult<Row> => {
+        try {
+          return startOperationSync(queueKey, () =>
+            buildJSQueryResult(nativeStatement.execute(params)),
+          )
+        } catch (error) {
+          throw NitroSQLiteError.fromError(error)
+        }
+      },
+      executeAsync: async <Row extends QueryResultRow = QueryResultRow>(
+        params?: SQLiteQueryParams,
+      ): Promise<QueryResult<Row>> => {
+        try {
+          return await queueOperationAsync(queueKey, async () =>
+            buildJSQueryResult(await nativeStatement.executeAsync(params)),
+          )
+        } catch (error) {
+          throw NitroSQLiteError.fromError(error)
+        }
+      },
+      finalize: () => {
+        try {
+          startOperationSync(queueKey, () => nativeStatement.finalize())
+        } catch (error) {
+          throw NitroSQLiteError.fromError(error)
+        }
+      },
+    }
+  } catch (error) {
+    throw NitroSQLiteError.fromError(error)
+  }
+}