postgrejs 3.9.0 → 3.10.0

package/data-types/classes/interval.js

@@ -14,20 +14,29 @@ function pad2(v) {
  * 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
@@ -36,25 +45,35 @@ function pad2(v) {
  * 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 class Interval {
-    years;
-    months;
-    days;
-    hours;
-    minutes;
-    /** Whole seconds; the sub-second part is in `milliseconds`. */
-    seconds;
-    /** The sub-second part, fractional down to a microsecond. */
-    milliseconds;
+    /**
+     * 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) {
-        this.years = fields?.years || 0;
-        this.months = fields?.months || 0;
-        this.days = fields?.days || 0;
-        this.hours = fields?.hours || 0;
-        this.minutes = fields?.minutes || 0;
-        this.seconds = fields?.seconds || 0;
-        this.milliseconds = fields?.milliseconds || 0;
+        if (!fields)
+            return;
+        if (fields.years)
+            this.years = fields.years;
+        if (fields.months)
+            this.months = fields.months;
+        if (fields.days)
+            this.days = fields.days;
+        if (fields.hours)
+            this.hours = fields.hours;
+        if (fields.minutes)
+            this.minutes = fields.minutes;
+        if (fields.seconds)
+            this.seconds = fields.seconds;
+        if (fields.milliseconds)
+            this.milliseconds = fields.milliseconds;
     }
     /**
      * Builds one from the three quantities the wire format carries: a signed
@@ -85,21 +104,22 @@ export class Interval {
     }
     /** The whole month count, as the wire format carries it. */
     get totalMonths() {
-        return this.years * 12 + this.months;
+        return (this.years ?? 0) * 12 + (this.months ?? 0);
     }
     /** The time part as a signed microsecond count, as the wire format carries it. */
     get totalMicroseconds() {
         // Split so that a fractional hours/minutes/seconds is folded in rather
         // than silently truncated, while whole values stay exact past what a
         // double can hold.
-        const whole = Math.trunc(this.hours) * 3600 +
-            Math.trunc(this.minutes) * 60 +
-            Math.trunc(this.seconds);
-        const fraction = (this.hours - Math.trunc(this.hours)) * 3600 +
-            (this.minutes - Math.trunc(this.minutes)) * 60 +
-            (this.seconds - Math.trunc(this.seconds));
+        const h = this.hours ?? 0;
+        const mi = this.minutes ?? 0;
+        const sec = this.seconds ?? 0;
+        const whole = Math.trunc(h) * 3600 + Math.trunc(mi) * 60 + Math.trunc(sec);
+        const fraction = (h - Math.trunc(h)) * 3600 +
+            (mi - Math.trunc(mi)) * 60 +
+            (sec - Math.trunc(sec));
         return (BigInt(whole) * US_PER_SECOND +
-            BigInt(Math.round(fraction * 1e6 + this.milliseconds * 1000)));
+            BigInt(Math.round(fraction * 1e6 + (this.milliseconds ?? 0) * 1000)));
     }
     /**
      * The interval as PostgreSQL itself prints it under the default
@@ -155,27 +175,35 @@ export class Interval {
         left -= minutes * US_PER_MINUTE;
         const seconds = left / US_PER_SECOND;
         left -= seconds * US_PER_SECOND;
+        // The sign goes on the components that have a value, not on all of
+        // them: `interval '-1 day -2 hours'` is `P0Y0M-1DT-2H0M0S`, and
+        // signing the empty ones printed `-0M-0S` - which is what `pg` does
+        // not write and no reader expects.
         const sign = negative ? '-' : '';
-        let secondsPart = sign + seconds;
+        const signed = (v) => (v ? sign : '') + v;
+        let secondsPart = (seconds || left ? sign : '') + seconds;
         if (left)
             secondsPart += '.' + String(left).padStart(6, '0').replace(/0+$/, '');
         return ('P' +
-            this.years +
+            (this.years ?? 0) +
             'Y' +
-            this.months +
+            (this.months ?? 0) +
             'M' +
-            this.days +
+            (this.days ?? 0) +
             'DT' +
-            sign +
-            hours +
+            signed(hours) +
             'H' +
-            sign +
-            minutes +
+            signed(minutes) +
             'M' +
             secondsPart +
             'S');
     }
-    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();
     }
 }

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

@@ -29,6 +29,12 @@ export declare class Numeric {
     /** The decimal exactly as PostgreSQL wrote it; casts back through `::numeric`. */
     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;
     /** The value as a double, which is lossy - that is the whole point of this class. */
     toNumber(): number;
     /**

package/data-types/classes/numeric.js

@@ -35,6 +35,14 @@ export class Numeric {
     toJSON() {
         return this.value;
     }
+    /**
+     * 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();
+    }
     /** The value as a double, which is lossy - that is the whole point of this class. */
     toNumber() {
         return parseFloat(this.value);

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

@@ -70,5 +70,10 @@ export declare class Range<T = any> {
      * `::int4range` and reads the way the same value does in psql.
      */
     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;
 }

package/data-types/classes/range.js

@@ -105,7 +105,12 @@ export class Range {
             formatBound(this.upper) +
             (this.upperInclusive && this.upper !== null ? ']' : ')'));
     }
-    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();
     }
 }

package/data-types/interval-type.js

@@ -60,7 +60,7 @@ export const IntervalType = {
     encodeBinary(buf, v) {
         const iv = toInterval(v);
         buf.writeBigInt64BE(iv.totalMicroseconds);
-        buf.writeInt32BE(iv.days);
+        buf.writeInt32BE(iv.days ?? 0);
         buf.writeInt32BE(iv.totalMonths);
     },
     decodeText: parseIntervalText,

package/data-types/money-type.js

@@ -1,5 +1,6 @@
 import { DataTypeOIDs } from '../constants.js';
 import { readBigInt64BE } from '../util/bigint-methods.js';
+import { wantsDecimalString } from '../util/decimal-as-string.js';
 import { Numeric } from './classes/numeric.js';
 import { trimTrailingZeros } from './numeric-type.js';
 /**
@@ -142,11 +143,19 @@ export const MoneyType = {
         const v = typeof buf.readBigInt64BE === 'function'
             ? buf.readBigInt64BE(offset)
             : readBigInt64BE(buf, offset);
-        return toNumberOrNumeric(moneyToString(v, formatOf(options).scale));
+        const s = moneyToString(v, formatOf(options).scale);
+        // The exact decimal is what the decode already built; handing it
+        // back is the whole of `decimalAsString`.
+        return wantsDecimalString(options, DataTypeOIDs.money)
+            ? s
+            : toNumberOrNumeric(s);
     },
     decodeText(s, options) {
         const { scale } = formatOf(options);
-        return toNumberOrNumeric(moneyToString(parseMoneyText(s), scale));
+        const exact = moneyToString(parseMoneyText(s), scale);
+        return wantsDecimalString(options, DataTypeOIDs.money)
+            ? exact
+            : toNumberOrNumeric(exact);
     },
     /**
      * Never inferred: a JavaScript number is `int4`, `float8` or `numeric`

package/data-types/numeric-type.js

@@ -1,5 +1,6 @@
 import { DataTypeOIDs } from '../constants.js';
 import { assertCoercedNumber } from '../util/assert-integer.js';
+import { wantsDecimalString } from '../util/decimal-as-string.js';
 import { fastParseFloatBuffer } from '../util/fast-parsefloat.js';
 import { Numeric } from './classes/numeric.js';
 const NUMERIC_NEG = 0x4000;
@@ -130,7 +131,7 @@ export const NumericType = {
             buf.writeInt16BE(digits[i]);
         }
     },
-    decodeBinary(v, offset = 0) {
+    decodeBinary(v, offset = 0, _len, options) {
         const len = v.readInt16BE(offset);
         const weight = v.readInt16BE(offset + 2);
         // sign is a bitmask (0x0000/0x4000/0xC000/0xD000/0xF000), not a two's
@@ -138,12 +139,16 @@ export const NumericType = {
         // values (which set the top bit) never compare equal to the constants.
         const sign = v.readUInt16BE(offset + 4);
         const scale = v.readInt16BE(offset + 6);
+        // The words PostgreSQL itself writes for these, when the caller
+        // asked for strings: a decimal string type that sometimes answers a
+        // number would have to be checked for on every value.
+        const asString = wantsDecimalString(options, DataTypeOIDs.numeric);
         if (sign === NUMERIC_NAN)
-            return NaN;
+            return asString ? 'NaN' : NaN;
         if (sign === NUMERIC_PINF)
-            return Infinity;
+            return asString ? 'Infinity' : Infinity;
         if (sign === NUMERIC_NINF)
-            return -Infinity;
+            return asString ? '-Infinity' : -Infinity;
         const digits = [];
         for (let i = 0; i < len; i++) {
             digits[i] = v.readInt16BE(offset + 8 + i * 2);
@@ -157,10 +162,13 @@ export const NumericType = {
         // and `scale` the digits after the point, which is enough to rule
         // both out. `weight === -1` is a value in [0.0001, 1), far from the
         // exponent that would make JavaScript switch notation.
-        if ((weight >= 0 && weight <= 4 && (weight + 1) * DEC_DIGITS + scale <= 15) ||
-            (weight === -1 && scale <= 15))
+        if (!asString &&
+            ((weight >= 0 &&
+                weight <= 4 &&
+                (weight + 1) * DEC_DIGITS + scale <= 15) ||
+                (weight === -1 && scale <= 15)))
             return parseFloat(numString);
-        return toNumberOrNumeric(numString);
+        return asString ? numString : toNumberOrNumeric(numString);
     },
     encodeText(v) {
         // Handed over as written. Going through a double here would undo
@@ -169,7 +177,9 @@ export const NumericType = {
         // the exponent form a JavaScript number stringifies to.
         return typeof v === 'string' ? v.trim() : String(v);
     },
-    decodeText(v) {
+    decodeText(v, options) {
+        if (wantsDecimalString(options, DataTypeOIDs.numeric))
+            return v;
         // NaN and the infinities arrive as those words and stay numbers.
         const n = parseFloat(v);
         if (!Number.isFinite(n))
@@ -180,8 +190,9 @@ export const NumericType = {
         // Eight characters hold at most eight digits, cannot reach 1e21 -
         // which needs twenty-two - and cannot reach 1e-7, which needs `0.`
         // and seven more. So a value this short is carried faithfully by
-        // definition and keeps the parser that never builds a string.
-        if (len <= 8)
+        // definition and keeps the parser that never builds a string - but
+        // only while a number is what the caller wants back.
+        if (len <= 8 && !wantsDecimalString(options, DataTypeOIDs.numeric))
             return fastParseFloatBuffer(buf, offset, len);
         return NumericType.decodeText(buf.toString('latin1', offset, offset + len), options);
     },

package/data-types/temporal-types.d.ts

@@ -0,0 +1,19 @@
+import { DataTypeMap } from '../data-type-map.js';
+import type { DataType } from '../interfaces/data-type.js';
+import type { OID } from '../types.js';
+import { type TemporalApi } from '../util/temporal.js';
+/** The five types a caller may ask for by OID. */
+export declare const TemporalCapableOIDs: readonly OID[];
+/** Every registration one selected OID stands for. */
+export declare function temporalTypesFor(oid: OID, T: TemporalApi): DataType[];
+/**
+ * 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 declare function temporalTypeMap(selection?: boolean | OID[], base?: DataTypeMap): DataTypeMap;