postgrejs 3.5.0 → 3.6.1

package/data-types/timestamptz-type.js

@@ -34,14 +34,13 @@ export const TimestamptzType = {
         buf.writeInt32BE(hi);
         buf.writeUInt32BE(lo);
     },
-    decodeBinary(v, offset = 0, _len, options) {
-        const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.timestamptz);
+    decodeBinary(v, offset = 0) {
         const hi = v.readInt32BE(offset);
         const lo = v.readUInt32BE(offset + 4);
         if (lo === 0xffffffff && hi === 0x7fffffff)
-            return fetchAsString ? 'infinity' : Infinity;
+            return Infinity;
         if (lo === 0x00000000 && hi === -0x80000000)
-            return fetchAsString ? '-infinity' : -Infinity;
+            return -Infinity;
         // Shift from 2000 to 1970. A timestamptz is an absolute instant, so
         // this is already the value - there is nothing to reinterpret against
         // the local zone the way `timestamp` (which carries no zone of its
@@ -51,23 +50,10 @@ export const TimestamptzType = {
         // ambiguous read as wall-clock, so the rebuild silently picked the
         // other one and moved the value an hour. The text path never did that,
         // so the same row decoded binary and text disagreed.
-        const d = new Date((lo + hi * timeMul) / 1000 + timeShift);
-        return fetchAsString ? dateToTimestamptzString(d) : d;
+        return new Date((lo + hi * timeMul) / 1000 + timeShift);
     },
     decodeText(v, options) {
-        const d = parseDateTimeTz(v, options.utcDates);
-        if (options.fetchAsString?.includes(DataTypeOIDs.timestamptz)) {
-            if (d instanceof Date)
-                return dateToTimestamptzString(d);
-            if (d === Infinity)
-                return 'infinity';
-            if (d === -Infinity)
-                return '-infinity';
-            // parseDateTimeTz() only ever returns a Date, Infinity or -Infinity,
-            // never anything else, so this is unreachable.
-            return '';
-        }
-        return d;
+        return parseDateTimeTz(v, options.utcDates);
     },
     // Reads PostgreSQL's own timestamp shape straight from the wire bytes.
     // Building the string first and handing it to decodeText() costs about
@@ -75,26 +61,16 @@ export const TimestamptzType = {
     // scanned a character at a time. Anything not in that exact shape
     // (infinity, a BC suffix, an LMT-style offset) has no Date to give back
     // and takes the original path, which still needs the string.
-    //
-    // Note this type's decodeText always parses first and only branches on
-    // fetchAsString afterward (unlike date/time/timestamp, which early-return
-    // the raw string), so the same order is kept here.
     decodeTextBuffer(buf, offset, len, options) {
         const d = parsePgTimestampBuffer(buf, offset, offset + len);
-        if (d !== undefined) {
-            return options.fetchAsString?.includes(DataTypeOIDs.timestamptz)
-                ? dateToTimestamptzString(d)
-                : d;
-        }
+        if (d !== undefined)
+            return d;
         return TimestamptzType.decodeText(buf.toString('latin1', offset, offset + len), options);
     },
     isType(v) {
         return v instanceof Date;
     },
 };
-function dateToTimestamptzString(d) {
-    return d.toISOString().replace('T', ' ');
-}
 export const ArrayTimestamptzType = {
     ...TimestamptzType,
     name: '_timestamptz',

package/index.d.ts

@@ -23,6 +23,7 @@ export * from './interfaces/query-result.js';
 export * from './interfaces/script-execute-options.js';
 export * from './interfaces/script-result.js';
 export * from './interfaces/statement-prepare-options.js';
+export * from './protocol/connection-lost-error.js';
 export * from './protocol/database-error.js';
 export * from './protocol/smart-buffer.js';
 export * from './types.js';

package/index.js

@@ -23,6 +23,7 @@ export * from './interfaces/query-result.js';
 export * from './interfaces/script-execute-options.js';
 export * from './interfaces/script-result.js';
 export * from './interfaces/statement-prepare-options.js';
+export * from './protocol/connection-lost-error.js';
 export * from './protocol/database-error.js';
 export * from './protocol/smart-buffer.js';
 export * from './types.js';

package/interfaces/batch-result.d.ts

@@ -8,7 +8,7 @@ import type { FieldInfo } from './field-info.js';
 export interface BatchCommandResult {
     /** The command tag PostgreSQL reported for this set (INSERT/UPDATE/...). */
     command?: string;
-    /** Rows affected, for INSERT/UPDATE/DELETE - as in QueryResult. */
+    /** Rows affected, for INSERT/UPDATE/DELETE/MERGE - as in QueryResult. */
     rowsAffected?: number;
     /**
      * Rows this set returned, decoded the same way `execute()` decodes them

package/interfaces/command-result.d.ts

@@ -24,7 +24,27 @@ export interface CommandResult {
      */
     executeTime?: number;
     /**
-     * How many rows affected
+     * True when the server stopped at the `fetchCount` limit instead of
+     * running the statement to completion: the portal suspended and the rows
+     * behind it were never fetched, so `rows` is a prefix rather than the
+     * whole result.
+     *
+     * Only ever set when an explicit `fetchCount` was given - the default
+     * asks for every row. Note the server does not look ahead: a statement
+     * whose result is exactly `fetchCount` rows long suspends too, so this
+     * means "the limit was reached", not "there are definitely more rows".
+     *
+     * Use a Cursor when the point is to read a large result in batches; a
+     * suspended portal on this path is simply discarded by the Sync that
+     * follows.
+     */
+    suspended?: boolean;
+    /**
+     * How many rows the statement changed, for INSERT/UPDATE/DELETE/MERGE
+     * (MERGE reports its own total of inserted, updated and deleted rows,
+     * and needs PostgreSQL 15+). Left undefined for every other command,
+     * including SELECT - the count those report describes rows returned or
+     * moved, not rows affected.
      */
     rowsAffected?: number;
 }

package/interfaces/data-mapping-options.d.ts

@@ -5,5 +5,21 @@ export interface DataMappingOptions {
      * @default false
      */
     utcDates?: boolean;
+    /**
+     * OIDs whose columns are to be handed back exactly as the server renders
+     * them, instead of being converted to a JavaScript value.
+     *
+     * This is a wire-level request, not a formatting choice made here: the
+     * listed columns are asked for in PostgreSQL's text format and returned
+     * unparsed, so the string is the server's own and nothing can drift
+     * between the two. Bind's result format codes are positional, though, so
+     * the OIDs can only be mapped onto columns once their types are known -
+     * a query whose statement is not prepared asks for the whole row as text
+     * instead (see IntlConnection.queryOnce()).
+     *
+     * An array column is selected by its own array OID (`_timestamptz`),
+     * never by its element's, and then the whole array literal is the string
+     * that comes back.
+     */
     fetchAsString?: OID[];
 }

package/interfaces/data-type.d.ts

@@ -7,6 +7,17 @@ export interface DataType {
     jsType: string;
     arraySeparator?: string;
     isType: (v: any) => boolean;
+    /**
+     * Whether DataTypeMap.determine() may pick this type for a value, which
+     * it does by asking `isType`. Defaults to true.
+     *
+     * `false` is for a type that can genuinely hold the value - so `isType`
+     * answers truthfully for anyone who asks it directly - but that no
+     * caller means when they pass a plain JavaScript value. Inference then
+     * passes it by and the type is reached only by asking for it, with
+     * `new BindParam(oid, value)`.
+     */
+    inferrable?: boolean;
     decodeBinary: DecodeBinaryFunction;
     decodeText: DecodeTextFunction;
     decodeTextBuffer?: DecodeTextBufferFunction;

package/interfaces/query-options.d.ts

@@ -37,7 +37,15 @@ export interface QueryOptions extends DataMappingOptions {
      */
     typeMap?: DataTypeMap;
     /**
-     * If true, returns Cursor instance instead of rows
+     * If true, returns Cursor instance instead of rows.
+     *
+     * The cursor reads through a portal, and a portal lives only as long as
+     * the transaction that created it. Outside an explicit transaction that
+     * is the implicit one, which any other statement on the same connection
+     * ends - so running another query on that connection while the cursor is
+     * open destroys it. Open the cursor inside a transaction, or give it a
+     * connection of its own; `Pool.query()` does the latter for you and
+     * keeps the connection out of the pool until the cursor closes.
      */
     cursor?: boolean;
     /**
@@ -50,8 +58,22 @@ export interface QueryOptions extends DataMappingOptions {
      */
     columnFormat?: DataFormat | DataFormat[];
     /**
-     * Specifies how many rows will be fetched. For Cursor, this value specifies how many rows will be fetched in a batch
-     * @default 100
+     * Maximum number of rows to fetch.
+     *
+     * `query()` fetches every row by default. Giving an explicit limit stops
+     * the server at that many rows and leaves the rest unfetched: `rows` is
+     * then a prefix and `suspended` is set on the result to say so. There is
+     * no way to ask for the remainder afterwards - the portal is discarded
+     * by the Sync that closes the call - so use a Cursor when the point is
+     * to read a large result a piece at a time.
+     *
+     * For a Cursor this is the batch size instead: how many rows each fetch
+     * asks for, defaulting to 100, with the cursor itself walking the whole
+     * result.
+     *
+     * 0 means unlimited, as it does in the protocol.
+     *
+     * @default 0 for query(), 100 for a Cursor's batches
      */
     fetchCount?: number;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.5.0",
+  "version": "3.6.1",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {

package/protocol/connection-lost-error.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A connection whose socket closed without anyone asking it to - the
+ * backend terminated by an administrator, a failover, a network fault.
+ *
+ * Reported on `Connection`'s `'close'` event as its reason, and for a
+ * pooled connection on `Pool`'s `'destroy'` (as the second argument) and
+ * `'error'`. `Pool` emits `'error'` for this and for a connection that
+ * could not be created in the first place, and those want different
+ * handling - this class is how a listener tells them apart:
+ *
+ * ```ts
+ * pool.on('error', err => {
+ *   if (err.code === '08006') log.warn('pooled connection lost', err.processID);
+ *   else log.error('could not open a connection', err);
+ * });
+ * ```
+ *
+ * `code` is there so that branching does not have to mean `instanceof`,
+ * which fails across duplicated copies of the package and is awkward from
+ * JavaScript. It reads the same way `DatabaseError.code` does - a
+ * SQLSTATE - and `08006 connection_failure` is the one this is. The server
+ * never sends it: it cannot report that its own connection went away, so
+ * there is no ambiguity about where a code of this value came from.
+ *
+ * The message deliberately says nothing else: it matches what other
+ * drivers report for the same event, so code that branches on it keeps
+ * working. What happened to *this* connection is on the object instead -
+ * `processID` names the backend, and `cause` carries the socket error
+ * when there was one (a clean FIN leaves none).
+ */
+export declare class ConnectionLostError extends Error {
+    /**
+     * SQLSTATE 08006, `connection_failure`. Synthesized here rather than
+     * received - see the class doc.
+     */
+    readonly code: string;
+    /** The backend's process id, as it was before the connection reset. */
+    readonly processID?: number;
+    constructor(processID?: number, cause?: unknown);
+}

package/protocol/connection-lost-error.js

@@ -0,0 +1,54 @@
+/**
+ * A connection whose socket closed without anyone asking it to - the
+ * backend terminated by an administrator, a failover, a network fault.
+ *
+ * Reported on `Connection`'s `'close'` event as its reason, and for a
+ * pooled connection on `Pool`'s `'destroy'` (as the second argument) and
+ * `'error'`. `Pool` emits `'error'` for this and for a connection that
+ * could not be created in the first place, and those want different
+ * handling - this class is how a listener tells them apart:
+ *
+ * ```ts
+ * pool.on('error', err => {
+ *   if (err.code === '08006') log.warn('pooled connection lost', err.processID);
+ *   else log.error('could not open a connection', err);
+ * });
+ * ```
+ *
+ * `code` is there so that branching does not have to mean `instanceof`,
+ * which fails across duplicated copies of the package and is awkward from
+ * JavaScript. It reads the same way `DatabaseError.code` does - a
+ * SQLSTATE - and `08006 connection_failure` is the one this is. The server
+ * never sends it: it cannot report that its own connection went away, so
+ * there is no ambiguity about where a code of this value came from.
+ *
+ * The message deliberately says nothing else: it matches what other
+ * drivers report for the same event, so code that branches on it keeps
+ * working. What happened to *this* connection is on the object instead -
+ * `processID` names the backend, and `cause` carries the socket error
+ * when there was one (a clean FIN leaves none).
+ */
+export class ConnectionLostError extends Error {
+    /**
+     * SQLSTATE 08006, `connection_failure`. Synthesized here rather than
+     * received - see the class doc.
+     */
+    code = '08006';
+    /** The backend's process id, as it was before the connection reset. */
+    processID;
+    constructor(processID, cause) {
+        super('Connection terminated unexpectedly');
+        this.name = 'ConnectionLostError';
+        this.processID = processID;
+        // Assigned rather than passed to the constructor, as abortError()
+        // does - same reason, the option is newer than this package's floor.
+        if (cause !== undefined) {
+            try {
+                this.cause = cause;
+            }
+            catch {
+                /* c8 ignore next */
+            }
+        }
+    }
+}

package/protocol/frontend.d.ts

@@ -20,6 +20,13 @@ export declare namespace Frontend {
         paramTypes?: Maybe<OID>[];
         params?: any[];
         queryOptions: QueryOptions;
+        /**
+         * Result format codes to write, overriding queryOptions.columnFormat.
+         * Set by callers that know the statement's column types and have
+         * turned fetchAsString's OID list into positional codes - see
+         * resolveColumnFormats().
+         */
+        columnFormat?: Protocol.DataFormat | Protocol.DataFormat[];
     }
     interface ParseMessageArgs {
         statement?: string;

package/protocol/frontend.js

@@ -133,9 +133,11 @@ export class Frontend {
         io.writeCString(args.portal || '', 'utf8');
         io.writeCString(args.statement || '', 'utf8');
         const { params, paramTypes, queryOptions } = args;
-        const columnFormat = queryOptions.columnFormat != null
-            ? queryOptions.columnFormat
-            : DEFAULT_COLUMN_FORMAT;
+        const columnFormat = args.columnFormat != null
+            ? args.columnFormat
+            : queryOptions.columnFormat != null
+                ? queryOptions.columnFormat
+                : DEFAULT_COLUMN_FORMAT;
         if (params && params.length) {
             io.writeInt16BE(params.length);
             const formatOffset = io.position;

package/protocol/pg-socket.d.ts

@@ -13,6 +13,12 @@ export interface SocketError extends Error {
 export declare class PgSocket extends SafeEventEmitter {
     options: ConnectionConfiguration;
     private _state;
+    /**
+     * The socket-level error that is about to end this connection, kept so
+     * the 'close' that follows can say what happened instead of arriving
+     * bare. Cleared by _reset().
+     */
+    private _closeReason?;
     private _socket?;
     private _backend;
     private _frontend;
@@ -282,6 +288,7 @@ export declare class PgSocket extends SafeEventEmitter {
     /** Accepts this server, or drops it and moves to the next candidate. */
     protected _applySessionAttrs(wanted: string, standby: boolean, readOnly: boolean): void;
     protected _handleClose(): void;
+    private _buildCloseReason;
     protected _handleError(err: unknown): void;
     /** Rejects and clears every still-open capture, e.g. on close/error. */
     private _failPendingCaptures;

package/protocol/pg-socket.js

@@ -8,6 +8,7 @@ import { ConnectionState } from '../constants.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { Backend } from './backend.js';
 import { signatureHashOfCertificate } from './cert-signature.js';
+import { ConnectionLostError } from './connection-lost-error.js';
 import { DatabaseError } from './database-error.js';
 import { Frontend } from './frontend.js';
 import { Protocol } from './protocol.js';
@@ -17,6 +18,12 @@ const COMMAND_RESULT_PATTERN = /^([^\d]+)(?: (\d+)(?: (\d+))?)?$/;
 export class PgSocket extends SafeEventEmitter {
     options;
     _state = ConnectionState.CLOSED;
+    /**
+     * The socket-level error that is about to end this connection, kept so
+     * the 'close' that follows can say what happened instead of arriving
+     * bare. Cleared by _reset().
+     */
+    _closeReason;
     _socket;
     _backend = new Backend();
     _frontend;
@@ -532,6 +539,7 @@ export class PgSocket extends SafeEventEmitter {
         this._socket.removeAllListeners('close');
     }
     _reset() {
+        this._closeReason = undefined;
         this._backend.reset();
         this._sessionParameters = {};
         this._processID = undefined;
@@ -627,14 +635,30 @@ export class PgSocket extends SafeEventEmitter {
         this._connectToHost();
     }
     _handleClose() {
+        // close() is the only thing that sets CLOSING, so anything else here
+        // is the far end going away on its own - an admin terminating the
+        // backend, a failover, a network fault. Built before _reset() clears
+        // the process id, which is the one detail that makes the report
+        // actionable, and carrying the socket error as its cause when there
+        // was one (a bare FIN leaves none).
+        const reason = this._state === ConnectionState.CLOSING
+            ? undefined
+            : this._buildCloseReason();
         this._failPendingCaptures(new Error('Connection closed'));
         this._reset();
         this._socket = undefined;
         this._state = ConnectionState.CLOSED;
-        this.emit('close');
+        this.emit('close', reason);
+    }
+    _buildCloseReason() {
+        return new ConnectionLostError(this._processID, this._closeReason);
     }
     _handleError(err) {
-        this._failPendingCaptures(err instanceof Error ? err : new Error(String(err)));
+        // Kept for the 'close' that follows: the socket reports the cause
+        // here and the fact of closing separately, and only the pair together
+        // says what actually happened.
+        this._closeReason = err instanceof Error ? err : new Error(String(err));
+        this._failPendingCaptures(this._closeReason);
         if (this._state !== ConnectionState.READY) {
             this._socket?.end();
         }

package/util/channel-name.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Checks a LISTEN/NOTIFY channel name and answers with the name the server
+ * will actually use for it.
+ *
+ * The name is written into LISTEN/UNLISTEN as an identifier, and an
+ * identifier can never be a parameter - so it goes through
+ * escapeIdentifier() at the call site rather than being restricted to a
+ * pattern. Any name PostgreSQL accepts then works, one-character and
+ * underscore-leading names included, which the old `/^[A-Z]\w+$/i` guard
+ * refused.
+ *
+ * Quoting alone would change what a name means, though, which is what this
+ * function is for: `LISTEN Foo` unquoted subscribes to `foo`, and every
+ * notification for it comes back as `foo`. Callers were registering their
+ * callback under the name they passed and never hearing from it - any
+ * channel name that was not already lower case was silently dead. Folding
+ * the same way the server would keeps the registration key and the name
+ * the server reports the same string, and keeps `NOTIFY Foo` written by
+ * hand on the other side reaching a `listen('Foo')` here.
+ *
+ * A name that could not have been written unquoted (a space, a dash) has
+ * no folding question to answer and is passed through as it is.
+ */
+export declare function normalizeChannelName(channel: string): string;

package/util/channel-name.js

@@ -0,0 +1,44 @@
+/**
+ * PostgreSQL folds an unquoted identifier to lower case and takes a quoted
+ * one literally. A LISTEN channel name is an identifier, so this is the
+ * shape that would have been folded had it been written unquoted.
+ */
+const UNQUOTED_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+/** NAMEDATALEN - 1. */
+const MAX_CHANNEL_BYTES = 63;
+/**
+ * Checks a LISTEN/NOTIFY channel name and answers with the name the server
+ * will actually use for it.
+ *
+ * The name is written into LISTEN/UNLISTEN as an identifier, and an
+ * identifier can never be a parameter - so it goes through
+ * escapeIdentifier() at the call site rather than being restricted to a
+ * pattern. Any name PostgreSQL accepts then works, one-character and
+ * underscore-leading names included, which the old `/^[A-Z]\w+$/i` guard
+ * refused.
+ *
+ * Quoting alone would change what a name means, though, which is what this
+ * function is for: `LISTEN Foo` unquoted subscribes to `foo`, and every
+ * notification for it comes back as `foo`. Callers were registering their
+ * callback under the name they passed and never hearing from it - any
+ * channel name that was not already lower case was silently dead. Folding
+ * the same way the server would keeps the registration key and the name
+ * the server reports the same string, and keeps `NOTIFY Foo` written by
+ * hand on the other side reaching a `listen('Foo')` here.
+ *
+ * A name that could not have been written unquoted (a space, a dash) has
+ * no folding question to answer and is passed through as it is.
+ */
+export function normalizeChannelName(channel) {
+    if (typeof channel !== 'string' || !channel.length)
+        throw new TypeError('Channel name must be a non-empty string');
+    if (channel.indexOf('\0') >= 0)
+        throw new TypeError('Channel name cannot contain NUL (\\0) bytes');
+    // Refused rather than passed on: the server truncates a longer
+    // identifier instead of rejecting it, so LISTEN would subscribe to a
+    // name the caller never asked for and every notification would arrive
+    // under that one - the same silent mismatch as the case folding above.
+    if (Buffer.byteLength(channel, 'utf8') > MAX_CHANNEL_BYTES)
+        throw new TypeError(`Channel name cannot be longer than ${MAX_CHANNEL_BYTES} bytes`);
+    return UNQUOTED_IDENTIFIER.test(channel) ? channel.toLowerCase() : channel;
+}

package/util/get-parsers.d.ts

@@ -1,4 +1,5 @@
 import type { DataTypeMap } from '../data-type-map.js';
+import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { Protocol } from '../protocol/protocol.js';
 import type { AnyParseFunction } from '../types.js';
-export declare function getParsers(typeMap: DataTypeMap, fields: Protocol.RowDescription[]): AnyParseFunction[];
+export declare function getParsers(typeMap: DataTypeMap, fields: Protocol.RowDescription[], mappingOptions?: DataMappingOptions): AnyParseFunction[];

package/util/get-parsers.js

@@ -3,13 +3,28 @@ import { decodeBinaryArray } from './decode-binaryarray.js';
 import { parsePostgresArray } from './parse-array.js';
 const DefaultColumnParser = (data, offset, len) => data.subarray(offset, offset + len);
 const DefaultTextColumnParser = (data, offset, len) => data.toString('utf8', offset, offset + len);
-export function getParsers(typeMap, fields) {
+export function getParsers(typeMap, fields, mappingOptions) {
     const parsers = new Array(fields.length);
+    const asString = mappingOptions?.fetchAsString;
     const l = fields.length;
     let f;
     let i;
     for (i = 0; i < l; i++) {
         f = fields[i];
+        // fetchAsString asks for the value exactly as the server renders it,
+        // and resolveColumnFormats() has already asked the server to send this
+        // column as text - so there is nothing left to do but hand the bytes
+        // back. An array column only reaches here when its own array OID was
+        // listed, and then the whole literal is the string that comes back.
+        // The format check is not redundant: a column can still arrive binary
+        // when its types were unknown at Bind time (a pipelined one-shot), and
+        // then the registered decoder is the only thing that can read it.
+        if (asString &&
+            f.format === DataFormat.text &&
+            asString.includes(f.dataTypeId)) {
+            parsers[i] = DefaultTextColumnParser;
+            continue;
+        }
         const dataTypeReg = typeMap.get(f.dataTypeId);
         if (dataTypeReg) {
             const isArray = !!dataTypeReg.elementsOID;

package/util/resolve-column-formats.d.ts

@@ -0,0 +1,33 @@
+import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
+import { Protocol } from '../protocol/protocol.js';
+import type { Maybe, OID } from '../types.js';
+export interface ColumnFormatOptions extends DataMappingOptions {
+    columnFormat?: Protocol.DataFormat | Protocol.DataFormat[];
+}
+/**
+ * Turns `fetchAsString`'s OID list into the positional result format codes
+ * a Bind message actually carries.
+ *
+ * The protocol has no way to say "send this OID as text" - Bind's result
+ * format codes are per column, by position, and nothing in Parse/Bind is
+ * keyed on a type. So the OID list can only be honored once the column
+ * types are known, which means after a Describe and before the Bind that
+ * asks for them. Callers that already hold a RowDescription (a prepared
+ * statement's, or a cached one's) pay nothing for this; callers that do
+ * not have to ask for the whole row as text instead - see queryOnce().
+ *
+ * A column matches on its own `dataTypeId`, so an array column is only
+ * ever selected by its own array OID (`_timestamptz`), never by its
+ * element's. Listing the element OID leaves array columns alone.
+ *
+ * Returns `columnFormat` untouched when there is nothing to do, so the
+ * common case allocates nothing and keeps sending a single format code.
+ */
+export declare function resolveColumnFormats(fields: Maybe<Protocol.RowDescription[]>, options: ColumnFormatOptions): Protocol.DataFormat | Protocol.DataFormat[];
+/**
+ * Whether two `fetchAsString` lists select the same columns. Used to tell
+ * a cached set of parsers apart from one built for a different list, which
+ * `columnFormat` alone cannot do: an explicitly text column and one turned
+ * text by fetchAsString carry the same format code but decode differently.
+ */
+export declare function fetchAsStringEqual(a: Maybe<OID[]>, b: Maybe<OID[]>): boolean;

package/util/resolve-column-formats.js

@@ -0,0 +1,67 @@
+import { DEFAULT_COLUMN_FORMAT } from '../constants.js';
+import { Protocol } from '../protocol/protocol.js';
+const DataFormat = Protocol.DataFormat;
+/**
+ * Turns `fetchAsString`'s OID list into the positional result format codes
+ * a Bind message actually carries.
+ *
+ * The protocol has no way to say "send this OID as text" - Bind's result
+ * format codes are per column, by position, and nothing in Parse/Bind is
+ * keyed on a type. So the OID list can only be honored once the column
+ * types are known, which means after a Describe and before the Bind that
+ * asks for them. Callers that already hold a RowDescription (a prepared
+ * statement's, or a cached one's) pay nothing for this; callers that do
+ * not have to ask for the whole row as text instead - see queryOnce().
+ *
+ * A column matches on its own `dataTypeId`, so an array column is only
+ * ever selected by its own array OID (`_timestamptz`), never by its
+ * element's. Listing the element OID leaves array columns alone.
+ *
+ * Returns `columnFormat` untouched when there is nothing to do, so the
+ * common case allocates nothing and keeps sending a single format code.
+ */
+export function resolveColumnFormats(fields, options) {
+    const base = options.columnFormat != null ? options.columnFormat : DEFAULT_COLUMN_FORMAT;
+    const asString = options.fetchAsString;
+    if (!fields || !asString || !asString.length)
+        return base;
+    const l = fields.length;
+    const baseIsArray = Array.isArray(base);
+    const out = new Array(l);
+    let hit = false;
+    let i;
+    for (i = 0; i < l; i++) {
+        if (asString.includes(fields[i].dataTypeId)) {
+            // fetchAsString names the value the caller wants verbatim, so it
+            // overrides an explicit columnFormat for its own columns - the two
+            // cannot both be honored and the OID list is the more specific ask.
+            out[i] = DataFormat.text;
+            hit = true;
+        }
+        else
+            out[i] = baseIsArray
+                ? (base[i] ?? DEFAULT_COLUMN_FORMAT)
+                : base;
+    }
+    return hit ? out : base;
+}
+/**
+ * Whether two `fetchAsString` lists select the same columns. Used to tell
+ * a cached set of parsers apart from one built for a different list, which
+ * `columnFormat` alone cannot do: an explicitly text column and one turned
+ * text by fetchAsString carry the same format code but decode differently.
+ */
+export function fetchAsStringEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return !a?.length && !b?.length;
+    const l = a.length;
+    if (l !== b.length)
+        return false;
+    let i;
+    for (i = 0; i < l; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}

package/util/wrap-row-description.d.ts

@@ -1,5 +1,6 @@
 import { DataFormat } from '../constants.js';
 import type { DataTypeMap } from '../data-type-map.js';
+import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { FieldInfo } from '../interfaces/field-info.js';
 import type { Protocol } from '../protocol/protocol.js';
-export declare function wrapRowDescription(typeMap: DataTypeMap, fields: Protocol.RowDescription[], columnFormat: DataFormat | DataFormat[]): FieldInfo[];
+export declare function wrapRowDescription(typeMap: DataTypeMap, fields: Protocol.RowDescription[], columnFormat: DataFormat | DataFormat[], mappingOptions?: DataMappingOptions): FieldInfo[];