postgrejs 3.11.1 → 3.12.1

package/util/format-datetime.js

@@ -38,6 +38,14 @@ function coerce(v) {
         return '-infinity';
     return v instanceof Date ? v : new Date(v);
 }
+/**
+ * Renders a value as the `YYYY-MM-DD` a `date` parameter goes out as.
+ *
+ * @param v The date, an epoch milliseconds, or text to pass through.
+ * @param options `utcDates` decides which clock its components are read
+ * from.
+ * @returns The date's text.
+ */
 export function formatDate(v, options) {
     const d = coerce(v);
     if (typeof d === 'string')
@@ -45,6 +53,14 @@ export function formatDate(v, options) {
     const p = parts(d, options);
     return `${pad(p.year, 4)}-${pad(p.month)}-${pad(p.day)}`;
 }
+/**
+ * Renders a value as the `HH:MM:SS.mmm` a `time` parameter goes out as.
+ *
+ * @param v The time, an epoch milliseconds, or text to pass through.
+ * @param options `utcDates` decides which clock its components are read
+ * from.
+ * @returns The time's text.
+ */
 export function formatTime(v, options) {
     const d = coerce(v);
     if (typeof d === 'string')
@@ -52,6 +68,16 @@ export function formatTime(v, options) {
     const p = parts(d, options);
     return `${pad(p.hour)}:${pad(p.minute)}:${pad(p.second)}.${pad(p.ms, 3)}`;
 }
+/**
+ * Renders a value as the `YYYY-MM-DD HH:MM:SS.mmm` a `timestamp`
+ * parameter goes out as.
+ *
+ * @param v The timestamp, an epoch milliseconds, or text to pass
+ * through.
+ * @param options `utcDates` decides which clock its components are read
+ * from.
+ * @returns The timestamp's text.
+ */
 export function formatTimestamp(v, options) {
     const d = coerce(v);
     if (typeof d === 'string')

package/util/get-parsers.d.ts

@@ -2,4 +2,13 @@ import type { DataTypeMap } from '../data-type-map.js';
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { Protocol } from '../protocol/protocol.js';
 import type { AnyParseFunction } from '../types.js';
+/**
+ * Chooses one parser per column, for the format that column is coming
+ * back in.
+ *
+ * @param typeMap Where the types are registered.
+ * @param fields The columns, as the server described them.
+ * @param options `fetchAsString` and the rest of the mapping options.
+ * @returns One parser per column, in order.
+ */
 export declare function getParsers(typeMap: DataTypeMap, fields: Protocol.RowDescription[], mappingOptions?: DataMappingOptions): AnyParseFunction[];

package/util/get-parsers.js

@@ -4,6 +4,15 @@ import { fetchAsStringNamesElement, fetchAsStringNamesOid, } from './fetch-as-st
 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);
+/**
+ * Chooses one parser per column, for the format that column is coming
+ * back in.
+ *
+ * @param typeMap Where the types are registered.
+ * @param fields The columns, as the server described them.
+ * @param options `fetchAsString` and the rest of the mapping options.
+ * @returns One parser per column, in order.
+ */
 export function getParsers(typeMap, fields, mappingOptions) {
     const parsers = new Array(fields.length);
     const asString = mappingOptions?.fetchAsString;

package/util/hex-text.d.ts

@@ -1,26 +1,18 @@
 /**
- * Writes `count` bytes of `src` into `scratch` as lowercase hex, each
- * byte's two characters starting at `positions[i]` - so the separators
- * a type writes between its bytes are put in once, when the scratch is
- * built, and never again.
+ * Writes `count` bytes of `src` into `scratch` as lowercase hex, two
+ * characters per byte, the first at `positions[i]`.
  *
- * The scratch is then read back with `latin1`, which is what the text
- * paths of these types already use: the output is fixed-format ASCII,
- * so it decodes identically to `utf8` and skips V8's multi-byte-sequence
- * detection.
+ * The positions are what let a type keep the separators of its own text
+ * form - a uuid's dashes, a macaddr's colons - in the scratch, written
+ * once when it is built and never again. The scratch is read back with
+ * `latin1`, which is what these types' text paths already use: the
+ * output is fixed-format ASCII, so it decodes identically to `utf8` and
+ * skips V8's multi-byte-sequence detection.
  *
- * Why not `Buffer.toString('hex')`: a type whose text has separators in
- * it has to call that once per group and join the pieces. For `uuid`
- * that was five calls and four concatenations per value - 25 000 strings
- * and 20 000 concatenations for a 5 000-row column, which is more work
- * than `pg` does for the same column despite this client reading half
- * the bytes. Measured over 5 000 values, medians of nine runs:
- *
- * ```
- * five toString + concat        1.86 ms
- * one toString, then slice      0.81 ms
- * a byte -> two-char table      0.64 ms
- * this                          0.33 ms
- * ```
+ * @param scratch The buffer to write into, reused across values.
+ * @param positions Where each byte's two characters go.
+ * @param src The bytes to render.
+ * @param offset Where they start in `src`.
+ * @param count How many to render.
  */
 export declare function writeHexBytes(scratch: Buffer, positions: number[], src: Buffer, offset: number, count: number): void;

package/util/hex-text.js

@@ -1,30 +1,33 @@
 /** `0`-`f` as bytes, so a nibble indexes straight into it. */
 const HEX = Buffer.from('0123456789abcdef', 'latin1');
 /**
- * Writes `count` bytes of `src` into `scratch` as lowercase hex, each
- * byte's two characters starting at `positions[i]` - so the separators
- * a type writes between its bytes are put in once, when the scratch is
- * built, and never again.
+ * Writes `count` bytes of `src` into `scratch` as lowercase hex, two
+ * characters per byte, the first at `positions[i]`.
  *
- * The scratch is then read back with `latin1`, which is what the text
- * paths of these types already use: the output is fixed-format ASCII,
- * so it decodes identically to `utf8` and skips V8's multi-byte-sequence
- * detection.
+ * The positions are what let a type keep the separators of its own text
+ * form - a uuid's dashes, a macaddr's colons - in the scratch, written
+ * once when it is built and never again. The scratch is read back with
+ * `latin1`, which is what these types' text paths already use: the
+ * output is fixed-format ASCII, so it decodes identically to `utf8` and
+ * skips V8's multi-byte-sequence detection.
  *
- * Why not `Buffer.toString('hex')`: a type whose text has separators in
- * it has to call that once per group and join the pieces. For `uuid`
- * that was five calls and four concatenations per value - 25 000 strings
- * and 20 000 concatenations for a 5 000-row column, which is more work
- * than `pg` does for the same column despite this client reading half
- * the bytes. Measured over 5 000 values, medians of nine runs:
- *
- * ```
- * five toString + concat        1.86 ms
- * one toString, then slice      0.81 ms
- * a byte -> two-char table      0.64 ms
- * this                          0.33 ms
- * ```
+ * @param scratch The buffer to write into, reused across values.
+ * @param positions Where each byte's two characters go.
+ * @param src The bytes to render.
+ * @param offset Where they start in `src`.
+ * @param count How many to render.
  */
+/* Why not Buffer.toString('hex'): a type whose text has separators in it
+   has to call that once per group and join the pieces. For uuid that was
+   five calls and four concatenations per value - 25 000 strings and
+   20 000 concatenations for a 5 000-row column, more work than pg does
+   for the same column despite this client reading half the bytes.
+   Measured over 5 000 values, medians of nine runs:
+
+     five toString + concat        1.86 ms
+     one toString, then slice      0.81 ms
+     a byte -> two-char table      0.64 ms
+     this                          0.33 ms */
 export function writeHexBytes(scratch, positions, src, offset, count) {
     let i;
     let p;

package/util/local-date.d.ts

@@ -7,46 +7,7 @@
  * comes back as a Date reading 10:30 locally rather than the instant
  * 10:30Z.
  *
- * Doing that by reading the seven `getUTC*` components off one Date and
- * handing them to another was the most expensive thing left in the
- * common decode path - the getters alone cost more than either Date:
- *
- * ```
- * new Date(epochMs)               43.6 ns
- * getUTC* x 7                     97.4 ns
- * new Date(y, m, d, h, mi, s, ms) 61.7 ns
- * ```
- *
- * Shifting the instant by the zone's own offset lands on the same wall
- * clock for a fraction of that, but only where the offset is a whole
- * number of minutes and holds either side of where the shift lands.
- * Two guards and a floor make that exact rather than usually-right:
- *
- * - **The offset must survive the shift.** Where it does not, the shift
- *   crossed a transition and the wall clock it landed on is not the one
- *   that was asked for - or does not exist at all.
- * - **The offset must hold for the hour before the landing too.** That
- *   is the hour a backward transition repeats, where both instants read
- *   the same wall clock and the shift keeps the wrong one of the two.
- *   Pacific/Chatham found this: `2024-04-07T03:00Z` is `03:00` in both
- *   +12:45 and +13:45, an hour apart.
- * - **Nothing before 1970.** A zone's pre-standard offset carries
- *   seconds - Europe/Istanbul was +01:55:52 - and `getTimezoneOffset()`
- *   answers in whole minutes, so the shift lands up to 59 seconds off.
- *   The tz database does not claim correctness before 1970 either.
- *
- * Whatever fails those goes back to the component route, which is what
- * this has always answered. Checked against it over 1850-2040 at
- * 90-minute steps - 1.1 million instants - in ten zones including the
- * 45-minute and 30-minute DST ones: no disagreement, and
- *
- * ```
- *                    before     after
- * Europe/Istanbul    157.5 ns   123.0 ns
- * America/New_York   245.6 ns   131.2 ns
- * ```
- *
- * The DST zone was dearer before because V8 pays for a transition lookup
- * on every local construction; here it pays for one instant instead.
+ * @param ms The instant whose UTC components are the wall clock wanted.
+ * @returns A Date reading that wall clock in the local zone.
  */
 export declare function utcPartsAsLocal(ms: number): Date;

package/util/local-date.js

@@ -7,48 +7,46 @@
  * comes back as a Date reading 10:30 locally rather than the instant
  * 10:30Z.
  *
- * Doing that by reading the seven `getUTC*` components off one Date and
- * handing them to another was the most expensive thing left in the
- * common decode path - the getters alone cost more than either Date:
- *
- * ```
- * new Date(epochMs)               43.6 ns
- * getUTC* x 7                     97.4 ns
- * new Date(y, m, d, h, mi, s, ms) 61.7 ns
- * ```
- *
- * Shifting the instant by the zone's own offset lands on the same wall
- * clock for a fraction of that, but only where the offset is a whole
- * number of minutes and holds either side of where the shift lands.
- * Two guards and a floor make that exact rather than usually-right:
- *
- * - **The offset must survive the shift.** Where it does not, the shift
- *   crossed a transition and the wall clock it landed on is not the one
- *   that was asked for - or does not exist at all.
- * - **The offset must hold for the hour before the landing too.** That
- *   is the hour a backward transition repeats, where both instants read
- *   the same wall clock and the shift keeps the wrong one of the two.
- *   Pacific/Chatham found this: `2024-04-07T03:00Z` is `03:00` in both
- *   +12:45 and +13:45, an hour apart.
- * - **Nothing before 1970.** A zone's pre-standard offset carries
- *   seconds - Europe/Istanbul was +01:55:52 - and `getTimezoneOffset()`
- *   answers in whole minutes, so the shift lands up to 59 seconds off.
- *   The tz database does not claim correctness before 1970 either.
- *
- * Whatever fails those goes back to the component route, which is what
- * this has always answered. Checked against it over 1850-2040 at
- * 90-minute steps - 1.1 million instants - in ten zones including the
- * 45-minute and 30-minute DST ones: no disagreement, and
- *
- * ```
- *                    before     after
- * Europe/Istanbul    157.5 ns   123.0 ns
- * America/New_York   245.6 ns   131.2 ns
- * ```
- *
- * The DST zone was dearer before because V8 pays for a transition lookup
- * on every local construction; here it pays for one instant instead.
+ * @param ms The instant whose UTC components are the wall clock wanted.
+ * @returns A Date reading that wall clock in the local zone.
  */
+/* Doing this by reading the seven getUTC* components off one Date and
+   handing them to another was the most expensive thing left in the
+   common decode path - the getters alone cost more than either Date:
+
+     new Date(epochMs)               43.6 ns
+     getUTC* x 7                     97.4 ns
+     new Date(y, m, d, h, mi, s, ms) 61.7 ns
+
+   Shifting the instant by the zone's own offset lands on the same wall
+   clock for a fraction of that, but only where the offset is a whole
+   number of minutes and holds either side of where the shift lands. Two
+   guards and a floor make that exact rather than usually-right:
+
+   - The offset must survive the shift. Where it does not, the shift
+     crossed a transition and the wall clock it landed on is not the one
+     that was asked for - or does not exist at all.
+   - The offset must hold for the hour before the landing too. That is
+     the hour a backward transition repeats, where both instants read the
+     same wall clock and the shift keeps the wrong one of the two.
+     Pacific/Chatham found this: 2024-04-07T03:00Z is 03:00 in both
+     +12:45 and +13:45, an hour apart.
+   - Nothing before 1970. A zone's pre-standard offset carries seconds -
+     Europe/Istanbul was +01:55:52 - and getTimezoneOffset() answers in
+     whole minutes, so the shift lands up to 59 seconds off. The tz
+     database does not claim correctness before 1970 either.
+
+   Whatever fails those goes back to the component route, which is what
+   this has always answered. Checked against it over 1850-2040 at
+   90-minute steps - 1.1 million instants - in ten zones including the
+   45-minute and 30-minute DST ones: no disagreement, and
+
+                      before     after
+     Europe/Istanbul    157.5 ns   123.0 ns
+     America/New_York   245.6 ns   131.2 ns
+
+   The DST zone was dearer before because V8 pays for a transition lookup
+   on every local construction; here it pays for one instant instead. */
 export function utcPartsAsLocal(ms) {
     if (ms >= 0) {
         const offset = new Date(ms).getTimezoneOffset();

package/util/parse-array.d.ts

@@ -1,4 +1,12 @@
 import type { Maybe } from '../types.js';
+/**
+ * Reads an array literal - `{1,2,{3,4}}` - into a nested array.
+ *
+ * @param s The literal, as the server wrote it.
+ * @param opts `transform` reads each element's text into a value, and
+ * `separator` is for the types that do not use a comma.
+ * @returns The array, or `undefined` when there was no literal.
+ */
 export declare function parsePostgresArray(s: string, opts?: {
     transform?: (v: string) => any;
     separator?: string;

package/util/parse-array.js

@@ -1,3 +1,11 @@
+/**
+ * Reads an array literal - `{1,2,{3,4}}` - into a nested array.
+ *
+ * @param s The literal, as the server wrote it.
+ * @param opts `transform` reads each element's text into a value, and
+ * `separator` is for the types that do not use a comma.
+ * @returns The array, or `undefined` when there was no literal.
+ */
 export function parsePostgresArray(s, opts) {
     if (!s)
         return;

package/util/parse-bytea.d.ts

@@ -1,2 +1,17 @@
+/**
+ * Reads a `bytea`'s text form into its bytes.
+ *
+ * @param v The value as the server wrote it - `\\x` hex, or the older
+ * escape form.
+ * @returns The bytes.
+ */
 export declare function parseBytea(v: string): Buffer;
+/**
+ * The same, straight from the wire bytes - no string is made.
+ *
+ * @param buf The buffer holding the value.
+ * @param offset Where it starts.
+ * @param len How many bytes it runs for.
+ * @returns The decoded bytes.
+ */
 export declare function parseByteaBuffer(buf: Buffer, offset: number, len: number): Buffer;

package/util/parse-bytea.js

@@ -36,6 +36,13 @@ function parseByteaEscape(input) {
     }
     return Buffer.from(output, 'binary');
 }
+/**
+ * Reads a `bytea`'s text form into its bytes.
+ *
+ * @param v The value as the server wrote it - `\\x` hex, or the older
+ * escape form.
+ * @returns The bytes.
+ */
 export function parseBytea(v) {
     // PostgreSQL's default bytea_output is "hex" (`\x`-prefixed) - check the
     // two marker chars directly rather than a regex test, and hex-decode
@@ -65,6 +72,14 @@ const HEX_NIBBLE = (() => {
 // format via a single 'latin1' string conversion - its own grammar (\ddd
 // octal triplets, ASCII digits, or a literal backslash) is pure ASCII, same
 // as the hex path, so 'latin1' is safe there too.
+/**
+ * The same, straight from the wire bytes - no string is made.
+ *
+ * @param buf The buffer holding the value.
+ * @param offset Where it starts.
+ * @param len How many bytes it runs for.
+ * @returns The decoded bytes.
+ */
 export function parseByteaBuffer(buf, offset, len) {
     if (buf[offset] === 0x5c /* '\' */ && buf[offset + 1] === 0x78 /* 'x' */) {
         // Truncate a trailing odd nibble instead of throwing, matching

package/util/parse-datetime.d.ts

@@ -1,4 +1,30 @@
 import { type PgDateStyle } from './date-style.js';
+/**
+ * Reads a `date` as the server wrote it.
+ *
+ * @param str The value's text.
+ * @param utc Whether to build the Date in UTC rather than locally.
+ * @param dateStyle The session's DateStyle, when it is not ISO - which
+ * is what says whether `01/02/2024` is January or February.
+ * @returns The date, or ±Infinity for the two that are not dates.
+ */
 export declare function parseDate(str: string, utc?: boolean, dateStyle?: PgDateStyle): Date | number;
+/**
+ * Reads a `timestamp` (without time zone) as the server wrote it.
+ *
+ * @param str The value's text.
+ * @param utc Whether to build the Date in UTC rather than locally.
+ * @param dateStyle The session's DateStyle, when it is not ISO.
+ * @returns The timestamp, or ±Infinity.
+ */
 export declare function parseDateTime(str: string, utc?: boolean, dateStyle?: PgDateStyle): Date | number;
+/**
+ * Reads a `timestamptz` as the server wrote it, offset included.
+ *
+ * @param str The value's text.
+ * @param utc Whether to build the Date in UTC rather than locally, for
+ * a value that carries no offset.
+ * @param dateStyle The session's DateStyle, when it is not ISO.
+ * @returns The instant, or ±Infinity.
+ */
 export declare function parseDateTimeTz(str: string, utc?: boolean, dateStyle?: PgDateStyle): Date | number;

package/util/parse-datetime.js

@@ -22,6 +22,15 @@ function fillTimeArgs(m, args) {
         }
     }
 }
+/**
+ * Reads a `date` as the server wrote it.
+ *
+ * @param str The value's text.
+ * @param utc Whether to build the Date in UTC rather than locally.
+ * @param dateStyle The session's DateStyle, when it is not ISO - which
+ * is what says whether `01/02/2024` is January or February.
+ * @returns The date, or ±Infinity for the two that are not dates.
+ */
 export function parseDate(str, utc, dateStyle) {
     if (dateStyle) {
         const styled = parseStyledDateTime(str, dateStyle, utc);
@@ -46,6 +55,14 @@ export function parseDate(str, utc, dateStyle) {
         return new Date(Date.UTC(...args));
     return new Date(...args);
 }
+/**
+ * Reads a `timestamp` (without time zone) as the server wrote it.
+ *
+ * @param str The value's text.
+ * @param utc Whether to build the Date in UTC rather than locally.
+ * @param dateStyle The session's DateStyle, when it is not ISO.
+ * @returns The timestamp, or ±Infinity.
+ */
 export function parseDateTime(str, utc, dateStyle) {
     if (dateStyle) {
         const styled = parseStyledDateTime(str, dateStyle, utc);
@@ -88,6 +105,15 @@ export function parseDateTime(str, utc, dateStyle) {
         return new Date(Date.UTC(...args));
     return new Date(...args);
 }
+/**
+ * Reads a `timestamptz` as the server wrote it, offset included.
+ *
+ * @param str The value's text.
+ * @param utc Whether to build the Date in UTC rather than locally, for
+ * a value that carries no offset.
+ * @param dateStyle The session's DateStyle, when it is not ISO.
+ * @returns The instant, or ±Infinity.
+ */
 export function parseDateTimeTz(str, utc, dateStyle) {
     if (dateStyle) {
         const styled = parseStyledDateTime(str, dateStyle, utc);

package/util/parse-row.d.ts

@@ -1,5 +1,26 @@
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { FieldInfo } from '../interfaces/field-info.js';
 import type { AnyParseFunction } from '../types.js';
-export declare function parseRow(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions): any[];
-export declare function parseObjectRow(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): object;
+/**
+ * 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 declare function parseRow(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, start?: number): any[];
+/**
+ * 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 declare function parseObjectRow(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, fields: FieldInfo[], start?: number): object;

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;