postgrejs 3.8.0 → 3.10.0

package/util/decimal-as-string.js

@@ -0,0 +1,30 @@
+import { DataTypeNames, DataTypeOIDs } from '../constants.js';
+/**
+ * The types that can decode to an exact decimal string: the two that
+ * carry a decimal the wire format states exactly, rather than a double's
+ * nearest approximation of one.
+ */
+export const DecimalAsStringOIDs = Object.freeze([
+    DataTypeOIDs.numeric,
+    DataTypeOIDs.money,
+]);
+/** Whether this type's values are wanted as their exact decimal string. */
+export function wantsDecimalString(options, oid) {
+    const v = options?.decimalAsString;
+    if (v === undefined || v === false)
+        return false;
+    return v === true || v.includes(oid);
+}
+export function validateDecimalAsString(v) {
+    if (v === undefined || typeof v === 'boolean')
+        return;
+    if (!Array.isArray(v))
+        throw new TypeError('`decimalAsString` is either a boolean or an array of OIDs, not ' +
+            typeof v);
+    const l = v.length;
+    let i;
+    for (i = 0; i < l; i++)
+        if (!DecimalAsStringOIDs.includes(v[i]))
+            throw new TypeError('`decimalAsString` accepts only numeric (1700) and money (790). ' +
+                `Received ${v[i]}${DataTypeNames[v[i]] ? ' (' + DataTypeNames[v[i]] + ')' : ''}.`);
+}

package/util/fetch-as-string.d.ts

@@ -0,0 +1,33 @@
+import type { DataTypeMap } from '../data-type-map.js';
+import type { FetchAsStringItem } from '../interfaces/data-mapping-options.js';
+import type { Maybe, OID } from '../types.js';
+/**
+ * What `fetchAsString`'s entries mean, in one place - three call sites
+ * read the list and they have to agree: the Bind's result format codes
+ * (resolve-column-formats.ts), the parser chosen for each column
+ * (get-parsers.ts), and whether a cached set of parsers was built for
+ * the same ask (fetchAsStringEqual, below).
+ */
+/** Whether the list names this OID itself, in either form. */
+export declare function fetchAsStringNamesOid(list: Maybe<FetchAsStringItem[]>, oid: OID): boolean;
+/**
+ * Whether the list names the element type of an array column, and lets
+ * that reach the array - `{ oid, arrays: false }` is how a caller asks
+ * for a scalar column as text and leaves its array columns decoding.
+ *
+ * `numeric` is why: `pg` hands back a scalar `numeric` as a string and a
+ * `numeric[]` as numbers, so reproducing it needs the two said
+ * separately.
+ */
+export declare function fetchAsStringNamesElement(list: Maybe<FetchAsStringItem[]>, elementsOID: OID): boolean;
+/** Whether two lists select the same columns the same way. */
+export declare function fetchAsStringEqual(a: Maybe<FetchAsStringItem[]>, b: Maybe<FetchAsStringItem[]>): boolean;
+/**
+ * Refuses a selector that asks for something this does not do, rather
+ * than quietly not doing it.
+ *
+ * Checked once per list object, which is what a connection-level default
+ * or a module-level constant is; an inline list is a walk of a handful
+ * of entries.
+ */
+export declare function validateFetchAsString(list: Maybe<FetchAsStringItem[]>, typeMap?: Maybe<DataTypeMap>): void;

package/util/fetch-as-string.js

@@ -0,0 +1,122 @@
+import { DataTypeNames } from '../constants.js';
+/**
+ * What `fetchAsString`'s entries mean, in one place - three call sites
+ * read the list and they have to agree: the Bind's result format codes
+ * (resolve-column-formats.ts), the parser chosen for each column
+ * (get-parsers.ts), and whether a cached set of parsers was built for
+ * the same ask (fetchAsStringEqual, below).
+ */
+/** Whether the list names this OID itself, in either form. */
+export function fetchAsStringNamesOid(list, oid) {
+    if (!list)
+        return false;
+    const l = list.length;
+    let i;
+    let item;
+    for (i = 0; i < l; i++) {
+        item = list[i];
+        if (typeof item === 'number' ? item === oid : item.oid === oid)
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether the list names the element type of an array column, and lets
+ * that reach the array - `{ oid, arrays: false }` is how a caller asks
+ * for a scalar column as text and leaves its array columns decoding.
+ *
+ * `numeric` is why: `pg` hands back a scalar `numeric` as a string and a
+ * `numeric[]` as numbers, so reproducing it needs the two said
+ * separately.
+ */
+export function fetchAsStringNamesElement(list, elementsOID) {
+    if (!list)
+        return false;
+    const l = list.length;
+    let i;
+    let item;
+    for (i = 0; i < l; i++) {
+        item = list[i];
+        if (typeof item === 'number') {
+            if (item === elementsOID)
+                return true;
+        }
+        else if (item.oid === elementsOID && item.arrays !== false)
+            return true;
+    }
+    return false;
+}
+/** Whether two lists select the same columns the same way. */
+export function fetchAsStringEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return !a?.length && !b?.length;
+    const l = a.length;
+    if (l !== b.length)
+        return false;
+    let i;
+    let x;
+    let y;
+    for (i = 0; i < l; i++) {
+        x = a[i];
+        y = b[i];
+        if (x === y)
+            continue;
+        // A bare OID and a selector for the same OID are only the same ask
+        // while the selector says nothing; anything else decodes differently
+        // and must not be handed the other one's cached parsers.
+        if (typeof x === 'number' || typeof y === 'number') {
+            const num = typeof x === 'number' ? x : y;
+            const sel = (typeof x === 'number' ? y : x);
+            if (sel.oid !== num || sel.arrays === false || sel.ranges)
+                return false;
+            continue;
+        }
+        if (x.oid !== y.oid || (x.arrays === false) !== (y.arrays === false))
+            return false;
+        if (!!x.ranges !== !!y.ranges)
+            return false;
+    }
+    return true;
+}
+const _checked = new WeakSet();
+/**
+ * Refuses a selector that asks for something this does not do, rather
+ * than quietly not doing it.
+ *
+ * Checked once per list object, which is what a connection-level default
+ * or a module-level constant is; an inline list is a walk of a handful
+ * of entries.
+ */
+export function validateFetchAsString(list, typeMap) {
+    if (!list || _checked.has(list))
+        return;
+    const l = list.length;
+    let i;
+    let item;
+    for (i = 0; i < l; i++) {
+        item = list[i];
+        if (typeof item === 'number')
+            continue;
+        if (!item || typeof item.oid !== 'number')
+            throw new TypeError('`fetchAsString` takes an OID or `{ oid, arrays }`; received ' +
+                JSON.stringify(item));
+        if (item.ranges)
+            throw new TypeError('`fetchAsString` does not reach range columns through their ' +
+                "element's OID yet, so `ranges: true` would ask for something " +
+                'that will not happen. Name the range type itself instead - ' +
+                '`numrange` rather than `numeric`.');
+        // The flags say what happens to the *arrays of* the named type, so
+        // naming an array type and then talking about its arrays is not an
+        // ask anything can honour.
+        if (typeMap?.get(item.oid)?.elementsOID)
+            throw new TypeError(`\`fetchAsString\` selector ${name(item.oid)} is an array type, and ` +
+                'the flags describe what happens to a type’s array columns. ' +
+                'Name the element type instead, or list the array OID on its own.');
+    }
+    _checked.add(list);
+}
+function name(oid) {
+    return DataTypeNames[oid] ? `${oid} (${DataTypeNames[oid]})` : String(oid);
+}

package/util/get-parsers.js

@@ -1,5 +1,6 @@
 import { DataFormat } from '../constants.js';
 import { decodeBinaryArray } from './decode-binaryarray.js';
+import { fetchAsStringNamesElement, fetchAsStringNamesOid, } from './fetch-as-string.js';
 import { parsePostgresArray } from './parse-array.js';
 const DefaultColumnParser = (data, offset, len) => data.subarray(offset, offset + len);
 const DefaultTextColumnParser = (data, offset, len) => data.toString('utf8', offset, offset + len);
@@ -21,11 +22,27 @@ export function getParsers(typeMap, fields, mappingOptions) {
         // then the registered decoder is the only thing that can read it.
         if (asString &&
             f.format === DataFormat.text &&
-            asString.includes(f.dataTypeId)) {
+            fetchAsStringNamesOid(asString, f.dataTypeId)) {
             parsers[i] = DefaultTextColumnParser;
             continue;
         }
         const dataTypeReg = typeMap.get(f.dataTypeId);
+        // The other half of the same ask: the list named this column's
+        // *element* type, so the literal is split and the elements are handed
+        // back as the server wrote them - an array of what naming the scalar
+        // OID gives for a scalar column. Naming the array's own OID still
+        // means the whole literal, above; the two remain tellable apart
+        // because they name different OIDs.
+        if (asString &&
+            f.format === DataFormat.text &&
+            dataTypeReg?.elementsOID &&
+            fetchAsStringNamesElement(asString, dataTypeReg.elementsOID)) {
+            const separator = dataTypeReg.arraySeparator;
+            parsers[i] = (data, offset, len) => parsePostgresArray(data.toString('utf8', offset, offset + len), {
+                separator,
+            });
+            continue;
+        }
         if (dataTypeReg) {
             const isArray = !!dataTypeReg.elementsOID;
             if (f.format === DataFormat.binary) {

package/util/parse-datetime.d.ts

@@ -1,3 +1,4 @@
-export declare function parseDate(str: string, utc?: boolean): Date | number;
-export declare function parseDateTime(str: string, utc?: boolean): Date | number;
-export declare function parseDateTimeTz(str: string, utc?: boolean): Date | number;
+import { type PgDateStyle } from './date-style.js';
+export declare function parseDate(str: string, utc?: boolean, dateStyle?: PgDateStyle): Date | number;
+export declare function parseDateTime(str: string, utc?: boolean, dateStyle?: PgDateStyle): Date | number;
+export declare function parseDateTimeTz(str: string, utc?: boolean, dateStyle?: PgDateStyle): Date | number;

package/util/parse-datetime.js

@@ -1,4 +1,5 @@
 // noinspection RegExpUnnecessaryNonCapturingGroup
+import { parseStyledDateTime } from './date-style.js';
 import { fastParseInt } from './fast-parseint.js';
 import { parsePgTimestampString } from './parse-pg-timestamp.js';
 // noinspection RegExpUnnecessaryNonCapturingGroup
@@ -21,7 +22,12 @@ function fillTimeArgs(m, args) {
         }
     }
 }
-export function parseDate(str, utc) {
+export function parseDate(str, utc, dateStyle) {
+    if (dateStyle) {
+        const styled = parseStyledDateTime(str, dateStyle, utc);
+        if (styled)
+            return styled;
+    }
     const m = str.match(TIMESTAMP_PATTERN);
     if (!m)
         return noMatch(str);
@@ -40,7 +46,12 @@ export function parseDate(str, utc) {
         return new Date(Date.UTC(...args));
     return new Date(...args);
 }
-export function parseDateTime(str, utc) {
+export function parseDateTime(str, utc, dateStyle) {
+    if (dateStyle) {
+        const styled = parseStyledDateTime(str, dateStyle, utc);
+        if (styled)
+            return styled;
+    }
     if (!utc) {
         if (str === 'infinity')
             return Infinity;
@@ -49,9 +60,14 @@ export function parseDateTime(str, utc) {
         const fast = parsePgTimestampString(str);
         if (fast)
             return fast;
-        const d = new Date(str);
-        if (!isNaN(d.getTime()))
-            return d;
+        // Only reached under the ISO DateStyle: `new Date()` reads
+        // `05.03.2024` as the third of May, and a session that renders dates
+        // that way has said so above.
+        if (!dateStyle) {
+            const d = new Date(str);
+            if (!isNaN(d.getTime()))
+                return d;
+        }
     }
     const m = str.match(TIMESTAMP_PATTERN);
     if (!m)
@@ -72,7 +88,12 @@ export function parseDateTime(str, utc) {
         return new Date(Date.UTC(...args));
     return new Date(...args);
 }
-export function parseDateTimeTz(str, utc) {
+export function parseDateTimeTz(str, utc, dateStyle) {
+    if (dateStyle) {
+        const styled = parseStyledDateTime(str, dateStyle, utc);
+        if (styled)
+            return styled;
+    }
     if (str === 'infinity')
         return Infinity;
     if (str === '-infinity')
@@ -80,9 +101,13 @@ export function parseDateTimeTz(str, utc) {
     const fast = parsePgTimestampString(str);
     if (fast)
         return fast;
-    const native = new Date(str);
-    if (!isNaN(native.getTime()))
-        return native;
+    // See parseDateTime(): the engine's guess is only trusted where the
+    // session renders ISO.
+    if (!dateStyle) {
+        const native = new Date(str);
+        if (!isNaN(native.getTime()))
+            return native;
+    }
     const m = str.match(TIMESTAMP_PATTERN);
     if (!m)
         return noMatch(str);

package/util/resolve-column-formats.d.ts

@@ -1,7 +1,7 @@
 import type { DataTypeMap } from '../data-type-map.js';
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import { Protocol } from '../protocol/protocol.js';
-import type { Maybe, OID } from '../types.js';
+import type { Maybe } from '../types.js';
 export interface ColumnFormatOptions extends DataMappingOptions {
     columnFormat?: Protocol.DataFormat | Protocol.DataFormat[];
 }
@@ -17,18 +17,12 @@ export interface ColumnFormatOptions extends DataMappingOptions {
  * statement's, or a cached one's) pay nothing for this; callers that do
  * not have to ask for the whole row as text instead - see queryOnce().
  *
- * A column matches on its own `dataTypeId`, so an array column is only
- * ever selected by its own array OID (`_timestamptz`), never by its
- * element's. Listing the element OID leaves array columns alone.
+ * An array column is selected by its own array OID (`_timestamptz`) and
+ * by its element's (`timestamptz`) - both need the column as text, and
+ * which of the two was named is what get-parsers.ts reads to decide
+ * between the whole literal and the elements.
  *
  * Returns `columnFormat` untouched when there is nothing to do, so the
  * common case allocates nothing and keeps sending a single format code.
  */
 export declare function resolveColumnFormats(fields: Maybe<Protocol.RowDescription[]>, options: ColumnFormatOptions, typeMap?: DataTypeMap): Protocol.DataFormat | Protocol.DataFormat[];
-/**
- * Whether two `fetchAsString` lists select the same columns. Used to tell
- * a cached set of parsers apart from one built for a different list, which
- * `columnFormat` alone cannot do: an explicitly text column and one turned
- * text by fetchAsString carry the same format code but decode differently.
- */
-export declare function fetchAsStringEqual(a: Maybe<OID[]>, b: Maybe<OID[]>): boolean;

package/util/resolve-column-formats.js

@@ -1,5 +1,6 @@
 import { DEFAULT_COLUMN_FORMAT } from '../constants.js';
 import { Protocol } from '../protocol/protocol.js';
+import { fetchAsStringNamesElement, fetchAsStringNamesOid, } from './fetch-as-string.js';
 const DataFormat = Protocol.DataFormat;
 /**
  * Whether this client could read the column if it arrived in `format`.
@@ -13,6 +14,18 @@ function canDecode(typeMap, oid, format) {
     const reg = typeMap.get(oid);
     return !!reg && typeof reg.decodeBinary === 'function';
 }
+/**
+ * Whether `asString` names the element type of the array type `oid` -
+ * "give me this type verbatim", asked of a column of them.
+ *
+ * Needs the type map to find the element OID, which the caller already
+ * hands over for `unknownTypesAsString`; without one this answers no and
+ * only an array's own OID selects it, as it always did.
+ */
+function namesElementOf(typeMap, asString, oid) {
+    const elementsOID = typeMap?.get(oid)?.elementsOID;
+    return !!elementsOID && fetchAsStringNamesElement(asString, elementsOID);
+}
 /**
  * Turns `fetchAsString`'s OID list into the positional result format codes
  * a Bind message actually carries.
@@ -25,9 +38,10 @@ function canDecode(typeMap, oid, format) {
  * statement's, or a cached one's) pay nothing for this; callers that do
  * not have to ask for the whole row as text instead - see queryOnce().
  *
- * A column matches on its own `dataTypeId`, so an array column is only
- * ever selected by its own array OID (`_timestamptz`), never by its
- * element's. Listing the element OID leaves array columns alone.
+ * An array column is selected by its own array OID (`_timestamptz`) and
+ * by its element's (`timestamptz`) - both need the column as text, and
+ * which of the two was named is what get-parsers.ts reads to decide
+ * between the whole literal and the elements.
  *
  * Returns `columnFormat` untouched when there is nothing to do, so the
  * common case allocates nothing and keeps sending a single format code.
@@ -42,6 +56,10 @@ export function resolveColumnFormats(fields, options, typeMap) {
     const named = !!asString && asString.length > 0;
     if (!fields || (!named && !unknownAsString))
         return base;
+    // Both options do one thing: ask for a column as text. A row that is
+    // already all text has nothing left for them to ask.
+    if (base === DataFormat.text)
+        return base;
     const l = fields.length;
     const baseIsArray = Array.isArray(base);
     const out = new Array(l);
@@ -54,10 +72,16 @@ export function resolveColumnFormats(fields, options, typeMap) {
         format = baseIsArray
             ? (base[i] ?? DEFAULT_COLUMN_FORMAT)
             : base;
-        if (named && asString.includes(oid)) {
+        if (named &&
+            (fetchAsStringNamesOid(asString, oid) ||
+                namesElementOf(typeMap, asString, oid))) {
             // fetchAsString names the value the caller wants verbatim, so it
             // overrides an explicit columnFormat for its own columns - the two
             // cannot both be honored and the OID list is the more specific ask.
+            // An array column is selected either way: by its own OID, which
+            // asks for the whole literal, or by its element's, which asks for
+            // the elements - both need the column as text, and get-parsers.ts
+            // is where the two part company.
             format = DataFormat.text;
             hit = true;
         }
@@ -72,23 +96,3 @@ export function resolveColumnFormats(fields, options, typeMap) {
     }
     return hit ? out : base;
 }
-/**
- * Whether two `fetchAsString` lists select the same columns. Used to tell
- * a cached set of parsers apart from one built for a different list, which
- * `columnFormat` alone cannot do: an explicitly text column and one turned
- * text by fetchAsString carry the same format code but decode differently.
- */
-export function fetchAsStringEqual(a, b) {
-    if (a === b)
-        return true;
-    if (!a || !b)
-        return !a?.length && !b?.length;
-    const l = a.length;
-    if (l !== b.length)
-        return false;
-    let i;
-    for (i = 0; i < l; i++)
-        if (a[i] !== b[i])
-            return false;
-    return true;
-}

package/util/row-decoder.d.ts

@@ -17,12 +17,28 @@ import type { AnyParseFunction } from '../types.js';
  * every other row's bytes in it) alive until released.
  */
 export declare abstract class RowDecoder {
+    /**
+     * What `QueryResult.rowType`/`Cursor.rowType` reports for rows this
+     * decoder produced - a promise to the caller about their shape, so it
+     * is the decoder's to make. `'custom'` here is the honest answer for
+     * a decoder nobody else knows anything about; the two built-ins name
+     * their own shape, and a subclass of one that still produces that
+     * shape inherits the right answer without doing anything.
+     *
+     * Set it when a subclass changes the shape - a decoder that hands
+     * back a lazy view rather than a plain array is not an `'array'`, and
+     * a caller that indexes it because the result said so would be
+     * reading the wrong thing.
+     */
+    readonly rowType: 'array' | 'object' | 'custom';
     abstract decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): any;
 }
 export declare class ArrayRowDecoder extends RowDecoder {
+    readonly rowType: "array";
     decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions): any[];
 }
 export declare class ObjectRowDecoder extends RowDecoder {
+    readonly rowType: "object";
     decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): object;
 }
 export declare const DEFAULT_ARRAY_ROW_DECODER: ArrayRowDecoder;
@@ -40,10 +56,14 @@ interface RowDecoderOptions {
  */
 export declare function resolveRowDecoder(options: RowDecoderOptions): RowDecoder;
 /**
- * The `rowType` string surfaced on `QueryResult`/`Cursor.rowType`. `'custom'`
- * when the caller supplied their own RowDecoder subclass - there's no way to
- * know what shape it returns - otherwise the same `'array' | 'object'` this
- * option has always reported.
+ * The `rowType` string surfaced on `QueryResult`/`Cursor.rowType`.
+ *
+ * Asked of the decoder rather than worked out from its class: an
+ * `instanceof` test answers `'array'` for anything derived from
+ * `ArrayRowDecoder`, including a subclass that overrode `decode()` to
+ * return something else entirely - which is the only reason to subclass
+ * it. The built-ins declare their own shape, so the answers are
+ * unchanged, and a subclass that changes the shape can now say so.
  */
 export declare function resolveRowType(options: RowDecoderOptions): 'array' | 'object' | 'custom';
 export {};

package/util/row-decoder.js

@@ -15,13 +15,29 @@ import { parseObjectRow, parseRow } from './parse-row.js';
  * every other row's bytes in it) alive until released.
  */
 export class RowDecoder {
+    /**
+     * What `QueryResult.rowType`/`Cursor.rowType` reports for rows this
+     * decoder produced - a promise to the caller about their shape, so it
+     * is the decoder's to make. `'custom'` here is the honest answer for
+     * a decoder nobody else knows anything about; the two built-ins name
+     * their own shape, and a subclass of one that still produces that
+     * shape inherits the right answer without doing anything.
+     *
+     * Set it when a subclass changes the shape - a decoder that hands
+     * back a lazy view rather than a plain array is not an `'array'`, and
+     * a caller that indexes it because the result said so would be
+     * reading the wrong thing.
+     */
+    rowType = 'custom';
 }
 export class ArrayRowDecoder extends RowDecoder {
+    rowType = 'array';
     decode(parsers, data, columnCount, options) {
         return parseRow(parsers, data, columnCount, options);
     }
 }
 export class ObjectRowDecoder extends RowDecoder {
+    rowType = 'object';
     decode(parsers, data, columnCount, options, fields) {
         return parseObjectRow(parsers, data, columnCount, options, fields);
     }
@@ -48,16 +64,15 @@ export function resolveRowDecoder(options) {
         : DEFAULT_ARRAY_ROW_DECODER;
 }
 /**
- * The `rowType` string surfaced on `QueryResult`/`Cursor.rowType`. `'custom'`
- * when the caller supplied their own RowDecoder subclass - there's no way to
- * know what shape it returns - otherwise the same `'array' | 'object'` this
- * option has always reported.
+ * The `rowType` string surfaced on `QueryResult`/`Cursor.rowType`.
+ *
+ * Asked of the decoder rather than worked out from its class: an
+ * `instanceof` test answers `'array'` for anything derived from
+ * `ArrayRowDecoder`, including a subclass that overrode `decode()` to
+ * return something else entirely - which is the only reason to subclass
+ * it. The built-ins declare their own shape, so the answers are
+ * unchanged, and a subclass that changes the shape can now say so.
  */
 export function resolveRowType(options) {
-    const decoder = resolveRowDecoder(options);
-    if (decoder instanceof ObjectRowDecoder)
-        return 'object';
-    if (decoder instanceof ArrayRowDecoder)
-        return 'array';
-    return 'custom';
+    return resolveRowDecoder(options).rowType;
 }

package/util/sql-tag.js

@@ -1,10 +1,11 @@
 import { BindParam } from '../connection/bind-param.js';
 import { DataTypeMap, GlobalTypeMap } from '../data-type-map.js';
+import { arrayLeaf } from './array-leaf.js';
 import { escapeIdentifier } from './escape-identifier.js';
 import { escapeLiteral } from './escape-literal.js';
 import { formatDateParam } from './format-datetime.js';
 import { stringifyArrayLiteral } from './stringify-arrayliteral.js';
-import { arrayLeaf, isUnspecifiedParam } from './unspecified-param.js';
+import { isUnspecifiedParam } from './unspecified-param.js';
 /**
  * A statement built by the `sql` tag: its text with the values pulled out.
  *

package/util/stringify-for-sql.js

@@ -14,11 +14,12 @@ export function stringifyArrayForSQL(v, options, encode) {
  * registered `encodeText()` that writes exactly the literal PostgreSQL
  * reads back, and `determine()` already knows which type each one is -
  * it is what the same value is sent as when it is bound as a parameter.
- * Without asking, all of them became `::json`, and since these classes
- * have a `toJSON()` returning their own literal the result was not even
- * a JSON object but a JSON string holding one, which casts to nothing:
- * `'"(1,2)"'::json` where `'(1,2)'::point` was meant. A Date became its
- * ISO string and a Buffer leaked its bytes as `{"type":"Buffer",...}`.
+ * Without asking, all of them became `::json`: `'{"x":1,"y":2}'::json`
+ * where `'(1,2)'::point` was meant - a JSON object that casts to no
+ * geometric type at all, and which back when these classes had a
+ * `toJSON()` of their own was not even that, but a JSON string holding
+ * the literal. A Date became its ISO string and a Buffer leaked its
+ * bytes as `{"type":"Buffer",...}`.
  */
 function stringifyObjectForSQL(v, options) {
     // determine() throws for a class that must carry a type OID and does

package/util/temporal.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reaching the `Temporal` the application provides, without depending on
+ * one.
+ *
+ * No runtime ships Temporal yet - Node 24.15 and Bun 1.3.10 both answer
+ * `undefined`, with or without `--harmony` - so today every caller that
+ * turns `temporalTypes` on has installed a polyfill. That is why this is
+ * read off `globalThis` when it is needed rather than imported: this
+ * package takes no dependency, a polyfill loaded after this module is
+ * still seen, and the day a runtime ships Temporal nothing here changes.
+ */
+/**
+ * The parts of `Temporal` this client calls. Deliberately untyped past
+ * the names: the shape cannot be checked against a global that may not
+ * exist, so the presence check below is the check.
+ */
+export interface TemporalApi {
+    Instant: any;
+    PlainDate: any;
+    PlainDateTime: any;
+    PlainTime: any;
+    Duration: any;
+    ZonedDateTime: any;
+}
+/**
+ * The runtime's `Temporal`, or an error saying how to get one.
+ *
+ * Called when a type map is built - which for a connection is while it
+ * is being constructed - so a missing Temporal is reported before any
+ * I/O rather than in the middle of decoding a row.
+ */
+export declare function getTemporal(): TemporalApi;
+/**
+ * The zone a `timestamptz` is printed in when the caller named none.
+ *
+ * Only the printing: a timestamptz is an absolute instant and arrives as
+ * one, so the zone decides what wall clock the ZonedDateTime shows and
+ * nothing about which moment it is.
+ */
+export declare function systemTimeZone(): string;
+/**
+ * Checks a zone name before it is handed to Temporal, so the complaint
+ * names the setting it came from instead of surfacing from inside a
+ * decode. `Intl` accepts exactly what Temporal does and is here whether
+ * Temporal is or not.
+ */
+export declare function requireTimeZone(zone: string, where: string): string;