postgrejs 3.8.0 → 3.9.0

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/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.

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.