postgrejs 3.6.0 → 3.7.0

package/data-types/tsvector-type.d.ts

@@ -0,0 +1,5 @@
+import type { DataType } from '../interfaces/data-type.js';
+export declare const TsVectorType: DataType;
+export declare const ArrayTsVectorType: DataType;
+export declare const TsQueryType: DataType;
+export declare const ArrayTsQueryType: DataType;

package/data-types/tsvector-type.js

@@ -0,0 +1,216 @@
+import { DataTypeOIDs } from '../constants.js';
+/**
+ * `tsvector` and `tsquery` decode to the strings PostgreSQL prints -
+ * `'cat':1,3 'dog':2` and `'a' & !'b'` - and encode by handing a string
+ * straight back to the server. They share this file because they share
+ * that decision and half their quoting.
+ *
+ * **Why the text form.** It is the canonical spelling of both types: what
+ * the server accepts back, what the documentation is written in, and what
+ * someone inspecting an indexed document or a stored search wants to
+ * read. A structure of lexemes and positions, or a query tree, would be a
+ * second representation to convert to and from for values that are
+ * produced by `to_tsvector`/`to_tsquery` and consumed by a match
+ * operator, rather than walked. `pg` leaves both as strings.
+ *
+ * **Why no encodeBinary.** The server's own input parser is what defines
+ * these values. A `tsvector` literal is sorted and deduplicated on the
+ * way in, by a byte ordering and a position-merging rule that belong to
+ * the server; a `tsquery` literal is a small expression language, with
+ * operators that have been added across releases. Re-implementing either
+ * here would mean `'b a'::tsvector` or `'a<->b'::tsquery` quietly meaning
+ * one thing as a literal and another as a parameter, depending only on
+ * which column format the value travelled in. Handing the string over
+ * instead makes them the same by construction - the cost is that these
+ * two types cannot appear in a binary `COPY`, which `copyFrom` reports
+ * by name before it writes a row.
+ *
+ * Decoding is a different matter and is done here: the tree has already
+ * been built by the server, so reading it back is not parsing a grammar.
+ */
+/** The four weights, in the order the top two bits of a position hold. */
+const VECTOR_WEIGHTS = ['', 'C', 'B', 'A'];
+/** The weights a query value carries, as a bit each. */
+const QUERY_WEIGHTS = [
+    [8, 'A'],
+    [4, 'B'],
+    [2, 'C'],
+    [1, 'D'],
+];
+const POSITION_MASK = 0x3fff;
+const QI_VAL = 1;
+const OP_NOT = 1;
+const OP_AND = 2;
+const OP_OR = 3;
+const OP_PHRASE = 4;
+/**
+ * How tightly each operator binds, which is what decides where the
+ * server puts parentheses - and so where this has to put them too.
+ */
+const PRIORITY = {
+    [OP_NOT]: 4,
+    [OP_PHRASE]: 3,
+    [OP_AND]: 2,
+    [OP_OR]: 1,
+};
+/** A lexeme is printed quoted, with `'` doubled and `\` escaped. */
+function quote(lexeme) {
+    let out = "'";
+    const l = lexeme.length;
+    let i;
+    let c;
+    for (i = 0; i < l; i++) {
+        c = lexeme[i];
+        if (c === "'" || c === '\\')
+            out += c;
+        out += c;
+    }
+    return out + "'";
+}
+/**
+ * An int32 lexeme count, then for each: the lexeme as a NUL-terminated
+ * string, an int16 count of positions, and that many int16s holding the
+ * weight in the top two bits and the position in the low fourteen. A
+ * weight of D is the default and is not printed.
+ */
+function decodeVector(v, offset) {
+    const count = v.readInt32BE(offset);
+    let p = offset + 4;
+    let out = '';
+    let i;
+    let j;
+    let end;
+    let positions;
+    let entry;
+    for (i = 0; i < count; i++) {
+        end = v.indexOf(0, p);
+        if (i)
+            out += ' ';
+        out += quote(v.toString('utf8', p, end));
+        p = end + 1;
+        positions = v.readInt16BE(p);
+        p += 2;
+        for (j = 0; j < positions; j++) {
+            entry = v.readUInt16BE(p);
+            p += 2;
+            out +=
+                (j ? ',' : ':') + (entry & POSITION_MASK) + VECTOR_WEIGHTS[entry >> 14];
+        }
+    }
+    return out;
+}
+/**
+ * An int32 node count, then the nodes themselves: an operator before its
+ * operands, and its right operand before its left. A value node carries
+ * a weight bitmask, a prefix flag and a NUL-terminated lexeme; a phrase
+ * operator carries an int16 distance.
+ */
+function readQueryNode(v, pos) {
+    const type = v[pos.p++];
+    if (type === QI_VAL) {
+        const weights = v[pos.p++];
+        const prefix = !!v[pos.p++];
+        const end = v.indexOf(0, pos.p);
+        const lexeme = v.toString('utf8', pos.p, end);
+        pos.p = end + 1;
+        return { lexeme, weights, prefix };
+    }
+    const oper = v[pos.p++];
+    if (oper === OP_NOT)
+        return { oper, right: readQueryNode(v, pos) };
+    let distance = 0;
+    if (oper === OP_PHRASE) {
+        distance = v.readInt16BE(pos.p);
+        pos.p += 2;
+    }
+    // Right before left, which is the order they were written in.
+    const right = readQueryNode(v, pos);
+    const left = readQueryNode(v, pos);
+    return { oper, distance, left, right };
+}
+/**
+ * Prints the tree the way the server prints it, parentheses included.
+ * An operand is wrapped when it binds more loosely than what it sits
+ * under; the extra `rightPhraseOp` case is what keeps
+ * `'a' <-> ( 'b' <-> 'c' )` distinct from `'a' <-> 'b' <-> 'c'`, which
+ * are different queries.
+ */
+function printQuery(node, parentPriority, rightPhraseOp) {
+    if (node.oper === undefined) {
+        let out = quote(node.lexeme);
+        if (node.weights || node.prefix) {
+            // The star comes before the letters - `'d':*AB`, not `'d':AB*`.
+            out += ':';
+            if (node.prefix)
+                out += '*';
+            let w;
+            for (w of QUERY_WEIGHTS)
+                if (node.weights & w[0])
+                    out += w[1];
+        }
+        return out;
+    }
+    const priority = PRIORITY[node.oper];
+    if (node.oper === OP_NOT)
+        return '!' + printQuery(node.right, priority, false);
+    const op = node.oper === OP_AND
+        ? '&'
+        : node.oper === OP_OR
+            ? '|'
+            : node.distance === 1
+                ? '<->'
+                : '<' + node.distance + '>';
+    const out = printQuery(node.left, priority, false) +
+        ' ' +
+        op +
+        ' ' +
+        printQuery(node.right, priority, node.oper === OP_PHRASE);
+    return priority < parentPriority ||
+        (rightPhraseOp && priority === parentPriority)
+        ? '( ' + out + ' )'
+        : out;
+}
+export const TsVectorType = {
+    name: 'tsvector',
+    oid: DataTypeOIDs.tsvector,
+    jsType: 'string',
+    // The text form is ordinary-looking text - see inet-type.ts for why
+    // none of these string-shaped types join inference.
+    inferrable: false,
+    encodeText(v) {
+        return '' + v;
+    },
+    decodeBinary(v, offset = 0) {
+        return decodeVector(v, offset);
+    },
+    decodeText(v) {
+        return v;
+    },
+    isType(v) {
+        return typeof v === 'string';
+    },
+};
+export const ArrayTsVectorType = {
+    ...TsVectorType,
+    name: '_tsvector',
+    oid: DataTypeOIDs._tsvector,
+    elementsOID: DataTypeOIDs.tsvector,
+};
+export const TsQueryType = {
+    ...TsVectorType,
+    name: 'tsquery',
+    oid: DataTypeOIDs.tsquery,
+    decodeBinary(v, offset = 0) {
+        const count = v.readInt32BE(offset);
+        // An empty query prints as nothing, and has no root to read.
+        if (!count)
+            return '';
+        return printQuery(readQueryNode(v, { p: offset + 4 }), 0, false);
+    },
+};
+export const ArrayTsQueryType = {
+    ...TsQueryType,
+    name: '_tsquery',
+    oid: DataTypeOIDs._tsquery,
+    elementsOID: DataTypeOIDs.tsquery,
+};

package/data-types/xid-type.d.ts

@@ -0,0 +1,7 @@
+import type { DataType } from '../interfaces/data-type.js';
+export declare const XidType: DataType;
+export declare const ArrayXidType: DataType;
+export declare const CidType: DataType;
+export declare const ArrayCidType: DataType;
+export declare const Xid8Type: DataType;
+export declare const ArrayXid8Type: DataType;

package/data-types/xid-type.js

@@ -0,0 +1,110 @@
+import { DataTypeOIDs } from '../constants.js';
+import { fastParseInt, fastParseIntBuffer } from '../util/fast-parseint.js';
+/**
+ * `xid`, `xid8` and `cid` - the transaction and command counters behind
+ * the `xmin`, `xmax`, `cmin` and `cmax` system columns, which an
+ * application selects when it wants a row's identity for optimistic
+ * locking. They are counters, so they decode to numbers.
+ *
+ * None of the three joins inference. A JavaScript number says nothing
+ * about which of these it is, and claiming integers here would take them
+ * from `int4` and `int8`, where they almost always belong - name the
+ * type to use one.
+ */
+const BIG32 = BigInt(32);
+/**
+ * A 64-bit value is only exactly a JavaScript number while its high half
+ * is at most this: 0x1fffff * 2^32 + 0xffffffff is exactly
+ * Number.MAX_SAFE_INTEGER.
+ */
+const MAX_SAFE_HIGH = 0x1fffff;
+/** Both 64-bit types here are unsigned, so the halves are read apart. */
+function readUInt64(v, offset) {
+    const hi = v.readUInt32BE(offset);
+    const lo = v.readUInt32BE(offset + 4);
+    if (hi <= MAX_SAFE_HIGH)
+        return hi * 4294967296 + lo;
+    return (BigInt(hi) << BIG32) | BigInt(lo);
+}
+function writeUInt64(buf, v) {
+    const n = typeof v === 'bigint' ? v : BigInt(fastParseInt(v));
+    buf.writeUInt32BE(Number(n >> BIG32));
+    buf.writeUInt32BE(Number(n & BigInt(0xffffffff)));
+}
+function createUInt32Type(name, oid) {
+    return {
+        name,
+        oid,
+        jsType: 'number',
+        inferrable: false,
+        encodeText(v) {
+            return '' + v;
+        },
+        encodeBinary(buf, v) {
+            buf.writeUInt32BE(fastParseInt(v));
+        },
+        decodeBinary(v, offset = 0) {
+            return v.readUInt32BE(offset);
+        },
+        decodeText: fastParseInt,
+        decodeTextBuffer: fastParseIntBuffer,
+        isType(v) {
+            return (typeof v === 'number' &&
+                Number.isInteger(v) &&
+                v >= 0 &&
+                v <= 4294967295);
+        },
+    };
+}
+export const XidType = createUInt32Type('xid', DataTypeOIDs.xid);
+export const ArrayXidType = {
+    ...XidType,
+    name: '_xid',
+    oid: DataTypeOIDs._xid,
+    elementsOID: DataTypeOIDs.xid,
+};
+export const CidType = createUInt32Type('cid', DataTypeOIDs.cid);
+export const ArrayCidType = {
+    ...CidType,
+    name: '_cid',
+    oid: DataTypeOIDs._cid,
+    elementsOID: DataTypeOIDs.cid,
+};
+export const Xid8Type = {
+    name: 'xid8',
+    oid: DataTypeOIDs.xid8,
+    // A number while the value fits one exactly, a BigInt after that -
+    // the same contract int8 has.
+    jsType: 'BigInt',
+    inferrable: false,
+    encodeText(v) {
+        return '' + v;
+    },
+    encodeBinary: writeUInt64,
+    decodeBinary(v, offset = 0) {
+        return readUInt64(v, offset);
+    },
+    decodeText(s) {
+        // A full transaction id never has a sign, so the digit count alone
+        // decides whether it can be a number.
+        if (s.length <= 15)
+            return Number(s);
+        const v = BigInt(s);
+        return v <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(v) : v;
+    },
+    decodeTextBuffer(buf, offset, len) {
+        if (len <= 15)
+            return fastParseIntBuffer(buf, offset, len);
+        return Xid8Type.decodeText(buf.toString('latin1', offset, offset + len), {});
+    },
+    isType(v) {
+        return (typeof v === 'bigint' ||
+            (typeof v === 'number' && Number.isInteger(v) && v >= 0));
+    },
+};
+export const ArrayXid8Type = {
+    ...Xid8Type,
+    name: '_xid8',
+    oid: DataTypeOIDs._xid8,
+    elementsOID: DataTypeOIDs.xid8,
+};

package/index.d.ts

@@ -8,6 +8,10 @@ export * from './connection/pool.js';
 export * from './connection/prepared-statement.js';
 export * from './constants.js';
 export * from './data-type-map.js';
+export * from './data-types/classes/geometric.js';
+export * from './data-types/classes/interval.js';
+export * from './data-types/classes/numeric.js';
+export * from './data-types/classes/range.js';
 export * from './interfaces/batch-result.js';
 export * from './interfaces/command-result.js';
 export * from './interfaces/copy-from-rows-options.js';
@@ -23,6 +27,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

@@ -8,6 +8,10 @@ export * from './connection/pool.js';
 export * from './connection/prepared-statement.js';
 export * from './constants.js';
 export * from './data-type-map.js';
+export * from './data-types/classes/geometric.js';
+export * from './data-types/classes/interval.js';
+export * from './data-types/classes/numeric.js';
+export * from './data-types/classes/range.js';
 export * from './interfaces/batch-result.js';
 export * from './interfaces/command-result.js';
 export * from './interfaces/copy-from-rows-options.js';
@@ -23,6 +27,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/data-mapping-options.d.ts

@@ -22,4 +22,30 @@ export interface DataMappingOptions {
      * that comes back.
      */
     fetchAsString?: OID[];
+    /**
+     * Ask the server for text on any column this client has no way to
+     * decode, instead of taking bytes it cannot read.
+     *
+     * Result columns are requested in binary, and there is a decoder only
+     * for the types registered in the type map - so an enum, a composite,
+     * an extension type, and 54 of PostgreSQL's own built-ins (`interval`,
+     * `inet`, the range family, `tsvector`, `money`, ...) arrive as a raw
+     * `Buffer` that nothing can interpret. With this on they arrive as the
+     * string PostgreSQL would have printed, which is what `pg` gives for
+     * the same column.
+     *
+     * Off by default, and it is not free: the column types have to be known
+     * before the Bind that asks for them, so a query that has not been
+     * prepared yet is prepared on first sight (one extra round trip per
+     * distinct statement per connection, measured at 233µs -> 447µs on
+     * loopback), and one run with `prepare: false` asks for the whole row
+     * as text.
+     *
+     * A registered type is untouched, so nothing that decodes today starts
+     * arriving as a string. An array whose own OID is unregistered comes
+     * back as the array literal rather than a JS array - there is no way to
+     * know it is an array without reading the catalog, and `pg` answers the
+     * same way. `fields[i].dataTypeName` stays empty for the same reason.
+     */
+    unknownTypesAsString?: boolean;
 }

package/interfaces/data-type.d.ts

@@ -26,15 +26,14 @@ export interface DataType {
     encodeText?: EncodeTextFunction;
     encodeCalculateDim?: EncodeCalculateDimFunction;
 }
-export interface Point {
-    x: number;
-    y: number;
-}
-export interface Circle {
-    x: number;
-    y: number;
-    r: number;
-}
+/**
+ * The shape `box` and `lseg` share.
+ *
+ * @deprecated Both types now decode to a class of their own - `Box` and
+ *   `LineSegment` - which is what tells them apart; they were
+ *   indistinguishable while both were only this. Kept because a plain
+ *   object of these four numbers is still accepted as a parameter.
+ */
 export interface Rectangle {
     x1: number;
     y1: number;

package/package.json

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

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

@@ -0,0 +1,42 @@
+/**
+ * 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, for a pooled
+ * connection on `Pool`'s `'destroy'` (as the second argument) and
+ * `'error'`, and as the rejection of whatever query was in flight when it
+ * happened - one object for all of them, so a caller that needs both can
+ * pair them by identity. `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,56 @@
+/**
+ * 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, for a pooled
+ * connection on `Pool`'s `'destroy'` (as the second argument) and
+ * `'error'`, and as the rejection of whatever query was in flight when it
+ * happened - one object for all of them, so a caller that needs both can
+ * pair them by identity. `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/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,44 @@ export class PgSocket extends SafeEventEmitter {
         this._connectToHost();
     }
     _handleClose() {
-        this._failPendingCaptures(new Error('Connection closed'));
+        // 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();
+        // Whatever was in flight is rejected with the same object the 'close'
+        // event carries, so `err.code === '08006'` works in a caller's catch
+        // exactly as it does in a Pool listener - the generic message it used
+        // to get named no cause and carried no code at all. A close that was
+        // asked for keeps that message: nothing went wrong, the caller simply
+        // raced the shutdown.
+        this._failPendingCaptures(reason ?? 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));
+        // An error on a live connection is that connection going away - Node
+        // always follows 'error' with 'close' - so the caller gets the same
+        // ConnectionLostError the close will carry, with this as its cause,
+        // rather than a raw ECONNRESET whose `code` is a Node errno where a
+        // SQLSTATE is expected. Before READY there is no connection to have
+        // lost, and the error itself is the useful thing.
+        this._failPendingCaptures(this._state === ConnectionState.READY
+            ? this._buildCloseReason()
+            : this._closeReason);
         if (this._state !== ConnectionState.READY) {
             this._socket?.end();
         }

package/util/parse-array.js

@@ -21,13 +21,28 @@ export function parsePostgresArray(s, opts) {
                     continue;
                 }
                 if (c === '}' || c === sep) {
-                    if (token) {
+                    // An element is present when it had content OR when it was
+                    // quoted: `""` is a real empty string, and testing the token
+                    // alone dropped it - `{"",b}` came back as one element, with
+                    // every later index shifted.
+                    //
+                    // An unquoted empty token is still skipped. PostgreSQL never
+                    // emits one (a null prints as the bare word NULL, an empty
+                    // string always as `""`), so `{a,,b}` is not output this has to
+                    // read - and skipping it is what keeps the separator that
+                    // follows a nested array from pushing an element of its own.
+                    if (token || exactlyValue) {
                         if (token === 'NULL' && !exactlyValue)
                             arr.push(null);
                         else
                             arr.push(transform ? transform(token) : token);
-                        exactlyValue = false;
                     }
+                    // Reset per element rather than only when one was pushed.
+                    // Leaving it set carried "this one was quoted" into the next
+                    // element - and that flag is what tells a real NULL apart from
+                    // the string "NULL", so a null following an empty string
+                    // decoded as four characters of text.
+                    exactlyValue = false;
                     token = '';
                     if (c === '}')
                         return;