@m2k-5f/pgtx 2.6.1 → 2.6.2

package/dist/batch.d.ts

@@ -5,10 +5,11 @@ export declare class Batch {
     private _queryQueue;
     private _buffer;
     constructor(buffer: ConnectionRequestWriter);
+    registerParse(query: PostgresQuery): void;
     registerQuery(query: PostgresQuery): void;
     end(): ConnectionRequestWriter;
     get current(): PostgresQuery;
     next(): void;
-    reject(cause: PostgresError): void;
+    reject(cause: PostgresError): number;
 }
 //# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAc,aAAa,EAAE,MAAM,SAAS,CAAC;AAGpD,qBAAa,KAAK;IACd,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,OAAO,CAAyB;gBAE5B,MAAM,EAAE,uBAAuB;IAK3C,aAAa,CAAC,KAAK,EAAE,aAAa;IAelC,GAAG;IAIH,IAAI,OAAO,kBAEV;IAED,IAAI;IAIJ,MAAM,CAAC,KAAK,EAAE,aAAa;CAK9B"}
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,qBAAa,KAAK;IACd,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,OAAO,CAAyB;gBAE5B,MAAM,EAAE,uBAAuB;IAM3C,aAAa,CAAC,KAAK,EAAE,aAAa;IAOlC,aAAa,CAAC,KAAK,EAAE,aAAa;IAQlC,GAAG;IAIH,IAAI,OAAO,kBAEV;IAED,IAAI;IAIJ,MAAM,CAAC,KAAK,EAAE,aAAa;CAS9B"}

package/dist/batch.js

@@ -1,18 +1,16 @@
-import { ParseQuery } from "./query";
 import { Queue } from "./queue";
 export class Batch {
     constructor(buffer) {
         this._queryQueue = new Queue();
         this._buffer = buffer;
     }
+    registerParse(query) {
+        this._buffer
+            .writeParse(query.statement, query.text)
+            .writeDescribe(query.statement);
+    }
     registerQuery(query) {
         this._queryQueue.push(query);
-        if (query instanceof ParseQuery) {
-            this._buffer
-                .writeParse(query.statement, query.text)
-                .writeDescribe(query.statement);
-            return;
-        }
         this._buffer
             .writeBind("", query.statement, query.args)
             .writeExecute("");
@@ -27,8 +25,11 @@ export class Batch {
         this._queryQueue.next();
     }
     reject(cause) {
+        let counter = 0;
         while (this._queryQueue.hasMore) {
+            counter++;
             this._queryQueue.shift.reject(cause);
         }
+        return counter;
     }
 }

package/dist/connection.d.ts

@@ -1,42 +1,23 @@
-import { ConnectionPartialConfig } from "./types";
+import { ConnectionPartialConfig, Row } from "./types";
 import { Transaction } from "./transaction";
 import { Future } from 'fluent-future';
 import { PostgresError } from "./error";
 /**
- * Represents a single dedicated connection to the PostgreSQL database.
- *
- * Supports:
- * - Tagged template queries with automatic parameter binding
- * - Prepared statements with caching
- * - Transaction management with savepoints
- * - Pipeline execution for concurrent queries
+ * A dedicated connection to PostgreSQL: tagged-template queries, prepared
+ * statement caching, transactions with savepoints, and pipelined execution.
  *
  * @example
- * ```ts
- * const conn = await Connection.new({
- *   host: 'localhost',
- *   user: 'postgres',
- *   password: 'postgres',
- *   database: 'test'
- * })
- *
- * // Simple query
+ * const conn = await Connection.new({ host: 'localhost', user: 'postgres', password: 'postgres', database: 'test' })
  * const users = await conn.query`SELECT * FROM users WHERE id = ${1}`
- *
- * // Transaction
- * await conn.begin(async tx => {
- *   await tx.query`INSERT INTO users ...`
- * })
- *
- * // Close connection
+ * await conn.begin(async tx => tx.query`INSERT INTO users ...`)
  * conn.close()
- * ```
  */
 export declare class Connection {
     private readonly config;
     private _activeBatch;
-    private _isOpened;
-    private _isReconnecting;
+    private _closing;
+    private _closed;
+    private _reconnecting;
     private _cachedBuffer;
     private _socket;
     private _batchQueue;
@@ -47,158 +28,66 @@ export declare class Connection {
     private _nextStatement;
     private constructor();
     /**
-     * Creates a new database connection.
-     *
-     * @param params - Connection parameters
-     * @returns A new Connection instance
-     * @throws {PostgresError} If authentication fails or connection cannot be established
-     *
-     * @example
-     * ```ts
-     * const conn = await Connection.new({
-     *   host: 'localhost',
-     *   port: 5432,
-     *   user: 'postgres',
-     *   password: 'secret',
-     *   database: 'myapp'
-     * })
-     * ```
+     * Opens a new connection and authenticates.
+     * @throws {PostgresError} if authentication fails or the connection can't be established
      */
     static new(config: ConnectionPartialConfig): Future<Connection, PostgresError>;
     private _registerBatch;
     private _sync;
     /**
-     * Executes a query using tagged template literals.
-     *
-     * Parameters are automatically bound to `$1, $2, ...` placeholders.
-     * Queries with parameters use prepared statements for performance.
-     *
-     * @param templates - Tagged template string with SQL
-     * @param args - Query parameters
-     * @returns Array of rows with proper typing
-     * @throws {Error} If connection is dead or query fails
+     * Runs a query, binding template values as `$1, $2, ...`.
+     * Parameterized queries are cached as prepared statements.
      *
      * @example
-     * ```ts
-     * // Simple query
-     * const users = await conn.query`SELECT * FROM users`
-     *
-     * // With parameters
-     * const user = await conn.query`SELECT * FROM users WHERE id = ${1}`
-     *
-     * // With typed result
-     * type User = { id: number, name: string }
-     * const users = await conn.query<User>`SELECT * FROM users`
-     * ```
+     * const users = await conn.query<User>`SELECT * FROM users WHERE id = ${1}`
      */
-    query<T extends Record<string, any>>(templates: TemplateStringsArray, ...params: any[]): Future<T[], PostgresError>;
+    query<T extends Row>(templates: TemplateStringsArray, ...params: any[]): Future<T[], PostgresError>;
+    private _performQuery;
     /**
-     * Starts a managed transaction on this connection.
-     *
-     * Automatically handles:
-     * - `BEGIN` before the callback
-     * - `COMMIT` on successful completion
-     * - `ROLLBACK` if an error is thrown
-     *
-     * @param txCallback - Async function that receives a `Transaction` instance
-     * @returns The value returned from the callback
-     * @throws {Error} If connection is dead or transaction fails
+     * Like {@link query}, but for statements that don't return rows (INSERT/UPDATE/DDL/etc).
      *
      * @example
-     * ```ts
-     * const result = await conn.begin(async tx => {
-     *   await tx.query`INSERT INTO accounts (id, balance) VALUES (1, 100)`
-     *   await tx.query`UPDATE accounts SET balance = balance - 10 WHERE id = 1`
-     *   return { success: true }
-     * })
-     * ```
+     * await conn.execute`UPDATE users SET name = ${name} WHERE id = ${id}`
      */
-    begin<T>(txCallback: (transaction: Transaction) => Promise<T>): Future<T, unknown>;
+    execute(templates: TemplateStringsArray, ...params: any[]): Future<void, PostgresError>;
+    private _performExecute;
     /**
-     * Sends an asynchronous notification to a channel via `pg_notify`.
-     *
-     * @param channelName - The channel identifier
-     * @param payload - Optional string data (max 8000 bytes)
+     * Runs `txCallback` inside `BEGIN`/`COMMIT`, rolling back on error.
      *
      * @example
-     * ```ts
-     * await conn.notify('events', 'hello')
-     * ```
+     * await conn.begin(async tx => {
+     *   await tx.query`UPDATE accounts SET balance = balance - 10 WHERE id = 1`
+     * })
      */
+    begin<T>(txCallback: (transaction: Transaction) => Promise<T>): Future<T, unknown>;
+    /** Sends a `pg_notify` message on `channelName` (payload ≤ 8000 bytes). */
     notify(channelName: string, payload?: string): Future<void, PostgresError>;
-    /**
-     * Subscribes a callback to a channel. Sends `LISTEN` on the first subscription.
-     *
-     * @param channelName - The channel identifier
-     * @param callback - Function invoked when a notification arrives
-     *
-     * @example
-     * ```ts
-     * await conn.listen('events', data => console.log(data))
-     * ```
-     */
+    /** Subscribes `callback` to `channelName`, issuing `LISTEN` on first subscription. */
     listen(channelName: string, callback: (payload: string) => void): Future<void, PostgresError>;
-    /**
-     * Unsubscribes a callback. Sends `UNLISTEN` if no callbacks remain for the channel.
-     *
-     * @param channelName - The channel identifier
-     * @param callback - The registered callback to remove
-     *
-     * @example
-     * ```ts
-     * await conn.unlisten('events', callback)
-     * ```
-     */
+    /** Unsubscribes `callback`, issuing `UNLISTEN` once no callbacks remain. */
     unlisten(channelName: string, callback: (payload: string) => void): Future<void, 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' } });
+     * Streams query results as a `ReadableStream`, without buffering rows in memory.
+     * Ideal for large result sets or piping straight into an HTTP response.
      *
      * @example
-     * // Asynchronously iterating over rows as they arrive from the wire socket
-     * const stream = conn.stream<User>`SELECT * FROM orders WHERE status = ${'processed'}`;
-     * for await (const row of stream) {
-     *     console.log(row.id, row.amount); // Row object is eligible for GC immediately after iteration
-     * }
+     * for await (const row of conn.stream<User>`SELECT * FROM orders`) { ... }
      */
-    stream<T extends Record<string, any>>(templates: TemplateStringsArray, ...params: any[]): ReadableStream<T>;
-    private _streamWithController;
-    private _registerReconnect;
-    private _resetConnectionState;
+    stream<T extends Row>(templates: TemplateStringsArray, ...params: any[]): ReadableStream<T>;
+    private _performStream;
     private _reconnect;
+    private _performReconnect;
     private _restoreSubscriptions;
     private _getCurrentQuery;
-    private _rejectAllBatches;
     private _handlePacket;
-    /**
-     * Checks if the connection is still alive and usable.
-     * Returns `false` if the socket is destroyed or connection is dead.
-     */
+    private get _hasQueries();
+    /** Whether the connection is alive and usable. */
     get isOpened(): boolean;
+    /** Whether the connection is closed or closing. */
+    get isClosed(): boolean;
     /**
-     * Closes the connection immediately.
-     * All pending queries will be rejected with an error.
-     * The connection cannot be used after this call.
-     *
-     * @example
-     * ```ts
-     * conn.close()
-     * ```
+     * Closes the connection, awaiting for all pending queries. Not usable afterward.
      */
-    close(): void;
+    close(): Future<void, PostgresError>;
 }
 //# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAMA,OAAO,EAA6D,uBAAuB,EAAuC,MAAM,SAAS,CAAA;AACjJ,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAK3C,OAAO,EAAS,MAAM,EAAM,MAAM,eAAe,CAAA;AACjD,OAAO,EAAkD,aAAa,EAAE,MAAM,SAAS,CAAA;AAKvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,SAAS,CAAO;IACxB,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,aAAa,CAAgC;IAErD,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,WAAW,CAA4B;IAE/C,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,QAAQ,CAAyD;IAEzE,OAAO,CAAC,mBAAmB,CAAyD;IACpF,OAAO,CAAC,YAAY,CAAI;IAGxB,OAAO,CAAC,cAAc;IAKtB,OAAO;IAYP;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,uBAAuB;IAe1C,OAAO,CAAC,cAAc;IAgBtB,OAAO,CAAC,KAAK;IA4Bb;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,aAAa,CAAC;IA2CnH;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC;IAoB7D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW;IAQhD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;IAgB/D;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC;IAqB/F;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IAqDvF,OAAO,CAAC,qBAAqB;IAoD7B,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,qBAAqB;YASf,UAAU;IAgBxB,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,aAAa;IAqHrB;;;OAGG;IACH,IAAI,QAAQ,YAEX;IAGD;;;;;;;;;OASG;IACH,KAAK;CAKR"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAMA,OAAO,EAAiC,uBAAuB,EAAmC,GAAG,EAAiB,MAAM,SAAS,CAAA;AACrI,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAK3C,OAAO,EAAS,MAAM,EAAM,MAAM,eAAe,CAAA;AACjD,OAAO,EAAkD,aAAa,EAAE,MAAM,SAAS,CAAA;AAavF;;;;;;;;;GASG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAsD;IACtE,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,aAAa,CAA2C;IAChE,OAAO,CAAC,aAAa,CAAgC;IAErD,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,WAAW,CAA4B;IAE/C,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,QAAQ,CAAsC;IAEtD,OAAO,CAAC,mBAAmB,CAAyD;IACpF,OAAO,CAAC,YAAY,CAAI;IAGxB,OAAO,CAAC,cAAc;IAKtB,OAAO;IAYP;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,uBAAuB;IAe1C,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,KAAK;IASb;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,SAAS,GAAG,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IAStE,OAAO,CAAC,aAAa;IA4CrB;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IASzD,OAAO,CAAC,eAAe;IAsCvB;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC;IAoB7D,2EAA2E;IAC3E,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW;IAOhD,sFAAsF;IACtF,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;IAe/D,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC;IAoB/F;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,SAAS,GAAG,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IAyBvE,OAAO,CAAC,cAAc;IA2CtB,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,iBAAiB;IA2BzB,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,aAAa;IA2HrB,OAAO,KAAK,WAAW,GAEtB;IAGD,kDAAkD;IAClD,IAAI,QAAQ,YAEX;IAGD,mDAAmD;IACnD,IAAI,QAAQ,YAEX;IAGD;;OAEG;IACH,KAAK;CAwBR"}