postgrejs 3.12.0 → 3.12.2

package/protocol/protocol.d.ts

@@ -1,5 +1,15 @@
+/**
+ * The wire protocol itself: the message codes, the shapes each message
+ * carries, and the version numbers the handshake negotiates.
+ *
+ * These are PostgreSQL's own definitions, named as the documentation
+ * names them - nothing here is this client's invention, and a reader
+ * comparing it against the protocol pages should find the two line up.
+ */
 export declare namespace Protocol {
+    /** The protocol major version, which has been 3 since PostgreSQL 7.4. */
     const VERSION_MAJOR = 3;
+    /** The minor version a connection asks for by default. */
     const VERSION_MINOR = 0;
     /**
      * Minor version 3.2 (PostgreSQL 18+) differs from 3.0 only in that
@@ -11,6 +21,7 @@ export declare namespace Protocol {
      * never a connection-breaking choice, only ever a possible no-op.
      */
     const VERSION_MINOR_LONG_CANCEL_KEY = 2;
+    /** The first byte of each message the server sends. */
     enum BackendMessageCode {
         Authentication = 82,// R
         BackendKeyData = 75,// K
@@ -37,6 +48,7 @@ export declare namespace Protocol {
         ReadyForQuery = 90,// Z
         RowDescription = 84
     }
+    /** The first byte of each message the client sends. */
     enum FrontendMessageCode {
         Bind = 66,// B
         Close = 67,// C
@@ -53,6 +65,7 @@ export declare namespace Protocol {
         Sync = 83,// S
         Terminate = 88
     }
+    /** Which authentication the server asked for, by name rather than by its number. */
     enum AuthenticationMessageKind {
         KerberosV5 = "KerberosV5",
         CleartextPassword = "CleartextPassword",
@@ -65,48 +78,64 @@ export declare namespace Protocol {
         SASLContinue = "SASLContinue",
         SASLFinal = "SASLFinal"
     }
+    /** How a value travels: as the text the server prints, or in its binary form. */
     enum DataFormat {
+        /** The type's own text, as `::text` would render it. */
         text = 0,
+        /** The type's binary form - fewer bytes, and no text to parse. */
         binary = 1
     }
+    /** What every Authentication message carries: which kind it is. */
     interface AuthenticationRequiredMessage {
+        /** The authentication the server is asking for. */
         kind: AuthenticationMessageKind;
     }
+    /** Kerberos V5 authentication is required - not implemented by this client, nor by any modern server. */
     interface AuthenticationKerberosV5Message extends AuthenticationRequiredMessage {
         kind: AuthenticationMessageKind.KerberosV5;
     }
+    /** The server wants the password as it is, which only a trusted transport should be asked for. */
     interface AuthenticationCleartextPasswordMessage extends AuthenticationRequiredMessage {
         kind: AuthenticationMessageKind.CleartextPassword;
     }
+    /** The server wants the password MD5-hashed with the salt it sent. */
     interface AuthenticationMD5PasswordMessage extends AuthenticationRequiredMessage {
         kind: AuthenticationMessageKind.MD5Password;
         salt: Buffer;
     }
+    /** SCM credential authentication, which only ever applied to some unix sockets. */
     interface AuthenticationSCMCredentialMessage extends AuthenticationRequiredMessage {
         kind: AuthenticationMessageKind.SCMCredential;
     }
+    /** GSSAPI authentication is required. */
     interface AuthenticationGSSMessage extends AuthenticationRequiredMessage {
         kind: AuthenticationMessageKind.GSS;
     }
+    /** SSPI authentication is required - the Windows spelling of GSSAPI. */
     interface AuthenticationSSPIMessage extends AuthenticationRequiredMessage {
         kind: AuthenticationMessageKind.SSPI;
     }
+    /** One more round of GSSAPI/SSPI data. */
     interface AuthenticationGSSContinueMessage extends AuthenticationRequiredMessage {
         kind: AuthenticationMessageKind.GSSContinue;
         data: Buffer;
     }
+    /** SASL authentication is required; the message names which mechanisms the server offers. */
     interface AuthenticationSASLMessage extends AuthenticationRequiredMessage {
         kind: AuthenticationMessageKind.SASL;
         mechanisms: string[];
     }
+    /** The server's half of the SCRAM exchange in progress. */
     interface AuthenticationSASLContinueMessage extends AuthenticationRequiredMessage {
         kind: AuthenticationMessageKind.SASLContinue;
         data: string;
     }
+    /** The server's final SCRAM message, which proves it knew the password too. */
     interface AuthenticationSASLFinalMessage extends AuthenticationRequiredMessage {
         kind: AuthenticationMessageKind.SASLFinal;
         data: string;
     }
+    /** The process id and secret key a cancel request has to carry, sent once at startup. */
     interface BackendKeyDataMessage {
         processID: number;
         /**
@@ -118,25 +147,36 @@ export declare namespace Protocol {
          */
         secretKey: Buffer;
     }
+    /** One statement finished: its tag, and what the tag reports. */
     interface CommandCompleteMessage {
         command: string;
         oid?: number;
         rowCount?: number;
     }
+    /** One chunk of a copy in either direction. */
     interface CopyDataMessage {
         data: Buffer;
     }
+    /** A copy is starting: which format it is in, and per column. */
     interface CopyResponseMessage {
         overallFormat: DataFormat;
         columnCount: number;
         columnFormats?: DataFormat[];
     }
+    /** The DataRow message body, kept for its name; `DataRowMessage` is the shape actually used. */
     interface DataRow {
     }
+    /** One row, still as the bytes it arrived in - the values are read out of `data` by the column parsers. */
     interface DataRowMessage {
         columnCount: number;
-        data: Buffer;
-    }
+        /** The read buffer the row's values sit in. */
+        buffer: Buffer;
+        /** Where they start in it. */
+        offset: number;
+        /** How many bytes they run for. */
+        len: number;
+    }
+    /** An error or a notice, with every field the server chose to send. `code` is the SQLSTATE and is the part to branch on. */
     interface ErrorResponseMessage {
         severity?: string;
         code?: string;
@@ -156,15 +196,18 @@ export declare namespace Protocol {
         line?: string;
         routine?: string;
     }
+    /** A `NOTIFY` arriving: which channel, what payload, and which backend sent it. */
     interface NotificationResponseMessage {
         processId: number;
         channel: string;
         payload: string;
     }
+    /** A fast-path function's return value, undecoded - the protocol says nothing about its type. */
     interface FunctionCallResponseMessage {
         /** `null` when the function returned SQL NULL. */
         result: Buffer | null;
     }
+    /** The server does not speak the minor version that was asked for, and names the highest it does. */
     interface NegotiateProtocolVersionMessage {
         /** Newest minor protocol version the server supports. */
         supportedVersionMinor: number;
@@ -175,17 +218,21 @@ export declare namespace Protocol {
          */
         unrecognizedOptions: string[];
     }
+    /** What the server resolved each parameter of a prepared statement to. */
     interface ParameterDescriptionMessage {
         parameterCount: number;
         parameterIds: number[];
     }
+    /** A session setting the server reports, at startup and whenever it changes. */
     interface ParameterStatusMessage {
         name: string;
         value: string;
     }
+    /** The server is ready for the next statement, and says whether a transaction is open. */
     interface ReadyForQueryMessage {
         status: string;
     }
+    /** One column of a result, as the server describes it. */
     interface RowDescription {
         fieldName: string;
         tableId: number;
@@ -195,6 +242,7 @@ export declare namespace Protocol {
         modifier?: number;
         format: DataFormat;
     }
+    /** The columns a statement will return, sent before its rows. */
     interface RowDescriptionMessage {
         fields: RowDescription[];
     }

package/protocol/protocol.js

@@ -1,6 +1,16 @@
+/**
+ * The wire protocol itself: the message codes, the shapes each message
+ * carries, and the version numbers the handshake negotiates.
+ *
+ * These are PostgreSQL's own definitions, named as the documentation
+ * names them - nothing here is this client's invention, and a reader
+ * comparing it against the protocol pages should find the two line up.
+ */
 export var Protocol;
 (function (Protocol) {
+    /** The protocol major version, which has been 3 since PostgreSQL 7.4. */
     Protocol.VERSION_MAJOR = 3;
+    /** The minor version a connection asks for by default. */
     Protocol.VERSION_MINOR = 0;
     /**
      * Minor version 3.2 (PostgreSQL 18+) differs from 3.0 only in that
@@ -12,7 +22,8 @@ export var Protocol;
      * never a connection-breaking choice, only ever a possible no-op.
      */
     Protocol.VERSION_MINOR_LONG_CANCEL_KEY = 2;
-    // https://www.postgresql.org/docs/9.3/protocol-message-formats.html
+    /** The first byte of each message the server sends. */
+    /* https://www.postgresql.org/docs/9.3/protocol-message-formats.html */
     let BackendMessageCode;
     (function (BackendMessageCode) {
         BackendMessageCode[BackendMessageCode["Authentication"] = 82] = "Authentication";
@@ -40,6 +51,7 @@ export var Protocol;
         BackendMessageCode[BackendMessageCode["ReadyForQuery"] = 90] = "ReadyForQuery";
         BackendMessageCode[BackendMessageCode["RowDescription"] = 84] = "RowDescription";
     })(BackendMessageCode = Protocol.BackendMessageCode || (Protocol.BackendMessageCode = {}));
+    /** The first byte of each message the client sends. */
     let FrontendMessageCode;
     (function (FrontendMessageCode) {
         FrontendMessageCode[FrontendMessageCode["Bind"] = 66] = "Bind";
@@ -57,6 +69,7 @@ export var Protocol;
         FrontendMessageCode[FrontendMessageCode["Sync"] = 83] = "Sync";
         FrontendMessageCode[FrontendMessageCode["Terminate"] = 88] = "Terminate";
     })(FrontendMessageCode = Protocol.FrontendMessageCode || (Protocol.FrontendMessageCode = {}));
+    /** Which authentication the server asked for, by name rather than by its number. */
     let AuthenticationMessageKind;
     (function (AuthenticationMessageKind) {
         AuthenticationMessageKind["KerberosV5"] = "KerberosV5";
@@ -70,9 +83,12 @@ export var Protocol;
         AuthenticationMessageKind["SASLContinue"] = "SASLContinue";
         AuthenticationMessageKind["SASLFinal"] = "SASLFinal";
     })(AuthenticationMessageKind = Protocol.AuthenticationMessageKind || (Protocol.AuthenticationMessageKind = {}));
+    /** How a value travels: as the text the server prints, or in its binary form. */
     let DataFormat;
     (function (DataFormat) {
+        /** The type's own text, as `::text` would render it. */
         DataFormat[DataFormat["text"] = 0] = "text";
+        /** The type's binary form - fewer bytes, and no text to parse. */
         DataFormat[DataFormat["binary"] = 1] = "binary";
     })(DataFormat = Protocol.DataFormat || (Protocol.DataFormat = {}));
 })(Protocol || (Protocol = {}));

package/protocol/sasl.d.ts

@@ -1,4 +1,9 @@
+/**
+ * SCRAM-SHA-256, and the channel binding that ties it to the TLS
+ * connection underneath.
+ */
 export declare namespace SASL {
+    /** One exchange in progress: what was sent, and what is needed to check the reply. */
     interface Session {
         username: string;
         mechanism: string;
@@ -18,6 +23,23 @@ export declare namespace SASL {
      *   is what tells the server a stripped -PLUS offer would be an attack.
      */
     function createSession(username: string, mechanism: string, bindingData?: Buffer, supportsBinding?: boolean): Session;
+    /**
+     * Answers the server's first SCRAM message.
+     *
+     * @param session The session started for this connection.
+     * @param password The password to prove knowledge of.
+     * @param serverData The server's message.
+     * @param channelBinding The binding data, when the mechanism uses it.
+     */
     function continueSession(session: Session, password: string, data: string): void;
+    /**
+     * Checks the server's final message, which is what proves the server
+     * knew the password too.
+     *
+     * @param session The session in progress.
+     * @param data The server's final message.
+     * @throws Error When the signature does not match, meaning the server
+     * is not the one it claims to be.
+     */
     function finalizeSession(session: Session, data: string): void;
 }

package/protocol/sasl.js

@@ -1,4 +1,8 @@
 import crypto from 'crypto';
+/**
+ * SCRAM-SHA-256, and the channel binding that ties it to the TLS
+ * connection underneath.
+ */
 export var SASL;
 (function (SASL) {
     const CLIENT_KEY = 'Client Key';
@@ -37,6 +41,14 @@ export var SASL;
         };
     }
     SASL.createSession = createSession;
+    /**
+     * Answers the server's first SCRAM message.
+     *
+     * @param session The session started for this connection.
+     * @param password The password to prove knowledge of.
+     * @param serverData The server's message.
+     * @param channelBinding The binding data, when the mechanism uses it.
+     */
     function continueSession(session, password, data) {
         const s = data.toString();
         const items = s.split(',');
@@ -91,6 +103,15 @@ export var SASL;
             clientFinalMessageWithoutProof + ',p=' + clientProof;
     }
     SASL.continueSession = continueSession;
+    /**
+     * Checks the server's final message, which is what proves the server
+     * knew the password too.
+     *
+     * @param session The session in progress.
+     * @param data The server's final message.
+     * @throws Error When the signature does not match, meaning the server
+     * is not the one it claims to be.
+     */
     function finalizeSession(session, data) {
         let serverSignature = '';
         const arr = data.split(',');

package/protocol/smart-buffer.d.ts

@@ -1,7 +1,11 @@
 import { FlexyBuffer } from 'flexy-buffer';
+/** How a `SmartBuffer` grows, how far, and when it gives the pages back. */
 export interface SmartBufferConfig {
+    /** Bytes added at a time when it has to grow. */
     pageSize?: number;
+    /** The most it may ever hold. */
     maxLength?: number;
+    /** Idle milliseconds before the grown capacity is released. */
     houseKeepMs?: number;
 }
 /**

package/safe-event-emitter.d.ts

@@ -1,4 +1,11 @@
 import { EventEmitter } from 'events';
+/**
+ * An `EventEmitter` whose listeners cannot take the process down.
+ *
+ * A listener that throws would otherwise escape into whatever was
+ * emitting - the socket's own data handler, more often than not - and
+ * an `error` event with nobody listening would throw by definition.
+ */
 export declare class SafeEventEmitter extends EventEmitter {
     emit(event: string | symbol, ...args: any[]): boolean;
 }

package/safe-event-emitter.js

@@ -1,4 +1,11 @@
 import { EventEmitter } from 'events';
+/**
+ * An `EventEmitter` whose listeners cannot take the process down.
+ *
+ * A listener that throws would otherwise escape into whatever was
+ * emitting - the socket's own data handler, more often than not - and
+ * an `error` event with nobody listening would throw by definition.
+ */
 export class SafeEventEmitter extends EventEmitter {
     emit(event, ...args) {
         try {

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