postgrejs 3.8.0 → 3.10.0

package/util/temporal.js

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+let _systemTimeZone;
+const _knownZones = new Set();
+/**
+ * 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 function getTemporal() {
+    const t = globalThis.Temporal;
+    if (!t || !t.ZonedDateTime)
+        throw new Error('Temporal is not available in this runtime. postgrejs reads ' +
+            'globalThis.Temporal and takes no dependency of its own: install ' +
+            '`temporal-polyfill` and import it before connecting, or leave ' +
+            '`temporalTypes` off.');
+    return t;
+}
+/**
+ * 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 function systemTimeZone() {
+    if (_systemTimeZone === undefined)
+        _systemTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return _systemTimeZone;
+}
+/**
+ * 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 function requireTimeZone(zone, where) {
+    if (_knownZones.has(zone))
+        return zone;
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: zone });
+    }
+    catch {
+        throw new Error(`"${zone}" (${where}) is not a time zone this runtime knows, so a ` +
+            'timestamptz cannot be given one. Pass `timeZone` in the mapping ' +
+            'options to name one yourself.');
+    }
+    _knownZones.add(zone);
+    return zone;
+}

package/util/transaction-command.d.ts

@@ -0,0 +1,7 @@
+/** Whether `sql` opens or closes a transaction. */
+export declare function isTransactionCommand(sql: string): boolean;
+/**
+ * Whether `sql` must not run inside a savepoint - it is a transaction
+ * command, or it configures the transaction.
+ */
+export declare function refusesSavepoint(sql: string): boolean;

package/util/transaction-command.js

@@ -0,0 +1,32 @@
+/**
+ * Statements that open or close a transaction, and so manage their own
+ * boundaries: an implicit BEGIN or COMMIT around one would be wrong, and
+ * wrapping one in a savepoint - COMMIT, say - is nonsense.
+ */
+const TRANSACTION_COMMAND_PATTERN = /^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i;
+/**
+ * `SET TRANSACTION`, which configures the transaction it runs in rather
+ * than opening or closing one.
+ *
+ * It needs an answer of its own because the two are not the same
+ * question. PostgreSQL refuses two of its forms inside a subtransaction
+ * - `SET TRANSACTION ISOLATION LEVEL` and `SET TRANSACTION [NOT]
+ * DEFERRABLE`, both 25001 - so the savepoint `rollbackOnError` puts
+ * around every statement in a transaction made them impossible to run
+ * at all. But the implicit BEGIN that `autoCommit: false` adds is
+ * exactly what they need, so answering "transaction command" for them
+ * and suppressing both would trade one failure for another.
+ */
+const CONFIGURES_TRANSACTION_PATTERN = /^\bSET\s+TRANSACTION\b/i;
+/** Whether `sql` opens or closes a transaction. */
+export function isTransactionCommand(sql) {
+    return TRANSACTION_COMMAND_PATTERN.test(sql);
+}
+/**
+ * Whether `sql` must not run inside a savepoint - it is a transaction
+ * command, or it configures the transaction.
+ */
+export function refusesSavepoint(sql) {
+    return (TRANSACTION_COMMAND_PATTERN.test(sql) ||
+        CONFIGURES_TRANSACTION_PATTERN.test(sql));
+}

package/util/unspecified-param.d.ts

@@ -1,8 +1,3 @@
-/**
- * The first value inside `v` that is not itself an array - what an array
- * parameter's element type would be read from. A scalar answers itself.
- */
-export declare function arrayLeaf(v: any): any;
 /**
  * Whether a parameter goes out with no declared type (OID 0), as text,
  * for the server to resolve from wherever it lands.
@@ -25,8 +20,23 @@ export declare function arrayLeaf(v: any): any;
  * as it does under `pg`. A cast (`$1::text`) or a named type
  * (`new BindParam(DataTypeOIDs.varchar, v)`) says which type is meant.
  *
- * Numbers, booleans and Buffers keep their declared types: they are
- * already right nearly everywhere, and sending them as text would give
- * up the binary encoding for no correctness gain.
+ * - An array of numbers is the same question, and the answer matters
+ *   more: `[1, 2]` is `int2[]`, `int4[]`, `int8[]`, `numeric[]`,
+ *   `float4[]` or `float8[]` depending on where it lands, and unlike
+ *   their scalars those types have no operators or implicit casts
+ *   between them. A declared `int4[]` is therefore not merely a guess
+ *   but a wrong answer wherever the column is one of the other five:
+ *   `array[1,2]::int8[] = $1` is `42883 operator does not exist:
+ *   bigint[] = integer[]`, and `numeric[] = double precision[]` the
+ *   same. The scalars are left declared because they do have those
+ *   operators - `1::int8 = $1` and `1.5::numeric = $1` both resolve.
+ *
+ * A scalar number, a boolean, a Buffer, and an array of anything but
+ * numbers keep their declared types: an array of booleans, of Buffers
+ * or of one of this client's own classes has one type it can be, so
+ * naming it says nothing the server would have decided differently -
+ * and it keeps the binary encoding, which the text literal gives up.
+ * A caller who wants that back for a large numeric array names the type
+ * with `new BindParam(DataTypeOIDs._float8, v)`.
  */
 export declare function isUnspecifiedParam(v: any): boolean;

package/util/unspecified-param.js

@@ -1,13 +1,4 @@
-/**
- * The first value inside `v` that is not itself an array - what an array
- * parameter's element type would be read from. A scalar answers itself.
- */
-export function arrayLeaf(v) {
-    let x = v;
-    while (Array.isArray(x))
-        x = x[0];
-    return x;
-}
+import { arrayLeaf } from './array-leaf.js';
 /**
  * Whether a parameter goes out with no declared type (OID 0), as text,
  * for the server to resolve from wherever it lands.
@@ -30,11 +21,28 @@ export function arrayLeaf(v) {
  * as it does under `pg`. A cast (`$1::text`) or a named type
  * (`new BindParam(DataTypeOIDs.varchar, v)`) says which type is meant.
  *
- * Numbers, booleans and Buffers keep their declared types: they are
- * already right nearly everywhere, and sending them as text would give
- * up the binary encoding for no correctness gain.
+ * - An array of numbers is the same question, and the answer matters
+ *   more: `[1, 2]` is `int2[]`, `int4[]`, `int8[]`, `numeric[]`,
+ *   `float4[]` or `float8[]` depending on where it lands, and unlike
+ *   their scalars those types have no operators or implicit casts
+ *   between them. A declared `int4[]` is therefore not merely a guess
+ *   but a wrong answer wherever the column is one of the other five:
+ *   `array[1,2]::int8[] = $1` is `42883 operator does not exist:
+ *   bigint[] = integer[]`, and `numeric[] = double precision[]` the
+ *   same. The scalars are left declared because they do have those
+ *   operators - `1::int8 = $1` and `1.5::numeric = $1` both resolve.
+ *
+ * A scalar number, a boolean, a Buffer, and an array of anything but
+ * numbers keep their declared types: an array of booleans, of Buffers
+ * or of one of this client's own classes has one type it can be, so
+ * naming it says nothing the server would have decided differently -
+ * and it keeps the binary encoding, which the text literal gives up.
+ * A caller who wants that back for a large numeric array names the type
+ * with `new BindParam(DataTypeOIDs._float8, v)`.
  */
 export function isUnspecifiedParam(v) {
     const x = arrayLeaf(v);
-    return typeof x === 'string' || x instanceof Date;
+    if (typeof x === 'string' || x instanceof Date)
+        return true;
+    return Array.isArray(v) && (typeof x === 'number' || typeof x === 'bigint');
 }