@m2k-5f/pgtx 2.6.1 → 2.6.2

package/dist/pool.d.ts

@@ -2,41 +2,15 @@ import { Connection } from "./connection";
 import { Transaction } from "./transaction";
 import { Future } from "fluent-future";
 import { PostgresError } from "./error";
-import { PoolPartialConfig } from "./types";
+import { PoolPartialConfig, Row } from "./types";
 /**
- * The main entry point for Pgtx.
- * Manages a connection pool and provides high-level API for queries and transactions.
+ * Connection pool and the main entry point for Pgtx.
  *
  * @example
- * ```ts
- * const pool = new Pool({
- *   host: 'localhost',
- *   user: 'postgres',
- *   password: 'postgres',
- *   database: 'test',
- *   max: 10
- * })
- *
- * // Simple query
+ * const pool = new Pool({ host: 'localhost', user: 'postgres', password: 'postgres', database: 'test', max: 10 })
  * const users = await pool.query`SELECT * FROM users WHERE id = ${1}`
- *
- * // Transaction
- * const result = await pool.begin(async tx => {
- *   await tx.query`INSERT INTO users ...`
- *   return 'success'
- * })
- *
- * // Manual acquire/release
- * const conn = await pool.acquire()
- * try {
- *   await conn.query`SELECT 1`
- * } finally {
- *   pool.release(conn)
- * }
- *
- * // Clean up
- *  pool.close()
- * ```
+ * await pool.begin(async tx => tx.query`INSERT INTO users ...`)
+ * await pool.close()
  */
 export declare class Pool {
     private _available;
@@ -46,188 +20,62 @@ export declare class Pool {
     private _isOpened;
     constructor(config: PoolPartialConfig);
     /**
-     * Acquires a dedicated connection from the pool.
-     *
-     * **Note:** You must call `pool.release(conn)` manually when finished.
-     * For most cases, prefer using `pool.query()` or `pool.begin()` which handle this automatically.
-     *
-     * @returns A connection from the pool or a new one if available.
-     *
-     * @example
-     * ```ts
-     * const conn = await pool.acquire()
-     * try {
-     *   await conn.query`SELECT 1`
-     * } finally {
-     *   pool.release(conn)
-     * }
-     * ```
+     * Acquires a dedicated connection. Call `pool.release(conn)` when done —
+     * prefer `pool.query()`/`pool.begin()` where possible, they release automatically.
      */
     acquire(): Future<Connection, PostgresError>;
     /**
-     * Provides a safe execution context for performing low-level operations
-     * directly on a single, dedicated `Connection` instance.
-     *
-     * Automatically borrows a free socket from the pool, forwards it to the provided callback function,
-     * and guarantees that the connection is released back to the pool once the execution completes,
-     * even if errors or unexpected exceptions are thrown. Prevents connection descriptor leaks.
-     *
-     * @template T The return type of the provided callback function.
-     * @param {(conn: Connection) => Promise<T>} fn A callback function that operates on the allocated Connection.
-     * @returns {Future<T, PostgresError>} A `Future` that resolves with the return value of the callback.
+     * Runs `fn` with a borrowed connection and releases it afterward, even on error.
      *
      * @example
-     * // Executing low-level engine commands on a single, pinned connection
-     * const status = await pool.withAcquire(async (conn) => {
-     *     return await conn.query`SELECT pg_is_in_recovery()`;
-     * });
+     * const status = await pool.withAcquire(conn => conn.query`SELECT pg_is_in_recovery()`)
      */
     withAcquire<T>(fn: (conn: Connection) => Promise<T>): Future<T, unknown>;
-    /**
-     * Releases the connection back to the pool.
-     *
-     * If there are pending `acquire()` calls, the connection is passed directly to the next waiter.
-     * Otherwise, it's added to the available connections queue.
-     *
-     * @param conn - The connection to release.
-     *
-     * @example
-     * ```ts
-     * const conn = await pool.acquire()
-     * try {
-     *   await conn.query`SELECT 1`
-     * } finally {
-     *   pool.release(conn)
-     * }
-     * ```
-     */
+    /** Returns `conn` to the pool, or hands it directly to the next waiting `acquire()`. */
     release(conn: Connection): void;
     /**
-     * Starts a managed transaction.
-     *
-     * Automatically acquires a connection and handles `BEGIN`, `COMMIT`, and `ROLLBACK`.
-     * If the callback throws an error, the transaction is rolled back.
-     *
-     * @param txCallback - Async function that receives a `Transaction` instance.
-     * @returns The value returned from the callback.
+     * Runs `txCallback` inside a transaction on a borrowed connection, releasing it afterward.
      *
      * @example
-     * ```ts
-     * const result = await pool.begin(async tx => {
-     *   await tx.query`INSERT INTO accounts (id, balance) VALUES (1, 100)`
+     * await pool.begin(async tx => {
      *   await tx.query`UPDATE accounts SET balance = balance - 10 WHERE id = 1`
-     *   return { success: true }
      * })
-     * ```
      */
     begin<T>(txCallback: (transaction: Transaction) => Promise<T>): Future<T, unknown>;
     /**
-     * Executes a one-off query using pipeline.
-     *
-     * Automatically acquires and releases a connection from the pool.
-     * For optimal performance, multiple queries can be pipelined through the same connection.
-     *
-     * @param templates - Tagged template string with SQL.
-     * @param args - Query parameters.
-     * @returns Array of rows with proper typing.
-     *
-     * @example
-     * ```ts
-     * // Simple query
-     * const users = await pool.query`SELECT * FROM users`
-     *
-     * // With parameters
-     * const user = await pool.query`SELECT * FROM users WHERE id = ${1}`
-     *
-     * // With typed result
-     * type User = { id: number, name: string }
-     * const users = await pool.query<User>`SELECT * FROM users`
-     * ```
-     */
-    query<T extends Record<string, any>>(templates: TemplateStringsArray, ...args: any[]): Future<T[], PostgresError>;
-    /**
-     * 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 = pool.stream<User>`SELECT id, name FROM users`;
-     * return new Response(userStream, { headers: { 'Content-Type': 'application/json' } });
+     * Runs a one-off query on a borrowed connection.
      *
      * @example
-     * // Asynchronously iterating over rows as they arrive from the wire socket
-     * const stream = pool.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
-     * }
+     * const users = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
      */
-    stream<T extends Record<string, any>>(templates: TemplateStringsArray, ...args: any[]): ReadableStream<T>;
+    query<T extends Row>(templates: TemplateStringsArray, ...args: any[]): Future<T[], PostgresError>;
+    /** Like {@link query}, but for statements that don't return rows. */
+    execute(templates: TemplateStringsArray, ...params: any[]): Future<void, PostgresError>;
     /**
-     * Sends an asynchronous notification to a channel via `pg_notify`.
-     *
-     * @param channelName - The channel identifier
-     * @param payload - Optional string data (max 8000 bytes)
+     * Streams query results as a `ReadableStream`, without buffering rows in memory.
      *
      * @example
-     * ```ts
-     * await pool.notify('events', 'hello')
-     * ```
+     * for await (const row of pool.stream<User>`SELECT * FROM orders`) { ... }
      */
+    stream<T extends Row>(templates: TemplateStringsArray, ...args: any[]): ReadableStream<T>;
+    /** Sends a `pg_notify` message on `channelName` (payload ≤ 8000 bytes). */
     notify(channelName: string, payload?: string): Future<void, PostgresError>;
     /**
-     * Asynchronously subscribes to pub/sub events on a specific PostgreSQL channel (LISTEN).
-     *
-     * This method automatically claims a dedicated connection from the pool, registers the callback
-     * to handle incoming asynchronous database notices (`NotificationResponse` packets), and returns
-     * a lazy unsubscribe function wrapped in a `Future`.
-     *
-     * Invoking the returned unsubscribe function will automatically issue the `UNLISTEN` command
-     * to the database backend, clean up the memory callback, and safely release the connection back to the pool.
-     *
-     * @param {string} channel The name of the PostgreSQL notification channel.
-     * @param {(payload: string) => void} callback The event handler invoked when a NOTIFY message arrives.
-     * @returns {Future<() => Promise<void>, PostgresError>} A `Future` resolving to an async unsubscribe function.
+     * Subscribes `callback` to `channel` on a dedicated connection.
+     * Returns an unsubscribe function that issues `UNLISTEN` and releases the connection.
      *
      * @example
-     * // Subscribing to database events directly from the Pool
-     * const unlisten = await pool.listen('order_created', (payload) => {
-     *     const order = JSON.parse(payload);
-     *     console.log(`New order received: ${order.id}`);
-     * });
-     *
-     * // When the subscription is no longer needed (e.g., during teardown or server stop):
-     * await unlisten(); // The socket cleanly issues UNLISTEN and returns to the pool of free connections.
+     * const unlisten = await pool.listen('order_created', payload => console.log(payload))
+     * await unlisten()
      */
     listen(channel: string, callback: (payload: string) => void): Future<() => Future<void, PostgresError>, PostgresError>;
-    /**
-     * Number of available (idle) connections in the pool.
-     */
+    /** Number of idle connections. */
     get size(): number;
-    /**
-     * Total number of connections currently managed by the pool
-     * (available + in use).
-     */
+    /** Total connections managed (idle + in use). */
     get total(): number;
     /**
-     * Shuts down the pool and closes all active connections.
-     *
-     * All pending `acquire()` calls will be rejected with an error.
-     * The pool cannot be used after calling `close()`.
-     *
-     * @example
-     * ```ts
-     *  pool.close()
-     * ```
+     * Closes idle connections and rejects pending `acquire()` calls. Not usable afterward.
      */
-    close(): void;
+    close(): Future<void, PostgresError>;
 }
 //# sourceMappingURL=pool.d.ts.map

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,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C,OAAO,EAAS,MAAM,EAAM,MAAM,eAAe,CAAC;AAClD,OAAO,EAAiB,aAAa,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,EAAc,iBAAiB,EAAU,MAAM,SAAS,CAAC;AAGhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,IAAI;IACb,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,SAAS,CAAO;gBAEZ,MAAM,EAAE,iBAAiB;IAOrC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO;IA2BP;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC;IAUnD;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU;IAiBxB;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC;IAU7D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;IAuBpF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC;IAoCzG;;;;;;;;;;OAUG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW;IAQhD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;IAY3D;;OAEG;IACH,IAAI,IAAI,WAEP;IAGD;;;OAGG;IACH,IAAI,KAAK,WAER;IAGD;;;;;;;;;;OAUG;IACH,KAAK;CAaR"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C,OAAO,EAAS,MAAM,EAAM,MAAM,eAAe,CAAC;AAClD,OAAO,EAAiB,aAAa,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,EAAc,iBAAiB,EAAE,GAAG,EAAU,MAAM,SAAS,CAAC;AAGrE;;;;;;;;GAQG;AACH,qBAAa,IAAI;IACb,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,SAAS,CAAO;gBAEZ,MAAM,EAAE,iBAAiB;IAOrC;;;OAGG;IACH,OAAO;IA2BP;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC;IAUnD,wFAAwF;IACxF,OAAO,CAAC,IAAI,EAAE,UAAU;IAoBxB;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC;IAU7D;;;;;OAKG;IACH,KAAK,CAAC,CAAC,SAAS,GAAG,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;IAuBpE,qEAAqE;IACrE,OAAO,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IAuBzD;;;;;OAKG;IACH,MAAM,CAAC,CAAC,SAAS,GAAG,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC;IAoCzF,2EAA2E;IAC3E,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW;IAQhD;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;IAY3D,kCAAkC;IAClC,IAAI,IAAI,WAEP;IAGD,iDAAiD;IACjD,IAAI,KAAK,WAER;IAGD;;OAEG;IACH,KAAK;CAiBR"}

package/dist/pool.js

@@ -3,39 +3,13 @@ import { Queue, RingQueue } from "./queue";
 import { Begin, Future, Ok } from "fluent-future";
 import { ErrPoolClosed } from "./error";
 /**
- * The main entry point for Pgtx.
- * Manages a connection pool and provides high-level API for queries and transactions.
+ * Connection pool and the main entry point for Pgtx.
  *
  * @example
- * ```ts
- * const pool = new Pool({
- *   host: 'localhost',
- *   user: 'postgres',
- *   password: 'postgres',
- *   database: 'test',
- *   max: 10
- * })
- *
- * // Simple query
+ * const pool = new Pool({ host: 'localhost', user: 'postgres', password: 'postgres', database: 'test', max: 10 })
  * const users = await pool.query`SELECT * FROM users WHERE id = ${1}`
- *
- * // Transaction
- * const result = await pool.begin(async tx => {
- *   await tx.query`INSERT INTO users ...`
- *   return 'success'
- * })
- *
- * // Manual acquire/release
- * const conn = await pool.acquire()
- * try {
- *   await conn.query`SELECT 1`
- * } finally {
- *   pool.release(conn)
- * }
- *
- * // Clean up
- *  pool.close()
- * ```
+ * await pool.begin(async tx => tx.query`INSERT INTO users ...`)
+ * await pool.close()
  */
 export class Pool {
     constructor(config) {
@@ -47,22 +21,8 @@ export class Pool {
         this._available = new RingQueue(this.config.max);
     }
     /**
-     * Acquires a dedicated connection from the pool.
-     *
-     * **Note:** You must call `pool.release(conn)` manually when finished.
-     * For most cases, prefer using `pool.query()` or `pool.begin()` which handle this automatically.
-     *
-     * @returns A connection from the pool or a new one if available.
-     *
-     * @example
-     * ```ts
-     * const conn = await pool.acquire()
-     * try {
-     *   await conn.query`SELECT 1`
-     * } finally {
-     *   pool.release(conn)
-     * }
-     * ```
+     * Acquires a dedicated connection. Call `pool.release(conn)` when done —
+     * prefer `pool.query()`/`pool.begin()` where possible, they release automatically.
      */
     acquire() {
         if (!this._isOpened)
@@ -84,22 +44,10 @@ export class Pool {
         return future;
     }
     /**
-     * Provides a safe execution context for performing low-level operations
-     * directly on a single, dedicated `Connection` instance.
-     *
-     * Automatically borrows a free socket from the pool, forwards it to the provided callback function,
-     * and guarantees that the connection is released back to the pool once the execution completes,
-     * even if errors or unexpected exceptions are thrown. Prevents connection descriptor leaks.
-     *
-     * @template T The return type of the provided callback function.
-     * @param {(conn: Connection) => Promise<T>} fn A callback function that operates on the allocated Connection.
-     * @returns {Future<T, PostgresError>} A `Future` that resolves with the return value of the callback.
+     * Runs `fn` with a borrowed connection and releases it afterward, even on error.
      *
      * @example
-     * // Executing low-level engine commands on a single, pinned connection
-     * const status = await pool.withAcquire(async (conn) => {
-     *     return await conn.query`SELECT pg_is_in_recovery()`;
-     * });
+     * const status = await pool.withAcquire(conn => conn.query`SELECT pg_is_in_recovery()`)
      */
     withAcquire(fn) {
         return Begin()
@@ -107,27 +55,12 @@ export class Pool {
             .andThen(conn => Future.of(fn(conn))
             .finally(() => this.release(conn)));
     }
-    /**
-     * Releases the connection back to the pool.
-     *
-     * If there are pending `acquire()` calls, the connection is passed directly to the next waiter.
-     * Otherwise, it's added to the available connections queue.
-     *
-     * @param conn - The connection to release.
-     *
-     * @example
-     * ```ts
-     * const conn = await pool.acquire()
-     * try {
-     *   await conn.query`SELECT 1`
-     * } finally {
-     *   pool.release(conn)
-     * }
-     * ```
-     */
+    /** Returns `conn` to the pool, or hands it directly to the next waiting `acquire()`. */
     release(conn) {
-        if (!this._isOpened)
+        if (!this._isOpened) {
+            void conn.close();
             throw ErrPoolClosed;
+        }
         if (!conn.isOpened) {
             this._total--;
             return;
@@ -139,22 +72,12 @@ export class Pool {
         this._available.push(conn);
     }
     /**
-     * Starts a managed transaction.
-     *
-     * Automatically acquires a connection and handles `BEGIN`, `COMMIT`, and `ROLLBACK`.
-     * If the callback throws an error, the transaction is rolled back.
-     *
-     * @param txCallback - Async function that receives a `Transaction` instance.
-     * @returns The value returned from the callback.
+     * Runs `txCallback` inside a transaction on a borrowed connection, releasing it afterward.
      *
      * @example
-     * ```ts
-     * const result = await pool.begin(async tx => {
-     *   await tx.query`INSERT INTO accounts (id, balance) VALUES (1, 100)`
+     * await pool.begin(async tx => {
      *   await tx.query`UPDATE accounts SET balance = balance - 10 WHERE id = 1`
-     *   return { success: true }
      * })
-     * ```
      */
     begin(txCallback) {
         return Begin()
@@ -163,27 +86,10 @@ export class Pool {
             .finally(() => this.release(conn)));
     }
     /**
-     * Executes a one-off query using pipeline.
-     *
-     * Automatically acquires and releases a connection from the pool.
-     * For optimal performance, multiple queries can be pipelined through the same connection.
-     *
-     * @param templates - Tagged template string with SQL.
-     * @param args - Query parameters.
-     * @returns Array of rows with proper typing.
+     * Runs a one-off query on a borrowed connection.
      *
      * @example
-     * ```ts
-     * // Simple query
-     * const users = await pool.query`SELECT * FROM users`
-     *
-     * // With parameters
-     * const user = await pool.query`SELECT * FROM users WHERE id = ${1}`
-     *
-     * // With typed result
-     * type User = { id: number, name: string }
-     * const users = await pool.query<User>`SELECT * FROM users`
-     * ```
+     * const users = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
      */
     query(templates, ...args) {
         if (!this._isOpened)
@@ -203,30 +109,30 @@ export class Pool {
             return conn.query(templates, ...args);
         });
     }
+    /** Like {@link query}, but for statements that don't return rows. */
+    execute(templates, ...params) {
+        if (!this._isOpened)
+            return Future.reject(ErrPoolClosed);
+        while (this._available.hasMore) {
+            const conn = this._available.shift;
+            if (conn.isClosed) {
+                this._total--;
+                continue;
+            }
+            this._available.push(conn);
+            return conn.execute(templates, ...params);
+        }
+        return this.acquire()
+            .andThen(conn => {
+            this.release(conn);
+            return conn.execute(templates, ...params);
+        });
+    }
     /**
-     * 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.
+     * Streams query results as a `ReadableStream`, without buffering rows in memory.
      *
      * @example
-     * // Streaming a giant table directly to an HTTP response (Bun.serve)
-     * const userStream = pool.stream<User>`SELECT id, name FROM users`;
-     * return new Response(userStream, { headers: { 'Content-Type': 'application/json' } });
-     *
-     * @example
-     * // Asynchronously iterating over rows as they arrive from the wire socket
-     * const stream = pool.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 pool.stream<User>`SELECT * FROM orders`) { ... }
      */
     stream(templates, ...args) {
         if (!this._isOpened)
@@ -249,52 +155,26 @@ export class Pool {
         this.acquire()
             .tap(conn => {
             this.release(conn);
-            conn['_streamWithController'](templates, args, controller);
+            conn['_performStream'](templates, args, controller);
         })
             .catch(err => {
             controller.error(err);
         });
         return stream;
     }
-    /**
-     * 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')
-     * ```
-     */
+    /** Sends a `pg_notify` message on `channelName` (payload ≤ 8000 bytes). */
     notify(channelName, payload = "") {
         return this.acquire()
             .andThen(conn => conn.notify(channelName, payload)
             .finally(() => this.release(conn)));
     }
     /**
-     * Asynchronously subscribes to pub/sub events on a specific PostgreSQL channel (LISTEN).
-     *
-     * This method automatically claims a dedicated connection from the pool, registers the callback
-     * to handle incoming asynchronous database notices (`NotificationResponse` packets), and returns
-     * a lazy unsubscribe function wrapped in a `Future`.
-     *
-     * Invoking the returned unsubscribe function will automatically issue the `UNLISTEN` command
-     * to the database backend, clean up the memory callback, and safely release the connection back to the pool.
-     *
-     * @param {string} channel The name of the PostgreSQL notification channel.
-     * @param {(payload: string) => void} callback The event handler invoked when a NOTIFY message arrives.
-     * @returns {Future<() => Promise<void>, PostgresError>} A `Future` resolving to an async unsubscribe function.
+     * Subscribes `callback` to `channel` on a dedicated connection.
+     * Returns an unsubscribe function that issues `UNLISTEN` and releases the connection.
      *
      * @example
-     * // Subscribing to database events directly from the Pool
-     * const unlisten = await pool.listen('order_created', (payload) => {
-     *     const order = JSON.parse(payload);
-     *     console.log(`New order received: ${order.id}`);
-     * });
-     *
-     * // When the subscription is no longer needed (e.g., during teardown or server stop):
-     * await unlisten(); // The socket cleanly issues UNLISTEN and returns to the pool of free connections.
+     * const unlisten = await pool.listen('order_created', payload => console.log(payload))
+     * await unlisten()
      */
     listen(channel, callback) {
         return this.acquire()
@@ -302,38 +182,27 @@ export class Pool {
             .map(() => () => conn.unlisten(channel, callback)
             .tap(() => this.release(conn))));
     }
-    /**
-     * Number of available (idle) connections in the pool.
-     */
+    /** Number of idle connections. */
     get size() {
         return this._available.size;
     }
-    /**
-     * Total number of connections currently managed by the pool
-     * (available + in use).
-     */
+    /** Total connections managed (idle + in use). */
     get total() {
         return this._total;
     }
     /**
-     * Shuts down the pool and closes all active connections.
-     *
-     * All pending `acquire()` calls will be rejected with an error.
-     * The pool cannot be used after calling `close()`.
-     *
-     * @example
-     * ```ts
-     *  pool.close()
-     * ```
+     * Closes idle connections and rejects pending `acquire()` calls. Not usable afterward.
      */
     close() {
         this._isOpened = false;
+        const futures = [];
         while (this._available.hasMore) {
-            this._available.shift.close();
+            futures.push(this._available.shift.close());
         }
         while (this._waiting.hasMore) {
             this._waiting.shift.reject(ErrPoolClosed);
         }
         this._total = 0;
+        return Future.all(futures).map(() => { });
     }
 }

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

@@ -64,5 +64,6 @@ export declare class ConnectionResponseReader {
     readBindComplete(): void;
     readParameterDescription(): void;
     readNoData(): void;
+    skip(count: number): void;
 }
 //# sourceMappingURL=connection-response-reader.d.ts.map

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,EAA6B,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC5G,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAOxC,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,OAAO,IAAI,OAAO;IAKlB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAO3C,cAAc,IAAI,IAAI;IAOtB,mBAAmB,IAAI,IAAI;IAO3B,cAAc,IAAI,MAAM;IAaxB,SAAS,CAAC,SAAS,EAAE,MAAM;IAK3B,aAAa,IAAI,OAAO;IAaxB,iBAAiB;IAIjB,QAAQ;IAMR,YAAY,IAAI,MAAM;IAOtB,SAAS;IAST,WAAW;IAOX,WAAW,IAAI,MAAM;IAMrB,QAAQ;IAWR,SAAS,CAAC,MAAM,EAAE,MAAM;IAQxB,aAAa,CAAC,MAAM,EAAE,MAAM;CAW/B;AAGD,qBAAa,wBAAwB;IAG7B,OAAO,CAAC,MAAM;IADlB,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM;IAK1B,QAAQ;cACoC,YAAY;;;IAIxD,kBAAkB,IACoB,kBAAkB;IAIxD,WAAW;IAKX,mBAAmB;;;;IAQnB,kBAAkB;;;;IAQlB,iBAAiB,IAAI,aAAa;IA4ClC,iBAAiB,IACoB,iBAAiB;IAItD,kBAAkB,IAAI,MAAM,EAAE;IAa9B,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAKvC,kBAAkB;IAsBlB,WAAW,CAAC,YAAY,EAAE,iBAAiB,EAAE,EAAE,YAAY,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IA0G1F,wBAAwB;;;;IASxB,mBAAmB,IAAI,MAAM;IAK7B,OAAO;IAKP,aAAa;IAKb,iBAAiB;IAKjB,iBAAiB;IAGjB,gBAAgB;IAGhB,wBAAwB;IAOxB,UAAU;CACb"}
+{"version":3,"file":"connection-response-reader.d.ts","sourceRoot":"","sources":["../../src/protocol/connection-response-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA6B,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC5G,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAQxC,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,OAAO,IAAI,OAAO;IAKlB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAO3C,cAAc,IAAI,IAAI;IAOtB,mBAAmB,IAAI,IAAI;IAO3B,cAAc,IAAI,MAAM;IAaxB,SAAS,CAAC,SAAS,EAAE,MAAM;IAK3B,aAAa,IAAI,OAAO;IAaxB,iBAAiB;IAIjB,QAAQ;IAMR,YAAY,IAAI,MAAM;IAOtB,SAAS;IAST,WAAW;IAOX,WAAW,IAAI,MAAM;IAMrB,QAAQ;IAWR,SAAS,CAAC,MAAM,EAAE,MAAM;IAQxB,aAAa,CAAC,MAAM,EAAE,MAAM;CAW/B;AAGD,qBAAa,wBAAwB;IAG7B,OAAO,CAAC,MAAM;IADlB,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM;IAK1B,QAAQ;cACoC,YAAY;;;IAIxD,kBAAkB,IACoB,kBAAkB;IAIxD,WAAW;IAKX,mBAAmB;;;;IAQnB,kBAAkB;;;;IAQlB,iBAAiB,IAAI,aAAa;IA4ClC,iBAAiB,IACoB,iBAAiB;IAItD,kBAAkB,IAAI,MAAM,EAAE;IAa9B,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAKvC,kBAAkB;IAsBlB,WAAW,CAAC,YAAY,EAAE,iBAAiB,EAAE,EAAE,YAAY,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IA0G1F,wBAAwB;;;;IASxB,mBAAmB,IAAI,MAAM;IAK7B,OAAO;IAKP,aAAa;IAKb,iBAAiB;IAKjB,iBAAiB;IAGjB,gBAAgB;IAGhB,wBAAwB;IAOxB,UAAU;IAEV,IAAI,CAAC,KAAK,EAAE,MAAM;CAGrB"}

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

@@ -376,4 +376,7 @@ export class ConnectionResponseReader {
         }
     }
     readNoData() { }
+    skip(count) {
+        this.buffer.skipBytes(count);
+    }
 }

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

@@ -4,14 +4,14 @@ import { ConnectionResponseReader } from '../protocol/connection-response-reader
 import { ConnectionRequestWriter } from '../protocol/connection-request-writer';
 export declare class SocketConnector {
     private _socket;
-    private _onData;
-    private _onError;
     private residualBuffer;
-    private _isDestroyed;
-    constructor(_socket: Socket, _onData: (type: ResponseType, length: number, reader: ConnectionResponseReader) => void, _onError: (error: Error) => void);
+    private _onError;
+    private _onClose;
+    private _onData;
+    private _destroyed;
+    constructor(_socket: Socket, onData: (type: ResponseType, length: number, reader: ConnectionResponseReader) => void, onError: (error: unknown) => void);
     write(writer: ConnectionRequestWriter): void;
     unwrapSocket(): Socket;
     destroy(): void;
-    get isDestroyed(): boolean;
 }
 //# sourceMappingURL=socket-connector.d.ts.map

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,MAAM,EAAE,MAAM,EAAE,wBAAwB,KAAK,IAAI,EACvF,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;IA8B5C,KAAK,CAAC,MAAM,EAAE,uBAAuB;IAMrC,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;IAQpB,OAAO,CAAC,OAAO;IAPnB,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,UAAU,CAAQ;gBAGd,OAAO,EAAE,MAAM,EACvB,MAAM,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,wBAAwB,KAAK,IAAI,EACtF,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IA4CrC,KAAK,CAAC,MAAM,EAAE,uBAAuB;IAKrC,YAAY;IASZ,OAAO;CAGV"}