postgrejs 3.11.1 → 3.12.1

package/util/parse-time.js

@@ -1,8 +1,18 @@
 import { fastParseInt } from './fast-parseint.js';
 // noinspection RegExpUnnecessaryNonCapturingGroup
+/** A time as the server writes one: two digits a part, colons in place. */
 export const STRICT_TIME_PATTERN = /^([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(?:\.(\d+))?(?:(Z)|(?:([+-])([01]?[0-9]|2[0-3]):?([0-5][0-9])?))?$/;
 // noinspection RegExpUnnecessaryNonCapturingGroup
+/** The same, loosened for what a caller might pass as a parameter - the colons and the seconds may be left out. */
 export const TIME_PATTERN = /^([01][0-9]|2[0-3]):?([0-5][0-9]):?([0-5][0-9])?(?:\.(\d+))?(?:(Z)|(?:([+-])([01]?[0-9]|2[0-3]):?([0-5][0-9])?))?$/;
+/**
+ * Reads a time of day into a Date on the epoch day.
+ *
+ * @param str The value's text.
+ * @param parseTimeZone Whether an offset in the text should be applied.
+ * @param utc Whether to build the Date in UTC rather than locally.
+ * @returns A Date carrying that clock time.
+ */
 export function parseTime(str, parseTimeZone, utc) {
     const m = str.match(TIME_PATTERN);
     if (!m)

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

@@ -2,6 +2,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 } from '../types.js';
+/** What decides the per-column format codes a Bind asks for. */
 export interface ColumnFormatOptions extends DataMappingOptions {
     columnFormat?: Protocol.DataFormat | Protocol.DataFormat[];
 }

package/util/row-decoder.d.ts

@@ -32,16 +32,48 @@ export declare abstract class RowDecoder {
      */
     readonly rowType: 'array' | 'object' | 'custom';
     abstract decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): any;
+    /**
+     * The same, reading the row where it already is: `buffer` is the
+     * socket's own read buffer and the row's values run for `len` bytes
+     * from `offset`.
+     *
+     * Optional, and what a decoder implements when it has no use for a
+     * `Buffer` of its own - which is every decoder that reads its values
+     * and does not keep them. Implementing it means no view is built for
+     * the row at all; a decoder that only implements `decode()` still gets
+     * one, exactly as before.
+     */
+    decodeAt?(parsers: AnyParseFunction[], buffer: Buffer, offset: number, len: number, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): any;
 }
+/** Reads each row into an array of values, in column order. */
+/**
+ * A row's bytes as a `Buffer` of their own.
+ *
+ * For the paths that set a row aside and read it later, and for a
+ * caller's decoder that only implements `decode()`.
+ *
+ * @param msg The row as it arrived.
+ * @returns A view of just its values.
+ */
+export declare function dataRowBytes(msg: {
+    buffer: Buffer;
+    offset: number;
+    len: number;
+}): Buffer;
 export declare class ArrayRowDecoder extends RowDecoder {
     readonly rowType: "array";
     decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions): any[];
+    decodeAt(parsers: AnyParseFunction[], buffer: Buffer, offset: number, _len: number, columnCount: number, options: DataMappingOptions): any[];
 }
+/** Reads each row into an object keyed by column name. */
 export declare class ObjectRowDecoder extends RowDecoder {
     readonly rowType: "object";
     decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): object;
+    decodeAt(parsers: AnyParseFunction[], buffer: Buffer, offset: number, _len: number, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): object;
 }
+/** The array decoder every query shares - it holds no state. */
 export declare const DEFAULT_ARRAY_ROW_DECODER: ArrayRowDecoder;
+/** The object decoder every query shares - it holds no state. */
 export declare const DEFAULT_OBJECT_ROW_DECODER: ObjectRowDecoder;
 interface RowDecoderOptions {
     rowDecoder?: 'array' | 'object' | RowDecoder;

package/util/row-decoder.js

@@ -30,19 +30,41 @@ export class RowDecoder {
      */
     rowType = 'custom';
 }
+/** Reads each row into an array of values, in column order. */
+/**
+ * A row's bytes as a `Buffer` of their own.
+ *
+ * For the paths that set a row aside and read it later, and for a
+ * caller's decoder that only implements `decode()`.
+ *
+ * @param msg The row as it arrived.
+ * @returns A view of just its values.
+ */
+export function dataRowBytes(msg) {
+    return msg.buffer.subarray(msg.offset, msg.offset + msg.len);
+}
 export class ArrayRowDecoder extends RowDecoder {
     rowType = 'array';
     decode(parsers, data, columnCount, options) {
         return parseRow(parsers, data, columnCount, options);
     }
+    decodeAt(parsers, buffer, offset, _len, columnCount, options) {
+        return parseRow(parsers, buffer, columnCount, options, offset);
+    }
 }
+/** Reads each row into an object keyed by column name. */
 export class ObjectRowDecoder extends RowDecoder {
     rowType = 'object';
     decode(parsers, data, columnCount, options, fields) {
         return parseObjectRow(parsers, data, columnCount, options, fields);
     }
+    decodeAt(parsers, buffer, offset, _len, columnCount, options, fields) {
+        return parseObjectRow(parsers, buffer, columnCount, options, fields, offset);
+    }
 }
+/** The array decoder every query shares - it holds no state. */
 export const DEFAULT_ARRAY_ROW_DECODER = new ArrayRowDecoder();
+/** The object decoder every query shares - it holds no state. */
 export const DEFAULT_OBJECT_ROW_DECODER = new ObjectRowDecoder();
 /**
  * Collapses the `rowDecoder`/`objectRows` query options into one RowDecoder

package/util/stringify-arrayliteral.d.ts

@@ -1,3 +1,36 @@
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { EncodeTextFunction } from '../types.js';
+/**
+ * Renders an array as the literal the server parses - `{1,2,{3,4}}`.
+ *
+ * @param value The array, nested to any depth.
+ * @param options Passed to the element encoder.
+ * @param encode The element type's own text encoder, when the type is
+ * known; without one each element is taken as it stringifies.
+ * @returns The literal.
+ */
 export declare function stringifyArrayLiteral(value: any[], options?: DataMappingOptions, encode?: EncodeTextFunction): string;
+/**
+ * Writes an array as a length-prefixed literal, straight into `io`,
+ * without building the literal as a string first.
+ *
+ * The text is the one `stringifyArrayLiteral()` returns, so what reaches
+ * the server is the same either way. Only an array of numbers with no
+ * element encoder takes this path - the untyped-parameter case, and the
+ * only one where a numeric array becomes a literal at all, since a
+ * declared one keeps the binary encoding. Anything else, and anything
+ * under `WRITE_BYTES_FROM` elements, is handed to the string path.
+ *
+ * @param io The buffer to write into - the connection's own.
+ * @param value The array to write.
+ * @param options Passed to the element encoder, when there is one.
+ * @param encode The element type's own text encoder, if the type was
+ * declared.
+ */
+export declare function writeArrayLiteral(io: {
+    buffer: Buffer;
+    size: number;
+    writeInt32BE(v: number): number;
+    writeBytes(b: Buffer): number;
+    writeLString(s?: string, encoding?: BufferEncoding): number;
+}, value: any[], options?: DataMappingOptions, encode?: EncodeTextFunction): void;

package/util/stringify-arrayliteral.js

@@ -1,4 +1,27 @@
 import { arrayCalculateDim } from './array-calculatedim.js';
+import { arrayLeaf } from './array-leaf.js';
+/**
+ * What a number's own text looks like: digits, one optional dot, an
+ * optional exponent, an optional leading minus. 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 that
+   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+)?$/;
+/**
+ * Renders an array as the literal the server parses - `{1,2,{3,4}}`.
+ *
+ * @param value The array, nested to any depth.
+ * @param options Passed to the element encoder.
+ * @param encode The element type's own text encoder, when the type is
+ * known; without one each element is taken as it stringifies.
+ * @returns The literal.
+ */
 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 +32,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 +57,225 @@ 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);
 }
+/** Quotes one element, escaping the two characters that need it. */
+/* Backslash and double quote are the only two 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, '\\"') + '"';
+}
+/** How many bytes writeArrayLiteral() writes into `io` at a time. */
+/* Bounded rather than grown to fit: a 100 000-element array is 1.1MB of
+   literal, and a scratch sized to the largest one ever written would
+   hold that for the life of the process. Flushing every 64KB keeps this
+   constant, and what it flushes into is the connection's own buffer,
+   which already knows how to grow and to hand its pages back when
+   idle. */
+const CHUNK = 64 * 1024;
+/** The scratch itself, reused by every call. */
+const chunk = Buffer.allocUnsafe(CHUNK);
+/**
+ * Whether the digit lane applies to this value - see writeArrayLiteral().
+ * Asked of the array's first leaf to choose a path, and of every element
+ * on the way past.
+ */
+function isInt32(v) {
+    return (typeof v === 'number' &&
+        v >= -2147483648 &&
+        v <= 2147483647 &&
+        Number.isInteger(v));
+}
+/** Digits, written backwards, before they are copied out forwards. */
+const DIGITS = new Uint8Array(24);
+/** Below this many elements the literal is built as a string instead. */
+/* Writing bytes wins from about a hundred elements up and loses below
+   it: Buffer.write() has a per-call cost that `+=` does not, and for a
+   handful of short elements that cost is the whole of the work. The
+   number is where the two met when measured, so it is a floor against a
+   small regression rather than a tuned parameter. */
+const WRITE_BYTES_FROM = 16;
+/**
+ * Writes an array as a length-prefixed literal, straight into `io`,
+ * without building the literal as a string first.
+ *
+ * The text is the one `stringifyArrayLiteral()` returns, so what reaches
+ * the server is the same either way. Only an array of numbers with no
+ * element encoder takes this path - the untyped-parameter case, and the
+ * only one where a numeric array becomes a literal at all, since a
+ * declared one keeps the binary encoding. Anything else, and anything
+ * under `WRITE_BYTES_FROM` elements, is handed to the string path.
+ *
+ * @param io The buffer to write into - the connection's own.
+ * @param value The array to write.
+ * @param options Passed to the element encoder, when there is one.
+ * @param encode The element type's own text encoder, if the type was
+ * declared.
+ */
+/* The string was never wanted: writeLString() encoded it to UTF-8 and
+   threw it away. For a 100 000-element int4[] it is 1.1MB, built out of
+   ~200 000 rope nodes, flattened once and encoded once - counted with
+   --trace-gc over 100 calls, that step collects 10.1 MB a call.
+
+   The saving is not in avoiding the string, though. Writing bytes
+   through Buffer.write() per element is *slower* than letting V8 build a
+   rope and flatten it once - 1.1x to 1.35x slower across every size and
+   type, which is why this is not simply the byte-writing version of
+   stringifyArrayLiteral(). What pays is never producing the element's
+   text at all: an integer's digits go into the buffer from the number
+   itself, with no string and no per-element call. Against the string
+   path on an int4[], medians of alternating runs:
+
+     elements      64      1 000    100 000
+     string      2.38 us   22.2 us   3180 us
+     digits      0.88 us    4.8 us    917 us
+                 2.7x       4.6x      3.5x
+
+   What a caller waits for moves less, and the difference is worth
+   knowing before quoting one: inserting the same array over a loopback
+   connection is 14.21ms against 12.51ms, 1.14x, because the server's own
+   parse of a 1.1MB literal is most of it. The allocation is gone either
+   way - 10.10 MB a call to 0.00.
+
+   So the fast lane is integers, and everything else on this path - a
+   float, a bigint too large to be exact, anything a reader of the array
+   did not expect - falls back to its own text and is written as such. */
+export function writeArrayLiteral(io, value, options, encode) {
+    if (encode ||
+        !Array.isArray(value) ||
+        value.length < WRITE_BYTES_FROM ||
+        !isInt32(arrayLeaf(value))) {
+        io.writeLString(stringifyArrayLiteral(value, options, encode), 'utf8');
+        return;
+    }
+    const dim = arrayCalculateDim(value);
+    const lastLevel = dim.length - 1;
+    // The length is only known once everything is written, so the field is
+    // reserved now and filled in at the end - the same shape the binary
+    // encoders use for their own payloads.
+    io.writeInt32BE(0);
+    const lengthAt = io.size - 4;
+    const start = io.size;
+    let p = 0;
+    const writeDim = (arr, level) => {
+        const elemCount = dim[level];
+        const isLeafLevel = level >= lastLevel;
+        // No room check here: this is entered either at the top level, with
+        // an empty scratch, or from inside the loop below, which has just
+        // made room for the separator, the longest number, and both braces.
+        chunk[p++] = 123; /* { */
+        let x;
+        let s;
+        let v;
+        let q;
+        let i;
+        for (i = 0; i < elemCount; i++) {
+            // Every element writes at most a separator, a sign and 24 digits,
+            // plus the two braces a nested dimension would open and close
+            // around them; the text branch reserves its own room below. That
+            // headroom is what lets the braces be written unchecked.
+            if (p > CHUNK - 32) {
+                io.writeBytes(chunk.subarray(0, p));
+                p = 0;
+            }
+            if (i)
+                chunk[p++] = 44; /* , */
+            x = arr && arr[i];
+            if (!isLeafLevel) {
+                if (x != null && !Array.isArray(x))
+                    x = [x];
+                writeDim(x, level + 1);
+                continue;
+            }
+            if (x == null) {
+                chunk[p++] = 78; /* N */
+                chunk[p++] = 85; /* U */
+                chunk[p++] = 76; /* L */
+                chunk[p++] = 76; /* L */
+                continue;
+            }
+            // int32 rather than any safe integer: the digits come out of a
+            // repeated `(v / 10) | 0`, which is exact and fast only within
+            // that range. Above it, dividing a double sixteen times per
+            // element is slower than letting V8 print the number - measured at
+            // 11x slower on values near 9e15 - so those go the same way as a
+            // float does, through their own text.
+            if (x >= -2147483648 && x <= 2147483647 && Number.isInteger(x)) {
+                v = x;
+                if (v < 0) {
+                    chunk[p++] = 45; /* - */
+                    v = -v;
+                }
+                q = 24;
+                do {
+                    DIGITS[--q] = 48 + (v % 10);
+                    v = (v / 10) | 0;
+                } while (v);
+                while (q < 24)
+                    chunk[p++] = DIGITS[q++];
+                continue;
+            }
+            // Anything else: its own text, quoted exactly as the string path
+            // would quote it.
+            // Asked before the text is produced, and of the value rather than
+            // 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;
+            const bare = isNumber && BARE_NUMBER.test(s);
+            if (!bare)
+                s =
+                    s.indexOf('\\') < 0 && s.indexOf('"') < 0
+                        ? s
+                        : s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            // A UTF-16 code unit is at most three UTF-8 bytes, which is the
+            // room to have without measuring the string first. The two quotes
+            // are in it, and one byte more for the `}` that may follow this
+            // element without a check of its own.
+            const bound = s.length * 3 + 3;
+            if (p + bound > CHUNK) {
+                io.writeBytes(chunk.subarray(0, p));
+                p = 0;
+            }
+            if (bound > CHUNK) {
+                // One element larger than the whole scratch - a long text value.
+                // It goes out on its own rather than growing anything, and
+                // `Buffer.write` would otherwise have truncated it in silence.
+                io.writeBytes(Buffer.from(bare ? s : '"' + s + '"', 'utf8'));
+                continue;
+            }
+            if (bare)
+                p += chunk.write(s, p, 'utf8');
+            else {
+                chunk[p++] = 34; /* " */
+                p += chunk.write(s, p, 'utf8');
+                chunk[p++] = 34;
+            }
+        }
+        chunk[p++] = 125; /* } */
+    };
+    writeDim(value, 0);
+    if (p)
+        io.writeBytes(chunk.subarray(0, p));
+    io.buffer.writeInt32BE(io.size - start, lengthAt);
 }

package/util/stringify-for-sql.d.ts

@@ -1,4 +1,21 @@
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { EncodeTextFunction } from '../types.js';
+/**
+ * Renders an array as the `ARRAY[...]` an SQL statement can carry.
+ *
+ * For the `sql` tag, which puts values into the text rather than sending
+ * them as parameters.
+ *
+ * @param arr The array, nested to any depth.
+ * @param options Passed to the element encoder.
+ * @returns The literal, cast to the element type it was built for.
+ */
 export declare function stringifyArrayForSQL(v: any[], options?: DataMappingOptions, encode?: EncodeTextFunction): string;
+/**
+ * Renders one value as the literal an SQL statement can carry.
+ *
+ * @param v The value.
+ * @param options Passed to the type's own text encoder.
+ * @returns The literal, quoted and escaped as the value needs.
+ */
 export declare function stringifyValueForSQL(v: any, options?: DataMappingOptions, encode?: EncodeTextFunction): string;

package/util/stringify-for-sql.js

@@ -3,6 +3,16 @@ import { GlobalTypeMap } from '../data-type-map.js';
 import { UuidType } from '../data-types/uuid-type.js';
 import { escapeLiteral } from './escape-literal.js';
 import { formatDateParam } from './format-datetime.js';
+/**
+ * Renders an array as the `ARRAY[...]` an SQL statement can carry.
+ *
+ * For the `sql` tag, which puts values into the text rather than sending
+ * them as parameters.
+ *
+ * @param arr The array, nested to any depth.
+ * @param options Passed to the element encoder.
+ * @returns The literal, cast to the element type it was built for.
+ */
 export function stringifyArrayForSQL(v, options, encode) {
     const arr = v.map(x => stringifyValueForSQL(x, options, encode));
     return 'ARRAY[' + arr.join(',') + ']';
@@ -38,6 +48,13 @@ function stringifyObjectForSQL(v, options) {
             dataType.name);
     return escapeLiteral(JSON.stringify(v)) + '::json';
 }
+/**
+ * Renders one value as the literal an SQL statement can carry.
+ *
+ * @param v The value.
+ * @param options Passed to the type's own text encoder.
+ * @returns The literal, quoted and escaped as the value needs.
+ */
 export function stringifyValueForSQL(v, options, encode) {
     if (v == null)
         return 'null';

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);

package/util/wrap-row-description.d.ts

@@ -3,4 +3,14 @@ import type { DataTypeMap } from '../data-type-map.js';
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { FieldInfo } from '../interfaces/field-info.js';
 import type { Protocol } from '../protocol/protocol.js';
+/**
+ * Turns the server's RowDescription into the `FieldInfo[]` a caller
+ * sees, naming each column's type and what it maps to.
+ *
+ * @param typeMap Where the types are registered.
+ * @param fields The columns, as the server described them.
+ * @param columnFormat What format they are coming back in.
+ * @param options The mapping options in force.
+ * @returns One FieldInfo per column, in order.
+ */
 export declare function wrapRowDescription(typeMap: DataTypeMap, fields: Protocol.RowDescription[], columnFormat: DataFormat | DataFormat[], mappingOptions?: DataMappingOptions): FieldInfo[];

package/util/wrap-row-description.js

@@ -9,6 +9,16 @@ const DataTypeOIDByName = {};
 for (const oid of Object.keys(DataTypeNames)) {
     DataTypeOIDByName[DataTypeNames[oid]] = Number(oid);
 }
+/**
+ * Turns the server's RowDescription into the `FieldInfo[]` a caller
+ * sees, naming each column's type and what it maps to.
+ *
+ * @param typeMap Where the types are registered.
+ * @param fields The columns, as the server described them.
+ * @param columnFormat What format they are coming back in.
+ * @param options The mapping options in force.
+ * @returns One FieldInfo per column, in order.
+ */
 export function wrapRowDescription(typeMap, fields, columnFormat, mappingOptions) {
     const asString = mappingOptions?.fetchAsString;
     return fields.map((f, idx) => {