postgrejs 3.9.0 → 3.10.1

package/package.json

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

package/util/connection-config.js

@@ -1,12 +1,66 @@
 import { merge } from '@jsopen/objects';
 import { configFromEnv } from './config-from-env.js';
+/**
+ * Spellings from other clients that mean something here under a
+ * different name.
+ *
+ * Nothing checks that a configuration's keys are keys this client knows,
+ * and it deliberately stays that way: a `PoolConfiguration` carries
+ * `lightning-pool`'s own options, which are not declared here, and
+ * callers pass configurations that carry their own fields. An allowlist
+ * would reject those, and would have to be kept current forever.
+ *
+ * What is caught instead is the short list of names that are *wrong* -
+ * each is the right idea under another client's spelling, so it can be
+ * answered with the name that works rather than merely refused.
+ */
+const FOREIGN_KEYS = {
+    connection_string: 'connectionString',
+    connectionUri: 'connectionString',
+    uri: 'connectionString',
+    url: 'connectionString',
+    dbname: 'database',
+    db: 'database',
+    username: 'user',
+    pass: 'password',
+    passwd: 'password',
+    hostname: 'host',
+    application_name: 'applicationName',
+    connect_timeout: 'connectTimeoutMs',
+    connectionTimeoutMillis: 'connectTimeoutMs',
+};
+function checkForeignKeys(config) {
+    let k;
+    for (k in config) {
+        const meant = FOREIGN_KEYS[k];
+        if (meant && config[k] !== undefined)
+            throw new TypeError(`"${k}" is not a connection option here - did you mean "${meant}"? ` +
+                'An option this client does not know is otherwise ignored, so a ' +
+                'name that is nearly right does nothing and says nothing.');
+    }
+}
 export function getConnectionConfig(config) {
     const cfg = configFromEnv();
     if (typeof config === 'string') {
         merge(cfg, parseConnectionString(config));
     }
     else if (typeof config === 'object') {
+        checkForeignKeys(config);
         merge(cfg, config);
+        // `pg`'s spelling of the same thing, and what `drizzle-orm`'s first
+        // example writes - so it is the single most likely key someone
+        // moving from `pg` puts here. Ignored, it did not fail: it connected
+        // to whatever the environment defaults to, which in development is
+        // usually a database that exists, so the mistake surfaced as missing
+        // tables or as writes landing somewhere else. Applied after the
+        // merge and not before it, because `pg` lets the string win over the
+        // fields beside it.
+        const cs = cfg.connectionString;
+        if (cs !== undefined) {
+            delete cfg.connectionString;
+            if (cs)
+                merge(cfg, parseConnectionString('' + cs));
+        }
     }
     if (cfg.host) {
         const explicitRequireSSL = cfg.requireSSL;
@@ -61,6 +115,16 @@ function splitHosts(value, fallbackPort) {
         return { host: entry, port: fallbackPort };
     });
 }
+/**
+ * The schemes whose path is the database name.
+ *
+ * PostgreSQL gives two URI forms of its own, `postgres://` and
+ * `postgresql://`, and the longer one is what Prisma, TypeORM and most
+ * tutorials write - it was missing here, so a string naming a database
+ * connected to the default one instead, with nothing reported. `pg:`
+ * has been accepted for longer than either and stays.
+ */
+const DATABASE_PATH_SCHEMES = ['pg:', 'postgres:', 'postgresql:'];
 export function parseConnectionString(str) {
     if (str.startsWith('/'))
         str = 'socket:/' + str;
@@ -89,7 +153,7 @@ export function parseConnectionString(str) {
         if (parsed.searchParams.get('db'))
             cfg.database = decodeURI(getFirst(parsed.searchParams.get('db')));
     }
-    else if (parsed.protocol === 'pg:' || parsed.protocol === 'postgres:') {
+    else if (DATABASE_PATH_SCHEMES.includes(parsed.protocol)) {
         if (parsed.pathname)
             cfg.database = decodeURI(parsed.pathname.substring(1));
     }

package/util/decimal-as-string.d.ts

@@ -0,0 +1,11 @@
+import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
+import type { Maybe, OID } from '../types.js';
+/**
+ * The types that can decode to an exact decimal string: the two that
+ * carry a decimal the wire format states exactly, rather than a double's
+ * nearest approximation of one.
+ */
+export declare const DecimalAsStringOIDs: readonly OID[];
+/** Whether this type's values are wanted as their exact decimal string. */
+export declare function wantsDecimalString(options: Maybe<DataMappingOptions>, oid: OID): boolean;
+export declare function validateDecimalAsString(v: Maybe<boolean | OID[]>): void;

package/util/decimal-as-string.js

@@ -0,0 +1,30 @@
+import { DataTypeNames, DataTypeOIDs } from '../constants.js';
+/**
+ * The types that can decode to an exact decimal string: the two that
+ * carry a decimal the wire format states exactly, rather than a double's
+ * nearest approximation of one.
+ */
+export const DecimalAsStringOIDs = Object.freeze([
+    DataTypeOIDs.numeric,
+    DataTypeOIDs.money,
+]);
+/** Whether this type's values are wanted as their exact decimal string. */
+export function wantsDecimalString(options, oid) {
+    const v = options?.decimalAsString;
+    if (v === undefined || v === false)
+        return false;
+    return v === true || v.includes(oid);
+}
+export function validateDecimalAsString(v) {
+    if (v === undefined || typeof v === 'boolean')
+        return;
+    if (!Array.isArray(v))
+        throw new TypeError('`decimalAsString` is either a boolean or an array of OIDs, not ' +
+            typeof v);
+    const l = v.length;
+    let i;
+    for (i = 0; i < l; i++)
+        if (!DecimalAsStringOIDs.includes(v[i]))
+            throw new TypeError('`decimalAsString` accepts only numeric (1700) and money (790). ' +
+                `Received ${v[i]}${DataTypeNames[v[i]] ? ' (' + DataTypeNames[v[i]] + ')' : ''}.`);
+}

package/util/fetch-as-string.d.ts

@@ -0,0 +1,33 @@
+import type { DataTypeMap } from '../data-type-map.js';
+import type { FetchAsStringItem } from '../interfaces/data-mapping-options.js';
+import type { Maybe, OID } from '../types.js';
+/**
+ * What `fetchAsString`'s entries mean, in one place - three call sites
+ * read the list and they have to agree: the Bind's result format codes
+ * (resolve-column-formats.ts), the parser chosen for each column
+ * (get-parsers.ts), and whether a cached set of parsers was built for
+ * the same ask (fetchAsStringEqual, below).
+ */
+/** Whether the list names this OID itself, in either form. */
+export declare function fetchAsStringNamesOid(list: Maybe<FetchAsStringItem[]>, oid: OID): boolean;
+/**
+ * Whether the list names the element type of an array column, and lets
+ * that reach the array - `{ oid, arrays: false }` is how a caller asks
+ * for a scalar column as text and leaves its array columns decoding.
+ *
+ * `numeric` is why: `pg` hands back a scalar `numeric` as a string and a
+ * `numeric[]` as numbers, so reproducing it needs the two said
+ * separately.
+ */
+export declare function fetchAsStringNamesElement(list: Maybe<FetchAsStringItem[]>, elementsOID: OID): boolean;
+/** Whether two lists select the same columns the same way. */
+export declare function fetchAsStringEqual(a: Maybe<FetchAsStringItem[]>, b: Maybe<FetchAsStringItem[]>): boolean;
+/**
+ * Refuses a selector that asks for something this does not do, rather
+ * than quietly not doing it.
+ *
+ * Checked once per list object, which is what a connection-level default
+ * or a module-level constant is; an inline list is a walk of a handful
+ * of entries.
+ */
+export declare function validateFetchAsString(list: Maybe<FetchAsStringItem[]>, typeMap?: Maybe<DataTypeMap>): void;

package/util/fetch-as-string.js

@@ -0,0 +1,122 @@
+import { DataTypeNames } from '../constants.js';
+/**
+ * What `fetchAsString`'s entries mean, in one place - three call sites
+ * read the list and they have to agree: the Bind's result format codes
+ * (resolve-column-formats.ts), the parser chosen for each column
+ * (get-parsers.ts), and whether a cached set of parsers was built for
+ * the same ask (fetchAsStringEqual, below).
+ */
+/** Whether the list names this OID itself, in either form. */
+export function fetchAsStringNamesOid(list, oid) {
+    if (!list)
+        return false;
+    const l = list.length;
+    let i;
+    let item;
+    for (i = 0; i < l; i++) {
+        item = list[i];
+        if (typeof item === 'number' ? item === oid : item.oid === oid)
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether the list names the element type of an array column, and lets
+ * that reach the array - `{ oid, arrays: false }` is how a caller asks
+ * for a scalar column as text and leaves its array columns decoding.
+ *
+ * `numeric` is why: `pg` hands back a scalar `numeric` as a string and a
+ * `numeric[]` as numbers, so reproducing it needs the two said
+ * separately.
+ */
+export function fetchAsStringNamesElement(list, elementsOID) {
+    if (!list)
+        return false;
+    const l = list.length;
+    let i;
+    let item;
+    for (i = 0; i < l; i++) {
+        item = list[i];
+        if (typeof item === 'number') {
+            if (item === elementsOID)
+                return true;
+        }
+        else if (item.oid === elementsOID && item.arrays !== false)
+            return true;
+    }
+    return false;
+}
+/** Whether two lists select the same columns the same way. */
+export function fetchAsStringEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return !a?.length && !b?.length;
+    const l = a.length;
+    if (l !== b.length)
+        return false;
+    let i;
+    let x;
+    let y;
+    for (i = 0; i < l; i++) {
+        x = a[i];
+        y = b[i];
+        if (x === y)
+            continue;
+        // A bare OID and a selector for the same OID are only the same ask
+        // while the selector says nothing; anything else decodes differently
+        // and must not be handed the other one's cached parsers.
+        if (typeof x === 'number' || typeof y === 'number') {
+            const num = typeof x === 'number' ? x : y;
+            const sel = (typeof x === 'number' ? y : x);
+            if (sel.oid !== num || sel.arrays === false || sel.ranges)
+                return false;
+            continue;
+        }
+        if (x.oid !== y.oid || (x.arrays === false) !== (y.arrays === false))
+            return false;
+        if (!!x.ranges !== !!y.ranges)
+            return false;
+    }
+    return true;
+}
+const _checked = new WeakSet();
+/**
+ * Refuses a selector that asks for something this does not do, rather
+ * than quietly not doing it.
+ *
+ * Checked once per list object, which is what a connection-level default
+ * or a module-level constant is; an inline list is a walk of a handful
+ * of entries.
+ */
+export function validateFetchAsString(list, typeMap) {
+    if (!list || _checked.has(list))
+        return;
+    const l = list.length;
+    let i;
+    let item;
+    for (i = 0; i < l; i++) {
+        item = list[i];
+        if (typeof item === 'number')
+            continue;
+        if (!item || typeof item.oid !== 'number')
+            throw new TypeError('`fetchAsString` takes an OID or `{ oid, arrays }`; received ' +
+                JSON.stringify(item));
+        if (item.ranges)
+            throw new TypeError('`fetchAsString` does not reach range columns through their ' +
+                "element's OID yet, so `ranges: true` would ask for something " +
+                'that will not happen. Name the range type itself instead - ' +
+                '`numrange` rather than `numeric`.');
+        // The flags say what happens to the *arrays of* the named type, so
+        // naming an array type and then talking about its arrays is not an
+        // ask anything can honour.
+        if (typeMap?.get(item.oid)?.elementsOID)
+            throw new TypeError(`\`fetchAsString\` selector ${name(item.oid)} is an array type, and ` +
+                'the flags describe what happens to a type’s array columns. ' +
+                'Name the element type instead, or list the array OID on its own.');
+    }
+    _checked.add(list);
+}
+function name(oid) {
+    return DataTypeNames[oid] ? `${oid} (${DataTypeNames[oid]})` : String(oid);
+}

package/util/get-parsers.js

@@ -1,5 +1,6 @@
 import { DataFormat } from '../constants.js';
 import { decodeBinaryArray } from './decode-binaryarray.js';
+import { fetchAsStringNamesElement, fetchAsStringNamesOid, } from './fetch-as-string.js';
 import { parsePostgresArray } from './parse-array.js';
 const DefaultColumnParser = (data, offset, len) => data.subarray(offset, offset + len);
 const DefaultTextColumnParser = (data, offset, len) => data.toString('utf8', offset, offset + len);
@@ -21,11 +22,27 @@ export function getParsers(typeMap, fields, mappingOptions) {
         // then the registered decoder is the only thing that can read it.
         if (asString &&
             f.format === DataFormat.text &&
-            asString.includes(f.dataTypeId)) {
+            fetchAsStringNamesOid(asString, f.dataTypeId)) {
             parsers[i] = DefaultTextColumnParser;
             continue;
         }
         const dataTypeReg = typeMap.get(f.dataTypeId);
+        // The other half of the same ask: the list named this column's
+        // *element* type, so the literal is split and the elements are handed
+        // back as the server wrote them - an array of what naming the scalar
+        // OID gives for a scalar column. Naming the array's own OID still
+        // means the whole literal, above; the two remain tellable apart
+        // because they name different OIDs.
+        if (asString &&
+            f.format === DataFormat.text &&
+            dataTypeReg?.elementsOID &&
+            fetchAsStringNamesElement(asString, dataTypeReg.elementsOID)) {
+            const separator = dataTypeReg.arraySeparator;
+            parsers[i] = (data, offset, len) => parsePostgresArray(data.toString('utf8', offset, offset + len), {
+                separator,
+            });
+            continue;
+        }
         if (dataTypeReg) {
             const isArray = !!dataTypeReg.elementsOID;
             if (f.format === DataFormat.binary) {

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

@@ -1,7 +1,7 @@
 import type { DataTypeMap } from '../data-type-map.js';
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import { Protocol } from '../protocol/protocol.js';
-import type { Maybe, OID } from '../types.js';
+import type { Maybe } from '../types.js';
 export interface ColumnFormatOptions extends DataMappingOptions {
     columnFormat?: Protocol.DataFormat | Protocol.DataFormat[];
 }
@@ -17,18 +17,12 @@ export interface ColumnFormatOptions extends DataMappingOptions {
  * statement's, or a cached one's) pay nothing for this; callers that do
  * not have to ask for the whole row as text instead - see queryOnce().
  *
- * A column matches on its own `dataTypeId`, so an array column is only
- * ever selected by its own array OID (`_timestamptz`), never by its
- * element's. Listing the element OID leaves array columns alone.
+ * An array column is selected by its own array OID (`_timestamptz`) and
+ * by its element's (`timestamptz`) - both need the column as text, and
+ * which of the two was named is what get-parsers.ts reads to decide
+ * between the whole literal and the elements.
  *
  * Returns `columnFormat` untouched when there is nothing to do, so the
  * common case allocates nothing and keeps sending a single format code.
  */
 export declare function resolveColumnFormats(fields: Maybe<Protocol.RowDescription[]>, options: ColumnFormatOptions, typeMap?: DataTypeMap): Protocol.DataFormat | Protocol.DataFormat[];
-/**
- * Whether two `fetchAsString` lists select the same columns. Used to tell
- * a cached set of parsers apart from one built for a different list, which
- * `columnFormat` alone cannot do: an explicitly text column and one turned
- * text by fetchAsString carry the same format code but decode differently.
- */
-export declare function fetchAsStringEqual(a: Maybe<OID[]>, b: Maybe<OID[]>): boolean;

package/util/resolve-column-formats.js

@@ -1,5 +1,6 @@
 import { DEFAULT_COLUMN_FORMAT } from '../constants.js';
 import { Protocol } from '../protocol/protocol.js';
+import { fetchAsStringNamesElement, fetchAsStringNamesOid, } from './fetch-as-string.js';
 const DataFormat = Protocol.DataFormat;
 /**
  * Whether this client could read the column if it arrived in `format`.
@@ -13,6 +14,18 @@ function canDecode(typeMap, oid, format) {
     const reg = typeMap.get(oid);
     return !!reg && typeof reg.decodeBinary === 'function';
 }
+/**
+ * Whether `asString` names the element type of the array type `oid` -
+ * "give me this type verbatim", asked of a column of them.
+ *
+ * Needs the type map to find the element OID, which the caller already
+ * hands over for `unknownTypesAsString`; without one this answers no and
+ * only an array's own OID selects it, as it always did.
+ */
+function namesElementOf(typeMap, asString, oid) {
+    const elementsOID = typeMap?.get(oid)?.elementsOID;
+    return !!elementsOID && fetchAsStringNamesElement(asString, elementsOID);
+}
 /**
  * Turns `fetchAsString`'s OID list into the positional result format codes
  * a Bind message actually carries.
@@ -25,9 +38,10 @@ function canDecode(typeMap, oid, format) {
  * statement's, or a cached one's) pay nothing for this; callers that do
  * not have to ask for the whole row as text instead - see queryOnce().
  *
- * A column matches on its own `dataTypeId`, so an array column is only
- * ever selected by its own array OID (`_timestamptz`), never by its
- * element's. Listing the element OID leaves array columns alone.
+ * An array column is selected by its own array OID (`_timestamptz`) and
+ * by its element's (`timestamptz`) - both need the column as text, and
+ * which of the two was named is what get-parsers.ts reads to decide
+ * between the whole literal and the elements.
  *
  * Returns `columnFormat` untouched when there is nothing to do, so the
  * common case allocates nothing and keeps sending a single format code.
@@ -58,10 +72,16 @@ export function resolveColumnFormats(fields, options, typeMap) {
         format = baseIsArray
             ? (base[i] ?? DEFAULT_COLUMN_FORMAT)
             : base;
-        if (named && asString.includes(oid)) {
+        if (named &&
+            (fetchAsStringNamesOid(asString, oid) ||
+                namesElementOf(typeMap, asString, oid))) {
             // fetchAsString names the value the caller wants verbatim, so it
             // overrides an explicit columnFormat for its own columns - the two
             // cannot both be honored and the OID list is the more specific ask.
+            // An array column is selected either way: by its own OID, which
+            // asks for the whole literal, or by its element's, which asks for
+            // the elements - both need the column as text, and get-parsers.ts
+            // is where the two part company.
             format = DataFormat.text;
             hit = true;
         }
@@ -76,23 +96,3 @@ export function resolveColumnFormats(fields, options, typeMap) {
     }
     return hit ? out : base;
 }
-/**
- * Whether two `fetchAsString` lists select the same columns. Used to tell
- * a cached set of parsers apart from one built for a different list, which
- * `columnFormat` alone cannot do: an explicitly text column and one turned
- * text by fetchAsString carry the same format code but decode differently.
- */
-export function fetchAsStringEqual(a, b) {
-    if (a === b)
-        return true;
-    if (!a || !b)
-        return !a?.length && !b?.length;
-    const l = a.length;
-    if (l !== b.length)
-        return false;
-    let i;
-    for (i = 0; i < l; i++)
-        if (a[i] !== b[i])
-            return false;
-    return true;
-}

package/util/stringify-for-sql.js

@@ -14,11 +14,12 @@ export function stringifyArrayForSQL(v, options, encode) {
  * registered `encodeText()` that writes exactly the literal PostgreSQL
  * reads back, and `determine()` already knows which type each one is -
  * it is what the same value is sent as when it is bound as a parameter.
- * Without asking, all of them became `::json`, and since these classes
- * have a `toJSON()` returning their own literal the result was not even
- * a JSON object but a JSON string holding one, which casts to nothing:
- * `'"(1,2)"'::json` where `'(1,2)'::point` was meant. A Date became its
- * ISO string and a Buffer leaked its bytes as `{"type":"Buffer",...}`.
+ * Without asking, all of them became `::json`: `'{"x":1,"y":2}'::json`
+ * where `'(1,2)'::point` was meant - a JSON object that casts to no
+ * geometric type at all, and which back when these classes had a
+ * `toJSON()` of their own was not even that, but a JSON string holding
+ * the literal. A Date became its ISO string and a Buffer leaked its
+ * bytes as `{"type":"Buffer",...}`.
  */
 function stringifyObjectForSQL(v, options) {
     // determine() throws for a class that must carry a type OID and does

package/util/temporal.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reaching the `Temporal` the application provides, without depending on
+ * one.
+ *
+ * No runtime ships Temporal yet - Node 24.15 and Bun 1.3.10 both answer
+ * `undefined`, with or without `--harmony` - so today every caller that
+ * turns `temporalTypes` on has installed a polyfill. That is why this is
+ * read off `globalThis` when it is needed rather than imported: this
+ * package takes no dependency, a polyfill loaded after this module is
+ * still seen, and the day a runtime ships Temporal nothing here changes.
+ */
+/**
+ * The parts of `Temporal` this client calls. Deliberately untyped past
+ * the names: the shape cannot be checked against a global that may not
+ * exist, so the presence check below is the check.
+ */
+export interface TemporalApi {
+    Instant: any;
+    PlainDate: any;
+    PlainDateTime: any;
+    PlainTime: any;
+    Duration: any;
+    ZonedDateTime: any;
+}
+/**
+ * The runtime's `Temporal`, or an error saying how to get one.
+ *
+ * Called when a type map is built - which for a connection is while it
+ * is being constructed - so a missing Temporal is reported before any
+ * I/O rather than in the middle of decoding a row.
+ */
+export declare function getTemporal(): TemporalApi;
+/**
+ * The zone a `timestamptz` is printed in when the caller named none.
+ *
+ * Only the printing: a timestamptz is an absolute instant and arrives as
+ * one, so the zone decides what wall clock the ZonedDateTime shows and
+ * nothing about which moment it is.
+ */
+export declare function systemTimeZone(): string;
+/**
+ * Checks a zone name before it is handed to Temporal, so the complaint
+ * names the setting it came from instead of surfacing from inside a
+ * decode. `Intl` accepts exactly what Temporal does and is here whether
+ * Temporal is or not.
+ */
+export declare function requireTimeZone(zone: string, where: string): string;

package/util/temporal.js

@@ -0,0 +1,61 @@
+/**
+ * Reaching the `Temporal` the application provides, without depending on
+ * one.
+ *
+ * No runtime ships Temporal yet - Node 24.15 and Bun 1.3.10 both answer
+ * `undefined`, with or without `--harmony` - so today every caller that
+ * turns `temporalTypes` on has installed a polyfill. That is why this is
+ * read off `globalThis` when it is needed rather than imported: this
+ * package takes no dependency, a polyfill loaded after this module is
+ * still seen, and the day a runtime ships Temporal nothing here changes.
+ */
+let _systemTimeZone;
+const _knownZones = new Set();
+/**
+ * The runtime's `Temporal`, or an error saying how to get one.
+ *
+ * Called when a type map is built - which for a connection is while it
+ * is being constructed - so a missing Temporal is reported before any
+ * I/O rather than in the middle of decoding a row.
+ */
+export function getTemporal() {
+    const t = globalThis.Temporal;
+    if (!t || !t.ZonedDateTime)
+        throw new Error('Temporal is not available in this runtime. postgrejs reads ' +
+            'globalThis.Temporal and takes no dependency of its own: install ' +
+            '`temporal-polyfill` and import it before connecting, or leave ' +
+            '`temporalTypes` off.');
+    return t;
+}
+/**
+ * The zone a `timestamptz` is printed in when the caller named none.
+ *
+ * Only the printing: a timestamptz is an absolute instant and arrives as
+ * one, so the zone decides what wall clock the ZonedDateTime shows and
+ * nothing about which moment it is.
+ */
+export function systemTimeZone() {
+    if (_systemTimeZone === undefined)
+        _systemTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return _systemTimeZone;
+}
+/**
+ * Checks a zone name before it is handed to Temporal, so the complaint
+ * names the setting it came from instead of surfacing from inside a
+ * decode. `Intl` accepts exactly what Temporal does and is here whether
+ * Temporal is or not.
+ */
+export function requireTimeZone(zone, where) {
+    if (_knownZones.has(zone))
+        return zone;
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: zone });
+    }
+    catch {
+        throw new Error(`"${zone}" (${where}) is not a time zone this runtime knows, so a ` +
+            'timestamptz cannot be given one. Pass `timeZone` in the mapping ' +
+            'options to name one yourself.');
+    }
+    _knownZones.add(zone);
+    return zone;
+}

package/util/unspecified-param.d.ts

@@ -20,8 +20,23 @@
  * as it does under `pg`. A cast (`$1::text`) or a named type
  * (`new BindParam(DataTypeOIDs.varchar, v)`) says which type is meant.
  *
- * Numbers, booleans and Buffers keep their declared types: they are
- * already right nearly everywhere, and sending them as text would give
- * up the binary encoding for no correctness gain.
+ * - An array of numbers is the same question, and the answer matters
+ *   more: `[1, 2]` is `int2[]`, `int4[]`, `int8[]`, `numeric[]`,
+ *   `float4[]` or `float8[]` depending on where it lands, and unlike
+ *   their scalars those types have no operators or implicit casts
+ *   between them. A declared `int4[]` is therefore not merely a guess
+ *   but a wrong answer wherever the column is one of the other five:
+ *   `array[1,2]::int8[] = $1` is `42883 operator does not exist:
+ *   bigint[] = integer[]`, and `numeric[] = double precision[]` the
+ *   same. The scalars are left declared because they do have those
+ *   operators - `1::int8 = $1` and `1.5::numeric = $1` both resolve.
+ *
+ * A scalar number, a boolean, a Buffer, and an array of anything but
+ * numbers keep their declared types: an array of booleans, of Buffers
+ * 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)`.
  */
 export declare function isUnspecifiedParam(v: any): boolean;

package/util/unspecified-param.js

@@ -21,11 +21,28 @@ import { arrayLeaf } from './array-leaf.js';
  * as it does under `pg`. A cast (`$1::text`) or a named type
  * (`new BindParam(DataTypeOIDs.varchar, v)`) says which type is meant.
  *
- * Numbers, booleans and Buffers keep their declared types: they are
- * already right nearly everywhere, and sending them as text would give
- * up the binary encoding for no correctness gain.
+ * - An array of numbers is the same question, and the answer matters
+ *   more: `[1, 2]` is `int2[]`, `int4[]`, `int8[]`, `numeric[]`,
+ *   `float4[]` or `float8[]` depending on where it lands, and unlike
+ *   their scalars those types have no operators or implicit casts
+ *   between them. A declared `int4[]` is therefore not merely a guess
+ *   but a wrong answer wherever the column is one of the other five:
+ *   `array[1,2]::int8[] = $1` is `42883 operator does not exist:
+ *   bigint[] = integer[]`, and `numeric[] = double precision[]` the
+ *   same. The scalars are left declared because they do have those
+ *   operators - `1::int8 = $1` and `1.5::numeric = $1` both resolve.
+ *
+ * A scalar number, a boolean, a Buffer, and an array of anything but
+ * numbers keep their declared types: an array of booleans, of Buffers
+ * 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)`.
  */
 export function isUnspecifiedParam(v) {
     const x = arrayLeaf(v);
-    return typeof x === 'string' || x instanceof Date;
+    if (typeof x === 'string' || x instanceof Date)
+        return true;
+    return Array.isArray(v) && (typeof x === 'number' || typeof x === 'bigint');
 }