@sqlitecloud/drivers 0.0.40 → 0.0.50

package/lib/{transport-tls.d.ts → drivers/connection-tls.d.ts}

@@ -1,25 +1,25 @@
 /**
- * transport-tls.ts - handles low level communication with sqlitecloud server via tls socket and binary protocol
+ * connection-tls.ts - handles low level communication with sqlitecloud server via tls socket and binary protocol
  */
 import { SQLiteCloudConfig, ErrorCallback, ResultsCallback } from './types';
-import { ConnectionTransport } from './connection';
+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.
  */
-export declare class TlsSocketTransport implements ConnectionTransport {
-    /** Configuration passed to connect */
-    private config?;
+export declare class SQLiteCloudTlsConnection extends SQLiteCloudConnection {
     /** Currently opened tls socket used to communicated with SQLiteCloud server */
     private socket?;
     /** True if connection is open */
     get connected(): boolean;
-    connect(config: SQLiteCloudConfig, callback?: ErrorCallback): this;
+    connectTransport(config: SQLiteCloudConfig, callback?: ErrorCallback): this;
     /** Will send a command immediately (no queueing), return the rowset/result or throw an error */
-    processCommands(commands: string, callback?: ResultsCallback): this;
+    transportCommands(commands: string, callback?: ResultsCallback): this;
     /** Disconnect from server, release connection. */
     close(): this;
 }
+export default SQLiteCloudTlsConnection;

package/lib/drivers/connection-tls.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * connection-tls.ts - handles low level communication with sqlitecloud server via tls socket and binary protocol
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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"));
+/**
+ * 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.
+ */
+class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
+    /** 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. */
+    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);
+        };
+        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);
+                    });
+                }
+            });
+        }
+        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 }));
+        });
+        return this;
+    }
+    /** Will send a command immediately (no queueing), return the rowset/result or throw an error */
+    transportCommands(commands, callback) {
+        var _a, _b, _c;
+        // 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;
+        }
+        // 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;
+            }
+        };
+        // 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);
+                            }
+                        }
+                    }
+                }
+                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);
+                    }
+                }
+            }
+            catch (error) {
+                console.assert(error instanceof Error);
+                if (error instanceof Error) {
+                    finish(error);
+                }
+            }
+        };
+        (_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;
+    }
+    /** Disconnect from server, release connection. */
+    close() {
+        console.assert(this.socket !== null, 'TlsConnection.close - connection already closed');
+        this.operations.clear();
+        if (this.socket) {
+            this.socket.destroy();
+            this.socket = null;
+        }
+        this.socket = undefined;
+        return this;
+    }
+}
+exports.SQLiteCloudTlsConnection = SQLiteCloudTlsConnection;
+exports.default = SQLiteCloudTlsConnection;

package/lib/{transport-ws.d.ts → drivers/connection-ws.d.ts}

@@ -2,23 +2,22 @@
  * transport-ws.ts - handles low level communication with sqlitecloud server via socket.io websocket
  */
 import { SQLiteCloudConfig, ErrorCallback, ResultsCallback } from './types';
-import { ConnectionTransport } from './connection';
+import { SQLiteCloudConnection } from './connection';
 /**
  * Implementation of TransportConnection that connects to the database indirectly
  * via SQLite Cloud Gateway, a socket.io based deamon that responds to sql query
  * requests by returning results and rowsets in json format. The gateway handles
  * connect, disconnect, retries, order of operations, timeouts, etc.
  */
-export declare class WebSocketTransport implements ConnectionTransport {
-    /** Configuration passed to connect */
-    private config?;
+export declare class SQLiteCloudWebsocketConnection extends SQLiteCloudConnection {
     /** Socket.io used to communicated with SQLiteCloud server */
     private socket?;
     /** True if connection is open */
     get connected(): boolean;
-    connect(config: SQLiteCloudConfig, callback?: ErrorCallback): this;
+    connectTransport(config: SQLiteCloudConfig, callback?: ErrorCallback): this;
     /** Will send a command immediately (no queueing), return the rowset/result or throw an error */
-    processCommands(commands: string, callback?: ResultsCallback): this;
+    transportCommands(commands: string, callback?: ResultsCallback): this;
     /** Disconnect socket.io from server */
     close(): this;
 }
+export default SQLiteCloudWebsocketConnection;

package/lib/{transport-ws.js → drivers/connection-ws.js}

@@ -3,9 +3,10 @@
  * transport-ws.ts - handles low level communication with sqlitecloud server via socket.io websocket
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketTransport = void 0;
+exports.SQLiteCloudWebsocketConnection = void 0;
 const types_1 = require("./types");
 const rowset_1 = require("./rowset");
+const connection_1 = require("./connection");
 const socket_io_client_1 = require("socket.io-client");
 /**
  * Implementation of TransportConnection that connects to the database indirectly
@@ -13,13 +14,13 @@ const socket_io_client_1 = require("socket.io-client");
  * requests by returning results and rowsets in json format. The gateway handles
  * connect, disconnect, retries, order of operations, timeouts, etc.
  */
-class WebSocketTransport {
+class SQLiteCloudWebsocketConnection extends connection_1.SQLiteCloudConnection {
     /** 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. */
-    connect(config, callback) {
+    connectTransport(config, callback) {
         var _a;
         try {
             // connection established while we were waiting in line?
@@ -38,7 +39,7 @@ class WebSocketTransport {
         return this;
     }
     /** Will send a command immediately (no queueing), return the rowset/result or throw an error */
-    processCommands(commands, callback) {
+    transportCommands(commands, callback) {
         // 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' }));
@@ -53,7 +54,7 @@ class WebSocketTransport {
                 const { data, metadata } = response;
                 if (data && metadata) {
                     if (metadata.numberOfRows !== undefined && metadata.numberOfColumns !== undefined && metadata.columns !== undefined) {
-                        console.assert(Array.isArray(data), 'SQLiteCloudWebsocketConnection.processCommands - data is not an array');
+                        console.assert(Array.isArray(data), 'SQLiteCloudWebsocketConnection.transportCommands - data is not an array');
                         // we can recreate a SQLiteCloudRowset from the response which we know to be an array of arrays
                         // eslint-disable-next-line @typescript-eslint/no-unsafe-call
                         const rowset = new rowset_1.SQLiteCloudRowset(metadata, data.flat());
@@ -69,13 +70,15 @@ class WebSocketTransport {
     /** Disconnect socket.io from server */
     close() {
         var _a;
-        console.assert(this.socket !== null, 'WebsocketTransport.close - connection already closed');
+        console.assert(this.socket !== null, 'SQLiteCloudWebsocketConnection.close - connection already closed');
         if (this.socket) {
             (_a = this.socket) === null || _a === void 0 ? void 0 : _a.close();
             this.socket = undefined;
         }
+        this.operations.clear();
         this.socket = undefined;
         return this;
     }
 }
-exports.WebSocketTransport = WebSocketTransport;
+exports.SQLiteCloudWebsocketConnection = SQLiteCloudWebsocketConnection;
+exports.default = SQLiteCloudWebsocketConnection;

package/lib/drivers/connection.d.ts

@@ -0,0 +1,32 @@
+/**
+ * connection.ts - base abstract class for sqlitecloud server connections
+ */
+import { SQLiteCloudConfig, ErrorCallback, ResultsCallback } from './types';
+import { OperationsQueue } from './queue';
+/**
+ * Base class for SQLiteCloudConnection handles basics and defines methods.
+ * Actual connection management and communication with the server in concrete classes.
+ */
+export declare abstract class SQLiteCloudConnection {
+    /** 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;
+    /** 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 */
+    protected connect(callback?: ErrorCallback): this;
+    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;
+    /** Will log to console if verbose mode is enabled */
+    protected log(message: string, ...optionalParams: any[]): void;
+    /** Returns true if connection is open */
+    abstract get connected(): boolean;
+    /** Enable verbose logging for debug purposes */
+    verbose(): void;
+    /** Will enquee a command to be executed and callback with the resulting rowset/result/error */
+    sendCommands(commands: string, callback?: ResultsCallback): this;
+    /** Disconnect from server, release transport. */
+    abstract close(): this;
+}

package/lib/drivers/connection.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * connection.ts - base abstract class for sqlitecloud server connections
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLiteCloudConnection = void 0;
+const types_1 = require("./types");
+const utilities_1 = require("./utilities");
+const queue_1 = require("./queue");
+const utilities_2 = require("./utilities");
+/**
+ * Base class for SQLiteCloudConnection handles basics and defines methods.
+ * Actual connection management and communication with the server in concrete classes.
+ */
+class SQLiteCloudConnection {
+    /** 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 });
+        }
+        else {
+            this.config = (0, utilities_1.validateConfiguration)(config);
+        }
+        // connect transport layer to server
+        this.connect(callback);
+    }
+    //
+    // internal methods (some are implemented in concrete classes using different transport layers)
+    //
+    /** Connect will establish a tls or websocket transport to the server based on configuration and environment */
+    connect(callback) {
+        this.operations.enqueue(done => {
+            this.connectTransport(this.config, error => {
+                if (error) {
+                    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);
+                done(error);
+            });
+        });
+        return this;
+    }
+    /** Will log to console if verbose mode is enabled */
+    log(message, ...optionalParams) {
+        if (this.config.verbose) {
+            message = (0, utilities_2.anonimizeCommand)(message);
+            console.log(`${new Date().toISOString()} ${this.config.clientId}: ${message}`, ...optionalParams);
+        }
+    }
+    /** Enable verbose logging for debug purposes */
+    verbose() {
+        this.config.verbose = true;
+    }
+    /** Will enquee a command to be executed and callback with the resulting rowset/result/error */
+    sendCommands(commands, callback) {
+        this.operations.enqueue(done => {
+            if (!this.connected) {
+                const error = new types_1.SQLiteCloudError('Connection not established', { errorCode: 'ERR_CONNECTION_NOT_ESTABLISHED' });
+                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);
+            });
+        });
+        return this;
+    }
+}
+exports.SQLiteCloudConnection = SQLiteCloudConnection;

package/lib/{database.js → drivers/database.js}

@@ -2,6 +2,29 @@
 //
 // database.ts - database driver api, implements and extends sqlite3
 //
+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;
+};
 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) {
@@ -16,18 +39,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Database = void 0;
-// Trying as much as possible to be a drop-in replacement for SQLite3 API
-// https://github.com/TryGhost/node-sqlite3/wiki/API
-// https://github.com/TryGhost/node-sqlite3
-// https://github.com/TryGhost/node-sqlite3/blob/master/lib/sqlite3.d.ts
-/* eslint-disable @typescript-eslint/no-unused-vars */
-/* eslint-disable @typescript-eslint/explicit-module-boundary-types */
-const connection_1 = require("./connection");
 const rowset_1 = require("./rowset");
 const types_1 = require("./types");
 const utilities_1 = require("./utilities");
 const statement_1 = require("./statement");
 const eventemitter3_1 = __importDefault(require("eventemitter3"));
+const utilities_2 = require("./utilities");
 // Uses eventemitter3 instead of node events for browser compatibility
 // https://github.com/primus/eventemitter3
 /**
@@ -50,29 +67,61 @@ class Database extends eventemitter3_1.default {
         }
         // mode is ignored for now
         // opens first connection to the database automatically
-        this.getConnection(callback);
+        this.getConnection((error, _connection) => {
+            if (callback) {
+                callback.call(this, error);
+            }
+        });
     }
     //
     // private methods
     //
     /** Returns first available connection from connection pool */
     getConnection(callback) {
-        var _a;
+        var _a, _b, _c;
         // TODO sqlitecloud-js / implement database connection pool #10
         if (((_a = this.connections) === null || _a === void 0 ? void 0 : _a.length) > 0) {
             callback === null || callback === void 0 ? void 0 : callback.call(this, null, this.connections[0]);
         }
         else {
-            this.connections.push(new connection_1.SQLiteCloudConnection(this.config, error => {
-                if (error) {
-                    this.handleError(this.connections[0], error, callback);
-                }
-                else {
-                    console.assert;
-                    callback === null || callback === void 0 ? void 0 : callback.call(this, null, this.connections[0]);
-                    this.emitEvent('open');
-                }
-            }));
+            // connect using websocket if tls is not supported or if explicitly requested
+            const useWebsocket = utilities_2.isBrowser || ((_b = this.config) === null || _b === void 0 ? void 0 : _b.useWebsocket) || ((_c = this.config) === null || _c === void 0 ? void 0 : _c.gatewayUrl);
+            if (useWebsocket) {
+                // socket.io transport works in both node.js and browser environments and connects via SQLite Cloud Gateway
+                Promise.resolve().then(() => __importStar(require('./connection-ws'))).then(module => {
+                    this.connections.push(new module.default(this.config, error => {
+                        if (error) {
+                            this.handleError(this.connections[0], error, callback);
+                        }
+                        else {
+                            console.assert;
+                            callback === null || callback === void 0 ? void 0 : callback.call(this, null, this.connections[0]);
+                            this.emitEvent('open');
+                        }
+                    }));
+                })
+                    .catch(error => {
+                    this.handleError(null, error, callback);
+                });
+            }
+            else {
+                // tls sockets work only in node.js environments
+                Promise.resolve().then(() => __importStar(require('./connection-tls'))).then(module => {
+                    this.connections.push(new module.default(this.config, error => {
+                        if (error) {
+                            this.handleError(this.connections[0], error, callback);
+                        }
+                        else {
+                            console.assert;
+                            callback === null || callback === void 0 ? void 0 : callback.call(this, null, this.connections[0]);
+                            this.emitEvent('open');
+                        }
+                    }));
+                })
+                    .catch(error => {
+                    this.handleError(null, error, callback);
+                });
+            }
         }
     }
     /** Handles an error by closing the connection, calling the callback and/or emitting an error event */

package/lib/drivers/protocol.d.ts

@@ -0,0 +1,51 @@
+/// <reference types="node" />
+import { type SQLCloudRowsetMetadata, type SQLiteCloudDataTypes } from './types';
+import { SQLiteCloudRowset } from './rowset';
+export declare const CMD_STRING = "+";
+export declare const CMD_ZEROSTRING = "!";
+export declare const CMD_ERROR = "-";
+export declare const CMD_INT = ":";
+export declare const CMD_FLOAT = ",";
+export declare const CMD_ROWSET = "*";
+export declare const CMD_ROWSET_CHUNK = "/";
+export declare const CMD_JSON = "#";
+export declare const CMD_NULL = "_";
+export declare const CMD_BLOB = "$";
+export declare const CMD_COMPRESSED = "%";
+export declare const CMD_COMMAND = "^";
+export declare const CMD_ARRAY = "=";
+export declare const ROWSET_CHUNKS_END = "/6 0 0 0 ";
+/** Analyze first character to check if corresponding data type has LEN */
+export declare function hasCommandLength(firstCharacter: string): boolean;
+/** Analyze a command with explict LEN and extract it */
+export declare function parseCommandLength(data: Buffer): number;
+/** Receive a compressed buffer, decompress with lz4, return buffer and datatype */
+export declare function decompressBuffer(buffer: Buffer): {
+    buffer: Buffer;
+    dataType: string;
+};
+/** Parse error message or extended error message */
+export declare function parseError(buffer: Buffer, spaceIndex: number): never;
+/** Parse an array of items (each of which will be parsed by type separately) */
+export declare function parseArray(buffer: Buffer, spaceIndex: number): SQLiteCloudDataTypes[];
+/** Parse header in a rowset or chunk of a chunked rowset */
+export declare function parseRowsetHeader(buffer: Buffer): {
+    index: number;
+    metadata: SQLCloudRowsetMetadata;
+    fwdBuffer: Buffer;
+};
+export declare function bufferStartsWith(buffer: Buffer, prefix: string): boolean;
+export declare function bufferEndsWith(buffer: Buffer, suffix: string): boolean;
+/**
+ * Parse a chunk of a chunked rowset command, eg:
+ * *LEN 0:VERS NROWS NCOLS DATA
+ * @see https://github.com/sqlitecloud/sdk/blob/master/PROTOCOL.md#scsp-rowset-chunk
+ */
+export declare function parseRowsetChunks(buffers: Buffer[]): SQLiteCloudRowset;
+/** Parse command, extract its data, return the data and the buffer moved to the first byte after the command */
+export declare function popData(buffer: Buffer): {
+    data: SQLiteCloudDataTypes | SQLiteCloudRowset;
+    fwdBuffer: Buffer;
+};
+/** Format a command to be sent via SCSP protocol */
+export declare function formatCommand(command: string): string;