postgrejs 3.6.1 → 3.8.0

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

package/data-types/classes/range.js

@@ -0,0 +1,111 @@
+import { REQUIRES_TYPE_OID, setTypeOid } from './type-oid.js';
+function formatBound(v) {
+    if (v === null || v === undefined)
+        return '';
+    // A Date renders as an ISO 8601 timestamp rather than the JavaScript
+    // form: PostgreSQL accepts it back, `Mon Oct 22 2020 ...` it does not,
+    // and the point of this method is that the string casts to a range
+    // again.
+    const s = v instanceof Date ? v.toISOString() : String(v);
+    // The server quotes a bound that is empty or carries anything that
+    // would be read as punctuation of the literal itself - whitespace
+    // included, which is why a timestamp is always quoted. Inside the
+    // quotes a quote and a backslash are each doubled.
+    if (s === '' || /["\\()[\],]|\s/.test(s))
+        return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '""') + '"';
+    return s;
+}
+/**
+ * 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 class Range {
+    /**
+     * All six range types answer `instanceof Range`, so one has to be named
+     * rather than guessed - see REQUIRES_TYPE_OID.
+     */
+    static [REQUIRES_TYPE_OID] = true;
+    /** The lower bound, or null when the range runs to negative infinity. */
+    lower;
+    /** The upper bound, or null when the range runs to infinity. */
+    upper;
+    lowerInclusive;
+    upperInclusive;
+    /** True for `empty`, which contains no values - not the same as `(,)`. */
+    isEmpty;
+    /**
+     * @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 = null, upper = null, bounds = '[)', oid) {
+        this.lower = lower;
+        this.upper = upper;
+        // An absent bound is never inclusive; the server prints `(` for it
+        // whatever was asked for.
+        this.lowerInclusive = bounds.charAt(0) === '[' && lower !== null;
+        this.upperInclusive = bounds.charAt(1) === ']' && upper !== null;
+        this.isEmpty = false;
+        if (oid !== undefined)
+            setTypeOid(this, oid);
+    }
+    /** The empty range, which contains no values. */
+    static empty(oid) {
+        const r = new Range(null, null, '[)', oid);
+        r.isEmpty = true;
+        return r;
+    }
+    /**
+     * The range as PostgreSQL prints it, so it casts straight back through
+     * `::int4range` and reads the way the same value does in psql.
+     */
+    toString() {
+        if (this.isEmpty)
+            return 'empty';
+        return ((this.lowerInclusive && this.lower !== null ? '[' : '(') +
+            formatBound(this.lower) +
+            ',' +
+            formatBound(this.upper) +
+            (this.upperInclusive && this.upper !== null ? ']' : ')'));
+    }
+    toJSON() {
+        return this.toString();
+    }
+}

package/data-types/classes/type-oid.d.ts

@@ -0,0 +1,34 @@
+import type { Maybe, OID } from '../../types.js';
+/**
+ * The OID a decoded value came from, carried on the value itself.
+ *
+ * A symbol rather than a property named `oid`, and non-enumerable on top
+ * of that: `{ oid: 3904 }` is an ordinary object somebody might store in
+ * a json column, and reading a plain key would mistake it for a typed
+ * value. A symbol cannot collide, and being non-enumerable keeps it out
+ * of `JSON.stringify`, object spread, `Object.keys` and expect's
+ * `toStrictEqual` - so a stamped value compares equal to an unstamped one
+ * with the same fields.
+ */
+export declare const TYPE_OID: unique symbol;
+/**
+ * Marks a class whose instances cannot be typed by inspection, so passing
+ * one as an untyped parameter is an error rather than a guess.
+ *
+ * Range is the case: all six range types answer `instanceof Range` and
+ * nothing about a Range says which it is. Without this, such a value
+ * falls through to JsonType - whose isType() takes any object - and goes
+ * out declared `json`, which comes back looking right.
+ */
+export declare const REQUIRES_TYPE_OID: unique symbol;
+/**
+ * Records which type a value was decoded from, so it can go back as that
+ * type without the caller naming it again.
+ *
+ * Only worth doing for a value whose class cannot say what it is on its
+ * own - it costs a defineProperty per value (~160ns), which is not free
+ * on a column of them.
+ */
+export declare function setTypeOid<T extends object>(value: T, oid: OID): T;
+/** The OID a value was decoded from, if it carries one. */
+export declare function getTypeOid(value: unknown): Maybe<OID>;

package/data-types/classes/type-oid.js

@@ -0,0 +1,45 @@
+/**
+ * The OID a decoded value came from, carried on the value itself.
+ *
+ * A symbol rather than a property named `oid`, and non-enumerable on top
+ * of that: `{ oid: 3904 }` is an ordinary object somebody might store in
+ * a json column, and reading a plain key would mistake it for a typed
+ * value. A symbol cannot collide, and being non-enumerable keeps it out
+ * of `JSON.stringify`, object spread, `Object.keys` and expect's
+ * `toStrictEqual` - so a stamped value compares equal to an unstamped one
+ * with the same fields.
+ */
+export const TYPE_OID = Symbol('postgrejs.typeOid');
+/**
+ * Marks a class whose instances cannot be typed by inspection, so passing
+ * one as an untyped parameter is an error rather than a guess.
+ *
+ * Range is the case: all six range types answer `instanceof Range` and
+ * nothing about a Range says which it is. Without this, such a value
+ * falls through to JsonType - whose isType() takes any object - and goes
+ * out declared `json`, which comes back looking right.
+ */
+export const REQUIRES_TYPE_OID = Symbol('postgrejs.requiresTypeOid');
+/**
+ * Records which type a value was decoded from, so it can go back as that
+ * type without the caller naming it again.
+ *
+ * Only worth doing for a value whose class cannot say what it is on its
+ * own - it costs a defineProperty per value (~160ns), which is not free
+ * on a column of them.
+ */
+export function setTypeOid(value, oid) {
+    Object.defineProperty(value, TYPE_OID, {
+        value: oid,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+    return value;
+}
+/** The OID a value was decoded from, if it carries one. */
+export function getTypeOid(value) {
+    return value != null
+        ? value[TYPE_OID]
+        : undefined;
+}

package/data-types/inet-type.d.ts

@@ -0,0 +1,5 @@
+import type { DataType } from '../interfaces/data-type.js';
+export declare const InetType: DataType;
+export declare const ArrayInetType: DataType;
+export declare const CidrType: DataType;
+export declare const ArrayCidrType: DataType;

package/data-types/inet-type.js

@@ -0,0 +1,286 @@
+import { DataTypeOIDs } from '../constants.js';
+/**
+ * `inet` and `cidr` share a file because they share everything that
+ * matters: one wire format, one JavaScript shape, and one pair of
+ * conversions. A single flag byte tells them apart on the wire, and on
+ * output the only difference is whether the netmask is always printed.
+ *
+ * Both decode to a string. JavaScript has no address type, and every Node
+ * API that takes an address - `net`, `dns`, `http` - takes a string, so an
+ * object of parts would be something every caller has to join back
+ * together before using. `pg` answers with a string too.
+ */
+/**
+ * PostgreSQL's own address-family numbers, deliberately not the
+ * platform's: they are written into the stored value, so they cannot
+ * depend on how a particular `<sys/socket.h>` happens to number `AF_INET6`.
+ */
+const PGSQL_AF_INET = 2;
+const PGSQL_AF_INET6 = 3;
+const IPV4_PATTERN = /^\d{1,3}(?:\.\d{1,3}){0,3}$/;
+const IPV6_GROUP_PATTERN = /^[0-9a-fA-F]{1,4}$/;
+/**
+ * Writes the four octets of an IPv4 address.
+ *
+ * Fewer than four is allowed, the rest reading as zero - `10/8` for
+ * `10.0.0.0/8`. That is PostgreSQL's own rule for both types, confirmed
+ * against the server rather than assumed: `inet '10.0/16'` is accepted
+ * and stored as `10.0.0.0/16`.
+ */
+function writeIPv4(out, offset, v) {
+    if (!IPV4_PATTERN.test(v))
+        return false;
+    const parts = v.split('.');
+    const l = parts.length;
+    let i;
+    let n;
+    for (i = 0; i < l; i++) {
+        n = +parts[i];
+        if (n > 255)
+            return false;
+        out[offset + i] = n;
+    }
+    return true;
+}
+/**
+ * Writes the sixteen bytes of an IPv6 address, accepting the two
+ * shorthands the server does: a single `::` standing for at least one
+ * all-zero group, and a trailing dotted-quad for the last two groups.
+ */
+function writeIPv6(out, offset, v) {
+    const dot = v.indexOf('.');
+    if (dot >= 0) {
+        // An embedded IPv4 tail occupies the last two groups. Rewritten into
+        // hex here so the group walk below does not have to know about it.
+        const i = v.lastIndexOf(':', dot);
+        if (i < 0)
+            return false;
+        const quad = Buffer.alloc(4);
+        const tail = v.slice(i + 1);
+        // Unlike a bare IPv4 address, the embedded form has no abbreviated
+        // spelling - `::1.2` is not an address.
+        if (tail.split('.').length !== 4 || !writeIPv4(quad, 0, tail))
+            return false;
+        v =
+            v.slice(0, i + 1) +
+                quad.readUInt16BE(0).toString(16) +
+                ':' +
+                quad.readUInt16BE(2).toString(16);
+    }
+    const halves = v.split('::');
+    if (halves.length > 2)
+        return false;
+    const head = halves[0] ? halves[0].split(':') : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    const given = head.length + tail.length;
+    // Without `::` every group must be written out; with it, at least one
+    // must be left for the `::` itself to stand for.
+    if (halves.length === 2 ? given > 7 : given !== 8)
+        return false;
+    out.fill(0, offset, offset + 16);
+    let p = offset;
+    let g;
+    for (g of head) {
+        if (!IPV6_GROUP_PATTERN.test(g))
+            return false;
+        out.writeUInt16BE(parseInt(g, 16), p);
+        p += 2;
+    }
+    p = offset + 16 - tail.length * 2;
+    for (g of tail) {
+        if (!IPV6_GROUP_PATTERN.test(g))
+            return false;
+        out.writeUInt16BE(parseInt(g, 16), p);
+        p += 2;
+    }
+    return true;
+}
+/**
+ * Renders sixteen bytes the way `inet_net_ntop()` does, which is what
+ * this has to match - not any general IPv6 convention - because the
+ * point is to hand back the string the server itself would have printed.
+ *
+ * The longest run of zero groups collapses to `::`, but only when it
+ * covers at least two of them (`::2:3:4:5:6:7:8` comes back from the
+ * server as `0:2:3:4:5:6:7:8`), and the earliest run wins a tie. An
+ * address whose last four bytes are really an IPv4 one is printed in
+ * dotted form.
+ */
+function formatIPv6(buf, offset) {
+    const words = new Array(8);
+    let i;
+    for (i = 0; i < 8; i++)
+        words[i] = buf.readUInt16BE(offset + i * 2);
+    let bestBase = -1;
+    let bestLen = 0;
+    let curBase = -1;
+    let curLen = 0;
+    for (i = 0; i < 8; i++) {
+        if (words[i] !== 0) {
+            curBase = -1;
+            continue;
+        }
+        if (curBase === -1) {
+            curBase = i;
+            curLen = 1;
+        }
+        else
+            curLen++;
+        if (curLen > bestLen) {
+            bestBase = curBase;
+            bestLen = curLen;
+        }
+    }
+    if (bestLen < 2)
+        bestBase = -1;
+    let out = '';
+    for (i = 0; i < 8; i++) {
+        if (bestBase !== -1 && i >= bestBase && i < bestBase + bestLen) {
+            if (i === bestBase)
+                out += ':';
+            continue;
+        }
+        if (i !== 0)
+            out += ':';
+        // `::a.b.c.d` and `::ffff:a.b.c.d` - the two prefixes that mean the
+        // tail is an IPv4 address. Nothing else qualifies, so `::1:1.2.3.4`
+        // prints as `::1:102:304`.
+        if (i === 6 &&
+            bestBase === 0 &&
+            (bestLen === 6 || (bestLen === 5 && words[5] === 0xffff))) {
+            out +=
+                buf[offset + 12] +
+                    '.' +
+                    buf[offset + 13] +
+                    '.' +
+                    buf[offset + 14] +
+                    '.' +
+                    buf[offset + 15];
+            break;
+        }
+        out += words[i].toString(16);
+    }
+    // A run that reaches the end leaves only one colon behind.
+    if (bestBase !== -1 && bestBase + bestLen === 8)
+        out += ':';
+    return out;
+}
+/**
+ * The address and its netmask, or undefined if the string is not one.
+ * Splitting is done here rather than by the caller because the two types
+ * differ only in what they do with the parts.
+ */
+function parseAddress(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const slash = v.indexOf('/');
+    const addr = slash < 0 ? v : v.slice(0, slash);
+    const family = addr.includes(':') ? PGSQL_AF_INET6 : PGSQL_AF_INET;
+    const size = family === PGSQL_AF_INET6 ? 16 : 4;
+    const bytes = Buffer.alloc(size);
+    const ok = family === PGSQL_AF_INET6
+        ? writeIPv6(bytes, 0, addr)
+        : writeIPv4(bytes, 0, addr);
+    if (!ok)
+        return undefined;
+    let bits = size * 8;
+    if (slash >= 0) {
+        const s = v.slice(slash + 1);
+        if (!/^\d{1,3}$/.test(s))
+            return undefined;
+        bits = +s;
+        if (bits > size * 8)
+            return undefined;
+    }
+    return { family, bits, bytes };
+}
+function encode(buf, v, isCidr) {
+    const a = parseAddress(v);
+    if (!a)
+        throw new Error(`"${v}" is not a valid ${isCidr ? 'cidr' : 'inet'} value`);
+    buf.writeUInt8(a.family);
+    // Unsigned: a full IPv6 mask is 128, which does not fit a signed byte.
+    buf.writeUInt8(a.bits);
+    buf.writeUInt8(isCidr ? 1 : 0);
+    buf.writeUInt8(a.bytes.length);
+    buf.writeBytes(a.bytes);
+}
+/**
+ * Four header bytes - family, netmask bits, the cidr flag and the
+ * address length - then the address itself. The flag is what decides
+ * whether the netmask is printed, so one decoder serves both types: a
+ * `cidr` always carries its mask, an `inet` only when it is not the whole
+ * address.
+ */
+function decode(v, offset) {
+    const family = v[offset];
+    const bits = v[offset + 1];
+    const isCidr = v[offset + 2];
+    const size = v[offset + 3];
+    if (family !== PGSQL_AF_INET && family !== PGSQL_AF_INET6)
+        throw new Error(`Unknown address family ${family} in inet value`);
+    const text = family === PGSQL_AF_INET6
+        ? formatIPv6(v, offset + 4)
+        : v[offset + 4] +
+            '.' +
+            v[offset + 5] +
+            '.' +
+            v[offset + 6] +
+            '.' +
+            v[offset + 7];
+    return isCidr || bits !== size * 8 ? text + '/' + bits : text;
+}
+export const InetType = {
+    name: 'inet',
+    oid: DataTypeOIDs.inet,
+    jsType: 'string',
+    // An address is not a shape - it is a string like any other, and an
+    // application storing one in a `text` column passes exactly the same
+    // value. Inferring this type from a string would send `inet` where
+    // `text` was meant and break that query, so the type is reached only by
+    // naming it: `new BindParam(DataTypeOIDs.inet, '192.168.0.1')`, or a
+    // column whose declared type says so.
+    inferrable: false,
+    encodeText(v) {
+        // Handed to the server as written; it does its own parsing here, and
+        // accepts spellings this file's own parser is not asked to know.
+        return '' + v;
+    },
+    encodeBinary(buf, v) {
+        encode(buf, v, false);
+    },
+    decodeBinary(v, offset = 0) {
+        return decode(v, offset);
+    },
+    decodeText(v) {
+        return v;
+    },
+    // An address is pure ASCII, so 'latin1' decodes identically to 'utf8'
+    // while skipping V8's multi-byte-sequence detection.
+    decodeTextBuffer(buf, offset, len) {
+        return buf.toString('latin1', offset, offset + len);
+    },
+    isType(v) {
+        return !!parseAddress(v);
+    },
+};
+export const ArrayInetType = {
+    ...InetType,
+    name: '_inet',
+    oid: DataTypeOIDs._inet,
+    elementsOID: DataTypeOIDs.inet,
+};
+export const CidrType = {
+    ...InetType,
+    name: 'cidr',
+    oid: DataTypeOIDs.cidr,
+    encodeBinary(buf, v) {
+        encode(buf, v, true);
+    },
+};
+export const ArrayCidrType = {
+    ...CidrType,
+    name: '_cidr',
+    oid: DataTypeOIDs._cidr,
+    elementsOID: DataTypeOIDs.cidr,
+};

package/data-types/int2-vector-type.js

@@ -10,7 +10,10 @@ export const Int2VectorType = {
     encodeBinary(buf, v) {
         encodeBinaryArray(buf, v, DataTypeOIDs.int2, {}, (io, x) => {
             io.writeInt16BE(x);
-        });
+        }, 
+        // A vector is genuinely 0-based, unlike every ordinary array -
+        // `array_lower(pg_index.indkey, 1)` is 0 on the server.
+        undefined, 0);
     },
     encodeCalculateDim(v) {
         return [v.length];

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

@@ -0,0 +1,5 @@
+import type { DataType } from '../interfaces/data-type.js';
+import { Interval } from './classes/interval.js';
+export declare function parseIntervalText(v: string): Interval;
+export declare const IntervalType: DataType;
+export declare const ArrayIntervalType: DataType;

package/data-types/interval-type.js

@@ -0,0 +1,79 @@
+import { DataTypeOIDs } from '../constants.js';
+import { readBigInt64BE } from '../util/bigint-methods.js';
+import { Interval } from './classes/interval.js';
+/**
+ * What PostgreSQL prints under the default `IntervalStyle` - years, months
+ * and days as counted words, then a signed clock time. Every part is
+ * optional and the server omits the ones that are zero, except that a
+ * wholly zero interval still prints `00:00:00`.
+ */
+const INTERVAL_PATTERN = /^\s*(?:([+-]?\d+)\s+years?\s*)?(?:([+-]?\d+)\s+mons?\s*)?(?:([+-]?\d+)\s+days?\s*)?(?:([+-])?(\d+):(\d\d):(\d\d)(?:\.(\d{1,6}))?)?\s*$/;
+function toInterval(v) {
+    if (v instanceof Interval)
+        return v;
+    if (typeof v === 'string')
+        return parseIntervalText(v);
+    if (v && typeof v === 'object')
+        return new Interval(v);
+    throw new TypeError(`"${typeof v}" cannot be encoded as an interval - pass an Interval, ` +
+        'a plain object of its fields, or a string PostgreSQL would accept');
+}
+export function parseIntervalText(v) {
+    const m = INTERVAL_PATTERN.exec(v);
+    if (!m) {
+        // Rather than answering with a zero interval, which is what reading
+        // an unrecognized shape leniently would amount to. The other styles
+        // (`sql_standard`, `postgres_verbose`, `iso_8601`) are not parsed
+        // here, and the binary path - which is the default - never sees any
+        // of this.
+        throw new Error(`"${v}" is not an interval in PostgreSQL's default IntervalStyle`);
+    }
+    const sign = m[4] === '-' ? -1 : 1;
+    return new Interval({
+        years: m[1] ? parseInt(m[1], 10) : 0,
+        months: m[2] ? parseInt(m[2], 10) : 0,
+        days: m[3] ? parseInt(m[3], 10) : 0,
+        hours: m[5] ? sign * parseInt(m[5], 10) : 0,
+        minutes: m[6] ? sign * parseInt(m[6], 10) : 0,
+        seconds: m[7] ? sign * parseInt(m[7], 10) : 0,
+        // The fraction is microseconds with trailing zeroes dropped, so `.5`
+        // is half a second rather than five microseconds.
+        milliseconds: m[8] ? (sign * parseInt(m[8].padEnd(6, '0'), 10)) / 1000 : 0,
+    });
+}
+export const IntervalType = {
+    name: 'interval',
+    oid: DataTypeOIDs.interval,
+    jsType: 'Interval',
+    /**
+     * 16 bytes, and three separate quantities rather than one total: a
+     * signed microsecond count for the time, then a day count and a month
+     * count. The server keeps them apart because they are not convertible -
+     * see the Interval class.
+     */
+    decodeBinary(v, offset = 0) {
+        const micros = typeof v.readBigInt64BE === 'function'
+            ? v.readBigInt64BE(offset)
+            : readBigInt64BE(v, offset);
+        return Interval.fromParts(micros, v.readInt32BE(offset + 8), v.readInt32BE(offset + 12));
+    },
+    encodeBinary(buf, v) {
+        const iv = toInterval(v);
+        buf.writeBigInt64BE(iv.totalMicroseconds);
+        buf.writeInt32BE(iv.days);
+        buf.writeInt32BE(iv.totalMonths);
+    },
+    decodeText: parseIntervalText,
+    encodeText(v) {
+        return toInterval(v).toString();
+    },
+    isType(v) {
+        return v instanceof Interval;
+    },
+};
+export const ArrayIntervalType = {
+    ...IntervalType,
+    name: '_interval',
+    oid: DataTypeOIDs._interval,
+    elementsOID: DataTypeOIDs.interval,
+};

package/data-types/jsonpath-type.d.ts

@@ -0,0 +1,3 @@
+import type { DataType } from '../interfaces/data-type.js';
+export declare const JsonPathType: DataType;
+export declare const ArrayJsonPathType: DataType;