postgrejs 3.11.0 → 3.12.0

package/CHANGELOG.md

@@ -1,6 +1,46 @@
 ## Changelog
 
-### [v3.11.0](https://github.com/panates/postgrejs/compare/v3.10.1...v3.11.0) - 
+### [v3.12.0](https://github.com/panates/postgrejs/compare/v3.11.1...v3.12.0) - 
+
+#### Breaking Changes :warning:
+
+- fix!: refuse what the server refuses instead of storing another number @Eray Hanoğlu  
+
+#### 🚀 New Features
+
+- feat(benchmark): count the bytes sent, and what a run keeps @Eray Hanoğlu 
+- feat: report the parameter types the server resolved @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix(benchmark): a figure nobody could measure is not a bar of zero @Eray Hanoğlu 
+- fix: take the value out of a BindParam handed to a prepared statement @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs(benchmark): update benchmarks to include new memory and network metrics @Eray Hanoğlu 
+- docs: say what an untyped numeric array actually costs @Eray Hanoğlu 
+- docs(benchmark): say what Peak Heap is not, and what survives a re-run @Eray Hanoğlu 
+- docs(benchmark): Retained is a working set, not a permanent footprint @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: stop quoting and re-escaping every element of an array literal @Eray Hanoğlu 
+
+### [v3.11.1](https://github.com/panates/postgrejs/compare/v3.11.0...v3.11.1) -  24 September 2026 
+
+#### 🪲 Fixes
+
+- fix(bench): count off-heap memory in Peak Heap @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: shift the instant instead of rebuilding a local Date from its parts @Eray Hanoğlu 
+- perf: build uuid and macaddr text in one pass instead of five @Eray Hanoğlu 
+- perf: stop asking whether a small money value round-trips @Eray Hanoğlu 
+- perf: write a pg_lsn without four strings a value @Eray Hanoğlu 
+
+### [v3.11.0](https://github.com/panates/postgrejs/compare/v3.10.1...v3.11.0) -  23 September 2026 
 
 #### 🚀 New Features
 

package/connection/intl-connection.d.ts

@@ -332,9 +332,17 @@ export declare class IntlConnection extends SafeEventEmitter {
      * a separately-awaited Sync, and fetches the RowDescription/NoData in the
      * same round trip so the caller can cache it (see executeReused()) rather
      * than every later execute() re-Describing its own portal.
+     *
+     * The Describe answers with the parameters too, and that answer is worth
+     * keeping: it is the only place the server says what it made of a
+     * parameter the client declared nothing for. `insert into t(v)
+     * values($1)` resolves `$1` from the column, not from the value - which
+     * is why it is stable across executions and why a caller who wants the
+     * binary encoding back can read it and name that type with BindParam.
      */
     prepareOnce(sql: string, paramTypes: Maybe<Maybe<OID>[]>, statementName: string): Promise<{
         fields?: Protocol.RowDescription[];
+        resolvedParamTypes?: OID[];
     }>;
     /**
      * Bind+Execute+Sync as a single round trip against an unnamed portal, for

package/connection/intl-connection.js

@@ -1239,12 +1239,20 @@ export class IntlConnection extends SafeEventEmitter {
      * a separately-awaited Sync, and fetches the RowDescription/NoData in the
      * same round trip so the caller can cache it (see executeReused()) rather
      * than every later execute() re-Describing its own portal.
+     *
+     * The Describe answers with the parameters too, and that answer is worth
+     * keeping: it is the only place the server says what it made of a
+     * parameter the client declared nothing for. `insert into t(v)
+     * values($1)` resolves `$1` from the column, not from the value - which
+     * is why it is stable across executions and why a caller who wants the
+     * binary encoding back can read it and name that type with BindParam.
      */
     async prepareOnce(sql, paramTypes, statementName) {
         this.assertConnected();
         this.ref();
         try {
             let fields;
+            let resolvedParamTypes;
             let error;
             this.runningQueryCount++;
             await this.socket
@@ -1257,8 +1265,10 @@ export class IntlConnection extends SafeEventEmitter {
                         // Not an error: handed over, and the loop carries on.
                         this.emit('notice', msg);
                         break;
-                    case Protocol.BackendMessageCode.ParseComplete:
                     case Protocol.BackendMessageCode.ParameterDescription:
+                        resolvedParamTypes = msg.parameterIds;
+                        break;
+                    case Protocol.BackendMessageCode.ParseComplete:
                     case Protocol.BackendMessageCode.NoData:
                         break;
                     case Protocol.BackendMessageCode.RowDescription:
@@ -1280,7 +1290,7 @@ export class IntlConnection extends SafeEventEmitter {
                 .finally(() => {
                 this.runningQueryCount--;
             });
-            return { fields };
+            return { fields, resolvedParamTypes };
         }
         finally {
             this.unref();

package/connection/prepared-statement.d.ts

@@ -10,6 +10,7 @@ export declare class PreparedStatement extends SafeEventEmitter implements Async
     private readonly _sql;
     private readonly _name;
     private readonly _paramTypes?;
+    private _resolvedParamTypes?;
     private _fields?;
     protected _onErrorSavePoint: string;
     private _refCount;
@@ -20,6 +21,24 @@ export declare class PreparedStatement extends SafeEventEmitter implements Async
     get name(): Maybe<string>;
     get sql(): string;
     get paramTypes(): Maybe<Maybe<OID>[]>;
+    /**
+     * What the server made of each parameter, in order, as its Describe
+     * answered - not what was asked for in `paramTypes`.
+     *
+     * A parameter the caller declared nothing for is resolved by the
+     * server from where it appears: the column it is inserted into, the
+     * operator it sits beside, the function it is passed to. It never
+     * looks at the value, which is still three messages away, so this is
+     * a property of the statement and does not change between executions.
+     *
+     * Useful for two things. It says what a parameter with no context
+     * became - `select $1` resolves to `text`, which is why an array
+     * there comes back as an array literal rather than an array. And it
+     * is the type to name with `new BindParam(oid, v)` for a caller who
+     * wants the binary encoding a large numeric array gives up by going
+     * out untyped (see `isUnspecifiedParam`).
+     */
+    get resolvedParamTypes(): Maybe<OID[]>;
     execute(options?: QueryOptions): Promise<QueryResult>;
     /**
      * Runs this statement once per parameter set, sending every Bind/Execute
@@ -78,6 +97,28 @@ export declare class PreparedStatement extends SafeEventEmitter implements Async
      * holding a `Connection` never saw. Hard to provoke - `DEALLOCATE`
      * does not normally raise one - which is why there is no test for it.
      */
+    /**
+     * Takes the value out of a `BindParam`, and refuses one that names a
+     * type this statement is not.
+     *
+     * A prepared statement's parameter types are fixed by its Parse, so a
+     * `BindParam` here cannot change one: the Bind's format code says
+     * binary or text, and the server decodes with the type it already
+     * resolved. Naming a different one and being believed would read the
+     * bytes as something else - which is why the mismatch is an error
+     * rather than something to quietly honour.
+     *
+     * It used to be neither: nothing unwrapped the object, so it reached
+     * the encoder as a value with no type of its own and went out as
+     * `'' + v`. A text column took `"[object Object]"` and said nothing.
+     *
+     * What it is compared against is what the caller declared at
+     * `prepare()`, or failing that what the server resolved - which is the
+     * same type either way, and is why an agreeing `BindParam` is simply
+     * unwrapped. Where there is nothing to compare against, the value is
+     * taken as given.
+     */
+    protected _unwrapBindParams(params: Maybe<any[]>): Maybe<any[]>;
     protected _emitNotice(msg: any): void;
     protected _executeBatchWithTransaction(paramSets: any[][], options: QueryOptions): Promise<BatchResult>;
     protected _executeWithTransaction(options?: QueryOptions): Promise<QueryResult>;

package/connection/prepared-statement.js

@@ -1,4 +1,4 @@
-import { DataTypeOIDs } from '../constants.js';
+import { DataTypeNames, DataTypeOIDs } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
@@ -8,6 +8,7 @@ import { resolveColumnFormats } from '../util/resolve-column-formats.js';
 import { resolveRowType } from '../util/row-decoder.js';
 import { isTransactionCommand, refusesSavepoint, } from '../util/transaction-command.js';
 import { wrapRowDescription } from '../util/wrap-row-description.js';
+import { BindParam } from './bind-param.js';
 import { Cursor } from './cursor.js';
 import { getIntlConnection } from './intl-connection.js';
 import { Portal } from './portal.js';
@@ -18,6 +19,7 @@ export class PreparedStatement extends SafeEventEmitter {
     _sql = '';
     _name = '';
     _paramTypes;
+    _resolvedParamTypes;
     _fields;
     _onErrorSavePoint;
     _refCount = 0;
@@ -34,8 +36,9 @@ export class PreparedStatement extends SafeEventEmitter {
         const intoCon = getIntlConnection(connection);
         intoCon.assertConnected();
         const statement = new PreparedStatement(connection, sql, options?.paramTypes);
-        const { fields } = await intoCon.prepareOnce(sql, statement.paramTypes, statement.name);
+        const { fields, resolvedParamTypes } = await intoCon.prepareOnce(sql, statement.paramTypes, statement.name);
         statement._fields = fields;
+        statement._resolvedParamTypes = resolvedParamTypes;
         statement._refCount = 1;
         return statement;
     }
@@ -51,6 +54,26 @@ export class PreparedStatement extends SafeEventEmitter {
     get paramTypes() {
         return this._paramTypes;
     }
+    /**
+     * What the server made of each parameter, in order, as its Describe
+     * answered - not what was asked for in `paramTypes`.
+     *
+     * A parameter the caller declared nothing for is resolved by the
+     * server from where it appears: the column it is inserted into, the
+     * operator it sits beside, the function it is passed to. It never
+     * looks at the value, which is still three messages away, so this is
+     * a property of the statement and does not change between executions.
+     *
+     * Useful for two things. It says what a parameter with no context
+     * became - `select $1` resolves to `text`, which is why an array
+     * there comes back as an array literal rather than an array. And it
+     * is the type to name with `new BindParam(oid, v)` for a caller who
+     * wants the binary encoding a large numeric array gives up by going
+     * out untyped (see `isUnspecifiedParam`).
+     */
+    get resolvedParamTypes() {
+        return this._resolvedParamTypes;
+    }
     async execute(options = {}) {
         const intlCon = getIntlConnection(this.connection);
         // Folded in here rather than deeper: a cursor keeps these options
@@ -130,13 +153,58 @@ export class PreparedStatement extends SafeEventEmitter {
      * holding a `Connection` never saw. Hard to provoke - `DEALLOCATE`
      * does not normally raise one - which is why there is no test for it.
      */
+    /**
+     * Takes the value out of a `BindParam`, and refuses one that names a
+     * type this statement is not.
+     *
+     * A prepared statement's parameter types are fixed by its Parse, so a
+     * `BindParam` here cannot change one: the Bind's format code says
+     * binary or text, and the server decodes with the type it already
+     * resolved. Naming a different one and being believed would read the
+     * bytes as something else - which is why the mismatch is an error
+     * rather than something to quietly honour.
+     *
+     * It used to be neither: nothing unwrapped the object, so it reached
+     * the encoder as a value with no type of its own and went out as
+     * `'' + v`. A text column took `"[object Object]"` and said nothing.
+     *
+     * What it is compared against is what the caller declared at
+     * `prepare()`, or failing that what the server resolved - which is the
+     * same type either way, and is why an agreeing `BindParam` is simply
+     * unwrapped. Where there is nothing to compare against, the value is
+     * taken as given.
+     */
+    _unwrapBindParams(params) {
+        if (!params)
+            return params;
+        let out;
+        const l = params.length;
+        let i;
+        let prm;
+        let expected;
+        for (i = 0; i < l; i++) {
+            prm = params[i];
+            if (!(prm instanceof BindParam))
+                continue;
+            expected = this._paramTypes?.[i] ?? this._resolvedParamTypes?.[i];
+            if (expected != null && prm.oid !== expected)
+                throw new TypeError(`Parameter $${i + 1} was given as ${typeLabel(prm.oid)}, but this ` +
+                    `prepared statement's $${i + 1} is ${typeLabel(expected)}. A ` +
+                    'prepared statement takes its parameter types at ' +
+                    'prepare(sql, { paramTypes }), and they cannot be changed per ' +
+                    'execution.');
+            out = out || params.slice();
+            out[i] = prm.value;
+        }
+        return out || params;
+    }
     _emitNotice(msg) {
         this.emit('notice', msg);
         getIntlConnection(this.connection).emit('notice', msg);
     }
     _executeBatchWithTransaction(paramSets, options) {
         const intlCon = getIntlConnection(this.connection);
-        return this._withTransaction(options, () => intlCon.executeBatchReused(this.name, this._fields, this.paramTypes, paramSets, options));
+        return this._withTransaction(options, () => intlCon.executeBatchReused(this.name, this._fields, this.paramTypes, paramSets.map(set => this._unwrapBindParams(set)), options));
     }
     async _executeWithTransaction(options = {}) {
         // The Bind+Execute+Sync path can carry the rollbackOnError savepoint
@@ -238,6 +306,7 @@ export class PreparedStatement extends SafeEventEmitter {
     }
     async _execute(options = {}, savepoint) {
         const intlCon = getIntlConnection(this.connection);
+        const params = this._unwrapBindParams(options.params);
         if (options.cursor && this._fields) {
             intlCon.ref();
             let portal = new Portal(this, 'P_' + ++portalCounter);
@@ -247,7 +316,7 @@ export class PreparedStatement extends SafeEventEmitter {
                 // codes on the Bind below with no round trip of its own.
                 const typeMap = options.typeMap || GlobalTypeMap;
                 const columnFormat = resolveColumnFormats(this._fields, options, typeMap);
-                const fields = await portal.bindAndRetrieveFields(options.params, options, columnFormat);
+                const fields = await portal.bindAndRetrieveFields(params, options, columnFormat);
                 const parsers = getParsers(typeMap, fields, options);
                 const resultFields = wrapRowDescription(typeMap, fields, columnFormat, options);
                 const result = {
@@ -270,7 +339,7 @@ export class PreparedStatement extends SafeEventEmitter {
         // unnamed portal, reusing the RowDescription prepare() already fetched
         // instead of re-Describing (and re-Close-ing) a fresh named portal on
         // every call.
-        return intlCon.executeReused(this.name, this._fields, this.paramTypes, options.params, options, savepoint);
+        return intlCon.executeReused(this.name, this._fields, this.paramTypes, params, options, savepoint);
     }
     /**
      * Called by Cursor.close() instead of separately awaiting
@@ -372,3 +441,8 @@ export class PreparedStatement extends SafeEventEmitter {
         return this.close();
     }
 }
+/** `int2 (21)` - the name when there is one, and always the oid. */
+function typeLabel(oid) {
+    const name = DataTypeNames[oid];
+    return name ? `${name} (${oid})` : String(oid);
+}

package/data-types/date-type.js

@@ -1,5 +1,6 @@
 import { DataTypeOIDs } from '../constants.js';
 import { formatDate } from '../util/format-datetime.js';
+import { utcPartsAsLocal } from '../util/local-date.js';
 import { parseDate } from '../util/parse-datetime.js';
 const timeShift = 946684800000;
 export const DateType = {
@@ -35,11 +36,11 @@ export const DateType = {
             return Infinity;
         if (t === -0x80000000)
             return -Infinity;
-        // Shift from 2000 to 1970
-        let d = new Date(t * 1000 * 86400 + timeShift);
-        if (!options.utcDates)
-            d = new Date(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
-        return d;
+        // Shift from 2000 to 1970. A date's wire value is exactly midnight
+        // UTC, so the local wall clock it stands for is local midnight -
+        // which is what the shift lands on.
+        const ms = t * 1000 * 86400 + timeShift;
+        return options.utcDates ? new Date(ms) : utcPartsAsLocal(ms);
     },
     decodeText(v, options) {
         return parseDate(v, options.utcDates, options.dateStyle);

package/data-types/int2-type.js

@@ -9,7 +9,7 @@ export const Int2Type = {
         return '' + v;
     },
     encodeBinary(buf, v) {
-        buf.writeInt16BE(assertInteger(fastParseInt(v), 'int2'));
+        buf.writeInt16BE(assertInteger(v, 'int2', -32768, 32767));
     },
     decodeBinary(v, offset = 0) {
         return v.readInt16BE(offset);

package/data-types/int4-type.js

@@ -9,7 +9,7 @@ export const Int4Type = {
         return '' + v;
     },
     encodeBinary(buf, v) {
-        buf.writeInt32BE(assertInteger(fastParseInt(v), 'int4'));
+        buf.writeInt32BE(assertInteger(v, 'int4', -2147483648, 2147483647));
     },
     decodeBinary(v, offset = 0) {
         return v.readInt32BE(offset);

package/data-types/int8-type.js

@@ -1,5 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
-import { assertBigIntSource } from '../util/assert-integer.js';
+import { assertBigInt } from '../util/assert-integer.js';
 import { readBigInt64BE } from '../util/bigint-methods.js';
 import { fastParseIntBuffer } from '../util/fast-parseint.js';
 const maxSafeInteger = BigInt(Number.MAX_SAFE_INTEGER);
@@ -11,7 +11,7 @@ export const Int8Type = {
         return '' + v;
     },
     encodeBinary(buf, v) {
-        buf.writeBigInt64BE(assertBigIntSource(v, 'int8'));
+        buf.writeBigInt64BE(assertBigInt(v, 'int8'));
     },
     decodeBinary(buf, offset = 0) {
         const v = typeof buf.readBigInt64BE === 'function'

package/data-types/macaddr-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+import { writeHexBytes } from '../util/hex-text.js';
 /**
  * `macaddr` and `macaddr8` share a file for the same reason `inet` and
  * `cidr` do: one wire format - the address bytes and nothing else - and
@@ -33,6 +34,17 @@ function parseMacaddr(v, size) {
     return Buffer.from(hex, 'hex');
 }
 function createType(name, oid, size) {
+    // The text this type writes, built once: `size` pairs of hex with a
+    // colon between them, and only the hex is rewritten per value. See
+    // util/hex-text.ts for why not `toString('hex')` per byte.
+    const text = Buffer.allocUnsafe(size * 3 - 1);
+    const positions = [];
+    let i;
+    for (i = 0; i < size; i++) {
+        positions.push(i * 3);
+        if (i)
+            text[i * 3 - 1] = 58; /* : */
+    }
     return {
         name,
         oid,
@@ -52,11 +64,8 @@ function createType(name, oid, size) {
             buf.writeBytes(b);
         },
         decodeBinary(v, offset = 0) {
-            let out = v.toString('hex', offset, offset + 1);
-            let i;
-            for (i = 1; i < size; i++)
-                out += ':' + v.toString('hex', offset + i, offset + i + 1);
-            return out;
+            writeHexBytes(text, positions, v, offset, size);
+            return text.toString('latin1');
         },
         decodeText(v) {
             return v;

package/data-types/money-type.js

@@ -59,6 +59,23 @@ export function moneyToString(minorUnits, scale) {
         '.' +
         digits.slice(digits.length - scale));
 }
+/**
+ * Below this many minor units the decimal has at most fifteen
+ * significant digits, which a double both holds and prints back exactly
+ * - so the round trip below can only agree, and asking it is the most
+ * expensive thing in the decode: measured over values that vary,
+ * `parseFloat` plus the comparison is 241 ns against 113 ns without it,
+ * on a decode whose string-building is 109 ns of that.
+ *
+ * The scale bound is the other half: the test is about *printed* digits,
+ * and JavaScript switches to exponential notation below 1e-6, which
+ * PostgreSQL never writes. At scale 6 the smallest non-zero value is
+ * exactly 1e-6, and no currency has more.
+ */
+const FAITHFUL_LIMIT = 1000000000000000n; // 10^15
+function isFaithful(minorUnits, scale) {
+    return (scale <= 6 && minorUnits < FAITHFUL_LIMIT && minorUnits > -FAITHFUL_LIMIT);
+}
 /**
  * A number while a double carries the value exactly, a Numeric after
  * that - the same rule `numeric` decodes by, and for the same reason.
@@ -143,18 +160,22 @@ export const MoneyType = {
         const v = typeof buf.readBigInt64BE === 'function'
             ? buf.readBigInt64BE(offset)
             : readBigInt64BE(buf, offset);
-        const s = moneyToString(v, formatOf(options).scale);
+        const { scale } = formatOf(options);
+        const s = moneyToString(v, scale);
         // The exact decimal is what the decode already built; handing it
         // back is the whole of `decimalAsString`.
-        return wantsDecimalString(options, DataTypeOIDs.money)
-            ? s
-            : toNumberOrNumeric(s);
+        if (wantsDecimalString(options, DataTypeOIDs.money))
+            return s;
+        return isFaithful(v, scale) ? parseFloat(s) : toNumberOrNumeric(s);
     },
     decodeText(s, options) {
         const { scale } = formatOf(options);
-        const exact = moneyToString(parseMoneyText(s), scale);
-        return wantsDecimalString(options, DataTypeOIDs.money)
-            ? exact
+        const minorUnits = parseMoneyText(s);
+        const exact = moneyToString(minorUnits, scale);
+        if (wantsDecimalString(options, DataTypeOIDs.money))
+            return exact;
+        return isFaithful(minorUnits, scale)
+            ? parseFloat(exact)
             : toNumberOrNumeric(exact);
     },
     /**

package/data-types/oid-type.js

@@ -9,7 +9,7 @@ export const OidType = {
         return '' + v;
     },
     encodeBinary(buf, v) {
-        buf.writeUInt32BE(assertInteger(fastParseInt(v), 'oid'));
+        buf.writeUInt32BE(assertInteger(v, 'oid', 0, 4294967295));
     },
     decodeBinary(v, offset = 0) {
         return v.readUInt32BE(offset);

package/data-types/pg-lsn-type.js

@@ -14,6 +14,29 @@ import { DataTypeOIDs } from '../constants.js';
  * compared rather than arithmetic.
  */
 const LSN_PATTERN = /^([0-9a-fA-F]{1,8})\/([0-9a-fA-F]{1,8})$/;
+/**
+ * `0`-`F` as bytes, and the text written into one reused scratch.
+ *
+ * `toString(16).toUpperCase()` per half is two strings each and four per
+ * value: 281 ns against 70 ns here, measured over values that vary. An
+ * LSN is not decoded in bulk - it comes back from monitoring queries a
+ * few rows at a time - so this is worth only the fifteen lines it takes
+ * and no machinery beyond them.
+ */
+const HEX_UPPER = Buffer.from('0123456789ABCDEF', 'latin1');
+const TEXT = Buffer.allocUnsafe(17);
+/** Writes one half at `p`, unpadded, and answers where it ended. */
+function writeHalf(value, p) {
+    let shift = 28;
+    // Neither half is padded - the server writes `0/0` and `A/B` - so the
+    // leading zeros are skipped, and the last nibble is written whatever
+    // it is so that zero comes out as `0` rather than nothing.
+    while (shift && !((value >>> shift) & 15))
+        shift -= 4;
+    for (; shift >= 0; shift -= 4)
+        TEXT[p++] = HEX_UPPER[(value >>> shift) & 15];
+    return p;
+}
 export const PgLsnType = {
     name: 'pg_lsn',
     oid: DataTypeOIDs.pg_lsn,
@@ -32,12 +55,10 @@ export const PgLsnType = {
         buf.writeUInt32BE(parseInt(m[2], 16));
     },
     decodeBinary(v, offset = 0) {
-        return (v.readUInt32BE(offset).toString(16).toUpperCase() +
-            '/' +
-            v
-                .readUInt32BE(offset + 4)
-                .toString(16)
-                .toUpperCase());
+        let p = writeHalf(v.readUInt32BE(offset), 0);
+        TEXT[p++] = 47; /* / */
+        p = writeHalf(v.readUInt32BE(offset + 4), p);
+        return TEXT.toString('latin1', 0, p);
     },
     decodeText(v) {
         return v;

package/data-types/time-type.js

@@ -1,5 +1,6 @@
 import { DataTypeOIDs } from '../constants.js';
 import { formatTime } from '../util/format-datetime.js';
+import { utcPartsAsLocal } from '../util/local-date.js';
 import { parseTime, STRICT_TIME_PATTERN } from '../util/parse-time.js';
 const timeMul = 4294967296;
 export const TimeType = {
@@ -27,11 +28,8 @@ export const TimeType = {
     decodeBinary(v, offset = 0, _len, options) {
         const hi = v.readInt32BE(offset);
         const lo = v.readUInt32BE(offset + 4);
-        let d = new Date((lo + hi * timeMul) / 1000);
-        if (!options.utcDates) {
-            d = new Date(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), d.getUTCMilliseconds());
-        }
-        return d;
+        const ms = (lo + hi * timeMul) / 1000;
+        return options.utcDates ? new Date(ms) : utcPartsAsLocal(ms);
     },
     decodeText(v, options) {
         return parseTime(v, false, options.utcDates);

package/data-types/timestamp-type.js

@@ -1,5 +1,6 @@
 import { DataTypeOIDs } from '../constants.js';
 import { formatTimestamp } from '../util/format-datetime.js';
+import { utcPartsAsLocal } from '../util/local-date.js';
 import { parseDateTime } from '../util/parse-datetime.js';
 import { parsePgTimestampBuffer } from '../util/parse-pg-timestamp.js';
 const timeShift = 946684800000;
@@ -44,11 +45,8 @@ export const TimestampType = {
         if (lo === 0x00000000 && hi === -0x80000000)
             return -Infinity;
         // Shift from 2000 to 1970
-        let d = new Date((lo + hi * timeMul) / 1000 + timeShift);
-        if (!options.utcDates) {
-            d = new Date(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), d.getUTCMilliseconds());
-        }
-        return d;
+        const ms = (lo + hi * timeMul) / 1000 + timeShift;
+        return options.utcDates ? new Date(ms) : utcPartsAsLocal(ms);
     },
     decodeText(v, options) {
         return parseDateTime(v, options.utcDates, options.dateStyle);

package/data-types/uuid-type.js

@@ -1,4 +1,15 @@
 import { DataTypeOIDs } from '../constants.js';
+import { writeHexBytes } from '../util/hex-text.js';
+/**
+ * The canonical text, written once and read back per value: 36 ASCII
+ * characters whose four dashes never move, so only the hex is rewritten.
+ * Reused rather than allocated because a decode fills it and converts it
+ * before anything else can run.
+ */
+const TEXT = Buffer.allocUnsafe(36);
+TEXT[8] = TEXT[13] = TEXT[18] = TEXT[23] = 45; /* - */
+/** Where each of the sixteen bytes writes its two characters. */
+const POSITIONS = [0, 2, 4, 6, 9, 11, 14, 16, 19, 21, 24, 26, 28, 30, 32, 34];
 const GUID_PATTERN = /^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}$/;
 export const UuidType = {
     name: 'uuid',
@@ -14,15 +25,8 @@ export const UuidType = {
         buf.writeBytes(b);
     },
     decodeBinary(v, offset = 0) {
-        return (v.toString('hex', offset, offset + 4) +
-            '-' +
-            v.toString('hex', offset + 4, offset + 6) +
-            '-' +
-            v.toString('hex', offset + 6, offset + 8) +
-            '-' +
-            v.toString('hex', offset + 8, offset + 10) +
-            '-' +
-            v.toString('hex', offset + 10, offset + 16));
+        writeHexBytes(TEXT, POSITIONS, v, offset, 16);
+        return TEXT.toString('latin1');
     },
     decodeText(v) {
         return v;

package/data-types/xid-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+import { assertInteger } from '../util/assert-integer.js';
 import { fastParseInt, fastParseIntBuffer } from '../util/fast-parseint.js';
 /**
  * `xid`, `xid8` and `cid` - the transaction and command counters behind
@@ -41,7 +42,7 @@ function createUInt32Type(name, oid) {
             return '' + v;
         },
         encodeBinary(buf, v) {
-            buf.writeUInt32BE(fastParseInt(v));
+            buf.writeUInt32BE(assertInteger(v, name, 0, 4294967295));
         },
         decodeBinary(v, offset = 0) {
             return v.readUInt32BE(offset);

package/package.json

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

package/util/assert-integer.d.ts

@@ -1,22 +1,48 @@
 /**
- * Returns `v` coerced to an integer, or throws when it cannot be one.
+ * Returns `v` as the integer an integer column can store, or throws.
  *
- * `fastParseInt()` already answers NaN for a value with no integer reading
- * - `'abc'`, `{}`, `[]`, `true` - but `Buffer.writeInt32BE(NaN)` then
- * stores a silent zero, so the answer is lost exactly where it matters.
- * Nothing downstream can tell that apart from a real zero afterwards: the
- * row inserts, the copy succeeds, and the wrong number is in the table.
+ * The rule is that the binary encoding must accept exactly what the text
+ * one does and refuse exactly what the server refuses, because which of
+ * the two a value goes out as is not the caller's choice: it depends on
+ * whether the parameter's type was declared, which statement cache the
+ * query hit, and what the server resolved. A value that means one thing
+ * through one path and another through the other is the worst outcome
+ * there is, and that is what this used to be:
  *
- * Floats are deliberately not rejected: truncating 3.7 to 3 is the
- * long-standing behaviour of these encoders and is usually what a caller
- * writing into an integer column means. Only "this is not a number at all"
- * is refused.
+ * ```
+ *                             text          binary (before)
+ * [1.5]     -> int4[]         22P02 error   stored 1
+ * [-1.5]    -> int4[]         22P02 error   stored -2   (a floor, not a truncation)
+ * ['0x10']  -> int4[]         22P02 error   stored 0
+ * ['']      -> int8[]         22P02 error   stored 0
+ * [40000]   -> int2[]         22003 error   RangeError, from Buffer
+ * ```
  *
- * Unlike the integer types, float4/float8/numeric leave NaN alone - it is a
- * value PostgreSQL stores and returns as NaN, distinct from NULL, on every
- * supported server version.
+ * Only the last of those was safe. The rest put a number in the table
+ * that the caller never wrote and the server would have refused, and
+ * silently - the row inserted, the copy succeeded.
+ *
+ * So a fractional value is refused rather than floored. Truncating 3.7
+ * to 3 was the long-standing behaviour here and the argument for it was
+ * that it is usually what a caller writing into an integer column means;
+ * what that argument misses is that the same caller writing the same
+ * value through the same client gets an error whenever the encoding
+ * happens to be text, so it cannot be what they meant. Round or truncate
+ * at the call site, or let the server do it with a cast.
+ *
+ * `min`/`max` are checked here as well, rather than left to Buffer's own
+ * bounds check, so that the message names the type and the value.
+ */
+export declare function assertInteger(v: any, typeName: string, min: number, max: number): number;
+/**
+ * The same rule for int8, which counts past what a `number` holds.
+ *
+ * BigInt is happy to convert things that are not numbers at all -
+ * `BigInt('')` is 0n because an empty string reads as zero, `BigInt(true)`
+ * is 1n - so a bad value in a bigint column used to land as a plausible
+ * 0 or 1. Only what genuinely carries an exact integer is let through.
  */
-export declare function assertInteger(v: number, typeName: string): number;
+export declare function assertBigInt(v: any, typeName: string): bigint;
 /**
  * Returns `parsed` when a value that was NOT already a number coerced to
  * one, and throws when it did not.
@@ -30,14 +56,3 @@ export declare function assertInteger(v: number, typeName: string): number;
  * as NaN would be indistinguishable afterwards from a NaN that was meant.
  */
 export declare function assertCoercedNumber(parsed: number, typeName: string): number;
-/**
- * Refuses a value that only has an integer reading through a coercion
- * nobody asked for.
- *
- * int8 goes to `BigInt` rather than through `fastParseInt()`, and BigInt is
- * happy to convert things that are not numbers at all: `BigInt([])` is 0n
- * because an empty array stringifies to "", and `BigInt(true)` is 1n. A
- * bad value in a bigint column would land as a plausible-looking 0 or 1,
- * so only the types that genuinely carry an integer are let through.
- */
-export declare function assertBigIntSource(v: any, typeName: string): bigint | number;

package/util/assert-integer.js

@@ -1,26 +1,107 @@
 /**
- * Returns `v` coerced to an integer, or throws when it cannot be one.
+ * What the server reads as an integer from text: optional sign, digits,
+ * nothing else. `'1.5'`, `'1e3'` and `'0x10'` are all refused by
+ * `int4in()`, and surrounding whitespace is trimmed before it looks.
+ */
+const DECIMAL_INTEGER = /^[+-]?\d+$/;
+/**
+ * Returns `v` as the integer an integer column can store, or throws.
+ *
+ * The rule is that the binary encoding must accept exactly what the text
+ * one does and refuse exactly what the server refuses, because which of
+ * the two a value goes out as is not the caller's choice: it depends on
+ * whether the parameter's type was declared, which statement cache the
+ * query hit, and what the server resolved. A value that means one thing
+ * through one path and another through the other is the worst outcome
+ * there is, and that is what this used to be:
  *
- * `fastParseInt()` already answers NaN for a value with no integer reading
- * - `'abc'`, `{}`, `[]`, `true` - but `Buffer.writeInt32BE(NaN)` then
- * stores a silent zero, so the answer is lost exactly where it matters.
- * Nothing downstream can tell that apart from a real zero afterwards: the
- * row inserts, the copy succeeds, and the wrong number is in the table.
+ * ```
+ *                             text          binary (before)
+ * [1.5]     -> int4[]         22P02 error   stored 1
+ * [-1.5]    -> int4[]         22P02 error   stored -2   (a floor, not a truncation)
+ * ['0x10']  -> int4[]         22P02 error   stored 0
+ * ['']      -> int8[]         22P02 error   stored 0
+ * [40000]   -> int2[]         22003 error   RangeError, from Buffer
+ * ```
  *
- * Floats are deliberately not rejected: truncating 3.7 to 3 is the
- * long-standing behaviour of these encoders and is usually what a caller
- * writing into an integer column means. Only "this is not a number at all"
- * is refused.
+ * Only the last of those was safe. The rest put a number in the table
+ * that the caller never wrote and the server would have refused, and
+ * silently - the row inserted, the copy succeeded.
  *
- * Unlike the integer types, float4/float8/numeric leave NaN alone - it is a
- * value PostgreSQL stores and returns as NaN, distinct from NULL, on every
- * supported server version.
+ * So a fractional value is refused rather than floored. Truncating 3.7
+ * to 3 was the long-standing behaviour here and the argument for it was
+ * that it is usually what a caller writing into an integer column means;
+ * what that argument misses is that the same caller writing the same
+ * value through the same client gets an error whenever the encoding
+ * happens to be text, so it cannot be what they meant. Round or truncate
+ * at the call site, or let the server do it with a cast.
+ *
+ * `min`/`max` are checked here as well, rather than left to Buffer's own
+ * bounds check, so that the message names the type and the value.
  */
-export function assertInteger(v, typeName) {
-    if (Number.isNaN(v)) {
+export function assertInteger(v, typeName, min, max) {
+    let n;
+    const t = typeof v;
+    if (t === 'number') {
+        n = v;
+        if (Number.isNaN(n))
+            throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
+    }
+    else if (t === 'bigint') {
+        // Exact up to 2^53; beyond that the range check below refuses it
+        // anyway, since nothing this function guards is that wide.
+        n = Number(v);
+    }
+    else if (t === 'string') {
+        const s = v.trim();
+        if (!DECIMAL_INTEGER.test(s))
+            throw new TypeError(`Cannot encode "${v}" as ${typeName}: it is not an integer`);
+        n = +s;
+    }
+    else {
         throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
     }
-    return v;
+    if (!Number.isInteger(n))
+        throw new TypeError(`Cannot encode ${n} as ${typeName}: it is not an integer`);
+    if (n < min || n > max)
+        throw new RangeError(`Cannot encode ${n} as ${typeName}: it is out of range (${min} to ${max})`);
+    return n;
+}
+const INT8_MIN = BigInt('-9223372036854775808');
+const INT8_MAX = BigInt('9223372036854775807');
+/**
+ * The same rule for int8, which counts past what a `number` holds.
+ *
+ * BigInt is happy to convert things that are not numbers at all -
+ * `BigInt('')` is 0n because an empty string reads as zero, `BigInt(true)`
+ * is 1n - so a bad value in a bigint column used to land as a plausible
+ * 0 or 1. Only what genuinely carries an exact integer is let through.
+ */
+export function assertBigInt(v, typeName) {
+    let n;
+    const t = typeof v;
+    if (t === 'bigint') {
+        n = v;
+    }
+    else if (t === 'number') {
+        if (!Number.isInteger(v))
+            throw new TypeError(Number.isNaN(v)
+                ? `Cannot encode value as ${typeName}: it has no integer value`
+                : `Cannot encode ${v} as ${typeName}: it is not an integer`);
+        n = BigInt(v);
+    }
+    else if (t === 'string') {
+        const s = v.trim();
+        if (!DECIMAL_INTEGER.test(s))
+            throw new TypeError(`Cannot encode "${v}" as ${typeName}: it is not an integer`);
+        n = BigInt(s);
+    }
+    else {
+        throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
+    }
+    if (n < INT8_MIN || n > INT8_MAX)
+        throw new RangeError(`Cannot encode ${n} as ${typeName}: it is out of range (${INT8_MIN} to ${INT8_MAX})`);
+    return n;
 }
 /**
  * Returns `parsed` when a value that was NOT already a number coerced to
@@ -40,19 +121,3 @@ export function assertCoercedNumber(parsed, typeName) {
     }
     return parsed;
 }
-/**
- * Refuses a value that only has an integer reading through a coercion
- * nobody asked for.
- *
- * int8 goes to `BigInt` rather than through `fastParseInt()`, and BigInt is
- * happy to convert things that are not numbers at all: `BigInt([])` is 0n
- * because an empty array stringifies to "", and `BigInt(true)` is 1n. A
- * bad value in a bigint column would land as a plausible-looking 0 or 1,
- * so only the types that genuinely carry an integer are let through.
- */
-export function assertBigIntSource(v, typeName) {
-    const t = typeof v;
-    if (t === 'bigint' || t === 'number' || t === 'string')
-        return v;
-    throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
-}

package/util/hex-text.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Writes `count` bytes of `src` into `scratch` as lowercase hex, each
+ * byte's two characters starting at `positions[i]` - so the separators
+ * a type writes between its bytes are put in once, when the scratch is
+ * built, and never again.
+ *
+ * The scratch is then read back with `latin1`, which is what the text
+ * paths of these types already use: the output is fixed-format ASCII,
+ * so it decodes identically to `utf8` and skips V8's multi-byte-sequence
+ * detection.
+ *
+ * Why not `Buffer.toString('hex')`: a type whose text has separators in
+ * it has to call that once per group and join the pieces. For `uuid`
+ * that was five calls and four concatenations per value - 25 000 strings
+ * and 20 000 concatenations for a 5 000-row column, which is more work
+ * than `pg` does for the same column despite this client reading half
+ * the bytes. Measured over 5 000 values, medians of nine runs:
+ *
+ * ```
+ * five toString + concat        1.86 ms
+ * one toString, then slice      0.81 ms
+ * a byte -> two-char table      0.64 ms
+ * this                          0.33 ms
+ * ```
+ */
+export declare function writeHexBytes(scratch: Buffer, positions: number[], src: Buffer, offset: number, count: number): void;

package/util/hex-text.js

@@ -0,0 +1,38 @@
+/** `0`-`f` as bytes, so a nibble indexes straight into it. */
+const HEX = Buffer.from('0123456789abcdef', 'latin1');
+/**
+ * Writes `count` bytes of `src` into `scratch` as lowercase hex, each
+ * byte's two characters starting at `positions[i]` - so the separators
+ * a type writes between its bytes are put in once, when the scratch is
+ * built, and never again.
+ *
+ * The scratch is then read back with `latin1`, which is what the text
+ * paths of these types already use: the output is fixed-format ASCII,
+ * so it decodes identically to `utf8` and skips V8's multi-byte-sequence
+ * detection.
+ *
+ * Why not `Buffer.toString('hex')`: a type whose text has separators in
+ * it has to call that once per group and join the pieces. For `uuid`
+ * that was five calls and four concatenations per value - 25 000 strings
+ * and 20 000 concatenations for a 5 000-row column, which is more work
+ * than `pg` does for the same column despite this client reading half
+ * the bytes. Measured over 5 000 values, medians of nine runs:
+ *
+ * ```
+ * five toString + concat        1.86 ms
+ * one toString, then slice      0.81 ms
+ * a byte -> two-char table      0.64 ms
+ * this                          0.33 ms
+ * ```
+ */
+export function writeHexBytes(scratch, positions, src, offset, count) {
+    let i;
+    let p;
+    let b;
+    for (i = 0; i < count; i++) {
+        p = positions[i];
+        b = src[offset + i];
+        scratch[p] = HEX[b >> 4];
+        scratch[p + 1] = HEX[b & 15];
+    }
+}

package/util/local-date.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The local `Date` whose wall clock reads what `ms` reads in UTC.
+ *
+ * `timestamp`, `date` and `time` carry no zone: the server sends a wall
+ * clock and the client decides which one it names. With `utcDates` off -
+ * the default - that is the local one, so a `2024-06-15 10:30` column
+ * comes back as a Date reading 10:30 locally rather than the instant
+ * 10:30Z.
+ *
+ * Doing that by reading the seven `getUTC*` components off one Date and
+ * handing them to another was the most expensive thing left in the
+ * common decode path - the getters alone cost more than either Date:
+ *
+ * ```
+ * new Date(epochMs)               43.6 ns
+ * getUTC* x 7                     97.4 ns
+ * new Date(y, m, d, h, mi, s, ms) 61.7 ns
+ * ```
+ *
+ * Shifting the instant by the zone's own offset lands on the same wall
+ * clock for a fraction of that, but only where the offset is a whole
+ * number of minutes and holds either side of where the shift lands.
+ * Two guards and a floor make that exact rather than usually-right:
+ *
+ * - **The offset must survive the shift.** Where it does not, the shift
+ *   crossed a transition and the wall clock it landed on is not the one
+ *   that was asked for - or does not exist at all.
+ * - **The offset must hold for the hour before the landing too.** That
+ *   is the hour a backward transition repeats, where both instants read
+ *   the same wall clock and the shift keeps the wrong one of the two.
+ *   Pacific/Chatham found this: `2024-04-07T03:00Z` is `03:00` in both
+ *   +12:45 and +13:45, an hour apart.
+ * - **Nothing before 1970.** A zone's pre-standard offset carries
+ *   seconds - Europe/Istanbul was +01:55:52 - and `getTimezoneOffset()`
+ *   answers in whole minutes, so the shift lands up to 59 seconds off.
+ *   The tz database does not claim correctness before 1970 either.
+ *
+ * Whatever fails those goes back to the component route, which is what
+ * this has always answered. Checked against it over 1850-2040 at
+ * 90-minute steps - 1.1 million instants - in ten zones including the
+ * 45-minute and 30-minute DST ones: no disagreement, and
+ *
+ * ```
+ *                    before     after
+ * Europe/Istanbul    157.5 ns   123.0 ns
+ * America/New_York   245.6 ns   131.2 ns
+ * ```
+ *
+ * The DST zone was dearer before because V8 pays for a transition lookup
+ * on every local construction; here it pays for one instant instead.
+ */
+export declare function utcPartsAsLocal(ms: number): Date;

package/util/local-date.js

@@ -0,0 +1,69 @@
+/**
+ * The local `Date` whose wall clock reads what `ms` reads in UTC.
+ *
+ * `timestamp`, `date` and `time` carry no zone: the server sends a wall
+ * clock and the client decides which one it names. With `utcDates` off -
+ * the default - that is the local one, so a `2024-06-15 10:30` column
+ * comes back as a Date reading 10:30 locally rather than the instant
+ * 10:30Z.
+ *
+ * Doing that by reading the seven `getUTC*` components off one Date and
+ * handing them to another was the most expensive thing left in the
+ * common decode path - the getters alone cost more than either Date:
+ *
+ * ```
+ * new Date(epochMs)               43.6 ns
+ * getUTC* x 7                     97.4 ns
+ * new Date(y, m, d, h, mi, s, ms) 61.7 ns
+ * ```
+ *
+ * Shifting the instant by the zone's own offset lands on the same wall
+ * clock for a fraction of that, but only where the offset is a whole
+ * number of minutes and holds either side of where the shift lands.
+ * Two guards and a floor make that exact rather than usually-right:
+ *
+ * - **The offset must survive the shift.** Where it does not, the shift
+ *   crossed a transition and the wall clock it landed on is not the one
+ *   that was asked for - or does not exist at all.
+ * - **The offset must hold for the hour before the landing too.** That
+ *   is the hour a backward transition repeats, where both instants read
+ *   the same wall clock and the shift keeps the wrong one of the two.
+ *   Pacific/Chatham found this: `2024-04-07T03:00Z` is `03:00` in both
+ *   +12:45 and +13:45, an hour apart.
+ * - **Nothing before 1970.** A zone's pre-standard offset carries
+ *   seconds - Europe/Istanbul was +01:55:52 - and `getTimezoneOffset()`
+ *   answers in whole minutes, so the shift lands up to 59 seconds off.
+ *   The tz database does not claim correctness before 1970 either.
+ *
+ * Whatever fails those goes back to the component route, which is what
+ * this has always answered. Checked against it over 1850-2040 at
+ * 90-minute steps - 1.1 million instants - in ten zones including the
+ * 45-minute and 30-minute DST ones: no disagreement, and
+ *
+ * ```
+ *                    before     after
+ * Europe/Istanbul    157.5 ns   123.0 ns
+ * America/New_York   245.6 ns   131.2 ns
+ * ```
+ *
+ * The DST zone was dearer before because V8 pays for a transition lookup
+ * on every local construction; here it pays for one instant instead.
+ */
+export function utcPartsAsLocal(ms) {
+    if (ms >= 0) {
+        const offset = new Date(ms).getTimezoneOffset();
+        const local = new Date(ms + offset * 60000);
+        if (local.getTimezoneOffset() === offset &&
+            new Date(local.getTime() - 3600000).getTimezoneOffset() === offset)
+            return local;
+    }
+    const utc = new Date(ms);
+    const year = utc.getUTCFullYear();
+    const local = new Date(year, utc.getUTCMonth(), utc.getUTCDate(), utc.getUTCHours(), utc.getUTCMinutes(), utc.getUTCSeconds(), utc.getUTCMilliseconds());
+    // `new Date(44, 2, 15)` means 1944 - the constructor's own century
+    // rule, which is not what a server sending `0044-03-15` meant. It only
+    // reaches values this old, which take this route anyway.
+    if (year >= 0 && year <= 99)
+        local.setFullYear(year);
+    return local;
+}

package/util/stringify-arrayliteral.js

@@ -1,4 +1,20 @@
 import { arrayCalculateDim } from './array-calculatedim.js';
+/**
+ * What a number's own text looks like: digits, one optional dot, an
+ * optional exponent, an optional leading minus. Nothing in it is special
+ * to the array literal grammar and it cannot be read as `NULL`, so an
+ * element that matches goes out bare - `{1,2}` rather than `{"1","2"}`,
+ * which is what the server itself prints and what every other client
+ * writes.
+ *
+ * Deliberately narrower than "has no special characters": it is applied
+ * only to what a JS number or bigint encoded to, and matching it is the
+ * evidence that the encoder really did produce a number's text. `NaN`
+ * and `Infinity` fail it and stay quoted (both forms parse the same, so
+ * this costs nothing), and so does anything an unexpected encoder made
+ * of a number - a date type handed a timestamp, say.
+ */
+const BARE_NUMBER = /^-?\d+(\.\d+)?([eE][-+]?\d+)?$/;
 export function stringifyArrayLiteral(value, options, encode) {
     const dim = arrayCalculateDim(value);
     // `dim` is built once above and never mutated, so its last index is
@@ -9,19 +25,24 @@ export function stringifyArrayLiteral(value, options, encode) {
     const lastLevel = dim.length - 1;
     const writeDim = (arr, level) => {
         const elemCount = dim[level];
-        const out = [];
         const isLeafLevel = level >= lastLevel;
+        // Concatenated rather than collected and joined: V8 builds a rope
+        // and flattens it once, where an array of one string per element is
+        // a second allocation per element before the join sees any of them.
+        let out = '{';
         for (let i = 0; i < elemCount; i++) {
+            if (i)
+                out += ',';
             let x = arr && arr[i];
             if (!isLeafLevel) {
                 if (x != null && !Array.isArray(x))
                     x = [x];
-                out.push(writeDim(x, level + 1));
+                out += writeDim(x, level + 1);
                 continue;
             }
             // if value is null
             if (x == null) {
-                out.push('NULL');
+                out += 'NULL';
                 continue;
             }
             /* c8 ignore start - dim is (re)computed above from a DFS that visits
@@ -29,18 +50,32 @@ export function stringifyArrayLiteral(value, options, encode) {
                can never actually be an array once `level` reaches the leaf -
                if it were, dim would already have gone one level deeper there. */
             if (Array.isArray(x)) {
-                out.push(stringifyArrayLiteral(x, options, encode));
+                out += stringifyArrayLiteral(x, options, encode);
                 continue;
             }
             /* c8 ignore stop */
+            // Asked before the encoder runs, so the test below is only ever
+            // applied to a value that really was a number.
+            const isNumber = typeof x === 'number' || typeof x === 'bigint';
             if (encode)
                 x = encode(x, options || {});
-            out.push(escapeArrayItem('' + x));
+            const s = '' + x;
+            out += isNumber && BARE_NUMBER.test(s) ? s : escapeArrayItem(s);
         }
-        return '{' + out.join(',') + '}';
+        return out + '}';
     };
     return writeDim(value, 0);
 }
+/**
+ * Backslash and double quote are the only two characters the literal
+ * grammar gives meaning to inside a quoted element, and neither is in
+ * most values - so they are looked for before anything is rewritten. The
+ * two `replace()` calls each walk the string and build another one even
+ * when they change nothing, which for a column of ordinary text was
+ * half the cost of writing the literal.
+ */
 function escapeArrayItem(str) {
-    return '"' + str.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+    return str.indexOf('\\') < 0 && str.indexOf('"') < 0
+        ? '"' + str + '"'
+        : '"' + str.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
 }

package/util/unspecified-param.d.ts

@@ -36,7 +36,31 @@
  * or of one of this client's own classes has one type it can be, so
  * naming it says nothing the server would have decided differently -
  * and it keeps the binary encoding, which the text literal gives up.
- * A caller who wants that back for a large numeric array names the type
- * with `new BindParam(DataTypeOIDs._float8, v)`.
+ *
+ * What that giving up costs, which the commit making this change put at
+ * nothing measurable and is not: inserting the same value over a
+ * loopback connection, alternating within each round, medians of nine -
+ *
+ * ```
+ *                  as text   as BindParam
+ * float8[]  1 000   2.33ms       0.91ms    2.6x
+ * float8[] 10 000  17.34ms       3.75ms    4.6x
+ * float8[] 100 000  143.0ms      26.9ms    5.3x
+ * int4[]   100 000   24.5ms      15.5ms    1.6x
+ * ```
+ *
+ * It grows with the array and with how wide an element's text is
+ * against its binary: a float8 is 8 bytes against about 19 characters,
+ * an int4 is 4 against up to 11 - and most of what a float8[] costs is
+ * the server's own parse of that text, not the writing of it. The
+ * original measurement was of the smallest of these shapes and read it
+ * as level; it is not, at any size.
+ *
+ * So this is a real price, paid for a correctness the client cannot buy
+ * any other way before the server has spoken. A caller who knows the
+ * column - and for a large numeric array that is worth knowing - names
+ * the type with `new BindParam(DataTypeOIDs._float8, v)` and gets the
+ * binary encoding back with nothing given up, since a named type is an
+ * answer rather than a guess.
  */
 export declare function isUnspecifiedParam(v: any): boolean;

package/util/unspecified-param.js

@@ -37,8 +37,32 @@ import { arrayLeaf } from './array-leaf.js';
  * or of one of this client's own classes has one type it can be, so
  * naming it says nothing the server would have decided differently -
  * and it keeps the binary encoding, which the text literal gives up.
- * A caller who wants that back for a large numeric array names the type
- * with `new BindParam(DataTypeOIDs._float8, v)`.
+ *
+ * What that giving up costs, which the commit making this change put at
+ * nothing measurable and is not: inserting the same value over a
+ * loopback connection, alternating within each round, medians of nine -
+ *
+ * ```
+ *                  as text   as BindParam
+ * float8[]  1 000   2.33ms       0.91ms    2.6x
+ * float8[] 10 000  17.34ms       3.75ms    4.6x
+ * float8[] 100 000  143.0ms      26.9ms    5.3x
+ * int4[]   100 000   24.5ms      15.5ms    1.6x
+ * ```
+ *
+ * It grows with the array and with how wide an element's text is
+ * against its binary: a float8 is 8 bytes against about 19 characters,
+ * an int4 is 4 against up to 11 - and most of what a float8[] costs is
+ * the server's own parse of that text, not the writing of it. The
+ * original measurement was of the smallest of these shapes and read it
+ * as level; it is not, at any size.
+ *
+ * So this is a real price, paid for a correctness the client cannot buy
+ * any other way before the server has spoken. A caller who knows the
+ * column - and for a large numeric array that is worth knowing - names
+ * the type with `new BindParam(DataTypeOIDs._float8, v)` and gets the
+ * binary encoding back with nothing given up, since a named type is an
+ * answer rather than a guess.
  */
 export function isUnspecifiedParam(v) {
     const x = arrayLeaf(v);