fix: Make Model.executeQuery class funcs public (#87)

Author: kilnerm

README.md

@@ -222,35 +222,70 @@ Grade.deleteAll { error in
 }
 ```
 
-### Customization
+### Customizing your Model
 
-The ORM uses [Swift-Kuery](https://github.com/IBM-Swift/Swift-Kuery) which allows you to customize and execute your own queries without breaking any existing ORM functionality. You'll want to have access to the table for your object, which you can get with the `getTable()` function:
+The ORM defines an extension to `Model` which provides a number of `public static executeQuery(…)` functions. These can be used to create custom functions within your model that perform more complex database operations. The example below defines a Person model and with a custom function that will retrieve all records which have age > 20:
 
 ```swift
-do {
-  let table = Grade.getTable()
-} catch {
-  // Error
+// define the Person struct
+struct Person: Codable {
+    var firstname: String
+    var surname: String
+    var age: Int
 }
-```
 
-After you retrieve your table, you can create a `Query` object to specify what you want to execute on your database, and perform it like so:
-
-```swift
-executeQuery(query: Query) { (grade: Grade?, error: RequestError?) in
-  ...
+// extend Person to conform to model and add overTwenties function
+extension Person: Model {
+
+    // Define a synchronous function to retrieve all records of Person with age > 20
+    public static func getOverTwenties() -> [Person]? {
+        let wait = DispatchSemaphore(value: 0)
+        // First get the table
+        var table: Table
+        do {
+            table = try Person.getTable()
+        } catch {
+            // Handle error
+        }
+        // Define result, query and execute
+        var overTwenties: [Person]? = nil
+        let query = Select(from: table).where("age > 20")
+
+        Person.executeQuery(query: query, parameters: nil) { results, error in
+            guard let results = results else {
+                // Handle error
+            }
+            overTwenties = results
+            wait.signal()
+            return
+        }
+        wait.wait()
+        return overTwenties
+    }
 }
 ```
 
-You can customize the parameters passed into your closure after you execute a `Query` like so:
-
+Alternatively you can define and asynchronous getOverTwenties function:
 ```swift
-executeQuery(query: Query) { grade, error in
-  ...
+public static func getOverTwenties(oncompletion: @escaping ([Person]?, RequestError?)-> Void) {
+    var table: Table
+    do {
+        table = try Person.getTable()
+    } catch {
+        // Handle error
+    }
+    let query = Select(from: table).where("age > 20")
+    Person.executeQuery(query: query, parameters: nil, oncompletion)
 }
+```
 
-executeQuery(query: Query) { error in
-  ...
+which can be called in a fashion similar to the following:
+```swift
+Person.getOverTwenties() { result, error in
+    guard let result = result else {
+        // Handle error
+    }
+    // Use result
 }
 ```
 

Sources/SwiftKueryORM/Model.swift

@@ -349,7 +349,7 @@ public extension Model {
         Self.executeQuery(query: query, parameters: parameters, using: db, onCompletion)
     }
 
-    internal func executeQuery(query: Query, parameters: [Any?], using db: Database? = nil, _ onCompletion: @escaping (Self?, RequestError?) -> Void ) {
+    private func executeQuery(query: Query, parameters: [Any?], using db: Database? = nil, _ onCompletion: @escaping (Self?, RequestError?) -> Void ) {
         Self.executeTask() { connection, error in
             guard let connection = connection else {
                 guard let error = error else {
@@ -372,7 +372,7 @@ public extension Model {
         }
     }
 
-    internal func executeQuery<I: Identifier>(query: Query, parameters: [Any?], using db: Database? = nil, _ onCompletion: @escaping (I?, Self?, RequestError?) -> Void ) {
+    private func executeQuery<I: Identifier>(query: Query, parameters: [Any?], using db: Database? = nil, _ onCompletion: @escaping (I?, Self?, RequestError?) -> Void ) {
         Self.executeTask() { connection, error in
             guard let connection = connection else {
                 guard let error = error else {
@@ -422,7 +422,12 @@ public extension Model {
         }
     }
 
-    internal static func executeQuery(query: Query, parameters: [Any?], using db: Database? = nil, _ onCompletion: @escaping (Self?, RequestError?) -> Void ) {
+    /// Allows custom functions on a model to query the database directly.
+    /// - Parameter query: The `Query` to execute
+    /// - Parameter parameters: An optional array of parameters to pass to the query
+    /// - Parameter using: Optional Database to use
+    /// - Parameter onCompletion: The function to be called when the execution of the query has completed. The function will be passed a tuple of (Self?, RequestError?), of which one will be nil, depending on whether the query was successful.
+    public static func executeQuery(query: Query, parameters: [Any?], using db: Database? = nil, _ onCompletion: @escaping (Self?, RequestError?) -> Void ) {
         Self.executeTask() { connection, error in
             guard let connection = connection else {
                 guard let error = error else {
@@ -462,7 +467,12 @@ public extension Model {
         }
     }
 
-    internal static func executeQuery<I: Identifier>(query: Query, parameters: [Any?], using db: Database? = nil, _ onCompletion: @escaping (I?, Self?, RequestError?) -> Void ) {
+    /// Allows custom functions on a model to query the database directly.
+    /// - Parameter query: The `Query` to execute
+    /// - Parameter parameters: An optional array of parameters to pass to the query
+    /// - Parameter using: Optional Database to use
+    /// - Parameter onCompletion: The function to be called when the execution of the query has completed. The function will be passed a tuple of (Identifier?, Self?, RequestError?), of which some will be nil, depending on whether the query was successful.
+    public static func executeQuery<I: Identifier>(query: Query, parameters: [Any?], using db: Database? = nil, _ onCompletion: @escaping (I?, Self?, RequestError?) -> Void ) {
         Self.executeTask() { connection, error in
             guard let connection = connection else {
                 guard let error = error else {
@@ -520,9 +530,12 @@ public extension Model {
         }
     }
 
+    /// Allows custom functions on a model to query the database directly.
+    /// - Parameter query: The `Query` to execute
+    /// - Parameter parameters: An optional array of parameters to pass to the query
     /// - Parameter using: Optional Database to use
-    /// - Returns: A tuple ([Model], RequestError)
-    internal static func executeQuery(query: Query, parameters: [Any?]? = nil, using db: Database? = nil, _ onCompletion: @escaping ([Self]?, RequestError?)-> Void ) {
+    /// - Parameter onCompletion: The function to be called when the execution of the query has completed. The function will be passed a tuple of ([Self]?, RequestError?), of which one will be nil, depending on whether the query was successful.
+    public static func executeQuery(query: Query, parameters: [Any?]? = nil, using db: Database? = nil, _ onCompletion: @escaping ([Self]?, RequestError?)-> Void ) {
         Self.executeTask() { connection, error in
             guard let connection = connection else {
                 guard let error = error else {
@@ -582,9 +595,12 @@ public extension Model {
         }
     }
 
+    /// Allows custom functions on a model to query the database directly.
+    /// - Parameter query: The `Query` to execute
+    /// - Parameter parameters: An optional array of parameters to pass to the query
     /// - Parameter using: Optional Database to use
-    /// - Returns: A tuple ([Model], RequestError)
-    internal static func executeQuery<I: Identifier>(query: Query, parameters: [Any?]? = nil, using db: Database? = nil, _ onCompletion: @escaping ([(I, Self)]?, RequestError?) -> Void ) {
+    /// - Parameter onCompletion: The function to be called when the execution of the query has completed. The function will be passed a tuple of ([Identifier, Self]?, RequestError?), of which one will be nil, depending on whether the query was successful.
+    public static func executeQuery<I: Identifier>(query: Query, parameters: [Any?]? = nil, using db: Database? = nil, _ onCompletion: @escaping ([(I, Self)]?, RequestError?) -> Void ) {
         Self.executeTask() { connection, error in
             guard let connection = connection else {
                 guard let error = error else {
@@ -658,10 +674,12 @@ public extension Model {
         }
     }
 
+    /// Allows custom functions on a model to query the database directly.
+    /// - Parameter query: The `Query` to execute
+    /// - Parameter parameters: An optional array of parameters to pass to the query
     /// - Parameter using: Optional Database to use
-    /// - Returns: An optional RequestError
-
-    internal static func executeQuery(query: Query, parameters: [Any?]? = nil, using db: Database? = nil, _ onCompletion: @escaping (RequestError?) -> Void ) {
+    /// - Parameter onCompletion: The function to be called when the execution of the query has completed. The function will be passed a RequestError? which may be nil, depending on whether the query was successful.
+    public static func executeQuery(query: Query, parameters: [Any?]? = nil, using db: Database? = nil, _ onCompletion: @escaping (RequestError?) -> Void ) {
         Self.executeTask() { connection, error in
             guard let connection = connection else {
                 guard let error = error else {