postgrejs 3.11.1 → 3.12.1

package/protocol/cert-signature.d.ts

@@ -9,4 +9,12 @@
  * signatureAlgorithm and signatureValue, so this skips the first and reads
  * the OID out of the second.
  */
+/**
+ * The hash a certificate was signed with, for `tls-server-end-point`
+ * channel binding.
+ *
+ * @param der The server's certificate, as DER.
+ * @returns The Node digest name to bind with - SHA-256 where the
+ * signature's own hash is MD5 or SHA-1, as the RFC requires.
+ */
 export declare function signatureHashOfCertificate(der: Buffer): string;

package/protocol/cert-signature.js

@@ -79,6 +79,14 @@ const PSS_HASHES = {
     '2.16.840.1.101.3.4.2.2': 'sha384',
     '2.16.840.1.101.3.4.2.3': 'sha512',
 };
+/**
+ * The hash a certificate was signed with, for `tls-server-end-point`
+ * channel binding.
+ *
+ * @param der The server's certificate, as DER.
+ * @returns The Node digest name to bind with - SHA-256 where the
+ * signature's own hash is MD5 or SHA-1, as the RFC requires.
+ */
 export function signatureHashOfCertificate(der) {
     let index = expectSequence(der, 0).index; // Certificate
     const tbs = readLength(der, index + 1); // tbsCertificate's own header

package/protocol/database-error.d.ts

@@ -1,5 +1,13 @@
 import type { BatchCommandResult } from '../interfaces/batch-result.js';
 import { Protocol } from './protocol.js';
+/**
+ * An error the server reported, with every field it sent.
+ *
+ * `code` is the five-character SQLSTATE and is the thing to branch on -
+ * `23505` for a unique violation, `40P01` for a deadlock - since the
+ * message is localized and may be reworded between releases. `detail`,
+ * `hint`, `position` and the rest are there when the server sent them.
+ */
 export declare class DatabaseError extends Error {
     /**
      * Which entry of a multi-statement submission the server rejected -

package/protocol/database-error.js

@@ -1,4 +1,12 @@
 import { Protocol } from './protocol.js';
+/**
+ * An error the server reported, with every field it sent.
+ *
+ * `code` is the five-character SQLSTATE and is the thing to branch on -
+ * `23505` for a unique violation, `40P01` for a deadlock - since the
+ * message is localized and may be reworded between releases. `detail`,
+ * `hint`, `position` and the rest are there when the server sent them.
+ */
 export class DatabaseError extends Error {
     /**
      * Which entry of a multi-statement submission the server rejected -

package/protocol/frontend.d.ts

@@ -4,15 +4,20 @@ import type { Maybe, OID } from '../types.js';
 import { Protocol } from './protocol.js';
 import type { SASL } from './sasl.js';
 import { type SmartBufferConfig } from './smart-buffer.js';
+/** How a `Frontend` builds its messages - the buffer it writes them into. */
 export interface FrontendOptions {
+    /** The send buffer's own configuration. */
     buffer?: SmartBufferConfig;
 }
+/** What each message the client sends is built from. */
 export declare namespace Frontend {
+    /** The startup packet: who is connecting, to what, and any session settings to carry with it. */
     interface StartupMessageArgs {
         user: string;
         database: string;
         [index: string]: string;
     }
+    /** A Bind: which statement, which portal, the parameters and the formats to read the result in. */
     interface BindMessageArgs {
         typeMap: DataTypeMap;
         statement?: string;
@@ -28,19 +33,23 @@ export declare namespace Frontend {
          */
         columnFormat?: Protocol.DataFormat | Protocol.DataFormat[];
     }
+    /** A Parse: the SQL, the name to give it, and any parameter types to declare. */
     interface ParseMessageArgs {
         statement?: string;
         sql: string;
         paramTypes?: Maybe<OID>[];
     }
+    /** A Describe: of a statement (`S`) or of a portal (`P`). */
     interface DescribeMessageArgs {
         type: 'P' | 'S';
         name?: string;
     }
+    /** An Execute: which portal, and how many rows to stop at. */
     interface ExecuteMessageArgs {
         portal?: string;
         fetchCount?: number;
     }
+    /** A Close: of a statement (`S`) or of a portal (`P`). */
     interface CloseMessageArgs {
         type: 'P' | 'S';
         name?: string;
@@ -69,6 +78,13 @@ export declare namespace Frontend {
         resultFormat?: Protocol.DataFormat;
     }
 }
+/**
+ * Builds the client's messages, into one buffer it keeps and reuses.
+ *
+ * Each method returns the bytes of one message; the socket writes them,
+ * often several at a time so a statement costs one round trip rather
+ * than one per message.
+ */
 export declare class Frontend {
     private _io;
     constructor(options?: FrontendOptions);

package/protocol/frontend.js

@@ -3,7 +3,7 @@ import { DataTypeMap } from '../data-type-map.js';
 import { arrayLeaf } from '../util/array-leaf.js';
 import { encodeBinaryArray } from '../util/encode-binaryarray.js';
 import { formatDateParam } from '../util/format-datetime.js';
-import { stringifyArrayLiteral } from '../util/stringify-arrayliteral.js';
+import { writeArrayLiteral } from '../util/stringify-arrayliteral.js';
 import { Protocol } from './protocol.js';
 import { SmartBuffer } from './smart-buffer.js';
 const DataFormat = Protocol.DataFormat;
@@ -35,6 +35,13 @@ const StaticCopyDoneBuffer = Buffer.from([
     0x00,
     0x04,
 ]);
+/**
+ * Builds the client's messages, into one buffer it keeps and reuses.
+ *
+ * Each method returns the bytes of one message; the socket writes them,
+ * often several at a time so a statement costs one round trip rather
+ * than one per message.
+ */
 export class Frontend {
     _io;
     constructor(options) {
@@ -182,10 +189,10 @@ export class Frontend {
                         io.buffer.writeInt32BE(io.size - dataOffset, dataOffset - 4); // Update length
                     }
                     else if (typeof dt.encodeText === 'function') {
-                        v = dt.elementsOID
-                            ? stringifyArrayLiteral(v, queryOptions, dt.encodeText)
-                            : dt.encodeText(v, queryOptions);
-                        io.writeLString(v, 'utf8');
+                        if (dt.elementsOID)
+                            writeArrayLiteral(io, v, queryOptions, dt.encodeText);
+                        else
+                            io.writeLString(dt.encodeText(v, queryOptions), 'utf8');
                     }
                 }
                 else if (v instanceof Date) {
@@ -201,7 +208,7 @@ export class Frontend {
                     // takes the element type from the column. `'' + v` would hand
                     // it `a,b`, which is not one - the elements have to be quoted
                     // and the braces written, and a nested array needs its own.
-                    io.writeLString(stringifyArrayLiteral(v, queryOptions, arrayLeaf(v) instanceof Date ? formatDateParam : undefined), 'utf8');
+                    writeArrayLiteral(io, v, queryOptions, arrayLeaf(v) instanceof Date ? formatDateParam : undefined);
                 }
                 else if (Buffer.isBuffer(v)) {
                     // Set param format to binary

package/protocol/pg-socket.d.ts

@@ -6,10 +6,20 @@ import { SafeEventEmitter } from '../safe-event-emitter.js';
 import type { Callback, Maybe } from '../types.js';
 import { Frontend } from './frontend.js';
 import { Protocol } from './protocol.js';
+/**
+ * What a sender registers to receive the messages its statement
+ * provokes, until it calls `done`.
+ */
 export type CaptureCallback = (code: Protocol.BackendMessageCode, msg: any, done: (err: Maybe<Error>, result?: any) => void) => void | Promise<void>;
+/** A socket-level failure, with the code the platform gave it. */
 export interface SocketError extends Error {
     code: string;
 }
+/**
+ * The connected socket: the handshake, the authentication, TLS where it
+ * is asked for, and a queue that pairs each response with whoever sent
+ * the statement that caused it.
+ */
 export declare class PgSocket extends SafeEventEmitter {
     options: ConnectionConfiguration;
     private _state;

package/protocol/pg-socket.js

@@ -15,6 +15,11 @@ import { Protocol } from './protocol.js';
 import { SASL } from './sasl.js';
 const DEFAULT_PORT_NUMBER = 5432;
 const COMMAND_RESULT_PATTERN = /^([^\d]+)(?: (\d+)(?: (\d+))?)?$/;
+/**
+ * The connected socket: the handshake, the authentication, TLS where it
+ * is asked for, and a queue that pairs each response with whoever sent
+ * the statement that caused it.
+ */
 export class PgSocket extends SafeEventEmitter {
     options;
     _state = ConnectionState.CLOSED;
@@ -588,13 +593,15 @@ export class PgSocket extends SafeEventEmitter {
         this.sendQueryMessage('select pg_catalog.pg_is_in_recovery()::text as a,' +
             " current_setting('transaction_read_only') as b", (code, msg, done) => {
             if (code === Protocol.BackendMessageCode.DataRow) {
-                // Two text columns, each length-prefixed within the row buffer.
-                const data = msg.data;
-                const aLen = data.readInt32BE(0);
-                const a = data.toString('utf8', 4, 4 + aLen);
-                const bOffset = 4 + aLen;
-                const bLen = data.readInt32BE(bOffset);
-                const b = data.toString('utf8', bOffset + 4, bOffset + 4 + bLen);
+                // Two text columns, each length-prefixed, read where the row
+                // already sits in the read buffer.
+                const buffer = msg.buffer;
+                const start = msg.offset;
+                const aLen = buffer.readInt32BE(start);
+                const a = buffer.toString('utf8', start + 4, start + 4 + aLen);
+                const bOffset = start + 4 + aLen;
+                const bLen = buffer.readInt32BE(bOffset);
+                const b = buffer.toString('utf8', bOffset + 4, bOffset + 4 + bLen);
                 this._standbyState = { standby: a === 'true', readOnly: b === 'on' };
             }
             else if (code === Protocol.BackendMessageCode.ReadyForQuery) {

package/protocol/pgoutput.d.ts

@@ -1,4 +1,5 @@
 import { BufferReader } from './buffer-reader.js';
+/** One column of a replicated table, as the stream declared it. */
 export interface PgOutputColumn {
     name: string;
     dataTypeId: number;
@@ -6,6 +7,12 @@ export interface PgOutputColumn {
     /** Part of the replica identity, so it can identify a row on its own. */
     isKey: boolean;
 }
+/**
+ * A replicated table, declared once and then referred to by id.
+ *
+ * The stream sends this before the first change to that table and not
+ * again, so a decoder has to remember it.
+ */
 export interface PgOutputRelation {
     relationId: number;
     schema: string;
@@ -13,6 +20,7 @@ export interface PgOutputRelation {
     replicaIdentity: string;
     columns: PgOutputColumn[];
 }
+/** Any message the `pgoutput` plugin sends, decoded. */
 export type PgOutputMessage = {
     kind: 'begin';
     finalLsn: bigint;
@@ -66,6 +74,13 @@ export type PgOutputMessage = {
  * from the map entirely - which is not the same as being null.
  */
 export type TupleValues = Record<string, string | null>;
+/**
+ * Reads the `pgoutput` logical replication stream.
+ *
+ * Keeps the relations the stream declares, so each change can be
+ * reported with the table and column names it belongs to rather than
+ * the ids the wire uses.
+ */
 export declare class PgOutputDecoder {
     protected readonly _relations: Map<number, PgOutputRelation>;
     decode(data: Buffer): PgOutputMessage;

package/protocol/pgoutput.js

@@ -10,6 +10,13 @@ import { BufferReader } from './buffer-reader.js';
  */
 /** Microseconds since 2000-01-01, which is how this protocol tells time. */
 const PG_EPOCH_MS = Date.UTC(2000, 0, 1);
+/**
+ * Reads the `pgoutput` logical replication stream.
+ *
+ * Keeps the relations the stream declares, so each change can be
+ * reported with the table and column names it belongs to rather than
+ * the ids the wire uses.
+ */
 export class PgOutputDecoder {
     _relations = new Map();
     decode(data) {

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 {