@m2k-5f/pgtx 2.1.0 → 2.3.0

package/dist/connection.js

@@ -1,17 +1,18 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Connection = void 0;
-const process_1 = require("process");
-const connection_request_writer_1 = require("./protocol/connection-request-writer");
-const socket_authorization_1 = require("./protocol/socket-authorization");
-const constants_1 = require("./protocol/constants");
-const value_parser_1 = require("./utils/value-parser");
-const template_compiler_1 = require("./utils/template-compiler");
-const transaction_1 = require("./transaction");
-const socket_connector_1 = require("./protocol/socket-connector");
-const queue_1 = require("./queue");
-const query_1 = require("./query");
-const ErrConnectionDead = new Error("Connection is Dead");
+import { nextTick } from "process";
+import { ConnectionRequestWriter } from "./protocol/connection-request-writer";
+import { createAuthorizedSocket } from "./protocol/socket-authorization";
+import { ResponseTypes } from "./protocol/constants";
+import { parseRowValues } from "./utils/value-parser";
+import { compileSqlTemplate } from "./utils/template-compiler";
+import { Transaction } from "./transaction";
+import { SocketConnector } from "./protocol/socket-connector";
+import { Queue } from "./queue";
+import { Query, QueryState } from "./query";
+import { sql } from ".";
+import { Begin, Future, Resolve } from 'fluent-future';
+import { PostgresError } from "./error";
+const ErrConnectionClosed = new PostgresError("Connection is closed", 'connection_closed', "", "ERROR");
+const ErrConnectionReconnecring = new PostgresError("Connection are reconnecting", "connection_reconnecting", "", "ERROR");
 /**
  * Represents a single dedicated connection to the PostgreSQL database.
  *
@@ -42,23 +43,28 @@ const ErrConnectionDead = new Error("Connection is Dead");
  * conn.close()
  * ```
  */
-class Connection {
+export class Connection {
     _nextStatement() {
         return `s-${this._stmtCounter++}`;
     }
-    constructor(socket, writer, logLevel) {
+    _checkOpened() {
+        if (!this.isOpened)
+            throw ErrConnectionClosed;
+    }
+    constructor(socket, writer, logLevel, params) {
         this._isFlushing = false;
-        this._isAlive = true;
-        this._pipelinesQueue = new queue_1.Queue();
+        this._isOpened = true;
+        this._isReconnecting = false;
+        this._pipelinesQueue = new 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._socket = new SocketConnector(socket, (type, reader) => this._handlePacket(type, reader), (err) => this._registerReconnect());
         this._writer = writer;
     }
     /**
@@ -79,10 +85,10 @@ 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');
+    static new(params) {
+        const writer = ConnectionRequestWriter.new();
+        return createAuthorizedSocket(writer, params)
+            .andThen(socket => Resolve(new Connection(socket, writer, params.logLevel || 'error', params)));
     }
     /**
      * Executes a query using tagged template literals.
@@ -109,127 +115,219 @@ class Connection {
      * ```
      */
     query(templates, ...params) {
+        this._checkOpened();
         this._registerFlush();
-        if (!this._isAlive)
-            throw ErrConnectionDead;
-        const { text, args } = (0, template_compiler_1.compileSqlTemplate)({ templates, args: params });
+        const { text, args } = compileSqlTemplate({ templates, args: params });
         if (this._logLevel === 'query') {
             console.log(`\nQUERY:     ${text}\n${args.length !== 0 ? `ARGUMENTS: [${args}]\n` : ""}`);
         }
         const query = this._createQuery(text, args);
         this._writeQuery(query);
-        return query.promise;
+        return Future.of(query.promise, error => {
+            if (error instanceof PostgresError)
+                return error;
+            return new PostgresError(error.message);
+        });
+    }
+    /**
+     * 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 }
+     * })
+     * ```
+     */
+    begin(txCallback) {
+        this._checkOpened();
+        const tx = new Transaction(this);
+        return Begin()
+            .andThen(() => tx.query `BEGIN`)
+            .andThen(() => Future.of(txCallback(tx))
+            .tap(() => {
+            if (tx.isActive)
+                return tx.commit();
+        })
+            .tapErr(() => {
+            if (tx.isActive)
+                return tx.rollback();
+        }));
+    }
+    /**
+     * 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 = "") {
+        this._checkOpened();
+        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) {
+        this._checkOpened();
+        if (!this._listeningCallbacks.has(channelName)) {
+            this._listeningCallbacks.set(channelName, new Set());
+        }
+        const callbackSet = this._listeningCallbacks.get(channelName);
+        callbackSet.add(callback);
+        return this.query `listen ${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) {
+        this._checkOpened();
+        if (!this._listeningCallbacks.has(channelName)) {
+            return Resolve([]);
+        }
+        const callbackSet = this._listeningCallbacks.get(channelName);
+        callbackSet.delete(callback);
+        if (callbackSet.size === 0) {
+            this._listeningCallbacks.delete(channelName);
+            return this.query `unlisten ${sql.ident(channelName)};`;
+        }
+        return Resolve([]);
     }
     _createQuery(text, args) {
         if (this._parsed.has(text)) {
             const statementName = this._parsed.get(text);
             if (this._described.has(statementName)) {
                 const columns = this._described.get(statementName);
-                return new query_1.Query(text, args, query_1.QueryState.Executing, statementName, columns);
+                return new Query(text, args, QueryState.Executing, statementName, columns);
             }
             else {
                 if (this._describingPending.has(statementName)) {
-                    return new query_1.Query(text, args, query_1.QueryState.Executing, statementName);
+                    return new Query(text, args, QueryState.Executing, statementName);
                 }
                 else {
                     this._describingPending.add(statementName);
-                    return new query_1.Query(text, args, query_1.QueryState.Describing, statementName);
+                    return new Query(text, args, QueryState.Describing, statementName);
                 }
             }
         }
         else {
             if (this._parsingPending.has(text)) {
                 const statementName = this._parsingPending.get(text);
-                return new query_1.Query(text, args, query_1.QueryState.Describing, statementName);
+                return new Query(text, args, QueryState.Describing, statementName);
             }
             else {
                 const statementName = this._nextStatement();
                 this._parsingPending.set(text, statementName);
-                return new query_1.Query(text, args, query_1.QueryState.Parsing, statementName);
+                return new Query(text, args, QueryState.Parsing, statementName);
             }
         }
     }
     _writeQuery(query) {
-        if (query.state === query_1.QueryState.Parsing) {
+        if (query.state === QueryState.Parsing) {
             this._writer
                 .writeParse(query.statementName, query.text)
                 .writeDescribe(query.statementName)
                 .writeBind("", query.statementName, query.args)
                 .writeExecute("");
         }
-        if (query.state === query_1.QueryState.Describing) {
+        if (query.state === QueryState.Describing) {
             this._writer
                 .writeDescribe(query.statementName)
                 .writeBind("", query.statementName, query.args)
                 .writeExecute("");
         }
-        if (query.state === query_1.QueryState.Executing) {
+        if (query.state === QueryState.Executing) {
             this._writer
                 .writeBind("", query.statementName, query.args)
                 .writeExecute("");
         }
         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;
-            this._pipelinesQueue.push(new queue_1.Queue());
-            (0, process_1.nextTick)(() => {
+            this._pipelinesQueue.push(new Queue());
+            nextTick(() => {
                 this._flush();
             });
         }
     }
     _flush() {
-        this._isFlushing = false;
-        if (!this._isAlive) {
-            this._rejectPipeline(ErrConnectionDead);
+        if (!this._isOpened) {
+            this._rejectPipeline(ErrConnectionClosed);
             return;
         }
-        try {
+        if (this._isReconnecting) {
+            this._reconnect().then(() => {
+                this._isFlushing = false;
+                this._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();
-        }
+    }
+    _registerReconnect() {
+        this._isReconnecting = true;
+        this._rejectPipeline(ErrConnectionReconnecring);
+    }
+    _resetConnectionState(cause) {
+        this._parsed.clear();
+        this._described.clear();
+        this._describingPending.clear();
+        this._parsingPending.clear();
+        this._writer.clear();
+        this._rejectPipeline(cause);
+    }
+    async _reconnect() {
+        this._resetConnectionState(ErrConnectionReconnecring);
+        const socket = await createAuthorizedSocket(ConnectionRequestWriter.new(), this.params);
+        const connector = new SocketConnector(socket, (type, reader) => this._handlePacket(type, reader), (err) => this._registerReconnect());
+        this._socket = connector;
+        void this._restoreSubscriptions();
+        this._isReconnecting = false;
+    }
+    _restoreSubscriptions() {
+        if (this._listeningCallbacks.size === 0)
+            return Promise.resolve();
+        const promises = Array.from(this._listeningCallbacks.keys()).map(channel => {
+            return this.query `LISTEN ${sql.ident(channel)};`;
+        });
+        return Promise.all(promises);
     }
     _getCurrentQuery() {
         return this._pipelinesQueue.get().get();
@@ -245,76 +343,76 @@ class Connection {
     }
     _handlePacket(type, reader) {
         switch (type) {
-            case constants_1.ResponseTypes.ParseComplete:
+            case ResponseTypes.ParseComplete:
                 {
                     reader.readParseComplete();
                     const query = this._getCurrentQuery();
                     this._parsingPending.delete(query.text);
                     this._parsed.set(query.text, query.statementName);
-                    query.state = query_1.QueryState.Describing;
+                    query.state = QueryState.Describing;
                 }
                 break;
-            case constants_1.ResponseTypes.BindComplete:
+            case ResponseTypes.BindComplete:
                 {
                     reader.readBindComplete();
                 }
                 break;
-            case constants_1.ResponseTypes.CloseComplete:
+            case ResponseTypes.CloseComplete:
                 {
                     reader.readBindComplete();
                 }
                 break;
-            case constants_1.ResponseTypes.ParameterDescription:
+            case ResponseTypes.ParameterDescription:
                 {
                     reader.readParameterDescription();
                 }
                 break;
-            case constants_1.ResponseTypes.NoData:
+            case ResponseTypes.NoData:
                 {
                     reader.readNoData();
                     const query = this._getCurrentQuery();
                     this._describingPending.delete(query.statementName);
                     this._described.set(query.statementName, []);
-                    query.state = query_1.QueryState.Executing;
+                    query.state = QueryState.Executing;
                 }
                 break;
-            case constants_1.ResponseTypes.RowDescription:
+            case ResponseTypes.RowDescription:
                 {
                     const columns = reader.readRowDescription();
                     const query = this._getCurrentQuery();
                     this._describingPending.delete(query.statementName);
                     this._described.set(query.statementName, columns);
-                    query.state = query_1.QueryState.Executing;
+                    query.state = QueryState.Executing;
                     query.columns = columns;
                 }
                 break;
-            case constants_1.ResponseTypes.DataRow:
+            case ResponseTypes.DataRow:
                 {
                     const query = this._getCurrentQuery();
                     query.rows.push(reader.readDataRow());
                 }
                 break;
-            case constants_1.ResponseTypes.ComandComplete:
+            case ResponseTypes.ComandComplete:
                 {
                     reader.readCommandComplete();
                     if (this._pipelinesQueue.isFree) {
-                        this._destroyConnection();
+                        this.close();
                         break;
                     }
                     const query = this._getCurrentQuery();
                     if (!query) {
-                        this._destroyConnection();
+                        this.close();
                         break;
                     }
                     if (!query.columns) {
                         query.columns = this._described.get(query.statementName);
                     }
-                    query.state = query_1.QueryState.Completed;
+                    query.state = QueryState.Completed;
                     this._pipelinesQueue.get().next();
-                    query.resolve((0, value_parser_1.parseRowValues)(query.columns, query.rows));
+                    query.resolve(parseRowValues(query.columns, query.rows));
                 }
                 break;
-            case constants_1.ResponseTypes.ErrorResponse:
+            case ResponseTypes.ErrorResponse:
                 {
                     const error = reader.readErrorResponse();
                     if (this._logLevel === 'error' || this._logLevel === 'notice' || this._logLevel === 'query') {
@@ -322,18 +420,18 @@ class Connection {
                     }
                     const query = this._getCurrentQuery();
                     switch (query.state) {
-                        case query_1.QueryState.Parsing:
+                        case QueryState.Parsing:
                             this._parsingPending.delete(query.text);
                             break;
-                        case query_1.QueryState.Describing:
+                        case QueryState.Describing:
                             this._describingPending.delete(query.statementName);
                             break;
                     }
-                    query.state = query_1.QueryState.Failed;
+                    query.state = QueryState.Failed;
                     this._rejectPipeline(error);
                 }
                 break;
-            case constants_1.ResponseTypes.ReadyForQuery:
+            case ResponseTypes.ReadyForQuery:
                 {
                     reader.readReadyForQuery();
                     const pipeline = this._pipelinesQueue.get();
@@ -342,7 +440,7 @@ class Connection {
                     }
                 }
                 break;
-            case constants_1.ResponseTypes.Notice:
+            case ResponseTypes.Notice:
                 {
                     const message = reader.readErrorResponse();
                     if (this._logLevel === 'notice' || this._logLevel === 'query') {
@@ -350,6 +448,15 @@ class Connection {
                     }
                 }
                 break;
+            case 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,16 +464,8 @@ 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;
-    }
-    _destroyConnection() {
-        this._isAlive = false;
-        this._socket.destroy();
-        while (this._pipelinesQueue.hasMore) {
-            this._rejectPipeline(ErrConnectionDead);
-            this._pipelinesQueue.next();
-        }
+    get isOpened() {
+        return this._isOpened;
     }
     /**
      * Closes the connection immediately.
@@ -379,7 +478,11 @@ class Connection {
      * ```
      */
     close() {
-        this._destroyConnection();
+        this._isOpened = false;
+        this._socket.destroy();
+        while (this._pipelinesQueue.hasMore) {
+            this._rejectPipeline(ErrConnectionClosed);
+            this._pipelinesQueue.next();
+        }
     }
 }
-exports.Connection = Connection;

package/dist/error.d.ts

@@ -8,7 +8,7 @@ export declare class PostgresError extends Error {
     position: string;
     dataType: string;
     constraint: string;
-    constructor(message: string, code: string, detail: string, severity: string, where: string, hint: string, position: string, dataType: string, constraint: string);
+    constructor(message: string, code?: string, detail?: string, severity?: string, where?: string, hint?: string, position?: string, dataType?: string, constraint?: string);
     get isParseError(): boolean;
     get isDeadlock(): boolean;
     get isConstraintViolation(): boolean;

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,qBAAa,aAAc,SAAQ,KAAK;IAEhB,OAAO,EAAE,MAAM;IACxB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,MAAM;IACd,QAAQ,EAAE,MAAM;IAChB,KAAK,EAAE,MAAM;IACb,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,MAAM;IAChB,UAAU,EAAE,MAAM;gBART,OAAO,EAAE,MAAM,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM;IAQ7B,IAAI,YAAY,IAAI,OAAO,CAE1B;IAID,IAAI,UAAU,IAAI,OAAO,CAExB;IAID,IAAI,qBAAqB,IAAI,OAAO,CAEnC;IAGD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAGD,IAAI,mBAAmB,IAAI,OAAO,CAEjC;CACJ"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,qBAAa,aAAc,SAAQ,KAAK;IAEhB,OAAO,EAAE,MAAM;IACxB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,MAAM;IACd,QAAQ,EAAE,MAAM;IAChB,KAAK,EAAE,MAAM;IACb,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,MAAM;IAChB,UAAU,EAAE,MAAM;gBART,OAAO,EAAE,MAAM,EACxB,IAAI,GAAE,MAAqB,EAC3B,MAAM,GAAE,MAAW,EACnB,QAAQ,GAAE,MAAW,EACrB,KAAK,GAAE,MAAW,EAClB,IAAI,GAAE,MAAW,EACjB,QAAQ,GAAE,MAAW,EACrB,QAAQ,GAAE,MAAW,EACrB,UAAU,GAAE,MAAW;IAQlC,IAAI,YAAY,IAAI,OAAO,CAE1B;IAID,IAAI,UAAU,IAAI,OAAO,CAExB;IAID,IAAI,qBAAqB,IAAI,OAAO,CAEnC;IAGD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAGD,IAAI,mBAAmB,IAAI,OAAO,CAEjC;CACJ"}

package/dist/error.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PostgresError = void 0;
-class PostgresError extends Error {
-    constructor(message, code, detail, severity, where, hint, position, dataType, constraint) {
+export class PostgresError extends Error {
+    constructor(message, code = 'undeclared', detail = '', severity = '', where = '', hint = '', position = '', dataType = '', constraint = '') {
         super(message);
         this.message = message;
         this.code = code;
@@ -34,4 +31,3 @@ class PostgresError extends Error {
         return this.code.startsWith('08') || this.code.startsWith('57') && this.code !== '57014';
     }
 }
-exports.PostgresError = PostgresError;