feat: clarify known errors and allowed sql types

Author: pmorris-dev

README.md

@@ -173,6 +173,32 @@ const db = await Database.load('mydb.db', {
 > **Note:** Database paths are relative to the app's config directory. Unlike
 > `tauri-plugin-sql`, no `sqlite:` prefix is needed.
 
+### Parameter Binding and Types
+
+All query methods (`execute`, `fetchAll`, `fetchOne`) support parameter binding using
+the `$1`, `$2`, etc. syntax. Values must be of type `SqlValue`:
+
+```typescript
+type SqlValue = string | number | boolean | null | Uint8Array
+```
+
+Supported SQLite types:
+
+   * **TEXT** - `string` values (also used for DATE, TIME, DATETIME)
+   * **INTEGER** - `number` values (integers)
+   * **REAL** - `number` values (floating point)
+   * **BOOLEAN** - `boolean` values
+   * **NULL** - `null` value
+   * **BLOB** - `Uint8Array` for binary data
+
+```typescript
+// Example with different types
+await db.execute(
+   'INSERT INTO data (text, int, real, bool, blob) VALUES ($1, $2, $3, $4, $5)',
+   ['hello', 42, 3.14, true, new Uint8Array([1, 2, 3])]
+)
+```
+
 ### Executing Write Operations
 
 Use `execute()` for INSERT, UPDATE, DELETE, or any query that modifies data:
@@ -205,9 +231,46 @@ const deleteResult = await db.execute(
 )
 ```
 
+### Handling Errors
+
+Handle database errors gracefully using structured error responses:
+
+```typescript
+import type { SqliteError } from '@silvermine/tauri-plugin-sqlite';
+
+try {
+   await db.execute(
+      'INSERT INTO users (id, name) VALUES ($1, $2)',
+      [1, 'Alice']
+   );
+} catch (err) {
+   const error = err as SqliteError;
+
+   // Check error code for specific handling
+   if (error.code.startsWith('SQLITE_CONSTRAINT')) {
+      console.error('Constraint violation:', error.message);
+   } else if (error.code === 'DATABASE_NOT_LOADED') {
+      console.error('Database not initialized');
+   } else {
+      console.error('Database error:', error.code, error.message);
+   }
+}
+```
+
+Common error codes include:
+
+   * `SQLITE_CONSTRAINT` - Constraint violation (unique, foreign key, etc.)
+   * `SQLITE_NOTFOUND` - Table or column not found
+   * `DATABASE_NOT_LOADED` - Database hasn't been loaded yet
+   * `INVALID_PATH` - Invalid database path
+   * `IO_ERROR` - File system error
+   * `MIGRATION_ERROR` - Migration failed
+   * `READ_ONLY_QUERY_IN_EXECUTE` - Attempted to use execute() for a read-only query
+   * `MULTIPLE_ROWS_RETURNED` - `fetchOne()` query returned multiple rows
+
 ### Executing SELECT Queries
 
-Use `fetchAll()` for all read operations:
+Use `fetchAll()` or `fetchOne()` for all read operations:
 
 ```typescript
 type User = {id: number, name: string, email: string}
@@ -234,6 +297,11 @@ if (user) {
 }
 ```
 
+> **Note:** `fetchOne()` validates that the query returns exactly 0 or 1 rows. If your
+> query returns multiple rows, it will throw a `MULTIPLE_ROWS_RETURNED` error. This helps
+> catch bugs where a query unexpectedly returns multiple results. Use `fetchAll()` if you
+> expect multiple rows.
+
 ### Closing Connections
 
 ```typescript

api-iife.js

@@ -1,12 +1,36 @@
 import { invoke } from '@tauri-apps/api/core'
 
+/**
+ * Valid SQLite parameter binding value types.
+ *
+ * SQLite supports a limited set of types for parameter binding:
+ * - `string` - TEXT, DATE, TIME, DATETIME
+ * - `number` - INTEGER, REAL
+ * - `boolean` - BOOLEAN
+ * - `null` - NULL
+ * - `Uint8Array` - BLOB (binary data)
+ */
+export type SqlValue = string | number | boolean | null | Uint8Array
+
 export interface QueryResult {
    /** The number of rows affected by the query. */
    rowsAffected: number
    /** The last inserted row ID (SQLite ROWID). */
    lastInsertId: number
 }
 
+/**
+ * Structured error returned from SQLite operations.
+ *
+ * All errors thrown by the plugin will have this structure.
+ */
+export interface SqliteError {
+   /** Machine-readable error code (e.g., "SQLITE_CONSTRAINT", "DATABASE_NOT_LOADED") */
+   code: string
+   /** Human-readable error message */
+   message: string
+}
+
 /**
  * Custom configuration for SQLite database connection
  */
@@ -108,7 +132,7 @@ export default class Database {
     * );
     * ```
     */
-   async execute(query: string, bindValues?: unknown[]): Promise<QueryResult> {
+   async execute(query: string, bindValues?: SqlValue[]): Promise<QueryResult> {
       const [rowsAffected, lastInsertId] = await invoke<[number, number]>(
          'plugin:sqlite|execute',
          {
@@ -145,7 +169,7 @@ export default class Database {
     * );
     * ```
     */
-   async fetchAll<T>(query: string, bindValues?: unknown[]): Promise<T> {
+   async fetchAll<T>(query: string, bindValues?: SqlValue[]): Promise<T> {
       const result = await invoke<T>('plugin:sqlite|fetch_all', {
          db: this.path,
          query,
@@ -177,8 +201,8 @@ export default class Database {
     * }
     * ```
     */
-   async fetchOne<T>(query: string, bindValues?: unknown[]): Promise<T | undefined> {
-      const result = await invoke<T | undefined>('plugin:sqlite|select_one', {
+   async fetchOne<T>(query: string, bindValues?: SqlValue[]): Promise<T | undefined> {
+      const result = await invoke<T | undefined>('plugin:sqlite|fetch_one', {
          db: this.path,
          query,
          values: bindValues ?? []

guest-js/index.ts

@@ -1,19 +1,89 @@
 use serde::{Serialize, Serializer};
 
+/// Result type alias for plugin operations.
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// Structured error response for frontend.
+#[derive(Serialize)]
+struct ErrorResponse {
+   code: String,
+   message: String,
+}
+
+/// Error types for the SQLite plugin.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
-   // TODO: Add specific error variants for different failure cases
-   #[error("{0}")]
-   Custom(String),
+   /// Error from SQLx operations.
+   #[error(transparent)]
+   Sqlx(#[from] sqlx::Error),
+
+   /// Error from the connection manager.
+   #[error(transparent)]
+   ConnectionManager(#[from] sqlx_sqlite_conn_mgr::Error),
+
+   /// Error from database migrations.
+   #[error(transparent)]
+   Migration(#[from] sqlx::migrate::MigrateError),
+
+   /// Invalid database path provided.
+   #[error("invalid database path: {0}")]
+   InvalidPath(String),
+
+   /// Attempted to access a database that hasn't been loaded.
+   #[error("database {0} not loaded")]
+   DatabaseNotLoaded(String),
+
+   /// SQLite type that cannot be mapped to JSON.
+   #[error("unsupported datatype: {0}")]
+   UnsupportedDatatype(String),
+
+   /// I/O error when accessing database files.
+   #[error("io error: {0}")]
+   Io(#[from] std::io::Error),
+
+   /// Read-only query executed with execute command.
+   #[error("execute() should not be used for read-only queries. Use fetchX() instead.")]
+   ReadOnlyQueryInExecute,
+
+   /// Multiple rows returned from fetchOne query.
+   #[error("fetchOne() query returned {0} rows, expected 0 or 1")]
+   MultipleRowsReturned(usize),
+}
+
+impl Error {
+   /// Extract a structured error code from the error type.
+   ///
+   /// This provides machine-readable error codes for frontend error handling.
+   fn error_code(&self) -> String {
+      match self {
+         Error::Sqlx(e) => {
+            // Extract SQLite error codes from sqlx errors
+            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::Migration(_) => "MIGRATION_ERROR".to_string(),
+         Error::InvalidPath(_) => "INVALID_PATH".to_string(),
+         Error::DatabaseNotLoaded(_) => "DATABASE_NOT_LOADED".to_string(),
+         Error::UnsupportedDatatype(_) => "UNSUPPORTED_DATATYPE".to_string(),
+         Error::Io(_) => "IO_ERROR".to_string(),
+         Error::ReadOnlyQueryInExecute => "READ_ONLY_QUERY_IN_EXECUTE".to_string(),
+         Error::MultipleRowsReturned(_) => "MULTIPLE_ROWS_RETURNED".to_string(),
+      }
+   }
 }
 
 impl Serialize for Error {
    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
    where
       S: Serializer,
    {
-      serializer.serialize_str(self.to_string().as_ref())
+      let response = ErrorResponse {
+         code: self.error_code(),
+         message: self.to_string(),
+      };
+      response.serialize(serializer)
    }
 }