feat: refactor to separate pure Rust

Author: pmorris-dev

Cargo.lock

@@ -3,6 +3,7 @@ resolver = "3"
 members = [
    "crates/sqlx-sqlite-conn-mgr",
    "crates/sqlx-sqlite-observer",
+   "crates/sqlx-sqlite-toolkit",
 ]
 
 [package]
@@ -33,6 +34,15 @@ sqlx = { version = "0.8.6", features = ["sqlite", "json", "time", "runtime-tokio
 # Connection manager
 sqlx-sqlite-conn-mgr = { path = "crates/sqlx-sqlite-conn-mgr" }
 
+# Toolkit (high-level API — builders, transactions, decoding)
+sqlx-sqlite-toolkit = { path = "crates/sqlx-sqlite-toolkit", features = ["observer"] }
+
+# Observer types (for payload conversion)
+sqlx-sqlite-observer = { path = "crates/sqlx-sqlite-observer", features = ["conn-mgr"] }
+
+# Async stream support for observer subscriptions
+futures = "0.3"
+
 [build-dependencies]
 tauri-plugin = { version = "2.5.1", features = ["build"] }
 

Cargo.toml

@@ -11,6 +11,11 @@ fn main() {
       "close",
       "close_all",
       "remove",
+      "get_migration_events",
+      "observe",
+      "subscribe",
+      "unsubscribe",
+      "unobserve",
    ])
    .build();
 }

api-iife.js

@@ -13,11 +13,11 @@ keywords = ["sqlite", "sqlx", "reactive", "observer", "database"]
 categories = ["database", "asynchronous"]
 
 [features]
-conn-mgr = ["dep:sqlx-sqlite-conn-mgr"]
 # Bundle SQLite by default - preupdate hooks require SQLITE_ENABLE_PREUPDATE_HOOK
 # which most system SQLite libraries don't have enabled.
 default = ["bundled"]
 bundled = ["libsqlite3-sys/bundled"]
+conn-mgr = ["dep:sqlx-sqlite-conn-mgr"]
 
 [dependencies]
 tokio = { version = "1.49.0", features = ["sync"] }

build.rs

@@ -62,19 +62,19 @@ The library uses SQLite's native hooks for transaction-safe change tracking:
 │ (captures data) │     │  (Vec<Event>)   │     │                 │
 └─────────────────┘     └────────┬────────┘     └─────────────────┘
                                  │                       ▲
-                    ┌────────────┼────────────┐          │
-                    │            │            │          │
-              ┌─────▼────┐  ┌────▼─────┐      │          │
-              │  COMMIT  │  │ ROLLBACK │      │          │
-              └─────┬────┘  └────┬─────┘      │          │
-                    │            │            │          │
-                    ▼            ▼            │          │
-              on_commit()   on_rollback()     │          │
-                    │            │            │          │
-                    │       buffer.clear()    │          │
-                    │       (discard)         │          │
-                    │                         │          │
-                    └─────────────────────────┴──────────┘
+                    ┌────────────|                       │
+                    │            │                       │
+              ┌─────▼────┐  ┌────▼─────┐                 │
+              │  COMMIT  │  │ ROLLBACK │                 │
+              └─────┬────┘  └────┬─────┘                 │
+                    │            │                       │
+                    ▼            ▼                       │
+              on_commit()   on_rollback()                │
+                    │            │                       │
+                    │       buffer.clear()               │
+                    │       (discard)                    │
+                    │                                    │
+                    └────────────────────────────────────┘
                             change_tx.send()
                             (publish)
 ```
@@ -283,6 +283,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let config = ObserverConfig::new()
         .with_tables(["users"])
         .with_capture_values(false);
+
     let observer = SqliteObserver::new(
         SqlitePool::connect("sqlite:mydb.db").await?,
         config,

crates/sqlx-sqlite-observer/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "sqlx-sqlite-toolkit"
+# Sync major.minor with major.minor of SQLx crate
+version = "0.8.6"
+license = "MIT"
+edition = "2024"
+rust-version = "1.89"
+
+[features]
+default = []
+observer = ["dep:sqlx-sqlite-observer"]
+
+[dependencies]
+sqlx-sqlite-conn-mgr = { path = "../sqlx-sqlite-conn-mgr" }
+sqlx-sqlite-observer = { path = "../sqlx-sqlite-observer", features = ["conn-mgr"], optional = true }
+sqlx = { version = "0.8.6", features = ["sqlite", "json", "time", "runtime-tokio"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+thiserror = "2.0"
+indexmap = { version = "2.12", features = ["serde"] }
+base64 = "0.22"
+time = "0.3"
+uuid = { version = "1.11", features = ["v4"] }
+tokio = { version = "1.48.0", features = ["sync", "rt"] }
+tracing = { version = "0.1", default-features = false, features = ["std", "release_max_level_off"] }
+
+[dev-dependencies]
+tempfile = "3.23.0"
+tokio = { version = "1.48.0", features = ["rt-multi-thread", "macros"] }

crates/sqlx-sqlite-observer/README.md

@@ -9,7 +9,7 @@ use serde_json::Value as JsonValue;
 use sqlx_sqlite_conn_mgr::AttachedSpec;
 
 use crate::Error;
-use crate::wrapper::{WriteQueryResult, bind_value};
+use crate::wrapper::{DatabaseWrapper, WriteQueryResult, bind_value};
 
 /// Builder for SELECT queries returning multiple rows
 pub struct FetchAllBuilder {
@@ -155,18 +155,14 @@ impl IntoFuture for FetchOneBuilder {
 
 /// Builder for write queries (INSERT/UPDATE/DELETE)
 pub struct ExecuteBuilder {
-   db: Arc<sqlx_sqlite_conn_mgr::SqliteDatabase>,
+   db: DatabaseWrapper,
    query: String,
    values: Vec<JsonValue>,
    attached: Vec<AttachedSpec>,
 }
 
 impl ExecuteBuilder {
-   pub(crate) fn new(
-      db: Arc<sqlx_sqlite_conn_mgr::SqliteDatabase>,
-      query: String,
-      values: Vec<JsonValue>,
-   ) -> Self {
+   pub(crate) fn new(db: DatabaseWrapper, query: String, values: Vec<JsonValue>) -> Self {
       Self {
          db,
          query,
@@ -184,7 +180,7 @@ impl ExecuteBuilder {
    /// Execute the write operation
    pub async fn execute(self) -> Result<WriteQueryResult, Error> {
       if self.attached.is_empty() {
-         // No attached databases - use regular writer
+         // No attached databases - use wrapper's writer (routes through observer when enabled)
          let mut writer = self.db.acquire_writer().await?;
          let mut q = sqlx::query(&self.query);
          for value in self.values {
@@ -198,7 +194,8 @@ impl ExecuteBuilder {
       } else {
          // With attached database(s) - acquire writer with attached database(s)
          let mut conn =
-            sqlx_sqlite_conn_mgr::acquire_writer_with_attached(&self.db, self.attached).await?;
+            sqlx_sqlite_conn_mgr::acquire_writer_with_attached(self.db.inner(), self.attached)
+               .await?;
 
          let mut q = sqlx::query(&self.query);
          for value in self.values {
@@ -227,7 +224,7 @@ impl IntoFuture for ExecuteBuilder {
 }
 
 /// Helper to decode SQLite rows to JSON
-fn decode_rows(
+pub(crate) fn decode_rows(
    rows: Vec<sqlx::sqlite::SqliteRow>,
 ) -> Result<Vec<IndexMap<String, JsonValue>>, Error> {
    use sqlx::{Column, Row};

crates/sqlx-sqlite-toolkit/Cargo.toml

@@ -0,0 +1,81 @@
+/// Result type alias for toolkit operations.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Error types for SQLite toolkit operations.
+///
+/// These are pure database-operation errors with no Tauri dependencies.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+   /// Error from SQLx operations.
+   #[error(transparent)]
+   Sqlx(#[from] sqlx::Error),
+
+   /// Error from the connection manager.
+   #[error(transparent)]
+   ConnectionManager(#[from] sqlx_sqlite_conn_mgr::Error),
+
+   /// SQLite type that cannot be mapped to JSON.
+   #[error("unsupported datatype: {0}")]
+   UnsupportedDatatype(String),
+
+   /// Multiple rows returned from fetchOne query.
+   #[error("fetchOne() query returned {0} rows, expected 0 or 1")]
+   MultipleRowsReturned(usize),
+
+   /// Transaction failed and rollback also failed.
+   #[error("transaction failed: {transaction_error}; rollback also failed: {rollback_error}")]
+   TransactionRollbackFailed {
+      transaction_error: String,
+      rollback_error: String,
+   },
+
+   /// Transaction has already been committed or rolled back.
+   #[error("transaction has already been finalized (committed or rolled back)")]
+   TransactionAlreadyFinalized,
+
+   /// Transaction already active for this database.
+   #[error("transaction already active for database: {0}")]
+   TransactionAlreadyActive(String),
+
+   /// No active transaction for this database.
+   #[error("no active transaction for database: {0}")]
+   NoActiveTransaction(String),
+
+   /// Invalid transaction token provided.
+   #[error("invalid transaction token")]
+   InvalidTransactionToken,
+
+   /// I/O error when accessing database files.
+   #[error("io error: {0}")]
+   Io(#[from] std::io::Error),
+
+   /// Generic error for operations that don't fit other categories.
+   #[error("{0}")]
+   Other(String),
+}
+
+impl Error {
+   /// Extract a structured error code from the error type.
+   ///
+   /// This provides machine-readable error codes for error handling.
+   pub fn error_code(&self) -> String {
+      match self {
+         Error::Sqlx(e) => {
+            if let Some(code) = e.as_database_error().and_then(|db_err| db_err.code()) {
+               return format!("SQLITE_{}", code);
+            }
+            "SQLX_ERROR".to_string()
+         }
+         Error::ConnectionManager(_) => "CONNECTION_ERROR".to_string(),
+         Error::UnsupportedDatatype(_) => "UNSUPPORTED_DATATYPE".to_string(),
+         Error::MultipleRowsReturned(_) => "MULTIPLE_ROWS_RETURNED".to_string(),
+         Error::TransactionRollbackFailed { .. } => "TRANSACTION_ROLLBACK_FAILED".to_string(),
+         Error::TransactionAlreadyFinalized => "TRANSACTION_ALREADY_FINALIZED".to_string(),
+         Error::TransactionAlreadyActive(_) => "TRANSACTION_ALREADY_ACTIVE".to_string(),
+         Error::NoActiveTransaction(_) => "NO_ACTIVE_TRANSACTION".to_string(),
+         Error::InvalidTransactionToken => "INVALID_TRANSACTION_TOKEN".to_string(),
+         Error::Io(_) => "IO_ERROR".to_string(),
+         Error::Other(_) => "ERROR".to_string(),
+      }
+   }
+}