@sqlitecloud/drivers 1.0.178 → 1.0.245

package/README.md

@@ -32,6 +32,34 @@ We aim for full compatibility with the established [sqlite3 API](https://www.npm
 
 The package is developed entirely in TypeScript and is fully compatible with JavaScript. It doesn't require any native libraries. This makes it a straightforward and effective tool for managing cloud-based databases in a familiar SQLite environment.
 
+## Publish / Subscribe (Pub/Sub)
+
+```ts
+import { Database } from '@sqlitecloud/drivers'
+import { PubSub, PUBSUB_ENTITY_TYPE } from '@sqlitecloud/drivers/lib/drivers/pubsub'
+
+let database = new Database('sqlitecloud://user:password@xxx.sqlite.cloud:8860/chinook.sqlite')
+// or use sqlitecloud://xxx.sqlite.cloud:8860?apikey=xxxxxxx
+
+const pubSub: PubSub = await database.getPubSub()
+
+await pubSub.listen(PUBSUB_ENTITY_TYPE.TABLE, 'albums', (error, results, data) => {
+  if (results) {
+    // Changes on albums table will be received here as JSON object
+    console.log('Received message:', results)
+  }
+})
+
+await database.sql`INSERT INTO albums (Title, ArtistId) values ('Brand new song', 1)`
+
+// Stop listening changes on the table
+await pubSub.unlisten(PUBSUB_ENTITY_TYPE.TABLE, 'albums')
+```
+
+Pub/Sub is a messaging pattern that allows multiple applications to communicate with each other asynchronously. In the context of SQLiteCloud, Pub/Sub can be used to provide real-time updates and notifications to subscribed applications whenever data changes in the database or it can be used to send payloads (messages) to anyone subscribed to a channel.
+
+Pub/Sub Documentation: [https://docs.sqlitecloud.io/docs/pub-sub](https://docs.sqlitecloud.io/docs/pub-sub)
+
 ## More
 
 How do I deploy SQLite in the cloud?  

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

@@ -19,6 +19,7 @@ export declare class SQLiteCloudTlsConnection extends SQLiteCloudConnection {
     private startedOn;
     private executingCommands?;
     private processCallback?;
+    private pendingChunks;
     /** Handles data received in response to an outbound command sent by processCommands */
     private processCommandsData;
     /** Completes a transaction initiated by processCommands */

package/lib/drivers/connection-tls.js

@@ -45,6 +45,7 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
         // buffer to accumulate incoming data until an whole command is received and can be parsed
         this.buffer = Buffer.alloc(0);
         this.startedOn = new Date();
+        this.pendingChunks = [];
     }
     /** True if connection is open */
     get connected() {
@@ -137,10 +138,11 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
     }
     /** Handles data received in response to an outbound command sent by processCommands */
     processCommandsData(data) {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e, _f, _g;
         try {
             // append data to buffer as it arrives
             if (data.length && data.length > 0) {
+                // console.debug(`processCommandsData - received ${data.length} bytes`)
                 this.buffer = Buffer.concat([this.buffer, data]);
             }
             let dataType = (_a = this.buffer) === null || _a === void 0 ? void 0 : _a.subarray(0, 1).toString();
@@ -154,22 +156,33 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
                             bufferString = bufferString.substring(0, 100) + '...' + bufferString.substring(bufferString.length - 40);
                         }
                         const elapsedMs = new Date().getTime() - this.startedOn.getTime();
-                        console.debug(`<- ${bufferString} (${elapsedMs}ms)`);
+                        console.debug(`<- ${bufferString} (${bufferString.length} bytes, ${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);
+                        const decompressResults = (0, protocol_1.decompressBuffer)(this.buffer);
+                        if (decompressResults.dataType === protocol_1.CMD_ROWSET_CHUNK) {
+                            this.pendingChunks.push(decompressResults.buffer);
+                            this.buffer = decompressResults.remainingBuffer;
+                            this.processCommandsData(Buffer.alloc(0));
+                            return;
+                        }
+                        else {
+                            const { data } = (0, protocol_1.popData)(decompressResults.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);
+                        if (dataType !== protocol_1.CMD_ROWSET_CHUNK) {
+                            const { data } = (0, protocol_1.popData)(this.buffer);
+                            (_d = this.processCommandsFinish) === null || _d === void 0 ? void 0 : _d.call(this, null, data);
+                        }
+                        else {
+                            const completeChunk = (0, protocol_1.bufferEndsWith)(this.buffer, protocol_1.ROWSET_CHUNKS_END);
+                            if (completeChunk) {
+                                const parsedData = (0, protocol_1.parseRowsetChunks)([...this.pendingChunks, this.buffer]);
+                                (_e = this.processCommandsFinish) === null || _e === void 0 ? void 0 : _e.call(this, null, parsedData);
+                            }
                         }
                     }
                 }
@@ -179,14 +192,15 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
                 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);
+                    (_f = this.processCommandsFinish) === null || _f === void 0 ? void 0 : _f.call(this, null, data);
                 }
             }
         }
         catch (error) {
-            console.assert(error instanceof Error);
+            console.error(`processCommandsData - error: ${error}`);
+            console.assert(error instanceof Error, 'An error occoured while processing data');
             if (error instanceof Error) {
-                (_f = this.processCommandsFinish) === null || _f === void 0 ? void 0 : _f.call(this, error);
+                (_g = this.processCommandsFinish) === null || _g === void 0 ? void 0 : _g.call(this, error);
             }
         }
     }
@@ -202,8 +216,9 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
         }
         if (this.processCallback) {
             this.processCallback(error, result);
-            //      this.processCallback = undefined
         }
+        this.buffer = Buffer.alloc(0);
+        this.pendingChunks = [];
     }
     /** Disconnect immediately, release connection, no events. */
     close() {

package/lib/drivers/database.d.ts

@@ -2,6 +2,7 @@ import { SQLiteCloudConfig, RowCountCallback } from './types';
 import { Statement } from './statement';
 import { ErrorCallback, ResultsCallback, RowCallback, RowsCallback } from './types';
 import EventEmitter from 'eventemitter3';
+import { PubSub } from './pubsub';
 /**
  * Creating a Database object automatically opens a connection to the SQLite database.
  * When the connection is established the Database object emits an open event and calls
@@ -151,4 +152,13 @@ export declare class Database extends EventEmitter {
      * metadata in case of insert, update, delete.
      */
     sql(sql: TemplateStringsArray | string, ...values: any[]): Promise<any>;
+    /**
+     * PubSub class provides a Pub/Sub real-time updates and notifications system to
+     * allow multiple applications to communicate with each other asynchronously.
+     * It allows applications to subscribe to tables and receive notifications whenever
+     * data changes in the database table. It also enables sending messages to anyone
+     * subscribed to a specific channel.
+     * @returns {PubSub} A PubSub object
+     */
+    getPubSub(): Promise<PubSub>;
 }

package/lib/drivers/database.js

@@ -45,6 +45,7 @@ const utilities_1 = require("./utilities");
 const statement_1 = require("./statement");
 const eventemitter3_1 = __importDefault(require("eventemitter3"));
 const utilities_2 = require("./utilities");
+const pubsub_1 = require("./pubsub");
 // Uses eventemitter3 instead of node events for browser compatibility
 // https://github.com/primus/eventemitter3
 /**
@@ -443,5 +444,27 @@ class Database extends eventemitter3_1.default {
             });
         });
     }
+    /**
+     * PubSub class provides a Pub/Sub real-time updates and notifications system to
+     * allow multiple applications to communicate with each other asynchronously.
+     * It allows applications to subscribe to tables and receive notifications whenever
+     * data changes in the database table. It also enables sending messages to anyone
+     * subscribed to a specific channel.
+     * @returns {PubSub} A PubSub object
+     */
+    getPubSub() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => {
+                this.getConnection((error, connection) => {
+                    if (error || !connection) {
+                        reject(error);
+                    }
+                    else {
+                        resolve(new pubsub_1.PubSub(connection));
+                    }
+                });
+            });
+        });
+    }
 }
 exports.Database = Database;

package/lib/drivers/protocol.d.ts

@@ -14,6 +14,7 @@ export declare const CMD_BLOB = "$";
 export declare const CMD_COMPRESSED = "%";
 export declare const CMD_COMMAND = "^";
 export declare const CMD_ARRAY = "=";
+export declare const CMD_PUBSUB = "|";
 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;
@@ -23,6 +24,7 @@ export declare function parseCommandLength(data: Buffer): number;
 export declare function decompressBuffer(buffer: Buffer): {
     buffer: Buffer;
     dataType: string;
+    remainingBuffer: Buffer;
 };
 /** Parse error message or extended error message */
 export declare function parseError(buffer: Buffer, spaceIndex: number): never;

package/lib/drivers/protocol.js

@@ -3,9 +3,10 @@
 // protocol.ts - low level protocol handling for SQLiteCloud transport
 //
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatCommand = exports.popData = exports.parseRowsetChunks = exports.bufferEndsWith = exports.bufferStartsWith = exports.parseRowsetHeader = exports.parseArray = exports.parseError = exports.decompressBuffer = exports.parseCommandLength = exports.hasCommandLength = exports.ROWSET_CHUNKS_END = exports.CMD_ARRAY = exports.CMD_COMMAND = exports.CMD_COMPRESSED = exports.CMD_BLOB = exports.CMD_NULL = exports.CMD_JSON = exports.CMD_ROWSET_CHUNK = exports.CMD_ROWSET = exports.CMD_FLOAT = exports.CMD_INT = exports.CMD_ERROR = exports.CMD_ZEROSTRING = exports.CMD_STRING = void 0;
+exports.formatCommand = exports.popData = exports.parseRowsetChunks = exports.bufferEndsWith = exports.bufferStartsWith = exports.parseRowsetHeader = exports.parseArray = exports.parseError = exports.decompressBuffer = exports.parseCommandLength = exports.hasCommandLength = exports.ROWSET_CHUNKS_END = exports.CMD_PUBSUB = exports.CMD_ARRAY = exports.CMD_COMMAND = exports.CMD_COMPRESSED = exports.CMD_BLOB = exports.CMD_NULL = exports.CMD_JSON = exports.CMD_ROWSET_CHUNK = exports.CMD_ROWSET = exports.CMD_FLOAT = exports.CMD_INT = exports.CMD_ERROR = exports.CMD_ZEROSTRING = exports.CMD_STRING = void 0;
 const types_1 = require("./types");
 const rowset_1 = require("./rowset");
+// https://www.npmjs.com/package/lz4js
 const lz4 = require('lz4js');
 // The server communicates with clients via commands defined in
 // SQLiteCloud Server Protocol (SCSP), see more at:
@@ -24,7 +25,7 @@ exports.CMD_COMPRESSED = '%';
 exports.CMD_COMMAND = '^';
 exports.CMD_ARRAY = '=';
 // const CMD_RAWJSON = '{'
-// const CMD_PUBSUB = '|'
+exports.CMD_PUBSUB = '|';
 // const CMD_RECONNECT = '@'
 // To mark the end of the Rowset, the special string /LEN 0 0 0   is sent (LEN is always 6 in this case)
 // https://github.com/sqlitecloud/sdk/blob/master/PROTOCOL.md#scsp-rowset-chunk
@@ -44,26 +45,31 @@ function parseCommandLength(data) {
 exports.parseCommandLength = parseCommandLength;
 /** Receive a compressed buffer, decompress with lz4, return buffer and datatype */
 function decompressBuffer(buffer) {
+    // https://github.com/sqlitecloud/sdk/blob/master/PROTOCOL.md#scsp-compression
+    // jest test/database.test.ts -t "select large result set"
+    // starts with %<commandLength> <compressed> <uncompressed>
     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);
+    const commandLength = parseInt(buffer.subarray(1, spaceIndex).toString('utf8'));
+    let commandBuffer = buffer.subarray(spaceIndex + 1, spaceIndex + 1 + commandLength);
+    const remainingBuffer = buffer.subarray(spaceIndex + 1 + commandLength);
+    // extract compressed + decompressed  size
+    const compressedSize = parseInt(commandBuffer.subarray(0, commandBuffer.indexOf(' ') + 1).toString('utf8'));
+    commandBuffer = commandBuffer.subarray(commandBuffer.indexOf(' ') + 1);
+    const decompressedSize = parseInt(commandBuffer.subarray(0, commandBuffer.indexOf(' ') + 1).toString('utf8'));
+    commandBuffer = commandBuffer.subarray(commandBuffer.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);
+    const dataType = commandBuffer.subarray(0, 1).toString('utf8');
+    let decompressedBuffer = Buffer.alloc(decompressedSize);
+    const compressedBuffer = commandBuffer.subarray(commandBuffer.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]);
+    // the entire command is composed of the header (which is not compressed) + the decompressed block
+    decompressedBuffer = Buffer.concat([commandBuffer.subarray(0, commandBuffer.length - compressedSize), decompressedBuffer]);
     if (decompressionResult <= 0 || decompressionResult !== decompressedSize) {
         throw new Error(`lz4 decompression error at offset ${decompressionResult}`);
     }
-    return { buffer, dataType };
+    return { buffer: decompressedBuffer, dataType, remainingBuffer };
 }
 exports.decompressBuffer = decompressBuffer;
 /** Parse error message or extended error message */
@@ -117,7 +123,7 @@ function parseRowsetHeader(buffer) {
     buffer = buffer.subarray(buffer.indexOf(':') + 1);
     // extract rowset header
     const { data, fwdBuffer } = popIntegers(buffer, 3);
-    return {
+    const result = {
         index,
         metadata: {
             version: data[0],
@@ -127,6 +133,8 @@ function parseRowsetHeader(buffer) {
         },
         fwdBuffer
     };
+    // console.debug(`parseRowsetHeader`, result)
+    return result;
 }
 exports.parseRowsetHeader = parseRowsetHeader;
 /** Extract column names and, optionally, more metadata out of a rowset's header */
@@ -195,7 +203,8 @@ function parseRowsetChunks(buffers) {
     const data = [];
     // validate and skip data type
     const dataType = buffer.subarray(0, 1).toString();
-    console.assert(dataType === exports.CMD_ROWSET_CHUNK);
+    if (dataType !== exports.CMD_ROWSET_CHUNK)
+        throw new Error(`parseRowsetChunks - dataType: ${dataType} should be CMD_ROWSET_CHUNK`);
     buffer = buffer.subarray(buffer.indexOf(' ') + 1);
     while (buffer.length > 0 && !bufferStartsWith(buffer, exports.ROWSET_CHUNKS_END)) {
         // chunk header, eg: 0:VERS NROWS NCOLS
@@ -240,21 +249,24 @@ function popData(buffer) {
     }
     // first character is the data type
     console.assert(buffer && buffer instanceof Buffer);
-    const dataType = buffer.subarray(0, 1).toString('utf8');
-    console.assert(dataType !== exports.CMD_COMPRESSED, "Compressed data shouldn't be decompressed before parsing");
-    console.assert(dataType !== exports.CMD_ROWSET_CHUNK, 'Chunked data should be parsed by parseRowsetChunks');
+    let dataType = buffer.subarray(0, 1).toString('utf8');
+    if (dataType == exports.CMD_COMPRESSED)
+        throw new Error('Compressed data should be decompressed before parsing');
+    if (dataType == exports.CMD_ROWSET_CHUNK)
+        throw new Error('Chunked data should be parsed by parseRowsetChunks');
     let spaceIndex = buffer.indexOf(' ');
     if (spaceIndex === -1) {
         spaceIndex = buffer.length - 1;
     }
-    let commandEnd = -1;
+    let commandEnd = -1, commandLength = -1;
     if (dataType === exports.CMD_INT || dataType === exports.CMD_FLOAT || dataType === exports.CMD_NULL) {
         commandEnd = spaceIndex + 1;
     }
     else {
-        const commandLength = parseInt(buffer.subarray(1, spaceIndex).toString());
+        commandLength = parseInt(buffer.subarray(1, spaceIndex).toString());
         commandEnd = spaceIndex + 1 + commandLength;
     }
+    // console.debug(`popData - dataType: ${dataType}, spaceIndex: ${spaceIndex}, commandLength: ${commandLength}, commandEnd: ${commandEnd}`)
     switch (dataType) {
         case exports.CMD_INT:
             return popResults(parseInt(buffer.subarray(1, spaceIndex).toString()));
@@ -268,6 +280,8 @@ function popData(buffer) {
             return popResults(buffer.subarray(spaceIndex + 1, commandEnd - 1).toString('utf8'));
         case exports.CMD_COMMAND:
             return popResults(buffer.subarray(spaceIndex + 1, commandEnd).toString('utf8'));
+        case exports.CMD_PUBSUB:
+            return popResults(buffer.subarray(spaceIndex + 1, commandEnd).toString('utf8'));
         case exports.CMD_JSON:
             return popResults(JSON.parse(buffer.subarray(spaceIndex + 1, commandEnd).toString('utf8')));
         case exports.CMD_BLOB:
@@ -280,7 +294,9 @@ function popData(buffer) {
             parseError(buffer, spaceIndex); // throws custom error
             break;
     }
-    throw new TypeError(`Data type: ${dataType} is not defined in SCSP`);
+    const msg = `popData - Data type: ${Number(dataType)} '${dataType}'  is not defined in SCSP, spaceIndex: ${spaceIndex}, commandLength: ${commandLength}, commandEnd: ${commandEnd}`;
+    console.error(msg);
+    throw new TypeError(msg);
 }
 exports.popData = popData;
 /** Format a command to be sent via SCSP protocol */

package/lib/drivers/pubsub.d.ts

@@ -0,0 +1,48 @@
+import { SQLiteCloudConnection } from './connection';
+import { PubSubCallback } from './types';
+export declare enum PUBSUB_ENTITY_TYPE {
+    TABLE = "TABLE",
+    CHANNEL = "CHANNEL"
+}
+/**
+ * Pub/Sub class to receive changes on database tables or to send messages to channels.
+ */
+export declare class PubSub {
+    constructor(connection: SQLiteCloudConnection);
+    private connection;
+    private connectionPubSub;
+    /**
+     * Listen for a table or channel and start to receive messages to the provided callback.
+     * @param entityType One of TABLE or CHANNEL'
+     * @param entityName Name of the table or the channel
+     * @param callback Callback to be called when a message is received
+     * @param data Extra data to be passed to the callback
+     */
+    listen(entityType: PUBSUB_ENTITY_TYPE, entityName: string, callback: PubSubCallback, data?: any): Promise<any>;
+    /**
+     * Stop receive messages from a table or channel.
+     * @param entityType One of TABLE or CHANNEL
+     * @param entityName Name of the table or the channel
+     */
+    unlisten(entityType: string, entityName: string): Promise<any>;
+    /**
+     * Create a channel to send messages to.
+     * @param name Channel name
+     * @param failIfExists Raise an error if the channel already exists
+     */
+    createChannel(name: string, failIfExists?: boolean): Promise<any>;
+    /**
+     * Send a message to the channel.
+     */
+    notifyChannel(channelName: string, message: string): Promise<any>;
+    /**
+     * Ask the server to close the connection to the database and
+     * to keep only open the Pub/Sub connection.
+     * Only interaction with Pub/Sub commands will be allowed.
+     */
+    setPubSubOnly(): Promise<any>;
+    /** True if Pub/Sub connection is open. */
+    connected(): boolean;
+    /** Close Pub/Sub connection. */
+    close(): void;
+}

package/lib/drivers/pubsub.js

@@ -0,0 +1,116 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PubSub = exports.PUBSUB_ENTITY_TYPE = void 0;
+const connection_tls_1 = __importDefault(require("./connection-tls"));
+var PUBSUB_ENTITY_TYPE;
+(function (PUBSUB_ENTITY_TYPE) {
+    PUBSUB_ENTITY_TYPE["TABLE"] = "TABLE";
+    PUBSUB_ENTITY_TYPE["CHANNEL"] = "CHANNEL";
+})(PUBSUB_ENTITY_TYPE = exports.PUBSUB_ENTITY_TYPE || (exports.PUBSUB_ENTITY_TYPE = {}));
+/**
+ * Pub/Sub class to receive changes on database tables or to send messages to channels.
+ */
+class PubSub {
+    constructor(connection) {
+        this.connection = connection;
+        this.connectionPubSub = new connection_tls_1.default(connection.getConfig());
+    }
+    /**
+     * Listen for a table or channel and start to receive messages to the provided callback.
+     * @param entityType One of TABLE or CHANNEL'
+     * @param entityName Name of the table or the channel
+     * @param callback Callback to be called when a message is received
+     * @param data Extra data to be passed to the callback
+     */
+    listen(entityType, entityName, callback, data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const entity = entityType === 'TABLE' ? 'TABLE ' : '';
+            const authCommand = yield this.connection.sql(`LISTEN ${entity}${entityName};`);
+            return new Promise((resolve, reject) => {
+                this.connectionPubSub.sendCommands(authCommand, (error, results) => {
+                    if (error) {
+                        callback.call(this, error, null, data);
+                        reject(error);
+                    }
+                    else {
+                        // skip results from pubSub auth command
+                        if (results !== 'OK') {
+                            callback.call(this, null, results, data);
+                        }
+                        resolve(results);
+                    }
+                });
+            });
+        });
+    }
+    /**
+     * Stop receive messages from a table or channel.
+     * @param entityType One of TABLE or CHANNEL
+     * @param entityName Name of the table or the channel
+     */
+    unlisten(entityType, entityName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const subject = entityType === 'TABLE' ? 'TABLE ' : '';
+            return this.connection.sql(`UNLISTEN ${subject}?;`, entityName);
+        });
+    }
+    /**
+     * Create a channel to send messages to.
+     * @param name Channel name
+     * @param failIfExists Raise an error if the channel already exists
+     */
+    createChannel(name, failIfExists = true) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let notExistsCommand = '';
+            if (!failIfExists) {
+                notExistsCommand = 'IF NOT EXISTS;';
+            }
+            return this.connection.sql(`CREATE CHANNEL ? ${notExistsCommand}`, name);
+        });
+    }
+    /**
+     * Send a message to the channel.
+     */
+    notifyChannel(channelName, message) {
+        return this.connection.sql `NOTIFY ${channelName} ${message};`;
+    }
+    /**
+     * Ask the server to close the connection to the database and
+     * to keep only open the Pub/Sub connection.
+     * Only interaction with Pub/Sub commands will be allowed.
+     */
+    setPubSubOnly() {
+        return new Promise((resolve, reject) => {
+            this.connection.sendCommands('PUBSUB ONLY;', (error, results) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    this.connection.close();
+                    resolve(results);
+                }
+            });
+        });
+    }
+    /** True if Pub/Sub connection is open. */
+    connected() {
+        return this.connectionPubSub.connected;
+    }
+    /** Close Pub/Sub connection. */
+    close() {
+        this.connectionPubSub.close();
+    }
+}
+exports.PubSub = PubSub;

package/lib/drivers/types.d.ts

@@ -7,7 +7,7 @@ import tls from 'tls';
 /** Default timeout value for queries */
 export declare const DEFAULT_TIMEOUT: number;
 /** Default tls connection port */
-export declare const DEFAULT_PORT = 9960;
+export declare const DEFAULT_PORT = 8860;
 /**
  * Configuration for SQLite cloud connection
  * @note Options are all lowecase so they 1:1 compatible with C SDK
@@ -108,6 +108,7 @@ export type ResultsCallback<T = any> = (error: Error | null, results?: T) => voi
 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;
+export type PubSubCallback<T = any> = (error: Error | null, results?: T, extraData?: T) => void;
 /**
  * Certain responses include arrays with various types of metadata.
  * The first entry is always an array type from this list. This enum

package/lib/drivers/types.js

@@ -7,7 +7,7 @@ exports.SQLiteCloudArrayType = exports.SQLiteCloudError = exports.DEFAULT_PORT =
 /** Default timeout value for queries */
 exports.DEFAULT_TIMEOUT = 300 * 1000;
 /** Default tls connection port */
-exports.DEFAULT_PORT = 9960;
+exports.DEFAULT_PORT = 8860;
 /** Custom error reported by SQLiteCloud drivers */
 class SQLiteCloudError extends Error {
     constructor(message, args) {

package/lib/drivers/utilities.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseBooleanToZeroOne = exports.parseBoolean = exports.parseconnectionstring = exports.validateConfiguration = exports.popCallback = exports.getUpdateResults = exports.prepareSql = exports.escapeSqlParameter = exports.getInitializationCommands = exports.anonimizeError = exports.anonimizeCommand = exports.isNode = exports.isBrowser = void 0;
 const types_1 = require("./types");
 const types_2 = require("./types");
+const whatwg_url_1 = require("whatwg-url");
 //
 // determining running environment, thanks to browser-or-node
 // https://www.npmjs.com/package/browser-or-node
@@ -200,7 +201,7 @@ function validateConfiguration(config) {
     config.clientid || (config.clientid = 'SQLiteCloud');
     config.verbose = parseBoolean(config.verbose);
     config.noblob = parseBoolean(config.noblob);
-    config.compression = parseBoolean(config.compression);
+    config.compression = config.compression != undefined && config.compression != null ? parseBoolean(config.compression) : true; // default: true
     config.create = parseBoolean(config.create);
     config.non_linearizable = parseBoolean(config.non_linearizable);
     config.insecure = parseBoolean(config.insecure);
@@ -235,7 +236,7 @@ function parseconnectionstring(connectionstring) {
         // the sqlitecloud: protocol is not recognized by the URL constructor in browsers
         // so we need to replace it with https: to make it work
         const knownProtocolUrl = connectionstring.replace('sqlitecloud:', 'https:');
-        const url = new URL(knownProtocolUrl);
+        const url = new whatwg_url_1.URL(knownProtocolUrl);
         // all lowecase options
         const options = {};
         url.searchParams.forEach((value, key) => {