postgrejs 3.11.1 → 3.12.0

package/CHANGELOG.md

@@ -1,6 +1,33 @@
 ## Changelog
 
-### [v3.11.1](https://github.com/panates/postgrejs/compare/v3.11.0...v3.11.1) - 
+### [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
 

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/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/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/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.1",
+  "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/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);