postgrejs 3.4.0 → 3.6.0

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.4.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/protocol/pg-socket.d.ts

@@ -119,9 +119,9 @@ export declare class PgSocket extends SafeEventEmitter {
      */
     sendPipelineMessages(args: {
         statements: {
-            parse: Frontend.ParseMessageArgs;
+            parse?: Frontend.ParseMessageArgs;
             bind: Frontend.BindMessageArgs;
-            describe: Frontend.DescribeMessageArgs;
+            describe?: Frontend.DescribeMessageArgs;
             execute: Frontend.ExecuteMessageArgs;
         }[];
     }, cb: CaptureCallback): Promise<any>;

package/protocol/pg-socket.js

@@ -280,17 +280,23 @@ export class PgSocket extends SafeEventEmitter {
      */
     sendPipelineMessages(args, cb) {
         const l = args.statements.length;
-        const data = new Array(l * 4 + 1);
+        const data = [];
         let i;
         let st;
         for (i = 0; i < l; i++) {
             st = args.statements[i];
-            data[i * 4] = this._frontend.getParseMessage(st.parse);
-            data[i * 4 + 1] = this._frontend.getBindMessage(st.bind);
-            data[i * 4 + 2] = this._frontend.getDescribeMessage(st.describe);
-            data[i * 4 + 3] = this._frontend.getExecuteMessage(st.execute);
+            // Parse and Describe are both optional: a statement bound to one the
+            // connection has already prepared needs neither, since the server
+            // still holds the plan and IntlConnection still holds the
+            // RowDescription that came with it.
+            if (st.parse)
+                data.push(this._frontend.getParseMessage(st.parse));
+            data.push(this._frontend.getBindMessage(st.bind));
+            if (st.describe)
+                data.push(this._frontend.getDescribeMessage(st.describe));
+            data.push(this._frontend.getExecuteMessage(st.execute));
         }
-        data[l * 4] = this._frontend.getSyncMessage();
+        data.push(this._frontend.getSyncMessage());
         return this._sendAndCapture(data, cb, 'sendPipelineMessages', args);
     }
     /**

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;

package/util/channel-name.js

@@ -0,0 +1,44 @@
+/**
+ * PostgreSQL folds an unquoted identifier to lower case and takes a quoted
+ * one literally. A LISTEN channel name is an identifier, so this is the
+ * shape that would have been folded had it been written unquoted.
+ */
+const UNQUOTED_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+/** NAMEDATALEN - 1. */
+const MAX_CHANNEL_BYTES = 63;
+/**
+ * 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 function normalizeChannelName(channel) {
+    if (typeof channel !== 'string' || !channel.length)
+        throw new TypeError('Channel name must be a non-empty string');
+    if (channel.indexOf('\0') >= 0)
+        throw new TypeError('Channel name cannot contain NUL (\\0) bytes');
+    // Refused rather than passed on: the server truncates a longer
+    // identifier instead of rejecting it, so LISTEN would subscribe to a
+    // name the caller never asked for and every notification would arrive
+    // under that one - the same silent mismatch as the case folding above.
+    if (Buffer.byteLength(channel, 'utf8') > MAX_CHANNEL_BYTES)
+        throw new TypeError(`Channel name cannot be longer than ${MAX_CHANNEL_BYTES} bytes`);
+    return UNQUOTED_IDENTIFIER.test(channel) ? channel.toLowerCase() : channel;
+}

package/util/get-parsers.d.ts

@@ -1,4 +1,5 @@
 import type { DataTypeMap } from '../data-type-map.js';
+import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { Protocol } from '../protocol/protocol.js';
 import type { AnyParseFunction } from '../types.js';
-export declare function getParsers(typeMap: DataTypeMap, fields: Protocol.RowDescription[]): AnyParseFunction[];
+export declare function getParsers(typeMap: DataTypeMap, fields: Protocol.RowDescription[], mappingOptions?: DataMappingOptions): AnyParseFunction[];

package/util/get-parsers.js

@@ -3,13 +3,28 @@ import { decodeBinaryArray } from './decode-binaryarray.js';
 import { parsePostgresArray } from './parse-array.js';
 const DefaultColumnParser = (data, offset, len) => data.subarray(offset, offset + len);
 const DefaultTextColumnParser = (data, offset, len) => data.toString('utf8', offset, offset + len);
-export function getParsers(typeMap, fields) {
+export function getParsers(typeMap, fields, mappingOptions) {
     const parsers = new Array(fields.length);
+    const asString = mappingOptions?.fetchAsString;
     const l = fields.length;
     let f;
     let i;
     for (i = 0; i < l; i++) {
         f = fields[i];
+        // fetchAsString asks for the value exactly as the server renders it,
+        // and resolveColumnFormats() has already asked the server to send this
+        // column as text - so there is nothing left to do but hand the bytes
+        // back. An array column only reaches here when its own array OID was
+        // listed, and then the whole literal is the string that comes back.
+        // The format check is not redundant: a column can still arrive binary
+        // when its types were unknown at Bind time (a pipelined one-shot), and
+        // then the registered decoder is the only thing that can read it.
+        if (asString &&
+            f.format === DataFormat.text &&
+            asString.includes(f.dataTypeId)) {
+            parsers[i] = DefaultTextColumnParser;
+            continue;
+        }
         const dataTypeReg = typeMap.get(f.dataTypeId);
         if (dataTypeReg) {
             const isArray = !!dataTypeReg.elementsOID;

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

@@ -0,0 +1,33 @@
+import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
+import { Protocol } from '../protocol/protocol.js';
+import type { Maybe, OID } from '../types.js';
+export interface ColumnFormatOptions extends DataMappingOptions {
+    columnFormat?: Protocol.DataFormat | Protocol.DataFormat[];
+}
+/**
+ * Turns `fetchAsString`'s OID list into the positional result format codes
+ * a Bind message actually carries.
+ *
+ * The protocol has no way to say "send this OID as text" - Bind's result
+ * format codes are per column, by position, and nothing in Parse/Bind is
+ * keyed on a type. So the OID list can only be honored once the column
+ * types are known, which means after a Describe and before the Bind that
+ * asks for them. Callers that already hold a RowDescription (a prepared
+ * statement's, or a cached one's) pay nothing for this; callers that do
+ * not have to ask for the whole row as text instead - see queryOnce().
+ *
+ * A column matches on its own `dataTypeId`, so an array column is only
+ * ever selected by its own array OID (`_timestamptz`), never by its
+ * element's. Listing the element OID leaves array columns alone.
+ *
+ * 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[];
+/**
+ * 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
+ * `columnFormat` alone cannot do: an explicitly text column and one turned
+ * text by fetchAsString carry the same format code but decode differently.
+ */
+export declare function fetchAsStringEqual(a: Maybe<OID[]>, b: Maybe<OID[]>): boolean;

package/util/resolve-column-formats.js

@@ -0,0 +1,67 @@
+import { DEFAULT_COLUMN_FORMAT } from '../constants.js';
+import { Protocol } from '../protocol/protocol.js';
+const DataFormat = Protocol.DataFormat;
+/**
+ * Turns `fetchAsString`'s OID list into the positional result format codes
+ * a Bind message actually carries.
+ *
+ * The protocol has no way to say "send this OID as text" - Bind's result
+ * format codes are per column, by position, and nothing in Parse/Bind is
+ * keyed on a type. So the OID list can only be honored once the column
+ * types are known, which means after a Describe and before the Bind that
+ * asks for them. Callers that already hold a RowDescription (a prepared
+ * statement's, or a cached one's) pay nothing for this; callers that do
+ * not have to ask for the whole row as text instead - see queryOnce().
+ *
+ * A column matches on its own `dataTypeId`, so an array column is only
+ * ever selected by its own array OID (`_timestamptz`), never by its
+ * element's. Listing the element OID leaves array columns alone.
+ *
+ * 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) {
+    const base = options.columnFormat != null ? options.columnFormat : DEFAULT_COLUMN_FORMAT;
+    const asString = options.fetchAsString;
+    if (!fields || !asString || !asString.length)
+        return base;
+    const l = fields.length;
+    const baseIsArray = Array.isArray(base);
+    const out = new Array(l);
+    let hit = false;
+    let i;
+    for (i = 0; i < l; i++) {
+        if (asString.includes(fields[i].dataTypeId)) {
+            // 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;
+            hit = true;
+        }
+        else
+            out[i] = baseIsArray
+                ? (base[i] ?? DEFAULT_COLUMN_FORMAT)
+                : base;
+    }
+    return hit ? out : base;
+}
+/**
+ * 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
+ * `columnFormat` alone cannot do: an explicitly text column and one turned
+ * text by fetchAsString carry the same format code but decode differently.
+ */
+export function fetchAsStringEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return !a?.length && !b?.length;
+    const l = a.length;
+    if (l !== b.length)
+        return false;
+    let i;
+    for (i = 0; i < l; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}

package/util/wrap-row-description.d.ts

@@ -1,5 +1,6 @@
 import { DataFormat } from '../constants.js';
 import type { DataTypeMap } from '../data-type-map.js';
+import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
 import type { FieldInfo } from '../interfaces/field-info.js';
 import type { Protocol } from '../protocol/protocol.js';
-export declare function wrapRowDescription(typeMap: DataTypeMap, fields: Protocol.RowDescription[], columnFormat: DataFormat | DataFormat[]): FieldInfo[];
+export declare function wrapRowDescription(typeMap: DataTypeMap, fields: Protocol.RowDescription[], columnFormat: DataFormat | DataFormat[], mappingOptions?: DataMappingOptions): FieldInfo[];

package/util/wrap-row-description.js

@@ -9,7 +9,8 @@ const DataTypeOIDByName = {};
 for (const oid of Object.keys(DataTypeNames)) {
     DataTypeOIDByName[DataTypeNames[oid]] = Number(oid);
 }
-export function wrapRowDescription(typeMap, fields, columnFormat) {
+export function wrapRowDescription(typeMap, fields, columnFormat, mappingOptions) {
+    const asString = mappingOptions?.fetchAsString;
     return fields.map((f, idx) => {
         const cf = Array.isArray(columnFormat) ? columnFormat[idx] : columnFormat;
         const x = {
@@ -35,6 +36,11 @@ export function wrapRowDescription(typeMap, fields, columnFormat) {
         if (reg) {
             x.jsType = reg.jsType;
         }
+        // A column the caller asked for as a string is handed back exactly as
+        // the server rendered it, whatever the registered type would otherwise
+        // have produced - including an array, which comes back as the literal.
+        if (asString && asString.includes(x.dataTypeId))
+            x.jsType = 'string';
         return x;
     });
 }