postgrejs 3.9.0 → 3.10.1

package/CHANGELOG.md

@@ -1,6 +1,37 @@
 ## Changelog
 
-### [v3.9.0](https://github.com/panates/postgrejs/compare/v3.8.0...v3.9.0) - 
+### [v3.10.1](https://github.com/panates/postgrejs/compare/v3.10.0...v3.10.1) - 
+
+#### 🚀 New Features
+
+- feat: accept `connectionString`, and answer a key from another client @Eray Hanoğlu 
+
+### [v3.10.0](https://github.com/panates/postgrejs/compare/v3.9.0...v3.10.0) -  22 September 2026 
+
+#### Breaking Changes :warning:
+
+- feat!: serialise the value classes as their fields @Eray Hanoğlu  
+
+#### 🚀 New Features
+
+- feat: decode the date/time types into Temporal values on request @Eray Hanoğlu 
+- feat: let fetchAsString ask for a scalar without its arrays @Eray Hanoğlu 
+- feat: decode money and numeric as their exact decimal string on request @Eray Hanoğlu 
+- feat: let fetchAsString name an array column by its element type @Eray Hanoğlu 
+- feat: report a lost connection on 'error', not only on 'close' @Eray Hanoğlu 
+- feat: name Circle's radius `radius`, as pg does @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix: stop declaring an element type for an array of numbers @Eray Hanoğlu 
+- fix: sign only the interval components that have one, and add toPostgres() @Eray Hanoğlu 
+- fix: read the database out of a `postgresql://` URL @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs: name the migration note after the release it is for @Eray Hanoğlu 
+
+### [v3.9.0](https://github.com/panates/postgrejs/compare/v3.8.0...v3.9.0) -  22 September 2026 
 
 #### 🚀 New Features
 

package/connection/connection.js

@@ -1,5 +1,4 @@
 import { ConnectionState, DataTypeOIDs } from '../constants.js';
-import { GlobalTypeMap } from '../data-type-map.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { withAbortSignal } from '../util/abort-signal.js';
 import { normalizeChannelName } from '../util/channel-name.js';
@@ -665,7 +664,12 @@ export class Connection extends SafeEventEmitter {
             : this._intlCon.config.pipeline === false;
     }
     async _query(sql, options) {
-        const typeMap = options?.typeMap || GlobalTypeMap;
+        // Only the type map, not withDefaults(): the parameter types are
+        // decided here, before the options are merged, and merging them here
+        // would change what the merge means - a fetchAsString list that came
+        // from the connection deliberately takes a cheaper route than one
+        // named on the call.
+        const typeMap = this._intlCon.resolveTypeMap(options);
         const paramTypes = options?.params?.map(prm => prm instanceof BindParam
             ? prm.oid
             : // A Date and a string go out with no declared type, so the

package/connection/intl-connection.d.ts

@@ -73,9 +73,14 @@ export declare class IntlConnection extends SafeEventEmitter {
     /** The session's DateStyle as last reported, and what it parsed to. */
     protected _dateStyleRaw?: string;
     protected _dateStyle?: PgDateStyle;
+    /** The session's TimeZone as last reported, once checked. */
+    protected _timeZoneRaw?: string;
+    protected _timeZone?: string;
     /** The server's own money rendering - see ensureMoneyFormat(). */
     protected _moneyFormat?: MoneyFormat;
     protected _moneyFormatPromise?: Promise<void>;
+    /** Whether the socket has been up, which is what makes a close a loss. */
+    protected _live: boolean;
     /** Statements currently holding the wire - see enterWire(). */
     protected _wireUsers: number;
     protected _wireIdleWaiters?: (() => void)[];
@@ -410,6 +415,12 @@ export declare class IntlConnection extends SafeEventEmitter {
      * loop is over and the question can be asked.
      */
     protected _decodeDeferredRows(deferred: DeferredRows[], rowDecoder: RowDecoder, options: QueryOptions): Promise<QueryOptions>;
+    /**
+     * The type map a statement is parsed and its parameters typed with:
+     * the call's, else the connection's, with whatever `temporalTypes`
+     * asks for registered on top of it.
+     */
+    resolveTypeMap(options?: ConnectionMappingDefaults): DataTypeMap;
     withDefaults<T extends DataMappingOptions>(options: T): T;
     /**
      * The session's DateStyle, when it is not ISO.
@@ -422,8 +433,14 @@ export declare class IntlConnection extends SafeEventEmitter {
      * compare while nothing changes - which is always, for the ISO
      * default that needs no parsing at all.
      */
+    /**
+     * The zone `timestamptz` values are given when they decode to a
+     * Temporal.ZonedDateTime. Checked when the server's answer changes, so
+     * that a zone nothing can resolve is reported against the setting it
+     * came from instead of from inside a decode.
+     */
+    protected _currentTimeZone(): Maybe<string>;
     protected _currentDateStyle(): Maybe<PgDateStyle>;
-    protected _onError(err: Error): void;
 }
 export declare function getIntlConnection(connection: Connection): IntlConnection;
 export {};

package/connection/intl-connection.js

@@ -2,6 +2,7 @@ import { performance } from 'node:perf_hooks';
 import { ConnectionState, DataTypeOIDs, DEFAULT_COLUMN_FORMAT, } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { parseMoneyFormat } from '../data-types/money-type.js';
+import { temporalTypeMap } from '../data-types/temporal-types.js';
 import { DatabaseError } from '../protocol/database-error.js';
 import { PgSocket } from '../protocol/pg-socket.js';
 import { Protocol } from '../protocol/protocol.js';
@@ -9,10 +10,13 @@ import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { getConnectionConfig } from '../util/connection-config.js';
 import { buildCopySql, buildProbeSql, writeCopyBinaryRows, } from '../util/copy-from-rows.js';
 import { parseDateStyleSetting } from '../util/date-style.js';
+import { validateDecimalAsString } from '../util/decimal-as-string.js';
 import { escapeLiteral } from '../util/escape-literal.js';
+import { fetchAsStringEqual, fetchAsStringNamesElement, fetchAsStringNamesOid, validateFetchAsString, } from '../util/fetch-as-string.js';
 import { getParsers } from '../util/get-parsers.js';
-import { fetchAsStringEqual, resolveColumnFormats, } from '../util/resolve-column-formats.js';
+import { resolveColumnFormats } from '../util/resolve-column-formats.js';
 import { resolveRowDecoder, resolveRowType, } from '../util/row-decoder.js';
+import { requireTimeZone } from '../util/temporal.js';
 import { isTransactionCommand, refusesSavepoint, } from '../util/transaction-command.js';
 import { wrapRowDescription } from '../util/wrap-row-description.js';
 import { CopyFromStream, CopyToStream } from './copy-stream.js';
@@ -89,11 +93,14 @@ const PREPARE_AFTER_USES = 2;
 /** The connection-configuration keys that are per-statement defaults. */
 const MAPPING_DEFAULT_KEYS = [
     'typeMap',
+    'temporalTypes',
+    'timeZone',
     'columnFormat',
     'objectRows',
     'rowDecoder',
     'utcDates',
     'fetchAsString',
+    'decimalAsString',
     'unknownTypesAsString',
     'moneyFormat',
 ];
@@ -197,9 +204,14 @@ export class IntlConnection extends SafeEventEmitter {
     /** The session's DateStyle as last reported, and what it parsed to. */
     _dateStyleRaw;
     _dateStyle;
+    /** The session's TimeZone as last reported, once checked. */
+    _timeZoneRaw;
+    _timeZone;
     /** The server's own money rendering - see ensureMoneyFormat(). */
     _moneyFormat;
     _moneyFormatPromise;
+    /** Whether the socket has been up, which is what makes a close a loss. */
+    _live = false;
     /** Statements currently holding the wire - see enterWire(). */
     _wireUsers = 0;
     _wireIdleWaiters;
@@ -223,11 +235,36 @@ export class IntlConnection extends SafeEventEmitter {
         super();
         this._config = Object.freeze(getConnectionConfig(config));
         this._mappingDefaults = pickMappingDefaults(this._config);
+        // Built here rather than at the first statement, so that a Temporal
+        // this runtime does not have, or an OID that is not one of the five,
+        // is reported before any I/O - and so the map every statement then
+        // reuses is made once.
+        if (this._mappingDefaults?.temporalTypes)
+            temporalTypeMap(this._mappingDefaults.temporalTypes, this._mappingDefaults.typeMap || GlobalTypeMap);
         this.socket = new PgSocket(this._config);
-        this.socket.on('error', err => this._onError(err));
+        this.socket.on('ready', () => {
+            this._live = true;
+        });
         // The reason travels with it: 'close' on its own cannot tell an
         // ordinary shutdown from the backend being terminated under us.
-        this.socket.on('close', (reason) => this.emit('close', reason));
+        //
+        // A loss is reported on 'error' as well, which is where `pg` puts it
+        // and where code ported from it listens - `client.on('error')` was
+        // attached and never fired, because a terminated backend closes
+        // cleanly at the socket level and Node gives 'close' without an
+        // 'error' of its own. The Pool already reports the same object the
+        // same way. Emitted before 'close': the loss is the cause and the
+        // close is the consequence. Safe to do unconditionally, since
+        // SafeEventEmitter drops an 'error' nobody is listening for instead
+        // of throwing - and only for a connection that was up, so a failed
+        // connect stays the business of the promise connect() returns.
+        this.socket.on('close', (reason) => {
+            const live = this._live;
+            this._live = false;
+            if (reason && live)
+                this.emit('error', reason);
+            this.emit('close', reason);
+        });
         this.socket.on('notification', payload => this.emit('notification', payload));
         // Covers a notice that arrives while no statement is running. One
         // raised *by* a statement is dispatched to that statement's own
@@ -618,8 +655,11 @@ export class IntlConnection extends SafeEventEmitter {
             if (oid !== DataTypeOIDs.money && oid !== DataTypeOIDs._money)
                 continue;
             // Named by fetchAsString, so the value goes back exactly as the
-            // server rendered it and no decoder asks what a minor unit is.
-            if (asString?.includes(oid))
+            // server rendered it and no decoder asks what a minor unit is -
+            // which naming `money` does for a `money[]` column too.
+            if (fetchAsStringNamesOid(asString, oid) ||
+                (oid === DataTypeOIDs._money &&
+                    fetchAsStringNamesElement(asString, DataTypeOIDs.money)))
                 continue;
             return true;
         }
@@ -1815,11 +1855,27 @@ export class IntlConnection extends SafeEventEmitter {
         }
         return opts;
     }
+    /**
+     * The type map a statement is parsed and its parameters typed with:
+     * the call's, else the connection's, with whatever `temporalTypes`
+     * asks for registered on top of it.
+     */
+    resolveTypeMap(options) {
+        const defaults = this._mappingDefaults;
+        const base = options?.typeMap || defaults?.typeMap || GlobalTypeMap;
+        const temporal = options?.temporalTypes ?? defaults?.temporalTypes;
+        return temporal ? temporalTypeMap(temporal, base) : base;
+    }
     withDefaults(options) {
         const defaults = this._mappingDefaults;
         const money = this._moneyFormat;
         const dateStyle = this._currentDateStyle();
-        if (!defaults && !money && !dateStyle)
+        if (!defaults &&
+            !money &&
+            !dateStyle &&
+            !options.temporalTypes &&
+            !options.fetchAsString &&
+            options.decimalAsString === undefined)
             return options;
         let out;
         if (defaults) {
@@ -1840,6 +1896,32 @@ export class IntlConnection extends SafeEventEmitter {
             out = out || { ...options };
             out.dateStyle = dateStyle;
         }
+        // Every path into a statement passes through here, so a selector
+        // that asks for something this does not do is refused once, at the
+        // call that carries it, rather than in whichever of the three
+        // readers of the list happens to reach it first.
+        if ((out || options).fetchAsString)
+            validateFetchAsString((out || options).fetchAsString, this.resolveTypeMap(out || options));
+        if ((out || options).decimalAsString !== undefined)
+            validateDecimalAsString((out || options).decimalAsString);
+        if ((out || options).temporalTypes) {
+            // On top of whatever type map is in effect, rather than instead of
+            // it. The map is memoized per (base, selection), so this is two
+            // lookups and not a copy.
+            const base = (out || options).typeMap || GlobalTypeMap;
+            const map = this.resolveTypeMap(out || options);
+            if (map !== base) {
+                out = out || { ...options };
+                out.typeMap = map;
+            }
+            if (!(out || options).timeZone) {
+                const tz = this._currentTimeZone();
+                if (tz) {
+                    out = out || { ...options };
+                    out.timeZone = tz;
+                }
+            }
+        }
         return out || options;
     }
     /**
@@ -1853,6 +1935,22 @@ export class IntlConnection extends SafeEventEmitter {
      * compare while nothing changes - which is always, for the ISO
      * default that needs no parsing at all.
      */
+    /**
+     * The zone `timestamptz` values are given when they decode to a
+     * Temporal.ZonedDateTime. Checked when the server's answer changes, so
+     * that a zone nothing can resolve is reported against the setting it
+     * came from instead of from inside a decode.
+     */
+    _currentTimeZone() {
+        const raw = this.socket.sessionParameters.TimeZone;
+        if (raw !== this._timeZoneRaw) {
+            this._timeZoneRaw = raw;
+            this._timeZone = raw
+                ? requireTimeZone(raw, 'the session TimeZone')
+                : undefined;
+        }
+        return this._timeZone;
+    }
     _currentDateStyle() {
         const raw = this.socket.sessionParameters.DateStyle;
         if (raw !== this._dateStyleRaw) {
@@ -1861,11 +1959,6 @@ export class IntlConnection extends SafeEventEmitter {
         }
         return this._dateStyle;
     }
-    _onError(err) {
-        if (this.socket.state !== ConnectionState.READY)
-            return;
-        this.emit('error', err);
-    }
 }
 export function getIntlConnection(connection) {
     return connection._intlCon;

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;
 }