postgrejs 3.6.0 → 3.7.0

package/data-types/classes/geometric.js

@@ -0,0 +1,197 @@
+/**
+ * Whether a value is a bare object literal rather than an instance of
+ * some class.
+ *
+ * The geometric types accept both - a Point, and the `{x, y}` that was
+ * the only thing they returned before these classes existed - but a
+ * BoxType must not claim a LineSegment just because it carries the same
+ * four numbers, so the shape check is limited to plain objects.
+ */
+function isPlainObject(v) {
+    return (v !== null &&
+        typeof v === 'object' &&
+        Object.getPrototypeOf(v) === Object.prototype);
+}
+function isNum(v) {
+    return typeof v === 'number';
+}
+/** A `point`: one position. */
+export class Point {
+    x;
+    y;
+    constructor(x = 0, y = 0) {
+        this.x = x;
+        this.y = y;
+    }
+    /** As PostgreSQL prints it, so it casts back through `::point`. */
+    toString() {
+        return `(${this.x},${this.y})`;
+    }
+    toJSON() {
+        return this.toString();
+    }
+    /* c8 ignore next 3 */
+    static isPointLike(v) {
+        return (isPlainObject(v) &&
+            Object.keys(v).length === 2 &&
+            isNum(v.x) &&
+            isNum(v.y));
+    }
+}
+/** A `circle`: a centre and a radius. */
+export class Circle {
+    x;
+    y;
+    r;
+    constructor(x = 0, y = 0, r = 0) {
+        this.x = x;
+        this.y = y;
+        this.r = r;
+    }
+    /** As PostgreSQL prints it, so it casts back through `::circle`. */
+    toString() {
+        return `<(${this.x},${this.y}),${this.r}>`;
+    }
+    toJSON() {
+        return this.toString();
+    }
+    static isCircleLike(v) {
+        return (isPlainObject(v) &&
+            Object.keys(v).length === 3 &&
+            isNum(v.x) &&
+            isNum(v.y) &&
+            isNum(v.r));
+    }
+}
+/**
+ * Two corners, which is how both `box` and `lseg` are carried - and why
+ * they are two classes rather than one shared shape. They were
+ * indistinguishable as plain objects: both types' isType() accepted
+ * `{x1, y1, x2, y2}`, so `determine()` answered `box` for every one of
+ * them and an lseg parameter could not be expressed at all.
+ */
+class TwoPoints {
+    x1;
+    y1;
+    x2;
+    y2;
+    constructor(x1 = 0, y1 = 0, x2 = 0, y2 = 0) {
+        this.x1 = x1;
+        this.y1 = y1;
+        this.x2 = x2;
+        this.y2 = y2;
+    }
+    toJSON() {
+        return this.toString();
+    }
+    static isTwoPointsLike(v) {
+        return (isPlainObject(v) &&
+            Object.keys(v).length === 4 &&
+            isNum(v.x1) &&
+            isNum(v.y1) &&
+            isNum(v.x2) &&
+            isNum(v.y2));
+    }
+}
+/** A `box`: a rectangle given by two opposite corners. */
+export class Box extends TwoPoints {
+    /** As PostgreSQL prints it, so it casts back through `::box`. */
+    toString() {
+        return `(${this.x1},${this.y1}),(${this.x2},${this.y2})`;
+    }
+}
+/** An `lseg`: the straight line between two points. */
+export class LineSegment extends TwoPoints {
+    /** As PostgreSQL prints it, so it casts back through `::lseg`. */
+    toString() {
+        return `[(${this.x1},${this.y1}),(${this.x2},${this.y2})]`;
+    }
+}
+/**
+ * A `line`: the infinite line Ax + By + C = 0.
+ *
+ * PostgreSQL stores and prints the three coefficients whatever form the
+ * literal took - `line '((0,0),(1,1))'` comes back as `{1,-1,0}` - so
+ * that is what this carries. A pair of points would be a second, lossy
+ * spelling of the same thing, since a line through them is not the
+ * points.
+ */
+export class Line {
+    a;
+    b;
+    c;
+    constructor(a = 0, b = 0, c = 0) {
+        this.a = a;
+        this.b = b;
+        this.c = c;
+    }
+    /** As PostgreSQL prints it, so it casts back through `::line`. */
+    toString() {
+        return `{${this.a},${this.b},${this.c}}`;
+    }
+    toJSON() {
+        return this.toString();
+    }
+    static isLineLike(v) {
+        return (isPlainObject(v) &&
+            Object.keys(v).length === 3 &&
+            isNum(v.a) &&
+            isNum(v.b) &&
+            isNum(v.c));
+    }
+}
+/**
+ * The list of points `path` and `polygon` share. They are two classes
+ * rather than one for the same reason `Box` and `LineSegment` are: the
+ * values are indistinguishable by shape, so only the class can say which
+ * type a parameter is meant for.
+ */
+class PointList {
+    points;
+    /** Plain `{x, y}` objects are accepted and kept as Points. */
+    constructor(points = []) {
+        this.points = points.map(p => p instanceof Point ? p : new Point(p.x, p.y));
+    }
+    toJSON() {
+        return this.toString();
+    }
+    join() {
+        let out = '';
+        const l = this.points.length;
+        let i;
+        for (i = 0; i < l; i++) {
+            if (i)
+                out += ',';
+            out += this.points[i].toString();
+        }
+        return out;
+    }
+}
+/**
+ * A `path`: a series of points, open or closed.
+ *
+ * Closed is the default because it is PostgreSQL's - a literal written
+ * without brackets, `path '1,2,3,4'`, comes back closed. The flag is
+ * part of the value and not a formatting choice: the server stores it
+ * and prints `[...]` for an open path against `(...)` for a closed one.
+ */
+export class Path extends PointList {
+    isClosed;
+    constructor(points = [], isClosed = true) {
+        super(points);
+        this.isClosed = isClosed;
+    }
+    /** As PostgreSQL prints it, so it casts back through `::path`. */
+    toString() {
+        const inner = this.join();
+        return this.isClosed ? `(${inner})` : `[${inner}]`;
+    }
+}
+/** A `polygon`: a closed series of points. */
+export class Polygon extends PointList {
+    /** As PostgreSQL prints it, so it casts back through `::polygon`. */
+    toString() {
+        return `(${this.join()})`;
+    }
+}
+export { PointList, TwoPoints };

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

@@ -0,0 +1,73 @@
+/** The fields an Interval is built from. All optional, all defaulting to 0. */
+export interface IntervalFields {
+    years?: number;
+    months?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+/**
+ * PostgreSQL's `interval`, as the three independent quantities it actually
+ * is: a number of months, a number of days, and a time.
+ *
+ * They are kept apart rather than reduced to one total because they are
+ * not convertible - a month is 28 to 31 days and a day is 23 to 25 hours
+ * across a DST boundary, so only the server, holding a calendar and a time
+ * 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:
+ *
+ * ```ts
+ * const iv = new Interval({ days: 1, hours: 2 });
+ * iv.minutes;          // 0, not 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]`.
+ *
+ * `milliseconds` carries the sub-second part and can be fractional, since
+ * PostgreSQL stores microseconds: `interval '0.000001 seconds'` is
+ * `milliseconds: 0.001`. Also `pg`'s behaviour, kept for the same reason.
+ *
+ * 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 }`.
+ */
+export declare class Interval implements IntervalFields {
+    years: number;
+    months: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    /** Whole seconds; the sub-second part is in `milliseconds`. */
+    seconds: number;
+    /** The sub-second part, fractional down to a microsecond. */
+    milliseconds: number;
+    constructor(fields?: IntervalFields);
+    /**
+     * Builds one from the three quantities the wire format carries: a signed
+     * microsecond count for the time, and day and month counts of their own.
+     */
+    static fromParts(microseconds: bigint, days: number, months: number): Interval;
+    /** The whole month count, as the wire format carries it. */
+    get totalMonths(): number;
+    /** The time part as a signed microsecond count, as the wire format carries it. */
+    get totalMicroseconds(): bigint;
+    /**
+     * The interval as PostgreSQL itself prints it under the default
+     * `IntervalStyle`, so it round-trips through an `::interval` cast and
+     * reads the way the same value does in psql.
+     */
+    toString(): string;
+    /** The interval as an ISO 8601 duration. */
+    toISOString(): string;
+    toJSON(): string;
+}

package/data-types/classes/interval.js

@@ -0,0 +1,181 @@
+const US_PER_SECOND = 1000000n;
+const US_PER_MINUTE = 60n * US_PER_SECOND;
+const US_PER_HOUR = 60n * US_PER_MINUTE;
+function pad2(v) {
+    return v < 10 ? '0' + v : '' + v;
+}
+/**
+ * PostgreSQL's `interval`, as the three independent quantities it actually
+ * is: a number of months, a number of days, and a time.
+ *
+ * They are kept apart rather than reduced to one total because they are
+ * not convertible - a month is 28 to 31 days and a day is 23 to 25 hours
+ * across a DST boundary, so only the server, holding a calendar and a time
+ * 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:
+ *
+ * ```ts
+ * const iv = new Interval({ days: 1, hours: 2 });
+ * iv.minutes;          // 0, not 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]`.
+ *
+ * `milliseconds` carries the sub-second part and can be fractional, since
+ * PostgreSQL stores microseconds: `interval '0.000001 seconds'` is
+ * `milliseconds: 0.001`. Also `pg`'s behaviour, kept for the same reason.
+ *
+ * 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 }`.
+ */
+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;
+    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;
+    }
+    /**
+     * Builds one from the three quantities the wire format carries: a signed
+     * microsecond count for the time, and day and month counts of their own.
+     */
+    static fromParts(microseconds, days, months) {
+        const negative = microseconds < 0n;
+        let left = negative ? -microseconds : microseconds;
+        const hours = left / US_PER_HOUR;
+        left -= hours * US_PER_HOUR;
+        const minutes = left / US_PER_MINUTE;
+        left -= minutes * US_PER_MINUTE;
+        const seconds = left / US_PER_SECOND;
+        left -= seconds * US_PER_SECOND;
+        const sign = negative ? -1 : 1;
+        return new Interval({
+            // Months are stored as one count and printed as years plus months,
+            // so 13 comes back as a year and a month - which is what the server
+            // does with `interval '13 mons'`.
+            years: Math.trunc(months / 12),
+            months: months % 12,
+            days,
+            hours: sign * Number(hours),
+            minutes: sign * Number(minutes),
+            seconds: sign * Number(seconds),
+            milliseconds: (sign * Number(left)) / 1000,
+        });
+    }
+    /** The whole month count, as the wire format carries it. */
+    get totalMonths() {
+        return this.years * 12 + this.months;
+    }
+    /** 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));
+        return (BigInt(whole) * US_PER_SECOND +
+            BigInt(Math.round(fraction * 1e6 + this.milliseconds * 1000)));
+    }
+    /**
+     * The interval as PostgreSQL itself prints it under the default
+     * `IntervalStyle`, so it round-trips through an `::interval` cast and
+     * reads the way the same value does in psql.
+     */
+    toString() {
+        const out = [];
+        const { years, months, days } = this;
+        // Singular only for exactly 1 - the server prints `-1 days`, not
+        // `-1 day`.
+        if (years)
+            out.push(years + (years === 1 ? ' year' : ' years'));
+        if (months)
+            out.push(months + (months === 1 ? ' mon' : ' mons'));
+        if (days)
+            out.push(days + (days === 1 ? ' day' : ' days'));
+        const us = this.totalMicroseconds;
+        // The time is printed when it has a value, and also when nothing else
+        // does - a zero interval is `00:00:00` rather than an empty string.
+        if (us || !out.length) {
+            const negative = us < 0n;
+            let left = negative ? -us : us;
+            const hours = left / US_PER_HOUR;
+            left -= hours * US_PER_HOUR;
+            const minutes = left / US_PER_MINUTE;
+            left -= minutes * US_PER_MINUTE;
+            const seconds = left / US_PER_SECOND;
+            left -= seconds * US_PER_SECOND;
+            let time = (negative ? '-' : '') +
+                // Hours are not bounded at 24 and are padded only up to two
+                // digits: `100000:00:00` is what the server prints.
+                pad2(Number(hours)) +
+                ':' +
+                pad2(Number(minutes)) +
+                ':' +
+                pad2(Number(seconds));
+            if (left) {
+                time += '.' + String(left).padStart(6, '0').replace(/0+$/, '');
+            }
+            out.push(time);
+        }
+        return out.join(' ');
+    }
+    /** The interval as an ISO 8601 duration. */
+    toISOString() {
+        const us = this.totalMicroseconds;
+        const negative = us < 0n;
+        let left = negative ? -us : us;
+        const hours = left / US_PER_HOUR;
+        left -= hours * US_PER_HOUR;
+        const minutes = left / US_PER_MINUTE;
+        left -= minutes * US_PER_MINUTE;
+        const seconds = left / US_PER_SECOND;
+        left -= seconds * US_PER_SECOND;
+        const sign = negative ? '-' : '';
+        let secondsPart = sign + seconds;
+        if (left)
+            secondsPart += '.' + String(left).padStart(6, '0').replace(/0+$/, '');
+        return ('P' +
+            this.years +
+            'Y' +
+            this.months +
+            'M' +
+            this.days +
+            'DT' +
+            sign +
+            hours +
+            'H' +
+            sign +
+            minutes +
+            'M' +
+            secondsPart +
+            'S');
+    }
+    toJSON() {
+        return this.toString();
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * The exact decimal a `numeric` column holds, for the values a
+ * JavaScript number cannot carry.
+ *
+ * `numeric` exists precisely to hold numbers a double cannot - more than
+ * about fifteen significant digits, or a magnitude past what prints in
+ * plain notation - so decoding one into a double throws away the reason
+ * the column was declared that way. A value that does fit still decodes
+ * to a plain number; this class is what the rest become, and it carries
+ * the digits exactly as the server wrote them.
+ *
+ * It is a class rather than a bare string so that it can be told apart:
+ * `determine()` types a bare string as `varchar`, which the server then
+ * refuses to put in a numeric column, so a string could be read but not
+ * written back. A `Numeric` round-trips.
+ *
+ * There is deliberately no `valueOf()`. Arithmetic on one of these has
+ * to be an explicit decision - `Symbol.toPrimitive` hands back the exact
+ * text for every hint, so `String(n)` and `${n}` are lossless, and
+ * `toNumber()` is the way to ask for the double and say so.
+ */
+export declare class Numeric {
+    readonly value: string;
+    constructor(value: string | number | bigint);
+    /** The decimal exactly as PostgreSQL wrote it; casts back through `::numeric`. */
+    toString(): string;
+    toJSON(): string;
+    /** The value as a double, which is lossy - that is the whole point of this class. */
+    toNumber(): number;
+    /**
+     * The text for every hint, the numeric one included: coercing to a
+     * double behind the caller's back is the loss this class exists to
+     * prevent, so `n * 2` has to go through the string and `n + 1`
+     * concatenates rather than quietly rounding.
+     */
+    [Symbol.toPrimitive](): string;
+}

package/data-types/classes/numeric.js

@@ -0,0 +1,47 @@
+/**
+ * The exact decimal a `numeric` column holds, for the values a
+ * JavaScript number cannot carry.
+ *
+ * `numeric` exists precisely to hold numbers a double cannot - more than
+ * about fifteen significant digits, or a magnitude past what prints in
+ * plain notation - so decoding one into a double throws away the reason
+ * the column was declared that way. A value that does fit still decodes
+ * to a plain number; this class is what the rest become, and it carries
+ * the digits exactly as the server wrote them.
+ *
+ * It is a class rather than a bare string so that it can be told apart:
+ * `determine()` types a bare string as `varchar`, which the server then
+ * refuses to put in a numeric column, so a string could be read but not
+ * written back. A `Numeric` round-trips.
+ *
+ * There is deliberately no `valueOf()`. Arithmetic on one of these has
+ * to be an explicit decision - `Symbol.toPrimitive` hands back the exact
+ * text for every hint, so `String(n)` and `${n}` are lossless, and
+ * `toNumber()` is the way to ask for the double and say so.
+ */
+export class Numeric {
+    value;
+    constructor(value) {
+        this.value = typeof value === 'string' ? value : String(value);
+    }
+    /** The decimal exactly as PostgreSQL wrote it; casts back through `::numeric`. */
+    toString() {
+        return this.value;
+    }
+    toJSON() {
+        return this.value;
+    }
+    /** The value as a double, which is lossy - that is the whole point of this class. */
+    toNumber() {
+        return parseFloat(this.value);
+    }
+    /**
+     * The text for every hint, the numeric one included: coercing to a
+     * double behind the caller's back is the loss this class exists to
+     * prevent, so `n * 2` has to go through the string and `n + 1`
+     * concatenates rather than quietly rounding.
+     */
+    [Symbol.toPrimitive]() {
+        return this.value;
+    }
+}

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

@@ -0,0 +1,74 @@
+import type { OID } from '../../types.js';
+import { REQUIRES_TYPE_OID } from './type-oid.js';
+/** Which ends of a range include their bound, written as PostgreSQL writes it. */
+export type RangeBounds = '[)' | '[]' | '()' | '(]';
+/**
+ * PostgreSQL's range types - `int4range`, `tstzrange` and the rest - as
+ * a pair of bounds, each of which may be absent (the range runs to
+ * infinity that way) and each of which may or may not be included.
+ *
+ * ```ts
+ * const r = new Range(1, 10);          // the default bounds, [1,10)
+ * r.lowerInclusive;                    // true
+ * r.upperInclusive;                    // false
+ * String(r);                           // '[1,10)'
+ *
+ * new Range(null, 10);                 // '(,10)' - unbounded below
+ * new Range(1, 10, '[]');              // '[1,10]'
+ * Range.empty();                       // 'empty' - no values at all
+ * ```
+ *
+ * `empty` is a value of its own rather than a range whose bounds happen
+ * to meet, and `(,)` - unbounded at both ends - is its opposite, not the
+ * same thing. Only `isEmpty` tells them apart.
+ *
+ * The bounds are the element type's own JavaScript values, so a
+ * `tstzrange` has `Date`s in it and an `int4range` has numbers. An absent
+ * bound is `null`, which is also how PostgreSQL's own constructors take
+ * it: `int4range(null, 10)`.
+ *
+ * Note what the server does to a discrete type: `int4range(1,10,'[]')` is
+ * stored and returned as `[1,11)`, because for integers those are the
+ * same set. So `upperInclusive` comes back false for every `int4range`,
+ * `int8range` and `daterange` - that is PostgreSQL normalizing, not this
+ * class losing something.
+ *
+ * `toString()` prints what the server prints for a range over numbers.
+ * Over dates it cannot: a `Range` holds `Date`s and has no way to know
+ * whether it came from a `daterange`, a `tsrange` or a `tstzrange`, which
+ * the server renders three different ways. It prints the instant in ISO
+ * 8601 instead - the truth about the `Date` it holds, and something
+ * PostgreSQL accepts back, but not byte-for-byte what a `daterange`
+ * prints. The exact wire form is what goes out when the Range is passed
+ * as a parameter, where the element type's own renderer is in reach.
+ */
+export declare class Range<T = any> {
+    /**
+     * All six range types answer `instanceof Range`, so one has to be named
+     * rather than guessed - see REQUIRES_TYPE_OID.
+     */
+    static readonly [REQUIRES_TYPE_OID] = true;
+    /** The lower bound, or null when the range runs to negative infinity. */
+    lower: T | null;
+    /** The upper bound, or null when the range runs to infinity. */
+    upper: T | null;
+    lowerInclusive: boolean;
+    upperInclusive: boolean;
+    /** True for `empty`, which contains no values - not the same as `(,)`. */
+    isEmpty: boolean;
+    /**
+     * @param oid Which range type this is - `DataTypeOIDs.int4range` and so
+     *   on. A Range that came from a query already carries the one it was
+     *   decoded from; give it here when building one to send, or name it at
+     *   the call site with `new BindParam(oid, range)`.
+     */
+    constructor(lower?: T | null, upper?: T | null, bounds?: RangeBounds, oid?: OID);
+    /** The empty range, which contains no values. */
+    static empty<T = any>(oid?: OID): Range<T>;
+    /**
+     * The range as PostgreSQL prints it, so it casts straight back through
+     * `::int4range` and reads the way the same value does in psql.
+     */
+    toString(): string;
+    toJSON(): string;
+}