postgrejs 3.12.0 → 3.12.1

package/util/parse-row.js

@@ -1,6 +1,16 @@
-export function parseRow(parsers, data, columnCount, options) {
+/**
+ * Reads one row into an array of values.
+ *
+ * @param parsers One per column, already chosen for its format.
+ * @param data The row's own bytes, from the DataRow message.
+ * @param columnCount How many values it holds.
+ * @param options Passed to each parser.
+ * @param start Where the row's values begin in `data`.
+ * @returns The values, in column order.
+ */
+export function parseRow(parsers, data, columnCount, options, start = 0) {
     const row = new Array(columnCount);
-    let offset = 0;
+    let offset = start;
     let len;
     let i;
     for (i = 0; i < columnCount; i++) {
@@ -21,28 +31,26 @@ export function parseRow(parsers, data, columnCount, options) {
     }
     return row;
 }
-/**
- * Rows decoded against one `FieldInfo[]` before compiling a factory for it.
- *
- * Compiling costs ~0.8µs when the engine can reuse its own compilation
- * cache for identical source and several µs when it can't, against ~0.1µs
- * saved per row - so a query returning a handful of rows would pay more
- * than it ever got back. Since wrapRowDescription() builds a fresh fields
- * array per query, a single-row query executed in a loop would otherwise
- * recompile on every call. Waiting a few rows keeps that case free while
- * giving up well under 1% of the win on a result worth compiling for.
- */
+/** Rows decoded against one `FieldInfo[]` before compiling a factory for it. */
+/* Compiling costs ~0.8µs when the engine can reuse its own compilation
+   cache for identical source and several µs when it cannot, against
+   ~0.1µs saved per row - so a query returning a handful of rows would
+   pay more than it ever got back. Since wrapRowDescription() builds a
+   fresh fields array per query, a single-row query executed in a loop
+   would otherwise recompile on every call. Waiting a few rows keeps that
+   case free while giving up well under 1% of the win on a result worth
+   compiling for. */
 const OBJECT_ROW_FACTORY_THRESHOLD = 8;
 /**
- * Holds only factories that were actually compiled - never the row counts
- * leading up to one. Writing a fresh key here costs ~67ns plus the garbage
- * it leaves behind, which a single-row query (a new fields array every
- * time, never looked up again) would pay on every call for nothing.
- *
- * Keyed weakly, so a finished query's factory goes away with its fields;
- * an entry earns its keep only when the same fields array is decoded
- * against again after something else interrupted it.
+ * The compiled factories, keyed weakly by the fields they were built
+ * for, so a finished query's factory goes away with them.
  */
+/* Only factories that were actually compiled go in here, never the row
+   counts leading up to one: writing a fresh key costs ~67ns plus the
+   garbage it leaves behind, which a single-row query - a new fields
+   array every time, never looked up again - would pay on every call for
+   nothing. An entry earns its keep only when the same fields array is
+   decoded against again after something else interrupted it. */
 const objectRowFactories = new WeakMap();
 // Rows of one result arrive in a run, so a single entry in front of the
 // WeakMap answers nearly every lookup with one identity check - and is
@@ -58,17 +66,18 @@ let memoDeclined = false;
  * Compiles a function that builds this query's row object in one shot,
  * from a single object literal with every column name in it.
  *
- * Assigning the columns one at a time instead (`row[name] = value`) walks
- * the object through one hidden-class transition per column, per row -
- * measured at ~6.8x the cost of handing the engine a literal whose shape
- * it can lay out once and reuse for every row of the result.
- *
- * Returns null when that isn't possible, leaving the caller on the
- * assignment path: a column named `__proto__` would set the prototype
- * rather than become an own property if it appeared as a literal key, and
- * Function construction itself can be unavailable (a Content-Security-
- * Policy without 'unsafe-eval').
+ * @param fields The columns to build the literal from.
+ * @param columnCount How many of them the rows carry.
+ * @returns The factory, or `null` when this shape cannot be compiled -
+ * a column named `__proto__`, or a runtime with Function construction
+ * disabled - which leaves the caller on the assignment path.
  */
+/* Assigning the columns one at a time instead (row[name] = value) walks
+   the object through one hidden-class transition per column, per row -
+   ~6.8x the cost of handing the engine a literal whose shape it can lay
+   out once and reuse for every row of the result. A `__proto__` key in a
+   literal sets the prototype rather than becoming an own property, which
+   is why that one is refused rather than escaped. */
 function buildObjectRowFactory(fields, columnCount) {
     let src = 'return{';
     let name;
@@ -115,7 +124,18 @@ function getObjectRowFactory(fields, columnCount) {
     objectRowFactories.set(fields, factory);
     return factory;
 }
-export function parseObjectRow(parsers, data, columnCount, options, fields) {
+/**
+ * Reads one row into an object keyed by column name.
+ *
+ * @param parsers One per column, already chosen for its format.
+ * @param data The row's own bytes, from the DataRow message.
+ * @param columnCount How many values it holds.
+ * @param options Passed to each parser.
+ * @param fields The columns, whose names become the keys.
+ * @param start Where the row's values begin in `data`.
+ * @returns The row as an object.
+ */
+export function parseObjectRow(parsers, data, columnCount, options, fields, start = 0) {
     // A compiled factory is built against `fields`, so it can only be used
     // when the row really does have one value per field.
     const factory = fields.length === columnCount
@@ -123,7 +143,7 @@ export function parseObjectRow(parsers, data, columnCount, options, fields) {
         : null;
     if (factory) {
         const values = new Array(columnCount);
-        let offset = 0;
+        let offset = start;
         let len;
         let i;
         for (i = 0; i < columnCount; i++) {
@@ -139,11 +159,11 @@ export function parseObjectRow(parsers, data, columnCount, options, fields) {
         }
         return factory(values);
     }
-    return parseObjectRowByAssignment(parsers, data, columnCount, options, fields);
+    return parseObjectRowByAssignment(parsers, data, columnCount, options, fields, start);
 }
-function parseObjectRowByAssignment(parsers, data, columnCount, options, fields) {
+function parseObjectRowByAssignment(parsers, data, columnCount, options, fields, start = 0) {
     const row = {};
-    let offset = 0;
+    let offset = start;
     let len;
     let i;
     let value;

package/util/parse-time.d.ts

@@ -1,3 +1,13 @@
+/** A time as the server writes one: two digits a part, colons in place. */
 export declare const STRICT_TIME_PATTERN: RegExp;
+/** The same, loosened for what a caller might pass as a parameter - the colons and the seconds may be left out. */
 export declare const TIME_PATTERN: RegExp;
+/**
+ * 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 declare function parseTime(str: string, parseTimeZone?: boolean, utc?: boolean): Date;

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,20 +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. 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.
+ * 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
@@ -66,16 +73,209 @@ export function stringifyArrayLiteral(value, options, encode) {
     };
     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.
- */
+/** 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.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/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) => {