postgrejs 3.9.0 → 3.10.0

package/data-types/temporal-types.js

@@ -0,0 +1,520 @@
+import { DataTypeNames, DataTypeOIDs } from '../constants.js';
+import { DataTypeMap, GlobalTypeMap } from '../data-type-map.js';
+import { readBigInt64BE } from '../util/bigint-methods.js';
+import { getTemporal, systemTimeZone, } from '../util/temporal.js';
+import { DateType } from './date-type.js';
+import { IntervalType, parseIntervalText } from './interval-type.js';
+import { createMultiRangeType, createRangeType } from './range-type.js';
+import { TimeType } from './time-type.js';
+import { TimestampType } from './timestamp-type.js';
+import { TimestamptzType } from './timestamptz-type.js';
+/**
+ * PostgreSQL's date/time types decoded into `Temporal` values instead of
+ * `Date`.
+ *
+ * Three things `Date` cannot do and these can: carry the microseconds
+ * PostgreSQL actually stores (a `Date` is milliseconds, so the last three
+ * digits of every timestamp were being dropped), say that a `timestamp`
+ * has no zone at all rather than guessing one from `utcDates`, and keep
+ * a `date` a date instead of a midnight in some zone.
+ *
+ * Decoding only is opinionated: every type here still *accepts* as a
+ * parameter everything it accepted before, so turning this on does not
+ * invalidate the `Date`s and strings a caller already passes.
+ */
+const EPOCH_2000_NS = 946684800000000000n;
+const TS_INFINITY = 0x7fffffffffffffffn;
+const TS_MINUS_INFINITY = -0x8000000000000000n;
+const DATE_INFINITY = 0x7fffffff;
+const DATE_MINUS_INFINITY = -0x80000000;
+const MICROS_PER_DAY = 86400000000n;
+const MAX_SAFE_MICROS = BigInt(Number.MAX_SAFE_INTEGER);
+/** The five types a caller may ask for by OID. */
+export const TemporalCapableOIDs = Object.freeze([
+    DataTypeOIDs.date,
+    DataTypeOIDs.time,
+    DataTypeOIDs.timestamp,
+    DataTypeOIDs.timestamptz,
+    DataTypeOIDs.interval,
+]);
+function readMicros(v, offset) {
+    return typeof v.readBigInt64BE === 'function'
+        ? v.readBigInt64BE(offset)
+        : readBigInt64BE(v, offset);
+}
+/**
+ * PostgreSQL writes years before the common era as `0044-03-15 BC`;
+ * Temporal counts them astronomically, where that year is -43. Rewrites
+ * the one into the other - `-000043-03-15` - so the era is not simply
+ * refused, and the text path answers what the binary path already does.
+ */
+function withoutEra(v) {
+    const body = v.slice(0, -3);
+    const dash = body.indexOf('-');
+    const year = 1 - +body.substring(0, dash);
+    return ((year < 0 ? '-' : '+') +
+        String(Math.abs(year)).padStart(6, '0') +
+        body.substring(dash));
+}
+function zoneOf(options) {
+    return options.timeZone || systemTimeZone();
+}
+/** Guards the one thing PostgreSQL can store and Temporal cannot hold. */
+function requireMicrosecondPrecision(ns) {
+    if (ns % 1000n)
+        throw new TypeError('PostgreSQL stores microseconds, and this value carries ' +
+            'nanoseconds that would be dropped. Round it first: ' +
+            "value.round({ smallestUnit: 'microsecond' }).");
+    return ns / 1000n;
+}
+/**
+ * A `Temporal.Duration` out of the three quantities PostgreSQL keeps
+ * apart, or an error when they cannot make one.
+ *
+ * `interval '1 mon -3 days'` is an ordinary PostgreSQL value and has no
+ * Duration: Temporal refuses a duration whose fields disagree in sign,
+ * and balancing months against days needs a date to count from, which a
+ * bare interval does not have.
+ */
+function toDuration(T, months, days, micros) {
+    const signs = [
+        Math.sign(months),
+        Math.sign(days),
+        micros > 0n ? 1 : micros < 0n ? -1 : 0,
+    ];
+    let sign = 0;
+    let i;
+    for (i = 0; i < 3; i++) {
+        if (!signs[i])
+            continue;
+        if (!sign)
+            sign = signs[i];
+        else if (signs[i] !== sign)
+            throw new TypeError(`The interval ${months} mons ${days} days ${micros} us mixes ` +
+                'signs, and Temporal.Duration allows only one sign for all of ' +
+                'its fields. Leave `interval` out of `temporalTypes` for a ' +
+                'column that holds values like this one.');
+    }
+    if (micros > MAX_SAFE_MICROS || micros < -MAX_SAFE_MICROS)
+        throw new RangeError(`An interval of ${micros} microseconds is past what a ` +
+            'Temporal.Duration field can hold.');
+    // The time part is spread over hours/minutes/seconds rather than left
+    // as one microsecond count: a Duration never balances itself, so
+    // `interval '3 hours'` would answer 0 hours and 10800 seconds. Days
+    // and months are the two PostgreSQL keeps apart on purpose and are
+    // left exactly as they came.
+    const abs = micros < 0n ? -micros : micros;
+    const s = micros < 0n ? -1 : 1;
+    return T.Duration.from({
+        months,
+        days,
+        hours: Number(abs / 3600000000n) * s,
+        minutes: Number((abs / 60000000n) % 60n) * s,
+        seconds: Number((abs / 1000000n) % 60n) * s,
+        microseconds: Number(abs % 1000000n) * s,
+    });
+}
+/**
+ * The `Date` an existing decoder produced, as the Temporal value this
+ * type answers with. Only for the shapes the fast paths below hand back:
+ * `infinity` stays the number it already was, and an unreadable date -
+ * a zone abbreviation under a non-ISO DateStyle, which names no offset -
+ * is an error rather than an `Invalid Date` nobody can use.
+ */
+function checkDate(v, str) {
+    if (typeof v === 'number')
+        return v;
+    if (Number.isNaN(v.getTime()))
+        throw new Error(`"${str}" could not be read as a date - see DataMappingOptions.dateStyle.`);
+    return v;
+}
+function temporalTimestamptzType(T) {
+    const decodeText = (v, options) => {
+        // ISO is the default DateStyle and is Instant's own shape once the
+        // space between date and time is allowed for, which it is.
+        if (!options.dateStyle) {
+            const c = v.charCodeAt(0);
+            if (c >= 0x30 && c <= 0x39)
+                return T.Instant.from(v.endsWith(' BC') ? withoutEra(v) : v).toZonedDateTimeISO(zoneOf(options));
+        }
+        const d = checkDate(TimestamptzType.decodeText(v, options), v);
+        // A styled rendering carries milliseconds at best, so nothing is
+        // lost by going through the Date the existing parser built.
+        return typeof d === 'number'
+            ? d
+            : T.Instant.fromEpochMilliseconds(d.getTime()).toZonedDateTimeISO(zoneOf(options));
+    };
+    return {
+        name: 'timestamptz',
+        oid: DataTypeOIDs.timestamptz,
+        jsType: 'Temporal.ZonedDateTime',
+        decodeBinary(v, offset = 0, _len, options) {
+            const micros = readMicros(v, offset);
+            if (micros === TS_INFINITY)
+                return Infinity;
+            if (micros === TS_MINUS_INFINITY)
+                return -Infinity;
+            return T.Instant.fromEpochNanoseconds(EPOCH_2000_NS + micros * 1000n).toZonedDateTimeISO(zoneOf(options));
+        },
+        decodeText,
+        decodeTextBuffer(buf, offset, len, options) {
+            return decodeText(buf.toString('latin1', offset, offset + len), options);
+        },
+        encodeBinary(buf, v, options) {
+            if (v instanceof T.ZonedDateTime || v instanceof T.Instant) {
+                buf.writeBigInt64BE(requireMicrosecondPrecision(v.epochNanoseconds - EPOCH_2000_NS));
+                return;
+            }
+            TimestamptzType.encodeBinary(buf, v, options);
+        },
+        encodeText(v, options) {
+            // Without the [zone] suffix, which PostgreSQL does not read - the
+            // offset in front of it is what carries the instant anyway.
+            if (v instanceof T.ZonedDateTime)
+                return v.toString({ timeZoneName: 'never' });
+            if (v instanceof T.Instant)
+                return v.toString();
+            return TimestamptzType.encodeText(v, options);
+        },
+        isType(v) {
+            return (v instanceof T.ZonedDateTime ||
+                v instanceof T.Instant ||
+                TimestamptzType.isType(v));
+        },
+    };
+}
+function temporalTimestampType(T) {
+    const fromDate = (d, options) => options.utcDates
+        ? T.PlainDateTime.from({
+            year: d.getUTCFullYear(),
+            month: d.getUTCMonth() + 1,
+            day: d.getUTCDate(),
+            hour: d.getUTCHours(),
+            minute: d.getUTCMinutes(),
+            second: d.getUTCSeconds(),
+            millisecond: d.getUTCMilliseconds(),
+        })
+        : T.PlainDateTime.from({
+            year: d.getFullYear(),
+            month: d.getMonth() + 1,
+            day: d.getDate(),
+            hour: d.getHours(),
+            minute: d.getMinutes(),
+            second: d.getSeconds(),
+            millisecond: d.getMilliseconds(),
+        });
+    const decodeText = (v, options) => {
+        if (!options.dateStyle) {
+            const c = v.charCodeAt(0);
+            if (c >= 0x30 && c <= 0x39)
+                return T.PlainDateTime.from(v.endsWith(' BC') ? withoutEra(v) : v);
+        }
+        const d = checkDate(TimestampType.decodeText(v, options), v);
+        return typeof d === 'number' ? d : fromDate(d, options);
+    };
+    return {
+        name: 'timestamp',
+        oid: DataTypeOIDs.timestamp,
+        jsType: 'Temporal.PlainDateTime',
+        decodeBinary(v, offset = 0) {
+            const micros = readMicros(v, offset);
+            if (micros === TS_INFINITY)
+                return Infinity;
+            if (micros === TS_MINUS_INFINITY)
+                return -Infinity;
+            // A timestamp carries no zone, so it is read in UTC and the zone
+            // dropped again - `utcDates` has nothing left to decide here.
+            return T.Instant.fromEpochNanoseconds(EPOCH_2000_NS + micros * 1000n)
+                .toZonedDateTimeISO('UTC')
+                .toPlainDateTime();
+        },
+        decodeText,
+        decodeTextBuffer(buf, offset, len, options) {
+            return decodeText(buf.toString('latin1', offset, offset + len), options);
+        },
+        encodeBinary(buf, v, options) {
+            if (v instanceof T.PlainDateTime) {
+                buf.writeBigInt64BE(requireMicrosecondPrecision(v.toZonedDateTime('UTC').epochNanoseconds - EPOCH_2000_NS));
+                return;
+            }
+            TimestampType.encodeBinary(buf, v, options);
+        },
+        encodeText(v, options) {
+            if (v instanceof T.PlainDateTime)
+                return v.toString();
+            return TimestampType.encodeText(v, options);
+        },
+        isType(v) {
+            return v instanceof T.PlainDateTime || TimestampType.isType(v);
+        },
+    };
+}
+function temporalDateType(T) {
+    const EPOCH_2000 = T.PlainDate.from('2000-01-01');
+    const decodeText = (v, options) => {
+        if (!options.dateStyle) {
+            const c = v.charCodeAt(0);
+            if (c >= 0x30 && c <= 0x39)
+                return T.PlainDate.from(v.endsWith(' BC') ? withoutEra(v) : v);
+        }
+        const d = checkDate(DateType.decodeText(v, options), v);
+        if (typeof d === 'number')
+            return d;
+        return options.utcDates
+            ? T.PlainDate.from({
+                year: d.getUTCFullYear(),
+                month: d.getUTCMonth() + 1,
+                day: d.getUTCDate(),
+            })
+            : T.PlainDate.from({
+                year: d.getFullYear(),
+                month: d.getMonth() + 1,
+                day: d.getDate(),
+            });
+    };
+    return {
+        name: 'date',
+        oid: DataTypeOIDs.date,
+        jsType: 'Temporal.PlainDate',
+        decodeBinary(v, offset = 0) {
+            const days = v.readInt32BE(offset);
+            if (days === DATE_INFINITY)
+                return Infinity;
+            if (days === DATE_MINUS_INFINITY)
+                return -Infinity;
+            return EPOCH_2000.add({ days });
+        },
+        decodeText,
+        decodeTextBuffer(buf, offset, len, options) {
+            return decodeText(buf.toString('latin1', offset, offset + len), options);
+        },
+        encodeBinary(buf, v, options) {
+            if (v instanceof T.PlainDate) {
+                buf.writeInt32BE(EPOCH_2000.until(v, { largestUnit: 'day' }).days);
+                return;
+            }
+            DateType.encodeBinary(buf, v, options);
+        },
+        encodeText(v, options) {
+            if (v instanceof T.PlainDate)
+                return v.toString();
+            return DateType.encodeText(v, options);
+        },
+        isType(v) {
+            return v instanceof T.PlainDate || DateType.isType(v);
+        },
+    };
+}
+function temporalTimeType(T) {
+    const MIDNIGHT = T.PlainTime.from('00:00:00');
+    // `time` is rendered the same way under every DateStyle, so there is
+    // no styled shape to fall back to here.
+    const decodeText = (v) => T.PlainTime.from(v);
+    return {
+        name: 'time',
+        oid: DataTypeOIDs.time,
+        jsType: 'Temporal.PlainTime',
+        decodeBinary(v, offset = 0) {
+            const micros = readMicros(v, offset);
+            // PostgreSQL's `time` runs to 24:00:00 inclusive; a PlainTime stops
+            // one nanosecond short of it, and adding a day's worth of
+            // microseconds to midnight would silently wrap back to 00:00:00.
+            if (micros >= MICROS_PER_DAY)
+                throw new RangeError("PostgreSQL's time '24:00:00' has no Temporal.PlainTime - it is " +
+                    'the end of the day, and a PlainTime only reaches 23:59:59.999999999.');
+            return MIDNIGHT.add({ microseconds: Number(micros) });
+        },
+        decodeText,
+        decodeTextBuffer(buf, offset, len) {
+            return decodeText(buf.toString('latin1', offset, offset + len));
+        },
+        encodeBinary(buf, v, options) {
+            if (v instanceof T.PlainTime) {
+                const d = MIDNIGHT.until(v, { largestUnit: 'microsecond' });
+                if (d.nanoseconds)
+                    requireMicrosecondPrecision(BigInt(d.nanoseconds));
+                buf.writeBigInt64BE(BigInt(d.microseconds));
+                return;
+            }
+            TimeType.encodeBinary(buf, v, options);
+        },
+        encodeText(v, options) {
+            if (v instanceof T.PlainTime)
+                return v.toString();
+            return TimeType.encodeText(v, options);
+        },
+        isType(v) {
+            return v instanceof T.PlainTime || TimeType.isType(v);
+        },
+    };
+}
+function temporalIntervalType(T) {
+    return {
+        name: 'interval',
+        oid: DataTypeOIDs.interval,
+        jsType: 'Temporal.Duration',
+        decodeBinary(v, offset = 0) {
+            return toDuration(T, v.readInt32BE(offset + 12), v.readInt32BE(offset + 8), readMicros(v, offset));
+        },
+        decodeText(v) {
+            const iv = parseIntervalText(v);
+            return toDuration(T, iv.totalMonths, iv.days ?? 0, iv.totalMicroseconds);
+        },
+        encodeBinary(buf, v, options) {
+            if (!(v instanceof T.Duration)) {
+                IntervalType.encodeBinary(buf, v, options);
+                return;
+            }
+            buf.writeBigInt64BE(durationMicros(v));
+            buf.writeInt32BE(v.days + v.weeks * 7);
+            buf.writeInt32BE(v.years * 12 + v.months);
+        },
+        encodeText(v, options) {
+            // A Duration prints ISO 8601, which PostgreSQL reads whatever its
+            // IntervalStyle is set to.
+            if (v instanceof T.Duration)
+                return v.toString();
+            return IntervalType.encodeText(v, options);
+        },
+        isType(v) {
+            return v instanceof T.Duration || IntervalType.isType(v);
+        },
+    };
+}
+/** A Duration's time part, in the microseconds the wire carries. */
+function durationMicros(d) {
+    if (d.nanoseconds % 1000)
+        requireMicrosecondPrecision(BigInt(d.nanoseconds));
+    return (BigInt(d.hours) * 3600000000n +
+        BigInt(d.minutes) * 60000000n +
+        BigInt(d.seconds) * 1000000n +
+        BigInt(d.milliseconds) * 1000n +
+        BigInt(d.microseconds) +
+        BigInt(d.nanoseconds / 1000));
+}
+const FAMILIES = {
+    [DataTypeOIDs.date]: {
+        build: temporalDateType,
+        arrayOid: DataTypeOIDs._date,
+        range: {
+            name: 'daterange',
+            oid: DataTypeOIDs.daterange,
+            arrayOid: DataTypeOIDs._daterange,
+            multiOid: DataTypeOIDs.datemultirange,
+            multiArrayOid: DataTypeOIDs._datemultirange,
+        },
+    },
+    [DataTypeOIDs.time]: {
+        build: temporalTimeType,
+        arrayOid: DataTypeOIDs._time,
+    },
+    [DataTypeOIDs.timestamp]: {
+        build: temporalTimestampType,
+        arrayOid: DataTypeOIDs._timestamp,
+        range: {
+            name: 'tsrange',
+            oid: DataTypeOIDs.tsrange,
+            arrayOid: DataTypeOIDs._tsrange,
+            multiOid: DataTypeOIDs.tsmultirange,
+            multiArrayOid: DataTypeOIDs._tsmultirange,
+        },
+    },
+    [DataTypeOIDs.timestamptz]: {
+        build: temporalTimestamptzType,
+        arrayOid: DataTypeOIDs._timestamptz,
+        range: {
+            name: 'tstzrange',
+            oid: DataTypeOIDs.tstzrange,
+            arrayOid: DataTypeOIDs._tstzrange,
+            multiOid: DataTypeOIDs.tstzmultirange,
+            multiArrayOid: DataTypeOIDs._tstzmultirange,
+        },
+    },
+    [DataTypeOIDs.interval]: {
+        build: temporalIntervalType,
+        arrayOid: DataTypeOIDs._interval,
+    },
+};
+/** Every registration one selected OID stands for. */
+export function temporalTypesFor(oid, T) {
+    const spec = FAMILIES[oid];
+    const scalar = spec.build(T);
+    const out = [
+        scalar,
+        {
+            ...scalar,
+            name: '_' + scalar.name,
+            oid: spec.arrayOid,
+            elementsOID: scalar.oid,
+        },
+    ];
+    const r = spec.range;
+    if (r) {
+        const multiName = r.name.replace('range', 'multirange');
+        const range = createRangeType(r.name, r.oid, scalar);
+        const multi = createMultiRangeType(multiName, r.multiOid, range);
+        out.push(range, { ...range, name: '_' + r.name, oid: r.arrayOid, elementsOID: r.oid }, multi, {
+            ...multi,
+            name: '_' + multiName,
+            oid: r.multiArrayOid,
+            elementsOID: r.multiOid,
+        });
+    }
+    return out;
+}
+function normalizeSelection(selection) {
+    if (selection === true)
+        return TemporalCapableOIDs.slice();
+    if (selection === false)
+        return [];
+    if (!Array.isArray(selection))
+        throw new TypeError('`temporalTypes` is either a boolean or an array of OIDs, not ' +
+            typeof selection);
+    const out = [];
+    const l = selection.length;
+    let i;
+    let oid;
+    for (i = 0; i < l; i++) {
+        oid = selection[i];
+        if (!TemporalCapableOIDs.includes(oid))
+            throw new TypeError('`temporalTypes` accepts only date (1082), time (1083), timestamp ' +
+                '(1114), timestamptz (1184) and interval (1186). Received ' +
+                `${oid}${DataTypeNames[oid] ? ' (' + DataTypeNames[oid] + ')' : ''}.`);
+        if (!out.includes(oid))
+            out.push(oid);
+    }
+    return out.sort((a, b) => a - b);
+}
+const _derived = new WeakMap();
+/**
+ * A type map that decodes the selected date/time types into `Temporal`
+ * values, built on top of `base` - which keeps whatever else the caller
+ * registered there.
+ *
+ * The same selection on the same base always gives back the same map.
+ * That is not only to save the copy: a prepared statement is reused only
+ * while the map it was parsed with is the same object, so handing out a
+ * fresh map per statement would quietly empty the statement cache.
+ */
+export function temporalTypeMap(selection = true, base = GlobalTypeMap) {
+    const oids = normalizeSelection(selection);
+    if (!oids.length)
+        return base;
+    const key = oids.join(',');
+    let forBase = _derived.get(base);
+    if (!forBase) {
+        forBase = new Map();
+        _derived.set(base, forBase);
+    }
+    let map = forBase.get(key);
+    if (!map) {
+        const T = getTemporal();
+        map = new DataTypeMap(base);
+        const l = oids.length;
+        let i;
+        for (i = 0; i < l; i++)
+            map.register(temporalTypesFor(oids[i], T));
+        forBase.set(key, map);
+    }
+    return map;
+}

package/index.d.ts

@@ -12,6 +12,7 @@ export * from './data-types/classes/geometric.js';
 export * from './data-types/classes/interval.js';
 export * from './data-types/classes/numeric.js';
 export * from './data-types/classes/range.js';
+export * from './data-types/temporal-types.js';
 export * from './interfaces/batch-result.js';
 export * from './interfaces/command-result.js';
 export * from './interfaces/copy-from-rows-options.js';
@@ -33,6 +34,7 @@ export * from './protocol/database-error.js';
 export * from './protocol/smart-buffer.js';
 export * from './types.js';
 export * from './util/connection-config.js';
+export * from './util/decimal-as-string.js';
 export * from './util/escape-identifier.js';
 export * from './util/escape-literal.js';
 export * from './util/parse-datetime.js';

package/index.js

@@ -12,6 +12,7 @@ export * from './data-types/classes/geometric.js';
 export * from './data-types/classes/interval.js';
 export * from './data-types/classes/numeric.js';
 export * from './data-types/classes/range.js';
+export * from './data-types/temporal-types.js';
 export * from './interfaces/batch-result.js';
 export * from './interfaces/command-result.js';
 export * from './interfaces/copy-from-rows-options.js';
@@ -33,6 +34,7 @@ export * from './protocol/database-error.js';
 export * from './protocol/smart-buffer.js';
 export * from './types.js';
 export * from './util/connection-config.js';
+export * from './util/decimal-as-string.js';
 export * from './util/escape-identifier.js';
 export * from './util/escape-literal.js';
 export * from './util/parse-datetime.js';

package/interfaces/data-mapping-options.d.ts

@@ -7,7 +7,99 @@ export interface MoneyFormat {
     /** The decimal separator the server prints, `.` or `,`. */
     decimalSeparator: string;
 }
+/**
+ * One entry of `fetchAsString`: an OID on its own, or an OID with what
+ * it should reach.
+ */
+export type FetchAsStringItem = OID | FetchAsStringSelector;
+/** An OID named by `fetchAsString`, with what it reaches. */
+export interface FetchAsStringSelector {
+    oid: OID;
+    /**
+     * Whether naming a scalar type also asks for columns of *arrays* of
+     * it - which is what naming it on its own does, so this defaults to
+     * `true`.
+     *
+     * `false` is for reproducing something that is inconsistent on the
+     * other side: `pg` hands back a scalar `numeric` as a string and a
+     * `numeric[]` as numbers, and a `numeric[]` column already decodes
+     * that way here, so only the scalar wants asking for as text.
+     */
+    arrays?: boolean;
+    /**
+     * Reserved. An element OID does not reach range columns today - a
+     * `numrange` column is selected by naming `numrange` - so `false` is
+     * the only value this can be given, and `true` is refused rather than
+     * ignored.
+     */
+    ranges?: boolean;
+}
 export interface DataMappingOptions {
+    /**
+     * Decode `numeric` and `money` into the exact decimal string they
+     * carry, instead of a number.
+     *
+     * `true` takes both; an array takes only the ones it names, and may
+     * name only those two (`DecimalAsStringOIDs`). Their array, range and
+     * multirange types follow, since those decode through the element.
+     *
+     * The string is the value and nothing else: an optional leading `-`,
+     * the digits, and - for money - a decimal point with exactly the scale
+     * the server reported. No currency symbol, no thousands separator, no
+     * locale. That is what tells it apart from
+     * `fetchAsString: [DataTypeOIDs.money]`, which asks the *server* for
+     * its own rendering and gets `-$1,234.50` back, because `lc_monetary`
+     * is what writes a money value out.
+     *
+     * There is no conversion behind this: both types build the exact
+     * decimal while decoding and then decide whether a double can carry it
+     * (a `Numeric` when it cannot). This hands back that same string, so
+     * nothing is rounded, re-parsed or formatted a second time - which is
+     * the thing a caller doing it themselves cannot avoid, and cannot get
+     * right for money without knowing the scale.
+     *
+     * `numeric`'s non-finite values keep the spelling PostgreSQL writes:
+     * `'NaN'`, `'Infinity'`, `'-Infinity'`.
+     *
+     * Off by default.
+     */
+    decimalAsString?: boolean | OID[];
+    /**
+     * Decode PostgreSQL's date/time types into `Temporal` values instead
+     * of `Date`.
+     *
+     * `true` takes all five - `date`, `time`, `timestamp`, `timestamptz`
+     * and `interval`; an array takes only the ones it names, and may name
+     * only those five (`DataTypeOIDs.timestamptz`, and so on - see
+     * `TemporalCapableOIDs`). Each one selected brings its own array and
+     * range types with it, because those carry a copy of the element's
+     * decoders rather than following it.
+     *
+     * This is decoding only: every type still accepts as a *parameter*
+     * everything it accepted before, so the `Date`s and strings already
+     * being passed keep working.
+     *
+     * What it buys: the microseconds PostgreSQL stores and a `Date` cannot
+     * hold, a `timestamp` that says it has no zone instead of guessing one
+     * from `utcDates`, and a `date` that stays a date. What it costs: no
+     * runtime ships `Temporal` yet, so an application turning this on
+     * installs a polyfill (`temporal-polyfill`) and imports it before
+     * connecting; building these values is also dearer than `new Date`.
+     *
+     * Off by default.
+     */
+    temporalTypes?: boolean | OID[];
+    /**
+     * The time zone a `timestamptz` is given when it is decoded as a
+     * `Temporal.ZonedDateTime` - see `temporalTypes`.
+     *
+     * A connection fills this in from the `TimeZone` the server reports,
+     * so a caller normally never sets it; set it to print those values in
+     * a zone of your own choosing. It decides only what wall clock the
+     * value shows: a timestamptz is an absolute instant and is the same
+     * moment in every zone.
+     */
+    timeZone?: string;
     /**
      * How the server renders dates, when it is not rendering them in ISO.
      *
@@ -44,11 +136,14 @@ export interface DataMappingOptions {
      * a query whose statement is not prepared asks for the whole row as text
      * instead (see IntlConnection.queryOnce()).
      *
-     * An array column is selected by its own array OID (`_timestamptz`),
-     * never by its element's, and then the whole array literal is the string
-     * that comes back.
+     * An array column can be named either way, and the two ask for
+     * different things. Its own array OID (`_timestamptz`) asks for the
+     * whole literal, one string. Its *element's* OID (`timestamptz`) asks
+     * for the elements: an array, of the strings the server wrote, with
+     * the nulls still null - the same thing naming that OID does for a
+     * column of one.
      */
-    fetchAsString?: OID[];
+    fetchAsString?: FetchAsStringItem[];
     /**
      * Ask the server for text on any column this client has no way to
      * decode, instead of taking bytes it cannot read.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {