@m2k-5f/pgtx 2.1.0 → 2.2.0

package/README.md

@@ -113,6 +113,36 @@ await pool.begin(async (tx) => {
 })
 ```
 
+
+### Async Notifications (LISTEN / NOTIFY)
+
+Pgtx natively handles PostgreSQL `LISTEN/NOTIFY` protocol messages asynchronously without interrupting multiplexed query pipeline.
+
+```typescript
+// 1. Sending a notification
+await pool.notify('user_events', JSON.stringify({ id: 42, action: 'signup' }))
+
+// 2. Receiving notifications (Requires a dedicated connection from the pool)
+const conn = await pool.acquire()
+
+const onEvent = (payload: string) => {
+  console.log(`Received payload: ${payload}`)
+}
+
+// Multiplexes multiple callbacks onto a single LISTEN command seamlessly
+await conn.listen('user_events', onEvent)
+await conn.listen('user_events', (data) => logToFile(data))
+
+// Clean up callbacks (Sends UNLISTEN only when the channel has zero callbacks left)
+await conn.unlisten('user_events', onEvent)
+
+// Keep the connection active as long as you need notifications!
+// Do NOT release it back to the pool prematurely.
+```
+
+> ⚠️ **Architecture Note:** While `notify` is atomic and can be triggered directly from the `Pool` on any random socket, `listen` and `unlisten` are stateful commands tied to a specific PostgreSQL backend process. Therefore, subscription methods are **strictly available only on explicit `Connection` instances** fetched via `pool.acquire()`.
+
+
 ### Bulk Inserts
 
 ```typescript
@@ -252,6 +282,9 @@ class Connection {
 
     query<T>(strings: TemplateStringsArray, ...values: any[]): Promise<T[]>
     begin<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>
+    notify(channelName: string, payload?: string): Promise<[]>
+    listen(channelName: string, callback: (payload: string) => void): Promise<[]>
+    unlisten(channelName: string, callback: (payload: string) => void): Promise<[]>
 
     get isAlive(): boolean
     close(): void
@@ -275,6 +308,7 @@ class Pool {
 
     query<T>(strings: TemplateStringsArray, ...values: any[]): Promise<T[]>
     begin<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>
+    notify(channelName: string, payload?: string): Promise<[]>
     acquire(): Promise<Connection>
     release(conn: Connection): void
     close(): Promise<void>

package/dist/connection.d.ts

@@ -26,8 +26,9 @@ export type DescribeQueueUnit = {
     reject: (error: Error) => void;
     statementName: StatementName;
 };
-export type StatementName = Branded<string, 'statementName'>;
-export type QueryText = Branded<string, 'queryText'>;
+export type StatementName = Branded<string, 'StatementName'>;
+export type QueryText = Branded<string, 'QueryText'>;
+export type ChannelName = Branded<string, "ChannelName">;
 /**
  * Represents a single dedicated connection to the PostgreSQL database.
  *
@@ -59,8 +60,10 @@ export type QueryText = Branded<string, 'queryText'>;
  * ```
  */
 export declare class Connection {
+    private readonly params;
     private _isFlushing;
-    private _isAlive;
+    private _isOpened;
+    private _isReconnecting;
     private _socket;
     private _writer;
     private _pipelinesQueue;
@@ -68,6 +71,7 @@ export declare class Connection {
     private _describingPending;
     private _parsed;
     private _parsingPending;
+    private _listeningCallbacks;
     private _stmtCounter;
     private _logLevel;
     private _nextStatement;
@@ -116,8 +120,6 @@ export declare class Connection {
      * ```
      */
     query<T extends Record<string, any>>(templates: TemplateStringsArray, ...params: any[]): Promise<T[]>;
-    private _createQuery;
-    private _writeQuery;
     /**
      * Starts a managed transaction on this connection.
      *
@@ -140,8 +142,48 @@ export declare class Connection {
      * ```
      */
     begin<T>(txCallback: (transaction: Transaction) => Promise<T>): Promise<T>;
+    /**
+     * Sends an asynchronous notification to a channel via `pg_notify`.
+     *
+     * @param channelName - The channel identifier
+     * @param payload - Optional string data (max 8000 bytes)
+     *
+     * @example
+     * ```ts
+     * await conn.notify('events', 'hello')
+     * ```
+     */
+    notify(channelName: string, payload?: string): Promise<[]>;
+    /**
+     * Subscribes a callback to a channel. Sends `LISTEN` on the first subscription.
+     *
+     * @param channelName - The channel identifier
+     * @param callback - Function invoked when a notification arrives
+     *
+     * @example
+     * ```ts
+     * await conn.listen('events', data => console.log(data))
+     * ```
+     */
+    listen(channelName: string, callback: (payload: string) => void): Promise<Record<string, any>[]>;
+    /**
+     * Unsubscribes a callback. Sends `UNLISTEN` if no callbacks remain for the channel.
+     *
+     * @param channelName - The channel identifier
+     * @param callback - The registered callback to remove
+     *
+     * @example
+     * ```ts
+     * await conn.unlisten('events', callback)
+     * ```
+     */
+    unlisten(channelName: string, callback: (payload: string) => void): Promise<void> | Promise<Record<string, any>[]>;
+    private _createQuery;
+    private _writeQuery;
     private _registerFlush;
     private _flush;
+    private _reconnect;
+    private _restoreSubscriptions;
     private _getCurrentQuery;
     private _rejectPipeline;
     private _handlePacket;
@@ -149,7 +191,7 @@ export declare class Connection {
      * Checks if the connection is still alive and usable.
      * Returns `false` if the socket is destroyed or connection is dead.
      */
-    get isAlive(): boolean;
+    get isOpened(): boolean;
     private _destroyConnection;
     /**
      * Closes the connection immediately.

package/dist/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}

package/dist/connection.js

@@ -11,6 +11,7 @@ const transaction_1 = require("./transaction");
 const socket_connector_1 = require("./protocol/socket-connector");
 const queue_1 = require("./queue");
 const query_1 = require("./query");
+const _1 = require(".");
 const ErrConnectionDead = new Error("Connection is Dead");
 /**
  * Represents a single dedicated connection to the PostgreSQL database.
@@ -46,18 +47,22 @@ class Connection {
     _nextStatement() {
         return `s-${this._stmtCounter++}`;
     }
-    constructor(socket, writer, logLevel) {
+    constructor(socket, writer, logLevel, params) {
         this._isFlushing = false;
-        this._isAlive = true;
+        this._isOpened = true;
+        this._isReconnecting = false;
         this._pipelinesQueue = new queue_1.Queue();
         this._described = new Map();
         this._describingPending = new Set();
         this._parsed = new Map();
         this._parsingPending = new Map();
+        this._listeningCallbacks = new Map();
         this._stmtCounter = 0;
+        this.params = params;
         this._logLevel = logLevel;
         this._socket = new socket_connector_1.SocketConnector(socket, (type, reader) => this._handlePacket(type, reader), (err) => {
-            this._destroyConnection();
+            this._isReconnecting = true;
+            this._rejectPipeline(ErrConnectionDead);
         });
         this._writer = writer;
     }
@@ -82,7 +87,7 @@ class Connection {
     static async new(params) {
         const writer = connection_request_writer_1.ConnectionRequestWriter.new();
         const socket = await (0, socket_authorization_1.createAuthorizedSocket)(writer, params);
-        return new Connection(socket, writer, params.logLevel || 'error');
+        return new Connection(socket, writer, params.logLevel || 'error', params);
     }
     /**
      * Executes a query using tagged template literals.
@@ -110,7 +115,7 @@ class Connection {
      */
     query(templates, ...params) {
         this._registerFlush();
-        if (!this._isAlive)
+        if (!this._isOpened)
             throw ErrConnectionDead;
         const { text, args } = (0, template_compiler_1.compileSqlTemplate)({ templates, args: params });
         if (this._logLevel === 'query') {
@@ -120,6 +125,100 @@ class Connection {
         this._writeQuery(query);
         return query.promise;
     }
+    /**
+     * Starts a managed transaction on this connection.
+     *
+     * Automatically handles:
+     * - `BEGIN` before the callback
+     * - `COMMIT` on successful completion
+     * - `ROLLBACK` if an error is thrown
+     *
+     * @param txCallback - Async function that receives a `Transaction` instance
+     * @returns The value returned from the callback
+     * @throws {Error} If connection is dead or transaction fails
+     *
+     * @example
+     * ```ts
+     * const result = await conn.begin(async tx => {
+     *   await tx.query`INSERT INTO accounts (id, balance) VALUES (1, 100)`
+     *   await tx.query`UPDATE accounts SET balance = balance - 10 WHERE id = 1`
+     *   return { success: true }
+     * })
+     * ```
+     */
+    async begin(txCallback) {
+        if (!this._isOpened)
+            throw ErrConnectionDead;
+        const tx = new transaction_1.Transaction(this);
+        try {
+            await tx.query `BEGIN`;
+            const result = await txCallback(tx);
+            if (tx.isActive)
+                await tx.commit();
+            return result;
+        }
+        catch (err) {
+            if (tx.isActive)
+                await tx.rollback();
+            throw err;
+        }
+    }
+    /**
+     * Sends an asynchronous notification to a channel via `pg_notify`.
+     *
+     * @param channelName - The channel identifier
+     * @param payload - Optional string data (max 8000 bytes)
+     *
+     * @example
+     * ```ts
+     * await conn.notify('events', 'hello')
+     * ```
+     */
+    notify(channelName, payload = "") {
+        return this.query `select pg_notify(${channelName}, ${payload})`;
+    }
+    /**
+     * Subscribes a callback to a channel. Sends `LISTEN` on the first subscription.
+     *
+     * @param channelName - The channel identifier
+     * @param callback - Function invoked when a notification arrives
+     *
+     * @example
+     * ```ts
+     * await conn.listen('events', data => console.log(data))
+     * ```
+     */
+    listen(channelName, callback) {
+        if (!this._listeningCallbacks.has(channelName)) {
+            this._listeningCallbacks.set(channelName, new Set());
+        }
+        const callbackSet = this._listeningCallbacks.get(channelName);
+        callbackSet.add(callback);
+        return this.query `listen ${_1.sql.ident(channelName)};`;
+    }
+    /**
+     * Unsubscribes a callback. Sends `UNLISTEN` if no callbacks remain for the channel.
+     *
+     * @param channelName - The channel identifier
+     * @param callback - The registered callback to remove
+     *
+     * @example
+     * ```ts
+     * await conn.unlisten('events', callback)
+     * ```
+     */
+    unlisten(channelName, callback) {
+        if (!this._listeningCallbacks.has(channelName)) {
+            return Promise.resolve();
+        }
+        const callbackSet = this._listeningCallbacks.get(channelName);
+        callbackSet.delete(callback);
+        if (callbackSet.size === 0) {
+            this._listeningCallbacks.delete(channelName);
+            return this.query `unlisten ${_1.sql.ident(channelName)};`;
+        }
+        return Promise.resolve();
+    }
     _createQuery(text, args) {
         if (this._parsed.has(text)) {
             const statementName = this._parsed.get(text);
@@ -170,44 +269,6 @@ class Connection {
         }
         this._pipelinesQueue.get().push(query);
     }
-    /**
-     * Starts a managed transaction on this connection.
-     *
-     * Automatically handles:
-     * - `BEGIN` before the callback
-     * - `COMMIT` on successful completion
-     * - `ROLLBACK` if an error is thrown
-     *
-     * @param txCallback - Async function that receives a `Transaction` instance
-     * @returns The value returned from the callback
-     * @throws {Error} If connection is dead or transaction fails
-     *
-     * @example
-     * ```ts
-     * const result = await conn.begin(async tx => {
-     *   await tx.query`INSERT INTO accounts (id, balance) VALUES (1, 100)`
-     *   await tx.query`UPDATE accounts SET balance = balance - 10 WHERE id = 1`
-     *   return { success: true }
-     * })
-     * ```
-     */
-    async begin(txCallback) {
-        if (!this._isAlive)
-            throw ErrConnectionDead;
-        const tx = new transaction_1.Transaction(this);
-        try {
-            await tx.query `BEGIN`;
-            const result = await txCallback(tx);
-            if (tx.isActive)
-                await tx.commit();
-            return result;
-        }
-        catch (err) {
-            if (tx.isActive)
-                await tx.rollback();
-            throw err;
-        }
-    }
     _registerFlush() {
         if (!this._isFlushing) {
             this._isFlushing = true;
@@ -218,18 +279,54 @@ class Connection {
         }
     }
     _flush() {
-        this._isFlushing = false;
-        if (!this._isAlive) {
+        if (!this._isOpened) {
             this._rejectPipeline(ErrConnectionDead);
             return;
         }
-        try {
+        if (this._isReconnecting) {
+            this._reconnect().then(socket => {
+                this._isFlushing = false;
+                socket.write(this._writer.writeSync());
+                this._writer.clear();
+            });
+        }
+        else {
+            this._isFlushing = false;
             this._socket.write(this._writer.writeSync());
             this._writer.clear();
         }
-        catch (err) {
-            this._destroyConnection();
+    }
+    _reconnect() {
+        this._parsed.clear();
+        this._described.clear();
+        this._describingPending.clear();
+        this._parsingPending.clear();
+        this._writer.clear();
+        while (this._pipelinesQueue.hasMore) {
+            this._rejectPipeline(ErrConnectionDead);
+            this._pipelinesQueue.next();
         }
+        this._pipelinesQueue = new queue_1.Queue();
+        this._pipelinesQueue.push(new queue_1.Queue());
+        return (0, socket_authorization_1.createAuthorizedSocket)(connection_request_writer_1.ConnectionRequestWriter.new(), this.params)
+            .then(socket => {
+            const connector = new socket_connector_1.SocketConnector(socket, (type, reader) => this._handlePacket(type, reader), (err) => {
+                this._isReconnecting = true;
+                this._rejectPipeline(ErrConnectionDead);
+            });
+            this._socket = connector;
+            this._restoreSubscriptions();
+            this._isReconnecting = false;
+            return connector;
+        });
+    }
+    _restoreSubscriptions() {
+        if (this._listeningCallbacks.size === 0)
+            return Promise.resolve();
+        const promises = Array.from(this._listeningCallbacks.keys()).map(channel => {
+            return this.query `LISTEN ${_1.sql.ident(channel)};`;
+        });
+        return Promise.all(promises);
     }
     _getCurrentQuery() {
         return this._pipelinesQueue.get().get();
@@ -350,6 +447,15 @@ class Connection {
                     }
                 }
                 break;
+            case constants_1.ResponseTypes.NotificationResponse:
+                {
+                    const { name, payload } = reader.readNotificationResponse();
+                    const callbackSet = this._listeningCallbacks.get(name);
+                    if (!callbackSet)
+                        break;
+                    callbackSet.forEach(cb => cb(payload));
+                }
+                break;
             default: console.warn('Undeclared response type: ', type);
         }
     }
@@ -357,11 +463,11 @@ class Connection {
      * Checks if the connection is still alive and usable.
      * Returns `false` if the socket is destroyed or connection is dead.
      */
-    get isAlive() {
-        return this._isAlive && !this._socket.isDestroyed;
+    get isOpened() {
+        return this._isOpened;
     }
     _destroyConnection() {
-        this._isAlive = false;
+        this._isOpened = false;
         this._socket.destroy();
         while (this._pipelinesQueue.hasMore) {
             this._rejectPipeline(ErrConnectionDead);

package/dist/pool.d.ts

@@ -128,6 +128,18 @@ export declare class Pool {
      * ```
      */
     query<T extends Record<string, any>>(templates: TemplateStringsArray, ...args: any[]): Promise<T[]>;
+    /**
+     * Sends an asynchronous notification to a channel via `pg_notify`.
+     *
+     * @param channelName - The channel identifier
+     * @param payload - Optional string data (max 8000 bytes)
+     *
+     * @example
+     * ```ts
+     * await pool.notify('events', 'hello')
+     * ```
+     */
+    notify(channelName: string, payload?: string): Promise<[]>;
     /**
      * Number of available (idle) connections in the pool.
      */

package/dist/pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAK3C,KAAK,UAAU,GAAG,gBAAgB,GAAG;IACjC,GAAG,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,IAAI;IACb,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,IAAI,CAAQ;IACpB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,SAAS,CAAQ;IAEzB,OAAO,CAAC,YAAY;gBAIR,MAAM,EAAE,UAAU;IAM9B;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IA6BpC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU;IAoBxB;;;;;;;;;;;;;;;;;OAiBG;IACG,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAYhF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAmCnG;;OAEG;IACH,IAAI,IAAI,WAEP;IAGD;;;OAGG;IACH,IAAI,KAAK,WAER;IAGD;;;;;;;;;;OAUG;IACG,KAAK;CAed"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAK3C,KAAK,UAAU,GAAG,gBAAgB,GAAG;IACjC,GAAG,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,IAAI;IACb,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,IAAI,CAAQ;IACpB,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,SAAS,CAAQ;IAEzB,OAAO,CAAC,YAAY;gBAIR,MAAM,EAAE,UAAU;IAM9B;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IA6BpC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU;IAoBxB;;;;;;;;;;;;;;;;;OAiBG;IACG,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAYhF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAmCnG;;;;;;;;;;OAUG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW,GACuB,OAAO,CAAC,EAAE,CAAC;IAIlF;;OAEG;IACH,IAAI,IAAI,WAEP;IAGD;;;OAGG;IACH,IAAI,KAAK,WAER;IAGD;;;;;;;;;;OAUG;IACG,KAAK;CAed"}

package/dist/pool.js

@@ -74,7 +74,7 @@ class Pool {
         while (this._available.hasMore) {
             const conn = this._available.get();
             this._available.next();
-            if (conn.isAlive) {
+            if (conn.isOpened) {
                 return conn;
             }
             this._total--;
@@ -113,7 +113,7 @@ class Pool {
      */
     release(conn) {
         this._checkClosed();
-        if (!conn.isAlive) {
+        if (!conn.isOpened) {
             this._total--;
             return;
         }
@@ -180,7 +180,7 @@ class Pool {
         this._checkClosed();
         while (this._available.hasMore) {
             const conn = this._available.get();
-            if (conn.isAlive) {
+            if (conn.isOpened) {
                 return conn.query(templates, ...args);
             }
             this._available.next();
@@ -204,6 +204,20 @@ class Pool {
             return conn.query(templates, ...args);
         });
     }
+    /**
+     * Sends an asynchronous notification to a channel via `pg_notify`.
+     *
+     * @param channelName - The channel identifier
+     * @param payload - Optional string data (max 8000 bytes)
+     *
+     * @example
+     * ```ts
+     * await pool.notify('events', 'hello')
+     * ```
+     */
+    notify(channelName, payload = "") {
+        return this.query `select pg_notify(${channelName}, ${payload})`;
+    }
     /**
      * Number of available (idle) connections in the pool.
      */

package/dist/protocol/connection-response-reader.d.ts

@@ -1,6 +1,7 @@
 import { AuthenticationCode, ResponseType, TransactionStatus } from "./constants";
 import { ColumnDescription } from "../types";
 import { PostgresError } from "../error";
+import { ChannelName } from "../connection";
 export declare class ConnectionResponseBuffer {
     private buffer;
     private caret;
@@ -38,6 +39,10 @@ export declare class ConnectionResponseReader {
     readSaslMessage(): string;
     readRowDescription(): ColumnDescription[];
     readDataRow(): (string | null)[];
+    readNotificationResponse(): {
+        name: ChannelName;
+        payload: string;
+    };
     readCommandComplete(): string;
     hasMore(): boolean;
     hasFullPacket(): boolean;

package/dist/protocol/connection-response-reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection-response-reader.d.ts","sourceRoot":"","sources":["../../src/protocol/connection-response-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAGxC,qBAAa,wBAAwB;IAI7B,OAAO,CAAC,MAAM;IAHlB,OAAO,CAAC,KAAK,CAAI;IAEjB,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM;IAK1B,QAAQ,IAAI,MAAM;IAOlB,SAAS,IAAI,MAAM;IAOnB,SAAS,IAAI,MAAM;IAOnB,WAAW,IAAI,MAAM;IAQrB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAOrC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAOjC,OAAO,IAAI,OAAO;IAKlB,aAAa,IAAI,OAAO;IAaxB,iBAAiB;CAGpB;AAGD,qBAAa,wBAAwB;IAI7B,OAAO,CAAC,MAAM;IAHlB,OAAO,CAAC,mBAAmB,CAAK;IAEhC,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM;IAK1B,QAAQ,IAC6B,YAAY;IAIjD,kBAAkB,IAGoB,kBAAkB;IAIxD,WAAW;IAKX,mBAAmB;;;;IAUnB,kBAAkB;;;;IAUlB,iBAAiB,IAAI,aAAa;IA8ClC,iBAAiB,IAEoB,iBAAiB;IAItD,kBAAkB,IAAI,MAAM,EAAE;IAa9B,eAAe,IAAI,MAAM;IAOzB,kBAAkB;IAuBlB,WAAW;IAmBX,mBAAmB,IAAI,MAAM;IAM7B,OAAO;IAKP,aAAa;IAKb,iBAAiB;IAKjB,iBAAiB;IAKjB,gBAAgB;IAKhB,wBAAwB;IAQxB,UAAU;CAGb"}
+{"version":3,"file":"connection-response-reader.d.ts","sourceRoot":"","sources":["../../src/protocol/connection-response-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAG3C,qBAAa,wBAAwB;IAI7B,OAAO,CAAC,MAAM;IAHlB,OAAO,CAAC,KAAK,CAAI;IAEjB,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM;IAK1B,QAAQ,IAAI,MAAM;IAOlB,SAAS,IAAI,MAAM;IAOnB,SAAS,IAAI,MAAM;IAOnB,WAAW,IAAI,MAAM;IAQrB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAOrC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAOjC,OAAO,IAAI,OAAO;IAKlB,aAAa,IAAI,OAAO;IAaxB,iBAAiB;CAGpB;AAGD,qBAAa,wBAAwB;IAI7B,OAAO,CAAC,MAAM;IAHlB,OAAO,CAAC,mBAAmB,CAAK;IAEhC,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM;IAK1B,QAAQ,IAC6B,YAAY;IAIjD,kBAAkB,IAGoB,kBAAkB;IAIxD,WAAW;IAKX,mBAAmB;;;;IAUnB,kBAAkB;;;;IAUlB,iBAAiB,IAAI,aAAa;IA8ClC,iBAAiB,IAEoB,iBAAiB;IAItD,kBAAkB,IAAI,MAAM,EAAE;IAa9B,eAAe,IAAI,MAAM;IAOzB,kBAAkB;IAuBlB,WAAW;IAmBX,wBAAwB;;;;IAUxB,mBAAmB,IAAI,MAAM;IAM7B,OAAO;IAKP,aAAa;IAKb,iBAAiB;IAKjB,iBAAiB;IAKjB,gBAAgB;IAKhB,wBAAwB;IAQxB,UAAU;CAGb"}

package/dist/protocol/connection-response-reader.js

@@ -188,6 +188,13 @@ class ConnectionResponseReader {
         }
         return rowValues;
     }
+    readNotificationResponse() {
+        this.buffer.readInt32();
+        this.buffer.readInt32();
+        const name = this.buffer.readCString();
+        const payload = this.buffer.readCString();
+        return { name, payload };
+    }
     readCommandComplete() {
         this.buffer.readInt32();
         return this.buffer.readCString();

package/dist/protocol/constants.d.ts

@@ -26,6 +26,7 @@ export declare const ResponseTypes: {
     readonly ParameterDescription: "t";
     readonly NoData: "n";
     readonly Notice: "N";
+    readonly NotificationResponse: "A";
 };
 export type ResponseType = ValueOF<typeof ResponseTypes>;
 export declare const AuthenticationCodes: {

package/dist/protocol/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/protocol/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAElC,eAAO,MAAM,YAAY;;;;;;;;;CASf,CAAA;AAEV,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,YAAY,CAAC,CAAA;AAGtD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;CAgBhB,CAAA;AAGV,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,aAAa,CAAC,CAAA;AAGxD,eAAO,MAAM,mBAAmB;;;;;;;CAOtB,CAAA;AAEV,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAGpE,eAAO,MAAM,mBAAmB;;;;CAItB,CAAA;AAEV,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,OAAO,mBAAmB,CAAC,CAAA"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/protocol/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAElC,eAAO,MAAM,YAAY;;;;;;;;;CASf,CAAA;AAEV,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,YAAY,CAAC,CAAA;AAGtD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;CAiBhB,CAAA;AAGV,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,aAAa,CAAC,CAAA;AAGxD,eAAO,MAAM,mBAAmB;;;;;;;CAOtB,CAAA;AAEV,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAGpE,eAAO,MAAM,mBAAmB;;;;CAItB,CAAA;AAEV,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/dist/protocol/constants.js

@@ -26,7 +26,8 @@ exports.ResponseTypes = {
     CloseComplete: "3",
     ParameterDescription: "t",
     NoData: "n",
-    Notice: "N"
+    Notice: "N",
+    NotificationResponse: "A"
 };
 exports.AuthenticationCodes = {
     Ok: 0,

package/dist/protocol/socket-connector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket-connector.d.ts","sourceRoot":"","sources":["../../src/protocol/socket-connector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAA;AACjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAA;AAE/E,qBAAa,eAAe;IAKpB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,QAAQ;IANpB,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,YAAY,CAAQ;gBAGhB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,wBAAwB,KAAK,IAAI,EACvE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;IA4B5C,KAAK,CAAC,MAAM,EAAE,uBAAuB;IAOrC,YAAY;IAQZ,OAAO;IAMP,IAAI,WAAW,YAA6B;CAC/C"}
+{"version":3,"file":"socket-connector.d.ts","sourceRoot":"","sources":["../../src/protocol/socket-connector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAA;AACjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAA;AAE/E,qBAAa,eAAe;IAKpB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,QAAQ;IANpB,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,YAAY,CAAQ;gBAGhB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,wBAAwB,KAAK,IAAI,EACvE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;IA6B5C,KAAK,CAAC,MAAM,EAAE,uBAAuB;IAOrC,YAAY;IAQZ,OAAO;IAMP,IAAI,WAAW,YAA6B;CAC/C"}

package/dist/protocol/socket-connector.js

@@ -9,6 +9,7 @@ class SocketConnector {
         this._onError = _onError;
         this.residualBuffer = null;
         this._isDestroyed = false;
+        _socket.setKeepAlive(true, 10000);
         _socket.on('data', buffer => {
             const currentBuffer = this.residualBuffer
                 ? Buffer.concat([this.residualBuffer, buffer])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2k-5f/pgtx",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Blazing-fast PostgreSQL driver with pipeline support.",
   "files": [
     "dist",