postgrejs 3.6.1 → 3.8.0

package/protocol/pg-socket.js

@@ -644,7 +644,13 @@ export class PgSocket extends SafeEventEmitter {
         const reason = this._state === ConnectionState.CLOSING
             ? undefined
             : this._buildCloseReason();
-        this._failPendingCaptures(new Error('Connection closed'));
+        // Whatever was in flight is rejected with the same object the 'close'
+        // event carries, so `err.code === '08006'` works in a caller's catch
+        // exactly as it does in a Pool listener - the generic message it used
+        // to get named no cause and carried no code at all. A close that was
+        // asked for keeps that message: nothing went wrong, the caller simply
+        // raced the shutdown.
+        this._failPendingCaptures(reason ?? new Error('Connection closed'));
         this._reset();
         this._socket = undefined;
         this._state = ConnectionState.CLOSED;
@@ -658,7 +664,15 @@ export class PgSocket extends SafeEventEmitter {
         // here and the fact of closing separately, and only the pair together
         // says what actually happened.
         this._closeReason = err instanceof Error ? err : new Error(String(err));
-        this._failPendingCaptures(this._closeReason);
+        // An error on a live connection is that connection going away - Node
+        // always follows 'error' with 'close' - so the caller gets the same
+        // ConnectionLostError the close will carry, with this as its cause,
+        // rather than a raw ECONNRESET whose `code` is a Node errno where a
+        // SQLSTATE is expected. Before READY there is no connection to have
+        // lost, and the error itself is the useful thing.
+        this._failPendingCaptures(this._state === ConnectionState.READY
+            ? this._buildCloseReason()
+            : this._closeReason);
         if (this._state !== ConnectionState.READY) {
             this._socket?.end();
         }

package/util/decode-binaryarray.js

@@ -38,7 +38,14 @@ export function decodeBinaryArray(buf, offset, decoder, options = {}) {
     };
     for (let d = 0; d < ndims; d++) {
         dims[d] = io.readInt32BE();
-        io.readInt32BE(); // LBound
+        // The lower bound is read and dropped, deliberately. A server-side
+        // array really can have a non-default one, and a JavaScript array is
+        // always 0-based, so carrying it would mean deciding what a decoded
+        // array is supposed to represent - a wider change than the encoder's.
+        // Note that this is also what hid the encoder writing 0: a value
+        // written and read back through this client looked right, and only
+        // SQL against the stored value saw the difference.
+        io.readInt32BE();
     }
     return readDim(0);
 }

package/util/encode-binaryarray.d.ts

@@ -1,4 +1,15 @@
 import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { SmartBuffer } from '../protocol/smart-buffer.js';
 import type { EncodeBinaryFunction, EncodeCalculateDimFunction, OID } from '../types.js';
-export declare function encodeBinaryArray(io: SmartBuffer, value: any[], itemOid: OID, options: DataMappingOptions, encode: EncodeBinaryFunction, encodeCalculateDimFn?: EncodeCalculateDimFunction): void;
+/**
+ * Writes an array in the binary wire format.
+ *
+ * `lowerBound` is the index the first element answers to in SQL, and it
+ * is 1 for every ordinary array - `array_lower('{1,2}'::int4[], 1)` is
+ * 1, and a value written with 0 comes back subscripted from 0, so
+ * `arr[1]` is its *second* element and `::text` renders the
+ * explicit-bounds form `[0:2]={…}`. `oidvector` and `int2vector` are the
+ * exception and really are 0-based - confirmed against the catalog,
+ * `array_lower(pg_index.indkey, 1)` is 0 - so they pass 0 themselves.
+ */
+export declare function encodeBinaryArray(io: SmartBuffer, value: any[], itemOid: OID, options: DataMappingOptions, encode: EncodeBinaryFunction, encodeCalculateDimFn?: EncodeCalculateDimFunction, lowerBound?: number): void;

package/util/encode-binaryarray.js

@@ -1,6 +1,17 @@
 import { DataTypeOIDs } from '../constants.js';
 import { arrayCalculateDim } from './array-calculatedim.js';
-export function encodeBinaryArray(io, value, itemOid, options, encode, encodeCalculateDimFn) {
+/**
+ * Writes an array in the binary wire format.
+ *
+ * `lowerBound` is the index the first element answers to in SQL, and it
+ * is 1 for every ordinary array - `array_lower('{1,2}'::int4[], 1)` is
+ * 1, and a value written with 0 comes back subscripted from 0, so
+ * `arr[1]` is its *second* element and `::text` renders the
+ * explicit-bounds form `[0:2]={…}`. `oidvector` and `int2vector` are the
+ * exception and really are 0-based - confirmed against the catalog,
+ * `array_lower(pg_index.indkey, 1)` is 0 - so they pass 0 themselves.
+ */
+export function encodeBinaryArray(io, value, itemOid, options, encode, encodeCalculateDimFn, lowerBound = 1) {
     encodeCalculateDimFn = encodeCalculateDimFn || arrayCalculateDim;
     itemOid = itemOid || DataTypeOIDs.varchar;
     const dim = encodeCalculateDimFn(value);
@@ -12,7 +23,7 @@ export function encodeBinaryArray(io, value, itemOid, options, encode, encodeCal
     let d;
     for (d = 0; d < ndims; d++) {
         io.writeInt32BE(dim[d]); // Number of items in dimension
-        io.writeInt32BE(0); // LBound always 0.
+        io.writeInt32BE(lowerBound); // Index the first element answers to
     }
     let hasNull = false;
     let pos;

package/util/format-datetime.d.ts

@@ -8,3 +8,21 @@ export declare function formatTimestamp(v: Date | number | string, options?: Dat
  * ignores `utcDates`, which only governs the zone-less types.
  */
 export declare function formatTimestamptz(v: Date | number | string): string;
+/**
+ * A `Date` as a parameter, rendered the way `pg` renders one: the wall
+ * clock in the process's own zone, followed by that zone's offset.
+ *
+ * It is the only rendering that is right for both column kinds at once,
+ * which is why the parameter path uses it instead of declaring a type.
+ * A `timestamptz` column honours the offset and stores the instant; a
+ * `timestamp` column discards it and keeps the wall clock - so the
+ * server decides, from the column, what one JavaScript `Date` could
+ * never say on its own. Declaring `timestamp` instead moved the instant
+ * by the client's offset, and declaring `timestamptz` moved the wall
+ * clock by it; measured against `pg` in three session zones, this
+ * matches in all six.
+ *
+ * Under `utcDates` the UTC components go out with a zero offset, which
+ * is the same rule the zone-less encoders follow.
+ */
+export declare function formatDateParam(v: Date | number | string, options?: DataMappingOptions): string;

package/util/format-datetime.js

@@ -69,3 +69,36 @@ export function formatTimestamptz(v) {
         return d;
     return d.toISOString().replace('T', ' ').replace('Z', '+00');
 }
+/**
+ * A `Date` as a parameter, rendered the way `pg` renders one: the wall
+ * clock in the process's own zone, followed by that zone's offset.
+ *
+ * It is the only rendering that is right for both column kinds at once,
+ * which is why the parameter path uses it instead of declaring a type.
+ * A `timestamptz` column honours the offset and stores the instant; a
+ * `timestamp` column discards it and keeps the wall clock - so the
+ * server decides, from the column, what one JavaScript `Date` could
+ * never say on its own. Declaring `timestamp` instead moved the instant
+ * by the client's offset, and declaring `timestamptz` moved the wall
+ * clock by it; measured against `pg` in three session zones, this
+ * matches in all six.
+ *
+ * Under `utcDates` the UTC components go out with a zero offset, which
+ * is the same rule the zone-less encoders follow.
+ */
+export function formatDateParam(v, options) {
+    const d = coerce(v);
+    if (typeof d === 'string')
+        return d;
+    const p = parts(d, options);
+    const clock = `${pad(p.year, 4)}-${pad(p.month)}-${pad(p.day)}` +
+        ` ${pad(p.hour)}:${pad(p.minute)}:${pad(p.second)}.${pad(p.ms, 3)}`;
+    if (options?.utcDates)
+        return clock + '+00:00';
+    // getTimezoneOffset() counts minutes west of UTC, the opposite way
+    // round from how an offset is written.
+    const offset = -d.getTimezoneOffset();
+    const sign = offset < 0 ? '-' : '+';
+    const abs = Math.abs(offset);
+    return `${clock}${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+}

package/util/parse-array.js

@@ -21,13 +21,28 @@ export function parsePostgresArray(s, opts) {
                     continue;
                 }
                 if (c === '}' || c === sep) {
-                    if (token) {
+                    // An element is present when it had content OR when it was
+                    // quoted: `""` is a real empty string, and testing the token
+                    // alone dropped it - `{"",b}` came back as one element, with
+                    // every later index shifted.
+                    //
+                    // An unquoted empty token is still skipped. PostgreSQL never
+                    // emits one (a null prints as the bare word NULL, an empty
+                    // string always as `""`), so `{a,,b}` is not output this has to
+                    // read - and skipping it is what keeps the separator that
+                    // follows a nested array from pushing an element of its own.
+                    if (token || exactlyValue) {
                         if (token === 'NULL' && !exactlyValue)
                             arr.push(null);
                         else
                             arr.push(transform ? transform(token) : token);
-                        exactlyValue = false;
                     }
+                    // Reset per element rather than only when one was pushed.
+                    // Leaving it set carried "this one was quoted" into the next
+                    // element - and that flag is what tells a real NULL apart from
+                    // the string "NULL", so a null following an empty string
+                    // decoded as four characters of text.
+                    exactlyValue = false;
                     token = '';
                     if (c === '}')
                         return;

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

@@ -1,3 +1,4 @@
+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';
@@ -23,7 +24,7 @@ export interface ColumnFormatOptions extends DataMappingOptions {
  * 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): Protocol.DataFormat | Protocol.DataFormat[];
+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

package/util/resolve-column-formats.js

@@ -1,6 +1,18 @@
 import { DEFAULT_COLUMN_FORMAT } from '../constants.js';
 import { Protocol } from '../protocol/protocol.js';
 const DataFormat = Protocol.DataFormat;
+/**
+ * Whether this client could read the column if it arrived in `format`.
+ * Only ever answers no for binary: a column with no registered type at
+ * all still decodes as text, into the string the server printed, which is
+ * the whole point of asking for it that way.
+ */
+function canDecode(typeMap, oid, format) {
+    if (format !== DataFormat.binary)
+        return true;
+    const reg = typeMap.get(oid);
+    return !!reg && typeof reg.decodeBinary === 'function';
+}
 /**
  * Turns `fetchAsString`'s OID list into the positional result format codes
  * a Bind message actually carries.
@@ -20,28 +32,43 @@ const DataFormat = Protocol.DataFormat;
  * Returns `columnFormat` untouched when there is nothing to do, so the
  * common case allocates nothing and keeps sending a single format code.
  */
-export function resolveColumnFormats(fields, options) {
+export function resolveColumnFormats(fields, options, typeMap) {
     const base = options.columnFormat != null ? options.columnFormat : DEFAULT_COLUMN_FORMAT;
     const asString = options.fetchAsString;
-    if (!fields || !asString || !asString.length)
+    // unknownTypesAsString needs the type map to answer "could this be
+    // decoded", so it is inert without one - the call sites that have no
+    // map in hand are the ones that have no fields either.
+    const unknownAsString = !!options.unknownTypesAsString && !!typeMap;
+    const named = !!asString && asString.length > 0;
+    if (!fields || (!named && !unknownAsString))
         return base;
     const l = fields.length;
     const baseIsArray = Array.isArray(base);
     const out = new Array(l);
     let hit = false;
     let i;
+    let oid;
+    let format;
     for (i = 0; i < l; i++) {
-        if (asString.includes(fields[i].dataTypeId)) {
+        oid = fields[i].dataTypeId;
+        format = baseIsArray
+            ? (base[i] ?? DEFAULT_COLUMN_FORMAT)
+            : base;
+        if (named && asString.includes(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.
-            out[i] = DataFormat.text;
+            format = DataFormat.text;
+            hit = true;
+        }
+        else if (unknownAsString && !canDecode(typeMap, oid, format)) {
+            // Nothing here could read the binary, so the bytes would reach the
+            // caller as a Buffer. Text at least arrives as what the server
+            // printed.
+            format = DataFormat.text;
             hit = true;
         }
-        else
-            out[i] = baseIsArray
-                ? (base[i] ?? DEFAULT_COLUMN_FORMAT)
-                : base;
+        out[i] = format;
     }
     return hit ? out : base;
 }

package/util/sql-tag.js

@@ -2,6 +2,9 @@ import { BindParam } from '../connection/bind-param.js';
 import { DataTypeMap, GlobalTypeMap } from '../data-type-map.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';
 /**
  * A statement built by the `sql` tag: its text with the values pulled out.
  *
@@ -171,6 +174,18 @@ function encodeLiteral(value, typeMap, options) {
     }
     if (v == null)
         return 'null';
+    // A Date and a string go in bare, exactly as they go out as
+    // parameters with no declared type (see unspecified-param.ts): an
+    // unadorned literal is `unknown` and takes the type of wherever it
+    // lands. The cast this path adds everywhere else is what keeps
+    // query() and execute() meaning the same thing, and for these two it
+    // is what would break that - `'{"a":1}'::varchar` is refused by a
+    // json column that takes the parameter without complaint.
+    if (oid == null && isUnspecifiedParam(v)) {
+        if (!Array.isArray(v))
+            return escapeLiteral(v instanceof Date ? formatDateParam(v, options) : '' + v);
+        return escapeLiteral(stringifyArrayLiteral(v, options, arrayLeaf(v) instanceof Date ? formatDateParam : undefined));
+    }
     oid = oid ?? typeMap.determine(v);
     /* c8 ignore start - typeMap.determine() always falls back to the
        "unknown" oid rather than returning null/undefined, so this can't

package/util/stringify-for-sql.js

@@ -1,9 +1,42 @@
+import { DataTypeOIDs } from '../constants.js';
+import { GlobalTypeMap } from '../data-type-map.js';
 import { UuidType } from '../data-types/uuid-type.js';
 import { escapeLiteral } from './escape-literal.js';
+import { formatDateParam } from './format-datetime.js';
 export function stringifyArrayForSQL(v, options, encode) {
     const arr = v.map(x => stringifyValueForSQL(x, options, encode));
     return 'ARRAY[' + arr.join(',') + ']';
 }
+/**
+ * Which type an object is is asked rather than assumed.
+ *
+ * Every geometric class, Interval, Range, Date and Buffer has a
+ * 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",...}`.
+ */
+function stringifyObjectForSQL(v, options) {
+    // determine() throws for a class that must carry a type OID and does
+    // not - a Range built without one - and that throw is deliberate: the
+    // alternative is writing a literal for a type nobody chose.
+    const oid = GlobalTypeMap.determine(v);
+    const dataType = GlobalTypeMap.get(oid);
+    // json and jsonb are the fallback below; reaching them through their
+    // own encodeText would only add a cast the literal does not need.
+    // Anything with no registered text encoder lands there too.
+    if (dataType?.encodeText &&
+        oid !== DataTypeOIDs.json &&
+        oid !== DataTypeOIDs.jsonb)
+        return (escapeLiteral(dataType.encodeText(v, options || {})) +
+            '::' +
+            dataType.name);
+    return escapeLiteral(JSON.stringify(v)) + '::json';
+}
 export function stringifyValueForSQL(v, options, encode) {
     if (v == null)
         return 'null';
@@ -19,7 +52,17 @@ export function stringifyValueForSQL(v, options, encode) {
         return v.toString();
     if (typeof v === 'string' && UuidType.isType(v))
         return escapeLiteral('' + v) + '::uuid';
+    // A Date is written bare, with its offset and no cast, so that it
+    // means the same inlined as it does bound - the server resolves it
+    // from the column either way. See format-datetime.ts's
+    // formatDateParam().
+    if (v instanceof Date)
+        return escapeLiteral(formatDateParam(v, options));
     if (typeof v === 'object')
-        return escapeLiteral(JSON.stringify(v)) + '::json';
+        return stringifyObjectForSQL(v, options);
+    // A string is deliberately written bare. determine() would answer
+    // varchar, but an unadorned literal is `unknown` and takes the type of
+    // wherever it lands - `insert into t(n) values('5')` works and
+    // `'5'::varchar` would not.
     return escapeLiteral('' + v);
 }

package/util/unspecified-param.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ *
+ * Two kinds of value cannot say what they are:
+ *
+ * - A `Date` is an instant or a wall clock depending on the column, and
+ *   declaring either one moves the other. See `format-datetime.ts`.
+ * - A string is whichever of PostgreSQL's text-input types the context
+ *   calls for. `determine()` answers `varchar`, and declaring that stops
+ *   the server inferring: `insert into t(j) values($1)` into a `json`
+ *   column, `id = $1` against a `uuid`, `coalesce($1, 1)` and an enum
+ *   column all fail with "expression is of type character varying".
+ *   Unspecified, every one of them works.
+ *
+ * This is what `pg` sends for both, and the divergence from it is what
+ * the shapes above were failing on. It is not free: a parameter with no
+ * context to be resolved from - `$1 is null`, `array_agg($1)`,
+ * `concat($1, 1)` - now raises "could not determine data type", exactly
+ * 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.
+ */
+export declare function isUnspecifiedParam(v: any): boolean;

package/util/unspecified-param.js

@@ -0,0 +1,40 @@
+/**
+ * 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;
+}
+/**
+ * Whether a parameter goes out with no declared type (OID 0), as text,
+ * for the server to resolve from wherever it lands.
+ *
+ * Two kinds of value cannot say what they are:
+ *
+ * - A `Date` is an instant or a wall clock depending on the column, and
+ *   declaring either one moves the other. See `format-datetime.ts`.
+ * - A string is whichever of PostgreSQL's text-input types the context
+ *   calls for. `determine()` answers `varchar`, and declaring that stops
+ *   the server inferring: `insert into t(j) values($1)` into a `json`
+ *   column, `id = $1` against a `uuid`, `coalesce($1, 1)` and an enum
+ *   column all fail with "expression is of type character varying".
+ *   Unspecified, every one of them works.
+ *
+ * This is what `pg` sends for both, and the divergence from it is what
+ * the shapes above were failing on. It is not free: a parameter with no
+ * context to be resolved from - `$1 is null`, `array_agg($1)`,
+ * `concat($1, 1)` - now raises "could not determine data type", exactly
+ * 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.
+ */
+export function isUnspecifiedParam(v) {
+    const x = arrayLeaf(v);
+    return typeof x === 'string' || x instanceof Date;
+}