@m2k-5f/pgtx 2.4.1 → 2.5.0

package/README.md

@@ -55,6 +55,7 @@
 
   - **Pipeline queries** — Automatic query multiplexing over PostgreSQL pipeline protocol
   - **Tagged templates** — Natural SQL with type safety
+  - **Native Web Streams API** — Memory-efficient data streaming via `pool.stream()`
   - **Transactions & Savepoints** — Nested transactions with rollback
   - **Bulk inserts** — Auto-extract columns from objects
   - **Dynamic updates** — Generate SET clauses from objects
@@ -63,42 +64,64 @@
   - **Connection pool** — Auto-management connections with support for pipeline queries via the pool itself.
   - **Zero dependencies** — Lightweight and blazing
 
-  ---
+---
 
-  ## ⚡ Performance & Benchmarks
+## ⚡ Performance
 
-  ### 1. In-Engine Pipeline Blast (3000 Parallel Queries)
-  *Measured using `mitata` inside GitHub Actions cloud runners (Ubuntu, 2 vCPUs, 10 DB Connections).*
+All benchmarks are executed on **GitHub Actions** (Ubuntu, 2 vCPUs) and are fully reproducible. Benchmark sources are included in this repository.
 
-  | Driver | Avg Time per Iteration | Relative Speed | Memory (p75) |
-  | :--- | :---: | :---: | :---: |
-  | **Pgtx (Pipeline)** | **19.21 ms** | **Baseline (3.6×)** | **874.71 KB** |
-  | Postgres.js (Pipeline) | 70.50 ms | 3.6× Slower | 1.29 MB |
-  | node-postgres (no pipeline) | 327.07 ms | 17.0× Slower | 4.05 MB |
+### 1. PostgreSQL Pipeline Stress Test
 
-  > **Stability Note:** Pgtx provides an rock-solid flat latency graph (p99 is strictly bounded to `21.76 ms`), while maintaining a 2.5× smaller memory footprint compared to Postgres.js due to zero-allocation binary parsing.
+**3000 concurrent parameterized `SELECT` queries**
 
-  ### 2. Real-World HTTP Throughput (`wrk` Stress Test)
-  *HTTP server baseline using a `node:http` instance on GitHub Actions runner, handling 1,000 concurrent network connections (`wrk -t2 -c1000 -d10s`).*
+* Connection pool: **10 connections**
+* Measured with **mitata**
 
-  - **Pgtx:**  **~14,500 RPS**
-  - **Postgres.js:**  **~11,500 RPS**
+| Driver                 |     Avg Time |       Relative Speed | Memory (p75) |
+| :--------------------- | -----------: | -------------------: | -----------: |
+| **Pgtx (Pipeline)**    | **24.18 ms** | **Baseline (1.00×)** |  **≈2.5 MB** |
+| Postgres.js (Pipeline) |     83.36 ms |     **3.45× slower** |      ≈7.6 MB |
+| node-postgres (`pg`)   |    377.95 ms |    **15.63× slower** |     ≈11.4 MB |
 
-  On high-concurrency bare metal servers, Pgtx effortlessly maintains a **+25% performance lead** over Postgres.js.
+### 2. Real-World HTTP Throughput
 
-  Pgtx achieves high throughput by:
+Simple `node:http` server serving a PostgreSQL-backed endpoint.
 
-  * Pipeline query multiplexing
-  * Synchronous protocol encoding
-  * Batched socket writes
-  * Automatic prepared statement caching
-  * Row description caching
-  * Zero-dependency implementation
-  * Binary protocol support
+Measured with:
 
-  > Benchmarks source is available in the repository and can be reproduced locally.
+```bash
+wrk -t2 -c<N> -d10s http://localhost:3000/users
+```
 
-  ---
+| Concurrent Connections |             Pgtx |  Postgres.js |   Speedup |
+| ---------------------: | ---------------: | -----------: | --------: |
+|                     50 |      5,272 req/s |  5,691 req/s |     0.93× |
+|                    200 | **12,918 req/s** |  6,724 req/s | **1.92×** |
+|                   1000 | **21,429 req/s** |  8,423 req/s | **2.54×** |
+|                  10000 | **22,486 req/s** | 12,764 req/s | **1.76×** |
+
+### Why is Pgtx fast?
+
+Pgtx is engineered for **throughput**, not for minimizing the latency of individual queries.
+
+Instead of optimizing a single request in isolation, Pgtx minimizes per-query overhead under sustained concurrent load by combining:
+
+* Pipeline query multiplexing
+* Synchronous PostgreSQL wire protocol encoding
+* Batched socket writes
+* Automatic prepared statement caching
+* Prepared statement deduplication
+* Row description caching
+* Binary protocol support
+* Zero-dependency implementation
+
+As concurrency increases, these optimizations significantly reduce protocol overhead, allowing Pgtx to scale more efficiently than traditional PostgreSQL drivers.
+
+In the `mitata` benchmark, Pgtx also demonstrated approximately **3× lower memory usage** than Postgres.js while processing the same workload, reducing allocation pressure and improving sustained throughput under heavy load.
+
+> **Blazing** isn't just a tagline — it's backed by reproducible benchmarks.
+
+---
 
   ## 🔥 Why Pgtx?
 
@@ -156,6 +179,60 @@
   > 🚀 Pgtx automatically groups concurrent queries into pipeline batches, reducing network overhead by up to 5x compared to sequential queries.
 
 
+  ### High-Performance Data Streaming (`pool.stream`)
+
+  For heavy database lookups (exporting millions of rows, bulk reports, or large analytical dumps), memory accumulation is the ultimate killer of backend stability. Storing rows in a standard JavaScript array causes massive heap pollution and triggers blocking Garbage Collection spikes.
+
+  Pgtx solves this at the protocol level by introducing `pool.stream()`, which bypasses row aggregation entirely and pipes rows transitively directly into a native Web **`ReadableStream`**.
+
+  #### 1. Ultra-Low Memory Row Iteration
+  You can consume database rows sequentially using standard `for await...of` syntax. Rows are processed and evicted from memory the moment they arrive from the network socket buffer.
+
+  ```typescript
+  interface HeavyLog { id: number; data: string; timestamp: Date; }
+
+  const logStream = pool.stream<HeavyLog>`
+    SELECT id, data, timestamp FROM application_logs WHERE level = ${'error'}
+  `;
+
+  for await (const log of logStream) {
+    // Each log object is parsed on-the-fly and processed instantly.
+    // Zero rows are accumulated in the internal driver state!
+    console.log(`[${log.timestamp.toISOString()}] ${log.data}`);
+  }
+  ```
+
+  #### 2. Streaming Directly to HTTP Responses (`Bun.serve`)
+  Since Pgtx implements the standardized Web Streams API, you can bridge your database query directly into an HTTP response body with absolutely zero intermediate buffers.
+
+  ```typescript
+  import { Pool } from "@m2k-5f/pgtx";
+
+  const pool = new Pool({ /* ... config ... */ });
+
+  export default {
+    port: 3000,
+    async fetch(request) {
+      const url = new URL(request.url);
+
+      if (url.pathname === "/export/users") {
+        // Synchronously returns a stream handle even if pool sockets are currently busy
+        const userStream = pool.stream`SELECT id, email, profile_metadata FROM giant_user_table`;
+
+        return new Response(userStream, {
+          headers: {
+            "Content-Type": "application/json",
+            "Transfer-Encoding": "chunked",
+          },
+        });
+      }
+
+      return new Response("Not Found", { status: 404 });
+    },
+  };
+  ```
+
+
   ### Transactions & Savepoints
 
   ```typescript
@@ -173,13 +250,36 @@
 
   ### Async Notifications (LISTEN / NOTIFY)
 
-  Pgtx natively handles PostgreSQL `LISTEN/NOTIFY` protocol messages asynchronously without interrupting multiplexed query pipeline.
+  Pgtx natively handles PostgreSQL `LISTEN/NOTIFY` protocol messages asynchronously without interrupting the multiplexed query pipeline. It offers two distinct ways to subscribe: high-level pool-driven subscriptions and low-level connection pinning.
 
+  #### 1. Sending a Notification
+  Notifications are atomic and can be triggered directly from the `Pool` utilizing any available socket:
   ```typescript
-  // 1. Sending a notification
   await pool.notify('user_events', JSON.stringify({ id: 42, action: 'signup' }))
+  ```
+
+  #### 2. High-Level Pool Subscription (Recommended)
+  You can subscribe directly via the `Pool` instance. Pgtx will automatically borrow a dedicated connection from the pool, issue the `LISTEN` command, and seamlessly manage its lifecycle. 
+
+  The method returns a lazy, async **unsubscribe function** that cleanly handles `UNLISTEN` and returns the connection to the pool when invoked.
+
+  ```typescript
+  const onEvent = (payload: string) => {
+    console.log(`Received payload: ${payload}`)
+  }
+
+  // Automatically borrows a connection and sets up the listener
+  const unsubscribe = await pool.listen('user_events', onEvent)
+
+  // When the subscription is no longer needed (e.g., server shutdown):
+  // It automatically sends UNLISTEN and releases the connection back to the pool!
+  await unsubscribe()
+  ```
+
+  #### 3. Low-Level Connection Subscription (Stateful)
+  If you need complete control over a specific PostgreSQL backend process, you can acquire an explicit `Connection` instance. This allows you to multiplex multiple callbacks onto a single channel seamlessly.
 
-  // 2. Receiving notifications (Requires a dedicated connection from the pool)
+  ```typescript
   const conn = await pool.acquire()
 
   const onEvent = (payload: string) => {
@@ -190,14 +290,15 @@
   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)
+  // Cleans 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.
+  // ⚠️ Manual lifecycle management is strictly required for this pattern!
+  // Do NOT release it back to the pool until you are completely done listening.
+  this.release(conn)
   ```
 
-  > ⚠️ **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()`.
+  > ⚠️ **Architecture Note:** While `pool.notify` is a fire-and-forget atomic command, subscription states (`LISTEN`/`UNLISTEN`) are strictly tied to specific PostgreSQL backend processes. Using the high-level `pool.listen()` is strongly recommended for application code, as it encapsulates socket management into an elegant, leak-proof callback boundary.
 
 
   ### Bulk Inserts
@@ -342,7 +443,7 @@
       notify(channelName: string, payload?: string): Future<[], PostgresError>
       listen(channelName: string, callback: (payload: string) => void): Future<[], PostgresError>
       unlisten(channelName: string, callback: (payload: string) => void): Future<[], PostgresError>
-
+      stream<T extends Record<string, any>>(templates: TemplateStringsArray, ...params: any[]): ReadableStream<T>
       get isAlive(): boolean
       close(): void
   }
@@ -353,7 +454,8 @@
       host: string
       port: number
       database: string
-      logLevel?: 'none' | 'error' | 'notice' | 'query' // defaul: "error"
+      queryTimeout?: number // default: 30 srconds
+      logLevel?: 'none' | 'error' | 'notice' | 'query' // default: "error"
   }
   ```
 
@@ -363,10 +465,13 @@
   class Pool {
       constructor(config: PoolConfig)
 
-      query<T>(strings: TemplateStringsArray, ...values: any[]): Future<T[], Error>
+      query<T>(strings: TemplateStringsArray, ...values: any[]): Future<T[], PostgresError>
       begin<T>(callback: (tx: Transaction) => Promise<T>): Future<T, Error>
       notify(channelName: string, payload?: string): Future<[], PostgresError>
-      acquire(): Future<Connection, Error>
+      listen(channel: string, callback: (payload: string) => void): Future<() => Promise<void>, PostgresError>
+      stream<T extends Record<string, any>>(templates: TemplateStringsArray, ...args: any[]): ReadableStream<T>
+      withAcquire<T>(fn: (conn: Connection) => Promise<T>): Future<T, Error>
+      acquire(): Future<Connection, PostgresError>
       release(conn: Connection): void
       close(): void
 

package/dist/connection.d.ts

@@ -1,4 +1,4 @@
-import { Branded, ColumnDescription } from "./types";
+import { Branded } from "./types";
 import { Transaction } from "./transaction";
 import { Future } from 'fluent-future';
 import { PostgresError } from "./error";
@@ -11,23 +11,7 @@ export type ConnectionParams = {
     database: string;
     logLevel?: LogLevel;
     int8toBigint?: boolean;
-};
-export type ExecuteQueueUnit = {
-    rows: (string | null)[][];
-    resolve: (value: any) => void;
-    reject: (err: Error) => void;
-    statementName: StatementName;
-};
-export type ParsingQueueUnit = {
-    resolve: (statementName: StatementName) => void;
-    reject: (error: Error) => void;
-    text: QueryText;
-    statementName: StatementName;
-};
-export type DescribeQueueUnit = {
-    resolve: (value: ColumnDescription[]) => void;
-    reject: (error: Error) => void;
-    statementName: StatementName;
+    queryTimeout?: number;
 };
 export type StatementName = Branded<string, 'StatementName'>;
 export type QueryText = Branded<string, 'QueryText'>;
@@ -182,7 +166,35 @@ export declare class Connection {
      * ```
      */
     unlisten(channelName: string, callback: (payload: string) => void): Future<[], 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 = conn.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 = 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
+     * }
+     */
+    stream<T extends Record<string, any>>(templates: TemplateStringsArray, ...params: any[]): ReadableStream<T>;
+    private _streamWithController;
     private _createQuery;
+    private _createStream;
     private _writeQuery;
     private _registerFlush;
     private _flush;

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

@@ -5,7 +5,7 @@ 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 { Query, QueryState, StreamQuery } from "./query";
 import { sql } from ".";
 import { Begin, Future, Resolve } from 'fluent-future';
 import { PostgresError } from "./error";
@@ -62,7 +62,7 @@ export class Connection {
         this._stmtCounter = 0;
         this.params = params;
         this._logLevel = logLevel;
-        this._socket = new SocketConnector(socket, (type, reader) => this._handlePacket(type, reader), (err) => this._registerReconnect());
+        this._socket = new SocketConnector(socket, (type, _, reader) => this._handlePacket(type, reader), (err) => this._registerReconnect());
         this._writer = writer;
     }
     /**
@@ -121,11 +121,8 @@ export class Connection {
         }
         const query = this._createQuery(text, args);
         this._writeQuery(query);
-        return Future.of(query.promise, error => {
-            if (error instanceof PostgresError)
-                return error;
-            return new PostgresError(error.message);
-        });
+        query.startTimeout(this.params.queryTimeout || 30000);
+        return query.future;
     }
     /**
      * Starts a managed transaction on this connection.
@@ -222,6 +219,61 @@ export class Connection {
         }
         return Resolve([]);
     }
+    /**
+     * 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' } });
+     *
+     * @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
+     * }
+     */
+    stream(templates, ...params) {
+        this._checkOpened();
+        this._registerFlush();
+        const { text, args } = compileSqlTemplate({ templates, args: params });
+        if (this._logLevel === 'query') {
+            console.log(`\nQUERY:     ${text}\n${args.length !== 0 ? `ARGUMENTS: [${args}]\n` : ""}`);
+        }
+        let controller;
+        const stream = new ReadableStream({
+            start: c => {
+                controller = c;
+            }
+        });
+        const query = this._createStream(text, args, controller);
+        this._writeQuery(query);
+        query.startTimeout(this.params.queryTimeout || 30000);
+        return stream;
+    }
+    _streamWithController(templates, params, controller) {
+        this._checkOpened();
+        this._registerFlush();
+        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._createStream(text, args, controller);
+        this._writeQuery(query);
+        query.startTimeout(this.params.queryTimeout || 30000);
+        return query;
+    }
     _createQuery(text, args) {
         if (this._parsed.has(text)) {
             const statementName = this._parsed.get(text);
@@ -251,6 +303,35 @@ export class Connection {
             }
         }
     }
+    _createStream(text, args, controller) {
+        if (this._parsed.has(text)) {
+            const statementName = this._parsed.get(text);
+            if (this._described.has(statementName)) {
+                const columns = this._described.get(statementName);
+                return new StreamQuery(text, args, QueryState.Executing, statementName, controller, columns);
+            }
+            else {
+                if (this._describingPending.has(statementName)) {
+                    return new StreamQuery(text, args, QueryState.Executing, statementName, controller);
+                }
+                else {
+                    this._describingPending.add(statementName);
+                    return new StreamQuery(text, args, QueryState.Describing, statementName, controller);
+                }
+            }
+        }
+        else {
+            if (this._parsingPending.has(text)) {
+                const statementName = this._parsingPending.get(text);
+                return new StreamQuery(text, args, QueryState.Describing, statementName, controller);
+            }
+            else {
+                const statementName = this._nextStatement();
+                this._parsingPending.set(text, statementName);
+                return new StreamQuery(text, args, QueryState.Parsing, statementName, controller);
+            }
+        }
+    }
     _writeQuery(query) {
         if (query.state === QueryState.Parsing) {
             this._writer
@@ -314,7 +395,7 @@ export class Connection {
     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());
+        const connector = new SocketConnector(socket, (type, _, reader) => this._handlePacket(type, reader), (err) => this._registerReconnect());
         this._socket = connector;
         void this._restoreSubscriptions();
         this._isReconnecting = false;

package/dist/pool.d.ts

@@ -67,7 +67,26 @@ export declare class Pool {
      * }
      * ```
      */
-    acquire(): Future<Connection, Error>;
+    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.
+     *
+     * @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()`;
+     * });
+     */
+    withAcquire<T>(fn: (conn: Connection) => Promise<T>): Future<T, Error>;
     /**
      * Releases the connection back to the pool.
      *
@@ -129,7 +148,33 @@ export declare class Pool {
      * const users = await pool.query<User>`SELECT * FROM users`
      * ```
      */
-    query<T extends Record<string, any>>(templates: TemplateStringsArray, ...args: any[]): Future<T[], Error>;
+    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' } });
+     *
+     * @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
+     * }
+     */
+    stream<T extends Record<string, any>>(templates: TemplateStringsArray, ...args: any[]): ReadableStream<T>;
     /**
      * Sends an asynchronous notification to a channel via `pg_notify`.
      *
@@ -142,6 +187,31 @@ export declare class Pool {
      * ```
      */
     notify(channelName: string, payload?: string): Future<[], 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.
+     *
+     * @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.
+     */
+    listen(channel: string, callback: (payload: string) => void): Future<() => Promise<void>, PostgresError>;
     /**
      * 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;AAG3C,OAAO,EAAE,MAAM,EAAW,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,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;IACH,OAAO;IAyBP;;;;;;;;;;;;;;;;;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;IAW7D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;IAuBpF;;;;;;;;;;OAUG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW,GACuB,MAAM,CAAC,EAAE,EAAE,aAAa,CAAC;IAIhG;;OAEG;IACH,IAAI,IAAI,WAEP;IAGD;;;OAGG;IACH,IAAI,KAAK,WAER;IAGD;;;;;;;;;;OAUG;IACH,KAAK;CAWR"}
+{"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;AAG3C,OAAO,EAAS,MAAM,EAAW,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,KAAK,UAAU,GAAG,gBAAgB,GAAG;IACjC,GAAG,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;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;IAY7D;;;;;;;;;;;;;;;;;;;;;;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,GACuB,MAAM,CAAC,EAAE,EAAE,aAAa,CAAC;IAIhG;;;;;;;;;;;;;;;;;;;;;;;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;CAWR"}

package/dist/pool.js

@@ -1,6 +1,8 @@
 import { Connection } from "./connection";
 import { Queue } from "./queue";
-import { Future, Resolve } from "fluent-future";
+import { Begin, Future, Resolve } from "fluent-future";
+import { PostgresError } from "./error";
+const ErrPoolClosed = new PostgresError('Pool closed');
 /**
  * The main entry point for Pgtx.
  * Manages a connection pool and provides high-level API for queries and transactions.
@@ -78,12 +80,36 @@ export class Pool {
         }
         if (this._total < this._max) {
             this._total++;
-            return Future.of(Connection.new(this._config))
+            return Connection.new(this._config)
                 .tapErr(() => this._total--);
         }
-        return Future.of(new Promise((resolve, reject) => {
-            this._waiting.push({ resolve, reject });
-        }));
+        const { future, reject, resolve } = Future.withResolvers();
+        this._waiting.push({ resolve, reject });
+        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.
+     *
+     * @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()`;
+     * });
+     */
+    withAcquire(fn) {
+        return Begin()
+            .andThen(() => this.acquire())
+            .andThen(conn => Future.of(fn(conn))
+            .finally(() => this.release(conn)));
     }
     /**
      * Releases the connection back to the pool.
@@ -135,7 +161,8 @@ export class Pool {
      */
     begin(txCallback) {
         this._checkClosed();
-        return this.acquire()
+        return Begin()
+            .andThen(() => this.acquire())
             .andThen(conn => conn.begin(txCallback)
             .finally(() => this.release(conn)));
     }
@@ -179,6 +206,58 @@ export class Pool {
             return conn.query(templates, ...args);
         });
     }
+    /**
+     * 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' } });
+     *
+     * @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
+     * }
+     */
+    stream(templates, ...args) {
+        this._checkClosed();
+        while (this._available.hasMore) {
+            const conn = this._available.shift;
+            if (!conn.isOpened) {
+                this._total--;
+                continue;
+            }
+            this._available.push(conn);
+            return conn.stream(templates, ...args);
+        }
+        let controller;
+        const stream = new ReadableStream({
+            start: c => {
+                controller = c;
+            }
+        });
+        this.acquire()
+            .tap(conn => {
+            this.release(conn);
+            conn['_streamWithController'](templates, args, controller);
+        })
+            .catch(err => {
+            controller.error(err);
+        });
+        return stream;
+    }
     /**
      * Sends an asynchronous notification to a channel via `pg_notify`.
      *
@@ -193,6 +272,38 @@ export class Pool {
     notify(channelName, payload = "") {
         return this.query `select pg_notify(${channelName}, ${payload})`;
     }
+    /**
+     * 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.
+     *
+     * @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.
+     */
+    listen(channel, callback) {
+        return this.acquire()
+            .andThen(conn => conn.listen(channel, callback)
+            .map(() => async () => {
+            await conn.unlisten(channel, callback);
+            this.release(conn);
+        }));
+    }
     /**
      * Number of available (idle) connections in the pool.
      */
@@ -222,7 +333,7 @@ export class Pool {
             this._available.shift.close();
         }
         while (this._waiting.hasMore) {
-            this._waiting.shift.reject(new Error('Pool closed'));
+            this._waiting.shift.reject(ErrPoolClosed);
         }
         this._total = 0;
     }

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

@@ -32,7 +32,10 @@ export declare class ConnectionResponseReader {
     private currentPacketLength;
     private constructor();
     static from(buffer: Buffer): ConnectionResponseReader;
-    readType(): ResponseType;
+    readType(): {
+        type: ResponseType;
+        length: number;
+    };
     readAuthentication(): AuthenticationCode;
     readMD5Salt(): Buffer<ArrayBufferLike>;
     readParameterStatus(): {
@@ -46,7 +49,7 @@ export declare class ConnectionResponseReader {
     readErrorResponse(): PostgresError;
     readReadyForQuery(): TransactionStatus;
     readSaslMechanisms(): string[];
-    readSaslMessage(): string;
+    readSaslMessage(length: number): string;
     readRowDescription(): ColumnDescription[];
     readDataRow(descriptions: ColumnDescription[], int8toBigint?: boolean): Record<string, any>;
     readNotificationResponse(): {

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,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAM3C,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,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,IAAI,MAAM;IAMrB,aAAa,CAAC,MAAM,EAAE,MAAM;CAW/B;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,CAAC,YAAY,EAAE,iBAAiB,EAAE,EAAE,YAAY,GAAE,OAAe,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IA8FlG,wBAAwB;;;;IAUxB,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,EAA6B,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC5G,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAM3C,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,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,IAAI,MAAM;IAMrB,aAAa,CAAC,MAAM,EAAE,MAAM;CAW/B;AAGD,qBAAa,wBAAwB;IAI7B,OAAO,CAAC,MAAM;IAHlB,OAAO,CAAC,mBAAmB,CAAK;IAEhC,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,GAAE,OAAe,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IA6FlG,wBAAwB;;;;IASxB,mBAAmB,IAAI,MAAM;IAK7B,OAAO;IAKP,aAAa;IAKb,iBAAiB;IAKjB,iBAAiB;IAGjB,gBAAgB;IAGhB,wBAAwB;IAOxB,UAAU;CACb"}

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

@@ -123,31 +123,27 @@ export class ConnectionResponseReader {
         return new ConnectionResponseReader(ConnectionResponseBuffer.from(buffer));
     }
     readType() {
-        return this.buffer.readChar();
+        return { type: this.buffer.readChar(), length: this.buffer.readInt32() };
     }
     readAuthentication() {
-        this.currentPacketLength = this.buffer.readInt32();
         return this.buffer.readInt32();
     }
     readMD5Salt() {
         return this.buffer.readBytes(4);
     }
     readParameterStatus() {
-        this.buffer.readInt32();
         return {
             name: this.buffer.readCString(),
             value: this.buffer.readCString()
         };
     }
     readBackendKeyData() {
-        this.buffer.readInt32();
         return {
             PID: this.buffer.readInt32(),
             secret: this.buffer.readInt32()
         };
     }
     readErrorResponse() {
-        this.buffer.readInt32();
         let severity = '';
         let code = '';
         let message = '';
@@ -195,7 +191,6 @@ export class ConnectionResponseReader {
         return new PostgresError(message, code, detail, severity, where, hint, position, dataType, constraint);
     }
     readReadyForQuery() {
-        this.buffer.readInt32();
         return this.buffer.readChar();
     }
     readSaslMechanisms() {
@@ -208,12 +203,10 @@ export class ConnectionResponseReader {
         }
         return mechanisms;
     }
-    readSaslMessage() {
-        const dataLength = this.currentPacketLength - 4 - 4;
-        return this.buffer.readRawString(dataLength);
+    readSaslMessage(length) {
+        return this.buffer.readRawString(length - 4 - 4);
     }
     readRowDescription() {
-        this.buffer.skipBytes(4);
         const columnsCount = this.buffer.readInt16();
         const columns = new Array(columnsCount);
         for (let i = 0; i < columnsCount; i++) {
@@ -230,7 +223,6 @@ export class ConnectionResponseReader {
         return columns;
     }
     readDataRow(descriptions, int8toBigint = false) {
-        this.buffer.skipBytes(4);
         const fieldsCount = this.buffer.readInt16();
         const row = {};
         for (let i = 0; i < fieldsCount; i++) {
@@ -311,14 +303,12 @@ export class ConnectionResponseReader {
         return row;
     }
     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();
     }
     hasMore() {
@@ -330,20 +320,13 @@ export class ConnectionResponseReader {
     getResidualBuffer() {
         return this.buffer.getResidualBuffer();
     }
-    readParseComplete() {
-        this.buffer.readInt32();
-    }
-    readBindComplete() {
-        this.buffer.readInt32();
-    }
+    readParseComplete() { }
+    readBindComplete() { }
     readParameterDescription() {
-        this.buffer.readInt32();
         const count = this.buffer.readInt16();
         for (let i = 0; i < count; i++) {
             this.buffer.readInt32();
         }
     }
-    readNoData() {
-        this.buffer.readInt32();
-    }
+    readNoData() { }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"socket-authorization.d.ts","sourceRoot":"","sources":["../../src/protocol/socket-authorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,MAAM,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAA;AAKrE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAGtC,MAAM,MAAM,mBAAmB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAGD,eAAO,MAAM,gBAAgB,eAAmF,CAAA;AAChH,eAAO,MAAM,mBAAmB,eAAqE,CAAA;AAIrG,eAAO,MAAM,sBAAsB,GAAI,QAAQ,uBAAuB,EAAE,QAAQ,mBAAmB,kCAwHlG,CAAA"}
+{"version":3,"file":"socket-authorization.d.ts","sourceRoot":"","sources":["../../src/protocol/socket-authorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,MAAM,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAA;AAKrE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAGtC,MAAM,MAAM,mBAAmB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAGD,eAAO,MAAM,gBAAgB,eAAmF,CAAA;AAChH,eAAO,MAAM,mBAAmB,eAAqE,CAAA;AAIrG,eAAO,MAAM,sBAAsB,GAAI,QAAQ,uBAAuB,EAAE,QAAQ,mBAAmB,kCAyHlG,CAAA"}

package/dist/protocol/socket-authorization.js

@@ -13,7 +13,7 @@ export const createAuthorizedSocket = (writer, params) => {
         let clientMessage = '';
         let serverMessage = '';
         const socket = createConnection({ host: params.host, port: params.port });
-        const connector = new SocketConnector(socket, (type, reader) => {
+        const connector = new SocketConnector(socket, (type, length, reader) => {
             writer.clear();
             switch (type) {
                 case ResponseTypes.Authentication: {
@@ -42,7 +42,7 @@ export const createAuthorizedSocket = (writer, params) => {
                             break;
                         }
                         case AuthenticationCodes.SASLContinue: {
-                            serverMessage = reader.readSaslMessage();
+                            serverMessage = reader.readSaslMessage(length);
                             if (!params.password)
                                 throw ErrPasswordRequired;
                             const parts = Object.fromEntries(serverMessage.split(',').map(x => x.split('=')));
@@ -61,7 +61,7 @@ export const createAuthorizedSocket = (writer, params) => {
                             break;
                         }
                         case AuthenticationCodes.SASLFinal: {
-                            reader.readSaslMessage();
+                            reader.readSaslMessage(length);
                             break;
                         }
                     }

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

@@ -8,7 +8,7 @@ export declare class SocketConnector {
     private _onError;
     private residualBuffer;
     private _isDestroyed;
-    constructor(_socket: Socket, _onData: (type: ResponseType, reader: ConnectionResponseReader) => void, _onError: (error: Error) => void);
+    constructor(_socket: Socket, _onData: (type: ResponseType, length: number, reader: ConnectionResponseReader) => void, _onError: (error: Error) => void);
     write(writer: ConnectionRequestWriter): void;
     unwrapSocket(): Socket;
     destroy(): void;

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;IA6B5C,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,MAAM,EAAE,MAAM,EAAE,wBAAwB,KAAK,IAAI,EACvF,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI;IA8B5C,KAAK,CAAC,MAAM,EAAE,uBAAuB;IAOrC,YAAY;IAQZ,OAAO;IAMP,IAAI,WAAW,YAA6B;CAC/C"}

package/dist/protocol/socket-connector.js

@@ -18,7 +18,8 @@ export class SocketConnector {
                     this.residualBuffer = reader.getResidualBuffer();
                     return;
                 }
-                this._onData(reader.readType(), reader);
+                const { type, length } = reader.readType();
+                this._onData(type, length, reader);
             }
         });
         _socket.on('error', error => {

package/dist/query.d.ts

@@ -1,5 +1,7 @@
+import { Future } from "fluent-future";
 import { QueryText, StatementName } from "./connection";
 import { ColumnDescription, ValueOF } from "./types";
+import { PostgresError } from "./error";
 export declare const QueryState: {
     readonly Parsing: 0;
     readonly Describing: 1;
@@ -14,14 +16,31 @@ export declare class Query<T> {
     state: State;
     statementName: StatementName;
     columns?: ColumnDescription[] | undefined;
-    promise: Promise<T[]>;
+    future: Future<T[], PostgresError>;
     private _resolve;
     private _reject;
     private _rows;
+    private _timer?;
     constructor(text: QueryText, args: (string | null)[], state: State, statementName: StatementName, columns?: ColumnDescription[] | undefined);
+    startTimeout(timeout: number): void;
     setState(state: State): void;
     push(value: T): void;
-    reject(cause: Error): void;
+    reject(cause: PostgresError): void;
+    resolve(): void;
+}
+export declare class StreamQuery<T> {
+    text: QueryText;
+    args: (string | null)[];
+    state: State;
+    statementName: StatementName;
+    private _controller;
+    columns?: ColumnDescription[] | undefined;
+    private _timer?;
+    constructor(text: QueryText, args: (string | null)[], state: State, statementName: StatementName, _controller: ReadableStreamDefaultController<T>, columns?: ColumnDescription[] | undefined);
+    setState(state: State): void;
+    startTimeout(timeout: number): void;
+    push(value: T): void;
+    reject(cause: PostgresError): void;
     resolve(): void;
 }
 //# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGrD,eAAO,MAAM,UAAU;;;;;;CAMb,CAAA;AAGV,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,UAAU,CAAC,CAAA;AAG9C,qBAAa,KAAK,CAAC,CAAC;IAOL,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE;IACvB,KAAK,EAAE,KAAK;IACZ,aAAa,EAAE,aAAa;IAC5B,OAAO,CAAC,EAAE,iBAAiB,EAAE;IAVxC,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;IACrB,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,KAAK,CAAU;gBAGZ,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,EACvB,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,aAAa,EAC5B,OAAO,CAAC,EAAE,iBAAiB,EAAE,YAAA;IASxC,QAAQ,CAAC,KAAK,EAAE,KAAK;IAKrB,IAAI,CAAC,KAAK,EAAE,CAAC;IAKb,MAAM,CAAC,KAAK,EAAE,KAAK;IAKnB,OAAO;CAGV"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,eAAO,MAAM,UAAU;;;;;;CAMb,CAAA;AAGV,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,UAAU,CAAC,CAAA;AAG9C,qBAAa,KAAK,CAAC,CAAC;IASL,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE;IACvB,KAAK,EAAE,KAAK;IACZ,aAAa,EAAE,aAAa;IAC5B,OAAO,CAAC,EAAE,iBAAiB,EAAE;IAZxC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,EAAE,aAAa,CAAC,CAAA;IAClC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,KAAK,CAAU;IAEvB,OAAO,CAAC,MAAM,CAAC,CAAgB;gBAGpB,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,EACvB,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,aAAa,EAC5B,OAAO,CAAC,EAAE,iBAAiB,EAAE,YAAA;IAQxC,YAAY,CAAC,OAAO,EAAE,MAAM;IAO5B,QAAQ,CAAC,KAAK,EAAE,KAAK;IAKrB,IAAI,CAAC,KAAK,EAAE,CAAC;IAKb,MAAM,CAAC,KAAK,EAAE,aAAa;IAM3B,OAAO;CAIV;AAED,qBAAa,WAAW,CAAC,CAAC;IAKX,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE;IACvB,KAAK,EAAE,KAAK;IACZ,aAAa,EAAE,aAAa;IACnC,OAAO,CAAC,WAAW;IACZ,OAAO,CAAC,EAAE,iBAAiB,EAAE;IARxC,OAAO,CAAC,MAAM,CAAC,CAAgB;gBAGpB,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,EACvB,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,aAAa,EAC3B,WAAW,EAAE,+BAA+B,CAAC,CAAC,CAAC,EAChD,OAAO,CAAC,EAAE,iBAAiB,EAAE,YAAA;IAGxC,QAAQ,CAAC,KAAK,EAAE,KAAK;IAIrB,YAAY,CAAC,OAAO,EAAE,MAAM;IAM5B,IAAI,CAAC,KAAK,EAAE,CAAC;IAIb,MAAM,CAAC,KAAK,EAAE,aAAa;IAK3B,OAAO;CAIV"}

package/dist/query.js

@@ -1,3 +1,5 @@
+import { Future } from "fluent-future";
+import { PostgresError } from "./error";
 export const QueryState = {
     Parsing: 0,
     Describing: 1,
@@ -13,10 +15,15 @@ export class Query {
         this.statementName = statementName;
         this.columns = columns;
         this._rows = [];
-        this.promise = new Promise((a, b) => {
-            this._resolve = a;
-            this._reject = b;
-        });
+        const { future, reject, resolve } = Future.withResolvers();
+        this.future = future;
+        this._resolve = resolve;
+        this._reject = reject;
+    }
+    startTimeout(timeout) {
+        this._timer = setTimeout(() => {
+            this.reject(new PostgresError('Query timeout', '57014'));
+        }, timeout);
     }
     setState(state) {
         this.state = state;
@@ -25,9 +32,40 @@ export class Query {
         this._rows.push(value);
     }
     reject(cause) {
+        clearTimeout(this._timer);
         this._reject(cause);
     }
     resolve() {
+        clearTimeout(this._timer);
         this._resolve(this._rows);
     }
 }
+export class StreamQuery {
+    constructor(text, args, state, statementName, _controller, columns) {
+        this.text = text;
+        this.args = args;
+        this.state = state;
+        this.statementName = statementName;
+        this._controller = _controller;
+        this.columns = columns;
+    }
+    setState(state) {
+        this.state = state;
+    }
+    startTimeout(timeout) {
+        this._timer = setTimeout(() => {
+            this.reject(new PostgresError('Query timeout', '57014'));
+        }, timeout);
+    }
+    push(value) {
+        this._controller.enqueue(value);
+    }
+    reject(cause) {
+        clearTimeout(this._timer);
+        this._controller.error(cause);
+    }
+    resolve() {
+        clearTimeout(this._timer);
+        this._controller.close();
+    }
+}

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@m2k-5f/pgtx",
-  "version": "2.4.1",
-  "type": "module",
-  "description": "Blazing-fast PostgreSQL driver with pipeline support.",
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build",
-    "testGitHub": "node --import tsx --test $(find tests -name '*.test.ts')",
-    "test": "node --import tsx --test ./tests/*.test.ts",
-    "benchmark": "npx tsx benchmark.ts"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/M2K-5F/pgtx.git"
-  },
-  "keywords": [
-    "sql",
-    "postgres",
-    "driver",
-    "pipeline",
-    "query-builder",
-    "typescript",
-    "transactions",
-    "prepared-statements"
-  ],
-  "author": "M2K-5F",
-  "license": "MIT",
-  "homepage": "https://github.com/M2K-5F/pgtx",
-  "bugs": {
-    "url": "https://github.com/M2K-5F/pgtx/issues"
-  },
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "devDependencies": {
-    "@types/node": "^26.1.1",
-    "mitata": "^1.0.34",
-    "pg": "^8.22.0",
-    "postgres": "^3.4.9",
-    "tsx": "^4.21.0",
-    "typescript": "^5.0.0"
-  },
-  "dependencies": {
-    "fluent-future": "^1.3.2"
-  }
-}
+{
+  "name": "@m2k-5f/pgtx",
+  "version": "2.5.0",
+  "type": "module",
+  "description": "Blazing-fast PostgreSQL driver with pipeline support.",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "testGitHub": "node --import tsx --test $(find tests -name '*.test.ts')",
+    "test": "node --import tsx --test ./tests/*.test.ts",
+    "benchmark": "npx tsx benchmark.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/M2K-5F/pgtx.git"
+  },
+  "keywords": [
+    "sql",
+    "postgres",
+    "driver",
+    "pipeline",
+    "query-builder",
+    "typescript",
+    "transactions",
+    "prepared-statements"
+  ],
+  "author": "M2K-5F",
+  "license": "MIT",
+  "homepage": "https://github.com/M2K-5F/pgtx",
+  "bugs": {
+    "url": "https://github.com/M2K-5F/pgtx/issues"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "mitata": "^1.0.34",
+    "pg": "^8.22.0",
+    "postgres": "^3.4.9",
+    "tsx": "^4.23.5",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "fluent-future": "^1.3.3"
+  }
+}