@sqlitecloud/drivers 0.0.40 → 0.0.56

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

@@ -0,0 +1,29 @@
+/**
+ * connection-tls.ts - connection via tls socket and sqlitecloud protocol
+ */
+import { type SQLiteCloudConfig, type ErrorCallback, type ResultsCallback } from './types';
+import { SQLiteCloudConnection } from './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 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;
+    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

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * connection-tls.ts - connection via tls socket and sqlitecloud protocol
+ */
+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 utilities_1 = require("./utilities");
+const protocol_1 = require("./protocol");
+const tls = __importStar(require("tls"));
+/**
+ * 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) {
+        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);
+        // 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('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, _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
+        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]);
+            }
+            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)`);
+                    }
+                    // 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);
+                        }
+                    }
+                }
+            }
+            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);
+                }
+            }
+        }
+        catch (error) {
+            console.assert(error instanceof Error);
+            if (error instanceof Error) {
+                (_f = this.processCommandsFinish) === null || _f === void 0 ? void 0 : _f.call(this, error);
+            }
+        }
+    }
+    /** 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() {
+        if (this.socket) {
+            this.socket.removeAllListeners();
+            this.socket.destroy();
+            this.socket = undefined;
+        }
+        this.operations.clear();
+        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?
@@ -27,7 +28,7 @@ class WebSocketTransport {
             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`;
+                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);
@@ -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,34 @@
+/**
+ * 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;
+    /** 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 */
+    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,81 @@
+"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);
+    }
+    /** Returns the connection's configuration */
+    getConfig() {
+        return Object.assign({}, this.config);
+    }
+    //
+    // 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();
+                }
+                if (callback) {
+                    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);
+            }
+            else {
+                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;