postgrejs 3.11.0 → 3.11.1

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 ## Changelog
 
-### [v3.11.0](https://github.com/panates/postgrejs/compare/v3.10.1...v3.11.0) - 
+### [v3.11.1](https://github.com/panates/postgrejs/compare/v3.11.0...v3.11.1) - 
+
+#### 🪲 Fixes
+
+- fix(bench): count off-heap memory in Peak Heap @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: shift the instant instead of rebuilding a local Date from its parts @Eray Hanoğlu 
+- perf: build uuid and macaddr text in one pass instead of five @Eray Hanoğlu 
+- perf: stop asking whether a small money value round-trips @Eray Hanoğlu 
+- perf: write a pg_lsn without four strings a value @Eray Hanoğlu 
+
+### [v3.11.0](https://github.com/panates/postgrejs/compare/v3.10.1...v3.11.0) -  23 September 2026 
 
 #### 🚀 New Features
 

package/data-types/date-type.js

@@ -1,5 +1,6 @@
 import { DataTypeOIDs } from '../constants.js';
 import { formatDate } from '../util/format-datetime.js';
+import { utcPartsAsLocal } from '../util/local-date.js';
 import { parseDate } from '../util/parse-datetime.js';
 const timeShift = 946684800000;
 export const DateType = {
@@ -35,11 +36,11 @@ export const DateType = {
             return Infinity;
         if (t === -0x80000000)
             return -Infinity;
-        // Shift from 2000 to 1970
-        let d = new Date(t * 1000 * 86400 + timeShift);
-        if (!options.utcDates)
-            d = new Date(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
-        return d;
+        // Shift from 2000 to 1970. A date's wire value is exactly midnight
+        // UTC, so the local wall clock it stands for is local midnight -
+        // which is what the shift lands on.
+        const ms = t * 1000 * 86400 + timeShift;
+        return options.utcDates ? new Date(ms) : utcPartsAsLocal(ms);
     },
     decodeText(v, options) {
         return parseDate(v, options.utcDates, options.dateStyle);

package/data-types/macaddr-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+import { writeHexBytes } from '../util/hex-text.js';
 /**
  * `macaddr` and `macaddr8` share a file for the same reason `inet` and
  * `cidr` do: one wire format - the address bytes and nothing else - and
@@ -33,6 +34,17 @@ function parseMacaddr(v, size) {
     return Buffer.from(hex, 'hex');
 }
 function createType(name, oid, size) {
+    // The text this type writes, built once: `size` pairs of hex with a
+    // colon between them, and only the hex is rewritten per value. See
+    // util/hex-text.ts for why not `toString('hex')` per byte.
+    const text = Buffer.allocUnsafe(size * 3 - 1);
+    const positions = [];
+    let i;
+    for (i = 0; i < size; i++) {
+        positions.push(i * 3);
+        if (i)
+            text[i * 3 - 1] = 58; /* : */
+    }
     return {
         name,
         oid,
@@ -52,11 +64,8 @@ function createType(name, oid, size) {
             buf.writeBytes(b);
         },
         decodeBinary(v, offset = 0) {
-            let out = v.toString('hex', offset, offset + 1);
-            let i;
-            for (i = 1; i < size; i++)
-                out += ':' + v.toString('hex', offset + i, offset + i + 1);
-            return out;
+            writeHexBytes(text, positions, v, offset, size);
+            return text.toString('latin1');
         },
         decodeText(v) {
             return v;

package/data-types/money-type.js

@@ -59,6 +59,23 @@ export function moneyToString(minorUnits, scale) {
         '.' +
         digits.slice(digits.length - scale));
 }
+/**
+ * Below this many minor units the decimal has at most fifteen
+ * significant digits, which a double both holds and prints back exactly
+ * - so the round trip below can only agree, and asking it is the most
+ * expensive thing in the decode: measured over values that vary,
+ * `parseFloat` plus the comparison is 241 ns against 113 ns without it,
+ * on a decode whose string-building is 109 ns of that.
+ *
+ * The scale bound is the other half: the test is about *printed* digits,
+ * and JavaScript switches to exponential notation below 1e-6, which
+ * PostgreSQL never writes. At scale 6 the smallest non-zero value is
+ * exactly 1e-6, and no currency has more.
+ */
+const FAITHFUL_LIMIT = 1000000000000000n; // 10^15
+function isFaithful(minorUnits, scale) {
+    return (scale <= 6 && minorUnits < FAITHFUL_LIMIT && minorUnits > -FAITHFUL_LIMIT);
+}
 /**
  * A number while a double carries the value exactly, a Numeric after
  * that - the same rule `numeric` decodes by, and for the same reason.
@@ -143,18 +160,22 @@ export const MoneyType = {
         const v = typeof buf.readBigInt64BE === 'function'
             ? buf.readBigInt64BE(offset)
             : readBigInt64BE(buf, offset);
-        const s = moneyToString(v, formatOf(options).scale);
+        const { scale } = formatOf(options);
+        const s = moneyToString(v, scale);
         // The exact decimal is what the decode already built; handing it
         // back is the whole of `decimalAsString`.
-        return wantsDecimalString(options, DataTypeOIDs.money)
-            ? s
-            : toNumberOrNumeric(s);
+        if (wantsDecimalString(options, DataTypeOIDs.money))
+            return s;
+        return isFaithful(v, scale) ? parseFloat(s) : toNumberOrNumeric(s);
     },
     decodeText(s, options) {
         const { scale } = formatOf(options);
-        const exact = moneyToString(parseMoneyText(s), scale);
-        return wantsDecimalString(options, DataTypeOIDs.money)
-            ? exact
+        const minorUnits = parseMoneyText(s);
+        const exact = moneyToString(minorUnits, scale);
+        if (wantsDecimalString(options, DataTypeOIDs.money))
+            return exact;
+        return isFaithful(minorUnits, scale)
+            ? parseFloat(exact)
             : toNumberOrNumeric(exact);
     },
     /**

package/data-types/pg-lsn-type.js

@@ -14,6 +14,29 @@ import { DataTypeOIDs } from '../constants.js';
  * compared rather than arithmetic.
  */
 const LSN_PATTERN = /^([0-9a-fA-F]{1,8})\/([0-9a-fA-F]{1,8})$/;
+/**
+ * `0`-`F` as bytes, and the text written into one reused scratch.
+ *
+ * `toString(16).toUpperCase()` per half is two strings each and four per
+ * value: 281 ns against 70 ns here, measured over values that vary. An
+ * LSN is not decoded in bulk - it comes back from monitoring queries a
+ * few rows at a time - so this is worth only the fifteen lines it takes
+ * and no machinery beyond them.
+ */
+const HEX_UPPER = Buffer.from('0123456789ABCDEF', 'latin1');
+const TEXT = Buffer.allocUnsafe(17);
+/** Writes one half at `p`, unpadded, and answers where it ended. */
+function writeHalf(value, p) {
+    let shift = 28;
+    // Neither half is padded - the server writes `0/0` and `A/B` - so the
+    // leading zeros are skipped, and the last nibble is written whatever
+    // it is so that zero comes out as `0` rather than nothing.
+    while (shift && !((value >>> shift) & 15))
+        shift -= 4;
+    for (; shift >= 0; shift -= 4)
+        TEXT[p++] = HEX_UPPER[(value >>> shift) & 15];
+    return p;
+}
 export const PgLsnType = {
     name: 'pg_lsn',
     oid: DataTypeOIDs.pg_lsn,
@@ -32,12 +55,10 @@ export const PgLsnType = {
         buf.writeUInt32BE(parseInt(m[2], 16));
     },
     decodeBinary(v, offset = 0) {
-        return (v.readUInt32BE(offset).toString(16).toUpperCase() +
-            '/' +
-            v
-                .readUInt32BE(offset + 4)
-                .toString(16)
-                .toUpperCase());
+        let p = writeHalf(v.readUInt32BE(offset), 0);
+        TEXT[p++] = 47; /* / */
+        p = writeHalf(v.readUInt32BE(offset + 4), p);
+        return TEXT.toString('latin1', 0, p);
     },
     decodeText(v) {
         return v;

package/data-types/time-type.js

@@ -1,5 +1,6 @@
 import { DataTypeOIDs } from '../constants.js';
 import { formatTime } from '../util/format-datetime.js';
+import { utcPartsAsLocal } from '../util/local-date.js';
 import { parseTime, STRICT_TIME_PATTERN } from '../util/parse-time.js';
 const timeMul = 4294967296;
 export const TimeType = {
@@ -27,11 +28,8 @@ export const TimeType = {
     decodeBinary(v, offset = 0, _len, options) {
         const hi = v.readInt32BE(offset);
         const lo = v.readUInt32BE(offset + 4);
-        let d = new Date((lo + hi * timeMul) / 1000);
-        if (!options.utcDates) {
-            d = new Date(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), d.getUTCMilliseconds());
-        }
-        return d;
+        const ms = (lo + hi * timeMul) / 1000;
+        return options.utcDates ? new Date(ms) : utcPartsAsLocal(ms);
     },
     decodeText(v, options) {
         return parseTime(v, false, options.utcDates);

package/data-types/timestamp-type.js

@@ -1,5 +1,6 @@
 import { DataTypeOIDs } from '../constants.js';
 import { formatTimestamp } from '../util/format-datetime.js';
+import { utcPartsAsLocal } from '../util/local-date.js';
 import { parseDateTime } from '../util/parse-datetime.js';
 import { parsePgTimestampBuffer } from '../util/parse-pg-timestamp.js';
 const timeShift = 946684800000;
@@ -44,11 +45,8 @@ export const TimestampType = {
         if (lo === 0x00000000 && hi === -0x80000000)
             return -Infinity;
         // Shift from 2000 to 1970
-        let d = new Date((lo + hi * timeMul) / 1000 + timeShift);
-        if (!options.utcDates) {
-            d = new Date(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), d.getUTCMilliseconds());
-        }
-        return d;
+        const ms = (lo + hi * timeMul) / 1000 + timeShift;
+        return options.utcDates ? new Date(ms) : utcPartsAsLocal(ms);
     },
     decodeText(v, options) {
         return parseDateTime(v, options.utcDates, options.dateStyle);

package/data-types/uuid-type.js

@@ -1,4 +1,15 @@
 import { DataTypeOIDs } from '../constants.js';
+import { writeHexBytes } from '../util/hex-text.js';
+/**
+ * The canonical text, written once and read back per value: 36 ASCII
+ * characters whose four dashes never move, so only the hex is rewritten.
+ * Reused rather than allocated because a decode fills it and converts it
+ * before anything else can run.
+ */
+const TEXT = Buffer.allocUnsafe(36);
+TEXT[8] = TEXT[13] = TEXT[18] = TEXT[23] = 45; /* - */
+/** Where each of the sixteen bytes writes its two characters. */
+const POSITIONS = [0, 2, 4, 6, 9, 11, 14, 16, 19, 21, 24, 26, 28, 30, 32, 34];
 const GUID_PATTERN = /^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}$/;
 export const UuidType = {
     name: 'uuid',
@@ -14,15 +25,8 @@ export const UuidType = {
         buf.writeBytes(b);
     },
     decodeBinary(v, offset = 0) {
-        return (v.toString('hex', offset, offset + 4) +
-            '-' +
-            v.toString('hex', offset + 4, offset + 6) +
-            '-' +
-            v.toString('hex', offset + 6, offset + 8) +
-            '-' +
-            v.toString('hex', offset + 8, offset + 10) +
-            '-' +
-            v.toString('hex', offset + 10, offset + 16));
+        writeHexBytes(TEXT, POSITIONS, v, offset, 16);
+        return TEXT.toString('latin1');
     },
     decodeText(v) {
         return v;

package/package.json

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

package/util/hex-text.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Writes `count` bytes of `src` into `scratch` as lowercase hex, each
+ * byte's two characters starting at `positions[i]` - so the separators
+ * a type writes between its bytes are put in once, when the scratch is
+ * built, and never again.
+ *
+ * The scratch is then read back with `latin1`, which is what the text
+ * paths of these types already use: the output is fixed-format ASCII,
+ * so it decodes identically to `utf8` and skips V8's multi-byte-sequence
+ * detection.
+ *
+ * Why not `Buffer.toString('hex')`: a type whose text has separators in
+ * it has to call that once per group and join the pieces. For `uuid`
+ * that was five calls and four concatenations per value - 25 000 strings
+ * and 20 000 concatenations for a 5 000-row column, which is more work
+ * than `pg` does for the same column despite this client reading half
+ * the bytes. Measured over 5 000 values, medians of nine runs:
+ *
+ * ```
+ * five toString + concat        1.86 ms
+ * one toString, then slice      0.81 ms
+ * a byte -> two-char table      0.64 ms
+ * this                          0.33 ms
+ * ```
+ */
+export declare function writeHexBytes(scratch: Buffer, positions: number[], src: Buffer, offset: number, count: number): void;

package/util/hex-text.js

@@ -0,0 +1,38 @@
+/** `0`-`f` as bytes, so a nibble indexes straight into it. */
+const HEX = Buffer.from('0123456789abcdef', 'latin1');
+/**
+ * Writes `count` bytes of `src` into `scratch` as lowercase hex, each
+ * byte's two characters starting at `positions[i]` - so the separators
+ * a type writes between its bytes are put in once, when the scratch is
+ * built, and never again.
+ *
+ * The scratch is then read back with `latin1`, which is what the text
+ * paths of these types already use: the output is fixed-format ASCII,
+ * so it decodes identically to `utf8` and skips V8's multi-byte-sequence
+ * detection.
+ *
+ * Why not `Buffer.toString('hex')`: a type whose text has separators in
+ * it has to call that once per group and join the pieces. For `uuid`
+ * that was five calls and four concatenations per value - 25 000 strings
+ * and 20 000 concatenations for a 5 000-row column, which is more work
+ * than `pg` does for the same column despite this client reading half
+ * the bytes. Measured over 5 000 values, medians of nine runs:
+ *
+ * ```
+ * five toString + concat        1.86 ms
+ * one toString, then slice      0.81 ms
+ * a byte -> two-char table      0.64 ms
+ * this                          0.33 ms
+ * ```
+ */
+export function writeHexBytes(scratch, positions, src, offset, count) {
+    let i;
+    let p;
+    let b;
+    for (i = 0; i < count; i++) {
+        p = positions[i];
+        b = src[offset + i];
+        scratch[p] = HEX[b >> 4];
+        scratch[p + 1] = HEX[b & 15];
+    }
+}

package/util/local-date.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The local `Date` whose wall clock reads what `ms` reads in UTC.
+ *
+ * `timestamp`, `date` and `time` carry no zone: the server sends a wall
+ * clock and the client decides which one it names. With `utcDates` off -
+ * the default - that is the local one, so a `2024-06-15 10:30` column
+ * comes back as a Date reading 10:30 locally rather than the instant
+ * 10:30Z.
+ *
+ * Doing that by reading the seven `getUTC*` components off one Date and
+ * handing them to another was the most expensive thing left in the
+ * common decode path - the getters alone cost more than either Date:
+ *
+ * ```
+ * new Date(epochMs)               43.6 ns
+ * getUTC* x 7                     97.4 ns
+ * new Date(y, m, d, h, mi, s, ms) 61.7 ns
+ * ```
+ *
+ * Shifting the instant by the zone's own offset lands on the same wall
+ * clock for a fraction of that, but only where the offset is a whole
+ * number of minutes and holds either side of where the shift lands.
+ * Two guards and a floor make that exact rather than usually-right:
+ *
+ * - **The offset must survive the shift.** Where it does not, the shift
+ *   crossed a transition and the wall clock it landed on is not the one
+ *   that was asked for - or does not exist at all.
+ * - **The offset must hold for the hour before the landing too.** That
+ *   is the hour a backward transition repeats, where both instants read
+ *   the same wall clock and the shift keeps the wrong one of the two.
+ *   Pacific/Chatham found this: `2024-04-07T03:00Z` is `03:00` in both
+ *   +12:45 and +13:45, an hour apart.
+ * - **Nothing before 1970.** A zone's pre-standard offset carries
+ *   seconds - Europe/Istanbul was +01:55:52 - and `getTimezoneOffset()`
+ *   answers in whole minutes, so the shift lands up to 59 seconds off.
+ *   The tz database does not claim correctness before 1970 either.
+ *
+ * Whatever fails those goes back to the component route, which is what
+ * this has always answered. Checked against it over 1850-2040 at
+ * 90-minute steps - 1.1 million instants - in ten zones including the
+ * 45-minute and 30-minute DST ones: no disagreement, and
+ *
+ * ```
+ *                    before     after
+ * Europe/Istanbul    157.5 ns   123.0 ns
+ * America/New_York   245.6 ns   131.2 ns
+ * ```
+ *
+ * The DST zone was dearer before because V8 pays for a transition lookup
+ * on every local construction; here it pays for one instant instead.
+ */
+export declare function utcPartsAsLocal(ms: number): Date;

package/util/local-date.js

@@ -0,0 +1,69 @@
+/**
+ * The local `Date` whose wall clock reads what `ms` reads in UTC.
+ *
+ * `timestamp`, `date` and `time` carry no zone: the server sends a wall
+ * clock and the client decides which one it names. With `utcDates` off -
+ * the default - that is the local one, so a `2024-06-15 10:30` column
+ * comes back as a Date reading 10:30 locally rather than the instant
+ * 10:30Z.
+ *
+ * Doing that by reading the seven `getUTC*` components off one Date and
+ * handing them to another was the most expensive thing left in the
+ * common decode path - the getters alone cost more than either Date:
+ *
+ * ```
+ * new Date(epochMs)               43.6 ns
+ * getUTC* x 7                     97.4 ns
+ * new Date(y, m, d, h, mi, s, ms) 61.7 ns
+ * ```
+ *
+ * Shifting the instant by the zone's own offset lands on the same wall
+ * clock for a fraction of that, but only where the offset is a whole
+ * number of minutes and holds either side of where the shift lands.
+ * Two guards and a floor make that exact rather than usually-right:
+ *
+ * - **The offset must survive the shift.** Where it does not, the shift
+ *   crossed a transition and the wall clock it landed on is not the one
+ *   that was asked for - or does not exist at all.
+ * - **The offset must hold for the hour before the landing too.** That
+ *   is the hour a backward transition repeats, where both instants read
+ *   the same wall clock and the shift keeps the wrong one of the two.
+ *   Pacific/Chatham found this: `2024-04-07T03:00Z` is `03:00` in both
+ *   +12:45 and +13:45, an hour apart.
+ * - **Nothing before 1970.** A zone's pre-standard offset carries
+ *   seconds - Europe/Istanbul was +01:55:52 - and `getTimezoneOffset()`
+ *   answers in whole minutes, so the shift lands up to 59 seconds off.
+ *   The tz database does not claim correctness before 1970 either.
+ *
+ * Whatever fails those goes back to the component route, which is what
+ * this has always answered. Checked against it over 1850-2040 at
+ * 90-minute steps - 1.1 million instants - in ten zones including the
+ * 45-minute and 30-minute DST ones: no disagreement, and
+ *
+ * ```
+ *                    before     after
+ * Europe/Istanbul    157.5 ns   123.0 ns
+ * America/New_York   245.6 ns   131.2 ns
+ * ```
+ *
+ * The DST zone was dearer before because V8 pays for a transition lookup
+ * on every local construction; here it pays for one instant instead.
+ */
+export function utcPartsAsLocal(ms) {
+    if (ms >= 0) {
+        const offset = new Date(ms).getTimezoneOffset();
+        const local = new Date(ms + offset * 60000);
+        if (local.getTimezoneOffset() === offset &&
+            new Date(local.getTime() - 3600000).getTimezoneOffset() === offset)
+            return local;
+    }
+    const utc = new Date(ms);
+    const year = utc.getUTCFullYear();
+    const local = new Date(year, utc.getUTCMonth(), utc.getUTCDate(), utc.getUTCHours(), utc.getUTCMinutes(), utc.getUTCSeconds(), utc.getUTCMilliseconds());
+    // `new Date(44, 2, 15)` means 1944 - the constructor's own century
+    // rule, which is not what a server sending `0044-03-15` meant. It only
+    // reaches values this old, which take this route anyway.
+    if (year >= 0 && year <= 99)
+        local.setFullYear(year);
+    return local;
+}