@sqlitecloud/drivers 1.0.122 → 1.0.193

package/README.md

@@ -18,6 +18,7 @@ npm install @sqlitecloud/drivers
 import { Database } from '@sqlitecloud/drivers'
 
 let database = new Database('sqlitecloud://user:password@xxx.sqlite.cloud:8860/chinook.sqlite')
+// or use sqlitecloud://xxx.sqlite.cloud:8860?apikey=xxxxxxx
 
 let name = 'Breaking The Rules'
 
@@ -31,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

@@ -4,7 +4,7 @@
 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
+ * Implementation of SQLiteCloudConnection that connects to the database using specific tls APIs
  * that connect to native sockets or tls sockets and communicates via raw, binary protocol.
  */
 export declare class SQLiteCloudTlsConnection extends SQLiteCloudConnection {

package/lib/drivers/connection-tls.js

@@ -33,7 +33,7 @@ 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
+ * Implementation of SQLiteCloudConnection that connects to the database using specific tls APIs
  * that connect to native sockets or tls sockets and communicates via raw, binary protocol.
  */
 class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
@@ -65,7 +65,7 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
         const connectionOptions = {
             host: config.host,
             port: config.port,
-            rejectUnauthorized: false,
+            rejectUnauthorized: config.host != 'localhost',
             // 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
@@ -202,8 +202,8 @@ class SQLiteCloudTlsConnection extends connection_1.SQLiteCloudConnection {
         }
         if (this.processCallback) {
             this.processCallback(error, result);
-            //      this.processCallback = undefined
         }
+        this.buffer = Buffer.alloc(0);
     }
     /** 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;

package/lib/drivers/protocol.js

@@ -3,7 +3,7 @@
 // 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");
 const lz4 = require('lz4js');
@@ -24,7 +24,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
@@ -268,6 +268,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:

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

@@ -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/utilities.js

@@ -34,19 +34,15 @@ function anonimizeError(error) {
 exports.anonimizeError = anonimizeError;
 /** Initialization commands sent to database when connection is established */
 function getInitializationCommands(config) {
+    // we check the credentials using non linearizable so we're quicker
+    // then we bring back linearizability unless specified otherwise
+    let commands = 'SET CLIENT KEY NONLINEARIZABLE TO 1; ';
     // first user authentication, then all other commands
-    let commands = '';
     if (config.apikey) {
-        commands = `AUTH APIKEY ${config.apikey}; `;
+        commands += `AUTH APIKEY ${config.apikey}; `;
     }
     else {
-        commands = `AUTH USER ${config.username || ''} ${config.password_hashed ? 'HASH' : 'PASSWORD'} ${config.password || ''}; `;
-    }
-    if (config.database) {
-        if (config.create && !config.memory) {
-            commands += `CREATE DATABASE ${config.database} IF NOT EXISTS; `;
-        }
-        commands += `USE DATABASE ${config.database}; `;
+        commands += `AUTH USER ${config.username || ''} ${config.password_hashed ? 'HASH' : 'PASSWORD'} ${config.password || ''}; `;
     }
     if (config.compression) {
         commands += 'SET CLIENT KEY COMPRESSION TO 1; ';
@@ -54,9 +50,6 @@ function getInitializationCommands(config) {
     if (config.zerotext) {
         commands += 'SET CLIENT KEY ZEROTEXT TO 1; ';
     }
-    if (config.non_linearizable) {
-        commands += 'SET CLIENT KEY NONLINEARIZABLE TO 1; ';
-    }
     if (config.noblob) {
         commands += 'SET CLIENT KEY NOBLOB TO 1; ';
     }
@@ -69,6 +62,17 @@ function getInitializationCommands(config) {
     if (config.maxrowset) {
         commands += `SET CLIENT KEY MAXROWSET TO ${config.maxrowset}; `;
     }
+    // we ALWAYS set non linearizable to 1 when we start so we can be quicker on login
+    // but then we need to put it back to its default value if "linearizable" unless set
+    if (!config.non_linearizable) {
+        commands += 'SET CLIENT KEY NONLINEARIZABLE TO 0; ';
+    }
+    if (config.database) {
+        if (config.create && !config.memory) {
+            commands += `CREATE DATABASE ${config.database} IF NOT EXISTS; `;
+        }
+        commands += `USE DATABASE ${config.database}; `;
+    }
     return commands;
 }
 exports.getInitializationCommands = getInitializationCommands;