@m2k-5f/pgtx 2.4.0 → 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
@@ -270,7 +351,7 @@ export class Connection {
                 .writeBind("", query.statementName, query.args)
                 .writeExecute("");
         }
-        this._pipelinesQueue.get().push(query);
+        this._pipelinesQueue.last.push(query);
     }
     _registerFlush() {
         if (!this._isFlushing) {
@@ -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;
@@ -328,15 +409,14 @@ export class Connection {
         return Promise.all(promises);
     }
     _getCurrentQuery() {
-        return this._pipelinesQueue.get().get();
+        return this._pipelinesQueue.current.current;
     }
     _rejectPipeline(error) {
         if (this._pipelinesQueue.isFree)
             return;
-        const queue = this._pipelinesQueue.get();
+        const queue = this._pipelinesQueue.current;
         while (queue.hasMore) {
-            queue.get().reject(error);
-            queue.next();
+            queue.shift.reject(error);
         }
     }
     _handlePacket(type, reader) {
@@ -407,7 +487,7 @@ export class Connection {
                         break;
                     }
                     query.state = QueryState.Completed;
-                    this._pipelinesQueue.get().next();
+                    this._pipelinesQueue.current.next();
                     query.resolve();
                 }
                 break;
@@ -433,10 +513,7 @@ export class Connection {
             case ResponseTypes.ReadyForQuery:
                 {
                     reader.readReadyForQuery();
-                    const pipeline = this._pipelinesQueue.get();
-                    if (!pipeline.hasMore) {
-                        this._pipelinesQueue.next();
-                    }
+                    this._pipelinesQueue.next();
                 }
                 break;
             case ResponseTypes.Notice:

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;IA0BP;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU;IAoBxB;;;;;;;;;;;;;;;;;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;IAiCpF;;;;;;;;;;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;CAeR"}
+{"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"}