postgrejs 3.8.0 → 3.10.0

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

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

package/interfaces/database-connection-params.d.ts

@@ -2,6 +2,8 @@ import type { PoolConfiguration as LPoolConfiguration } from 'lightning-pool';
 import type { ConnectionOptions as TlsConnectionOptions } from 'tls';
 import type { SmartBufferConfig } from '../protocol/smart-buffer.js';
 import type { DebugLogger } from '../types.js';
+import type { DataMappingOptions } from './data-mapping-options.js';
+import type { QueryOptions } from './query-options.js';
 export interface DatabaseConnectionParams {
     host?: string;
     port?: number;
@@ -147,8 +149,32 @@ export type TargetSessionAttrs = 'read-write' | 'read-only' | 'primary' | 'stand
 export interface SocketOptions {
     keepAlive?: boolean;
 }
-export interface ConnectionConfiguration extends DatabaseConnectionParams, SocketOptions {
+/**
+ * The data-mapping options a connection can answer for every statement
+ * on it, so a caller that always wants the same shape says so once.
+ *
+ * Each is the default for `QueryOptions`'s field of the same name and
+ * is described there; a value on the call always wins. `fetchAsString`
+ * and `unknownTypesAsString` are the two with a cost worth knowing
+ * about - see `fetchAsString` in QueryOptions.
+ */
+export type ConnectionMappingDefaults = DataMappingOptions & Pick<QueryOptions, 'objectRows' | 'rowDecoder' | 'typeMap' | 'columnFormat'>;
+export interface ConnectionConfiguration extends DatabaseConnectionParams, SocketOptions, ConnectionMappingDefaults {
     buffer?: SmartBufferConfig;
+    /**
+     * Whether statements may share a connection with statements already in
+     * flight - the default for every call here, which
+     * `QueryOptions.pipeline` overrides per statement and describes in
+     * full.
+     *
+     * Defaults to **on for a `Connection`** (what one has always done) and
+     * **off for a `Pool`**, where sharing also means running on a
+     * connection other callers are using. `true` on a pool turns it on for
+     * every query that can take it; `false` on a connection gives the
+     * behaviour of a client that waits for each reply before sending the
+     * next statement.
+     */
+    pipeline?: boolean;
 }
 export interface PoolConfiguration extends ConnectionConfiguration, LPoolConfiguration {
     /**
@@ -162,10 +188,11 @@ export interface PoolConfiguration extends ConnectionConfiguration, LPoolConfigu
      * ceiling on connections - with the default pool of 10, a burst of 1000
      * queries no longer has to run as 100 sequential rounds of 10.
      *
-     * Set to 1 for the older behaviour, where Pool.query() holds a
-     * connection exclusively for the duration of each query. Connections
-     * handed out by acquire() are never shared, whatever this is set to, so
-     * transactions, cursors and prepared statements are unaffected.
+     * Only queries that asked to be pipelined are counted, since sharing a
+     * pooled connection is opt-in - see `pipeline`. Setting this to 1 is
+     * the other way to turn it off. Connections handed out by acquire()
+     * are never shared whatever either is set to, so transactions, cursors
+     * and prepared statements are unaffected.
      */
     pipelineMaxQueries?: number;
     /**

package/interfaces/query-options.d.ts

@@ -9,6 +9,38 @@ export interface QueryOptions extends DataMappingOptions {
      * @default true
      */
     autoCommit?: boolean;
+    /**
+     * Whether this statement may share a connection with statements that
+     * are already in flight.
+     *
+     * PostgreSQL correlates responses to requests by order, so several
+     * statements can be on the wire at once, each under its own Sync and
+     * therefore with its own error boundary.
+     *
+     * **The default differs by where the statement runs, because the two
+     * places are not the same question:**
+     *
+     * - On a `Connection`, **on**. The connection is the caller's own, and
+     *   concurrent `query()` calls on one have always overlapped this way.
+     * - On a `Pool`, **off**. Here it also decides *which* connection the
+     *   statement runs on: sharing puts it on a connection other callers
+     *   are using, where session state - `SET`, an advisory lock, a
+     *   temporary table - is no longer the caller's alone. That is opt-in,
+     *   per call or with `pipeline: true` on the pool.
+     *
+     * `false` asks for the wire to itself: the statement waits until
+     * nothing else is running on the connection, and nothing else starts
+     * until it finishes, whichever mode those asked for. Nothing orders
+     * two pipelined statements against each other, so this is how a
+     * statement that depends on what another one left behind says so.
+     *
+     * Some statements never share a *pooled* connection however this is
+     * set, because they need one to themselves for longer than the call:
+     * anything carrying an `AbortSignal`, anything with
+     * `autoCommit: false`, a cursor, and SQL that opens a transaction or a
+     * COPY. On a `Connection` the setting is only about the wire.
+     */
+    pipeline?: boolean;
     /**
      * Specifies if rows will be fetched as <FieldName, Value> pair objects or array of values
      * @deprecated Use `rowDecoder: 'object'` instead - `objectRows: true` still works exactly

package/interfaces/script-execute-options.d.ts

@@ -7,6 +7,38 @@ export interface ScriptExecuteOptions extends DataMappingOptions {
      * @default true
      */
     autoCommit?: boolean;
+    /**
+     * Whether this statement may share a connection with statements that
+     * are already in flight.
+     *
+     * PostgreSQL correlates responses to requests by order, so several
+     * statements can be on the wire at once, each under its own Sync and
+     * therefore with its own error boundary.
+     *
+     * **The default differs by where the statement runs, because the two
+     * places are not the same question:**
+     *
+     * - On a `Connection`, **on**. The connection is the caller's own, and
+     *   concurrent `query()` calls on one have always overlapped this way.
+     * - On a `Pool`, **off**. Here it also decides *which* connection the
+     *   statement runs on: sharing puts it on a connection other callers
+     *   are using, where session state - `SET`, an advisory lock, a
+     *   temporary table - is no longer the caller's alone. That is opt-in,
+     *   per call or with `pipeline: true` on the pool.
+     *
+     * `false` asks for the wire to itself: the statement waits until
+     * nothing else is running on the connection, and nothing else starts
+     * until it finishes, whichever mode those asked for. Nothing orders
+     * two pipelined statements against each other, so this is how a
+     * statement that depends on what another one left behind says so.
+     *
+     * Some statements never share a *pooled* connection however this is
+     * set, because they need one to themselves for longer than the call:
+     * anything carrying an `AbortSignal`, anything with
+     * `autoCommit: false`, a cursor, and SQL that opens a transaction or a
+     * COPY. On a `Connection` the setting is only about the wire.
+     */
+    pipeline?: boolean;
     /**
      * Specifies if rows will be fetched as <FieldName, Value> pair objects or array of values
      * @deprecated Use `rowDecoder: 'object'` instead - `objectRows: true` still works exactly

package/interfaces/transaction-options.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The modes PostgreSQL takes on the `BEGIN` itself.
+ *
+ * Setting them this way is one round trip where `BEGIN` followed by
+ * `SET TRANSACTION` is two - measured at 0.500ms against 0.740ms for
+ * opening and closing one isolated transaction, which is most of what a
+ * short transaction costs.
+ *
+ * `SET TRANSACTION SNAPSHOT` is deliberately absent: PostgreSQL does not
+ * accept it on `BEGIN`, so it still needs a statement of its own.
+ */
+export interface TransactionOptions {
+    /**
+     * What this transaction may see of the ones running beside it.
+     * Defaults to the server's `default_transaction_isolation`, which is
+     * `read committed` unless the server says otherwise.
+     */
+    isolationLevel?: 'serializable' | 'repeatable read' | 'read committed' | 'read uncommitted';
+    /** Refuses anything that would write, at the server. */
+    readOnly?: boolean;
+    /**
+     * Lets a `serializable` `readOnly` transaction wait until it can run
+     * without the serialization failures that level otherwise risks -
+     * ignored by the server for any other combination.
+     */
+    deferrable?: boolean;
+}

package/interfaces/transaction-options.js

@@ -0,0 +1 @@
+export {};

package/package.json

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

package/protocol/database-error.d.ts

@@ -16,6 +16,21 @@ export declare class DatabaseError extends Error {
      * explicit transaction was already open they are rolled back with it.
      */
     batchResults?: BatchCommandResult[];
+    /**
+     * The message exactly as PostgreSQL sent it.
+     *
+     * `message` is decorated where the server reported a position - the
+     * line and column, the offending source line and a caret under it -
+     * which is what makes an error readable in a terminal with no extra
+     * work, and would otherwise leave nothing holding the original. A
+     * consumer that parses the text needs the original: PostgreSQL does
+     * not always put the interesting part in a field, so an anchored
+     * pattern like `/^column (.+) does not exist$/` is how the column name
+     * is read, and a suffix defeats it.
+     *
+     * Always set, and equal to `message` when nothing was decorated.
+     */
+    readonly serverMessage: string;
     severity?: string;
     code?: string;
     detail?: string;

package/protocol/database-error.js

@@ -15,6 +15,21 @@ export class DatabaseError extends Error {
      * explicit transaction was already open they are rolled back with it.
      */
     batchResults;
+    /**
+     * The message exactly as PostgreSQL sent it.
+     *
+     * `message` is decorated where the server reported a position - the
+     * line and column, the offending source line and a caret under it -
+     * which is what makes an error readable in a terminal with no extra
+     * work, and would otherwise leave nothing holding the original. A
+     * consumer that parses the text needs the original: PostgreSQL does
+     * not always put the interesting part in a field, so an anchored
+     * pattern like `/^column (.+) does not exist$/` is how the column name
+     * is read, and a suffix defeats it.
+     *
+     * Always set, and equal to `message` when nothing was decorated.
+     */
+    serverMessage;
     severity;
     code;
     detail;
@@ -41,5 +56,9 @@ export class DatabaseError extends Error {
         });
         if (msg.position)
             this.position = parseInt(msg.position, 10) || undefined;
+        // Read off `message` rather than off `msg`, and after the assign
+        // above, so the two cannot drift apart - whatever this error was
+        // built to say, before anything decorates it.
+        this.serverMessage = this.message;
     }
 }

package/protocol/frontend.js

@@ -1,9 +1,9 @@
 import { DEFAULT_COLUMN_FORMAT } from '../constants.js';
 import { DataTypeMap } from '../data-type-map.js';
+import { arrayLeaf } from '../util/array-leaf.js';
 import { encodeBinaryArray } from '../util/encode-binaryarray.js';
 import { formatDateParam } from '../util/format-datetime.js';
 import { stringifyArrayLiteral } from '../util/stringify-arrayliteral.js';
-import { arrayLeaf } from '../util/unspecified-param.js';
 import { Protocol } from './protocol.js';
 import { SmartBuffer } from './smart-buffer.js';
 const DataFormat = Protocol.DataFormat;

package/protocol/pg-socket.js

@@ -899,16 +899,13 @@ export class PgSocket extends SafeEventEmitter {
             socket.write(data, cb);
             return true;
         }
-        socket.cork();
-        try {
-            const l = data.length;
-            let i;
-            for (i = 0; i < l; i++)
-                socket.write(data[i], i === l - 1 ? cb : undefined);
-        }
-        finally {
-            socket.uncork();
-        }
+        // Joined rather than written one by one under a cork: a statement is
+        // three messages (Bind, Execute, Sync) of a few dozen bytes, and a
+        // write apiece costs three trips through the stream machinery - a
+        // WriteReq, a buffer entry, a cork/uncork pair - to save a copy of
+        // 43 bytes. Measured at 50 concurrent queries, 150 writes against
+        // 50.
+        socket.write(data.length === 1 ? data[0] : Buffer.concat(data), cb);
         return true;
     }
     /**

package/util/array-leaf.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The first value inside `v` that is neither an array nor null - what an
+ * array's element type is read from. A scalar answers itself, and an
+ * array with nothing but nulls (or nothing at all) answers `undefined`.
+ *
+ * Reading `v[0]` instead is wrong twice over: `[[1, 2], [3, 4]]` asks
+ * what type `[1, 2]` is, and `[null, 2, 3]` asks what type `null` is.
+ * Neither has an answer, and both are ordinary values to send.
+ */
+export declare function arrayLeaf(v: any): any;

package/util/array-leaf.js

@@ -0,0 +1,22 @@
+/**
+ * The first value inside `v` that is neither an array nor null - what an
+ * array's element type is read from. A scalar answers itself, and an
+ * array with nothing but nulls (or nothing at all) answers `undefined`.
+ *
+ * Reading `v[0]` instead is wrong twice over: `[[1, 2], [3, 4]]` asks
+ * what type `[1, 2]` is, and `[null, 2, 3]` asks what type `null` is.
+ * Neither has an answer, and both are ordinary values to send.
+ */
+export function arrayLeaf(v) {
+    if (!Array.isArray(v))
+        return v;
+    const l = v.length;
+    let i;
+    let x;
+    for (i = 0; i < l; i++) {
+        x = arrayLeaf(v[i]);
+        if (x != null)
+            return x;
+    }
+    return undefined;
+}

package/util/connection-config.js

@@ -61,6 +61,16 @@ function splitHosts(value, fallbackPort) {
         return { host: entry, port: fallbackPort };
     });
 }
+/**
+ * The schemes whose path is the database name.
+ *
+ * PostgreSQL gives two URI forms of its own, `postgres://` and
+ * `postgresql://`, and the longer one is what Prisma, TypeORM and most
+ * tutorials write - it was missing here, so a string naming a database
+ * connected to the default one instead, with nothing reported. `pg:`
+ * has been accepted for longer than either and stays.
+ */
+const DATABASE_PATH_SCHEMES = ['pg:', 'postgres:', 'postgresql:'];
 export function parseConnectionString(str) {
     if (str.startsWith('/'))
         str = 'socket:/' + str;
@@ -89,7 +99,7 @@ export function parseConnectionString(str) {
         if (parsed.searchParams.get('db'))
             cfg.database = decodeURI(getFirst(parsed.searchParams.get('db')));
     }
-    else if (parsed.protocol === 'pg:' || parsed.protocol === 'postgres:') {
+    else if (DATABASE_PATH_SCHEMES.includes(parsed.protocol)) {
         if (parsed.pathname)
             cfg.database = decodeURI(parsed.pathname.substring(1));
     }

package/util/date-style.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The session's `DateStyle`, when it is not the ISO default.
+ *
+ * PostgreSQL renders a date four ways, and the client cannot tell which
+ * one it is looking at from the string alone - `05.03.2024` is the fifth
+ * of March in every style that prints it, but `05/03/2024` is the fifth
+ * of March under `SQL, DMY` and the third of May under `SQL, MDY`. The
+ * server reports `DateStyle` in its startup parameters and again on
+ * every `SET`, so the convention is known rather than guessed.
+ *
+ * Measured against PostgreSQL 18.4, one value in every combination:
+ *
+ * ```
+ * ISO,      any    2024-11-25 01:02:03.456        2024-03-05
+ * SQL,      MDY    11/25/2024 01:02:03.456 UTC    03/05/2024
+ * SQL,      DMY    25/11/2024 01:02:03.456 UTC    05/03/2024
+ * Postgres, MDY    Mon Nov 25 01:02:03.456 2024   03-05-2024
+ * Postgres, DMY    Mon 25 Nov 01:02:03.456 2024   05-03-2024
+ * German,   any    25.11.2024 01:02:03.456 UTC    05.03.2024
+ * ```
+ *
+ * Two things in that table are not what the setting's name suggests:
+ * German ignores the field order entirely, and `YMD` prints as `MDY`
+ * for every style. Both are read off the measurement rather than off
+ * the documentation.
+ */
+export interface PgDateStyle {
+    style: 'SQL' | 'Postgres' | 'German';
+    /** Whether the numeric day comes before the month. */
+    dayFirst: boolean;
+}
+/**
+ * The `DateStyle` the server reported, or undefined for ISO - which is
+ * the default, is what every existing parser here expects, and is the
+ * one shape that needs no extra work.
+ */
+export declare function parseDateStyleSetting(value: string | undefined): PgDateStyle | undefined;
+/**
+ * Reads a date or timestamp the server rendered in `style`.
+ *
+ * Returns undefined when the string is not that style's shape - a `BC`
+ * year, an `infinity`, or a zone abbreviation nobody can resolve - so
+ * the caller decides what to do with it. What it must never do is guess:
+ * handing `05.03.2024` to `new Date()` is how the fifth of March became
+ * the third of May, silently, for every day of the month up to twelve.
+ */
+export declare function parseStyledDateTime(str: string, style: PgDateStyle, utc?: boolean): Date | undefined;

package/util/date-style.js

@@ -0,0 +1,123 @@
+const MONTHS = {
+    jan: 0,
+    feb: 1,
+    mar: 2,
+    apr: 3,
+    may: 4,
+    jun: 5,
+    jul: 6,
+    aug: 7,
+    sep: 8,
+    oct: 9,
+    nov: 10,
+    dec: 11,
+};
+/**
+ * `Postgres` style: a weekday, then the month and day in the configured
+ * order, the time, the year, and for timestamptz a zone.
+ */
+const POSTGRES_PATTERN = /^[A-Za-z]{3} (?:([A-Za-z]{3}) (\d{1,2})|(\d{1,2}) ([A-Za-z]{3})) (\d{2}):(\d{2}):(\d{2})(?:\.(\d+))? (\d{1,6})(?: (.+))?$/;
+/** `SQL` and `German`: three numbers, a time, and for timestamptz a zone. */
+const NUMERIC_PATTERN = /^(\d{1,2})([./])(\d{1,2})\2(\d{1,6})(?: (\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?)?(?: (.+))?$/;
+/** `Postgres` style writes a date on its own with dashes. */
+const POSTGRES_DATE_PATTERN = /^(\d{1,2})-(\d{1,2})-(\d{1,6})$/;
+/**
+ * The `DateStyle` the server reported, or undefined for ISO - which is
+ * the default, is what every existing parser here expects, and is the
+ * one shape that needs no extra work.
+ */
+export function parseDateStyleSetting(value) {
+    if (!value)
+        return undefined;
+    const comma = value.indexOf(',');
+    const style = (comma < 0 ? value : value.substring(0, comma)).trim();
+    if (style === 'ISO')
+        return undefined;
+    if (style !== 'SQL' && style !== 'Postgres' && style !== 'German')
+        return undefined;
+    const order = comma < 0 ? '' : value.substring(comma + 1).trim();
+    // German prints day-first whatever the order says, and YMD prints as
+    // MDY - both measured, neither obvious.
+    return { style, dayFirst: style === 'German' || order === 'DMY' };
+}
+/**
+ * The offset a rendered zone stands for, in minutes, or undefined when
+ * it cannot be known.
+ *
+ * Outside ISO the server writes the zone's *abbreviation* where it has
+ * one - `EST`, `IST` - and those do not identify an offset: IST is India
+ * at +05:30, Israel at +02:00 and Ireland at +01:00. A numeric offset
+ * and UTC/GMT are exact, and anything else is refused rather than
+ * guessed at.
+ */
+function zoneOffsetMinutes(zone) {
+    if (zone === 'UTC' || zone === 'GMT' || zone === 'Z')
+        return 0;
+    const m = /^([+-])(\d{1,2})(?::?(\d{2}))?$/.exec(zone);
+    if (!m)
+        return undefined;
+    const sign = m[1] === '-' ? -1 : 1;
+    return sign * (+m[2] * 60 + (m[3] ? +m[3] : 0));
+}
+function build(y, mon, d, h, mi, s, ms, offsetMinutes, utc) {
+    if (offsetMinutes !== undefined)
+        return new Date(Date.UTC(y, mon, d, h, mi - offsetMinutes, s, ms));
+    if (utc)
+        return new Date(Date.UTC(y, mon, d, h, mi, s, ms));
+    return new Date(y, mon, d, h, mi, s, ms);
+}
+function fraction(f) {
+    return f ? +(f + '000').slice(0, 3) : 0;
+}
+/**
+ * Reads a date or timestamp the server rendered in `style`.
+ *
+ * Returns undefined when the string is not that style's shape - a `BC`
+ * year, an `infinity`, or a zone abbreviation nobody can resolve - so
+ * the caller decides what to do with it. What it must never do is guess:
+ * handing `05.03.2024` to `new Date()` is how the fifth of March became
+ * the third of May, silently, for every day of the month up to twelve.
+ */
+export function parseStyledDateTime(str, style, utc) {
+    // Every style writes it the same way, and it is not a date.
+    if (str.endsWith(' BC'))
+        return undefined;
+    if (style.style === 'Postgres') {
+        const m = POSTGRES_PATTERN.exec(str);
+        if (m) {
+            const mon = MONTHS[(m[1] || m[4]).toLowerCase()];
+            if (mon === undefined)
+                return undefined;
+            const day = +(m[2] || m[3]);
+            let offset;
+            if (m[10]) {
+                offset = zoneOffsetMinutes(m[10]);
+                if (offset === undefined)
+                    return undefined;
+            }
+            return build(+m[9], mon, day, +m[5], +m[6], +m[7], fraction(m[8]), offset, utc);
+        }
+        const d = POSTGRES_DATE_PATTERN.exec(str);
+        if (!d)
+            return undefined;
+        const day = +(style.dayFirst ? d[1] : d[2]);
+        const mon = +(style.dayFirst ? d[2] : d[1]) - 1;
+        return build(+d[3], mon, day, 0, 0, 0, 0, undefined, utc);
+    }
+    const m = NUMERIC_PATTERN.exec(str);
+    if (!m)
+        return undefined;
+    // German writes dots and SQL writes slashes; a string using the other
+    // one is not this session's rendering and is not read as if it were.
+    if (m[2] !== (style.style === 'German' ? '.' : '/'))
+        return undefined;
+    const day = +(style.dayFirst ? m[1] : m[3]);
+    const mon = +(style.dayFirst ? m[3] : m[1]) - 1;
+    let offset;
+    if (m[9]) {
+        offset = zoneOffsetMinutes(m[9]);
+        if (offset === undefined)
+            return undefined;
+    }
+    return build(+m[4], mon, day, m[5] ? +m[5] : 0, m[6] ? +m[6] : 0, m[7] ? +m[7] : 0, fraction(m[8]), offset, utc);
+}

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

@@ -0,0 +1,11 @@
+import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
+import type { Maybe, OID } from '../types.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 declare const DecimalAsStringOIDs: readonly OID[];
+/** Whether this type's values are wanted as their exact decimal string. */
+export declare function wantsDecimalString(options: Maybe<DataMappingOptions>, oid: OID): boolean;
+export declare function validateDecimalAsString(v: Maybe<boolean | OID[]>): void;