postgrejs 3.11.1 → 3.12.1

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,21 +5,101 @@ 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;
     private readonly _name;
     private readonly _paramTypes?;
+    private _resolvedParamTypes?;
     private _fields?;
     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
+     * answered - not what was asked for in `paramTypes`.
+     *
+     * A parameter the caller declared nothing for is resolved by the
+     * server from where it appears: the column it is inserted into, the
+     * operator it sits beside, the function it is passed to. It never
+     * looks at the value, which is still three messages away, so this is
+     * a property of the statement and does not change between executions.
+     *
+     * Useful for two things. It says what a parameter with no context
+     * became - `select $1` resolves to `text`, which is why an array
+     * there comes back as an array literal rather than an array. And it
+     * is the type to name with `new BindParam(oid, v)` for a caller who
+     * wants the binary encoding a large numeric array gives up by going
+     * 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
@@ -78,6 +158,28 @@ export declare class PreparedStatement extends SafeEventEmitter implements Async
      * holding a `Connection` never saw. Hard to provoke - `DEALLOCATE`
      * does not normally raise one - which is why there is no test for it.
      */
+    /**
+     * Takes the value out of a `BindParam`, and refuses one that names a
+     * type this statement is not.
+     *
+     * A prepared statement's parameter types are fixed by its Parse, so a
+     * `BindParam` here cannot change one: the Bind's format code says
+     * binary or text, and the server decodes with the type it already
+     * resolved. Naming a different one and being believed would read the
+     * bytes as something else - which is why the mismatch is an error
+     * rather than something to quietly honour.
+     *
+     * It used to be neither: nothing unwrapped the object, so it reached
+     * the encoder as a value with no type of its own and went out as
+     * `'' + v`. A text column took `"[object Object]"` and said nothing.
+     *
+     * What it is compared against is what the caller declared at
+     * `prepare()`, or failing that what the server resolved - which is the
+     * same type either way, and is why an agreeing `BindParam` is simply
+     * unwrapped. Where there is nothing to compare against, the value is
+     * taken as given.
+     */
+    protected _unwrapBindParams(params: Maybe<any[]>): Maybe<any[]>;
     protected _emitNotice(msg: any): void;
     protected _executeBatchWithTransaction(paramSets: any[][], options: QueryOptions): Promise<BatchResult>;
     protected _executeWithTransaction(options?: QueryOptions): Promise<QueryResult>;
@@ -95,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