postgrejs 3.8.0 → 3.10.0

package/connection/pool.d.ts

@@ -5,16 +5,21 @@ import type { QueryResult } from '../interfaces/query-result.js';
 import type { ScriptExecuteOptions } from '../interfaces/script-execute-options.js';
 import type { ScriptResult } from '../interfaces/script-result.js';
 import type { StatementPrepareOptions } from '../interfaces/statement-prepare-options.js';
+import type { TransactionOptions } from '../interfaces/transaction-options.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { QueryRequest } from '../util/sql-tag.js';
 import { Connection, type NotificationCallback } from './connection.js';
 import { IntlConnection } from './intl-connection.js';
 import type { PreparedStatement } from './prepared-statement.js';
-export interface PoolPipelineOptions {
-    pipeline?: boolean;
-}
-export type PoolQueryOptions = QueryOptions & PoolPipelineOptions;
-export type PoolScriptExecuteOptions = ScriptExecuteOptions & PoolPipelineOptions;
+/**
+ * @deprecated `pipeline` is part of `QueryOptions` and
+ * `ScriptExecuteOptions` now, so every connection takes it too. Kept as
+ * an alias of that one field so the exported type still means what it
+ * did.
+ */
+export type PoolPipelineOptions = Pick<QueryOptions, 'pipeline'>;
+export type PoolQueryOptions = QueryOptions;
+export type PoolScriptExecuteOptions = ScriptExecuteOptions;
 /**
  * One pooled connection the pipelined path is currently borrowing.
  *
@@ -93,7 +98,7 @@ export declare class Pool extends SafeEventEmitter {
      * is free to pick a different connection, and a transaction lives on
      * one. This is the way to get several statements onto the same one.
      */
-    transaction<T>(fn: (connection: Connection) => Promise<T>): Promise<T>;
+    transaction<T>(fn: (connection: Connection) => Promise<T>, options?: TransactionOptions): Promise<T>;
     prepare(sql: string, options?: StatementPrepareOptions): Promise<PreparedStatement>;
     release(connection: Connection): Promise<void>;
     listen(channel: string, callback: NotificationCallback): Promise<void>;
@@ -113,6 +118,25 @@ export declare class Pool extends SafeEventEmitter {
      * the connection had no query in flight to reject.
      */
     protected _onConnectionDestroyed(intlCon: IntlConnection): void;
+    /**
+     * Whether a one-shot query may share a pooled connection with the
+     * queries already in flight on it.
+     *
+     * **Opt-in**, per call or with `pipeline: true` on the pool. It is
+     * worth asking for - `max` stops being a ceiling on concurrent
+     * queries and becomes one on connections, and a burst of 500 through
+     * a pool of 10 measured 12ms against 29ms - but it is not the default,
+     * because it moves the query onto a connection other callers are
+     * using and session state there stops being the caller's own.
+     *
+     * The exclusions below are not policy, they are statements that need a
+     * connection to themselves for longer than the call takes to resolve:
+     * a cursor reads from a portal afterwards, a transaction spans later
+     * statements, a COPY holds the connection mid-stream, `autoCommit:
+     * false` says a transaction is being managed by hand, and an
+     * `AbortSignal` cancels by tearing down whatever the connection is
+     * doing - which, shared, is not only this query.
+     */
     protected _canPipeline(pipeline: boolean | undefined, sql: string, autoCommit: boolean | undefined, signal: AbortSignal | undefined): boolean;
     /**
      * Picks the pooled connection a pipelined query should ride on, or

package/connection/pool.js

@@ -272,10 +272,10 @@ export class Pool extends SafeEventEmitter {
      * is free to pick a different connection, and a transaction lives on
      * one. This is the way to get several statements onto the same one.
      */
-    async transaction(fn) {
+    async transaction(fn, options) {
         const connection = await this.acquire();
         try {
-            return await connection.transaction(fn);
+            return await connection.transaction(fn, options);
         }
         finally {
             await this.release(connection);
@@ -361,8 +361,27 @@ export class Pool extends SafeEventEmitter {
         // connection that could not be created stays unambiguous.
         this.emit('error', reason);
     }
+    /**
+     * Whether a one-shot query may share a pooled connection with the
+     * queries already in flight on it.
+     *
+     * **Opt-in**, per call or with `pipeline: true` on the pool. It is
+     * worth asking for - `max` stops being a ceiling on concurrent
+     * queries and becomes one on connections, and a burst of 500 through
+     * a pool of 10 measured 12ms against 29ms - but it is not the default,
+     * because it moves the query onto a connection other callers are
+     * using and session state there stops being the caller's own.
+     *
+     * The exclusions below are not policy, they are statements that need a
+     * connection to themselves for longer than the call takes to resolve:
+     * a cursor reads from a portal afterwards, a transaction spans later
+     * statements, a COPY holds the connection mid-stream, `autoCommit:
+     * false` says a transaction is being managed by hand, and an
+     * `AbortSignal` cancels by tearing down whatever the connection is
+     * doing - which, shared, is not only this query.
+     */
     _canPipeline(pipeline, sql, autoCommit, signal) {
-        return (pipeline === true &&
+        return ((pipeline != null ? pipeline : this.config.pipeline === true) &&
             !signal &&
             this._pipelineMaxQueries > 1 &&
             this._pipelineMaxConnections > 0 &&

package/connection/prepared-statement.js

@@ -1,3 +1,4 @@
+import { DataTypeOIDs } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
@@ -5,6 +6,7 @@ import { withAbortSignal } from '../util/abort-signal.js';
 import { getParsers } from '../util/get-parsers.js';
 import { resolveColumnFormats } from '../util/resolve-column-formats.js';
 import { resolveRowType } from '../util/row-decoder.js';
+import { isTransactionCommand, refusesSavepoint, } from '../util/transaction-command.js';
 import { wrapRowDescription } from '../util/wrap-row-description.js';
 import { Cursor } from './cursor.js';
 import { getIntlConnection } from './intl-connection.js';
@@ -51,6 +53,9 @@ export class PreparedStatement extends SafeEventEmitter {
     }
     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));
         return this._executeWithTransaction(options);
@@ -108,6 +113,7 @@ export class PreparedStatement extends SafeEventEmitter {
             throw new Error('executeBatch() cannot return a cursor - a batch runs every set to ' +
                 'completion under one Sync, so there is no portal left to fetch from');
         const intlCon = getIntlConnection(this.connection);
+        options = intlCon.withDefaults(options);
         if (!paramSets.length)
             return { results: [], totalRowsAffected: 0 };
         if (options.signal)
@@ -153,7 +159,17 @@ export class PreparedStatement extends SafeEventEmitter {
      */
     async _withTransaction(options = {}, fn, canInlineSavepoint = false) {
         const intlCon = getIntlConnection(this.connection);
-        const transactionCommand = this.sql.match(/^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i);
+        // See Connection._query(): a money parameter is written as an int64
+        // of minor units, so the server's scale has to be known before the
+        // Bind goes out.
+        if (this.paramTypes?.includes(DataTypeOIDs.money) ||
+            this.paramTypes?.includes(DataTypeOIDs._money) ||
+            // And before any of this statement's own money columns are read:
+            // a cursor and a batch both decode inside the message loop, where
+            // there is no longer anywhere to ask from.
+            intlCon.needsMoneyFormat(this._fields, options))
+            await intlCon.ensureMoneyFormat();
+        const transactionCommand = isTransactionCommand(this.sql);
         let beginFirst = false;
         let commitLast = false;
         const autoCommit = options?.autoCommit;
@@ -170,7 +186,11 @@ export class PreparedStatement extends SafeEventEmitter {
             await intlCon.execute('BEGIN');
         // See IntlConnection.execute()'s own rollbackOnError for why
         // intlCon.inTransaction goes first here but last in the checks below.
-        const rollbackOnError = !transactionCommand &&
+        const rollbackOnError = 
+        // See IntlConnection.execute(): `SET TRANSACTION` keeps the
+        // implicit BEGIN and loses only the savepoint, which PostgreSQL
+        // refuses to let it run inside.
+        !refusesSavepoint(this.sql) &&
             intlCon.inTransaction &&
             (options?.rollbackOnError ?? intlCon.config.rollbackOnError ?? true);
         // When `fn` can put the savepoint on the wire itself, SAVEPOINT and

package/data-type-map.d.ts

@@ -1,6 +1,8 @@
 import type { DataType } from './interfaces/data-type.js';
 import type { OID } from './types.js';
 export declare class DataTypeMap {
+    protected _inferScalars: DataType[];
+    protected _inferArrays: DataType[];
     private _itemsByOID;
     private _items;
     /**
@@ -17,6 +19,20 @@ export declare class DataTypeMap {
     constructor(other?: DataTypeMap);
     get(oid: OID): DataType;
     register(dataTypes: DataType | DataType[]): void;
+    /**
+     * The two lists determine() actually walks, newest-registered first.
+     *
+     * A value is either an array or it is not, so half of `_items` can
+     * never match it - and the half that can is the smaller one: of 127
+     * registered types, a plain number used to be tested against 22 and
+     * skipped past 105. Rebuilt on registration, which happens at startup
+     * and hardly ever again, so the walk itself reads a list that is
+     * already only what it needs.
+     *
+     * A type that is not inferrable is left out of both: determine() may
+     * never pick it, however well its isType matches.
+     */
+    protected _rebuildInferenceLists(): void;
     determine(value: any): OID;
 }
 export declare const GlobalTypeMap: DataTypeMap;

package/data-type-map.js

@@ -21,6 +21,7 @@ import { ArrayJsonPathType, JsonPathType } from './data-types/jsonpath-type.js';
 import { ArrayLineType, LineType } from './data-types/line-type.js';
 import { ArrayLsegType, LsegType } from './data-types/lseg-type.js';
 import { ArrayMacaddr8Type, ArrayMacaddrType, Macaddr8Type, MacaddrType, } from './data-types/macaddr-type.js';
+import { ArrayMoneyType, MoneyType } from './data-types/money-type.js';
 import { ArrayNumericType, NumericType } from './data-types/numeric-type.js';
 import { ArrayOidType, OidType } from './data-types/oid-type.js';
 import { ArrayOidVectorType, OidVectorType, } from './data-types/oid-vector-type.js';
@@ -38,7 +39,10 @@ import { ArrayTsQueryType, ArrayTsVectorType, TsQueryType, TsVectorType, } from
 import { ArrayUuidType, UuidType } from './data-types/uuid-type.js';
 import { ArrayVarcharType, VarcharType } from './data-types/varchar-type.js';
 import { ArrayCidType, ArrayXid8Type, ArrayXidType, CidType, Xid8Type, XidType, } from './data-types/xid-type.js';
+import { arrayLeaf } from './util/array-leaf.js';
 export class DataTypeMap {
+    _inferScalars = [];
+    _inferArrays = [];
     _itemsByOID = {};
     _items = [];
     /**
@@ -56,6 +60,11 @@ export class DataTypeMap {
         if (other instanceof DataTypeMap) {
             this._items = [...other._items];
             this._itemsByOID = { ...other._itemsByOID };
+            // Shared, not copied: they are rebuilt wholesale by register(),
+            // so a copy that registers nothing never diverges and one that
+            // does gets its own pair then.
+            this._inferScalars = other._inferScalars;
+            this._inferArrays = other._inferArrays;
         }
     }
     get(oid) {
@@ -71,6 +80,37 @@ export class DataTypeMap {
             else
                 this._items.push(t);
         }
+        this._rebuildInferenceLists();
+    }
+    /**
+     * The two lists determine() actually walks, newest-registered first.
+     *
+     * A value is either an array or it is not, so half of `_items` can
+     * never match it - and the half that can is the smaller one: of 127
+     * registered types, a plain number used to be tested against 22 and
+     * skipped past 105. Rebuilt on registration, which happens at startup
+     * and hardly ever again, so the walk itself reads a list that is
+     * already only what it needs.
+     *
+     * A type that is not inferrable is left out of both: determine() may
+     * never pick it, however well its isType matches.
+     */
+    _rebuildInferenceLists() {
+        const scalars = [];
+        const arrays = [];
+        let i;
+        let t;
+        // Built back to front, so index 0 is the newest registration and the
+        // walk runs forward - which is the direction a JS array is fastest
+        // to read and the one that needs no length arithmetic per step.
+        for (i = this._items.length - 1; i >= 0; i--) {
+            t = this._items[i];
+            if (t.inferrable === false)
+                continue;
+            (t.elementsOID ? arrays : scalars).push(t);
+        }
+        this._inferScalars = scalars;
+        this._inferArrays = arrays;
     }
     determine(value) {
         if (value == null)
@@ -94,21 +134,22 @@ export class DataTypeMap {
                     'it at the call site (`new BindParam(oid, value)`)');
             }
         }
+        // An array is typed from the first value inside it that is actually
+        // a value: `value[0]` answers `_int2vector` for [[1, 2], [3, 4]],
+        // because the first element is itself an array and a vector is the
+        // one registered type an array of numbers matches, and answers
+        // nothing at all for [null, 2, 3].
         const valueIsArray = Array.isArray(value);
+        const candidates = valueIsArray ? this._inferArrays : this._inferScalars;
+        const v = valueIsArray ? arrayLeaf(value) : value;
+        // Newest-registered first, so a later registration of the same OID
+        // wins - see _rebuildInferenceLists() for how the order is kept.
+        const l = candidates.length;
         let i;
         let t;
-        for (i = this._items.length - 1; i >= 0; i--) {
-            t = this._items[i];
-            // Walked newest-registered first, so a later registration of the
-            // same OID wins - and a type marked `inferrable: false` is never
-            // picked here at all, however well `isType` matches.
-            if (t.inferrable === false)
-                continue;
-            if (valueIsArray) {
-                if (t.elementsOID && t.isType(value[0]))
-                    return t.oid;
-            }
-            else if (!t.elementsOID && t.isType(value))
+        for (i = 0; i < l; i++) {
+            t = candidates[i];
+            if (t.isType(v))
                 return t.oid;
         }
         return DataTypeOIDs.unknown;
@@ -121,6 +162,9 @@ GlobalTypeMap.register([JsonbType, ArrayJsonbType]);
 GlobalTypeMap.register([JsonType, ArrayJsonType]);
 GlobalTypeMap.register([BoolType, ArrayBoolType]);
 GlobalTypeMap.register([NumericType, ArrayNumericType]);
+// Registered after numeric and not inferrable: a JavaScript number is
+// never money by shape, and the type is reached by naming it.
+GlobalTypeMap.register([MoneyType, ArrayMoneyType]);
 GlobalTypeMap.register([Float4Type, ArrayFloat4Type]);
 GlobalTypeMap.register([Float8Type, ArrayFloat8Type]);
 GlobalTypeMap.register([Int2Type, ArrayInt2Type]);

package/data-types/circle-type.js

@@ -8,13 +8,16 @@ export const CircleType = {
     name: 'circle',
     oid: DataTypeOIDs.circle,
     jsType: 'Circle',
+    // isType() accepts a plain object as well as a Circle, and that object
+    // may spell the radius either way - hence Circle.radiusOf() rather
+    // than the property.
     encodeText(v) {
-        return `<(${v.x},${v.y}),${v.r}>`;
+        return `<(${v.x},${v.y}),${Circle.radiusOf(v)}>`;
     },
     encodeBinary(buf, v) {
         buf.writeDoubleBE(v.x);
         buf.writeDoubleBE(v.y);
-        buf.writeDoubleBE(v.r);
+        buf.writeDoubleBE(Circle.radiusOf(v));
     },
     decodeBinary(v, offset = 0) {
         return new Circle(v.readDoubleBE(offset), v.readDoubleBE(offset + 8), v.readDoubleBE(offset + 16));

package/data-types/classes/geometric.d.ts

@@ -5,19 +5,46 @@ export declare class Point {
     constructor(x?: number, y?: number);
     /** As PostgreSQL prints it, so it casts back through `::point`. */
     toString(): string;
-    toJSON(): string;
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres(): string;
     static isPointLike(v: any): boolean;
 }
 /** A `circle`: a centre and a radius. */
 export declare class Circle {
     x: number;
     y: number;
-    r: number;
-    constructor(x?: number, y?: number, r?: number);
+    radius: number;
+    constructor(x?: number, y?: number, radius?: number);
+    /**
+     * The radius under the name this client used up to 3.9. `pg` spells it
+     * `radius`, and a value decoded here should be usable wherever one of
+     * its own is, so `radius` is what the property is now - but `r` was a
+     * released name, so it stays as an accessor onto the same number
+     * rather than silently reading back undefined.
+     *
+     * @deprecated use `radius`
+     */
+    get r(): number;
+    set r(value: number);
     /** As PostgreSQL prints it, so it casts back through `::circle`. */
     toString(): string;
-    toJSON(): string;
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres(): string;
     static isCircleLike(v: any): boolean;
+    /**
+     * The radius of anything isCircleLike() accepts: a Circle, the plain
+     * `{x, y, radius}` object `pg` hands back, or the `{x, y, r}` that was
+     * this client's own shape before the classes existed.
+     */
+    static radiusOf(v: any): number;
 }
 /**
  * Two corners, which is how both `box` and `lseg` are carried - and why
@@ -32,7 +59,12 @@ declare abstract class TwoPoints {
     x2: number;
     y2: number;
     constructor(x1?: number, y1?: number, x2?: number, y2?: number);
-    toJSON(): string;
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres(): string;
     static isTwoPointsLike(v: any): boolean;
 }
 /** A `box`: a rectangle given by two opposite corners. */
@@ -61,7 +93,12 @@ export declare class Line {
     constructor(a?: number, b?: number, c?: number);
     /** As PostgreSQL prints it, so it casts back through `::line`. */
     toString(): string;
-    toJSON(): string;
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres(): string;
     static isLineLike(v: any): boolean;
 }
 /**
@@ -77,7 +114,12 @@ declare abstract class PointList {
         x: number;
         y: number;
     })[]);
-    toJSON(): string;
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres(): string;
     protected join(): string;
 }
 /**

package/data-types/classes/geometric.js

@@ -27,7 +27,12 @@ export class Point {
     toString() {
         return `(${this.x},${this.y})`;
     }
-    toJSON() {
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres() {
         return this.toString();
     }
     /* c8 ignore next 3 */
@@ -42,17 +47,37 @@ export class Point {
 export class Circle {
     x;
     y;
-    r;
-    constructor(x = 0, y = 0, r = 0) {
+    radius;
+    constructor(x = 0, y = 0, radius = 0) {
         this.x = x;
         this.y = y;
-        this.r = r;
+        this.radius = radius;
+    }
+    /**
+     * The radius under the name this client used up to 3.9. `pg` spells it
+     * `radius`, and a value decoded here should be usable wherever one of
+     * its own is, so `radius` is what the property is now - but `r` was a
+     * released name, so it stays as an accessor onto the same number
+     * rather than silently reading back undefined.
+     *
+     * @deprecated use `radius`
+     */
+    get r() {
+        return this.radius;
+    }
+    set r(value) {
+        this.radius = value;
     }
     /** As PostgreSQL prints it, so it casts back through `::circle`. */
     toString() {
-        return `<(${this.x},${this.y}),${this.r}>`;
-    }
-    toJSON() {
+        return `<(${this.x},${this.y}),${this.radius}>`;
+    }
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres() {
         return this.toString();
     }
     static isCircleLike(v) {
@@ -60,7 +85,15 @@ export class Circle {
             Object.keys(v).length === 3 &&
             isNum(v.x) &&
             isNum(v.y) &&
-            isNum(v.r));
+            (isNum(v.radius) || isNum(v.r)));
+    }
+    /**
+     * The radius of anything isCircleLike() accepts: a Circle, the plain
+     * `{x, y, radius}` object `pg` hands back, or the `{x, y, r}` that was
+     * this client's own shape before the classes existed.
+     */
+    static radiusOf(v) {
+        return v.radius ?? v.r;
     }
 }
 /**
@@ -81,7 +114,12 @@ class TwoPoints {
         this.x2 = x2;
         this.y2 = y2;
     }
-    toJSON() {
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres() {
         return this.toString();
     }
     static isTwoPointsLike(v) {
@@ -129,7 +167,12 @@ export class Line {
     toString() {
         return `{${this.a},${this.b},${this.c}}`;
     }
-    toJSON() {
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres() {
         return this.toString();
     }
     static isLineLike(v) {
@@ -152,7 +195,12 @@ class PointList {
     constructor(points = []) {
         this.points = points.map(p => p instanceof Point ? p : new Point(p.x, p.y));
     }
-    toJSON() {
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres() {
         return this.toString();
     }
     join() {

package/data-types/classes/interval.d.ts

@@ -1,4 +1,4 @@
-/** The fields an Interval is built from. All optional, all defaulting to 0. */
+/** The fields an Interval is built from; it keeps the ones that have a value. */
 export interface IntervalFields {
     years?: number;
     months?: number;
@@ -18,20 +18,29 @@ export interface IntervalFields {
  * zone, can add one to a timestamp. Anything here that answered "how many
  * milliseconds is this" would have to invent those lengths.
  *
- * Every field is always present, 0 when the value has none:
+ * It carries the fields that have a value and no others, which is what
+ * the wire format carries too - three quantities, and a zero among them
+ * is not a field:
  *
  * ```ts
  * const iv = new Interval({ days: 1, hours: 2 });
- * iv.minutes;          // 0, not undefined
+ * Object.keys(iv);     // ['days', 'hours']
+ * iv.minutes;          // undefined
  * String(iv);          // '1 day 02:00:00'
  * iv.toISOString();    // 'P0Y0M1DT2H0M0S'
  * ```
  *
- * The field names are `pg`'s (`postgres-interval`), so code ported from it
- * reads the same values from the same places. The difference is that
- * package's objects are sparse - `interval '1 day'` gives it `{days: 1}`
- * and nothing else, so `iv.hours + 1` is NaN and a zero interval is `{}` -
- * and that it has no `toString()`, so a log line gets `[object Object]`.
+ * The field names and the shape are `pg`'s (`postgres-interval`), so code
+ * ported from it reads the same values from the same places and a
+ * `JSON.stringify` of a row says the same thing. The difference is that
+ * this has a `toString()` - `pg`'s object gives `[object Object]` in a log
+ * line - and a `toPostgres()`, so the value can be sent back.
+ *
+ * The fields are optional, so `iv.hours + 1` does not compile without
+ * saying what an absent one means (`(iv.hours ?? 0) + 1`). That is the
+ * point: which fields a value has depends on the value, not on the type,
+ * and the older shape - every field present and 0 - hid that behind
+ * numbers nobody wrote.
  *
  * `milliseconds` carries the sub-second part and can be fractional, since
  * PostgreSQL stores microseconds: `interval '0.000001 seconds'` is
@@ -40,17 +49,27 @@ export interface IntervalFields {
  * A negative interval carries the sign on each field that has one, the way
  * the server prints it: `interval '-1 day -2 hours'` is
  * `{ days: -1, hours: -2 }`.
+ *
+ * `toPostgres()` is `pg`'s convention for "write yourself back", so a
+ * value read here can be passed to any encoder that follows it - this
+ * client's own parameter path never needed it, since it knows the class.
  */
 export declare class Interval implements IntervalFields {
-    years: number;
-    months: number;
-    days: number;
-    hours: number;
-    minutes: number;
+    years?: number;
+    months?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
     /** Whole seconds; the sub-second part is in `milliseconds`. */
-    seconds: number;
+    seconds?: number;
     /** The sub-second part, fractional down to a microsecond. */
-    milliseconds: number;
+    milliseconds?: number;
+    /**
+     * Keeps the fields that have a value. A zero is not one: it is what
+     * every field of every interval would otherwise be filled with, and
+     * `{ days: 1 }` says what `interval '1 day'` is far better than the
+     * same thing plus six zeroes nobody wrote.
+     */
     constructor(fields?: IntervalFields);
     /**
      * Builds one from the three quantities the wire format carries: a signed
@@ -69,5 +88,10 @@ export declare class Interval implements IntervalFields {
     toString(): string;
     /** The interval as an ISO 8601 duration. */
     toISOString(): string;
-    toJSON(): string;
+    /**
+     * The literal PostgreSQL reads back, for an encoder that asks the value
+     * how to write itself - `pg`'s convention, and the reason a value this
+     * client decoded can be handed straight to one.
+     */
+    toPostgres(): string;
 }