feat(statement): server side prepared statement

Author: Daniele Briggi

.devcontainer/Dockerfile

@@ -0,0 +1,12 @@
+FROM oven/bun:debian
+
+# Config Bun
+ENV PATH="~/.bun/bin:${PATH}"
+RUN ln -s /usr/local/bin/bun /usr/local/bin/node
+
+# Update packages
+RUN if [ "debian" == "alpine" ] ; then apk update ; else apt-get update ; fi
+
+# Install Git
+RUN if [ "debian" == "alpine" ] ; then apk add git ; else apt-get install -y git ; fi
+

.devcontainer/devcontainer.json

@@ -0,0 +1,19 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/marcosgomesneto/bun-devcontainers/tree/main/src/basic-bun
+{
+  "name": "Bun",
+  "dockerFile": "Dockerfile",
+  // Configure tool-specific properties.
+  "customizations": {
+    // Configure properties specific to VS Code.
+    "vscode": {
+      // Add the IDs of extensions you want installed when the container is created.
+      "extensions": [
+        "oven.bun-vscode"
+      ]
+    }
+},
+"features": {
+	"ghcr.io/devcontainers/features/node:1": {}
+}
+}

.vscode/extensions.json

@@ -1,3 +1,7 @@
 {
-  "recommendations": ["kavod-io.vscode-jest-test-adapter", "esbenp.prettier-vscode", "github.vscode-github-actions", "hbenl.vscode-test-explorer"]
+  "recommendations": [
+    "esbenp.prettier-vscode",
+    "github.vscode-github-actions",
+    "hbenl.vscode-test-explorer"
+  ]
 }

bun.lockb

@@ -1,6 +1,6 @@
 {
   "name": "@sqlitecloud/drivers",
-  "version": "1.0.309",
+  "version": "1.0.331",
   "description": "SQLiteCloud drivers for Typescript/Javascript in edge, web and node clients",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -73,7 +73,7 @@
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^3.4.1",
     "express": "^4.19.2",
-    "husky": "^9.0.11",
+    "husky": "^9.1.7",
     "jest": "^29.7.0",
     "prettier": "^3.2.5",
     "sqlite3": "^5.1.7",

examples/with-javascript-express/package-lock.json

@@ -2,7 +2,7 @@
  * connection-tls.ts - connection via tls socket and sqlitecloud protocol
  */
 
-import { type SQLiteCloudConfig, SQLiteCloudError, type ErrorCallback, type ResultsCallback } from './types'
+import { type SQLiteCloudConfig, SQLiteCloudError, type ErrorCallback, type ResultsCallback, SQLiteCloudCommand } from './types'
 import { SQLiteCloudConnection } from './connection'
 import { getInitializationCommands } from './utilities'
 import {
@@ -23,8 +23,6 @@ import { Buffer } from 'buffer'
 
 import * as tls from 'tls'
 
-import fs from 'fs'
-
 /**
  * Implementation of SQLiteCloudConnection that connects to the database using specific tls APIs
  * that connect to native sockets or tls sockets and communicates via raw, binary protocol.
@@ -104,13 +102,17 @@ export class SQLiteCloudTlsConnection extends SQLiteCloudConnection {
   }
 
   /** Will send a command immediately (no queueing), return the rowset/result or throw an error */
-  transportCommands(commands: string, callback?: ResultsCallback): this {
+  transportCommands(commands: string | SQLiteCloudCommand, callback?: ResultsCallback): this {
     // connection needs to be established?
     if (!this.socket) {
       callback?.call(this, new SQLiteCloudError('Connection not established', { errorCode: 'ERR_CONNECTION_NOT_ESTABLISHED' }))
       return this
     }
 
+    if (typeof commands === 'string') {
+      commands = { query: commands } as SQLiteCloudCommand
+    }
+
     // reset buffer and rowset chunks, define response callback
     this.buffer = Buffer.alloc(0)
     this.startedOn = new Date()
@@ -148,7 +150,7 @@ export class SQLiteCloudTlsConnection extends SQLiteCloudConnection {
   // buffer to accumulate incoming data until an whole command is received and can be parsed
   private buffer: Buffer = Buffer.alloc(0)
   private startedOn: Date = new Date()
-  private executingCommands?: string
+  private executingCommands?: SQLiteCloudCommand
 
   // callback to be called when a command is finished processing
   private processCallback?: ResultsCallback

package-lock.json

@@ -2,7 +2,7 @@
  * transport-ws.ts - handles low level communication with sqlitecloud server via socket.io websocket
  */
 
-import { SQLiteCloudConfig, SQLiteCloudError, ErrorCallback, ResultsCallback } from './types'
+import { SQLiteCloudConfig, SQLiteCloudError, ErrorCallback, ResultsCallback, SQLiteCloudCommand } from './types'
 import { SQLiteCloudRowset } from './rowset'
 import { SQLiteCloudConnection } from './connection'
 import { io, Socket } from 'socket.io-client'
@@ -41,7 +41,7 @@ export class SQLiteCloudWebsocketConnection extends SQLiteCloudConnection {
   }
 
   /** Will send a command immediately (no queueing), return the rowset/result or throw an error */
-  transportCommands(commands: string, callback?: ResultsCallback): this {
+  transportCommands(commands: string | SQLiteCloudCommand, callback?: ResultsCallback): this {
     // connection needs to be established?
     if (!this.socket) {
       callback?.call(this, new SQLiteCloudError('Connection not established', { errorCode: 'ERR_CONNECTION_NOT_ESTABLISHED' }))

package.json

@@ -2,8 +2,8 @@
  * connection.ts - base abstract class for sqlitecloud server connections
  */
 
-import { SQLiteCloudConfig, SQLiteCloudError, ErrorCallback, ResultsCallback } from './types'
-import { validateConfiguration, prepareSql } from './utilities'
+import { SQLiteCloudConfig, SQLiteCloudError, ErrorCallback, ResultsCallback, SQLiteCloudCommand } from './types'
+import { validateConfiguration } from './utilities'
 import { OperationsQueue } from './queue'
 import { anonimizeCommand, getUpdateResults } from './utilities'
 
@@ -62,7 +62,7 @@ export abstract class SQLiteCloudConnection {
   protected abstract connectTransport(config: SQLiteCloudConfig, callback?: ErrorCallback): this
 
   /** Send a command, return the rowset/result or throw an error */
-  protected abstract transportCommands(commands: string, callback?: ResultsCallback): this
+  protected abstract transportCommands(commands: string | SQLiteCloudCommand, callback?: ResultsCallback): this
 
   /** Will log to console if verbose mode is enabled */
   protected log(message: string, ...optionalParams: any[]): void {
@@ -85,7 +85,7 @@ export abstract class SQLiteCloudConnection {
   }
 
   /** Will enquee a command to be executed and callback with the resulting rowset/result/error */
-  public sendCommands(commands: string, callback?: ResultsCallback): this {
+  public sendCommands(commands: string | SQLiteCloudCommand, callback?: ResultsCallback): this {
     this.operations.enqueue(done => {
       if (!this.connected) {
         const error = new SQLiteCloudError('Connection not established', { errorCode: 'ERR_CONNECTION_NOT_ESTABLISHED' })
@@ -108,32 +108,33 @@ export abstract class SQLiteCloudConnection {
    * 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
+   *  A SQLiteCloudCommand when the query is defined with question marks and bindings.
    * @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 = ''
+  public async sql(sql: TemplateStringsArray | string | SQLiteCloudCommand, ...values: any[]): Promise<any> {
+    let commands = { query: '' } as SQLiteCloudCommand
 
     // sql is a TemplateStringsArray, the 'raw' property is specific to TemplateStringsArray
     if (Array.isArray(sql) && 'raw' in sql) {
+      let query = ''
       sql.forEach((string, i) => {
-        preparedSql += string + (i < values.length ? '?' : '')
+        // TemplateStringsArray splits the string before each variable
+        // used in the template. Add the question mark
+        // to the end of the string for the number of used variables.
+        query += string + (i < values.length ? '?' : '')
       })
-      preparedSql = prepareSql(preparedSql, ...values)
+      commands = { query, parameters: values }
+    } else if (typeof sql === 'string') {
+      commands = { query: sql, parameters: values }
+    } else if (typeof sql === 'object') {
+      commands = sql as SQLiteCloudCommand
     } else {
-      if (typeof sql === 'string') {
-        if (values?.length > 0) {
-          preparedSql = prepareSql(sql, ...values)
-        } else {
-          preparedSql = sql
-        }
-      } else {
-        throw new Error('Invalid sql')
-      }
+      throw new Error('Invalid sql')
     }
 
     return new Promise((resolve, reject) => {
-      this.sendCommands(preparedSql, (error, results) => {
+      this.sendCommands(commands, (error, results) => {
         if (error) {
           reject(error)
         } else {