postgrejs 3.5.0 → 3.6.0

package/data-type-map.d.ts

@@ -3,6 +3,17 @@ import type { OID } from './types.js';
 export declare class DataTypeMap {
     private _itemsByOID;
     private _items;
+    /**
+     * Copies another map, so a connection can start from GlobalTypeMap and
+     * override a type or two without touching the global one.
+     *
+     * Both indexes have to be copied. `_items` alone is what `determine()`
+     * walks, but every decode goes through `get()`, which reads
+     * `_itemsByOID` - a copy carrying only the first one answers `undefined`
+     * for every OID, and get-parsers.ts then falls back to its default
+     * parser, handing the caller raw Buffers instead of decoded values with
+     * nothing reported.
+     */
     constructor(other?: DataTypeMap);
     get(oid: OID): DataType;
     register(dataTypes: DataType | DataType[]): void;

package/data-type-map.js

@@ -26,9 +26,22 @@ import { ArrayVarcharType, VarcharType } from './data-types/varchar-type.js';
 export class DataTypeMap {
     _itemsByOID = {};
     _items = [];
+    /**
+     * Copies another map, so a connection can start from GlobalTypeMap and
+     * override a type or two without touching the global one.
+     *
+     * Both indexes have to be copied. `_items` alone is what `determine()`
+     * walks, but every decode goes through `get()`, which reads
+     * `_itemsByOID` - a copy carrying only the first one answers `undefined`
+     * for every OID, and get-parsers.ts then falls back to its default
+     * parser, handing the caller raw Buffers instead of decoded values with
+     * nothing reported.
+     */
     constructor(other) {
-        if (other instanceof DataTypeMap)
-            Object.assign(this._items, other._items);
+        if (other instanceof DataTypeMap) {
+            this._items = [...other._items];
+            this._itemsByOID = { ...other._itemsByOID };
+        }
     }
     get(oid) {
         return this._itemsByOID[oid];
@@ -52,6 +65,11 @@ export class DataTypeMap {
         let t;
         for (i = this._items.length - 1; i >= 0; i--) {
             t = this._items[i];
+            // Walked newest-registered first, so a later registration of the
+            // same OID wins - and a type marked `inferrable: false` is never
+            // picked here at all, however well `isType` matches.
+            if (t.inferrable === false)
+                continue;
             if (valueIsArray) {
                 if (t.elementsOID && t.isType(value[0]))
                     return t.oid;

package/data-types/char-type.js

@@ -21,6 +21,21 @@ export const CharType = {
     isType(v) {
         return typeof v === 'string' && Buffer.byteLength(v, 'utf8') === 1;
     },
+    /**
+     * 18 is PostgreSQL's internal single-byte `"char"`, not `char(n)` and
+     * not `varchar`. A one-character JavaScript string fits it, which is why
+     * `isType` says so, but nobody passing `'A'` to a query means that type:
+     * inference used to answer 18 for every such value and declare the
+     * parameter `"char"` to the server.
+     *
+     * Comparisons and inserts survived on an implicit cast, but concatenation
+     * had no single obvious one - `select code || $1` answered `operator is
+     * not unique: character varying || "char"` - and an array was worse
+     * still. determine() types an array from its first element alone, so
+     * `['A', 'BB', 'CCC']` became `_char` and came back `['A', 'B', 'C']`,
+     * every later element cut to one byte with nothing reported.
+     */
+    inferrable: false,
 };
 export const ArrayCharType = {
     ...CharType,

package/data-types/date-type.js

@@ -30,22 +30,18 @@ export const DateType = {
         buf.writeInt32BE(t);
     },
     decodeBinary(v, offset = 0, _len, options) {
-        const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.date);
         const t = v.readInt32BE(offset);
         if (t === 0x7fffffff)
-            return fetchAsString ? 'infinity' : Infinity;
+            return Infinity;
         if (t === -0x80000000)
-            return fetchAsString ? '-infinity' : -Infinity;
+            return -Infinity;
         // Shift from 2000 to 1970
         let d = new Date(t * 1000 * 86400 + timeShift);
-        if (fetchAsString || !options.utcDates)
+        if (!options.utcDates)
             d = new Date(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
-        return fetchAsString ? dateToDateString(d) : d;
+        return d;
     },
     decodeText(v, options) {
-        const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.date);
-        if (fetchAsString)
-            return v;
         return parseDate(v, options.utcDates);
     },
     decodeTextBuffer(buf, offset, len, options) {
@@ -59,16 +55,6 @@ export const DateType = {
             v.getMilliseconds() === 0);
     },
 };
-function padZero(v) {
-    return v < 9 ? '0' + v : '' + v;
-}
-function dateToDateString(d) {
-    return (d.getFullYear() +
-        '-' +
-        padZero(d.getMonth() + 1) +
-        '-' +
-        padZero(d.getDate()));
-}
 export const ArrayDateType = {
     ...DateType,
     name: '_date',

package/data-types/float4-type.js

@@ -12,7 +12,7 @@ export const Float4Type = {
         buf.writeFloatBE(typeof v === 'number' ? v : assertCoercedNumber(parseFloat(v), 'float4'));
     },
     decodeBinary(v, offset = 0) {
-        return v.readFloatBE(offset);
+        return shortestFloat4(v.readFloatBE(offset));
     },
     decodeText: parseFloat,
     decodeTextBuffer: fastParseFloatBuffer,
@@ -26,3 +26,81 @@ export const ArrayFloat4Type = {
     oid: DataTypeOIDs._float4,
     elementsOID: DataTypeOIDs.float4,
 };
+/**
+ * Powers of ten that a double holds exactly. Past 1e22 the literal is
+ * already rounded, and scaling by it stops being a faithful operation.
+ */
+const POW10 = [
+    1, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13, 1e14,
+    1e15, 1e16, 1e17, 1e18, 1e19, 1e20, 1e21, 1e22,
+];
+/**
+ * The shortest decimal that reads back as this same float4.
+ *
+ * A float4 arrives as four bytes and widens into a double that spells out
+ * the binary approximation in full: the column PostgreSQL prints as `1.1`
+ * read back as `1.100000023841858`. The text path never had the problem,
+ * since the server does this itself before sending - so the same column
+ * answered differently depending on a wire format the caller may not know
+ * is there, and the binary default was the wrong-looking one.
+ *
+ * Nine significant digits always round-trip a binary32 and most values
+ * need far fewer, so this tries successively longer forms and takes the
+ * first that reads back unchanged. Integers inside +-2^24 are already
+ * exact in float4 and skip the search; past that they are not (1e20
+ * widens to 100000002004087730000) so the bound matters. Infinities and
+ * NaN have no decimal to shorten.
+ *
+ * Rounding by hand, rather than through toPrecision(), is what makes it
+ * affordable - 24ns a value against 115ns, measured, because toPrecision()
+ * costs four times what the engine's own shortest-form toString does and
+ * there is no cheaper built-in. Scaling by a power of ten is only faithful
+ * while both the digits and the power are exact in a double: the digits
+ * always are at nine or fewer, and the magnitude check keeps the power
+ * inside its own exact range. A value sitting exactly halfway is left to
+ * the string path as well - Math.round() breaks those ties away from zero
+ * and dtoa breaks them to even, and the disagreement would show. Checked
+ * against the string path over 299,007 values, structured and random:
+ * same answer every time.
+ */
+function shortestFloat4(n) {
+    if (!Number.isFinite(n))
+        return n;
+    if (Number.isInteger(n) && n >= -16777216 && n <= 16777216)
+        return n;
+    const abs = n < 0 ? -n : n;
+    // Two comparisons keep log10 and the loop off the path entirely for
+    // magnitudes whose power of ten could not be exact anyway.
+    if (abs >= 1e-14 && abs < 1e28) {
+        const e = Math.floor(Math.log10(abs));
+        let digits;
+        let k;
+        let pow;
+        let scaled;
+        let rounded;
+        let candidate;
+        for (digits = 7; digits <= 9; digits++) {
+            k = digits - 1 - e;
+            // Unreachable for the magnitudes let through above unless log10()
+            // lands a step out at a boundary, which it is entitled to do.
+            if (k < -22 || k > 22)
+                break;
+            pow = POW10[k < 0 ? -k : k];
+            scaled = k >= 0 ? n * pow : n / pow;
+            rounded = Math.round(scaled);
+            if (scaled - rounded === 0.5 || rounded - scaled === 0.5)
+                break;
+            candidate = k >= 0 ? rounded / pow : rounded * pow;
+            if (Math.fround(candidate) === n)
+                return candidate;
+        }
+    }
+    let p;
+    let s;
+    for (p = 7; p <= 9; p++) {
+        s = Number(n.toPrecision(p));
+        if (Math.fround(s) === n)
+            return s;
+    }
+    return n;
+}

package/data-types/json-type.js

@@ -3,11 +3,8 @@ export const JsonType = {
     name: 'json',
     oid: DataTypeOIDs.json,
     jsType: 'string',
-    decodeBinary(v, offset = 0, len, options) {
+    decodeBinary(v, offset = 0, len) {
         const content = v.toString('utf8', offset, offset + len);
-        const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.json);
-        if (fetchAsString)
-            return content;
         return content ? JSON.parse(content) : undefined;
     },
     // json is stored as the text itself, so its binary form is those bytes.
@@ -25,19 +22,17 @@ export const JsonType = {
             return v ? 'true' : 'false';
         return '' + v;
     },
-    decodeText(v, options) {
-        const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.json);
-        if (fetchAsString)
-            return v;
-        return v ? JSON.parse(v) : null;
-    },
-    decodeTextBuffer(buf, offset, len, options) {
-        return JsonType.decodeText(buf.toString('utf8', offset, offset + len), options);
+    decodeText: decodeJsonText,
+    decodeTextBuffer(buf, offset, len) {
+        return decodeJsonText(buf.toString('utf8', offset, offset + len));
     },
     isType(v) {
         return v && typeof v === 'object';
     },
 };
+function decodeJsonText(v) {
+    return v ? JSON.parse(v) : null;
+}
 export const ArrayJsonType = {
     ...JsonType,
     name: '_json',

package/data-types/jsonb-type.js

@@ -14,32 +14,27 @@ export const JsonbType = {
         buf.writeUInt8(1);
         buf.writeString(JsonbType.encodeText(v, {}), 'utf8');
     },
-    decodeBinary(v, offset = 0, len, options) {
+    decodeBinary(v, offset = 0, len) {
         // jsonb's binary form is a one-byte version followed by the JSON text,
         // which carries no terminator of its own - so its end is whatever
         // `len` says, not the end of the buffer it happens to sit in.
         if (v[offset] !== 1)
             throw new Error('Unexpected Jsonb version value in header');
         const content = v.toString('utf8', offset + 1, offset + len);
-        const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.jsonb);
-        if (fetchAsString)
-            return content;
         return content ? JSON.parse(content) : undefined;
     },
-    decodeText(v, options) {
-        const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.jsonb);
-        if (fetchAsString)
-            return v;
-        return v ? JSON.parse(v) : null;
-    },
+    decodeText: decodeJsonbText,
     // See json-type.ts's decodeTextBuffer comment - same rationale.
-    decodeTextBuffer(buf, offset, len, options) {
-        return JsonbType.decodeText(buf.toString('utf8', offset, offset + len), options);
+    decodeTextBuffer(buf, offset, len) {
+        return decodeJsonbText(buf.toString('utf8', offset, offset + len));
     },
     isType(v) {
         return v && typeof v === 'object';
     },
 };
+function decodeJsonbText(v) {
+    return v ? JSON.parse(v) : null;
+}
 export const ArrayJsonbType = {
     ...JsonbType,
     name: '_jsonb',

package/data-types/time-type.js

@@ -25,18 +25,15 @@ export const TimeType = {
         buf.writeUInt32BE(lo);
     },
     decodeBinary(v, offset = 0, _len, options) {
-        const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.time);
         const hi = v.readInt32BE(offset);
         const lo = v.readUInt32BE(offset + 4);
         let d = new Date((lo + hi * timeMul) / 1000);
-        if (fetchAsString || !options.utcDates) {
+        if (!options.utcDates) {
             d = new Date(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), d.getUTCMilliseconds());
         }
-        return fetchAsString ? dateToTimeString(d) : d;
+        return d;
     },
     decodeText(v, options) {
-        if (options.fetchAsString?.includes(DataTypeOIDs.time))
-            return v;
         return parseTime(v, false, options.utcDates);
     },
     // See date-type.ts's decodeTextBuffer comment - same rationale.
@@ -51,16 +48,6 @@ export const TimeType = {
             (typeof v === 'string' && STRICT_TIME_PATTERN.test(v)));
     },
 };
-function padZero(v) {
-    return v < 9 ? '0' + v : '' + v;
-}
-function dateToTimeString(d) {
-    return (padZero(d.getHours()) +
-        ':' +
-        padZero(d.getMinutes()) +
-        ':' +
-        padZero(d.getSeconds()));
-}
 export const ArrayTimeType = {
     ...TimeType,
     name: '_time',

package/data-types/timestamp-type.js

@@ -37,33 +37,28 @@ export const TimestampType = {
         buf.writeUInt32BE(lo);
     },
     decodeBinary(v, offset = 0, _len, options) {
-        const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.timestamp);
         const hi = v.readInt32BE(offset);
         const lo = v.readUInt32BE(offset + 4);
         if (lo === 0xffffffff && hi === 0x7fffffff)
-            return fetchAsString ? 'infinity' : Infinity;
+            return Infinity;
         if (lo === 0x00000000 && hi === -0x80000000)
-            return fetchAsString ? '-infinity' : -Infinity;
+            return -Infinity;
         // Shift from 2000 to 1970
         let d = new Date((lo + hi * timeMul) / 1000 + timeShift);
-        if (fetchAsString || !options.utcDates) {
+        if (!options.utcDates) {
             d = new Date(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), d.getUTCMilliseconds());
         }
-        return fetchAsString ? dateToTimestampString(d) : d;
+        return d;
     },
     decodeText(v, options) {
-        if (options.fetchAsString?.includes(DataTypeOIDs.timestamp))
-            return v;
         return parseDateTime(v, options.utcDates);
     },
     // Reads PostgreSQL's own timestamp shape straight from the wire bytes -
-    // see timestamptz-type.ts's decodeTextBuffer for why. The two guards are
-    // what decodeText()/parseDateTime() would have applied anyway: with
-    // fetchAsString the raw string is the answer, and with utcDates the
-    // string has to go through the regex path that reads it as UTC.
+    // see timestamptz-type.ts's decodeTextBuffer for why. The guard is what
+    // decodeText()/parseDateTime() would have applied anyway: with utcDates
+    // the string has to go through the regex path that reads it as UTC.
     decodeTextBuffer(buf, offset, len, options) {
-        if (!options.utcDates &&
-            !options.fetchAsString?.includes(DataTypeOIDs.timestamp)) {
+        if (!options.utcDates) {
             const d = parsePgTimestampBuffer(buf, offset, offset + len);
             if (d !== undefined)
                 return d;
@@ -79,22 +74,6 @@ export const TimestampType = {
             !(v.getFullYear() === 1970 && v.getMonth() === 0 && v.getDate() === 1));
     },
 };
-function padZero(v) {
-    return v < 9 ? '0' + v : '' + v;
-}
-function dateToTimestampString(d) {
-    return (d.getFullYear() +
-        '-' +
-        padZero(d.getMonth() + 1) +
-        '-' +
-        padZero(d.getDate()) +
-        ' ' +
-        padZero(d.getHours()) +
-        ':' +
-        padZero(d.getMinutes()) +
-        ':' +
-        padZero(d.getSeconds()));
-}
 export const ArrayTimestampType = {
     ...TimestampType,
     name: '_timestamp',

package/data-types/timestamptz-type.js

@@ -34,14 +34,13 @@ export const TimestamptzType = {
         buf.writeInt32BE(hi);
         buf.writeUInt32BE(lo);
     },
-    decodeBinary(v, offset = 0, _len, options) {
-        const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.timestamptz);
+    decodeBinary(v, offset = 0) {
         const hi = v.readInt32BE(offset);
         const lo = v.readUInt32BE(offset + 4);
         if (lo === 0xffffffff && hi === 0x7fffffff)
-            return fetchAsString ? 'infinity' : Infinity;
+            return Infinity;
         if (lo === 0x00000000 && hi === -0x80000000)
-            return fetchAsString ? '-infinity' : -Infinity;
+            return -Infinity;
         // Shift from 2000 to 1970. A timestamptz is an absolute instant, so
         // this is already the value - there is nothing to reinterpret against
         // the local zone the way `timestamp` (which carries no zone of its
@@ -51,23 +50,10 @@ export const TimestamptzType = {
         // ambiguous read as wall-clock, so the rebuild silently picked the
         // other one and moved the value an hour. The text path never did that,
         // so the same row decoded binary and text disagreed.
-        const d = new Date((lo + hi * timeMul) / 1000 + timeShift);
-        return fetchAsString ? dateToTimestamptzString(d) : d;
+        return new Date((lo + hi * timeMul) / 1000 + timeShift);
     },
     decodeText(v, options) {
-        const d = parseDateTimeTz(v, options.utcDates);
-        if (options.fetchAsString?.includes(DataTypeOIDs.timestamptz)) {
-            if (d instanceof Date)
-                return dateToTimestamptzString(d);
-            if (d === Infinity)
-                return 'infinity';
-            if (d === -Infinity)
-                return '-infinity';
-            // parseDateTimeTz() only ever returns a Date, Infinity or -Infinity,
-            // never anything else, so this is unreachable.
-            return '';
-        }
-        return d;
+        return parseDateTimeTz(v, options.utcDates);
     },
     // Reads PostgreSQL's own timestamp shape straight from the wire bytes.
     // Building the string first and handing it to decodeText() costs about
@@ -75,26 +61,16 @@ export const TimestamptzType = {
     // scanned a character at a time. Anything not in that exact shape
     // (infinity, a BC suffix, an LMT-style offset) has no Date to give back
     // and takes the original path, which still needs the string.
-    //
-    // Note this type's decodeText always parses first and only branches on
-    // fetchAsString afterward (unlike date/time/timestamp, which early-return
-    // the raw string), so the same order is kept here.
     decodeTextBuffer(buf, offset, len, options) {
         const d = parsePgTimestampBuffer(buf, offset, offset + len);
-        if (d !== undefined) {
-            return options.fetchAsString?.includes(DataTypeOIDs.timestamptz)
-                ? dateToTimestamptzString(d)
-                : d;
-        }
+        if (d !== undefined)
+            return d;
         return TimestamptzType.decodeText(buf.toString('latin1', offset, offset + len), options);
     },
     isType(v) {
         return v instanceof Date;
     },
 };
-function dateToTimestamptzString(d) {
-    return d.toISOString().replace('T', ' ');
-}
 export const ArrayTimestamptzType = {
     ...TimestamptzType,
     name: '_timestamptz',

package/interfaces/batch-result.d.ts

@@ -8,7 +8,7 @@ import type { FieldInfo } from './field-info.js';
 export interface BatchCommandResult {
     /** The command tag PostgreSQL reported for this set (INSERT/UPDATE/...). */
     command?: string;
-    /** Rows affected, for INSERT/UPDATE/DELETE - as in QueryResult. */
+    /** Rows affected, for INSERT/UPDATE/DELETE/MERGE - as in QueryResult. */
     rowsAffected?: number;
     /**
      * Rows this set returned, decoded the same way `execute()` decodes them

package/interfaces/command-result.d.ts

@@ -24,7 +24,27 @@ export interface CommandResult {
      */
     executeTime?: number;
     /**
-     * How many rows affected
+     * True when the server stopped at the `fetchCount` limit instead of
+     * running the statement to completion: the portal suspended and the rows
+     * behind it were never fetched, so `rows` is a prefix rather than the
+     * whole result.
+     *
+     * Only ever set when an explicit `fetchCount` was given - the default
+     * asks for every row. Note the server does not look ahead: a statement
+     * whose result is exactly `fetchCount` rows long suspends too, so this
+     * means "the limit was reached", not "there are definitely more rows".
+     *
+     * Use a Cursor when the point is to read a large result in batches; a
+     * suspended portal on this path is simply discarded by the Sync that
+     * follows.
+     */
+    suspended?: boolean;
+    /**
+     * How many rows the statement changed, for INSERT/UPDATE/DELETE/MERGE
+     * (MERGE reports its own total of inserted, updated and deleted rows,
+     * and needs PostgreSQL 15+). Left undefined for every other command,
+     * including SELECT - the count those report describes rows returned or
+     * moved, not rows affected.
      */
     rowsAffected?: number;
 }

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

@@ -5,5 +5,21 @@ export interface DataMappingOptions {
      * @default false
      */
     utcDates?: boolean;
+    /**
+     * OIDs whose columns are to be handed back exactly as the server renders
+     * them, instead of being converted to a JavaScript value.
+     *
+     * This is a wire-level request, not a formatting choice made here: the
+     * listed columns are asked for in PostgreSQL's text format and returned
+     * unparsed, so the string is the server's own and nothing can drift
+     * between the two. Bind's result format codes are positional, though, so
+     * the OIDs can only be mapped onto columns once their types are known -
+     * 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.
+     */
     fetchAsString?: OID[];
 }

package/interfaces/data-type.d.ts

@@ -7,6 +7,17 @@ export interface DataType {
     jsType: string;
     arraySeparator?: string;
     isType: (v: any) => boolean;
+    /**
+     * Whether DataTypeMap.determine() may pick this type for a value, which
+     * it does by asking `isType`. Defaults to true.
+     *
+     * `false` is for a type that can genuinely hold the value - so `isType`
+     * answers truthfully for anyone who asks it directly - but that no
+     * caller means when they pass a plain JavaScript value. Inference then
+     * passes it by and the type is reached only by asking for it, with
+     * `new BindParam(oid, value)`.
+     */
+    inferrable?: boolean;
     decodeBinary: DecodeBinaryFunction;
     decodeText: DecodeTextFunction;
     decodeTextBuffer?: DecodeTextBufferFunction;

package/interfaces/query-options.d.ts

@@ -37,7 +37,15 @@ export interface QueryOptions extends DataMappingOptions {
      */
     typeMap?: DataTypeMap;
     /**
-     * If true, returns Cursor instance instead of rows
+     * If true, returns Cursor instance instead of rows.
+     *
+     * The cursor reads through a portal, and a portal lives only as long as
+     * the transaction that created it. Outside an explicit transaction that
+     * is the implicit one, which any other statement on the same connection
+     * ends - so running another query on that connection while the cursor is
+     * open destroys it. Open the cursor inside a transaction, or give it a
+     * connection of its own; `Pool.query()` does the latter for you and
+     * keeps the connection out of the pool until the cursor closes.
      */
     cursor?: boolean;
     /**
@@ -50,8 +58,22 @@ export interface QueryOptions extends DataMappingOptions {
      */
     columnFormat?: DataFormat | DataFormat[];
     /**
-     * Specifies how many rows will be fetched. For Cursor, this value specifies how many rows will be fetched in a batch
-     * @default 100
+     * Maximum number of rows to fetch.
+     *
+     * `query()` fetches every row by default. Giving an explicit limit stops
+     * the server at that many rows and leaves the rest unfetched: `rows` is
+     * then a prefix and `suspended` is set on the result to say so. There is
+     * no way to ask for the remainder afterwards - the portal is discarded
+     * by the Sync that closes the call - so use a Cursor when the point is
+     * to read a large result a piece at a time.
+     *
+     * For a Cursor this is the batch size instead: how many rows each fetch
+     * asks for, defaulting to 100, with the cursor itself walking the whole
+     * result.
+     *
+     * 0 means unlimited, as it does in the protocol.
+     *
+     * @default 0 for query(), 100 for a Cursor's batches
      */
     fetchCount?: number;
     /**

package/package.json

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

package/protocol/frontend.d.ts

@@ -20,6 +20,13 @@ export declare namespace Frontend {
         paramTypes?: Maybe<OID>[];
         params?: any[];
         queryOptions: QueryOptions;
+        /**
+         * Result format codes to write, overriding queryOptions.columnFormat.
+         * Set by callers that know the statement's column types and have
+         * turned fetchAsString's OID list into positional codes - see
+         * resolveColumnFormats().
+         */
+        columnFormat?: Protocol.DataFormat | Protocol.DataFormat[];
     }
     interface ParseMessageArgs {
         statement?: string;

package/protocol/frontend.js

@@ -133,9 +133,11 @@ export class Frontend {
         io.writeCString(args.portal || '', 'utf8');
         io.writeCString(args.statement || '', 'utf8');
         const { params, paramTypes, queryOptions } = args;
-        const columnFormat = queryOptions.columnFormat != null
-            ? queryOptions.columnFormat
-            : DEFAULT_COLUMN_FORMAT;
+        const columnFormat = args.columnFormat != null
+            ? args.columnFormat
+            : queryOptions.columnFormat != null
+                ? queryOptions.columnFormat
+                : DEFAULT_COLUMN_FORMAT;
         if (params && params.length) {
             io.writeInt16BE(params.length);
             const formatOffset = io.position;

package/util/channel-name.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Checks a LISTEN/NOTIFY channel name and answers with the name the server
+ * will actually use for it.
+ *
+ * The name is written into LISTEN/UNLISTEN as an identifier, and an
+ * identifier can never be a parameter - so it goes through
+ * escapeIdentifier() at the call site rather than being restricted to a
+ * pattern. Any name PostgreSQL accepts then works, one-character and
+ * underscore-leading names included, which the old `/^[A-Z]\w+$/i` guard
+ * refused.
+ *
+ * Quoting alone would change what a name means, though, which is what this
+ * function is for: `LISTEN Foo` unquoted subscribes to `foo`, and every
+ * notification for it comes back as `foo`. Callers were registering their
+ * callback under the name they passed and never hearing from it - any
+ * channel name that was not already lower case was silently dead. Folding
+ * the same way the server would keeps the registration key and the name
+ * the server reports the same string, and keeps `NOTIFY Foo` written by
+ * hand on the other side reaching a `listen('Foo')` here.
+ *
+ * A name that could not have been written unquoted (a space, a dash) has
+ * no folding question to answer and is passed through as it is.
+ */
+export declare function normalizeChannelName(channel: string): string;