feat: Migrate JS-sided locks to DatabaseQueue for transactions and executeBatch commands (#227)

* Update bun.lockb

* feat: implement locks for `executeBatch`

* feat: add better errors

* feat: improve concurrency features

* refactor: rename databaseQueue variables

* feat: add `isExcusive` parameter to `transaction`

* fix: styling

* fix: handle errors in sync `executeBatch`

* fix: add NitroSQLite prefix to custom error

* refactor: remove type exports

* fix: database queue promise chaining

* refactor: remove redundant session functions

* refactor: move db name to constants

* chore: add package sources to example ts files

* refactor: restructure test db setup

* feat: add prefix to native C++ exception

* fix: add back line

* fix: transaction rollback result

* test: add transaction queuing test

* feat: adapt tests to new error types

* fix: make all transaction callbacks async

* refactor: export NitroSQLiteError class from package

* fix: transaction type

* fix: make another transaction callback async

* fix: always throw error on rollback

* refactor: rename variable

* test: add more DatabaseQueue tests

* refactor: re-arrange tests and extract error messages and strings

Author: chrispader

example/src/tests/db.ts

@@ -4,24 +4,40 @@ import type {
   BatchQueryCommand,
 } from 'react-native-nitro-sqlite'
 import { open } from 'react-native-nitro-sqlite'
+import {
+  getDatabaseQueue,
+  type DatabaseQueue,
+} from '../../../package/src/DatabaseQueue'
 
 const chance = new Chance()
 
-export let testDb: NitroSQLiteConnection | undefined
+export const TEST_DB_NAME = 'test'
+
+export let testDb: NitroSQLiteConnection
+export let testDbQueue: DatabaseQueue
 export function resetTestDb() {
   try {
     if (testDb != null) {
       testDb.close()
       testDb.delete()
     }
+
     testDb = open({
-      name: 'test',
+      name: TEST_DB_NAME,
     })
+    testDbQueue = getDatabaseQueue(TEST_DB_NAME)
+
+    testDb.execute('DROP TABLE IF EXISTS User;')
+    testDb.execute(
+      'CREATE TABLE User ( id REAL PRIMARY KEY, name TEXT NOT NULL, age REAL, networth REAL) STRICT;',
+    )
   } catch (e) {
     console.warn('Error resetting user database', e)
   }
 }
 
+const LARGE_DB_NAME = 'large'
+
 // Copyright 2024 Oscar Franco
 // Taken from "op-sqlite" example project.
 // Used to demonstrate the performance of NitroSQLite.
@@ -34,7 +50,7 @@ export function resetLargeDb() {
       largeDb.delete()
     }
     largeDb = open({
-      name: 'large',
+      name: LARGE_DB_NAME,
     })
 
     largeDb.execute(

example/src/tests/unit/common.ts

@@ -1,35 +1,27 @@
 import { Chance } from 'chance'
 import {
-  NitroSQLiteConnection,
   enableSimpleNullHandling,
+  NitroSQLiteError,
 } from 'react-native-nitro-sqlite'
-import { testDb as testDbInternal, resetTestDb } from '../db'
+import { resetTestDb } from '../db'
 import chai from 'chai'
 
-export function isError(e: unknown): e is Error {
-  return e instanceof Error
+export const TEST_ERROR_CODES = {
+  EXPECT_NITRO_SQLITE_ERROR: 'Should have thrown a valid NitroSQLiteError',
+  EXPECT_PROMISE_REJECTION: 'Should have thrown a promise rejection',
+} as const
+
+export const TEST_ERROR_MESSAGE = 'Error from callback'
+export const TEST_ERROR = new Error(TEST_ERROR_MESSAGE)
+
+export function isNitroSQLiteError(e: unknown): e is NitroSQLiteError {
+  return e instanceof NitroSQLiteError
 }
 
 export const expect = chai.expect
 export const chance = new Chance()
 
-export let testDb: NitroSQLiteConnection
-
 export function setupTestDb() {
   enableSimpleNullHandling(false)
-
-  try {
-    resetTestDb()
-
-    if (testDbInternal == null) throw new Error('Failed to reset test database')
-
-    testDbInternal.execute('DROP TABLE IF EXISTS User;')
-    testDbInternal.execute(
-      'CREATE TABLE User ( id REAL PRIMARY KEY, name TEXT NOT NULL, age REAL, networth REAL) STRICT;',
-    )
-
-    testDb = testDbInternal!
-  } catch (e) {
-    console.warn('Error resetting user database', e)
-  }
+  resetTestDb()
 }

example/src/tests/unit/index.ts

@@ -1,9 +1,10 @@
 import { beforeEach, describe } from '../MochaRNAdapter'
 import { setupTestDb } from './common'
-import registerExecuteUnitTests from './specs/execute.spec'
-import registerTransactionUnitTests from './specs/transaction.spec'
-import registerExecuteBatchUnitTests from './specs/executeBatch.spec'
+import registerExecuteUnitTests from './specs/operations/execute.spec'
+import registerTransactionUnitTests from './specs/operations/transaction.spec'
+import registerExecuteBatchUnitTests from './specs/operations/executeBatch.spec'
 import registerTypeORMUnitTestsSpecs from './specs/typeorm.spec'
+import registerDatabaseQueueUnitTests from './specs/DatabaseQueue.spec'
 
 export function registerUnitTests() {
   beforeEach(setupTestDb)
@@ -13,6 +14,8 @@ export function registerUnitTests() {
     registerTransactionUnitTests()
     registerExecuteBatchUnitTests()
   })
+
+  registerDatabaseQueueUnitTests()
 }
 
 export function registerTypeORMUnitTests() {

example/src/tests/unit/specs/DatabaseQueue.spec.ts

@@ -0,0 +1,182 @@
+import {
+  expect,
+  isNitroSQLiteError,
+  TEST_ERROR,
+  TEST_ERROR_CODES,
+  TEST_ERROR_MESSAGE,
+} from '../common'
+import { describe, it } from '../../MochaRNAdapter'
+import { testDb, testDbQueue } from '../../db'
+import type { BatchQueryCommand } from 'react-native-nitro-sqlite'
+
+const TEST_QUERY = 'SELECT * FROM [User];'
+
+const TEST_BATCH_COMMANDS: BatchQueryCommand[] = [{ query: TEST_QUERY }]
+
+export default function registerDatabaseQueueUnitTests() {
+  describe('Database Queue', () => {
+    it('multiple transactions are queued', async () => {
+      const transaction1Promise = testDb.transaction(async (tx) => {
+        tx.execute(TEST_QUERY)
+
+        expect(testDbQueue.queue.length).to.equal(2)
+        expect(testDbQueue.inProgress).to.equal(true)
+
+        await new Promise<void>((resolve) => setTimeout(resolve, 100))
+
+        tx.execute(TEST_QUERY)
+
+        expect(testDbQueue.queue.length).to.equal(2)
+        expect(testDbQueue.inProgress).to.equal(true)
+      })
+
+      expect(testDbQueue.inProgress).to.equal(true)
+      expect(testDbQueue.queue.length).to.equal(0)
+
+      const transaction2Promise = testDb.transaction(async (tx) => {
+        tx.execute(TEST_QUERY)
+      })
+
+      expect(testDbQueue.queue.length).to.equal(1)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      const transaction3Promise = testDb.transaction(async (tx) => {
+        tx.execute(TEST_QUERY)
+      })
+
+      await transaction1Promise
+
+      expect(testDbQueue.queue.length).to.equal(1)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      await transaction2Promise
+
+      expect(testDbQueue.queue.length).to.equal(0)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      await transaction3Promise
+
+      expect(testDbQueue.queue.length).to.equal(0)
+      expect(testDbQueue.inProgress).to.equal(false)
+    })
+
+    it('multiple executeBatchAsync operations are queued', async () => {
+      const executeBatch1Promise = testDb.executeBatchAsync(TEST_BATCH_COMMANDS)
+
+      expect(testDbQueue.queue.length).to.equal(0)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      const executeBatch2Promise = testDb.executeBatchAsync(TEST_BATCH_COMMANDS)
+
+      expect(testDbQueue.queue.length).to.equal(1)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      const executeBatch3Promise = testDb.executeBatchAsync(TEST_BATCH_COMMANDS)
+
+      expect(testDbQueue.queue.length).to.equal(2)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      await executeBatch1Promise
+
+      expect(testDbQueue.queue.length).to.equal(1)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      await executeBatch2Promise
+
+      expect(testDbQueue.queue.length).to.equal(0)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      await executeBatch3Promise
+
+      expect(testDbQueue.queue.length).to.equal(0)
+      expect(testDbQueue.inProgress).to.equal(false)
+    })
+
+    it('mixed transactions and executeBatchAsync operations are queued', async () => {
+      const transaction1Promise = testDb.transaction(async (tx) => {
+        tx.execute('SELECT * FROM [User];')
+      })
+
+      expect(testDbQueue.queue.length).to.equal(0)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      const executeBatch1Promise = testDb.executeBatchAsync(TEST_BATCH_COMMANDS)
+
+      expect(testDbQueue.queue.length).to.equal(1)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      const transaction2Promise = testDb.transaction(async (tx) => {
+        tx.execute(TEST_QUERY)
+      })
+
+      expect(testDbQueue.queue.length).to.equal(2)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      const executeBatch2Promise = testDb.executeBatchAsync(TEST_BATCH_COMMANDS)
+
+      expect(testDbQueue.queue.length).to.equal(3)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      await transaction1Promise
+
+      expect(testDbQueue.queue.length).to.equal(2)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      await executeBatch1Promise
+
+      expect(testDbQueue.queue.length).to.equal(1)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      await transaction2Promise
+
+      expect(testDbQueue.queue.length).to.equal(0)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      await executeBatch2Promise
+
+      expect(testDbQueue.queue.length).to.equal(0)
+      expect(testDbQueue.inProgress).to.equal(false)
+    })
+
+    it('errors are thrown through DatabaseQueue', async () => {
+      const transaction1Promise = testDb.transaction(async (tx) => {
+        tx.execute('SELECT * FROM [User];')
+        throw TEST_ERROR
+      })
+
+      expect(testDbQueue.queue.length).to.equal(0)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      const executeBatch1Promise = testDb.executeBatchAsync(TEST_BATCH_COMMANDS)
+
+      expect(testDbQueue.queue.length).to.equal(1)
+      expect(testDbQueue.inProgress).to.equal(true)
+
+      try {
+        await transaction1Promise
+
+        expect(testDbQueue.queue.length).to.equal(0)
+        expect(testDbQueue.inProgress).to.equal(true)
+      } catch (e) {
+        if (isNitroSQLiteError(e)) {
+          expect(e.message).to.include(TEST_ERROR_MESSAGE)
+        } else {
+          expect.fail(TEST_ERROR_CODES.EXPECT_NITRO_SQLITE_ERROR)
+        }
+      }
+
+      try {
+        await executeBatch1Promise
+
+        expect(testDbQueue.queue.length).to.equal(0)
+        expect(testDbQueue.inProgress).to.equal(false)
+      } catch (e) {
+        if (isNitroSQLiteError(e)) {
+          expect(e.message).to.include(TEST_ERROR_MESSAGE)
+        } else {
+          expect.fail(TEST_ERROR_CODES.EXPECT_NITRO_SQLITE_ERROR)
+        }
+      }
+    })
+  })
+}

example/src/tests/unit/specs/execute.spec.ts renamed to example/src/tests/unit/specs/operations/execute.spec.ts

@@ -1,9 +1,10 @@
-import { chance, expect, isError, testDb } from '../common'
+import { chance, expect, isNitroSQLiteError } from '../../common'
 import {
   enableSimpleNullHandling,
   NITRO_SQLITE_NULL,
 } from 'react-native-nitro-sqlite'
-import { describe, it } from '../../MochaRNAdapter'
+import { describe, it } from '../../../MochaRNAdapter'
+import { testDb } from '../../../db'
 
 export default function registerExecuteUnitTests() {
   describe('execute', () => {
@@ -93,7 +94,7 @@ export default function registerExecuteUnitTests() {
             [id, name, age, networth],
           )
         } catch (e: unknown) {
-          if (isError(e)) {
+          if (isNitroSQLiteError(e)) {
             expect(e.message).to.include(
               'cannot store TEXT value in REAL column User.age',
             )

example/src/tests/unit/specs/executeBatch.spec.ts renamed to example/src/tests/unit/specs/operations/executeBatch.spec.ts

@@ -1,6 +1,7 @@
-import { chance, expect, testDb } from '../common'
+import { chance, expect } from '../../common'
 import type { BatchQueryCommand } from 'react-native-nitro-sqlite'
-import { describe, it } from '../../MochaRNAdapter'
+import { describe, it } from '../../../MochaRNAdapter'
+import { testDb } from '../../../db'
 
 export default function registerExecuteBatchUnitTests() {
   describe('executeBatch', () => {