@m2k-5f/pgtx 2.6.11 → 2.7.0

package/dist/connection.js

@@ -5,41 +5,26 @@ import { compileSqlTemplate } from "./utils/template-compiler";
 import { Transaction } from "./transaction";
 import { SocketConnector } from "./protocol/socket-connector";
 import { Queue } from "./queue";
-import { ParseQuery, SimpleQuery, StreamQuery } from "./query";
+import { CollectQuery, StreamQuery, ExecuteQuery } from "./query";
 import { sql } from ".";
 import { Begin, Future, Ok } from 'fluent-future';
 import { ErrConnectionClosed, ErrConnectionReconnecting } from "./error";
 import { Batch } from "./batch";
 import { nextTick } from "process";
+const shedule = {
+    Immediate: setImmediate,
+    afterMicrotask: setTimeout,
+    beforeMicrotask: nextTick
+};
 /**
- * Represents a single dedicated connection to the PostgreSQL database.
- *
- * Supports:
- * - Tagged template queries with automatic parameter binding
- * - Prepared statements with caching
- * - Transaction management with savepoints
- * - Pipeline execution for concurrent queries
+ * A dedicated connection to PostgreSQL: tagged-template queries, prepared
+ * statement caching, transactions with savepoints, and pipelined execution.
  *
  * @example
- * ```ts
- * const conn = await Connection.new({
- *   host: 'localhost',
- *   user: 'postgres',
- *   password: 'postgres',
- *   database: 'test'
- * })
- *
- * // Simple query
+ * const conn = await Connection.new({ host: 'localhost', user: 'postgres', password: 'postgres', database: 'test' })
  * const users = await conn.query`SELECT * FROM users WHERE id = ${1}`
- *
- * // Transaction
- * await conn.begin(async tx => {
- *   await tx.query`INSERT INTO users ...`
- * })
- *
- * // Close connection
+ * await conn.begin(async tx => tx.query`INSERT INTO users ...`)
  * conn.close()
- * ```
  */
 export class Connection {
     _nextStatement() {
@@ -47,8 +32,9 @@ export class Connection {
     }
     constructor(config, socket) {
         this._activeBatch = null;
-        this._isOpened = true;
-        this._isReconnecting = false;
+        this._closing = null;
+        this._closed = false;
+        this._reconnecting = null;
         this._cachedBuffer = ConnectionRequestWriter.new();
         this._batchQueue = new Queue();
         this._parsed = new Map();
@@ -56,25 +42,11 @@ export class Connection {
         this._listeningCallbacks = new Map();
         this._stmtCounter = 0;
         this.config = config;
-        this._socket = new SocketConnector(socket, (type, _, reader) => this._handlePacket(type, reader), () => this._registerReconnect());
+        this._socket = new SocketConnector(socket, (type, length, reader) => this._handlePacket(type, reader, length), () => this._reconnect());
     }
     /**
-     * Creates a new database connection.
-     *
-     * @param params - Connection parameters
-     * @returns A new Connection instance
-     * @throws {PostgresError} If authentication fails or connection cannot be established
-     *
-     * @example
-     * ```ts
-     * const conn = await Connection.new({
-     *   host: 'localhost',
-     *   port: 5432,
-     *   user: 'postgres',
-     *   password: 'secret',
-     *   database: 'myapp'
-     * })
-     * ```
+     * Opens a new connection and authenticates.
+     * @throws {PostgresError} if authentication fails or the connection can't be established
      */
     static new(config) {
         const conf = {
@@ -82,7 +54,7 @@ export class Connection {
             logLevel: config.logLevel || 'error',
             int8toBigint: config.int8toBigint || false,
             queryTimeout: config.queryTimeout || 30000,
-            syncShedule: config.syncShedule || 'Immediate'
+            syncShedule: config.syncShedule || 'afterMicrotask'
         };
         const writer = ConnectionRequestWriter.new();
         return createAuthorizedSocket(writer, conf)
@@ -92,181 +64,138 @@ export class Connection {
         if (!this._activeBatch) {
             const batch = new Batch(this._cachedBuffer.clear());
             this._activeBatch = batch;
-            (this.config.syncShedule === 'Immediate' ? setImmediate : nextTick)(() => {
-                this._sync(batch);
-            });
+            shedule[this.config.syncShedule](() => this._sync(batch));
             return batch;
         }
         return this._activeBatch;
     }
     _sync(batch) {
-        if (!this._isOpened) {
-            batch.reject(ErrConnectionClosed);
+        if (this._reconnecting)
             return;
-        }
-        if (this._isReconnecting) {
-            this._reconnect()
-                .then(() => {
-                this._activeBatch = null;
-                this._isReconnecting = false;
-            })
-                .then(() => {
-                void this._restoreSubscriptions();
-            })
-                .catch(() => this.close());
-            return;
-        }
         this._socket.write(batch.end());
         this._activeBatch = null;
         this._batchQueue.push(batch);
     }
     /**
-     * Executes a query using tagged template literals.
-     *
-     * Parameters are automatically bound to `$1, $2, ...` placeholders.
-     * Queries with parameters use prepared statements for performance.
-     *
-     * @param templates - Tagged template string with SQL
-     * @param args - Query parameters
-     * @returns Array of rows with proper typing
-     * @throws {Error} If connection is dead or query fails
+     * Runs a query, binding template values as `$1, $2, ...`.
+     * Parameterized queries are cached as prepared statements.
      *
      * @example
-     * ```ts
-     * // Simple query
-     * const users = await conn.query`SELECT * FROM users`
-     *
-     * // With parameters
-     * const user = await conn.query`SELECT * FROM users WHERE id = ${1}`
-     *
-     * // With typed result
-     * type User = { id: number, name: string }
-     * const users = await conn.query<User>`SELECT * FROM users`
-     * ```
+     * const users = await conn.query<User>`SELECT * FROM users WHERE id = ${1}`
      */
     query(templates, ...params) {
-        if (!this._isOpened)
+        if (this.isClosed)
             return Future.reject(ErrConnectionClosed);
-        if (this._isReconnecting)
-            return Future.reject(ErrConnectionReconnecting);
+        if (this._reconnecting)
+            return this._reconnecting.andThen(() => this._performQuery(templates, ...params));
+        return this._performQuery(templates, ...params);
+    }
+    _performQuery(templates, ...params) {
         const { text, args } = compileSqlTemplate(templates, params);
         if (this.config.logLevel === 'query') {
             console.log(`\nQUERY:     ${text}\n${args.length !== 0 ? `ARGUMENTS: [${args}]\n` : ""}`);
         }
         if (this._parsed.has(text)) {
             const meta = this._parsed.get(text);
-            const query = new SimpleQuery(meta.statement, text, args, meta.columns, this.config.queryTimeout);
+            const query = new CollectQuery(meta.statement, text, args, meta.columns, this.config.queryTimeout);
             this._registerBatch().registerQuery(query);
             return query.future;
         }
-        if (!this._parsing.has(text)) {
-            const parseQuery = new ParseQuery(this._nextStatement(), text, this.config.queryTimeout);
-            this._parsing.set(text, parseQuery.future);
-            this._registerBatch().registerQuery(parseQuery);
-        }
-        const future = this._parsing.get(text);
-        return future.andThen(meta => {
-            const query = new SimpleQuery(meta.statement, text, args, meta.columns, this.config.queryTimeout);
+        if (this._parsing.has(text)) {
+            const statement = this._parsing.get(text);
+            const query = new CollectQuery(statement, text, args, null, this.config.queryTimeout);
             this._registerBatch().registerQuery(query);
             return query.future;
-        });
+        }
+        const query = new CollectQuery(this._nextStatement(), text, args, null, this.config.queryTimeout);
+        this._parsing.set(text, query.statement);
+        this._registerBatch().registerParse(query);
+        this._registerBatch().registerQuery(query);
+        return query.future;
     }
     /**
-     * Starts a managed transaction on this connection.
-     *
-     * Automatically handles:
-     * - `BEGIN` before the callback
-     * - `COMMIT` on successful completion
-     * - `ROLLBACK` if an error is thrown
+     * Like {@link query}, but for statements that don't return rows (INSERT/UPDATE/DDL/etc).
      *
-     * @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
+     * await conn.execute`UPDATE users SET name = ${name} WHERE id = ${id}`
+     */
+    execute(templates, ...params) {
+        if (this.isClosed)
+            return Future.reject(ErrConnectionClosed);
+        if (this._reconnecting)
+            return this._reconnecting.andThen(() => this._performExecute(templates, ...params));
+        return this._performExecute(templates, ...params);
+    }
+    _performExecute(templates, ...params) {
+        const { text, args } = compileSqlTemplate(templates, params);
+        if (this.config.logLevel === 'query') {
+            console.log(`\nQUERY:     ${text}\n${args.length !== 0 ? `ARGUMENTS: [${args}]\n` : ""}`);
+        }
+        if (this._parsed.has(text)) {
+            const meta = this._parsed.get(text);
+            const query = new ExecuteQuery(meta.statement, text, args, this.config.queryTimeout);
+            this._registerBatch().registerQuery(query);
+            return query.future;
+        }
+        if (this._parsing.has(text)) {
+            const statement = this._parsing.get(text);
+            const query = new ExecuteQuery(statement, text, args, this.config.queryTimeout);
+            this._registerBatch().registerQuery(query);
+            return query.future;
+        }
+        const query = new ExecuteQuery(this._nextStatement(), text, args, this.config.queryTimeout);
+        this._parsing.set(text, query.statement);
+        this._registerBatch().registerParse(query);
+        this._registerBatch().registerQuery(query);
+        return query.future;
+    }
+    /**
+     * Runs `txCallback` inside `BEGIN`/`COMMIT`, rolling back on error.
      *
      * @example
-     * ```ts
-     * const result = await conn.begin(async tx => {
-     *   await tx.query`INSERT INTO accounts (id, balance) VALUES (1, 100)`
+     * await conn.begin(async tx => {
      *   await tx.query`UPDATE accounts SET balance = balance - 10 WHERE id = 1`
-     *   return { success: true }
      * })
-     * ```
      */
     begin(txCallback) {
-        if (!this._isOpened)
+        if (this.isClosed)
             return Future.reject(ErrConnectionClosed);
-        if (this._isReconnecting)
-            return Future.reject(ErrConnectionReconnecting);
-        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();
-        }));
+            .andThen(() => this.execute `begin`)
+            .andThen(() => {
+            const tx = new Transaction(this);
+            return 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')
-     * ```
-     */
+    /** Sends a `pg_notify` message on `channelName` (payload ≤ 8000 bytes). */
     notify(channelName, payload = "") {
-        if (!this._isOpened)
+        if (this.isClosed)
             return Future.reject(ErrConnectionClosed);
-        if (this._isReconnecting)
-            return Future.reject(ErrConnectionReconnecting);
-        return this.query `select pg_notify(${channelName}, ${payload})`.map(() => { });
+        return this.execute `select pg_notify(${channelName}, ${payload})`.map(() => { });
     }
-    /**
-     * 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))
-     * ```
-     */
+    /** Subscribes `callback` to `channelName`, issuing `LISTEN` on first subscription. */
     listen(channelName, callback) {
-        if (!this._isOpened)
+        if (this.isClosed)
             return Future.reject(ErrConnectionClosed);
-        if (this._isReconnecting)
-            return Future.reject(ErrConnectionReconnecting);
         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)};`.map(() => { });
+        return this.execute `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)
-     * ```
-     */
+    /** Unsubscribes `callback`, issuing `UNLISTEN` once no callbacks remain. */
     unlisten(channelName, callback) {
-        if (!this._isOpened)
+        if (this.isClosed)
             return Future.reject(ErrConnectionClosed);
-        if (this._isReconnecting)
-            return Future.reject(ErrConnectionReconnecting);
         if (!this._listeningCallbacks.has(channelName)) {
             return Ok();
         }
@@ -274,76 +203,36 @@ export class Connection {
         callbackSet.delete(callback);
         if (callbackSet.size === 0) {
             this._listeningCallbacks.delete(channelName);
-            return this.query `unlisten ${sql.ident(channelName)};`.map(() => { });
+            return this.execute `unlisten ${sql.ident(channelName)};`.map(() => { });
         }
         return Ok();
     }
     /**
-     * Executes an SQL query in streaming mode.
-     *
-     * Data is streamed directly from the PostgreSQL binary network buffer into the Web Streams API
-     * (`ReadableStream`), bypassing any intermediate array allocation or row accumulation in the JS heap.
-     * This pattern provides a true Zero-Memory Footprint and is ideal for exporting massive tables
-     * or piping database payloads directly into HTTP responses (e.g., via `Bun.serve` or fetch `Response`).
-     *
-     * @template T The expected shape of a single row interface.
-     * @param {TemplateStringsArray} templates The SQL string parts from the tagged template literal.
-     * @param {...any} args The parameterized query arguments.
-     * @returns {ReadableStream<T>} Synchronously returns a native Web ReadableStream instance.
-     *
-     * @example
-     * // Streaming a giant table directly to an HTTP response (Bun.serve)
-     * const userStream = conn.stream<User>`SELECT id, name FROM users`;
-     * return new Response(userStream, { headers: { 'Content-Type': 'application/json' } });
+     * Streams query results as a `ReadableStream`, without buffering rows in memory.
+     * Ideal for large result sets or piping straight into an HTTP response.
      *
      * @example
-     * // Asynchronously iterating over rows as they arrive from the wire socket
-     * const stream = conn.stream<User>`SELECT * FROM orders WHERE status = ${'processed'}`;
-     * for await (const row of stream) {
-     *     console.log(row.id, row.amount); // Row object is eligible for GC immediately after iteration
-     * }
+     * for await (const row of conn.stream<User>`SELECT * FROM orders`) { ... }
      */
     stream(templates, ...params) {
-        if (!this._isOpened)
+        if (this.isClosed)
             throw ErrConnectionClosed;
-        if (this._isReconnecting)
-            throw ErrConnectionReconnecting;
-        const { text, args } = compileSqlTemplate(templates, params);
-        if (this.config.logLevel === 'query') {
-            console.log(`\nQUERY:     ${text}\n${args.length !== 0 ? `ARGUMENTS: [${args}]\n` : ""}`);
-        }
         let controller;
         const stream = new ReadableStream({
             start: c => {
                 controller = c;
             }
         });
-        if (this._parsed.has(text)) {
-            const meta = this._parsed.get(text);
-            const query = new StreamQuery(meta.statement, text, args, controller, meta.columns, this.config.queryTimeout);
-            this._registerBatch().registerQuery(query);
+        if (this._reconnecting) {
+            this._reconnecting
+                .tap(() => this._performStream(templates, params, controller))
+                .tapErr(err => controller.error(err));
             return stream;
         }
-        if (!this._parsing.has(text)) {
-            const parseQuery = new ParseQuery(this._nextStatement(), text, this.config.queryTimeout);
-            this._parsing.set(text, parseQuery.future);
-            this._registerBatch().registerQuery(parseQuery);
-        }
-        const future = this._parsing.get(text);
-        future
-            .tap(meta => {
-            const query = new StreamQuery(meta.statement, text, args, controller, meta.columns, this.config.queryTimeout);
-            this._registerBatch().registerQuery(query);
-        })
-            .tapErr(err => controller.error(err))
-            .recover();
+        this._performStream(templates, params, controller);
         return stream;
     }
-    _streamWithController(templates, params, controller) {
-        if (!this._isOpened)
-            throw ErrConnectionClosed;
-        if (this._isReconnecting)
-            throw ErrConnectionReconnecting;
+    _performStream(templates, params, controller) {
         const { text, args } = compileSqlTemplate(templates, params);
         if (this.config.logLevel === 'query') {
             console.log(`\nQUERY:     ${text}\n${args.length !== 0 ? `ARGUMENTS: [${args}]\n` : ""}`);
@@ -354,56 +243,59 @@ export class Connection {
             this._registerBatch().registerQuery(query);
             return;
         }
-        if (!this._parsing.has(text)) {
-            const parseQuery = new ParseQuery(this._nextStatement(), text, this.config.queryTimeout);
-            this._parsing.set(text, parseQuery.future);
-            this._registerBatch().registerQuery(parseQuery);
-        }
-        const future = this._parsing.get(text);
-        future
-            .tap(meta => {
-            const query = new StreamQuery(meta.statement, text, args, controller, meta.columns, this.config.queryTimeout);
+        if (this._parsing.has(text)) {
+            const statement = this._parsing.get(text);
+            const query = new StreamQuery(statement, text, args, controller, null, this.config.queryTimeout);
             this._registerBatch().registerQuery(query);
-        })
-            .tapErr(err => {
-            controller.error(err);
-        })
-            .recover();
+            return;
+        }
+        const query = new StreamQuery(this._nextStatement(), text, args, controller, null, this.config.queryTimeout);
+        this._parsing.set(text, query.statement);
+        this._registerBatch().registerParse(query);
+        this._registerBatch().registerQuery(query);
     }
-    _registerReconnect() {
-        if (this._isReconnecting)
+    _reconnect() {
+        if (this.isClosed)
+            return;
+        if (this._reconnecting)
             return;
-        this._isReconnecting = true;
+        this._reconnecting = this._performReconnect()
+            .tap(() => this._reconnecting = null)
+            .andThen(() => this._restoreSubscriptions())
+            .tapErr(() => {
+            this._reconnecting = null;
+            this._reconnect();
+        })
+            .recover();
     }
-    _resetConnectionState(cause) {
+    _performReconnect() {
+        this._socket.destroy();
         this._parsed.clear();
         this._parsing.clear();
+        this._activeBatch?.reject(ErrConnectionReconnecting);
         this._activeBatch = null;
-        this._rejectAllBatches(cause);
-    }
-    async _reconnect() {
-        const socket = await createAuthorizedSocket(ConnectionRequestWriter.new(), this.config);
-        const connector = new SocketConnector(socket, (type, _, reader) => this._handlePacket(type, reader), (err) => this._registerReconnect());
-        this._socket = connector;
-        this._resetConnectionState(ErrConnectionReconnecting);
+        while (this._batchQueue.hasMore) {
+            this._batchQueue.shift.reject(ErrConnectionReconnecting);
+        }
+        return createAuthorizedSocket(ConnectionRequestWriter.new(), this.config)
+            .andThen(socket => {
+            const connector = new SocketConnector(socket, (type, length, reader) => this._handlePacket(type, reader, length), () => this._reconnect());
+            this._socket = connector;
+            return Ok();
+        });
     }
     _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 Future.resolve();
+        const futures = Array.from(this._listeningCallbacks.keys()).map(channel => {
+            return this.execute `LISTEN ${sql.ident(channel)};`;
         });
-        return Promise.all(promises);
+        return Future.all(futures).map(() => { });
     }
     _getCurrentQuery() {
         return this._batchQueue.current.current;
     }
-    _rejectAllBatches(cause) {
-        while (this._batchQueue.hasMore) {
-            this._batchQueue.shift.reject(cause);
-        }
-    }
-    _handlePacket(type, reader) {
+    _handlePacket(type, reader, length) {
         switch (type) {
             case ResponseTypes.ParseComplete:
                 {
@@ -413,6 +305,13 @@ export class Connection {
             case ResponseTypes.BindComplete:
                 {
                     reader.readBindComplete();
+                    const query = this._getCurrentQuery();
+                    if (query instanceof ExecuteQuery) {
+                        break;
+                    }
+                    if (!query.columns) {
+                        query.columns = this._parsed.get(query.text).columns;
+                    }
                 }
                 break;
             case ResponseTypes.CloseComplete:
@@ -431,25 +330,27 @@ export class Connection {
                     const query = this._getCurrentQuery();
                     const meta = { statement: query.statement, columns: [] };
                     this._parsing.delete(query.text);
-                    query.resolve(meta);
                     this._parsed.set(query.text, meta);
-                    this._batchQueue.current.next();
                 }
                 break;
             case ResponseTypes.RowDescription:
                 {
                     const columns = reader.readRowDescription();
                     const query = this._getCurrentQuery();
-                    const meta = { statement: query.statement, columns };
+                    const meta = {
+                        statement: query.statement, columns
+                    };
                     this._parsing.delete(query.text);
-                    query.resolve(meta);
                     this._parsed.set(query.text, meta);
-                    this._batchQueue.current.next();
                 }
                 break;
             case ResponseTypes.DataRow:
                 {
                     let query = this._getCurrentQuery();
+                    if (query instanceof ExecuteQuery) {
+                        reader.skip(length - 4);
+                        break;
+                    }
                     query.push(reader.readDataRow(query.columns, this.config.int8toBigint));
                 }
                 break;
@@ -467,10 +368,7 @@ export class Connection {
                     if (this.config.logLevel === 'error' || this.config.logLevel === 'notice' || this.config.logLevel === 'query') {
                         console.log(`\nError:    ${error}\n`);
                     }
-                    const query = this._getCurrentQuery();
-                    if (query instanceof ParseQuery) {
-                        this._parsing.delete(query.text);
-                    }
+                    this._parsing.clear();
                     this._batchQueue.current.reject(error);
                 }
                 break;
@@ -478,6 +376,7 @@ export class Connection {
                 {
                     reader.readReadyForQuery();
                     this._batchQueue.next();
+                    this._closing && !this._hasQueries && this._closing.resolve();
                 }
                 break;
             case ResponseTypes.Notice:
@@ -500,26 +399,38 @@ export class Connection {
             default: console.log('Undeclared response type: ', type);
         }
     }
-    /**
-     * Checks if the connection is still alive and usable.
-     * Returns `false` if the socket is destroyed or connection is dead.
-     */
+    get _hasQueries() {
+        return this._batchQueue.hasMore || this._activeBatch;
+    }
+    /** Whether the connection is alive and usable. */
     get isOpened() {
-        return this._isOpened;
+        return !this._closing && !this._closed;
+    }
+    /** Whether the connection is closed or closing. */
+    get isClosed() {
+        return this._closed || !!this._closing;
     }
     /**
-     * Closes the connection immediately.
-     * All pending queries will be rejected with an error.
-     * The connection cannot be used after this call.
-     *
-     * @example
-     * ```ts
-     * conn.close()
-     * ```
+     * Closes the connection, awaiting for all pending queries. Not usable afterward.
      */
     close() {
-        this._isOpened = false;
-        this._socket.destroy();
-        this._rejectAllBatches(ErrConnectionClosed);
+        if (this._closed)
+            return Future.resolve();
+        if (this._closing) {
+            return this._closing.future;
+        }
+        if (!this._hasQueries) {
+            this._closed = true;
+            this._socket.destroy();
+            return Future.resolve();
+        }
+        const closing = Future.withResolvers();
+        this._closing = closing;
+        closing.future.tap(() => {
+            this._closing = null;
+            this._closed = true;
+            this._socket.destroy();
+        });
+        return closing.future;
     }
 }