feat: support transactions on the API

Author: pmorris-dev

README.md

@@ -302,6 +302,48 @@ if (user) {
 > catch bugs where a query unexpectedly returns multiple results. Use `fetchAll()` if you
 > expect multiple rows.
 
+### Using Transactions
+
+Transactions ensure that multiple operations either all succeed or all fail together,
+maintaining data consistency:
+
+```typescript
+// Begin a transaction
+await db.beginTransaction();
+
+try {
+   // Execute multiple operations atomically
+   await db.execute(
+      'INSERT INTO users (name, email) VALUES ($1, $2)',
+      ['Alice', 'alice@example.com']
+   );
+
+   await db.execute(
+      'INSERT INTO audit_log (action, user) VALUES ($1, $2)',
+      ['user_created', 'Alice']
+   );
+
+   // Commit if all operations succeed
+   await db.commitTransaction();
+   console.log('Transaction completed successfully');
+
+} catch (error) {
+   // Rollback if any operation fails
+   await db.rollbackTransaction();
+   console.error('Transaction failed, rolled back:', error);
+   throw error;
+}
+```
+
+**Important Notes:**
+
+   * All operations between `beginTransaction()` and
+     `commitTransaction()`/`rollbackTransaction()` are executed as a single atomic unit
+   * If an error occurs, call `rollbackTransaction()` to discard all changes
+   * Nested transactions are not supported
+   * Always ensure transactions are either committed or rolled back to avoid locking
+     issues
+
 ### Closing Connections
 
 ```typescript

api-iife.js

@@ -211,6 +211,78 @@ export default class Database {
       return result
    }
 
+   /**
+    * **beginTransaction**
+    *
+    * Begins a new database transaction. All subsequent operations will be
+    * part of this transaction until `commitTransaction()` or `rollbackTransaction()`
+    * is called.
+    *
+    * Transactions provide atomicity - either all operations succeed or all are rolled back.
+    *
+    * @example
+    * ```ts
+    * await db.beginTransaction();
+    * try {
+    *    await db.execute('INSERT INTO users (name) VALUES ($1)', ['Alice']);
+    *    await db.execute('INSERT INTO logs (action) VALUES ($1)', ['user_created']);
+    *    await db.commitTransaction();
+    * } catch (error) {
+    *    await db.rollbackTransaction();
+    *    throw error;
+    * }
+    * ```
+    */
+   async beginTransaction(): Promise<void> {
+      await invoke('plugin:sqlite|begin_transaction', {
+         db: this.path
+      })
+   }
+
+   /**
+    * **commitTransaction**
+    *
+    * Commits the current transaction, making all changes permanent.
+    *
+    * @example
+    * ```ts
+    * await db.beginTransaction();
+    * await db.execute('INSERT INTO users (name) VALUES ($1)', ['Alice']);
+    * await db.execute('INSERT INTO logs (action) VALUES ($1)', ['user_created']);
+    * await db.commitTransaction();
+    * ```
+    */
+   async commitTransaction(): Promise<void> {
+      await invoke('plugin:sqlite|commit_transaction', {
+         db: this.path
+      })
+   }
+
+   /**
+    * **rollbackTransaction**
+    *
+    * Rolls back the current transaction, discarding all changes made since
+    * `beginTransaction()` was called.
+    *
+    * @example
+    * ```ts
+    * await db.beginTransaction();
+    * try {
+    *    await db.execute('INSERT INTO users (name) VALUES ($1)', ['Alice']);
+    *    await db.execute('INSERT INTO logs (action) VALUES ($1)', ['user_created']);
+    *    await db.commitTransaction();
+    * } catch (error) {
+    *    await db.rollbackTransaction();
+    *    throw error;
+    * }
+    * ```
+    */
+   async rollbackTransaction(): Promise<void> {
+      await invoke('plugin:sqlite|rollback_transaction', {
+         db: this.path
+      })
+   }
+
    /**
     * **close**
     *