postgrejs 3.1.3 → 3.3.0

package/data-types/timestamptz-type.js

@@ -2,13 +2,13 @@ import { DataTypeOIDs } from '../constants.js';
 import { SmartBuffer } from '../protocol/smart-buffer.js';
 import { formatTimestamptz } from '../util/format-datetime.js';
 import { parseDateTimeTz } from '../util/parse-datetime.js';
+import { parsePgTimestampBuffer } from '../util/parse-pg-timestamp.js';
 const timeShift = 946684800000;
 const timeMul = 4294967296;
 export const TimestamptzType = {
     name: 'timestamptz',
     oid: DataTypeOIDs.timestamptz,
     jsType: 'Date',
-    fixedBinarySize: 8,
     encodeText(v) {
         return formatTimestamptz(v);
     },
@@ -34,7 +34,7 @@ export const TimestamptzType = {
         buf.writeInt32BE(hi);
         buf.writeUInt32BE(lo);
     },
-    decodeBinary(v, offset = 0, options) {
+    decodeBinary(v, offset = 0, _len, options) {
         const fetchAsString = options.fetchAsString?.includes(DataTypeOIDs.timestamptz);
         const hi = v.readInt32BE(offset);
         const lo = v.readUInt32BE(offset + 4);
@@ -42,11 +42,16 @@ export const TimestamptzType = {
             return fetchAsString ? 'infinity' : Infinity;
         if (lo === 0x00000000 && hi === -0x80000000)
             return fetchAsString ? '-infinity' : -Infinity;
-        // Shift from 2000 to 1970
-        let d = new Date((lo + hi * timeMul) / 1000 + timeShift);
-        if (fetchAsString || !options.utcDates) {
-            d = new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds());
-        }
+        // 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
+        // own) has to. Rebuilding the Date from its own local getters, as this
+        // used to, gave back the same instant for every value except one: an
+        // instant inside the hour that repeats when local time falls back is
+        // 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;
     },
     decodeText(v, options) {
@@ -64,11 +69,23 @@ export const TimestamptzType = {
         }
         return d;
     },
-    // See date-type.ts's decodeTextBuffer comment - same rationale. Note this
-    // type's decodeText always parses first and only branches on
+    // Reads PostgreSQL's own timestamp shape straight from the wire bytes.
+    // Building the string first and handing it to decodeText() costs about
+    // as much again as the parse itself, for a string that exists only to be
+    // 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) - delegating by reference preserves that as-is.
+    // 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;
+        }
         return TimestamptzType.decodeText(buf.toString('latin1', offset, offset + len), options);
     },
     isType(v) {

package/data-types/uuid-type.js

@@ -4,7 +4,6 @@ export const UuidType = {
     name: 'uuid',
     oid: DataTypeOIDs.uuid,
     jsType: 'String',
-    fixedBinarySize: 16,
     encodeText(v) {
         return '' + v;
     },
@@ -12,7 +11,7 @@ export const UuidType = {
         if (!GUID_PATTERN.test(v))
             throw new Error(`"${v}" is not a valid guid value`);
         const b = Buffer.from(v.replace(/-/g, ''), 'hex');
-        buf.writeBuffer(b);
+        buf.writeBytes(b);
     },
     decodeBinary(v, offset = 0) {
         return (v.toString('hex', offset, offset + 4) +

package/data-types/varchar-type.js

@@ -9,8 +9,8 @@ export const VarcharType = {
     encodeBinary(buf, v) {
         buf.writeString('' + v, 'utf8');
     },
-    decodeBinary(v, offset = 0) {
-        return v.toString('utf8', offset);
+    decodeBinary(v, offset = 0, len) {
+        return v.toString('utf8', offset, offset + len);
     },
     decodeText(v) {
         // The wire decoder always hands this a string (see intl-connection.ts's

package/index.d.ts

@@ -27,6 +27,7 @@ export * from './util/connection-config.js';
 export * from './util/escape-identifier.js';
 export * from './util/escape-literal.js';
 export * from './util/parse-datetime.js';
+export * from './util/row-decoder.js';
 export * from './util/sql-tag.js';
 export * from './util/stringify-arrayliteral.js';
 export * from './util/stringify-for-sql.js';

package/index.js

@@ -27,6 +27,7 @@ export * from './util/connection-config.js';
 export * from './util/escape-identifier.js';
 export * from './util/escape-literal.js';
 export * from './util/parse-datetime.js';
+export * from './util/row-decoder.js';
 export * from './util/sql-tag.js';
 export * from './util/stringify-arrayliteral.js';
 export * from './util/stringify-for-sql.js';

package/interfaces/command-result.d.ts

@@ -14,9 +14,10 @@ export interface CommandResult {
      */
     rows?: Row[];
     /**
-     * Contains row type
+     * Contains row type - `'custom'` when a custom `RowDecoder` instance was
+     * supplied via `rowDecoder` (there's no way to know what shape it returns)
      */
-    rowType?: 'array' | 'object';
+    rowType?: 'array' | 'object' | 'custom';
     /**
      * Time elapsed to execute command - only measured when `timing` is
      * enabled (off by default; see `DatabaseConnectionParams.timing`).

package/interfaces/data-type.d.ts

@@ -10,7 +10,6 @@ export interface DataType {
     decodeBinary: DecodeBinaryFunction;
     decodeText: DecodeTextFunction;
     decodeTextBuffer?: DecodeTextBufferFunction;
-    fixedBinarySize?: number;
     encodeAsNull?: EncodeAsNullFunction;
     encodeBinary?: EncodeBinaryFunction;
     encodeText?: EncodeTextFunction;

package/interfaces/query-options.d.ts

@@ -1,6 +1,7 @@
 import type { BindParam } from '../connection/bind-param.js';
 import type { DataFormat } from '../constants.js';
 import type { DataTypeMap } from '../data-type-map.js';
+import type { RowDecoder } from '../util/row-decoder.js';
 import type { DataMappingOptions } from './data-mapping-options.js';
 export interface QueryOptions extends DataMappingOptions {
     /**
@@ -10,9 +11,20 @@ export interface QueryOptions extends DataMappingOptions {
     autoCommit?: boolean;
     /**
      * Specifies if rows will be fetched as <FieldName, Value> pair objects or array of values
+     * @deprecated Use `rowDecoder: 'object'` instead - `objectRows: true` still works exactly
+     * as before, it's just the same thing `rowDecoder` now also expresses.
      * @default false
      */
     objectRows?: boolean;
+    /**
+     * Controls how each row's raw column data is turned into the value handed back to the
+     * caller. `'array'` and `'object'` select the built-in decoders (the same output
+     * `objectRows` has always produced); pass an instance of your own `RowDecoder` subclass
+     * to take over decoding entirely instead - e.g. for lazy per-cell decoding. Takes
+     * precedence over `objectRows` when both are set.
+     * @default 'array'
+     */
+    rowDecoder?: 'array' | 'object' | RowDecoder;
     /**
      * Data type map instance
      * @default GlobalTypeMap

package/interfaces/script-execute-options.d.ts

@@ -1,4 +1,5 @@
 import type { DataTypeMap } from '../data-type-map.js';
+import type { RowDecoder } from '../util/row-decoder.js';
 import type { DataMappingOptions } from './data-mapping-options.js';
 export interface ScriptExecuteOptions extends DataMappingOptions {
     /**
@@ -8,9 +9,20 @@ export interface ScriptExecuteOptions extends DataMappingOptions {
     autoCommit?: boolean;
     /**
      * Specifies if rows will be fetched as <FieldName, Value> pair objects or array of values
+     * @deprecated Use `rowDecoder: 'object'` instead - `objectRows: true` still works exactly
+     * as before, it's just the same thing `rowDecoder` now also expresses.
      * @default false
      */
     objectRows?: boolean;
+    /**
+     * Controls how each row's raw column data is turned into the value handed back to the
+     * caller. `'array'` and `'object'` select the built-in decoders (the same output
+     * `objectRows` has always produced); pass an instance of your own `RowDecoder` subclass
+     * to take over decoding entirely instead - e.g. for lazy per-cell decoding. Takes
+     * precedence over `objectRows` when both are set.
+     * @default 'array'
+     */
+    rowDecoder?: 'array' | 'object' | RowDecoder;
     /**
      * Data type map instance
      * @default GlobalTypeMap

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.1.3",
+  "version": "3.3.0",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {
     "@jsopen/objects": "^2.2.3",
     "doublylinked": "^2.5.6",
+    "flexy-buffer": "^1.1.0",
     "lightning-pool": "^4.12.0",
     "power-tasks": "^1.14.2",
     "putil-promisify": "^1.10.1",
@@ -45,7 +46,18 @@
     "client",
     "backend",
     "rdbms",
-    "sql"
+    "sql",
+    "typescript",
+    "wire-protocol",
+    "no-native-bindings",
+    "cursor",
+    "server-side-cursor",
+    "logical-replication",
+    "copy",
+    "connection-pool",
+    "prepared-statements",
+    "bun",
+    "bunjs"
   ],
   "publishConfig": {
     "access": "public"

package/protocol/backend.js

@@ -124,7 +124,7 @@ function parseAuthentication(io, code, len) {
         case 5:
             return {
                 kind: 'MD5Password',
-                salt: io.readBuffer(len - 8),
+                salt: io.readBytes(len - 8),
             };
         case 6:
             return {
@@ -141,7 +141,7 @@ function parseAuthentication(io, code, len) {
         case 8:
             return {
                 kind: 'GSSContinue',
-                data: io.readBuffer(len - 8),
+                data: io.readBytes(len - 8),
             };
         case 10: {
             const out = {
@@ -174,7 +174,7 @@ function parseBackendKeyData(io) {
     // this message's body (see Backend.parse()), so the secret key is
     // simply whatever bytes remain - 4 of them before protocol 3.2, up to
     // 256 with it (see VERSION_MINOR_LONG_CANCEL_KEY).
-    const secretKey = io.readBuffer();
+    const secretKey = io.readBytes();
     return { processID, secretKey };
 }
 function parseCommandComplete(io) {
@@ -184,7 +184,7 @@ function parseCommandComplete(io) {
 }
 function parseCopyData(io, code, len) {
     return {
-        data: io.readBuffer(len - 4),
+        data: io.readBytes(len - 4),
     };
 }
 function parseCopyResponse(io) {
@@ -208,7 +208,7 @@ function parseCopyResponse(io) {
 }
 function parseDataRow(io, code, len) {
     const columnCount = io.readUInt16BE();
-    const data = io.readBuffer(len - 6);
+    const data = io.readBytes(len - 6);
     return { columnCount, data };
 }
 function parseErrorResponse(io) {
@@ -234,7 +234,7 @@ function parseFunctionCallResponse(io) {
     // bytes following) - not deducible from the outer message length alone,
     // unlike most fixed-shape messages this codebase parses.
     const len = io.readInt32BE();
-    return { result: len < 0 ? null : io.readBuffer(len) };
+    return { result: len < 0 ? null : io.readBytes(len) };
 }
 function parseNegotiateProtocolVersion(io) {
     const supportedVersionMinor = io.readUInt32BE();

package/protocol/buffer-reader.d.ts

@@ -1,15 +1,10 @@
-export declare class BufferReader {
-    buffer: Buffer;
-    offset: number;
-    constructor(buffer: Buffer);
-    get length(): number;
-    readUInt8(): number;
-    readUInt16BE(): number;
-    readInt16BE(): number;
-    readUInt32BE(): number;
-    readInt32BE(): number;
+import { BufferReader as FlexyBufferReader } from 'flexy-buffer';
+/**
+ * Adds the PostgreSQL wire format's two string encodings on top of
+ * flexy-buffer's `BufferReader`: a NUL-terminated C string, and a
+ * length-prefixed string where a negative length is the NULL sentinel.
+ */
+export declare class BufferReader extends FlexyBufferReader {
     readCString(encoding?: BufferEncoding): string;
     readLString(len: number, encoding?: BufferEncoding): string | null;
-    readBuffer(len?: number): Buffer;
-    private _checkReadable;
 }

package/protocol/buffer-reader.js

@@ -1,68 +1,21 @@
-export class BufferReader {
-    buffer;
-    offset = 0;
-    constructor(buffer) {
-        this.buffer = buffer;
-    }
-    get length() {
-        return this.buffer.length;
-    }
-    readUInt8() {
-        this._checkReadable(1);
-        const v = this.buffer.readUInt8(this.offset);
-        this.offset++;
-        return v;
-    }
-    readUInt16BE() {
-        this._checkReadable(2);
-        const v = this.buffer.readUInt16BE(this.offset);
-        this.offset += 2;
-        return v;
-    }
-    readInt16BE() {
-        this._checkReadable(2);
-        const v = this.buffer.readInt16BE(this.offset);
-        this.offset += 2;
-        return v;
-    }
-    readUInt32BE() {
-        this._checkReadable(4);
-        const v = this.buffer.readUInt32BE(this.offset);
-        this.offset += 4;
-        return v;
-    }
-    readInt32BE() {
-        this._checkReadable(4);
-        const v = this.buffer.readInt32BE(this.offset);
-        this.offset += 4;
-        return v;
-    }
+import { BufferReader as FlexyBufferReader } from 'flexy-buffer';
+/**
+ * Adds the PostgreSQL wire format's two string encodings on top of
+ * flexy-buffer's `BufferReader`: a NUL-terminated C string, and a
+ * length-prefixed string where a negative length is the NULL sentinel.
+ */
+export class BufferReader extends FlexyBufferReader {
     readCString(encoding) {
-        const idx = this.buffer.indexOf(0, this.offset);
+        const idx = this.buffer.indexOf(0, this.position);
         if (idx === -1)
             throw new Error('Eof in buffer detected (readCString)');
-        const v = this.buffer.toString(encoding, this.offset, idx);
-        this.offset = idx + 1;
+        const v = this.buffer.toString(encoding, this.position, idx);
+        this.position = idx + 1;
         return v;
     }
     readLString(len, encoding) {
         if (len < 0)
             return null;
-        this._checkReadable(len);
-        const v = this.buffer.toString(encoding, this.offset, this.offset + len);
-        this.offset += len;
-        return v;
-    }
-    readBuffer(len) {
-        if (len)
-            this._checkReadable(len);
-        const end = len !== undefined ? this.offset + len : this.length;
-        const buf = this.buffer.subarray(this.offset, end);
-        this.offset = end;
-        return buf;
-    }
-    _checkReadable(size) {
-        if (this.offset + size - 1 >= this.length)
-            throw new Error('Eof in buffer detected');
+        return this.readString(len, encoding);
     }
 }