postgrejs 3.12.0 → 3.12.1

package/connection/cursor.js

@@ -1,7 +1,38 @@
+import { updateErrorMessage } from '@jsopen/objects';
 import DoublyLinked from 'doublylinked';
 import { TaskQueue } from 'power-tasks';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
-import { resolveRowDecoder, resolveRowType } from '../util/row-decoder.js';
+import { dataRowBytes, resolveRowDecoder, resolveRowType, } from '../util/row-decoder.js';
+/**
+ * A result read a batch at a time instead of all at once.
+ *
+ * Returned by `Connection.query()`/`PreparedStatement.execute()` when
+ * `cursor: true` is passed, and backed by a server-side portal: rows are
+ * fetched `fetchCount` at a time (100 by default) as they are asked for,
+ * so a result larger than memory can be read through without ever
+ * holding it.
+ *
+ * The cursor closes itself when the rows run out, and `for await`
+ * closes it however the loop ends. Anything else - breaking out of a
+ * manual `next()` loop, an error in the middle - wants `close()`, or
+ * `await using`, which calls it.
+ *
+ * ```ts
+ * const result = await connection.query('select * from big_table', {
+ *   cursor: true,
+ *   fetchCount: 500,
+ * });
+ * for await (const row of result.cursor!) {
+ *   // one row at a time; 500 arrive per round trip
+ * }
+ * ```
+ *
+ * Emits `fetch` with each batch as it arrives, and `close` once.
+ */
+/* The portal lives inside the implicit transaction the statement opened,
+   so any other statement on the same connection ends it - see
+   _fetchRows() for what that looks like when it happens, and why the
+   error says more than the server's own does. */
 export class Cursor extends SafeEventEmitter {
     _statement;
     _portal;
@@ -11,6 +42,7 @@ export class Cursor extends SafeEventEmitter {
     _taskQueue = new TaskQueue({ concurrency: 1 });
     _rows = new DoublyLinked();
     _closed = false;
+    /** What the columns of every row this cursor returns are. */
     fields;
     constructor(statement, portal, fields, parsers, queryOptions) {
         super();
@@ -21,12 +53,29 @@ export class Cursor extends SafeEventEmitter {
         this.fields = fields;
         this._rowDecoder = resolveRowDecoder(queryOptions);
     }
+    /**
+     * The shape of the rows this cursor hands back - `'array'`,
+     * `'object'`, or `'custom'` when a `RowDecoder` of the caller's own is
+     * producing them.
+     */
     get rowType() {
         return resolveRowType(this._queryOptions);
     }
+    /**
+     * Whether the cursor is finished: the rows ran out, `close()` was
+     * called, or the portal was lost.
+     */
     get isClosed() {
         return this._closed;
     }
+    /**
+     * The next row, or `undefined` once there are none left.
+     *
+     * Fetches a batch from the server when the current one is used up, and
+     * closes the cursor when the server answers with nothing.
+     *
+     * @returns The next row, or `undefined` at the end.
+     */
     async next() {
         if (!this._rows.length) {
             if (this._closed)
@@ -35,6 +84,16 @@ export class Cursor extends SafeEventEmitter {
         }
         return this._rows.shift();
     }
+    /**
+     * Up to `nRows` rows, fetching as many batches as it takes.
+     *
+     * Shorter than asked for only at the end of the result, and empty once
+     * the cursor is closed - which is how the end is told apart from a
+     * batch boundary.
+     *
+     * @param nRows How many rows to read at most.
+     * @returns The rows read, in order.
+     */
     async fetch(nRows) {
         const out = [];
         if (this._closed)
@@ -50,6 +109,12 @@ export class Cursor extends SafeEventEmitter {
         }
         return out;
     }
+    /**
+     * Closes the cursor and releases the portal behind it.
+     *
+     * Idempotent, and called automatically when the rows run out or a
+     * `for await` loop ends. Emits `close`.
+     */
     async close() {
         if (this._closed)
             return;
@@ -59,10 +124,12 @@ export class Cursor extends SafeEventEmitter {
         this.emit('close');
         this._closed = true;
     }
+    /** Reads one batch from the portal and queues it up for the callers. */
+    /* Both callers (next()/fetch()) already gate on _closed with no await
+       in between, so the test below cannot currently observe a change -
+       kept as a backstop for this method's own contract rather than for
+       anything that reaches it today. */
     async _fetchRows() {
-        // Both callers (next()/fetch()) already gate on _closed with no await
-        // in between, so this can't currently observe a change - kept as a
-        // defensive backstop for this private method's own contract.
         if (this._closed)
             return;
         const portal = this._portal;
@@ -83,11 +150,11 @@ export class Cursor extends SafeEventEmitter {
                 // connection for this cursor (Pool.query()) have it back.
                 if (e?.code === '34000') {
                     await this.close().catch(() => undefined);
-                    e.message +=
+                    updateErrorMessage(e, e.message +
                         ' - the portal was destroyed by another statement running on' +
-                            ' the same connection, which ends the implicit transaction it' +
-                            ' lives in. Open the cursor inside an explicit transaction, or' +
-                            ' give it a connection of its own.';
+                        ' the same connection, which ends the implicit transaction it' +
+                        ' lives in. Open the cursor inside an explicit transaction, or' +
+                        ' give it a connection of its own.');
                 }
                 throw e;
             }
@@ -100,8 +167,10 @@ export class Cursor extends SafeEventEmitter {
                     const rowLen = rows.length;
                     let i;
                     for (i = 0; i < rowLen; i++) {
-                        const { data, columnCount } = rows[i];
-                        rows[i] = rowDecoder.decode(parsers, data, columnCount, this._queryOptions, fields);
+                        const raw = rows[i];
+                        rows[i] = rowDecoder.decodeAt
+                            ? rowDecoder.decodeAt(parsers, raw.buffer, raw.offset, raw.len, raw.columnCount, this._queryOptions, fields)
+                            : rowDecoder.decode(parsers, dataRowBytes(raw), raw.columnCount, this._queryOptions, fields);
                     }
                 }
                 this._rows.push(...rows);
@@ -114,12 +183,15 @@ export class Cursor extends SafeEventEmitter {
             .toPromise();
     }
     /**
-     * Iterates the remaining rows, fetching a batch at a time, and closes
-     * the cursor when the loop ends - whether it ran out of rows, broke
-     * early, or the body threw. Nothing is decoded ahead of what is asked
-     * for, so this streams a result larger than memory the same way next()
-     * does one row at a time.
+     * Iterates the remaining rows, a batch at a time, and closes the cursor
+     * when the loop ends - whether it ran out of rows, broke early, or the
+     * body threw.
+     *
+     * @returns An iterator over the rows left to read.
      */
+    /* Nothing is decoded ahead of what is asked for, so this streams a
+       result larger than memory the same way next() does one row at a
+       time. */
     async *[Symbol.asyncIterator]() {
         try {
             let row;
@@ -130,6 +202,7 @@ export class Cursor extends SafeEventEmitter {
             await this.close();
         }
     }
+    /** Closes the cursor, so `await using` can own one. */
     [Symbol.asyncDispose]() {
         return this.close();
     }

package/connection/intl-connection.d.ts

@@ -34,6 +34,14 @@ interface DeferredRows {
     parsers: AnyParseFunction[];
     fields: any;
 }
+/**
+ * The internals `Connection` and `Pool` are both built on.
+ *
+ * Holds the socket, the session's state, the prepared statement cache
+ * and the reference count that decides when a connection may go back to
+ * its pool. Not part of the public API: `Connection` is the handle a
+ * caller holds, and this is what it and the pool share underneath.
+ */
 export declare class IntlConnection extends SafeEventEmitter {
     /**
      * Server-side prepared statements this connection has built, keyed by
@@ -450,5 +458,11 @@ export declare class IntlConnection extends SafeEventEmitter {
     protected _currentTimeZone(): Maybe<string>;
     protected _currentDateStyle(): Maybe<PgDateStyle>;
 }
+/**
+ * The internals behind a `Connection`.
+ *
+ * @param connection The handle.
+ * @returns What it wraps.
+ */
 export declare function getIntlConnection(connection: Connection): IntlConnection;
 export {};

package/connection/intl-connection.js

@@ -15,7 +15,7 @@ import { escapeLiteral } from '../util/escape-literal.js';
 import { fetchAsStringEqual, fetchAsStringNamesElement, fetchAsStringNamesOid, validateFetchAsString, } from '../util/fetch-as-string.js';
 import { getParsers } from '../util/get-parsers.js';
 import { resolveColumnFormats } from '../util/resolve-column-formats.js';
-import { resolveRowDecoder, resolveRowType, } from '../util/row-decoder.js';
+import { dataRowBytes, resolveRowDecoder, resolveRowType, } from '../util/row-decoder.js';
 import { requireTimeZone } from '../util/temporal.js';
 import { isTransactionCommand, refusesSavepoint, } from '../util/transaction-command.js';
 import { wrapRowDescription } from '../util/wrap-row-description.js';
@@ -165,6 +165,14 @@ const EMPTY_QUERY_TAG = { command: '' };
 function preparedCacheKey(sql, paramTypes) {
     return paramTypes?.length ? sql + '\u0000' + paramTypes.join(',') : sql;
 }
+/**
+ * The internals `Connection` and `Pool` are both built on.
+ *
+ * Holds the socket, the session's state, the prepared statement cache
+ * and the reference count that decides when a connection may go back to
+ * its pool. Not part of the public API: `Connection` is the handle a
+ * caller holds, and this is what it and the pool share underneath.
+ */
 export class IntlConnection extends SafeEventEmitter {
     /**
      * Server-side prepared statements this connection has built, keyed by
@@ -851,7 +859,7 @@ export class IntlConnection extends SafeEventEmitter {
                                 currentDeferred.raw.push(msg);
                                 break;
                             }
-                            const row = rowDecoder.decode(parsers, msg.data, msg.columnCount, options, current.fields);
+                            const row = rowDecoder.decode(parsers, dataRowBytes(msg), msg.columnCount, options, current.fields);
                             if (cb)
                                 cb('row', row);
                             current.rows = current.rows || [];
@@ -1111,6 +1119,7 @@ export class IntlConnection extends SafeEventEmitter {
             const startTime = timingEnabled ? performance.now() : 0;
             const result = { command: undefined };
             const rows = [];
+            let streaming = false;
             let parsers;
             let resultFields;
             let commandTag;
@@ -1173,9 +1182,45 @@ export class IntlConnection extends SafeEventEmitter {
                         resultFields = wrapRowDescription(typeMap, msg.fields, columnFormat, options);
                         result.fields = resultFields;
                         result.rowType = resolveRowType(options);
+                        // Everything a row needs to be read is now in hand, so it
+                        // can be read as it arrives rather than set aside - unless
+                        // something still has to be asked first, which is the one
+                        // case below.
+                        streaming = !this.needsMoneyFormat(resultFields, options);
                         break;
                     case Protocol.BackendMessageCode.DataRow:
-                        rows.push(msg);
+                        // Decoded here rather than collected and walked again
+                        // afterwards. Collecting costs a `{ columnCount, data }`
+                        // and its buffer view per row, alive until the second pass
+                        // reaches them - so a result holds every row twice at its
+                        // peak, once raw and once read. Measured against `pg` on
+                        // 5000 rows of one float8 column, that was 166 bytes a row
+                        // between the two clients and is 109 now; by six columns
+                        // the difference was already the other way and stays
+                        // there. Timings do not move either way.
+                        //
+                        // `parsers` and `resultFields` are set together with
+                        // `streaming` above, so they are here whenever it is true.
+                        if (streaming && parsers && resultFields) {
+                            try {
+                                rows.push(rowDecoder.decodeAt
+                                    ? rowDecoder.decodeAt(parsers, msg.buffer, msg.offset, msg.len, msg.columnCount, options, resultFields)
+                                    : rowDecoder.decode(parsers, dataRowBytes(msg), msg.columnCount, options, resultFields));
+                            }
+                            catch (e) {
+                                // A decoder of the caller's own can throw. Recorded
+                                // like a server error and reported at ReadyForQuery,
+                                // so the rest of the response is still drained; the
+                                // call then rejects before the pass below could run
+                                // over a row already read, which is why `rows` can
+                                // never end up holding a mixture.
+                                if (!error)
+                                    error = e;
+                                streaming = false;
+                            }
+                        }
+                        else
+                            rows.push(msg);
                         break;
                     // An empty statement - '' or nothing but a comment - answers
                     // with this *instead of* a CommandComplete, so it has to take
@@ -1215,10 +1260,15 @@ export class IntlConnection extends SafeEventEmitter {
                 if (!result.command)
                     result.command = 'SELECT';
                 result.rows = rows;
-                const l = rows.length;
-                let i;
-                for (i = 0; i < l; i++) {
-                    rows[i] = rowDecoder.decode(parsers, rows[i].data, rows[i].columnCount, options, resultFields);
+                // Only what the loop above set aside: with `streaming` the rows
+                // are already read, and re-reading one would be reading a value
+                // rather than a row.
+                if (!streaming) {
+                    const l = rows.length;
+                    let i;
+                    for (i = 0; i < l; i++) {
+                        rows[i] = rowDecoder.decode(parsers, dataRowBytes(rows[i]), rows[i].columnCount, options, resultFields);
+                    }
                 }
             }
             if (suspended)
@@ -1497,7 +1547,7 @@ export class IntlConnection extends SafeEventEmitter {
                                     const l = rows.length;
                                     let i;
                                     for (i = 0; i < l; i++) {
-                                        rows[i] = rowDecoder.decode(parsers, rows[i].data, rows[i].columnCount, options, resultFields);
+                                        rows[i] = rowDecoder.decode(parsers, dataRowBytes(rows[i]), rows[i].columnCount, options, resultFields);
                                     }
                                     result.rows = rows;
                                 }
@@ -1630,7 +1680,7 @@ export class IntlConnection extends SafeEventEmitter {
                             const l = pendingRows.length;
                             let i;
                             for (i = 0; i < l; i++) {
-                                pendingRows[i] = rowDecoder.decode(parsers, pendingRows[i].data, pendingRows[i].columnCount, options, resultFields);
+                                pendingRows[i] = rowDecoder.decode(parsers, dataRowBytes(pendingRows[i]), pendingRows[i].columnCount, options, resultFields);
                             }
                             item.rows = pendingRows;
                             if (!item.command)
@@ -1694,6 +1744,7 @@ export class IntlConnection extends SafeEventEmitter {
             let commandTag;
             let error;
             let suspended = false;
+            let streaming = false;
             const rowDecoder = resolveRowDecoder(options);
             // The whole point of reusing a prepared statement here: its
             // RowDescription is already in hand, so fetchAsString's OID list can
@@ -1706,6 +1757,11 @@ export class IntlConnection extends SafeEventEmitter {
                 resultFields = resolved.resultFields;
                 result.fields = resultFields;
                 result.rowType = resolveRowType(options);
+                // See queryOnce() for what this decides and what it costs. The
+                // answer is known before the first row here rather than at the
+                // RowDescription, since the statement's fields were already in
+                // hand.
+                streaming = !this.needsMoneyFormat(resultFields, options);
             }
             // The SAVEPOINT/RELEASE pair rollbackOnError needs travels with the
             // statement instead of costing a round trip each - see
@@ -1740,7 +1796,22 @@ export class IntlConnection extends SafeEventEmitter {
                         suspended = true;
                         break;
                     case Protocol.BackendMessageCode.DataRow:
-                        rows.push(msg);
+                        // Read as it arrives - see queryOnce(), including why a
+                        // decoder that throws here cannot leave a mixture behind.
+                        if (streaming) {
+                            try {
+                                rows.push(rowDecoder.decodeAt
+                                    ? rowDecoder.decodeAt(parsers, msg.buffer, msg.offset, msg.len, msg.columnCount, options, resultFields)
+                                    : rowDecoder.decode(parsers, dataRowBytes(msg), msg.columnCount, options, resultFields));
+                            }
+                            catch (e) {
+                                if (!error)
+                                    error = e;
+                                streaming = false;
+                            }
+                        }
+                        else
+                            rows.push(msg);
                         break;
                     // See queryOnce() for why an empty statement lands here.
                     case Protocol.BackendMessageCode.EmptyQueryResponse:
@@ -1780,10 +1851,13 @@ export class IntlConnection extends SafeEventEmitter {
                 if (!result.command)
                     result.command = 'SELECT';
                 result.rows = rows;
-                const l = rows.length;
-                let i;
-                for (i = 0; i < l; i++) {
-                    rows[i] = rowDecoder.decode(parsers, rows[i].data, rows[i].columnCount, options, resultFields);
+                // See queryOnce(): only the rows the loop set aside.
+                if (!streaming) {
+                    const l = rows.length;
+                    let i;
+                    for (i = 0; i < l; i++) {
+                        rows[i] = rowDecoder.decode(parsers, dataRowBytes(rows[i]), rows[i].columnCount, options, resultFields);
+                    }
                 }
             }
             if (suspended)
@@ -1860,7 +1934,7 @@ export class IntlConnection extends SafeEventEmitter {
             const l = d.raw.length;
             const out = new Array(l);
             for (k = 0; k < l; k++)
-                out[k] = rowDecoder.decode(d.parsers, d.raw[k].data, d.raw[k].columnCount, opts, d.fields);
+                out[k] = rowDecoder.decode(d.parsers, dataRowBytes(d.raw[k]), d.raw[k].columnCount, opts, d.fields);
             d.target.rows = out;
         }
         return opts;
@@ -1970,6 +2044,12 @@ export class IntlConnection extends SafeEventEmitter {
         return this._dateStyle;
     }
 }
+/**
+ * The internals behind a `Connection`.
+ *
+ * @param connection The handle.
+ * @returns What it wraps.
+ */
 export function getIntlConnection(connection) {
     return connection._intlCon;
 }

package/connection/large-object.d.ts

@@ -2,10 +2,14 @@ import { Readable, Writable } from 'node:stream';
 import type { Connection } from './connection.js';
 /** Open modes, as PostgreSQL's own INV_READ / INV_WRITE constants. */
 export declare const LargeObjectMode: {
+    /** Open for reading only. */
     readonly read: 262144;
+    /** Open for writing only. */
     readonly write: 131072;
+    /** Open for both. */
     readonly readWrite: 393216;
 };
+/** How a large object's `readable()`/`writable()` move their bytes. */
 export interface LargeObjectStreamOptions {
     /**
      * Bytes per round trip (default 65536). Each chunk is its own `loread`
@@ -33,12 +37,26 @@ export interface LargeObjectStreamOptions {
  * the caller started, which stays theirs to finish.
  */
 export declare class LargeObject {
+    /**
+     * What this object is called, and the only way back to it: a large
+     * object belongs to no row, so the oid is what a caller stores.
+     */
     readonly oid: number;
     protected readonly _connection: Connection;
     protected readonly _fd: number;
     /** True when this object opened the transaction and so should commit it. */
     protected readonly _ownsTransaction: boolean;
     protected _closed: boolean;
+    /**
+     * Built by `Connection.createLargeObject()`/`openLargeObject()`, which
+     * are what open the descriptor this wraps.
+     *
+     * @param connection The connection the descriptor lives on.
+     * @param oid The large object's own identifier.
+     * @param fd The open descriptor, valid for this transaction only.
+     * @param ownsTransaction Whether opening it started the transaction,
+     * and so whether `close()` should commit.
+     */
     constructor(connection: Connection, oid: number, fd: number, ownsTransaction: boolean);
     /** Reads at most `length` bytes from the current position. */
     read(length: number): Promise<Buffer>;

package/connection/large-object.js

@@ -3,8 +3,11 @@ import { DataTypeOIDs } from '../constants.js';
 import { BindParam } from './bind-param.js';
 /** Open modes, as PostgreSQL's own INV_READ / INV_WRITE constants. */
 export const LargeObjectMode = {
+    /** Open for reading only. */
     read: 0x00040000,
+    /** Open for writing only. */
     write: 0x00020000,
+    /** Open for both. */
     readWrite: 0x00060000,
 };
 /**
@@ -26,12 +29,26 @@ export const LargeObjectMode = {
  * the caller started, which stays theirs to finish.
  */
 export class LargeObject {
+    /**
+     * What this object is called, and the only way back to it: a large
+     * object belongs to no row, so the oid is what a caller stores.
+     */
     oid;
     _connection;
     _fd;
     /** True when this object opened the transaction and so should commit it. */
     _ownsTransaction;
     _closed = false;
+    /**
+     * Built by `Connection.createLargeObject()`/`openLargeObject()`, which
+     * are what open the descriptor this wraps.
+     *
+     * @param connection The connection the descriptor lives on.
+     * @param oid The large object's own identifier.
+     * @param fd The open descriptor, valid for this transaction only.
+     * @param ownsTransaction Whether opening it started the transaction,
+     * and so whether `close()` should commit.
+     */
     constructor(connection, oid, fd, ownsTransaction) {
         this._connection = connection;
         this.oid = oid;

package/connection/logical-replication.d.ts

@@ -3,12 +3,17 @@ import type { CaptureCallback } from '../protocol/pg-socket.js';
 import { PgOutputDecoder, type PgOutputMessage, type PgOutputRelation, type TupleValues } from '../protocol/pgoutput.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { IntlConnection } from './intl-connection.js';
+/** What happened to a row, as the replication stream reports it. */
 export type ChangeCommand = 'insert' | 'update' | 'delete' | 'truncate';
+/** One row change, decoded from the `pgoutput` stream. */
 export interface Change {
+    /** Which of the four it was. */
     command: ChangeCommand;
     /** Schema-qualified, e.g. `public.users`. */
     table: string;
+    /** The schema on its own, for a caller who does not want it qualified. */
     schema: string;
+    /** The table's own description, as the stream declared it. */
     relation: PgOutputRelation;
     /** The row after the change; absent for delete and truncate. */
     row?: TupleValues;
@@ -23,6 +28,10 @@ export interface Change {
     /** Commit time of the transaction it belongs to. */
     timestamp?: Date;
 }
+/**
+ * How to subscribe: everything a connection takes, plus which
+ * publication to follow and which slot to follow it in.
+ */
 export interface LogicalReplicationOptions extends ConnectionConfiguration {
     /** Publication(s) to subscribe to; they must already exist on the server. */
     publication: string | string[];
@@ -69,6 +78,7 @@ export interface LogicalReplicationOptions extends ConnectionConfiguration {
  * caller has to remember to acknowledge anything.
  */
 export declare class LogicalReplication extends SafeEventEmitter {
+    /** What this subscription was built with. */
     readonly options: LogicalReplicationOptions;
     protected _intlCon?: IntlConnection;
     protected readonly _decoder: PgOutputDecoder;
@@ -84,6 +94,11 @@ export declare class LogicalReplication extends SafeEventEmitter {
     protected _pendingLsn: bigint;
     protected _commitTime?: Date;
     protected _streamDone?: Promise<any>;
+    /**
+     * @param options The publication to follow, the slot to follow it in,
+     * and how to reach the server.
+     * @throws TypeError When no publication is named.
+     */
     constructor(options: LogicalReplicationOptions);
     /** The slot this subscription is reading from. */
     get slot(): string;

package/connection/logical-replication.js

@@ -31,6 +31,7 @@ const DEFAULT_KEEPALIVE_MS = 10000;
  * caller has to remember to acknowledge anything.
  */
 export class LogicalReplication extends SafeEventEmitter {
+    /** What this subscription was built with. */
     options;
     _intlCon;
     _decoder = new PgOutputDecoder();
@@ -46,6 +47,11 @@ export class LogicalReplication extends SafeEventEmitter {
     _pendingLsn = 0n;
     _commitTime;
     _streamDone;
+    /**
+     * @param options The publication to follow, the slot to follow it in,
+     * and how to reach the server.
+     * @throws TypeError When no publication is named.
+     */
     constructor(options) {
         super();
         if (!options.publication)