postgrejs 3.12.0 → 3.12.2

package/connection/pool.d.ts

@@ -18,7 +18,9 @@ import type { PreparedStatement } from './prepared-statement.js';
  * did.
  */
 export type PoolPipelineOptions = Pick<QueryOptions, 'pipeline'>;
+/** What `Pool.query()` takes - a connection's own options, since it runs on one. */
 export type PoolQueryOptions = QueryOptions;
+/** What `Pool.execute()` takes, for the same reason. */
 export type PoolScriptExecuteOptions = ScriptExecuteOptions;
 /**
  * One pooled connection the pipelined path is currently borrowing.
@@ -33,10 +35,37 @@ export type PoolScriptExecuteOptions = ScriptExecuteOptions;
  * reports zero running queries.
  */
 interface PipelineSlot {
+    /** The connection once it is open. */
     connection?: Connection;
+    /** What everything waiting for this slot awaits. */
     promise: Promise<Connection>;
+    /** Queries handed to this slot that have not settled yet. */
     load: number;
 }
+/**
+ * A set of connections, handed out and taken back.
+ *
+ * Takes the same configuration a `Connection` does, plus how many to
+ * keep (`min`, `max`) and how long an idle one lives. Nothing connects
+ * until something is asked for.
+ *
+ * Most callers never hold a connection at all: `query()`, `execute()`
+ * and `transaction()` take one, use it and give it back, so the pool is
+ * a drop-in for a connection.
+ *
+ * ```ts
+ * const pool = new Pool({ host: 'localhost', database: 'mydb', max: 10 });
+ * const result = await pool.query('select * from customers');
+ * await pool.close();
+ * ```
+ *
+ * `acquire()` is for the cases that need one connection for several
+ * statements - a session setting, an advisory lock - and its connection
+ * must be released.
+ *
+ * Emits `connect`, `acquire`, `release`, `remove`, `close`, `error` and
+ * `terminate`.
+ */
 export declare class Pool extends SafeEventEmitter {
     protected readonly _pool: LightningPool<IntlConnection>;
     protected readonly _notificationListeners: SafeEventEmitter;
@@ -52,7 +81,13 @@ export declare class Pool extends SafeEventEmitter {
     protected readonly _destroyReasons: WeakMap<IntlConnection, Error>;
     protected _pipelineMaxQueries: number;
     protected _pipelineMaxConnections: number;
+    /** What this pool was built with, frozen. */
     readonly config: PoolConfiguration;
+    /**
+     * @param config How to reach the server and how many connections to
+     * keep - an object, a connection string, or nothing to take it all
+     * from the environment.
+     */
     constructor(config?: PoolConfiguration | string);
     /**
      * Returns the number of connections that are currently acquired
@@ -66,6 +101,13 @@ export declare class Pool extends SafeEventEmitter {
      * Returns total number of connections in the pool regardless of whether they are idle or in use
      */
     get totalConnections(): number;
+    /**
+     * Opens the `min` connections now instead of waiting for the first
+     * caller to need one.
+     *
+     * Never required: a pool that is only used starts itself. Worth it
+     * where the first query should not pay for the handshake.
+     */
     start(): void;
     /**
      * Obtains a connection from the connection pool
@@ -99,10 +141,48 @@ export declare class Pool extends SafeEventEmitter {
      * one. This is the way to get several statements onto the same one.
      */
     transaction<T>(fn: (connection: Connection) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Prepares a statement on a connection of the pool's, which that
+     * statement keeps until it is closed.
+     *
+     * The connection is released by `close()` on the statement, so one
+     * that is never closed holds a connection out of the pool for good.
+     *
+     * @param sql The statement to prepare.
+     * @param options Declared parameter types.
+     * @returns The prepared statement, ready to execute.
+     */
     prepare(sql: string, options?: StatementPrepareOptions): Promise<PreparedStatement>;
+    /**
+     * Gives a connection taken with `acquire()` back to the pool.
+     *
+     * @param connection The connection to release.
+     */
     release(connection: Connection): Promise<void>;
+    /**
+     * Subscribes to a `NOTIFY` channel on a connection the pool keeps for
+     * notifications.
+     *
+     * A pooled connection cannot carry a subscription - it goes back to
+     * the pool and the next caller would receive them - so the first
+     * `listen()` opens one connection outside the pool and every channel
+     * shares it. `unListenAll()` closes it again.
+     *
+     * @param channel The channel to subscribe to.
+     * @param callback Called with each notification on it.
+     */
     listen(channel: string, callback: NotificationCallback): Promise<void>;
+    /**
+     * Drops every callback on one channel, and closes the notification
+     * connection when it was the last one.
+     *
+     * @param channel The channel to unsubscribe from.
+     */
     unListen(channel: string): Promise<void>;
+    /**
+     * Drops every callback on every channel and closes the connection the
+     * pool was keeping for them.
+     */
     unListenAll(): Promise<void>;
     /**
      * A pooled connection reported that its socket closed. `reason` is set

package/connection/pool.js

@@ -8,6 +8,30 @@ import { QueryRequest } from '../util/sql-tag.js';
 import { startsCopy, startsTransaction } from '../util/starts-transaction.js';
 import { Connection } from './connection.js';
 import { getIntlConnection, IntlConnection } from './intl-connection.js';
+/**
+ * A set of connections, handed out and taken back.
+ *
+ * Takes the same configuration a `Connection` does, plus how many to
+ * keep (`min`, `max`) and how long an idle one lives. Nothing connects
+ * until something is asked for.
+ *
+ * Most callers never hold a connection at all: `query()`, `execute()`
+ * and `transaction()` take one, use it and give it back, so the pool is
+ * a drop-in for a connection.
+ *
+ * ```ts
+ * const pool = new Pool({ host: 'localhost', database: 'mydb', max: 10 });
+ * const result = await pool.query('select * from customers');
+ * await pool.close();
+ * ```
+ *
+ * `acquire()` is for the cases that need one connection for several
+ * statements - a session setting, an advisory lock - and its connection
+ * must be released.
+ *
+ * Emits `connect`, `acquire`, `release`, `remove`, `close`, `error` and
+ * `terminate`.
+ */
 export class Pool extends SafeEventEmitter {
     _pool;
     _notificationListeners = new SafeEventEmitter();
@@ -23,7 +47,13 @@ export class Pool extends SafeEventEmitter {
     _destroyReasons = new WeakMap();
     _pipelineMaxQueries;
     _pipelineMaxConnections;
+    /** What this pool was built with, frozen. */
     config;
+    /**
+     * @param config How to reach the server and how many connections to
+     * keep - an object, a connection string, or nothing to take it all
+     * from the environment.
+     */
     constructor(config) {
         super();
         const cfg = getConnectionConfig(config);
@@ -132,6 +162,13 @@ export class Pool extends SafeEventEmitter {
     get totalConnections() {
         return this._pool.size;
     }
+    /**
+     * Opens the `min` connections now instead of waiting for the first
+     * caller to need one.
+     *
+     * Never required: a pool that is only used starts itself. Worth it
+     * where the first query should not pay for the handshake.
+     */
     start() {
         return this._pool.start();
     }
@@ -281,26 +318,52 @@ export class Pool extends SafeEventEmitter {
             await this.release(connection);
         }
     }
+    /**
+     * Prepares a statement on a connection of the pool's, which that
+     * statement keeps until it is closed.
+     *
+     * The connection is released by `close()` on the statement, so one
+     * that is never closed holds a connection out of the pool for good.
+     *
+     * @param sql The statement to prepare.
+     * @param options Declared parameter types.
+     * @returns The prepared statement, ready to execute.
+     */
     async prepare(sql, options) {
         const connection = await this.acquire();
         const statement = await connection.prepare(sql, options);
         statement.once('close', () => this._pool.release(getIntlConnection(connection)));
         return statement;
     }
+    /**
+     * Gives a connection taken with `acquire()` back to the pool.
+     *
+     * @param connection The connection to release.
+     */
     release(connection) {
         return this._pool.releaseAsync(getIntlConnection(connection));
     }
+    /**
+     * Subscribes to a `NOTIFY` channel on a connection the pool keeps for
+     * notifications.
+     *
+     * A pooled connection cannot carry a subscription - it goes back to
+     * the pool and the next caller would receive them - so the first
+     * `listen()` opens one connection outside the pool and every channel
+     * shares it. `unListenAll()` closes it again.
+     *
+     * @param channel The channel to subscribe to.
+     * @param callback Called with each notification on it.
+     */
+    /* The channel name is normalized here as well as in
+       Connection.listen(), because this emitter's keys have to be the same
+       strings the inner connection registers or unListen() would miss
+       them. And the test below is per channel: it used to be enough that
+       the shared connection existed, so a second channel added after the
+       first was recorded here but never reached the server - the same root
+       cause as the one fixed one layer up. */
     async listen(channel, callback) {
-        // Folded here as well as in Connection.listen(): this emitter's keys
-        // have to be the same strings the inner connection registers, or
-        // unListen() would miss them.
         channel = normalizeChannelName(channel);
-        // Bug: _initNotificationConnection() only ever bootstraps the shared
-        // connection and registers every channel known at that moment - it
-        // returns immediately once that connection already exists, so a second,
-        // different channel added afterwards was recorded here but never
-        // reached the server at all (same root cause fixed in
-        // Connection.listen(), one layer up).
         const alreadyListening = !!this._notificationListeners.listenerCount(channel);
         this._notificationListeners.on(channel, callback);
         if (!this._notificationConnection) {
@@ -310,6 +373,12 @@ export class Pool extends SafeEventEmitter {
             await this._notificationConnection.listen(channel, callback);
         }
     }
+    /**
+     * Drops every callback on one channel, and closes the notification
+     * connection when it was the last one.
+     *
+     * @param channel The channel to unsubscribe from.
+     */
     async unListen(channel) {
         channel = normalizeChannelName(channel);
         this._notificationListeners.removeAllListeners(channel);
@@ -319,6 +388,10 @@ export class Pool extends SafeEventEmitter {
         else if (this._notificationConnection)
             await this._notificationConnection.unListen(channel);
     }
+    /**
+     * Drops every callback on every channel and closes the connection the
+     * pool was keeping for them.
+     */
     async unListenAll() {
         this._notificationListeners.removeAllListeners();
         if (this._notificationConnection) {

package/connection/portal.d.ts

@@ -3,17 +3,40 @@ import { Protocol } from '../protocol/protocol.js';
 import type { Maybe } from '../types.js';
 import type { Connection } from './connection.js';
 import type { PreparedStatement } from './prepared-statement.js';
+/** What one Execute of a portal answered with. */
 export interface PortalExecuteResult {
+    /**
+     * The message that ended it: CommandComplete when the rows ran out,
+     * PortalSuspended when the fetch limit stopped it first.
+     */
     code: Protocol.BackendMessageCode;
+    /** The rows, still raw - the caller decodes them. */
     rows?: Protocol.DataRowMessage[];
+    /** The command tag, when the portal ran to completion. */
     command?: string;
+    /** What the tag reported, for the commands that report one. */
     rowCount?: number;
 }
+/**
+ * One execution of a prepared statement, named on the server so it can
+ * be executed a batch at a time.
+ *
+ * What a `Cursor` is built on: a portal holds the bound parameters and
+ * the position in the result, so `execute()` can be called again for the
+ * next batch. It lives inside the transaction that created it - implicit
+ * or otherwise - and is gone when that ends.
+ */
 export declare class Portal {
     private readonly _statement;
     private readonly _name?;
+    /**
+     * @param statement The statement this portal binds.
+     * @param name What the server will know the portal by.
+     */
     constructor(statement: PreparedStatement, name: string);
+    /** The connection the portal lives on. */
     get connection(): Connection;
+    /** What the server knows this portal by. */
     get name(): Maybe<string>;
     /**
      * Bind + Describe(portal) collapsed into one round trip instead of two
@@ -24,6 +47,20 @@ export declare class Portal {
      * same named portal failed with "portal ... does not exist").
      */
     bindAndRetrieveFields(params: Maybe<any[]>, queryOptions: QueryOptions, columnFormat?: Protocol.DataFormat | Protocol.DataFormat[]): Promise<Protocol.RowDescription[]>;
+    /**
+     * Runs the portal, for up to `fetchCount` rows.
+     *
+     * Called again for each batch: the result's `code` says which happened
+     * - PortalSuspended when the limit stopped it and there is more,
+     * CommandComplete when the rows ran out.
+     *
+     * @param fetchCount How many rows to ask for; every remaining row when
+     * it is absent or zero.
+     * @returns The raw rows and how the execution ended.
+     * @throws DatabaseError When the server refuses it - `34000` when the
+     * portal is gone, which is what another statement on the connection
+     * does to it.
+     */
     execute(fetchCount?: number): Promise<PortalExecuteResult>;
     /**
      * Close + Sync as one request (see PgSocket.sendCloseAndSyncMessages()

package/connection/portal.js

@@ -1,16 +1,31 @@
 import { GlobalTypeMap } from '../data-type-map.js';
 import { Protocol } from '../protocol/protocol.js';
 import { getIntlConnection } from './intl-connection.js';
+/**
+ * One execution of a prepared statement, named on the server so it can
+ * be executed a batch at a time.
+ *
+ * What a `Cursor` is built on: a portal holds the bound parameters and
+ * the position in the result, so `execute()` can be called again for the
+ * next batch. It lives inside the transaction that created it - implicit
+ * or otherwise - and is gone when that ends.
+ */
 export class Portal {
     _statement;
     _name;
+    /**
+     * @param statement The statement this portal binds.
+     * @param name What the server will know the portal by.
+     */
     constructor(statement, name) {
         this._statement = statement;
         this._name = name;
     }
+    /** The connection the portal lives on. */
     get connection() {
         return this._statement.connection;
     }
+    /** What the server knows this portal by. */
     get name() {
         return this._name;
     }
@@ -61,6 +76,20 @@ export class Portal {
             intoCon.unref();
         }
     }
+    /**
+     * Runs the portal, for up to `fetchCount` rows.
+     *
+     * Called again for each batch: the result's `code` says which happened
+     * - PortalSuspended when the limit stopped it and there is more,
+     * CommandComplete when the rows ran out.
+     *
+     * @param fetchCount How many rows to ask for; every remaining row when
+     * it is absent or zero.
+     * @returns The raw rows and how the execution ended.
+     * @throws DatabaseError When the server refuses it - `34000` when the
+     * portal is gone, which is what another statement on the connection
+     * does to it.
+     */
     async execute(fetchCount) {
         const intoCon = getIntlConnection(this.connection);
         intoCon.ref();

package/connection/prepared-statement.d.ts

@@ -5,6 +5,31 @@ import type { StatementPrepareOptions } from '../interfaces/statement-prepare-op
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import type { Maybe, OID } from '../types.js';
 import type { Connection } from './connection.js';
+/**
+ * A statement parsed once by the server and executed as many times as
+ * the caller likes.
+ *
+ * Obtained from `Connection.prepare()` or `Pool.prepare()`. Each
+ * `execute()` then costs a Bind and an Execute instead of a full Parse,
+ * and the server plans it once - which is what makes it worth naming a
+ * statement that runs in a loop. `executeBatch()` goes further and sends
+ * every parameter set before waiting for any of them.
+ *
+ * ```ts
+ * const statement = await connection.prepare(
+ *   'update customers set city = $1 where id = $2',
+ * );
+ * await statement.execute({ params: ['Berlin', 1] });
+ * await statement.execute({ params: ['Paris', 2] });
+ * await statement.close();
+ * ```
+ *
+ * A statement holds a server-side name until `close()`, and one taken
+ * from a `Pool` holds that pool's connection with it, so it must be
+ * closed - `await using` does it at the end of the scope.
+ *
+ * Emits `close` and `notice`.
+ */
 export declare class PreparedStatement extends SafeEventEmitter implements AsyncDisposable {
     private readonly _connection;
     private readonly _sql;
@@ -15,11 +40,37 @@ export declare class PreparedStatement extends SafeEventEmitter implements Async
     protected _onErrorSavePoint: string;
     private _refCount;
     private _closed;
+    /**
+     * Builds the handle; `prepare()` is what sends anything.
+     *
+     * @param connection The connection this statement lives on.
+     * @param sql The statement text.
+     * @param paramTypes Declared parameter types, if the caller named any.
+     */
     constructor(connection: Connection, sql: string, paramTypes?: OID[]);
+    /**
+     * Parses the statement on the server and describes it, in one round
+     * trip, so the first `execute()` already knows what its columns are.
+     *
+     * `Connection.prepare()` is the way to call this.
+     *
+     * @param connection The connection to prepare on.
+     * @param sql The statement text.
+     * @param options Declared parameter types.
+     * @returns The prepared statement.
+     * @throws DatabaseError When the server refuses to parse it.
+     */
     static prepare(connection: Connection, sql: string, options?: StatementPrepareOptions): Promise<PreparedStatement>;
+    /** The connection this statement was prepared on. */
     get connection(): Connection;
+    /** The name the server knows this statement by. */
     get name(): Maybe<string>;
+    /** The statement text, as it was prepared. */
     get sql(): string;
+    /**
+     * The parameter types the caller declared at `prepare()`, if any -
+     * `resolvedParamTypes` is what the server made of them.
+     */
     get paramTypes(): Maybe<Maybe<OID>[]>;
     /**
      * What the server made of each parameter, in order, as its Describe
@@ -39,6 +90,16 @@ export declare class PreparedStatement extends SafeEventEmitter implements Async
      * out untyped (see `isUnspecifiedParam`).
      */
     get resolvedParamTypes(): Maybe<OID[]>;
+    /**
+     * Runs the statement once, with one set of parameters.
+     *
+     * Takes the same options `Connection.query()` does, minus the SQL -
+     * parameters, row shape, type mapping, `cursor`, a signal.
+     *
+     * @param options Parameters and how to read the result.
+     * @returns The rows, the command tag, and what the columns were.
+     * @throws DatabaseError When the server refuses the execution.
+     */
     execute(options?: QueryOptions): Promise<QueryResult>;
     /**
      * Runs this statement once per parameter set, sending every Bind/Execute
@@ -136,6 +197,13 @@ export declare class PreparedStatement extends SafeEventEmitter implements Async
      * set back independently anyway.
      */
     protected _withTransaction<T>(options: QueryOptions | undefined, fn: (inlineSavepoint?: string) => Promise<T>, canInlineSavepoint?: boolean): Promise<T>;
+    /**
+     * Closes the statement on the server and releases what it was holding
+     * - the connection too, when it came from a pool.
+     *
+     * Idempotent, and deferred while a cursor of this statement is still
+     * open. Emits `close`.
+     */
     close(): Promise<void>;
     /**
      * Asks the server to cancel whatever this statement's connection is

package/connection/prepared-statement.js

@@ -14,6 +14,31 @@ import { getIntlConnection } from './intl-connection.js';
 import { Portal } from './portal.js';
 let statementCounter = 0;
 let portalCounter = 0;
+/**
+ * A statement parsed once by the server and executed as many times as
+ * the caller likes.
+ *
+ * Obtained from `Connection.prepare()` or `Pool.prepare()`. Each
+ * `execute()` then costs a Bind and an Execute instead of a full Parse,
+ * and the server plans it once - which is what makes it worth naming a
+ * statement that runs in a loop. `executeBatch()` goes further and sends
+ * every parameter set before waiting for any of them.
+ *
+ * ```ts
+ * const statement = await connection.prepare(
+ *   'update customers set city = $1 where id = $2',
+ * );
+ * await statement.execute({ params: ['Berlin', 1] });
+ * await statement.execute({ params: ['Paris', 2] });
+ * await statement.close();
+ * ```
+ *
+ * A statement holds a server-side name until `close()`, and one taken
+ * from a `Pool` holds that pool's connection with it, so it must be
+ * closed - `await using` does it at the end of the scope.
+ *
+ * Emits `close` and `notice`.
+ */
 export class PreparedStatement extends SafeEventEmitter {
     _connection;
     _sql = '';
@@ -24,6 +49,13 @@ export class PreparedStatement extends SafeEventEmitter {
     _onErrorSavePoint;
     _refCount = 0;
     _closed = false;
+    /**
+     * Builds the handle; `prepare()` is what sends anything.
+     *
+     * @param connection The connection this statement lives on.
+     * @param sql The statement text.
+     * @param paramTypes Declared parameter types, if the caller named any.
+     */
     constructor(connection, sql, paramTypes) {
         super();
         this._connection = connection;
@@ -32,6 +64,18 @@ export class PreparedStatement extends SafeEventEmitter {
         this._paramTypes = paramTypes;
         this._onErrorSavePoint = 'SP_' + Math.round(Math.random() * 100000000);
     }
+    /**
+     * Parses the statement on the server and describes it, in one round
+     * trip, so the first `execute()` already knows what its columns are.
+     *
+     * `Connection.prepare()` is the way to call this.
+     *
+     * @param connection The connection to prepare on.
+     * @param sql The statement text.
+     * @param options Declared parameter types.
+     * @returns The prepared statement.
+     * @throws DatabaseError When the server refuses to parse it.
+     */
     static async prepare(connection, sql, options) {
         const intoCon = getIntlConnection(connection);
         intoCon.assertConnected();
@@ -42,15 +86,22 @@ export class PreparedStatement extends SafeEventEmitter {
         statement._refCount = 1;
         return statement;
     }
+    /** The connection this statement was prepared on. */
     get connection() {
         return this._connection;
     }
+    /** The name the server knows this statement by. */
     get name() {
         return this._name;
     }
+    /** The statement text, as it was prepared. */
     get sql() {
         return this._sql;
     }
+    /**
+     * The parameter types the caller declared at `prepare()`, if any -
+     * `resolvedParamTypes` is what the server made of them.
+     */
     get paramTypes() {
         return this._paramTypes;
     }
@@ -74,10 +125,21 @@ export class PreparedStatement extends SafeEventEmitter {
     get resolvedParamTypes() {
         return this._resolvedParamTypes;
     }
+    /**
+     * Runs the statement once, with one set of parameters.
+     *
+     * Takes the same options `Connection.query()` does, minus the SQL -
+     * parameters, row shape, type mapping, `cursor`, a signal.
+     *
+     * @param options Parameters and how to read the result.
+     * @returns The rows, the command tag, and what the columns were.
+     * @throws DatabaseError When the server refuses the execution.
+     */
+    /* The options are merged with the connection's defaults here rather
+       than deeper down, because a cursor keeps them and decodes its own
+       rows with them long after this call is over. */
     async execute(options = {}) {
         const intlCon = getIntlConnection(this.connection);
-        // Folded in here rather than deeper: a cursor keeps these options
-        // and decodes its own rows with them long after this call is over.
         options = intlCon.withDefaults(options);
         if (options.signal)
             return withAbortSignal(options.signal, () => intlCon.cancel(), () => this._executeWithTransaction(options));
@@ -287,6 +349,13 @@ export class PreparedStatement extends SafeEventEmitter {
             throw e;
         }
     }
+    /**
+     * Closes the statement on the server and releases what it was holding
+     * - the connection too, when it came from a pool.
+     *
+     * Idempotent, and deferred while a cursor of this statement is still
+     * open. Emits `close`.
+     */
     async close() {
         if (this._closed)
             return;

package/constants.d.ts

@@ -1,7 +1,16 @@
 import { Protocol } from './protocol/protocol.js';
 import DataFormat = Protocol.DataFormat;
+export declare const version = "3.12.2";
 export { DataFormat };
+/**
+ * What columns come back in unless something asks otherwise.
+ *
+ * Binary: fewer bytes on the wire and no text to parse for most types.
+ * A column named by `fetchAsString`, and the types that have no binary
+ * decoder, come back as text regardless.
+ */
 export declare const DEFAULT_COLUMN_FORMAT = DataFormat.binary;
+/** Where a connection is between `connect()` and `close()`. */
 export declare enum ConnectionState {
     CLOSED = 0,
     CONNECTING = 1,
@@ -9,6 +18,14 @@ export declare enum ConnectionState {
     READY = 2,
     CLOSING = 10
 }
+/**
+ * Every type this client knows, by name, as `pg_type.oid` gives it - the
+ * scalar types and their array counterparts, which are named with a
+ * leading underscore the way the catalog names them.
+ *
+ * These are the numbers `BindParam`, `fetchAsString` and a
+ * `DataTypeMap`'s own registrations are written with.
+ */
 export declare const DataTypeOIDs: {
     bool: number;
     bytea: number;
@@ -185,4 +202,5 @@ export declare const DataTypeOIDs: {
     _datemultirange: number;
     _int8multirange: number;
 };
+/** The name of each type by its OID, for reporting a column's type back to a caller. */
 export declare const DataTypeNames: Record<string, string>;

package/constants.js

@@ -2,8 +2,17 @@ import { Protocol } from './protocol/protocol.js';
 var DataFormat = Protocol.DataFormat;
 // @ts-ignore
 Symbol.asyncDispose ??= Symbol('Symbol.asyncDispose');
+export const version = '3.12.2';
 export { DataFormat };
+/**
+ * What columns come back in unless something asks otherwise.
+ *
+ * Binary: fewer bytes on the wire and no text to parse for most types.
+ * A column named by `fetchAsString`, and the types that have no binary
+ * decoder, come back as text regardless.
+ */
 export const DEFAULT_COLUMN_FORMAT = DataFormat.binary;
+/** Where a connection is between `connect()` and `close()`. */
 export var ConnectionState;
 (function (ConnectionState) {
     ConnectionState[ConnectionState["CLOSED"] = 0] = "CLOSED";
@@ -12,6 +21,14 @@ export var ConnectionState;
     ConnectionState[ConnectionState["READY"] = 2] = "READY";
     ConnectionState[ConnectionState["CLOSING"] = 10] = "CLOSING";
 })(ConnectionState || (ConnectionState = {}));
+/**
+ * Every type this client knows, by name, as `pg_type.oid` gives it - the
+ * scalar types and their array counterparts, which are named with a
+ * leading underscore the way the catalog names them.
+ *
+ * These are the numbers `BindParam`, `fetchAsString` and a
+ * `DataTypeMap`'s own registrations are written with.
+ */
 export const DataTypeOIDs = {
     bool: 16,
     bytea: 17,
@@ -188,6 +205,7 @@ export const DataTypeOIDs = {
     _datemultirange: 6155,
     _int8multirange: 6157,
 };
+/** The name of each type by its OID, for reporting a column's type back to a caller. */
 export const DataTypeNames = {
     [DataTypeOIDs.bool]: 'bool',
     [DataTypeOIDs.bytea]: 'bytea',