postgrejs 3.12.0 → 3.12.2

package/README.md

@@ -62,7 +62,7 @@ PostgreJS is a driver, not a framework, so what you build on top of it stays you
       <a href="https://www.sqbjs.org"><img src="https://www.postgrejs.com/img/sqb-logo.svg" alt="SQB" height="60"></a><br><br>
       <b><a href="https://www.sqbjs.org">SQB</a></b><br>
       <a href="https://www.npmjs.com/package/@sqb/postgres"><code>@sqb/postgres</code></a><br>
-      <sub>native driver</sub>
+      <sub>first-party adapter</sub>
     </td>
     <td align="center" width="230" valign="top">
       <a href="https://kysely.dev"><img src="https://www.postgrejs.com/img/kysely-logo.svg" alt="Kysely" height="60"></a><br><br>

package/connection/bind-param.d.ts

@@ -1,6 +1,27 @@
 import type { OID } from '../types.js';
+/**
+ * A parameter with its type named, for the cases where the value cannot
+ * say what it is.
+ *
+ * An ordinary parameter is sent untyped and the server resolves it from
+ * where it lands, which is what makes a string work as a `json`, a
+ * `uuid` or an enum without being told. This is for when that is not
+ * enough: a value with no context to be resolved from (`$1 is null`),
+ * or a large numeric array, which keeps the binary encoding only when
+ * its type is declared.
+ *
+ * ```ts
+ * await connection.query('insert into t (v) values ($1)', {
+ *   params: [new BindParam(DataTypeOIDs._float8, bigArray)],
+ * });
+ * ```
+ */
 export declare class BindParam {
     oid: OID;
     value: any;
+    /**
+     * @param oid The type to declare for this parameter.
+     * @param value The value itself.
+     */
     constructor(oid: OID, value: any);
 }

package/connection/bind-param.js

@@ -1,6 +1,27 @@
+/**
+ * A parameter with its type named, for the cases where the value cannot
+ * say what it is.
+ *
+ * An ordinary parameter is sent untyped and the server resolves it from
+ * where it lands, which is what makes a string work as a `json`, a
+ * `uuid` or an enum without being told. This is for when that is not
+ * enough: a value with no context to be resolved from (`$1 is null`),
+ * or a large numeric array, which keeps the binary encoding only when
+ * its type is declared.
+ *
+ * ```ts
+ * await connection.query('insert into t (v) values ($1)', {
+ *   params: [new BindParam(DataTypeOIDs._float8, bigArray)],
+ * });
+ * ```
+ */
 export class BindParam {
     oid;
     value;
+    /**
+     * @param oid The type to declare for this parameter.
+     * @param value The value itself.
+     */
     constructor(oid, value) {
         this.oid = oid;
         this.value = value;

package/connection/connection.d.ts

@@ -21,14 +21,48 @@ import { IntlConnection } from './intl-connection.js';
 import { LargeObject } from './large-object.js';
 import type { Pool } from './pool.js';
 import { PreparedStatement } from './prepared-statement.js';
+/** One `NOTIFY` as the server delivered it: its channel, payload and sender. */
 export type NotificationMessage = Protocol.NotificationResponseMessage;
+/** What `listen()` calls with each notification on its channel. */
 export type NotificationCallback = (msg: NotificationMessage) => any;
+/**
+ * One session on one server.
+ *
+ * Built either from a configuration object, a connection string, or
+ * nothing at all - in which case the environment answers for it, the
+ * same variables `psql` reads (`PGHOST`, `PGDATABASE`, `PGUSER`, and the
+ * rest). `connect()` opens it and `close()` ends it; a connection taken
+ * from a `Pool` returns there instead.
+ *
+ * ```ts
+ * const connection = new Connection('postgres://localhost/mydb');
+ * await connection.connect();
+ * const result = await connection.query('select * from customers where id = $1', {
+ *   params: [42],
+ * });
+ * await connection.close();
+ * ```
+ *
+ * `await using` closes it at the end of the scope, and every query
+ * method accepts an `AbortSignal`.
+ *
+ * Emits `connecting`, `ready`, `close`, `terminate`, `error`, `notice`
+ * and `debug`.
+ */
 export declare class Connection extends SafeEventEmitter implements AsyncDisposable {
     protected _pool?: Pool;
     protected _intlCon: IntlConnection;
     protected _notificationListeners?: SafeEventEmitter;
     protected _closing: boolean;
+    /**
+     * @param pool The pool this connection belongs to.
+     * @param intlCon The internals it is a handle on.
+     */
     constructor(pool: Pool, intlCon: IntlConnection);
+    /**
+     * @param config How to reach the server - an object, a connection
+     * string, or nothing to take it all from the environment.
+     */
     constructor(config?: ConnectionConfiguration | string);
     /**
      * Returns configuration object
@@ -64,6 +98,12 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * Returns the secret key of the current session
      */
     get secretKey(): Maybe<Buffer>;
+    /**
+     * How many queries this connection is running right now.
+     *
+     * More than one only when they were pipelined; a connection answers
+     * them in order either way.
+     */
     get runningQueryCount(): number;
     /**
      * Connects to the server
@@ -101,6 +141,30 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
     callFunction(functionId: OID, args: Maybe<Buffer>[], options?: FunctionCallOptions & {
         signal?: AbortSignal;
     }): Promise<FunctionCallResult>;
+    /**
+     * Runs one statement and returns its result.
+     *
+     * Parameters are sent separately from the SQL - `$1`, `$2` and so on -
+     * so nothing has to be escaped into the text. A statement seen a few
+     * times is prepared and reused on this connection without being asked
+     * for, and `cursor: true` returns a `Cursor` instead of the rows.
+     *
+     * ```ts
+     * const result = await connection.query(
+     *   'select id, name from customers where city = $1',
+     *   { params: ['Berlin'], objectRows: true },
+     * );
+     * result.rows; // [{ id: 1, name: '...' }, ...]
+     * ```
+     *
+     * A statement built with the `sql` tag carries its own parameters and
+     * is passed on its own.
+     *
+     * @param sql The statement, or one built with the `sql` tag.
+     * @param options Parameters, row shape, type mapping, cursor, signal.
+     * @returns The rows, the command tag, and what the columns were.
+     * @throws DatabaseError When the server refuses the statement.
+     */
     query(sql: string | QueryRequest, options?: QueryOptions): Promise<QueryResult>;
     /**
      * Runs a `COPY ... TO STDOUT` and returns its output as a stream of the
@@ -233,7 +297,54 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * @param options Applied to every statement.
      */
     pipeline(requests: (string | QueryRequest | PipelineRequest)[], options?: QueryOptions): Promise<QueryResult[]>;
+    /**
+     * Bulk-loads rows into a table over `COPY ... FROM STDIN`, in
+     * PostgreSQL's binary format.
+     *
+     * The fastest way to write many rows: one statement carrying a stream
+     * of them, instead of an INSERT or a bind per row. Values are encoded
+     * from their JavaScript types against the table's own columns, so
+     * nothing has to be formatted by the caller.
+     *
+     * ```ts
+     * await connection.copyFromRows('customers', [
+     *   [1, 'Ada', new Date()],
+     *   [2, 'Grace', new Date()],
+     * ]);
+     * ```
+     *
+     * `source` can be an array, an iterable, or an async iterable - a
+     * stream of rows is never held whole.
+     *
+     * @param table The destination table, optionally schema-qualified.
+     * @param source The rows to load.
+     * @param options Which columns, how to encode them, a signal.
+     * @returns How many rows the server took.
+     * @throws DatabaseError When a row is refused, which ends the copy.
+     */
     copyFromRows(table: string, source: CopyRowSource, options?: CopyFromRowsOptions): Promise<CopyFromRowsResult>;
+    /**
+     * Opens a `COPY ... FROM STDIN` and hands back the stream to write it
+     * into, for a payload the caller formats itself.
+     *
+     * `copyFromRows()` is the one to reach for when the rows are
+     * JavaScript values; this is for bytes already in the format the
+     * statement names - CSV a caller produced, or a binary payload from
+     * somewhere else.
+     *
+     * ```ts
+     * const stream = await connection.copyFrom(
+     *   'copy customers from stdin (format csv)',
+     * );
+     * stream.write('1,Ada\n');
+     * await stream.end();
+     * ```
+     *
+     * @param sql The `COPY ... FROM STDIN` statement.
+     * @returns A writable stream; `end()` completes the copy and resolves
+     * with what the server took.
+     * @throws DatabaseError When the statement itself is refused.
+     */
     copyFrom(sql: string): Promise<CopyFromStream>;
     /**
      * Creates a PreparedStatement instance
@@ -368,8 +479,33 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      *   releaseSavepoint().
      */
     releaseSavepoint(name: string, immediate?: boolean): Promise<void>;
+    /**
+     * Subscribes to a `NOTIFY` channel, sending `LISTEN` the first time
+     * this connection hears of it.
+     *
+     * Several callbacks can share a channel; only the first costs a round
+     * trip. The channel name is quoted for the server, so it may be
+     * anything a string can hold.
+     *
+     * ```ts
+     * await connection.listen('order_placed', msg => {
+     *   console.log(msg.payload);
+     * });
+     * ```
+     *
+     * @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 sends `UNLISTEN` for it.
+     *
+     * Does nothing when the channel was never listened to.
+     *
+     * @param channel The channel to unsubscribe from.
+     */
     unListen(channel: string): Promise<void>;
+    /** Drops every callback on every channel, with one `UNLISTEN *`. */
     unListenAll(): Promise<void>;
     /**
      * Whether a statement asked for the wire to itself - `pipeline: false`

package/connection/connection.js

@@ -1,3 +1,4 @@
+import { updateErrorMessage } from '@jsopen/objects';
 import { ConnectionState, DataTypeOIDs } from '../constants.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { withAbortSignal } from '../util/abort-signal.js';
@@ -12,6 +13,30 @@ import { PreparedStatement } from './prepared-statement.js';
 const CAPTURE_STACK_TRACE_LIMIT = 5;
 /** Names the savepoint a nested transaction() scope takes. */
 let transactionScopeCounter = 0;
+/**
+ * One session on one server.
+ *
+ * Built either from a configuration object, a connection string, or
+ * nothing at all - in which case the environment answers for it, the
+ * same variables `psql` reads (`PGHOST`, `PGDATABASE`, `PGUSER`, and the
+ * rest). `connect()` opens it and `close()` ends it; a connection taken
+ * from a `Pool` returns there instead.
+ *
+ * ```ts
+ * const connection = new Connection('postgres://localhost/mydb');
+ * await connection.connect();
+ * const result = await connection.query('select * from customers where id = $1', {
+ *   params: [42],
+ * });
+ * await connection.close();
+ * ```
+ *
+ * `await using` closes it at the end of the scope, and every query
+ * method accepts an `AbortSignal`.
+ *
+ * Emits `connecting`, `ready`, `close`, `terminate`, `error`, `notice`
+ * and `debug`.
+ */
 export class Connection extends SafeEventEmitter {
     _pool;
     _intlCon;
@@ -78,6 +103,12 @@ export class Connection extends SafeEventEmitter {
     get secretKey() {
         return this._intlCon.secretKey;
     }
+    /**
+     * How many queries this connection is running right now.
+     *
+     * More than one only when they were pipelined; a connection answers
+     * them in order either way.
+     */
     get runningQueryCount() {
         return this._intlCon.runningQueryCount;
     }
@@ -187,6 +218,30 @@ export class Connection extends SafeEventEmitter {
     callFunction(functionId, args, options) {
         return withAbortSignal(options?.signal, () => this._intlCon.cancel(), () => this._captureErrorStack(this._intlCon.callFunction(functionId, args, options), this.callFunction));
     }
+    /**
+     * Runs one statement and returns its result.
+     *
+     * Parameters are sent separately from the SQL - `$1`, `$2` and so on -
+     * so nothing has to be escaped into the text. A statement seen a few
+     * times is prepared and reused on this connection without being asked
+     * for, and `cursor: true` returns a `Cursor` instead of the rows.
+     *
+     * ```ts
+     * const result = await connection.query(
+     *   'select id, name from customers where city = $1',
+     *   { params: ['Berlin'], objectRows: true },
+     * );
+     * result.rows; // [{ id: 1, name: '...' }, ...]
+     * ```
+     *
+     * A statement built with the `sql` tag carries its own parameters and
+     * is passed on its own.
+     *
+     * @param sql The statement, or one built with the `sql` tag.
+     * @param options Parameters, row shape, type mapping, cursor, signal.
+     * @returns The rows, the command tag, and what the columns were.
+     * @throws DatabaseError When the server refuses the statement.
+     */
     async query(sql, options) {
         if (sql instanceof QueryRequest) {
             if (options?.params)
@@ -389,6 +444,31 @@ export class Connection extends SafeEventEmitter {
             throw this._handleError(e, i != null && normalized[i] ? normalized[i].sql : normalized[0].sql);
         });
     }
+    /**
+     * Bulk-loads rows into a table over `COPY ... FROM STDIN`, in
+     * PostgreSQL's binary format.
+     *
+     * The fastest way to write many rows: one statement carrying a stream
+     * of them, instead of an INSERT or a bind per row. Values are encoded
+     * from their JavaScript types against the table's own columns, so
+     * nothing has to be formatted by the caller.
+     *
+     * ```ts
+     * await connection.copyFromRows('customers', [
+     *   [1, 'Ada', new Date()],
+     *   [2, 'Grace', new Date()],
+     * ]);
+     * ```
+     *
+     * `source` can be an array, an iterable, or an async iterable - a
+     * stream of rows is never held whole.
+     *
+     * @param table The destination table, optionally schema-qualified.
+     * @param source The rows to load.
+     * @param options Which columns, how to encode them, a signal.
+     * @returns How many rows the server took.
+     * @throws DatabaseError When a row is refused, which ends the copy.
+     */
     async copyFromRows(table, source, options) {
         /* c8 ignore start */
         if (this.listenerCount('debug')) {
@@ -404,6 +484,28 @@ export class Connection extends SafeEventEmitter {
             throw this._handleError(e, `COPY ${table} FROM STDIN (FORMAT binary)`);
         });
     }
+    /**
+     * Opens a `COPY ... FROM STDIN` and hands back the stream to write it
+     * into, for a payload the caller formats itself.
+     *
+     * `copyFromRows()` is the one to reach for when the rows are
+     * JavaScript values; this is for bytes already in the format the
+     * statement names - CSV a caller produced, or a binary payload from
+     * somewhere else.
+     *
+     * ```ts
+     * const stream = await connection.copyFrom(
+     *   'copy customers from stdin (format csv)',
+     * );
+     * stream.write('1,Ada\n');
+     * await stream.end();
+     * ```
+     *
+     * @param sql The `COPY ... FROM STDIN` statement.
+     * @returns A writable stream; `end()` completes the copy and resolves
+     * with what the server took.
+     * @throws DatabaseError When the statement itself is refused.
+     */
     async copyFrom(sql) {
         /* c8 ignore start */
         if (this.listenerCount('debug')) {
@@ -625,22 +727,45 @@ export class Connection extends SafeEventEmitter {
     releaseSavepoint(name, immediate) {
         return this._captureErrorStack(this._intlCon.releaseSavepoint(name, immediate));
     }
+    /**
+     * Subscribes to a `NOTIFY` channel, sending `LISTEN` the first time
+     * this connection hears of it.
+     *
+     * Several callbacks can share a channel; only the first costs a round
+     * trip. The channel name is quoted for the server, so it may be
+     * anything a string can hold.
+     *
+     * ```ts
+     * await connection.listen('order_placed', msg => {
+     *   console.log(msg.payload);
+     * });
+     * ```
+     *
+     * @param channel The channel to subscribe to.
+     * @param callback Called with each notification on it.
+     */
+    /* This used to test whether ANY channel had a listener rather than
+       this one, so a second channel added after the first never had its
+       own LISTEN sent and never received anything - verified live, only
+       the first channel ever appeared in pg_stat_activity's query text. */
     async listen(channel, callback) {
         channel = normalizeChannelName(channel);
         if (!this._notificationListeners) {
             this._notificationListeners = new SafeEventEmitter();
             this._intlCon.on('notification', (msg) => this._handleNotification(msg));
         }
-        // Bug: this used to check whether ANY channel already had a listener,
-        // not this one specifically - so a second, different channel added
-        // after the first never got its own LISTEN sent at all, and never
-        // received a notification for it (verified live: only the first
-        // channel ever showed up in pg_stat_activity's query text).
         const alreadyListening = !!this._notificationListeners.listenerCount(channel);
         this._notificationListeners.on(channel, callback);
         if (!alreadyListening)
             await this._captureErrorStack(this.query('LISTEN ' + escapeIdentifier(channel)));
     }
+    /**
+     * Drops every callback on one channel and sends `UNLISTEN` for it.
+     *
+     * Does nothing when the channel was never listened to.
+     *
+     * @param channel The channel to unsubscribe from.
+     */
     async unListen(channel) {
         channel = normalizeChannelName(channel);
         if (this._notificationListeners?.listenerCount(channel)) {
@@ -648,6 +773,7 @@ export class Connection extends SafeEventEmitter {
             await this._captureErrorStack(this.query('UNLISTEN ' + escapeIdentifier(channel)));
         }
     }
+    /** Drops every callback on every channel, with one `UNLISTEN *`. */
     async unListenAll() {
         if (this._notificationListeners?.eventNames().length) {
             this._notificationListeners.removeAllListeners();
@@ -780,6 +906,7 @@ export class Connection extends SafeEventEmitter {
                 err.message += `\n${String(err.lineNr - 1).padStart(3)}| ${lines[err.lineNr - 2]}`;
             err.message += `\n${String(err.lineNr).padStart(3)}| ${err.line}\n    .${'-'.repeat(Math.max(err.colNr - 1, 0))}^`;
         }
+        updateErrorMessage(err, err.message);
         return err;
     }
     /**

package/connection/copy-stream.d.ts

@@ -27,6 +27,7 @@ export declare class CopyToStream extends Readable {
     protected _discarding: boolean;
     protected _settled: boolean;
     protected _paused: boolean;
+    /** @param socket The socket the copy is running on. */
     constructor(socket: PgSocket);
     /**
      * Handles the copy's backend messages. Passed straight to
@@ -68,6 +69,7 @@ export declare class CopyFromStream extends Writable {
     protected _completed?: (err?: Error) => void;
     protected _copyEnded: boolean;
     protected _settled: boolean;
+    /** @param socket The socket the copy is running on. */
     constructor(socket: PgSocket);
     /**
      * Handles the copy's backend messages. Passed straight to

package/connection/copy-stream.js

@@ -27,6 +27,7 @@ export class CopyToStream extends Readable {
     _discarding = false;
     _settled = false;
     _paused = false;
+    /** @param socket The socket the copy is running on. */
     constructor(socket) {
         super();
         this._socket = socket;
@@ -148,6 +149,7 @@ export class CopyFromStream extends Writable {
     _completed;
     _copyEnded = false;
     _settled = false;
+    /** @param socket The socket the copy is running on. */
     constructor(socket) {
         super();
         this._socket = socket;

package/connection/cursor.d.ts

@@ -4,6 +4,32 @@ import { SafeEventEmitter } from '../safe-event-emitter.js';
 import type { AnyParseFunction, Maybe, Row } from '../types.js';
 import type { Portal } from './portal.js';
 import type { PreparedStatement } from './prepared-statement.js';
+/**
+ * A result read a batch at a time instead of all at once.
+ *
+ * Returned by `Connection.query()`/`PreparedStatement.execute()` when
+ * `cursor: true` is passed, and backed by a server-side portal: rows are
+ * fetched `fetchCount` at a time (100 by default) as they are asked for,
+ * so a result larger than memory can be read through without ever
+ * holding it.
+ *
+ * The cursor closes itself when the rows run out, and `for await`
+ * closes it however the loop ends. Anything else - breaking out of a
+ * manual `next()` loop, an error in the middle - wants `close()`, or
+ * `await using`, which calls it.
+ *
+ * ```ts
+ * const result = await connection.query('select * from big_table', {
+ *   cursor: true,
+ *   fetchCount: 500,
+ * });
+ * for await (const row of result.cursor!) {
+ *   // one row at a time; 500 arrive per round trip
+ * }
+ * ```
+ *
+ * Emits `fetch` with each batch as it arrives, and `close` once.
+ */
 export declare class Cursor extends SafeEventEmitter implements AsyncDisposable {
     private readonly _statement;
     private readonly _portal;
@@ -13,21 +39,57 @@ export declare class Cursor extends SafeEventEmitter implements AsyncDisposable
     private _taskQueue;
     private _rows;
     private _closed;
+    /** What the columns of every row this cursor returns are. */
     readonly fields: FieldInfo[];
     constructor(statement: PreparedStatement, portal: Portal, fields: FieldInfo[], parsers: AnyParseFunction[], queryOptions: QueryOptions);
+    /**
+     * The shape of the rows this cursor hands back - `'array'`,
+     * `'object'`, or `'custom'` when a `RowDecoder` of the caller's own is
+     * producing them.
+     */
     get rowType(): 'array' | 'object' | 'custom';
+    /**
+     * Whether the cursor is finished: the rows ran out, `close()` was
+     * called, or the portal was lost.
+     */
     get isClosed(): boolean;
+    /**
+     * The next row, or `undefined` once there are none left.
+     *
+     * Fetches a batch from the server when the current one is used up, and
+     * closes the cursor when the server answers with nothing.
+     *
+     * @returns The next row, or `undefined` at the end.
+     */
     next(): Promise<Maybe<Row>>;
+    /**
+     * Up to `nRows` rows, fetching as many batches as it takes.
+     *
+     * Shorter than asked for only at the end of the result, and empty once
+     * the cursor is closed - which is how the end is told apart from a
+     * batch boundary.
+     *
+     * @param nRows How many rows to read at most.
+     * @returns The rows read, in order.
+     */
     fetch(nRows: number): Promise<Row[]>;
+    /**
+     * Closes the cursor and releases the portal behind it.
+     *
+     * Idempotent, and called automatically when the rows run out or a
+     * `for await` loop ends. Emits `close`.
+     */
     close(): Promise<void>;
+    /** Reads one batch from the portal and queues it up for the callers. */
     private _fetchRows;
     /**
-     * Iterates the remaining rows, fetching a batch at a time, and closes
-     * the cursor when the loop ends - whether it ran out of rows, broke
-     * early, or the body threw. Nothing is decoded ahead of what is asked
-     * for, so this streams a result larger than memory the same way next()
-     * does one row at a time.
+     * Iterates the remaining rows, a batch at a time, and closes the cursor
+     * when the loop ends - whether it ran out of rows, broke early, or the
+     * body threw.
+     *
+     * @returns An iterator over the rows left to read.
      */
     [Symbol.asyncIterator](): AsyncIterableIterator<Row>;
+    /** Closes the cursor, so `await using` can own one. */
     [Symbol.asyncDispose](): Promise<void>;
 }