feat: implemented new SQLiteCloudVM (virtual machine)

feat: added new SQLiteCloudProvider protocol

Author: maxoly

Sources/SQLiteCloud/Core/SQLiteCloud.swift

@@ -51,7 +51,7 @@ import Darwin
 /// - SeeAlso: `SQLiteCloudConfig` for configuring the SQLite Cloud connection.
 /// - SeeAlso: `SQLiteCloudCommand` for representing SQL commands and queries.
 /// - SeeAlso: `SQLiteCloudResult` for representing the result of database operations.
-public final actor SQLiteCloud {
+public final actor SQLiteCloud: SQLiteCloudProvider {
     /// The sqlcloud connection opaque pointer.
     ///
     /// This property represents an opaque pointer to the SQLite Cloud connection.
@@ -1144,3 +1144,51 @@ public extension SQLiteCloud {
         }
     }
 }
+
+// MARK: - VM API
+
+public extension SQLiteCloud {
+    /// Compiles an SQL query into a byte-code virtual machine (VM). This method creates a 
+    /// `SQLiteCloudVM` instance that you can use to execute the compiled SQL statement.
+    ///
+    /// - Parameters:
+    ///   - query: The SQL query to compile.
+    ///
+    /// - Throws:
+    ///   - `SQLiteCloudError.connectionFailure`: If the connection to the SQLite Cloud 
+    ///     backend has failed. More details can be found in the associated value
+    ///     `SQLiteCloudError.ConnectionContext`.
+    ///
+    ///   - `SQLiteCloudError.handleError`: If an error occurs while handling the SQLite 
+    ///     Cloud operation.
+    ///
+    /// - Returns:
+    ///   A `SQLiteCloudVM` instance representing the compiled virtual machine for the SQL
+    ///    query. You can use this VM to execute the SQL statement.
+    ///
+    ///  Example usage:
+    ///  
+    ///  ```swift
+    ///  let query = "SELECT * FROM your_table"
+    ///  let vm = try await sqliteCloud.compile(query: query)
+    ///  try await vm.step()
+    ///  ```
+    func compile(query: String) async throws -> SQLiteCloudVM {
+        // Checks if connection is open and valid.
+        let conn = try getConnection()
+
+        // Compile an SQL statement into a byte-code virtual machine. 
+        // This function resembles the sqlite3_prepare SQLite API.
+        let vm = SQCloudVMCompile(conn, query, -1, nil)
+        
+        // Checks if compile is failed.
+        guard let vm = vm else {
+            let error =  SQLiteCloudError.handleError(connection: conn)
+            logError(category: "VIRTUAL MACHINE", message: "🚨 VM compile failed: \(error)")
+            throw error
+        }
+
+        logInfo(category: "VIRTUAL MACHINE", message: "🚀 '\(query)' virtual machine created succesfully")
+        return SQLiteCloudVM(vm: vm)
+    }
+}

Sources/SQLiteCloud/Core/SQLiteCloudError+Internal.swift

@@ -39,9 +39,15 @@ extension SQLiteCloudError.ExecutionContext {
 extension SQLiteCloudError.TaskError {
     static let urlHandlerFailed = SQLiteCloudError.TaskError(code: -5, message: "Cannot create URL Handler")
     static let cannotCreateOutputFile = SQLiteCloudError.TaskError(code: -6, message: "Cannot create output file")
-    static let invalidNumberOfRows = SQLiteCloudError.TaskError(code: -6, message: "Invalid number of rows.")
-    static let invalidBlobSizeRead = SQLiteCloudError.TaskError(code: -7, message: "Invalid blob size read.")
-    static let errorWritingBlob = SQLiteCloudError.TaskError(code: -8, message: "Error writing blob.")
+    static let invalidNumberOfRows = SQLiteCloudError.TaskError(code: -7, message: "Invalid number of rows.")
+    static let invalidBlobSizeRead = SQLiteCloudError.TaskError(code: -8, message: "Invalid blob size read.")
+    static let errorWritingBlob = SQLiteCloudError.TaskError(code: -9, message: "Error writing blob.")
+}
+
+extension SQLiteCloudError.VMContext {
+    static func invalidParameterIndex(index: Int) -> SQLiteCloudError.VMContext {
+        SQLiteCloudError.VMContext(code: -10, message: "Invalid parameter index [\(index)].")
+    }
 }
 
 extension SQLiteCloudError {
@@ -63,4 +69,12 @@ extension SQLiteCloudError {
 
         return SQLiteCloudError.unhandledError
     }
+
+    static func handleVMError(vm: OpaquePointer?) -> SQLiteCloudError {
+        let code = Int(SQCloudVMErrorCode(vm))
+        let message = String(SQCloudVMErrorMsg(vm))
+
+        let context = SQLiteCloudError.VMContext(code: code, message: message)
+        return SQLiteCloudError.virtualMachineFailure(context)
+    }
 }

Sources/SQLiteCloud/Core/SQLiteCloudError.swift

@@ -49,6 +49,11 @@ public enum SQLiteCloudError: Error, Sendable {
     /// An indication that a upload or download task error has occurred.
     /// More detailt can be found in the associated value `SQLiteCloudError.TaskError`
     case taskError(SQLiteCloudError.TaskError)
+
+    /// An indication that the virtual machine has failed.
+    /// The reasons can be of various types.
+    /// More details can be found in the associated value `SQLiteCloudError.VMContext`.
+    case virtualMachineFailure(SQLiteCloudError.VMContext)
 }
 
 public extension SQLiteCloudError {
@@ -93,4 +98,13 @@ public extension SQLiteCloudError {
         /// The errore message.
         public let message: String
     }
+
+    /// The context in which the virtual machine error occurred.
+    struct VMContext: Sendable {
+        /// The error code.
+        public let code: Int
+
+        /// The errore message.
+        public let message: String
+    }
 }