postgrejs 3.12.0 → 3.12.1

package/interfaces/database-connection-params.d.ts

@@ -4,6 +4,14 @@ import type { SmartBufferConfig } from '../protocol/smart-buffer.js';
 import type { DebugLogger } from '../types.js';
 import type { DataMappingOptions } from './data-mapping-options.js';
 import type { QueryOptions } from './query-options.js';
+/**
+ * Where the server is and how to log in.
+ *
+ * Every field is optional: what is left out is taken from the
+ * environment - `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`
+ * and the rest, the same variables `psql` reads - and what neither
+ * gives falls back to PostgreSQL's own defaults.
+ */
 export interface DatabaseConnectionParams {
     /**
      * A whole connection string, as an alternative to the fields below -
@@ -15,11 +23,20 @@ export interface DatabaseConnectionParams {
      * by one that was left in the object.
      */
     connectionString?: string;
+    /** Host name, IP, or the directory of a unix socket. */
     host?: string;
+    /** Port the server listens on. */
     port?: number;
+    /** Role to connect as. */
     user?: string;
+    /**
+     * The password, or a function asked for one when the server wants it -
+     * which is where a rotating credential or a secret store goes.
+     */
     password?: string | (() => string | Promise<string>);
+    /** Database to connect to. */
     database?: string;
+    /** What this connection calls itself, shown in `pg_stat_activity`. */
     applicationName?: string;
     /**
      * Opens the connection in replication mode, which is what lets it run
@@ -155,8 +172,14 @@ export interface DatabaseConnectionParams {
     timing?: boolean;
     debugLogger?: DebugLogger;
 }
+/**
+ * Which server in a list is acceptable, checked after connecting - the
+ * same values `libpq` takes, and how a client finds the primary.
+ */
 export type TargetSessionAttrs = 'read-write' | 'read-only' | 'primary' | 'standby' | 'prefer-standby';
+/** Options passed down to the socket itself. */
 export interface SocketOptions {
+    /** Whether TCP keep-alive is turned on. */
     keepAlive?: boolean;
 }
 /**
@@ -169,6 +192,10 @@ export interface SocketOptions {
  * about - see `fetchAsString` in QueryOptions.
  */
 export type ConnectionMappingDefaults = DataMappingOptions & Pick<QueryOptions, 'objectRows' | 'rowDecoder' | 'typeMap' | 'columnFormat'>;
+/**
+ * Everything a `Connection` can be given: where the server is, how to
+ * talk to it, and the defaults every statement on it inherits.
+ */
 export interface ConnectionConfiguration extends DatabaseConnectionParams, SocketOptions, ConnectionMappingDefaults {
     buffer?: SmartBufferConfig;
     /**
@@ -186,6 +213,10 @@ export interface ConnectionConfiguration extends DatabaseConnectionParams, Socke
      */
     pipeline?: boolean;
 }
+/**
+ * A connection's configuration, plus how many of them to keep and how
+ * long an idle one lives.
+ */
 export interface PoolConfiguration extends ConnectionConfiguration, LPoolConfiguration {
     /**
      * How many of Pool.query()'s one-shot queries may share a single pooled

package/interfaces/field-info.d.ts

@@ -1,3 +1,11 @@
+/**
+ * One column of a result, as the server described it and this client
+ * mapped it.
+ *
+ * The server's half - name, type OID, table and column - comes from the
+ * RowDescription; `jsType`, the element type of an array and the fixed
+ * size are what the type map made of it.
+ */
 export interface FieldInfo {
     /**
      * Name of the field

package/interfaces/function-call-options.d.ts

@@ -1,4 +1,5 @@
 import type { DataFormat } from '../constants.js';
+/** How a `Connection.callFunction()` sends its arguments and reads back its result. */
 export interface FunctionCallOptions {
     /**
      * Format of each argument, applied positionally - omit for text (the

package/interfaces/function-call-result.d.ts

@@ -1,3 +1,9 @@
+/**
+ * What a function call answered with, undecoded.
+ *
+ * The fast-call protocol says nothing about the return type, so the
+ * bytes are handed over as they arrived for the caller to read.
+ */
 export interface FunctionCallResult {
     /**
      * The function's return value, in the wire format requested via

package/interfaces/pipeline-request.d.ts

@@ -5,7 +5,9 @@ import type { Maybe, OID } from '../types.js';
  * tagged templates without any conversion.
  */
 export interface PipelineRequest {
+    /** The statement text. */
     sql: string;
+    /** Its parameters, for `$1`, `$2` and so on. */
     params?: any[];
     /**
      * Parameter type OIDs for this statement. Per statement rather than per

package/interfaces/query-options.d.ts

@@ -3,6 +3,13 @@ import type { DataFormat } from '../constants.js';
 import type { DataTypeMap } from '../data-type-map.js';
 import type { RowDecoder } from '../util/row-decoder.js';
 import type { DataMappingOptions } from './data-mapping-options.js';
+/**
+ * What `query()` and `execute()` take: the parameters, the shape of the
+ * rows, how much of the result to read, and how to stop.
+ *
+ * Everything a `DataMappingOptions` carries applies here too, and a value
+ * left out falls back to the connection's own setting.
+ */
 export interface QueryOptions extends DataMappingOptions {
     /**
      * Specifies weather execute query in auto-commit mode

package/interfaces/query-result.d.ts

@@ -1,5 +1,12 @@
 import type { Cursor } from '../connection/cursor.js';
 import type { CommandResult } from './command-result.js';
+/**
+ * What `query()` answered with - a `CommandResult`, plus the cursor when
+ * one was asked for.
+ *
+ * With `cursor: true` the rows are read through `cursor` instead of
+ * `rows`, which stays empty.
+ */
 export interface QueryResult extends CommandResult {
     /**
      * Cursor instance

package/interfaces/script-execute-options.d.ts

@@ -1,6 +1,10 @@
 import type { DataTypeMap } from '../data-type-map.js';
 import type { RowDecoder } from '../util/row-decoder.js';
 import type { DataMappingOptions } from './data-mapping-options.js';
+/**
+ * What `execute()` takes for a script of several statements - how much of
+ * each result to keep, and how to read the rows it does.
+ */
 export interface ScriptExecuteOptions extends DataMappingOptions {
     /**
      * Specifies weather execute query in auto-commit mode

package/interfaces/script-result.d.ts

@@ -1,4 +1,5 @@
 import type { CommandResult } from './command-result.js';
+/** What `execute()` answered with: one result per statement in the script. */
 export interface ScriptResult {
     /**
      * Array of command result for each sql command in the script

package/interfaces/statement-prepare-options.d.ts

@@ -1,5 +1,6 @@
 import type { DataTypeMap } from '../data-type-map.js';
 import type { OID } from '../types.js';
+/** What `prepare()` takes: the parameter types to declare, and which type map to read them with. */
 export interface StatementPrepareOptions {
     /**
      * Specifies data type for each parameter

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {
-    "@jsopen/objects": "^2.2.3",
+    "@jsopen/objects": "^2.3.4",
     "doublylinked": "^2.5.6",
-    "flexy-buffer": "^1.1.0",
-    "lightning-pool": "^4.12.0",
+    "flexy-buffer": "^1.1.1",
+    "lightning-pool": "^4.14.0",
     "power-tasks": "^1.14.2",
     "putil-promisify": "^1.10.1",
     "putil-varhelpers": "^1.7.0",
@@ -65,4 +65,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/protocol/backend.d.ts

@@ -1,5 +1,11 @@
 import { Protocol } from './protocol.js';
 declare type ParseCallback = (code: Protocol.BackendMessageCode, data?: any) => void;
+/**
+ * Reads the server's messages out of the bytes as they arrive.
+ *
+ * Keeps whatever a chunk left half-finished, so a message split across
+ * reads - or several in one read - comes out whole exactly once.
+ */
 export declare class Backend {
     private readonly _headerBuf;
     private _headerFilled;

package/protocol/backend.js

@@ -22,6 +22,12 @@ const ErrorFieldTypes = {
     L: 'line',
     R: 'routine',
 };
+/**
+ * Reads the server's messages out of the bytes as they arrive.
+ *
+ * Keeps whatever a chunk left half-finished, so a message split across
+ * reads - or several in one read - comes out whole exactly once.
+ */
 export class Backend {
     _headerBuf = Buffer.allocUnsafe(HEADER_LENGTH);
     _headerFilled = 0;
@@ -47,10 +53,17 @@ export class Backend {
                 const bodyStart = pos + HEADER_LENGTH;
                 const bodyEnd = bodyStart + (len - 4);
                 if (bodyEnd <= dataLen) {
-                    const io = new BufferReader(data.subarray(bodyStart, bodyEnd));
-                    const parser = MessageParsers[code];
-                    const v = parser && parser(io, code, len);
-                    callback(code, v);
+                    if (code === Protocol.BackendMessageCode.DataRow) {
+                        // Straight out of the read buffer: no view of the body, no
+                        // reader over it, and no view of the row's own bytes either.
+                        callback(code, dataRowMessage(data, bodyStart, bodyEnd));
+                    }
+                    else {
+                        const io = new BufferReader(data.subarray(bodyStart, bodyEnd));
+                        const parser = MessageParsers[code];
+                        const v = parser && parser(io, code, len);
+                        callback(code, v);
+                    }
                     pos = bodyEnd;
                     continue;
                 }
@@ -206,10 +219,27 @@ function parseCopyResponse(io) {
     }
     return out;
 }
+/**
+ * One row, pointing into the read buffer rather than copying out of it.
+ *
+ * A consumer that needs a `Buffer` of its own - a caller's RowDecoder,
+ * or a path that sets the row aside and reads it later - builds the view
+ * with `dataRowBytes()`. The decoders that read the row in place never
+ * do, which is the point.
+ */
+function dataRowMessage(buffer, bodyStart, bodyEnd) {
+    const offset = bodyStart + 2;
+    return {
+        columnCount: buffer.readUInt16BE(bodyStart),
+        buffer,
+        offset,
+        len: bodyEnd - offset,
+    };
+}
 function parseDataRow(io, code, len) {
     const columnCount = io.readUInt16BE();
     const data = io.readBytes(len - 6);
-    return { columnCount, data };
+    return { columnCount, buffer: data, offset: 0, len: data.length };
 }
 function parseErrorResponse(io) {
     const out = {};

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) {