Add connection.sql method for simple async queries

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqlitecloud/drivers",
-  "version": "0.0.57",
+  "version": "1.0.82",
   "description": "SQLiteCloud drivers for Typescript/Javascript in edge, web and node clients",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",

src/drivers/connection.ts

@@ -3,9 +3,9 @@
  */
 
 import { SQLiteCloudConfig, SQLiteCloudError, ErrorCallback, ResultsCallback } from './types'
-import { validateConfiguration } from './utilities'
+import { validateConfiguration, prepareSql } from './utilities'
 import { OperationsQueue } from './queue'
-import { anonimizeCommand } from './utilities'
+import { anonimizeCommand, getUpdateResults } from './utilities'
 
 /**
  * Base class for SQLiteCloudConnection handles basics and defines methods.
@@ -102,6 +102,49 @@ export abstract class SQLiteCloudConnection {
     return this
   }
 
+  /**
+   * Sql is a promise based API for executing SQL statements. You can
+   * pass a simple string with a SQL statement or a template string
+   * using backticks and parameters in ${parameter} format. These parameters
+   * will be properly escaped and quoted like when using a prepared statement.
+   * @param sql A sql string or a template string in `backticks` format
+   * @returns An array of rows in case of selections or an object with
+   * metadata in case of insert, update, delete.
+   */
+  public async sql(sql: TemplateStringsArray | string, ...values: any[]): Promise<any> {
+    let preparedSql = ''
+
+    // sql is a TemplateStringsArray, the 'raw' property is specific to TemplateStringsArray
+    if (Array.isArray(sql) && 'raw' in sql) {
+      sql.forEach((string, i) => {
+        preparedSql += string + (i < values.length ? '?' : '')
+      })
+      preparedSql = prepareSql(preparedSql, ...values)
+    } else {
+      if (typeof sql === 'string') {
+        if (values?.length > 0) {
+          preparedSql = prepareSql(sql, ...values)
+        } else {
+          preparedSql = sql
+        }
+      } else {
+        throw new Error('Invalid sql')
+      }
+    }
+
+    return new Promise((resolve, reject) => {
+      this.sendCommands(preparedSql, (error, results) => {
+        if (error) {
+          reject(error)
+        } else {
+          // metadata for operations like insert, update, delete?
+          const context = getUpdateResults(results)
+          resolve(context ? context : results)
+        }
+      })
+    })
+  }
+
   /** Disconnect from server, release transport. */
   public abstract close(): this
 }

src/drivers/utilities.ts

@@ -3,6 +3,7 @@
 //
 
 import { SQLiteCloudConfig, SQLiteCloudError, SQLiteCloudDataTypes, DEFAULT_PORT, DEFAULT_TIMEOUT } from './types'
+import { SQLiteCloudArrayType } from './types'
 
 //
 // determining running environment, thanks to browser-or-node
@@ -149,6 +150,29 @@ export function prepareSql(sql: string, ...params: (SQLiteCloudDataTypes | SQLit
   return preparedSql
 }
 
+/** Converts results of an update or insert call into a more meaning full result set */
+export function getUpdateResults(results?: any): Record<string, any> | undefined {
+  if (results) {
+    if (Array.isArray(results) && results.length > 0) {
+      switch (results[0]) {
+        case SQLiteCloudArrayType.ARRAY_TYPE_SQLITE_EXEC:
+          return {
+            type: results[0],
+            index: results[1],
+            lastID: results[2], // ROWID (sqlite3_last_insert_rowid)
+            changes: results[3], // CHANGES(sqlite3_changes)
+            totalChanges: results[4], // TOTAL_CHANGES (sqlite3_total_changes)
+            finalized: results[5], // FINALIZED
+            //
+            rowId: results[2] // same as lastId
+          }
+      }
+    }
+  }
+
+  return undefined
+}
+
 /**
  * Many of the methods in our API may contain a callback as their last argument.
  * This method will take the arguments array passed to the method and return an object