postgrejs 3.11.1 → 3.12.1

package/types.d.ts

@@ -1,9 +1,14 @@
 import type { DataMappingOptions } from './interfaces/data-mapping-options.js';
 import type { SmartBuffer } from './protocol/smart-buffer.js';
+/** A PostgreSQL type identifier, as `pg_type.oid` gives it. */
 export type OID = number;
+/** `T`, or nothing. */
 export type Maybe<T> = T | undefined;
+/** `T`, or SQL NULL. */
 export type Nullable<T> = T | null;
+/** One decoded row - an array, an object, or whatever a custom decoder returns. */
 export type Row = any;
+/** The node-style callback the stream-facing methods accept. */
 export type Callback = (err?: Error | null) => void;
 /**
  * What a DataType's own `decodeBinary` implements. `buf` is a shared
@@ -18,12 +23,28 @@ export type Callback = (err?: Error | null) => void;
  * end of the buffer" must not.
  */
 export type DecodeBinaryFunction = (buf: Buffer, offset: number, len: number, options: DataMappingOptions & Record<string, any>) => any;
+/**
+ * What a DataType's own `decodeTextBuffer` implements: the same value
+ * `decodeText` would be given, still as bytes in the shared row buffer.
+ */
 export type DecodeTextBufferFunction = (buf: Buffer, offset: number, len: number, options: DataMappingOptions & Record<string, any>) => any;
+/** What a DataType's own `encodeBinary` implements: writes the value into the send buffer. */
 export type EncodeBinaryFunction = (buf: SmartBuffer, v: any, options: DataMappingOptions) => void;
+/** Measures an array's dimensions, for a type whose own values are arrays. */
 export type EncodeCalculateDimFunction = (v: any[]) => number[];
+/** Whether this value should go out as SQL NULL instead of being encoded. */
 export type EncodeAsNullFunction = (v: any, options: DataMappingOptions) => boolean;
+/** What a DataType's own `decodeText` implements: reads the value out of the server's text. */
 export type DecodeTextFunction = (v: any, options: DataMappingOptions) => any;
+/** What a DataType's own `encodeText` implements: renders the value as text the server parses. */
 export type EncodeTextFunction = (v: any, options: DataMappingOptions) => string;
+/**
+ * One column's parser, already chosen for the format that column arrives
+ * in: called with the whole row's buffer and where this value sits in
+ * it.
+ */
 export type ResolvedColumnParser = (data: Buffer, offset: number, len: number, options: DataMappingOptions & Record<string, any>) => any;
+/** Any of the decode functions, which all share the column parser's shape. */
 export type AnyParseFunction = ResolvedColumnParser;
+/** What `debugLogger` is called with - a namespace, then `util.format` arguments. */
 export type DebugLogger = (namespace: string, format: any, ...args: any[]) => void;

package/util/array-calculatedim.d.ts

@@ -1 +1,11 @@
+/**
+ * The dimensions of a nested array, each level sized to its longest row.
+ *
+ * PostgreSQL arrays are rectangular: every row of a level has the same
+ * length. A ragged JavaScript array is squared off against these numbers
+ * by the writers, with the missing elements written as NULL.
+ *
+ * @param arr The array to measure.
+ * @returns One length per level; `[0]` for an empty array.
+ */
 export declare function arrayCalculateDim(arr: any[]): number[];

package/util/array-calculatedim.js

@@ -1,3 +1,13 @@
+/**
+ * The dimensions of a nested array, each level sized to its longest row.
+ *
+ * PostgreSQL arrays are rectangular: every row of a level has the same
+ * length. A ragged JavaScript array is squared off against these numbers
+ * by the writers, with the missing elements written as NULL.
+ *
+ * @param arr The array to measure.
+ * @returns One length per level; `[0]` for an empty array.
+ */
 export function arrayCalculateDim(arr) {
     if (!arr || arr.length === 0)
         return [0];

package/util/assert-integer.d.ts

@@ -1,22 +1,48 @@
 /**
- * Returns `v` coerced to an integer, or throws when it cannot be one.
+ * Returns `v` as the integer an integer column can store, or throws.
  *
- * `fastParseInt()` already answers NaN for a value with no integer reading
- * - `'abc'`, `{}`, `[]`, `true` - but `Buffer.writeInt32BE(NaN)` then
- * stores a silent zero, so the answer is lost exactly where it matters.
- * Nothing downstream can tell that apart from a real zero afterwards: the
- * row inserts, the copy succeeds, and the wrong number is in the table.
+ * The rule is that the binary encoding must accept exactly what the text
+ * one does and refuse exactly what the server refuses, because which of
+ * the two a value goes out as is not the caller's choice: it depends on
+ * whether the parameter's type was declared, which statement cache the
+ * query hit, and what the server resolved. A value that means one thing
+ * through one path and another through the other is the worst outcome
+ * there is, and that is what this used to be:
  *
- * Floats are deliberately not rejected: truncating 3.7 to 3 is the
- * long-standing behaviour of these encoders and is usually what a caller
- * writing into an integer column means. Only "this is not a number at all"
- * is refused.
+ * ```
+ *                             text          binary (before)
+ * [1.5]     -> int4[]         22P02 error   stored 1
+ * [-1.5]    -> int4[]         22P02 error   stored -2   (a floor, not a truncation)
+ * ['0x10']  -> int4[]         22P02 error   stored 0
+ * ['']      -> int8[]         22P02 error   stored 0
+ * [40000]   -> int2[]         22003 error   RangeError, from Buffer
+ * ```
  *
- * Unlike the integer types, float4/float8/numeric leave NaN alone - it is a
- * value PostgreSQL stores and returns as NaN, distinct from NULL, on every
- * supported server version.
+ * Only the last of those was safe. The rest put a number in the table
+ * that the caller never wrote and the server would have refused, and
+ * silently - the row inserted, the copy succeeded.
+ *
+ * So a fractional value is refused rather than floored. Truncating 3.7
+ * to 3 was the long-standing behaviour here and the argument for it was
+ * that it is usually what a caller writing into an integer column means;
+ * what that argument misses is that the same caller writing the same
+ * value through the same client gets an error whenever the encoding
+ * happens to be text, so it cannot be what they meant. Round or truncate
+ * at the call site, or let the server do it with a cast.
+ *
+ * `min`/`max` are checked here as well, rather than left to Buffer's own
+ * bounds check, so that the message names the type and the value.
+ */
+export declare function assertInteger(v: any, typeName: string, min: number, max: number): number;
+/**
+ * The same rule for int8, which counts past what a `number` holds.
+ *
+ * BigInt is happy to convert things that are not numbers at all -
+ * `BigInt('')` is 0n because an empty string reads as zero, `BigInt(true)`
+ * is 1n - so a bad value in a bigint column used to land as a plausible
+ * 0 or 1. Only what genuinely carries an exact integer is let through.
  */
-export declare function assertInteger(v: number, typeName: string): number;
+export declare function assertBigInt(v: any, typeName: string): bigint;
 /**
  * Returns `parsed` when a value that was NOT already a number coerced to
  * one, and throws when it did not.
@@ -30,14 +56,3 @@ export declare function assertInteger(v: number, typeName: string): number;
  * as NaN would be indistinguishable afterwards from a NaN that was meant.
  */
 export declare function assertCoercedNumber(parsed: number, typeName: string): number;
-/**
- * Refuses a value that only has an integer reading through a coercion
- * nobody asked for.
- *
- * int8 goes to `BigInt` rather than through `fastParseInt()`, and BigInt is
- * happy to convert things that are not numbers at all: `BigInt([])` is 0n
- * because an empty array stringifies to "", and `BigInt(true)` is 1n. A
- * bad value in a bigint column would land as a plausible-looking 0 or 1,
- * so only the types that genuinely carry an integer are let through.
- */
-export declare function assertBigIntSource(v: any, typeName: string): bigint | number;

package/util/assert-integer.js

@@ -1,26 +1,107 @@
 /**
- * Returns `v` coerced to an integer, or throws when it cannot be one.
+ * What the server reads as an integer from text: optional sign, digits,
+ * nothing else. `'1.5'`, `'1e3'` and `'0x10'` are all refused by
+ * `int4in()`, and surrounding whitespace is trimmed before it looks.
+ */
+const DECIMAL_INTEGER = /^[+-]?\d+$/;
+/**
+ * Returns `v` as the integer an integer column can store, or throws.
+ *
+ * The rule is that the binary encoding must accept exactly what the text
+ * one does and refuse exactly what the server refuses, because which of
+ * the two a value goes out as is not the caller's choice: it depends on
+ * whether the parameter's type was declared, which statement cache the
+ * query hit, and what the server resolved. A value that means one thing
+ * through one path and another through the other is the worst outcome
+ * there is, and that is what this used to be:
  *
- * `fastParseInt()` already answers NaN for a value with no integer reading
- * - `'abc'`, `{}`, `[]`, `true` - but `Buffer.writeInt32BE(NaN)` then
- * stores a silent zero, so the answer is lost exactly where it matters.
- * Nothing downstream can tell that apart from a real zero afterwards: the
- * row inserts, the copy succeeds, and the wrong number is in the table.
+ * ```
+ *                             text          binary (before)
+ * [1.5]     -> int4[]         22P02 error   stored 1
+ * [-1.5]    -> int4[]         22P02 error   stored -2   (a floor, not a truncation)
+ * ['0x10']  -> int4[]         22P02 error   stored 0
+ * ['']      -> int8[]         22P02 error   stored 0
+ * [40000]   -> int2[]         22003 error   RangeError, from Buffer
+ * ```
  *
- * Floats are deliberately not rejected: truncating 3.7 to 3 is the
- * long-standing behaviour of these encoders and is usually what a caller
- * writing into an integer column means. Only "this is not a number at all"
- * is refused.
+ * Only the last of those was safe. The rest put a number in the table
+ * that the caller never wrote and the server would have refused, and
+ * silently - the row inserted, the copy succeeded.
  *
- * Unlike the integer types, float4/float8/numeric leave NaN alone - it is a
- * value PostgreSQL stores and returns as NaN, distinct from NULL, on every
- * supported server version.
+ * So a fractional value is refused rather than floored. Truncating 3.7
+ * to 3 was the long-standing behaviour here and the argument for it was
+ * that it is usually what a caller writing into an integer column means;
+ * what that argument misses is that the same caller writing the same
+ * value through the same client gets an error whenever the encoding
+ * happens to be text, so it cannot be what they meant. Round or truncate
+ * at the call site, or let the server do it with a cast.
+ *
+ * `min`/`max` are checked here as well, rather than left to Buffer's own
+ * bounds check, so that the message names the type and the value.
  */
-export function assertInteger(v, typeName) {
-    if (Number.isNaN(v)) {
+export function assertInteger(v, typeName, min, max) {
+    let n;
+    const t = typeof v;
+    if (t === 'number') {
+        n = v;
+        if (Number.isNaN(n))
+            throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
+    }
+    else if (t === 'bigint') {
+        // Exact up to 2^53; beyond that the range check below refuses it
+        // anyway, since nothing this function guards is that wide.
+        n = Number(v);
+    }
+    else if (t === 'string') {
+        const s = v.trim();
+        if (!DECIMAL_INTEGER.test(s))
+            throw new TypeError(`Cannot encode "${v}" as ${typeName}: it is not an integer`);
+        n = +s;
+    }
+    else {
         throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
     }
-    return v;
+    if (!Number.isInteger(n))
+        throw new TypeError(`Cannot encode ${n} as ${typeName}: it is not an integer`);
+    if (n < min || n > max)
+        throw new RangeError(`Cannot encode ${n} as ${typeName}: it is out of range (${min} to ${max})`);
+    return n;
+}
+const INT8_MIN = BigInt('-9223372036854775808');
+const INT8_MAX = BigInt('9223372036854775807');
+/**
+ * The same rule for int8, which counts past what a `number` holds.
+ *
+ * BigInt is happy to convert things that are not numbers at all -
+ * `BigInt('')` is 0n because an empty string reads as zero, `BigInt(true)`
+ * is 1n - so a bad value in a bigint column used to land as a plausible
+ * 0 or 1. Only what genuinely carries an exact integer is let through.
+ */
+export function assertBigInt(v, typeName) {
+    let n;
+    const t = typeof v;
+    if (t === 'bigint') {
+        n = v;
+    }
+    else if (t === 'number') {
+        if (!Number.isInteger(v))
+            throw new TypeError(Number.isNaN(v)
+                ? `Cannot encode value as ${typeName}: it has no integer value`
+                : `Cannot encode ${v} as ${typeName}: it is not an integer`);
+        n = BigInt(v);
+    }
+    else if (t === 'string') {
+        const s = v.trim();
+        if (!DECIMAL_INTEGER.test(s))
+            throw new TypeError(`Cannot encode "${v}" as ${typeName}: it is not an integer`);
+        n = BigInt(s);
+    }
+    else {
+        throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
+    }
+    if (n < INT8_MIN || n > INT8_MAX)
+        throw new RangeError(`Cannot encode ${n} as ${typeName}: it is out of range (${INT8_MIN} to ${INT8_MAX})`);
+    return n;
 }
 /**
  * Returns `parsed` when a value that was NOT already a number coerced to
@@ -40,19 +121,3 @@ export function assertCoercedNumber(parsed, typeName) {
     }
     return parsed;
 }
-/**
- * Refuses a value that only has an integer reading through a coercion
- * nobody asked for.
- *
- * int8 goes to `BigInt` rather than through `fastParseInt()`, and BigInt is
- * happy to convert things that are not numbers at all: `BigInt([])` is 0n
- * because an empty array stringifies to "", and `BigInt(true)` is 1n. A
- * bad value in a bigint column would land as a plausible-looking 0 or 1,
- * so only the types that genuinely carry an integer are let through.
- */
-export function assertBigIntSource(v, typeName) {
-    const t = typeof v;
-    if (t === 'bigint' || t === 'number' || t === 'string')
-        return v;
-    throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
-}

package/util/bigint-methods.d.ts

@@ -1 +1,8 @@
+/**
+ * `Buffer.readBigInt64BE` for a runtime that does not have it.
+ *
+ * @param buf The buffer to read from.
+ * @param offset Where the eight bytes start.
+ * @returns The signed 64-bit value.
+ */
 export declare function readBigInt64BE(buf: Buffer, offset?: number): bigint;

package/util/bigint-methods.js

@@ -2,6 +2,15 @@
 const big0 = BigInt(0);
 const big32 = BigInt(32);
 // https://github.com/nodejs/node/blob/v13.9.0/lib/internal/buffer.js
+/**
+ * `Buffer.readBigInt64BE` for a runtime that does not have it.
+ *
+ * @param buf The buffer to read from.
+ * @param offset Where the eight bytes start.
+ * @returns The signed 64-bit value.
+ */
+/* Ported from Node's own lib/internal/buffer.js (v13.9.0), so the two
+   agree bit for bit where both exist. */
 export function readBigInt64BE(buf, offset = 0) {
     const first = buf[offset];
     const last = buf[offset + 7];

package/util/config-from-env.d.ts

@@ -1,2 +1,12 @@
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
+/**
+ * What the environment says about where to connect.
+ *
+ * The variables `psql` itself reads - `PGHOST`, `PGPORT`, `PGUSER`,
+ * `PGPASSWORD`, `PGDATABASE` and the rest - so a program configured for
+ * one is configured for the other.
+ *
+ * @returns Whatever the environment named; anything it did not is left
+ * out rather than defaulted here.
+ */
 export declare function configFromEnv(): ConnectionConfiguration;

package/util/config-from-env.js

@@ -1,4 +1,14 @@
 import { toInt, toIntDef } from 'putil-varhelpers';
+/**
+ * What the environment says about where to connect.
+ *
+ * The variables `psql` itself reads - `PGHOST`, `PGPORT`, `PGUSER`,
+ * `PGPASSWORD`, `PGDATABASE` and the rest - so a program configured for
+ * one is configured for the other.
+ *
+ * @returns Whatever the environment named; anything it did not is left
+ * out rather than defaulted here.
+ */
 export function configFromEnv() {
     const env = process.env;
     const result = {};

package/util/connection-config.d.ts

@@ -1,3 +1,20 @@
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
+/**
+ * Resolves what a caller passed into the configuration a connection is
+ * opened with.
+ *
+ * @param config An object, a connection string, or nothing at all.
+ * @returns The configuration, with the environment and PostgreSQL's own
+ * defaults filling what was left out.
+ * @throws Error When a field is named that no configuration has, which
+ * is usually a typo and is reported with what was probably meant.
+ */
 export declare function getConnectionConfig(config?: ConnectionConfiguration | string): ConnectionConfiguration;
+/**
+ * Reads a `postgres://` URL, or the `host=... port=...` keyword form,
+ * into a configuration.
+ *
+ * @param str The connection string.
+ * @returns What it named.
+ */
 export declare function parseConnectionString(str: string): ConnectionConfiguration;

package/util/connection-config.js

@@ -39,6 +39,16 @@ function checkForeignKeys(config) {
                 'name that is nearly right does nothing and says nothing.');
     }
 }
+/**
+ * Resolves what a caller passed into the configuration a connection is
+ * opened with.
+ *
+ * @param config An object, a connection string, or nothing at all.
+ * @returns The configuration, with the environment and PostgreSQL's own
+ * defaults filling what was left out.
+ * @throws Error When a field is named that no configuration has, which
+ * is usually a typo and is reported with what was probably meant.
+ */
 export function getConnectionConfig(config) {
     const cfg = configFromEnv();
     if (typeof config === 'string') {
@@ -125,6 +135,13 @@ function splitHosts(value, fallbackPort) {
  * has been accepted for longer than either and stays.
  */
 const DATABASE_PATH_SCHEMES = ['pg:', 'postgres:', 'postgresql:'];
+/**
+ * Reads a `postgres://` URL, or the `host=... port=...` keyword form,
+ * into a configuration.
+ *
+ * @param str The connection string.
+ * @returns What it named.
+ */
 export function parseConnectionString(str) {
     if (str.startsWith('/'))
         str = 'socket:/' + str;

package/util/copy-from-rows.d.ts

@@ -3,7 +3,9 @@ import type { CopyFromRowsOptions } from '../interfaces/copy-from-rows-options.j
 import type { OID } from '../types.js';
 /** Default bytes accumulated before a CopyData message goes out. */
 export declare const DEFAULT_COPY_CHUNK_SIZE: number;
+/** One row to copy: values in column order, or keyed by column name. */
 export type CopyRow = any[] | Record<string, any>;
+/** Where `copyFromRows()` takes its rows from - an array, an iterable, an async one, or a stream. */
 export type CopyRowSource = Iterable<CopyRow> | AsyncIterable<CopyRow> | Readable;
 /**
  * Quotes a possibly schema-qualified name. A single dot separates schema
@@ -21,7 +23,17 @@ export declare function quoteQualifiedName(name: string): string;
  * name here could only approximate.
  */
 export declare function buildProbeSql(table: string, columns?: string[]): string;
+/**
+ * Writes the `COPY ... FROM STDIN (FORMAT binary)` the rows will be sent
+ * under.
+ *
+ * @param table The destination, optionally schema-qualified.
+ * @param columns Which columns the rows line up with; all of them when
+ * absent.
+ * @returns The statement.
+ */
 export declare function buildCopySql(table: string, columns?: string[]): string;
+/** What a copy in flight needs to keep between its chunks. */
 export interface CopyFromRowsContext {
     columns: string[];
     dataTypeIds: OID[];

package/util/copy-from-rows.js

@@ -30,6 +30,15 @@ export function buildProbeSql(table, columns) {
     const cols = columns?.length ? columns.map(escapeIdentifier).join(', ') : '*';
     return `select ${cols} from ${quoteQualifiedName(table)} where false`;
 }
+/**
+ * Writes the `COPY ... FROM STDIN (FORMAT binary)` the rows will be sent
+ * under.
+ *
+ * @param table The destination, optionally schema-qualified.
+ * @param columns Which columns the rows line up with; all of them when
+ * absent.
+ * @returns The statement.
+ */
 export function buildCopySql(table, columns) {
     const cols = columns?.length
         ? ' (' + columns.map(escapeIdentifier).join(', ') + ')'

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

@@ -8,4 +8,10 @@ import type { Maybe, OID } from '../types.js';
 export declare const DecimalAsStringOIDs: readonly OID[];
 /** Whether this type's values are wanted as their exact decimal string. */
 export declare function wantsDecimalString(options: Maybe<DataMappingOptions>, oid: OID): boolean;
+/**
+ * Refuses a `decimalAsString` that names a type it cannot apply to.
+ *
+ * @param v The option as the caller wrote it.
+ * @throws TypeError When it names an OID outside the decimal types.
+ */
 export declare function validateDecimalAsString(v: Maybe<boolean | OID[]>): void;

package/util/decimal-as-string.js

@@ -15,6 +15,12 @@ export function wantsDecimalString(options, oid) {
         return false;
     return v === true || v.includes(oid);
 }
+/**
+ * Refuses a `decimalAsString` that names a type it cannot apply to.
+ *
+ * @param v The option as the caller wrote it.
+ * @throws TypeError When it names an OID outside the decimal types.
+ */
 export function validateDecimalAsString(v) {
     if (v === undefined || typeof v === 'boolean')
         return;

package/util/decode-binaryarray.d.ts

@@ -1,3 +1,12 @@
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { DecodeBinaryFunction, Nullable } from '../types.js';
+/**
+ * Reads an array out of the binary wire format, nested to whatever depth
+ * it declares.
+ *
+ * @param buf The value's own bytes.
+ * @param decode The element type's binary decoder.
+ * @param options Passed to it.
+ * @returns The array, with SQL NULLs as `null`.
+ */
 export declare function decodeBinaryArray<T = any>(buf: Buffer, offset: number, decoder: DecodeBinaryFunction, options?: DataMappingOptions): Nullable<T[]>;

package/util/decode-binaryarray.js

@@ -1,4 +1,13 @@
 import { BufferReader } from '../protocol/buffer-reader.js';
+/**
+ * Reads an array out of the binary wire format, nested to whatever depth
+ * it declares.
+ *
+ * @param buf The value's own bytes.
+ * @param decode The element type's binary decoder.
+ * @param options Passed to it.
+ * @returns The array, with SQL NULLs as `null`.
+ */
 export function decodeBinaryArray(buf, offset, decoder, options = {}) {
     if (!buf.length)
         return null;

package/util/escape-literal.d.ts

@@ -1 +1,12 @@
+/**
+ * Quotes a string as an SQL literal, escaping what has to be escaped.
+ *
+ * For the `sql` tag and anything else that has to put a value into the
+ * statement text; a parameter never needs this.
+ *
+ * @param str The value to quote.
+ * @returns The quoted literal, `E`-prefixed when it carries a backslash.
+ * @throws Error When the string holds a NUL byte, which PostgreSQL text
+ * cannot.
+ */
 export declare function escapeLiteral(str: string): string;

package/util/escape-literal.js

@@ -1,4 +1,17 @@
 // Ported from PostgreSQL 9.2.4 source code in src/interfaces/libpq/fe-exec.c
+/**
+ * Quotes a string as an SQL literal, escaping what has to be escaped.
+ *
+ * For the `sql` tag and anything else that has to put a value into the
+ * statement text; a parameter never needs this.
+ *
+ * @param str The value to quote.
+ * @returns The quoted literal, `E`-prefixed when it carries a backslash.
+ * @throws Error When the string holds a NUL byte, which PostgreSQL text
+ * cannot.
+ */
+/* Ported from PostgreSQL's own src/interfaces/libpq/fe-exec.c (9.2.4),
+   so it quotes what libpq quotes, the way libpq quotes it. */
 export function escapeLiteral(str) {
     if (str.indexOf('\0') >= 0) {
         throw new Error('PostgreSQL text values cannot contain NUL (\\0) bytes');

package/util/fast-parseint.d.ts

@@ -1,2 +1,16 @@
+/**
+ * Reads an integer out of what a decoder was handed.
+ *
+ * @param str The text, or a number already.
+ * @returns The integer, or NaN when there is none to read.
+ */
 export declare function fastParseInt(str: string | number): number;
+/**
+ * The same, straight from the wire bytes - no string is made.
+ *
+ * @param buf The buffer holding the digits.
+ * @param offset Where they start.
+ * @param len How many bytes they run for.
+ * @returns The integer the digits spell.
+ */
 export declare function fastParseIntBuffer(buf: Buffer, offset?: number, len?: number): number;

package/util/fast-parseint.js

@@ -1,3 +1,9 @@
+/**
+ * Reads an integer out of what a decoder was handed.
+ *
+ * @param str The text, or a number already.
+ * @returns The integer, or NaN when there is none to read.
+ */
 export function fastParseInt(str) {
     /* c8 ignore next */
     if (typeof str === 'number')
@@ -7,6 +13,14 @@ export function fastParseInt(str) {
         return NaN;
     return parseInt(str, 10);
 }
+/**
+ * The same, straight from the wire bytes - no string is made.
+ *
+ * @param buf The buffer holding the digits.
+ * @param offset Where they start.
+ * @param len How many bytes they run for.
+ * @returns The integer the digits spell.
+ */
 export function fastParseIntBuffer(buf, offset = 0, len = buf.length - offset) {
     const end = offset + len;
     let i = offset;

package/util/format-datetime.d.ts

@@ -1,6 +1,32 @@
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
+/**
+ * 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 declare function formatDate(v: Date | number | string, options?: DataMappingOptions): string;
+/**
+ * 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 declare function formatTime(v: Date | number | string, options?: DataMappingOptions): string;
+/**
+ * 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 declare function formatTimestamp(v: Date | number | string, options?: DataMappingOptions): string;
 /**
  * timestamptz is an absolute instant - its binary encoder uses getTime()