postgrejs 3.12.1 → 3.13.0

package/README.md

@@ -62,7 +62,7 @@ PostgreJS is a driver, not a framework, so what you build on top of it stays you
       <a href="https://www.sqbjs.org"><img src="https://www.postgrejs.com/img/sqb-logo.svg" alt="SQB" height="60"></a><br><br>
       <b><a href="https://www.sqbjs.org">SQB</a></b><br>
       <a href="https://www.npmjs.com/package/@sqb/postgres"><code>@sqb/postgres</code></a><br>
-      <sub>native driver</sub>
+      <sub>first-party adapter</sub>
     </td>
     <td align="center" width="230" valign="top">
       <a href="https://kysely.dev"><img src="https://www.postgrejs.com/img/kysely-logo.svg" alt="Kysely" height="60"></a><br><br>

package/connection/connection.js

@@ -5,7 +5,7 @@ import { withAbortSignal } from '../util/abort-signal.js';
 import { normalizeChannelName } from '../util/channel-name.js';
 import { escapeIdentifier } from '../util/escape-identifier.js';
 import { QueryRequest } from '../util/sql-tag.js';
-import { isUnspecifiedParam } from '../util/unspecified-param.js';
+import { isUnspecifiedParam, needsNumericParam, } from '../util/unspecified-param.js';
 import { BindParam } from './bind-param.js';
 import { IntlConnection } from './intl-connection.js';
 import { LargeObject, LargeObjectMode } from './large-object.js';
@@ -807,7 +807,12 @@ export class Connection extends SafeEventEmitter {
                 // out as is written in getBindMessage().
                 isUnspecifiedParam(prm)
                     ? 0
-                    : typeMap.determine(prm));
+                    : // A non-integer is declared numeric rather than the float8
+                        // its value suggests - see `needsNumericParam()` for the
+                        // cast that makes the difference, and what it costs.
+                        needsNumericParam(prm)
+                            ? DataTypeOIDs.numeric
+                            : typeMap.determine(prm));
         // A money parameter is written as an int64 of minor units, so the
         // scale has to be known before the Bind goes out - the probe fired
         // at connect answers in time for every result, but not necessarily

package/connection/intl-connection.d.ts

@@ -24,6 +24,7 @@ import { CopyFromStream, CopyToStream } from './copy-stream.js';
 interface PreparedCacheEntry {
     name: string;
     fields?: Protocol.RowDescription[];
+    resolvedParamTypes?: OID[];
 }
 /** See IntlConnection._decodeDeferredRows(). */
 interface DeferredRows {

package/connection/intl-connection.js

@@ -15,6 +15,7 @@ import { escapeLiteral } from '../util/escape-literal.js';
 import { fetchAsStringEqual, fetchAsStringNamesElement, fetchAsStringNamesOid, validateFetchAsString, } from '../util/fetch-as-string.js';
 import { getParsers } from '../util/get-parsers.js';
 import { resolveColumnFormats } from '../util/resolve-column-formats.js';
+import { resolvedBindTypes } from '../util/resolved-bind-type.js';
 import { dataRowBytes, resolveRowDecoder, resolveRowType, } from '../util/row-decoder.js';
 import { requireTimeZone } from '../util/temporal.js';
 import { isTransactionCommand, refusesSavepoint, } from '../util/transaction-command.js';
@@ -983,7 +984,7 @@ export class IntlConnection extends SafeEventEmitter {
             this._preparedCache.delete(key);
             this._preparedCache.set(key, cached);
             try {
-                return await this.executeReused(cached.name, cached.fields, paramTypes, params, options, savepoint);
+                return await this.executeReused(cached.name, cached.fields, resolvedBindTypes(paramTypes, params, cached.resolvedParamTypes), params, options, savepoint);
             }
             catch (e) {
                 if (!isStaleCachedPlan(e))
@@ -1052,8 +1053,8 @@ export class IntlConnection extends SafeEventEmitter {
     _prepareForCache(key, sql, paramTypes) {
         const name = 'C_' + ++this._preparedCounter;
         return (async () => {
-            const { fields } = await this.prepareOnce(sql, paramTypes, name);
-            const entry = { name, fields };
+            const { fields, resolvedParamTypes } = await this.prepareOnce(sql, paramTypes, name);
+            const entry = { name, fields, resolvedParamTypes };
             await this._evictPreparedIfFull();
             this._preparedCache.set(key, entry);
             return entry;

package/constants.d.ts

@@ -1,6 +1,6 @@
 import { Protocol } from './protocol/protocol.js';
 import DataFormat = Protocol.DataFormat;
-export declare const version = "3.12.1";
+export declare const version = "3.13.0";
 export { DataFormat };
 /**
  * What columns come back in unless something asks otherwise.

package/constants.js

@@ -2,7 +2,7 @@ import { Protocol } from './protocol/protocol.js';
 var DataFormat = Protocol.DataFormat;
 // @ts-ignore
 Symbol.asyncDispose ??= Symbol('Symbol.asyncDispose');
-export const version = '3.12.1';
+export const version = '3.13.0';
 export { DataFormat };
 /**
  * What columns come back in unless something asks otherwise.

package/data-types/date-type.js

@@ -28,7 +28,14 @@ export const DateType = {
             ? v.getTime()
             : v.getTime() - v.getTimezoneOffset() * 60 * 1000;
         n = (n - timeShift) / 1000 / 86400;
-        const t = Math.trunc(n + Number.EPSILON);
+        /* Floor, not trunc: a date before 2000-01-01 makes `n` negative, and
+           truncation there rounds *towards* the epoch - every pre-2000
+           instant with a time of day was stored one day late, silently.
+           `1999-12-31T22:00Z` under TZ=UTC went in as 2000-01-01 where the
+           text path, and `pg`, both say 1999-12-31. The epsilon stays: it is
+           what keeps an exact midnight from landing a hair under its own
+           day and flooring to the one before. */
+        const t = Math.floor(n + Number.EPSILON);
         buf.writeInt32BE(t);
     },
     decodeBinary(v, offset = 0, _len, options) {

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.12.1",
+  "version": "3.13.0",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {
     "@jsopen/objects": "^2.3.4",
     "doublylinked": "^2.5.6",
-    "flexy-buffer": "^1.1.1",
+    "flexy-buffer": "^1.1.2",
     "lightning-pool": "^4.14.0",
     "power-tasks": "^1.14.2",
     "putil-promisify": "^1.10.1",

package/protocol/frontend.d.ts

@@ -101,7 +101,20 @@ export declare class Frontend {
     getSASLMessage(sasl: SASL.Session): Buffer;
     getSASLFinalMessage(session: SASL.Session): Buffer;
     getParseMessage(args: Frontend.ParseMessageArgs): Buffer;
-    getBindMessage(args: Frontend.BindMessageArgs): Buffer;
+    /**
+     * Bind, carrying the parameter values - the one message in a statement
+     * whose size is the caller's data rather than a few dozen bytes.
+     *
+     * @param args The portal, statement, parameters and result formats.
+     * @param copy When false, the returned buffer is a view into the
+     * shared send buffer rather than a copy of it. It stays valid only
+     * until the next message is written, so a caller passing false must
+     * consume it - `Buffer.concat()`, a write - before building anything
+     * else, and must never hand it to the socket, which does not copy
+     * synchronously.
+     * @returns The Bind message.
+     */
+    getBindMessage(args: Frontend.BindMessageArgs, copy?: boolean): Buffer;
     getDescribeMessage(args: Frontend.DescribeMessageArgs): Buffer;
     getExecuteMessage(args: Frontend.ExecuteMessageArgs): Buffer;
     getCloseMessage(args: Frontend.CloseMessageArgs): Buffer;

package/protocol/frontend.js

@@ -4,6 +4,7 @@ import { arrayLeaf } from '../util/array-leaf.js';
 import { encodeBinaryArray } from '../util/encode-binaryarray.js';
 import { formatDateParam } from '../util/format-datetime.js';
 import { writeArrayLiteral } from '../util/stringify-arrayliteral.js';
+import { resolveToPostgres, unspecifiedText, } from '../util/unspecified-value.js';
 import { Protocol } from './protocol.js';
 import { SmartBuffer } from './smart-buffer.js';
 const DataFormat = Protocol.DataFormat;
@@ -131,7 +132,28 @@ export class Frontend {
         }
         return setLengthAndFlush(io, 1);
     }
-    getBindMessage(args) {
+    /**
+     * Bind, carrying the parameter values - the one message in a statement
+     * whose size is the caller's data rather than a few dozen bytes.
+     *
+     * @param args The portal, statement, parameters and result formats.
+     * @param copy When false, the returned buffer is a view into the
+     * shared send buffer rather than a copy of it. It stays valid only
+     * until the next message is written, so a caller passing false must
+     * consume it - `Buffer.concat()`, a write - before building anything
+     * else, and must never hand it to the socket, which does not copy
+     * synchronously.
+     * @returns The Bind message.
+     */
+    /* The copy exists for buffer reuse, not for the socket: every message
+       is built in this one SmartBuffer, so message N+1's start() would
+       overwrite N's bytes before they were assembled. Nothing flushed here
+       ever reaches socket.write() - only the concat of them does, which is
+       checked in a test. So a caller that builds the small messages first
+       and this one last can take a view and let the concat read it, which
+       is one copy of the payload rather than two: measured on a 100 000
+       element int4[], 2148 KB of copying a call against 1074. */
+    getBindMessage(args, copy = true) {
         if (args.portal && args.portal.length > 63)
             throw new Error('Portal name length must be lower than 63');
         if (args.statement && args.statement.length > 63)
@@ -166,6 +188,18 @@ export class Frontend {
                 }
                 const dataTypeOid = paramTypes ? paramTypes[i] : undefined;
                 const dt = dataTypeOid ? args.typeMap.get(dataTypeOid) : undefined;
+                // No declared type: the value writes itself if it knows how, and
+                // what it hands back decides which branch below takes it - a
+                // toPostgres() returning a Date belongs in the Date branch, not
+                // in `'' + v`. A declared type is left alone; it owns its own
+                // encoding.
+                if (!dt) {
+                    v = resolveToPostgres(v);
+                    if (v === null || v === undefined) {
+                        io.writeInt32BE(-1);
+                        continue;
+                    }
+                }
                 if (dt) {
                     if (typeof dt.encodeAsNull === 'function' &&
                         dt.encodeAsNull(v, queryOptions)) {
@@ -220,7 +254,7 @@ export class Frontend {
                     io.buffer.writeInt32BE(io.size - dataOffset, dataOffset - 4); // Update length
                 }
                 else {
-                    io.writeLString('' + v, 'utf8');
+                    io.writeLString(unspecifiedText(v), 'utf8');
                 }
             }
         }
@@ -242,7 +276,7 @@ export class Frontend {
         }
         else
             io.writeUInt16BE(0);
-        return setLengthAndFlush(io, 1);
+        return setLengthAndFlush(io, 1, copy);
     }
     getDescribeMessage(args) {
         if (args.name && args.name.length > 63) {
@@ -348,7 +382,7 @@ export class Frontend {
         return StaticSyncBuffer;
     }
 }
-function setLengthAndFlush(io, lengthOffset) {
+function setLengthAndFlush(io, lengthOffset, copy = true) {
     io.buffer.writeUInt32BE(io.size - lengthOffset, lengthOffset);
-    return io.flush();
+    return io.flush(copy);
 }

package/protocol/pg-socket.js

@@ -250,23 +250,41 @@ export class PgSocket extends SafeEventEmitter {
      * statement/portal at the next Parse/Bind referencing the unnamed name.
      */
     sendExtendedQueryMessages(args, cb) {
+        /* The Bind is built LAST and taken as a view, then concatenated here
+         rather than in _send(): it carries the caller's data, where the
+         other four messages are a few dozen bytes, and the copy flush()
+         makes exists only because this one SmartBuffer is reused for the
+         next message. Building the small ones first leaves nothing to
+         overwrite it before Buffer.concat() reads it, so the payload is
+         copied once instead of twice - measured on a 100 000-element
+         int4[], 2148 KB of copying a call against 1074, with the wire bytes
+         and the stored value unchanged. The view never reaches the socket;
+         only the concat does. */
+        const parse = this._frontend.getParseMessage(args.parse);
+        const describe = this._frontend.getDescribeMessage(args.describe);
+        const execute = this._frontend.getExecuteMessage(args.execute);
+        const sync = this._frontend.getSyncMessage();
         if (!args.before && !args.after) {
-            const data = [
-                this._frontend.getParseMessage(args.parse),
-                this._frontend.getBindMessage(args.bind),
-                this._frontend.getDescribeMessage(args.describe),
-                this._frontend.getExecuteMessage(args.execute),
-                this._frontend.getSyncMessage(),
-            ];
+            const bind = this._frontend.getBindMessage(args.bind, false);
+            const data = Buffer.concat([parse, bind, describe, execute, sync]);
             return this._sendAndCapture(data, cb, 'sendExtendedQueryMessages', args);
         }
-        const data = [];
+        const before = [];
         if (args.before)
-            this._pushUtilityStatement(data, args.before, args.bind);
-        data.push(this._frontend.getParseMessage(args.parse), this._frontend.getBindMessage(args.bind), this._frontend.getDescribeMessage(args.describe), this._frontend.getExecuteMessage(args.execute));
+            this._pushUtilityStatement(before, args.before, args.bind);
+        const after = [];
         if (args.after)
-            this._pushUtilityStatement(data, args.after, args.bind);
-        data.push(this._frontend.getSyncMessage());
+            this._pushUtilityStatement(after, args.after, args.bind);
+        const bind = this._frontend.getBindMessage(args.bind, false);
+        const data = Buffer.concat([
+            ...before,
+            parse,
+            bind,
+            describe,
+            execute,
+            ...after,
+            sync,
+        ]);
         return this._sendAndCapture(data, cb, 'sendExtendedQueryMessages', args);
     }
     /**
@@ -336,21 +354,22 @@ export class PgSocket extends SafeEventEmitter {
      * auto-clears an unnamed portal at the next Bind naming it.
      */
     sendBindExecuteMessages(args, cb) {
+        // See sendExtendedQueryMessages() for why the Bind is built last.
+        const execute = this._frontend.getExecuteMessage(args.execute);
+        const sync = this._frontend.getSyncMessage();
         if (!args.before && !args.after) {
-            const data = [
-                this._frontend.getBindMessage(args.bind),
-                this._frontend.getExecuteMessage(args.execute),
-                this._frontend.getSyncMessage(),
-            ];
+            const bind = this._frontend.getBindMessage(args.bind, false);
+            const data = Buffer.concat([bind, execute, sync]);
             return this._sendAndCapture(data, cb, 'sendBindExecuteMessages', args);
         }
-        const data = [];
+        const before = [];
         if (args.before)
-            this._pushUtilityStatement(data, args.before, args.bind);
-        data.push(this._frontend.getBindMessage(args.bind), this._frontend.getExecuteMessage(args.execute));
+            this._pushUtilityStatement(before, args.before, args.bind);
+        const after = [];
         if (args.after)
-            this._pushUtilityStatement(data, args.after, args.bind);
-        data.push(this._frontend.getSyncMessage());
+            this._pushUtilityStatement(after, args.after, args.bind);
+        const bind = this._frontend.getBindMessage(args.bind, false);
+        const data = Buffer.concat([...before, bind, execute, ...after, sync]);
         return this._sendAndCapture(data, cb, 'sendBindExecuteMessages', args);
     }
     /**

package/util/resolved-bind-type.d.ts

@@ -0,0 +1,15 @@
+import type { Maybe, OID } from '../types.js';
+/**
+ * The types to encode a Bind's parameters against, given what the caller
+ * declared and what the server resolved.
+ *
+ * Returns `declared` unchanged unless some parameter can be improved, so
+ * the common call allocates nothing.
+ *
+ * @param declared What went into Parse - `0`/undefined where this client
+ * declared nothing and left the type to the server.
+ * @param params The values about to be written.
+ * @param resolved What the server answered for this statement, in order.
+ * @returns The types to hand `getBindMessage`.
+ */
+export declare function resolvedBindTypes(declared: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, resolved: Maybe<OID[]>): Maybe<Maybe<OID>[]>;

package/util/resolved-bind-type.js

@@ -0,0 +1,85 @@
+import { DataTypeOIDs } from '../constants.js';
+import { arrayLeaf } from './array-leaf.js';
+/**
+ * The types a `Date` is allowed to be encoded into binary against, by
+ * whether the value is an array.
+ */
+/* Deliberately short. `time` and `timetz` are left out because
+   TimeType.encodeBinary() multiplies the whole epoch by 1000 and
+   overflows for any ordinary Date - measured, every one of four test
+   instants answered 22008 "time out of range", where the text path
+   stores the wall clock correctly. Nothing else here may be reached
+   until it has been checked the same way. */
+const DATE_SCALARS = new Set([
+    DataTypeOIDs.timestamptz,
+    DataTypeOIDs.timestamp,
+    DataTypeOIDs.date,
+]);
+const DATE_ARRAYS = new Set([
+    DataTypeOIDs._timestamptz,
+    DataTypeOIDs._timestamp,
+    DataTypeOIDs._date,
+]);
+/**
+ * The types to encode a Bind's parameters against, given what the caller
+ * declared and what the server resolved.
+ *
+ * Returns `declared` unchanged unless some parameter can be improved, so
+ * the common call allocates nothing.
+ *
+ * @param declared What went into Parse - `0`/undefined where this client
+ * declared nothing and left the type to the server.
+ * @param params The values about to be written.
+ * @param resolved What the server answered for this statement, in order.
+ * @returns The types to hand `getBindMessage`.
+ */
+/* A Date goes out as text because nothing but the server knows whether
+   the column is an instant or a wall clock - see `isUnspecifiedParam()`.
+   Once the statement has a name, the server has already said which, and
+   saying it does not have to be repeated: a prepared statement's
+   parameter types are fixed at Parse, so a later Bind may send binary
+   against them with no re-Parse. Checked on the wire: Parse with no
+   declared types resolves `$1` to 1184, and a Bind of eight binary bytes
+   against that statement reads back correctly.
+
+   Worth it only because the text is wide and the binary is not. Measured
+   over a loopback connection, 20 000 elements:
+
+       timestamptz[]   text 625 KB / 11.61ms    binary 234 KB / 3.79ms
+
+   The same measurement is why this is not done for numbers: an int4[] of
+   ordinary values is 380 KB of text against 781 KB of binary, because
+   the binary array format carries a 4-byte length per element whatever
+   its magnitude - there, text is both smaller and twice as fast.
+
+   Binary and text store the same value, which is the thing that had to
+   be true before any of this: checked for timestamptz, timestamp and
+   date, over four instants spanning a DST boundary and including
+   milliseconds, and for the array forms of two of them. */
+export function resolvedBindTypes(declared, params, resolved) {
+    if (!resolved || !params)
+        return declared;
+    const l = params.length;
+    let out;
+    let i;
+    for (i = 0; i < l; i++) {
+        // A type the caller named is an answer, not a guess - left alone.
+        if (declared?.[i])
+            continue;
+        const oid = resolved[i];
+        if (!oid)
+            continue;
+        const v = params[i];
+        if (!(arrayLeaf(v) instanceof Date))
+            continue;
+        // An array value needs an array type and a scalar needs a scalar
+        // one: getBindMessage() picks its encoder from the type alone and
+        // would hand an array to a scalar encoder.
+        if (!(Array.isArray(v) ? DATE_ARRAYS : DATE_SCALARS).has(oid))
+            continue;
+        if (!out)
+            out = declared ? declared.slice() : new Array(l).fill(0);
+        out[i] = oid;
+    }
+    return out || declared;
+}

package/util/stringify-arrayliteral.js

@@ -1,5 +1,6 @@
 import { arrayCalculateDim } from './array-calculatedim.js';
 import { arrayLeaf } from './array-leaf.js';
+import { unspecifiedText } from './unspecified-value.js';
 /**
  * What a number's own text looks like: digits, one optional dot, an
  * optional exponent, an optional leading minus. An element that matches
@@ -66,7 +67,11 @@ export function stringifyArrayLiteral(value, options, encode) {
             const isNumber = typeof x === 'number' || typeof x === 'bigint';
             if (encode)
                 x = encode(x, options || {});
-            const s = '' + x;
+            // With an encoder the element's text is the type's to produce;
+            // without one this is an undeclared array, where a value that
+            // knows how to write itself does, and a plain object goes out as
+            // JSON rather than as `[object Object]`.
+            const s = encode ? '' + x : unspecifiedText(x);
             out += isNumber && BARE_NUMBER.test(s) ? s : escapeArrayItem(s);
         }
         return out + '}';
@@ -241,7 +246,9 @@ export function writeArrayLiteral(io, value, options, encode) {
             // of its spelling - the same rule the string path states: a
             // string's own text is quoted whatever it looks like.
             const isNumber = typeof x === 'number' || typeof x === 'bigint';
-            s = '' + x;
+            // This lane is only entered with no element encoder, so the same
+            // rules the string path applies without one apply here.
+            s = unspecifiedText(x);
             const bare = isNumber && BARE_NUMBER.test(s);
             if (!bare)
                 s =

package/util/unspecified-param.d.ts

@@ -30,6 +30,9 @@
  *   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.
+ *   That is true of the operators *inside* the numeric family and not
+ *   of the casts out of it, which is what `needsNumericParam()` below
+ *   exists for.
  *
  * A scalar number, a boolean, a Buffer, and an array of anything but
  * numbers keep their declared types: an array of booleans, of Buffers
@@ -64,3 +67,14 @@
  * answer rather than a guess.
  */
 export declare function isUnspecifiedParam(v: any): boolean;
+/**
+ * Whether a number must be declared `numeric` rather than the `float8`
+ * its value suggests.
+ *
+ * True for a finite non-integer, false for everything else - an integer,
+ * a bigint, a non-finite number, and anything that is not a number.
+ *
+ * @param v The value a parameter is about to be declared for.
+ * @returns Whether to declare `numeric` instead of asking `determine()`.
+ */
+export declare function needsNumericParam(v: any): boolean;

package/util/unspecified-param.js

@@ -31,6 +31,9 @@ import { arrayLeaf } from './array-leaf.js';
  *   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.
+ *   That is true of the operators *inside* the numeric family and not
+ *   of the casts out of it, which is what `needsNumericParam()` below
+ *   exists for.
  *
  * A scalar number, a boolean, a Buffer, and an array of anything but
  * numbers keep their declared types: an array of booleans, of Buffers
@@ -70,3 +73,40 @@ export function isUnspecifiedParam(v) {
         return true;
     return Array.isArray(v) && (typeof x === 'number' || typeof x === 'bigint');
 }
+/**
+ * Whether a number must be declared `numeric` rather than the `float8`
+ * its value suggests.
+ *
+ * True for a finite non-integer, false for everything else - an integer,
+ * a bigint, a non-finite number, and anything that is not a number.
+ *
+ * @param v The value a parameter is about to be declared for.
+ * @returns Whether to declare `numeric` instead of asking `determine()`.
+ */
+/* `determine()` answers by value, so 12 is int4 and 12.34 is float8 -
+   and `int4 -> money` is an assignment cast while `float8 -> money` has
+   no pg_cast row at all. So `select ($1::money)::text` worked with 12
+   and failed 42846 with 12.34: the same SQL, the same column, decided by
+   whether the amount happened to have a fractional part, which for money
+   it usually does. A test written with 12 passed and production failed
+   on 12.34. `numeric -> money` is an assignment cast, which an explicit
+   `::money` accepts, and `numeric -> float8` is implicit, so a float8
+   column is unaffected.
+
+   Measured, inserting into a float8 column over a loopback connection,
+   three interleaved rounds of 3000: 0.197ms a call against float8's
+   0.198, and 51 bytes on the socket against 47. Round-tripping a double
+   through numeric is exact - checked against float8 for 0.1, 5e-324,
+   1.7976931348623157e308, 0.30000000000000004 and pi, among others.
+
+   Non-finite values keep float8 deliberately: `numeric` only grew
+   Infinity in PostgreSQL 14, and NaN would be the only one of the three
+   that worked on 12 and 13.
+
+   This does not close `$1::interval` from a number, which fails the same
+   way - there is no cast to interval from any numeric type, so only an
+   undeclared parameter reaches it. An integer scalar is left declared,
+   and `new BindParam(0, 5)` is the way to say it. */
+export function needsNumericParam(v) {
+    return typeof v === 'number' && Number.isFinite(v) && !Number.isInteger(v);
+}

package/util/unspecified-value.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Follows a value's `toPostgres()` until it reaches one that has none.
+ *
+ * `toPostgres()` is `pg`'s extension point for a type that knows how to
+ * write itself: a library with its own geometry, money or domain class
+ * implements it, and the value goes out as that class says rather than
+ * as whatever `String()` makes of it. The result is followed rather than
+ * returned, because what it hands back may itself be a `Date`, an array,
+ * a `Buffer` or another such value.
+ *
+ * @param v The value a parameter is about to be written from.
+ * @returns The value to write, which is `v` itself unless it had one.
+ * @throws TypeError if the values form a cycle.
+ */
+export declare function resolveToPostgres(v: any): any;
+/**
+ * The text an undeclared parameter - or one element of an undeclared
+ * array - goes out as.
+ *
+ * Follows `toPostgres()` first, then writes a plain object as JSON and
+ * anything else as its own text.
+ *
+ * @param v The value to render.
+ * @returns What to put on the wire, before any array quoting.
+ */
+export declare function unspecifiedText(v: any): string;

package/util/unspecified-value.js

@@ -0,0 +1,63 @@
+/**
+ * Follows a value's `toPostgres()` until it reaches one that has none.
+ *
+ * `toPostgres()` is `pg`'s extension point for a type that knows how to
+ * write itself: a library with its own geometry, money or domain class
+ * implements it, and the value goes out as that class says rather than
+ * as whatever `String()` makes of it. The result is followed rather than
+ * returned, because what it hands back may itself be a `Date`, an array,
+ * a `Buffer` or another such value.
+ *
+ * @param v The value a parameter is about to be written from.
+ * @returns The value to write, which is `v` itself unless it had one.
+ * @throws TypeError if the values form a cycle.
+ */
+/* Only for a parameter with no declared type. A declared type owns its
+   own encoding and is an answer the caller gave, not a guess.
+
+   This client's own classes are unaffected: every one of their
+   `toPostgres()` is `return this.toString()`, which is what the path
+   below used to reach anyway. What changes is a caller's class, which
+   used to be written `[object Object]` - silently, with a row written
+   and no error. */
+export function resolveToPostgres(v) {
+    if (v === null || typeof v !== 'object' || typeof v.toPostgres !== 'function')
+        return v;
+    const seen = [];
+    while (v !== null &&
+        typeof v === 'object' &&
+        typeof v.toPostgres === 'function') {
+        if (seen.includes(v))
+            throw new TypeError('Circular reference while preparing a parameter: toPostgres() returned a value that leads back to itself');
+        seen.push(v);
+        v = v.toPostgres();
+    }
+    return v;
+}
+/**
+ * The text an undeclared parameter - or one element of an undeclared
+ * array - goes out as.
+ *
+ * Follows `toPostgres()` first, then writes a plain object as JSON and
+ * anything else as its own text.
+ *
+ * @param v The value to render.
+ * @returns What to put on the wire, before any array quoting.
+ */
+/* The two rules `pg`'s `prepareValue` has that this path did not. The
+   rest of its rules are either already here in their own branch - a
+   Date, an array, a Buffer - or deliberately not taken: it writes a Date
+   with a `T` where this client writes a space, and quotes the elements
+   of a number array where this client writes them bare, which is 10-26%
+   smaller and parses identically. Those are spellings the server reads
+   the same way; these two are a value that arrives as something else. */
+export function unspecifiedText(v) {
+    v = resolveToPostgres(v);
+    if (v !== null &&
+        typeof v === 'object' &&
+        !(v instanceof Date) &&
+        !Buffer.isBuffer(v) &&
+        !Array.isArray(v))
+        return JSON.stringify(v);
+    return '' + v;
+}