@sqlitecloud/drivers 0.0.50 → 1.0.122

package/README.md

@@ -17,7 +17,7 @@ npm install @sqlitecloud/drivers
 ```ts
 import { Database } from '@sqlitecloud/drivers'
 
-let database = new Database('sqlitecloud://user:password@xxx.sqlite.cloud:8860/chinook.db')
+let database = new Database('sqlitecloud://user:password@xxx.sqlite.cloud:8860/chinook.sqlite')
 
 let name = 'Breaking The Rules'
 

package/lib/drivers/connection-tls.d.ts

@@ -1,25 +1,29 @@
 /**
- * connection-tls.ts - handles low level communication with sqlitecloud server via tls socket and binary protocol
+ * connection-tls.ts - connection via tls socket and sqlitecloud protocol
  */
-import { SQLiteCloudConfig, ErrorCallback, ResultsCallback } from './types';
+import { type SQLiteCloudConfig, type ErrorCallback, type ResultsCallback } from './types';
 import { SQLiteCloudConnection } from './connection';
 /**
- * Implementation of SQLiteCloudConnection that connects directly to the database via tls socket and raw, binary protocol.
- * Connects with plain socket with no encryption is the ?insecure=1 parameter is specified.
- * SQLiteCloud low-level connection, will do messaging, handle socket, authentication, etc.
- * A connection socket is established when the connection is created and closed when the connection is closed.
- * All operations are serialized by waiting for any pending operations to complete. Once a connection is closed,
- * it cannot be reopened and you must create a new connection.
+ * Implementation of SQLiteCloudConnection that connects to the database using specific Bun APIs
+ * that connect to native sockets or tls sockets and communicates via raw, binary protocol.
  */
 export declare class SQLiteCloudTlsConnection extends SQLiteCloudConnection {
-    /** Currently opened tls socket used to communicated with SQLiteCloud server */
+    /** Currently opened bun socket used to communicated with SQLiteCloud server */
     private socket?;
     /** True if connection is open */
     get connected(): boolean;
     connectTransport(config: SQLiteCloudConfig, callback?: ErrorCallback): this;
     /** Will send a command immediately (no queueing), return the rowset/result or throw an error */
     transportCommands(commands: string, callback?: ResultsCallback): this;
-    /** Disconnect from server, release connection. */
+    private buffer;
+    private startedOn;
+    private executingCommands?;
+    private processCallback?;
+    /** Handles data received in response to an outbound command sent by processCommands */
+    private processCommandsData;
+    /** Completes a transaction initiated by processCommands */
+    private processCommandsFinish;
+    /** Disconnect immediately, release connection, no events. */
     close(): this;
 }
 export default SQLiteCloudTlsConnection;

package/lib/drivers/connection-tls.js

@@ -1,234 +1,218 @@
 "use strict";
 /**
- * connection-tls.ts - handles low level communication with sqlitecloud server via tls socket and binary protocol
+ * connection-tls.ts - connection via tls socket and sqlitecloud protocol
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLiteCloudTlsConnection = void 0;
 const types_1 = require("./types");
 const connection_1 = require("./connection");
-const protocol_1 = require("./protocol");
 const utilities_1 = require("./utilities");
-const protocol_2 = require("./protocol");
-const net_1 = __importDefault(require("net"));
-const tls_1 = __importDefault(require("tls"));
+const protocol_1 = require("./protocol");
+const tls = __importStar(require("tls"));
 /**
- * Implementation of SQLiteCloudConnection that connects directly to the database via tls socket and raw, binary protocol.
- * Connects with plain socket with no encryption is the ?insecure=1 parameter is specified.
- * SQLiteCloud low-level connection, will do messaging, handle socket, authentication, etc.
- * A connection socket is established when the connection is created and closed when the connection is closed.
- * All operations are serialized by waiting for any pending operations to complete. Once a connection is closed,
- * it cannot be reopened and you must create a new connection.
+ * Implementation of SQLiteCloudConnection that connects to the database using specific Bun APIs
+ * that connect to native sockets or tls sockets and communicates via raw, binary protocol.
  */
 class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
+    constructor() {
+        super(...arguments);
+        // processCommands sets up empty buffers, results callback then send the command to the server via socket.write
+        // onData is called when data is received, it will process the data until all data is retrieved for a response
+        // when response is complete or there's an error, finish is called to call the results callback set by processCommands...
+        // buffer to accumulate incoming data until an whole command is received and can be parsed
+        this.buffer = Buffer.alloc(0);
+        this.startedOn = new Date();
+    }
     /** True if connection is open */
     get connected() {
         return !!this.socket;
     }
     /* Opens a connection with the server and sends the initialization commands. Will throw in case of errors. */
+    /* eslint-disable @typescript-eslint/no-unused-vars */
     connectTransport(config, callback) {
-        // connection established while we were waiting in line?
-        console.assert(!this.connected, 'Connection already established');
-        // clear all listeners and call done in the operations queue
-        const finish = error => {
-            if (this.socket) {
-                this.socket.removeAllListeners('data');
-                this.socket.removeAllListeners('error');
-                this.socket.removeAllListeners('close');
-                if (error) {
-                    this.close();
-                }
-            }
-            callback === null || callback === void 0 ? void 0 : callback.call(this, error);
-        };
+        console.assert(!this.connected, 'SQLiteCloudTlsConnection.connect - connection already established');
+        if (this.config.verbose) {
+            console.debug(`-> connecting ${config === null || config === void 0 ? void 0 : config.host}:${config === null || config === void 0 ? void 0 : config.port}`);
+        }
         this.config = config;
         const initializationCommands = (0, utilities_1.getInitializationCommands)(config);
-        if (config.insecure) {
-            // connect to plain socket, without encryption, only if insecure parameter specified
-            // this option is mainly for testing purposes and is not available on production nodes
-            // which would need to connect using tls and proper certificates as per code below
-            const connectionOptions = {
-                host: config.host,
-                port: config.port
-            };
-            this.socket = net_1.default.connect(connectionOptions, () => {
-                console.warn(`TlsConnection.connectTransport - connected to ${config.host}:${config.port} using insecure protocol`);
-                // send initialization commands
-                console.assert(this.socket, 'Connection already closed');
-                this.transportCommands(initializationCommands, error => {
-                    if (error && this.socket) {
-                        this.close();
-                    }
-                    if (callback) {
-                        callback === null || callback === void 0 ? void 0 : callback.call(this, error);
-                        callback = undefined;
-                    }
-                    finish(error);
-                });
-            });
-        }
-        else {
-            // connect to tls socket, initialize connection, setup event handlers
-            this.socket = tls_1.default.connect(this.config.port, this.config.host, this.config.tlsOptions, () => {
-                const tlsSocket = this.socket;
-                if (!(tlsSocket === null || tlsSocket === void 0 ? void 0 : tlsSocket.authorized)) {
-                    const anonimizedError = (0, utilities_1.anonimizeError)(tlsSocket.authorizationError);
-                    console.error('Connection was not authorized', anonimizedError);
-                    this.close();
-                    finish(new types_1.SQLiteCloudError('Connection was not authorized', { cause: anonimizedError }));
-                }
-                else {
-                    // the connection was closed before it was even opened,
-                    // eg. client closed the connection before the server accepted it
-                    if (this.socket === null) {
-                        finish(new types_1.SQLiteCloudError('Connection was closed before it was done opening'));
-                        return;
-                    }
-                    // send initialization commands
-                    console.assert(this.socket, 'Connection already closed');
-                    this.transportCommands(initializationCommands, error => {
-                        if (error && this.socket) {
-                            this.close();
-                        }
-                        if (callback) {
-                            callback === null || callback === void 0 ? void 0 : callback.call(this, error);
-                            callback = undefined;
-                        }
-                        finish(error);
-                    });
+        // connect to plain socket, without encryption, only if insecure parameter specified
+        // this option is mainly for testing purposes and is not available on production nodes
+        // which would need to connect using tls and proper certificates as per code below
+        const connectionOptions = {
+            host: config.host,
+            port: config.port,
+            rejectUnauthorized: false,
+            // Server name for the SNI (Server Name Indication) TLS extension.
+            // https://r2.nodejs.org/docs/v6.11.4/api/tls.html#tls_class_tls_tlssocket
+            servername: config.host
+        };
+        this.socket = tls.connect(connectionOptions, () => {
+            var _a;
+            if (this.config.verbose) {
+                console.debug(`SQLiteCloudTlsConnection - connected to ${this.config.host}, authorized: ${(_a = this.socket) === null || _a === void 0 ? void 0 : _a.authorized}`);
+            }
+            this.transportCommands(initializationCommands, error => {
+                if (this.config.verbose) {
+                    console.debug(`SQLiteCloudTlsConnection - initialized connection`);
                 }
+                callback === null || callback === void 0 ? void 0 : callback.call(this, error);
             });
-        }
-        this.socket.on('close', () => {
-            this.socket = null;
-            finish(new types_1.SQLiteCloudError('Connection was closed'));
         });
-        this.socket.once('error', (error) => {
-            console.error('Connection error', error);
-            finish(new types_1.SQLiteCloudError('Connection error', { cause: error }));
+        this.socket.on('data', data => {
+            this.processCommandsData(data);
+        });
+        this.socket.on('error', error => {
+            this.close();
+            this.processCommandsFinish(new types_1.SQLiteCloudError('Connection error', { errorCode: 'ERR_CONNECTION_ERROR', cause: error }));
+        });
+        this.socket.on('end', () => {
+            this.close();
+            if (this.processCallback)
+                this.processCommandsFinish(new types_1.SQLiteCloudError('Server ended the connection', { errorCode: 'ERR_CONNECTION_ENDED' }));
+        });
+        this.socket.on('close', () => {
+            this.close();
+            this.processCommandsFinish(new types_1.SQLiteCloudError('Connection closed', { errorCode: 'ERR_CONNECTION_CLOSED' }));
         });
         return this;
     }
     /** Will send a command immediately (no queueing), return the rowset/result or throw an error */
     transportCommands(commands, callback) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         // connection needs to be established?
         if (!this.socket) {
             callback === null || callback === void 0 ? void 0 : callback.call(this, new types_1.SQLiteCloudError('Connection not established', { errorCode: 'ERR_CONNECTION_NOT_ESTABLISHED' }));
             return this;
         }
+        // reset buffer and rowset chunks, define response callback
+        this.buffer = Buffer.alloc(0);
+        this.startedOn = new Date();
+        this.processCallback = callback;
+        this.executingCommands = commands;
         // compose commands following SCPC protocol
-        commands = (0, protocol_1.formatCommand)(commands);
-        let buffer = Buffer.alloc(0);
-        const rowsetChunks = [];
-        // const startedOn = new Date()
-        // define what to do if an answer does not arrive within the set timeout
-        let socketTimeout;
-        // clear all listeners and call done in the operations queue
-        const finish = (error, result) => {
-            clearTimeout(socketTimeout);
-            if (this.socket) {
-                this.socket.removeAllListeners('data');
-                this.socket.removeAllListeners('error');
-                this.socket.removeAllListeners('close');
-            }
-            if (callback) {
-                callback === null || callback === void 0 ? void 0 : callback.call(this, error, result);
-                callback = undefined;
+        const formattedCommands = (0, protocol_1.formatCommand)(commands);
+        if ((_a = this.config) === null || _a === void 0 ? void 0 : _a.verbose) {
+            console.debug(`-> ${formattedCommands}`);
+        }
+        const timeoutMs = (_c = (_b = this.config) === null || _b === void 0 ? void 0 : _b.timeout) !== null && _c !== void 0 ? _c : 0;
+        if (timeoutMs > 0) {
+            const timeout = setTimeout(() => {
+                var _a;
+                callback === null || callback === void 0 ? void 0 : callback.call(this, new types_1.SQLiteCloudError('Connection timeout out', { errorCode: 'ERR_CONNECTION_TIMEOUT' }));
+                (_a = this.socket) === null || _a === void 0 ? void 0 : _a.destroy();
+                this.socket = undefined;
+            }, timeoutMs);
+            (_d = this.socket) === null || _d === void 0 ? void 0 : _d.write(formattedCommands, 'utf-8', () => {
+                clearTimeout(timeout); // Clear the timeout on successful write
+            });
+        }
+        else {
+            (_e = this.socket) === null || _e === void 0 ? void 0 : _e.write(formattedCommands, 'utf-8');
+        }
+        return this;
+    }
+    /** Handles data received in response to an outbound command sent by processCommands */
+    processCommandsData(data) {
+        var _a, _b, _c, _d, _e, _f;
+        try {
+            // append data to buffer as it arrives
+            if (data.length && data.length > 0) {
+                this.buffer = Buffer.concat([this.buffer, data]);
             }
-        };
-        // define the Promise that waits for the server response
-        const readData = (data) => {
-            var _a, _b;
-            try {
-                // on first ondata event, dataType is read from data, on subsequent ondata event, is read from buffer that is the concatanations of data received on each ondata event
-                let dataType = buffer.length === 0 ? data.subarray(0, 1).toString() : buffer.subarray(0, 1).toString('utf8');
-                buffer = Buffer.concat([buffer, data]);
-                const commandLength = (0, protocol_1.hasCommandLength)(dataType);
-                if (commandLength) {
-                    const commandLength = (0, protocol_1.parseCommandLength)(buffer);
-                    const hasReceivedEntireCommand = buffer.length - buffer.indexOf(' ') - 1 >= commandLength ? true : false;
-                    if (hasReceivedEntireCommand) {
-                        if ((_a = this.config) === null || _a === void 0 ? void 0 : _a.verbose) {
-                            let bufferString = buffer.toString('utf8');
-                            if (bufferString.length > 1000) {
-                                bufferString = bufferString.substring(0, 100) + '...' + bufferString.substring(bufferString.length - 40);
-                            }
-                            // const elapsedMs = new Date().getTime() - startedOn.getTime()
-                            // console.debug(`Receive: ${bufferString} - ${elapsedMs}ms`)
-                        }
-                        // need to decompress this buffer before decoding?
-                        if (dataType === protocol_1.CMD_COMPRESSED) {
-                            ;
-                            ({ buffer, dataType } = (0, protocol_1.decompressBuffer)(buffer));
-                        }
-                        if (dataType !== protocol_1.CMD_ROWSET_CHUNK) {
-                            (_b = this.socket) === null || _b === void 0 ? void 0 : _b.off('data', readData);
-                            const { data } = (0, protocol_1.popData)(buffer);
-                            finish(null, data);
-                        }
-                        else {
-                            // check if rowset received the ending chunk
-                            if ((0, protocol_1.bufferEndsWith)(buffer, protocol_1.ROWSET_CHUNKS_END)) {
-                                rowsetChunks.push(buffer);
-                                const parsedData = (0, protocol_2.parseRowsetChunks)(rowsetChunks);
-                                finish === null || finish === void 0 ? void 0 : finish.call(this, null, parsedData);
-                            }
-                            else {
-                                // no ending string? ask server for another chunk
-                                rowsetChunks.push(buffer);
-                                buffer = Buffer.alloc(0);
-                            }
+            let dataType = (_a = this.buffer) === null || _a === void 0 ? void 0 : _a.subarray(0, 1).toString();
+            if ((0, protocol_1.hasCommandLength)(dataType)) {
+                const commandLength = (0, protocol_1.parseCommandLength)(this.buffer);
+                const hasReceivedEntireCommand = this.buffer.length - this.buffer.indexOf(' ') - 1 >= commandLength ? true : false;
+                if (hasReceivedEntireCommand) {
+                    if ((_b = this.config) === null || _b === void 0 ? void 0 : _b.verbose) {
+                        let bufferString = this.buffer.toString('utf8');
+                        if (bufferString.length > 1000) {
+                            bufferString = bufferString.substring(0, 100) + '...' + bufferString.substring(bufferString.length - 40);
                         }
+                        const elapsedMs = new Date().getTime() - this.startedOn.getTime();
+                        console.debug(`<- ${bufferString} (${elapsedMs}ms)`);
                     }
-                }
-                else {
-                    // command with no explicit len so make sure that the final character is a space
-                    const lastChar = buffer.subarray(buffer.length - 1, buffer.length).toString('utf8');
-                    if (lastChar == ' ') {
-                        const { data } = (0, protocol_1.popData)(buffer);
-                        finish(null, data);
+                    // need to decompress this buffer before decoding?
+                    if (dataType === protocol_1.CMD_COMPRESSED) {
+                        ;
+                        ({ buffer: this.buffer, dataType } = (0, protocol_1.decompressBuffer)(this.buffer));
+                    }
+                    if (dataType !== protocol_1.CMD_ROWSET_CHUNK) {
+                        const { data } = (0, protocol_1.popData)(this.buffer);
+                        (_c = this.processCommandsFinish) === null || _c === void 0 ? void 0 : _c.call(this, null, data);
+                    }
+                    else {
+                        // check if rowset received the ending chunk in which case it can be unpacked
+                        if ((0, protocol_1.bufferEndsWith)(this.buffer, protocol_1.ROWSET_CHUNKS_END)) {
+                            const parsedData = (0, protocol_1.parseRowsetChunks)([this.buffer]);
+                            (_d = this.processCommandsFinish) === null || _d === void 0 ? void 0 : _d.call(this, null, parsedData);
+                        }
                     }
                 }
             }
-            catch (error) {
-                console.assert(error instanceof Error);
-                if (error instanceof Error) {
-                    finish(error);
+            else {
+                // command with no explicit len so make sure that the final character is a space
+                const lastChar = this.buffer.subarray(this.buffer.length - 1, this.buffer.length).toString('utf8');
+                if (lastChar == ' ') {
+                    const { data } = (0, protocol_1.popData)(this.buffer);
+                    (_e = this.processCommandsFinish) === null || _e === void 0 ? void 0 : _e.call(this, null, data);
                 }
             }
-        };
-        (_a = this.socket) === null || _a === void 0 ? void 0 : _a.once('close', () => {
-            finish(new types_1.SQLiteCloudError('Connection was closed', { cause: (0, utilities_1.anonimizeCommand)(commands) }));
-        });
-        (_b = this.socket) === null || _b === void 0 ? void 0 : _b.write(commands, 'utf8', () => {
-            var _a, _b;
-            // @ts-ignore
-            socketTimeout = setTimeout(() => {
-                const timeoutError = new types_1.SQLiteCloudError('Request timed out', { cause: (0, utilities_1.anonimizeCommand)(commands) });
-                // console.debug(`Request timed out, config.timeout is ${this.config?.timeout as number}ms`, timeoutError)
-                finish(timeoutError);
-            }, (_a = this.config) === null || _a === void 0 ? void 0 : _a.timeout);
-            (_b = this.socket) === null || _b === void 0 ? void 0 : _b.on('data', readData);
-        });
-        (_c = this.socket) === null || _c === void 0 ? void 0 : _c.once('error', (error) => {
-            console.error('Socket error', error);
-            this.close();
-            finish(new types_1.SQLiteCloudError('Socket error', { cause: (0, utilities_1.anonimizeError)(error) }));
-        });
-        return this;
+        }
+        catch (error) {
+            console.assert(error instanceof Error);
+            if (error instanceof Error) {
+                (_f = this.processCommandsFinish) === null || _f === void 0 ? void 0 : _f.call(this, error);
+            }
+        }
     }
-    /** Disconnect from server, release connection. */
+    /** Completes a transaction initiated by processCommands */
+    processCommandsFinish(error, result) {
+        if (error) {
+            if (this.processCallback) {
+                console.error('processCommandsFinish - error', error);
+            }
+            else {
+                console.warn('processCommandsFinish - error with no registered callback', error);
+            }
+        }
+        if (this.processCallback) {
+            this.processCallback(error, result);
+            //      this.processCallback = undefined
+        }
+    }
+    /** Disconnect immediately, release connection, no events. */
     close() {
-        console.assert(this.socket !== null, 'TlsConnection.close - connection already closed');
-        this.operations.clear();
         if (this.socket) {
+            this.socket.removeAllListeners();
             this.socket.destroy();
-            this.socket = null;
+            this.socket = undefined;
         }
-        this.socket = undefined;
+        this.operations.clear();
         return this;
     }
 }

package/lib/drivers/connection-ws.js

@@ -27,9 +27,9 @@ class SQLiteCloudWebsocketConnection extends connection_1.SQLiteCloudConnection
             console.assert(!this.connected, 'Connection already established');
             if (!this.socket) {
                 this.config = config;
-                const connectionString = this.config.connectionString;
-                const gatewayUrl = ((_a = this.config) === null || _a === void 0 ? void 0 : _a.gatewayUrl) || `ws://${this.config.host}:4000`;
-                this.socket = (0, socket_io_client_1.io)(gatewayUrl, { auth: { token: connectionString } });
+                const connectionstring = this.config.connectionstring;
+                const gatewayUrl = ((_a = this.config) === null || _a === void 0 ? void 0 : _a.gatewayurl) || `${this.config.host === 'localhost' ? 'ws' : 'wss'}://${this.config.host}:4000`;
+                this.socket = (0, socket_io_client_1.io)(gatewayUrl, { auth: { token: connectionstring } });
             }
             callback === null || callback === void 0 ? void 0 : callback.call(this, null);
         }

package/lib/drivers/connection.d.ts

@@ -8,10 +8,12 @@ import { OperationsQueue } from './queue';
  * Actual connection management and communication with the server in concrete classes.
  */
 export declare abstract class SQLiteCloudConnection {
-    /** Parse and validate provided connectionString or configuration */
+    /** Parse and validate provided connectionstring or configuration */
     constructor(config: SQLiteCloudConfig | string, callback?: ErrorCallback);
     /** Configuration passed by client or extracted from connection string */
     protected config: SQLiteCloudConfig;
+    /** Returns the connection's configuration */
+    getConfig(): SQLiteCloudConfig;
     /** Operations are serialized by waiting an any pending promises */
     protected operations: OperationsQueue;
     /** Connect will establish a tls or websocket transport to the server based on configuration and environment */
@@ -27,6 +29,16 @@ export declare abstract class SQLiteCloudConnection {
     verbose(): void;
     /** Will enquee a command to be executed and callback with the resulting rowset/result/error */
     sendCommands(commands: string, callback?: ResultsCallback): 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.
+     */
+    sql(sql: TemplateStringsArray | string, ...values: any[]): Promise<any>;
     /** Disconnect from server, release transport. */
     abstract close(): this;
 }

package/lib/drivers/connection.js

@@ -2,6 +2,15 @@
 /**
  * connection.ts - base abstract class for sqlitecloud server connections
  */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SQLiteCloudConnection = void 0;
 const types_1 = require("./types");
@@ -13,12 +22,12 @@ const utilities_2 = require("./utilities");
  * Actual connection management and communication with the server in concrete classes.
  */
 class SQLiteCloudConnection {
-    /** Parse and validate provided connectionString or configuration */
+    /** Parse and validate provided connectionstring or configuration */
     constructor(config, callback) {
         /** Operations are serialized by waiting an any pending promises */
         this.operations = new queue_1.OperationsQueue();
         if (typeof config === 'string') {
-            this.config = (0, utilities_1.validateConfiguration)({ connectionString: config });
+            this.config = (0, utilities_1.validateConfiguration)({ connectionstring: config });
         }
         else {
             this.config = (0, utilities_1.validateConfiguration)(config);
@@ -26,6 +35,10 @@ class SQLiteCloudConnection {
         // connect transport layer to server
         this.connect(callback);
     }
+    /** Returns the connection's configuration */
+    getConfig() {
+        return Object.assign({}, this.config);
+    }
     //
     // internal methods (some are implemented in concrete classes using different transport layers)
     //
@@ -37,7 +50,9 @@ class SQLiteCloudConnection {
                     console.error(`SQLiteCloudConnection.connect - error connecting ${this.config.host}:${this.config.port} ${error.toString()}`, error);
                     this.close();
                 }
-                callback === null || callback === void 0 ? void 0 : callback.call(this, error || null);
+                if (callback) {
+                    callback.call(this, error || null);
+                }
                 done(error);
             });
         });
@@ -47,7 +62,7 @@ class SQLiteCloudConnection {
     log(message, ...optionalParams) {
         if (this.config.verbose) {
             message = (0, utilities_2.anonimizeCommand)(message);
-            console.log(`${new Date().toISOString()} ${this.config.clientId}: ${message}`, ...optionalParams);
+            console.log(`${new Date().toISOString()} ${this.config.clientid}: ${message}`, ...optionalParams);
         }
     }
     /** Enable verbose logging for debug purposes */
@@ -62,12 +77,60 @@ class SQLiteCloudConnection {
                 callback === null || callback === void 0 ? void 0 : callback.call(this, error);
                 done(error);
             }
-            this.transportCommands(commands, (error, result) => {
-                callback === null || callback === void 0 ? void 0 : callback.call(this, error, result);
-                done(error);
-            });
+            else {
+                this.transportCommands(commands, (error, result) => {
+                    callback === null || callback === void 0 ? void 0 : callback.call(this, error, result);
+                    done(error);
+                });
+            }
         });
         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.
+     */
+    sql(sql, ...values) {
+        return __awaiter(this, void 0, void 0, function* () {
+            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 = (0, utilities_1.prepareSql)(preparedSql, ...values);
+            }
+            else {
+                if (typeof sql === 'string') {
+                    if ((values === null || values === void 0 ? void 0 : values.length) > 0) {
+                        preparedSql = (0, utilities_1.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 = (0, utilities_2.getUpdateResults)(results);
+                        resolve(context ? context : results);
+                    }
+                });
+            });
+        });
+    }
 }
 exports.SQLiteCloudConnection = SQLiteCloudConnection;