feat: refactor tx API + add backing functions

- Consolidated transaction API to address a design flaw
  - Calling BEGIN and then ceding the write conn could
     leave an open transaction dangling
- Added backing functions to wrapper.rs
- Added decoder and tests
- Added tests for error types

Author: pmorris-dev

Cargo.lock

@@ -23,6 +23,7 @@ futures-core = "0.3.31"
 time = "0.3.44"
 tokio = { version = "1.48.0", features = ["sync"] }
 indexmap = { version = "2.12.1", features = ["serde"] }
+base64 = "0.22.1"
 
 # SQLx for types and queries (time feature enables datetime type decoding)
 sqlx = { version = "0.8.6", features = ["sqlite", "json", "time", "runtime-tokio"] }

Cargo.toml

@@ -304,45 +304,32 @@ if (user) {
 
 ### Using Transactions
 
-Transactions ensure that multiple operations either all succeed or all fail together,
-maintaining data consistency:
+Execute multiple database operations atomically using `executeTransaction()`. All
+statements either succeed together or 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
+// Execute multiple inserts atomically
+await db.executeTransaction([
+   ['INSERT INTO users (name, email) VALUES ($1, $2)', ['Alice', 'alice@example.com']],
+   ['INSERT INTO audit_log (action, user) VALUES ($1, $2)', ['user_created', 'Alice']]
+]);
+
+// Bank transfer example - all operations succeed or all fail
+await db.executeTransaction([
+   ['UPDATE accounts SET balance = balance - $1 WHERE id = $2', [100, 1]],
+   ['UPDATE accounts SET balance = balance + $1 WHERE id = $2', [100, 2]],
+   ['INSERT INTO transfers (from_id, to_id, amount) VALUES ($1, $2, $3)', [1, 2, 100]]
+]);
+```
+
+**How it works:**
+
+   * Automatically executes `BEGIN` before running statements
+   * Executes all statements in order
+   * Commits with `COMMIT` if all statements succeed
+   * Rolls back with `ROLLBACK` if any statement fails
+   * The write connection is held for the entire transaction, ensuring atomicity
+   * Errors are thrown after rollback, preserving the original error message
 
 ### Closing Connections
 

README.md

@@ -1,3 +1,4 @@
 fn main() {
+   // TODO: Add commands to the plugin
    tauri_plugin::Builder::new(&["hello"]).build();
 }

build.rs

@@ -212,74 +212,44 @@ export default class Database {
    }
 
    /**
-    * **beginTransaction**
+    * **executeTransaction**
     *
-    * Begins a new database transaction. All subsequent operations will be
-    * part of this transaction until `commitTransaction()` or `rollbackTransaction()`
-    * is called.
+    * Executes multiple statements atomically within a transaction.
+    * All statements either succeed together or fail together.
     *
-    * Transactions provide atomicity - either all operations succeed or all are rolled back.
+    * The function automatically:
+    * - Begins a transaction (BEGIN)
+    * - Executes all statements in order
+    * - Commits on success (COMMIT)
+    * - Rolls back on any error (ROLLBACK)
     *
-    * @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.
+    * @param statements - Array of [query, values?] tuples to execute
+    * @returns Promise that resolves when all statements complete successfully
+    * @throws SqliteError if any statement fails (after rollback)
     *
     * @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;
-    * }
+    * // Execute multiple inserts atomically
+    * await db.executeTransaction([
+    *    ['INSERT INTO users (name, email) VALUES ($1, $2)', ['Alice', 'alice@example.com']],
+    *    ['INSERT INTO audit_log (action, user) VALUES ($1, $2)', ['user_created', 'Alice']]
+    * ]);
+    *
+    * // Mixed operations
+    * await db.executeTransaction([
+    *    ['UPDATE accounts SET balance = balance - $1 WHERE id = $2', [100, 1]],
+    *    ['UPDATE accounts SET balance = balance + $1 WHERE id = $2', [100, 2]],
+    *    ['INSERT INTO transfers (from_id, to_id, amount) VALUES ($1, $2, $3)', [1, 2, 100]]
+    * ]);
     * ```
     */
-   async rollbackTransaction(): Promise<void> {
-      await invoke('plugin:sqlite|rollback_transaction', {
-         db: this.path
+   async executeTransaction(statements: Array<[string, SqlValue[]?]>): Promise<void> {
+      await invoke('plugin:sqlite|execute_transaction', {
+         db: this.path,
+         statements: statements.map(([query, values]) => ({
+            query,
+            values: values ?? []
+         }))
       })
    }
 

guest-js/index.ts

@@ -0,0 +1,157 @@
+use serde_json::Value as JsonValue;
+use sqlx::sqlite::SqliteValueRef;
+use sqlx::{TypeInfo, Value, ValueRef};
+use time::PrimitiveDateTime;
+
+use crate::Error;
+
+/// Convert a SQLite value to a JSON value.
+///
+/// This function handles the type conversion from SQLite's native types
+/// to JSON-compatible representations.
+pub fn to_json(value: SqliteValueRef) -> Result<JsonValue, Error> {
+   if value.is_null() {
+      return Ok(JsonValue::Null);
+   }
+
+   let column_type = value.type_info();
+
+   // Handle types based on SQLite's type affinity
+   let result = match column_type.name() {
+      "TEXT" => {
+         if let Ok(v) = value.to_owned().try_decode::<String>() {
+            JsonValue::String(v)
+         } else {
+            JsonValue::Null
+         }
+      }
+
+      "REAL" => {
+         if let Ok(v) = value.to_owned().try_decode::<f64>() {
+            JsonValue::from(v)
+         } else {
+            JsonValue::Null
+         }
+      }
+
+      "INTEGER" | "NUMERIC" => {
+         if let Ok(v) = value.to_owned().try_decode::<i64>() {
+            JsonValue::Number(v.into())
+         } else {
+            JsonValue::Null
+         }
+      }
+
+      "BOOLEAN" => {
+         if let Ok(v) = value.to_owned().try_decode::<bool>() {
+            JsonValue::Bool(v)
+         } else {
+            JsonValue::Null
+         }
+      }
+
+      "DATE" => {
+         // SQLite stores dates as TEXT in ISO 8601 format
+         if let Ok(v) = value.to_owned().try_decode::<String>() {
+            JsonValue::String(v)
+         } else {
+            JsonValue::Null
+         }
+      }
+
+      "TIME" => {
+         // SQLite stores time as TEXT in HH:MM:SS format
+         if let Ok(v) = value.to_owned().try_decode::<String>() {
+            JsonValue::String(v)
+         } else {
+            JsonValue::Null
+         }
+      }
+
+      "DATETIME" => {
+         // Try to decode as PrimitiveDateTime
+         if let Ok(dt) = value.to_owned().try_decode::<PrimitiveDateTime>() {
+            JsonValue::String(dt.to_string())
+         } else if let Ok(v) = value.to_owned().try_decode::<String>() {
+            // Fall back to string representation
+            JsonValue::String(v)
+         } else {
+            JsonValue::Null
+         }
+      }
+
+      "BLOB" => {
+         if let Ok(blob) = value.to_owned().try_decode::<Vec<u8>>() {
+            // Encode binary data as base64 for JSON serialization
+            JsonValue::String(base64_encode(&blob))
+         } else {
+            JsonValue::Null
+         }
+      }
+
+      "NULL" => JsonValue::Null,
+
+      _ => {
+         // For unknown types, try to decode as text
+         if let Ok(text) = value.to_owned().try_decode::<String>() {
+            JsonValue::String(text)
+         } else {
+            return Err(Error::UnsupportedDatatype(format!(
+               "Unknown SQLite type: {}",
+               column_type.name()
+            )));
+         }
+      }
+   };
+
+   Ok(result)
+}
+
+/// Base64 encode binary data for JSON serialization.
+///
+/// SQLite BLOB columns are encoded as base64 strings when serialized to JSON,
+/// as JSON does not have a native binary type.
+fn base64_encode(data: &[u8]) -> String {
+   use std::io::Write;
+
+   let mut buf = Vec::new();
+   {
+      let mut encoder =
+         base64::write::EncoderWriter::new(&mut buf, &base64::engine::general_purpose::STANDARD);
+      encoder.write_all(data).unwrap();
+   }
+   String::from_utf8(buf).unwrap()
+}
+
+#[cfg(test)]
+mod tests {
+   use super::*;
+
+   #[test]
+   fn test_base64_encode() {
+      assert_eq!(base64_encode(b"hello"), "aGVsbG8=");
+      assert_eq!(base64_encode(&[1, 2, 3, 4, 5]), "AQIDBAU=");
+      assert_eq!(base64_encode(&[]), "");
+   }
+
+   #[test]
+   fn test_base64_encode_binary() {
+      // Test with binary data including null bytes
+      assert_eq!(base64_encode(&[0, 0, 0]), "AAAA");
+      assert_eq!(base64_encode(&[255, 255, 255]), "////");
+   }
+
+   #[test]
+   fn test_base64_encode_large() {
+      // Test with larger binary data
+      let data: Vec<u8> = (0..255).collect();
+      let encoded = base64_encode(&data);
+      assert!(!encoded.is_empty());
+      // Verify it's valid base64 (only contains valid chars)
+      assert!(
+         encoded
+            .chars()
+            .all(|c| c.is_alphanumeric() || c == '+' || c == '/' || c == '=')
+      );
+   }
+}