@sqlitecloud/drivers 0.0.34

package/lib/transport-tls.js

@@ -0,0 +1,458 @@
+"use strict";
+/**
+ * transport-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.TlsSocketTransport = void 0;
+const types_1 = require("./types");
+const rowset_1 = require("./rowset");
+const connection_1 = require("./connection");
+const connection_2 = require("./connection");
+const tls_1 = __importDefault(require("tls"));
+const lz4 = require('lz4js');
+/**
+ * The server communicates with clients via commands defined
+ * in the SQLiteCloud Server Protocol (SCSP), see more at:
+ * https://github.com/sqlitecloud/sdk/blob/master/PROTOCOL.md
+ */
+const CMD_STRING = '+';
+const CMD_ZEROSTRING = '!';
+const CMD_ERROR = '-';
+const CMD_INT = ':';
+const CMD_FLOAT = ',';
+const CMD_ROWSET = '*';
+const CMD_ROWSET_CHUNK = '/';
+const CMD_JSON = '#';
+const CMD_NULL = '_';
+const CMD_BLOB = '$';
+const CMD_COMPRESSED = '%';
+const CMD_COMMAND = '^';
+const CMD_ARRAY = '=';
+// const CMD_RAWJSON = '{'
+// const CMD_PUBSUB = '|'
+// const CMD_RECONNECT = '@'
+/**
+ * Implementation of SQLiteCloudConnection that connects directly to the database via tls socket and raw, binary protocol.
+ * 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 TlsSocketTransport {
+    /** 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) {
+        // 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();
+                }
+            }
+        };
+        this.config = config;
+        // connect to tls socket, initialize connection, setup event handlers
+        this.socket = tls_1.default.connect(this.config.port, this.config.host, this.config.tlsOptions, () => {
+            var _a;
+            if (!((_a = this.socket) === null || _a === void 0 ? void 0 : _a.authorized)) {
+                const anonimizedError = (0, connection_2.anonimizeError)(this.socket.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');
+                const commands = (0, connection_1.getInitializationCommands)(config);
+                this.processCommands(commands, 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 */
+    processCommands(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 = 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, _c;
+            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 = hasCommandLength(dataType);
+                if (commandLength) {
+                    const commandLength = 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 === CMD_COMPRESSED) {
+                            ;
+                            ({ buffer, dataType } = decompressBuffer(buffer));
+                        }
+                        if (dataType !== CMD_ROWSET_CHUNK) {
+                            (_b = this.socket) === null || _b === void 0 ? void 0 : _b.off('data', readData);
+                            const { data } = popData(buffer);
+                            finish(null, data);
+                        }
+                        else {
+                            // @ts-expect-error
+                            // check if rowset received the ending chunk
+                            if (data.subarray(data.indexOf(' ') + 1, data.length).toString() === '0 0 0 ') {
+                                const parsedData = 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);
+                                const okCommand = formatCommand('OK');
+                                (_c = this.socket) === null || _c === void 0 ? void 0 : _c.write(okCommand);
+                            }
+                        }
+                    }
+                }
+                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 } = 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, connection_2.anonimizeCommand)(commands) }));
+        });
+        (_b = this.socket) === null || _b === void 0 ? void 0 : _b.write(commands, 'utf8', () => {
+            var _a, _b;
+            socketTimeout = setTimeout(() => {
+                const timeoutError = new types_1.SQLiteCloudError('Request timed out', { cause: (0, connection_2.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, connection_2.anonimizeError)(error) }));
+        });
+        return this;
+    }
+    /** Disconnect from server, release connection. */
+    close() {
+        console.assert(this.socket !== null, 'TlsSocketTransport.close - connection already closed');
+        if (this.socket) {
+            this.socket.destroy();
+            this.socket = null;
+        }
+        this.socket = undefined;
+        return this;
+    }
+}
+exports.TlsSocketTransport = TlsSocketTransport;
+//
+// utility functions
+//
+/** Analyze first character to check if corresponding data type has LEN */
+function hasCommandLength(firstCharacter) {
+    return firstCharacter == CMD_INT || firstCharacter == CMD_FLOAT || firstCharacter == CMD_NULL ? false : true;
+}
+/** Analyze a command with explict LEN and extract it */
+function parseCommandLength(data) {
+    return parseInt(data.subarray(1, data.indexOf(' ')).toString('utf8'));
+}
+/** Receive a compressed buffer, decompress with lz4, return buffer and datatype */
+function decompressBuffer(buffer) {
+    const spaceIndex = buffer.indexOf(' ');
+    buffer = buffer.subarray(spaceIndex + 1);
+    // extract compressed size
+    const compressedSize = parseInt(buffer.subarray(0, buffer.indexOf(' ') + 1).toString('utf8'));
+    buffer = buffer.subarray(buffer.indexOf(' ') + 1);
+    // extract decompressed size
+    const decompressedSize = parseInt(buffer.subarray(0, buffer.indexOf(' ') + 1).toString('utf8'));
+    buffer = buffer.subarray(buffer.indexOf(' ') + 1);
+    // extract compressed dataType
+    const dataType = buffer.subarray(0, 1).toString('utf8');
+    const decompressedBuffer = Buffer.alloc(decompressedSize);
+    const compressedBuffer = buffer.subarray(buffer.length - compressedSize);
+    // lz4js library is javascript and doesn't have types so we silence the type check
+    // eslint-disable-next-line
+    const decompressionResult = lz4.decompressBlock(compressedBuffer, decompressedBuffer, 0, compressedSize, 0);
+    buffer = Buffer.concat([buffer.subarray(0, buffer.length - compressedSize), decompressedBuffer]);
+    if (decompressionResult <= 0 || decompressionResult !== decompressedSize) {
+        throw new Error(`lz4 decompression error at offset ${decompressionResult}`);
+    }
+    return { buffer, dataType: dataType };
+}
+/** Parse error message or extended error message */
+function parseError(buffer, spaceIndex) {
+    const errorBuffer = buffer.subarray(spaceIndex + 1);
+    const errorString = errorBuffer.toString('utf8');
+    const parts = errorString.split(' ');
+    let errorCodeStr = parts.shift() || '0'; // Default errorCode is '0' if not present
+    let extErrCodeStr = '0'; // Default extended error code
+    let offsetCodeStr = '-1'; // Default offset code
+    // Split the errorCode by ':' to check for extended error codes
+    const errorCodeParts = errorCodeStr.split(':');
+    errorCodeStr = errorCodeParts[0];
+    if (errorCodeParts.length > 1) {
+        extErrCodeStr = errorCodeParts[1];
+        if (errorCodeParts.length > 2) {
+            offsetCodeStr = errorCodeParts[2];
+        }
+    }
+    // Rest of the error string is the error message
+    const errorMessage = parts.join(' ');
+    // Parse error codes to integers safely, defaulting to 0 if NaN
+    const errorCode = parseInt(errorCodeStr);
+    const extErrCode = parseInt(extErrCodeStr);
+    const offsetCode = parseInt(offsetCodeStr);
+    // create an Error object and add the custom properties
+    throw new types_1.SQLiteCloudError(errorMessage, {
+        errorCode: errorCode.toString(),
+        externalErrorCode: extErrCode.toString(),
+        offsetCode
+    });
+}
+/** Parse an array of items (each of which will be parsed by type separately) */
+function parseArray(buffer, spaceIndex) {
+    const parsedData = [];
+    const array = buffer.subarray(spaceIndex + 1, buffer.length);
+    const numberOfItems = parseInt(array.subarray(0, spaceIndex - 2).toString('utf8'));
+    let arrayItems = array.subarray(array.indexOf(' ') + 1, array.length);
+    for (let i = 0; i < numberOfItems; i++) {
+        const { data, fwdBuffer: buffer } = popData(arrayItems);
+        parsedData.push(data);
+        arrayItems = buffer;
+    }
+    return parsedData;
+}
+/** Parse header in a rowset or chunk of a chunked rowset */
+function parseRowsetHeader(buffer) {
+    const index = parseInt(buffer.subarray(0, buffer.indexOf(':') + 1).toString());
+    buffer = buffer.subarray(buffer.indexOf(':') + 1);
+    // extract rowset header
+    const { data, fwdBuffer } = popIntegers(buffer, 3);
+    return {
+        index,
+        metadata: {
+            version: data[0],
+            numberOfRows: data[1],
+            numberOfColumns: data[2],
+            columns: []
+        },
+        fwdBuffer
+    };
+}
+/** Extract column names and, optionally, more metadata out of a rowset's header */
+function parseRowsetColumnsMetadata(buffer, metadata) {
+    function popForward() {
+        const { data, fwdBuffer: fwdBuffer } = popData(buffer); // buffer in parent scope
+        buffer = fwdBuffer;
+        return data;
+    }
+    for (let i = 0; i < metadata.numberOfColumns; i++) {
+        metadata.columns.push({ name: popForward() });
+    }
+    // extract additional metadata if rowset has version 2
+    if (metadata.version == 2) {
+        for (let i = 0; i < metadata.numberOfColumns; i++)
+            metadata.columns[i].type = popForward();
+        for (let i = 0; i < metadata.numberOfColumns; i++)
+            metadata.columns[i].database = popForward();
+        for (let i = 0; i < metadata.numberOfColumns; i++)
+            metadata.columns[i].table = popForward();
+        for (let i = 0; i < metadata.numberOfColumns; i++)
+            metadata.columns[i].column = popForward(); // original column name
+    }
+    return buffer;
+}
+/** Parse a regular rowset (no chunks) */
+function parseRowset(buffer, spaceIndex) {
+    buffer = buffer.subarray(spaceIndex + 1, buffer.length);
+    const { metadata, fwdBuffer } = parseRowsetHeader(buffer);
+    buffer = parseRowsetColumnsMetadata(fwdBuffer, metadata);
+    // decode each rowset item
+    const data = [];
+    for (let j = 0; j < metadata.numberOfRows * metadata.numberOfColumns; j++) {
+        const { data: rowData, fwdBuffer } = popData(buffer);
+        data.push(rowData);
+        buffer = fwdBuffer;
+    }
+    console.assert(data && data.length === metadata.numberOfRows * metadata.numberOfColumns, 'SQLiteCloudConnection.parseRowset - invalid rowset data');
+    return new rowset_1.SQLiteCloudRowset(metadata, data);
+}
+/**
+ * Parse a chunk of a chunked rowset command, eg:
+ * *LEN 0:VERS NROWS NCOLS DATA
+ */
+function parseRowsetChunks(buffers) {
+    let metadata = { version: 1, numberOfColumns: 0, numberOfRows: 0, columns: [] };
+    const data = [];
+    for (let i = 0; i < buffers.length; i++) {
+        let buffer = buffers[i];
+        // validate and skip data type
+        const dataType = buffer.subarray(0, 1).toString();
+        console.assert(dataType === CMD_ROWSET_CHUNK);
+        buffer = buffer.subarray(buffer.indexOf(' ') + 1);
+        // chunk header, eg: 0:VERS NROWS NCOLS
+        const { index: chunkIndex, metadata: chunkMetadata, fwdBuffer } = parseRowsetHeader(buffer);
+        buffer = fwdBuffer;
+        // first chunk? extract columns metadata
+        if (chunkIndex === 1) {
+            metadata = chunkMetadata;
+            buffer = parseRowsetColumnsMetadata(buffer, metadata);
+        }
+        else {
+            metadata.numberOfRows += chunkMetadata.numberOfRows;
+        }
+        // extract single rowset row
+        for (let k = 0; k < chunkMetadata.numberOfRows * metadata.numberOfColumns; k++) {
+            const { data: itemData, fwdBuffer } = popData(buffer);
+            data.push(itemData);
+            buffer = fwdBuffer;
+        }
+    }
+    console.assert(data && data.length === metadata.numberOfRows * metadata.numberOfColumns, 'SQLiteCloudConnection.parseRowsetChunks - invalid rowset data');
+    return new rowset_1.SQLiteCloudRowset(metadata, data);
+}
+/** Pop one or more space separated integers from beginning of buffer, move buffer forward */
+function popIntegers(buffer, numberOfIntegers = 1) {
+    const data = [];
+    for (let i = 0; i < numberOfIntegers; i++) {
+        const spaceIndex = buffer.indexOf(' ');
+        data[i] = parseInt(buffer.subarray(0, spaceIndex).toString());
+        buffer = buffer.subarray(spaceIndex + 1);
+    }
+    return { data, fwdBuffer: buffer };
+}
+/** Parse command, extract its data, return the data and the buffer moved to the first byte after the command */
+function popData(buffer) {
+    function popResults(data) {
+        const fwdBuffer = buffer.subarray(commandEnd);
+        return { data, fwdBuffer };
+    }
+    // first character is the data type
+    console.assert(buffer && buffer instanceof Buffer);
+    const dataType = buffer.subarray(0, 1).toString('utf8');
+    console.assert(dataType !== CMD_COMPRESSED, "Compressed data shouldn't be decompressed before parsing");
+    console.assert(dataType !== CMD_ROWSET_CHUNK, 'Chunked data should be parsed by parseRowsetChunks');
+    let spaceIndex = buffer.indexOf(' ');
+    if (spaceIndex === -1) {
+        spaceIndex = buffer.length - 1;
+    }
+    let commandEnd = -1;
+    if (dataType === CMD_INT || dataType === CMD_FLOAT || dataType === CMD_NULL) {
+        commandEnd = spaceIndex + 1;
+    }
+    else {
+        const commandLength = parseInt(buffer.subarray(1, spaceIndex).toString());
+        commandEnd = spaceIndex + 1 + commandLength;
+    }
+    switch (dataType) {
+        case CMD_INT:
+            return popResults(parseInt(buffer.subarray(1, spaceIndex).toString()));
+        case CMD_FLOAT:
+            return popResults(parseFloat(buffer.subarray(1, spaceIndex).toString()));
+        case CMD_NULL:
+            return popResults(null);
+        case CMD_STRING:
+            return popResults(buffer.subarray(spaceIndex + 1, commandEnd).toString('utf8'));
+        case CMD_ZEROSTRING:
+            return popResults(buffer.subarray(spaceIndex + 1, commandEnd - 1).toString('utf8'));
+        case CMD_COMMAND:
+            return popResults(buffer.subarray(spaceIndex + 1, commandEnd).toString('utf8'));
+        case CMD_JSON:
+            return popResults(JSON.parse(buffer.subarray(spaceIndex + 1, commandEnd).toString('utf8')));
+        case CMD_BLOB:
+            return popResults(buffer.subarray(spaceIndex + 1, commandEnd));
+        case CMD_ARRAY:
+            return popResults(parseArray(buffer, spaceIndex));
+        case CMD_ROWSET:
+            return popResults(parseRowset(buffer, spaceIndex));
+        case CMD_ERROR:
+            parseError(buffer, spaceIndex); // throws custom error
+            break;
+    }
+    throw new TypeError(`Data type: ${dataType} is not defined in SCSP`);
+}
+/** Format a command to be sent via SCSP protocol */
+function formatCommand(command) {
+    const commandLength = Buffer.byteLength(command, 'utf-8');
+    return `+${commandLength} ${command}`;
+}

package/lib/transport-ws.d.ts

@@ -0,0 +1,24 @@
+/**
+ * transport-ws.ts - handles low level communication with sqlitecloud server via socket.io websocket
+ */
+import { SQLiteCloudConfig, ErrorCallback, ResultsCallback } from './types';
+import { ConnectionTransport } 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?;
+    /** Socket.io used to communicated with SQLiteCloud server */
+    private socket?;
+    /** True if connection is open */
+    get connected(): boolean;
+    connect(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;
+    /** Disconnect socket.io from server */
+    close(): this;
+}

package/lib/transport-ws.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * transport-ws.ts - handles low level communication with sqlitecloud server via socket.io websocket
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketTransport = void 0;
+const types_1 = require("./types");
+const rowset_1 = require("./rowset");
+const socket_io_client_1 = require("socket.io-client");
+/**
+ * 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.
+ */
+class WebSocketTransport {
+    /** 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) {
+        var _a;
+        try {
+            // connection established while we were waiting in line?
+            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 } });
+            }
+            callback === null || callback === void 0 ? void 0 : callback.call(this, null);
+        }
+        catch (error) {
+            callback === null || callback === void 0 ? void 0 : callback.call(this, error);
+        }
+        return this;
+    }
+    /** Will send a command immediately (no queueing), return the rowset/result or throw an error */
+    processCommands(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' }));
+            return this;
+        }
+        this.socket.emit('v1/sql', { sql: commands, row: 'array' }, (response) => {
+            if (response === null || response === void 0 ? void 0 : response.error) {
+                const error = new types_1.SQLiteCloudError(response.error.detail, Object.assign({}, response.error));
+                callback === null || callback === void 0 ? void 0 : callback.call(this, error);
+            }
+            else {
+                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');
+                        // 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());
+                        callback === null || callback === void 0 ? void 0 : callback.call(this, null, rowset);
+                        return;
+                    }
+                }
+                callback === null || callback === void 0 ? void 0 : callback.call(this, null, response === null || response === void 0 ? void 0 : response.data);
+            }
+        });
+        return this;
+    }
+    /** Disconnect socket.io from server */
+    close() {
+        var _a;
+        console.assert(this.socket !== null, 'WebsocketTransport.close - connection already closed');
+        if (this.socket) {
+            (_a = this.socket) === null || _a === void 0 ? void 0 : _a.close();
+            this.socket = undefined;
+        }
+        this.socket = undefined;
+        return this;
+    }
+}
+exports.WebSocketTransport = WebSocketTransport;

package/lib/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * types.ts - shared types and interfaces
+ */
+/// <reference types="node" />
+/// <reference types="node" />
+import tls from 'tls';
+/** Configuration for SQLite cloud connection */
+export interface SQLiteCloudConfig {
+    /** Connection string in the form of sqlitecloud://user:password@host:port/database?options */
+    connectionString?: string;
+    /** User name is required unless connectionString is provided */
+    username?: string;
+    /** Password is required unless connection string is provided */
+    password?: string;
+    /** True if password is hashed, default is false */
+    passwordHashed?: boolean;
+    /** Host name is required unless connectionString is provided */
+    host?: string;
+    /** Port number for tls socket */
+    port?: number;
+    /** Optional query timeout passed directly to TLS socket */
+    timeout?: number;
+    /** Name of database to open */
+    database?: string;
+    /** Create the database if it doesn't exist? */
+    createDatabase?: boolean;
+    /** Database will be created in memory */
+    dbMemory?: boolean;
+    /** Enable SQLite compatibility mode */
+    sqliteMode?: boolean;
+    compression?: boolean;
+    /** Request for immediate responses from the server node without waiting for linerizability guarantees */
+    nonlinearizable?: boolean;
+    /** Server should send BLOB columns */
+    noBlob?: boolean;
+    /** Do not send columns with more than max_data bytes */
+    maxData?: number;
+    /** Server should chunk responses with more than maxRows */
+    maxRows?: number;
+    /** Server should limit total number of rows in a set to maxRowset */
+    maxRowset?: number;
+    /** Custom options and configurations for tls socket, eg: additional certificates */
+    tlsOptions?: tls.ConnectionOptions;
+    /** True if we should force use of SQLite Cloud Gateway and websocket connections, default: true in browsers, false in node.js */
+    useWebsocket?: boolean;
+    /** Url where we can connect to a SQLite Cloud Gateway that has a socket.io deamon waiting to connect, eg. ws://host:4000 */
+    gatewayUrl?: string;
+    /** Optional identifier used for verbose logging */
+    clientId?: string;
+    /** True if connection should enable debug logs */
+    verbose?: boolean;
+}
+/** Metadata information for a set of rows resulting from a query */
+export interface SQLCloudRowsetMetadata {
+    /** Rowset version 1 has column's name, version 2 has extended metadata */
+    version: number;
+    /** Number of rows */
+    numberOfRows: number;
+    /** Number of columns */
+    numberOfColumns: number;
+    /** Columns' metadata */
+    columns: {
+        /** Column name in query (may be altered from original name) */
+        name: string;
+        /** Declare column type */
+        type?: string;
+        /** Database name */
+        database?: string;
+        /** Database table */
+        table?: string;
+        /** Original name of the column */
+        column?: string;
+    }[];
+}
+/** Basic types that can be returned by SQLiteCloud APIs */
+export type SQLiteCloudDataTypes = string | number | boolean | Record<string | number, unknown> | Buffer | null | undefined;
+/** Custom error reported by SQLiteCloud drivers */
+export declare class SQLiteCloudError extends Error {
+    constructor(message: string, args?: Partial<SQLiteCloudError>);
+    /** Upstream error that cause this error */
+    cause?: Error | string;
+    /** Error code returned by drivers or server */
+    errorCode?: string;
+    /** Additional error code */
+    externalErrorCode?: string;
+    /** Additional offset code in commands */
+    offsetCode?: number;
+}
+export type ErrorCallback = (error: Error | null) => void;
+export type ResultsCallback<T = any> = (error: Error | null, results?: T) => void;
+export type RowsCallback<T = Record<string, any>> = (error: Error | null, rows?: T[]) => void;
+export type RowCallback<T = Record<string, any>> = (error: Error | null, row?: T) => void;
+export type RowCountCallback = (error: Error | null, rowCount?: number) => void;
+/**
+ * Certain responses include arrays with various types of metadata.
+ * The first entry is always an array type from this list. This enum
+ * is called SQCLOUD_ARRAY_TYPE in the C API.
+ */
+export declare enum SQLiteCloudArrayType {
+    ARRAY_TYPE_SQLITE_EXEC = 10,
+    ARRAY_TYPE_DB_STATUS = 11,
+    ARRAY_TYPE_METADATA = 12,
+    ARRAY_TYPE_VM_STEP = 20,
+    ARRAY_TYPE_VM_COMPILE = 21,
+    ARRAY_TYPE_VM_STEP_ONE = 22,
+    ARRAY_TYPE_VM_SQL = 23,
+    ARRAY_TYPE_VM_STATUS = 24,
+    ARRAY_TYPE_VM_LIST = 25,
+    ARRAY_TYPE_BACKUP_INIT = 40,
+    ARRAY_TYPE_BACKUP_STEP = 41,
+    ARRAY_TYPE_BACKUP_END = 42,
+    ARRAY_TYPE_SQLITE_STATUS = 50
+}