postgrejs 3.5.0 → 3.6.0

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;
     });
 }