postgrejs 3.10.1 → 3.11.1

package/CHANGELOG.md

@@ -1,6 +1,29 @@
 ## Changelog
 
-### [v3.10.1](https://github.com/panates/postgrejs/compare/v3.10.0...v3.10.1) - 
+### [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
+
+- feat: add isMultiStatement(), so a caller can tell which of the two to use @Eray Hanoğlu 
+
+#### 🛠 Refactoring and Updates
+
+- refactor: rename `multi-statement` to `is-multi-statement` for clarity @Eray Hanoğlu 
+
+### [v3.10.1](https://github.com/panates/postgrejs/compare/v3.10.0...v3.10.1) -  22 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/index.d.ts

@@ -37,6 +37,7 @@ export * from './util/connection-config.js';
 export * from './util/decimal-as-string.js';
 export * from './util/escape-identifier.js';
 export * from './util/escape-literal.js';
+export * from './util/is-multi-statement.js';
 export * from './util/parse-datetime.js';
 export * from './util/row-decoder.js';
 export * from './util/sql-tag.js';

package/index.js

@@ -37,6 +37,7 @@ export * from './util/connection-config.js';
 export * from './util/decimal-as-string.js';
 export * from './util/escape-identifier.js';
 export * from './util/escape-literal.js';
+export * from './util/is-multi-statement.js';
 export * from './util/parse-datetime.js';
 export * from './util/row-decoder.js';
 export * from './util/sql-tag.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.10.1",
+  "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/is-multi-statement.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Whether `sql` holds more than one statement.
+ *
+ * This client has two ways to send SQL and they are not interchangeable:
+ * `query()` speaks the extended protocol, which PostgreSQL will not let
+ * carry more than one command, and `execute()` sends a simple `Query`,
+ * which may hold a whole script but gives up the prepared plan. A caller
+ * that knows which it has picks the right one and needs nothing from
+ * here. A caller with a single SQL-taking API above it - an ORM adapter,
+ * a migration runner, a REPL, anything taking SQL from a user - has to
+ * choose before it can send, and both shapes arrive at the same method.
+ *
+ * Nobody can answer that from the wire: the server does the parsing, and
+ * its count arrives with the results, long after the choice was made.
+ * `pg` picks from whether the call happened to carry parameters, which
+ * is a guess about intent rather than an answer. So the question belongs
+ * here, beside the two functions whose difference raises it.
+ *
+ * It is a scanner and not a parser - one pass, one boolean - and what it
+ * skips is everything a `;` can hide inside:
+ *
+ * | construct | skipped to |
+ * | --- | --- |
+ * | `'...'` | the closing quote, `''` being an escaped one |
+ * | `E'...'` | the same, and `\'` too |
+ * | `"..."` | the closing quote of an identifier, `""` escaped |
+ * | `$tag$...$tag$` | the matching tag - a function body |
+ * | `-- ...` | end of line |
+ * | `/* ... *\/` | the matching close, which PostgreSQL nests |
+ *
+ * A trailing `;`, or a run of them with only whitespace and comments
+ * after, is not a second statement: the server takes `select 1;;` on the
+ * extended protocol without complaint.
+ *
+ * Which way a wrong answer goes is not symmetric, and the tests are built
+ * on that: saying *several* about one statement costs it its prepared
+ * plan and nothing else, while saying *one* about several reaches the
+ * caller as `42601 cannot insert multiple commands into a prepared
+ * statement`.
+ *
+ * One boundary, left as it is: under `standard_conforming_strings = off`
+ * a backslash escapes inside a plain `'...'` too, so `select 'a\'; select
+ * 2` is one malformed statement to the server and two to this. Both roads
+ * end in an error, nothing is decoded wrongly, and that setting has
+ * defaulted to `on` since PostgreSQL 9.1.
+ */
+export declare function isMultiStatement(sql: string): boolean;

package/util/is-multi-statement.js

@@ -0,0 +1,184 @@
+/**
+ * Whether `sql` holds more than one statement.
+ *
+ * This client has two ways to send SQL and they are not interchangeable:
+ * `query()` speaks the extended protocol, which PostgreSQL will not let
+ * carry more than one command, and `execute()` sends a simple `Query`,
+ * which may hold a whole script but gives up the prepared plan. A caller
+ * that knows which it has picks the right one and needs nothing from
+ * here. A caller with a single SQL-taking API above it - an ORM adapter,
+ * a migration runner, a REPL, anything taking SQL from a user - has to
+ * choose before it can send, and both shapes arrive at the same method.
+ *
+ * Nobody can answer that from the wire: the server does the parsing, and
+ * its count arrives with the results, long after the choice was made.
+ * `pg` picks from whether the call happened to carry parameters, which
+ * is a guess about intent rather than an answer. So the question belongs
+ * here, beside the two functions whose difference raises it.
+ *
+ * It is a scanner and not a parser - one pass, one boolean - and what it
+ * skips is everything a `;` can hide inside:
+ *
+ * | construct | skipped to |
+ * | --- | --- |
+ * | `'...'` | the closing quote, `''` being an escaped one |
+ * | `E'...'` | the same, and `\'` too |
+ * | `"..."` | the closing quote of an identifier, `""` escaped |
+ * | `$tag$...$tag$` | the matching tag - a function body |
+ * | `-- ...` | end of line |
+ * | `/* ... *\/` | the matching close, which PostgreSQL nests |
+ *
+ * A trailing `;`, or a run of them with only whitespace and comments
+ * after, is not a second statement: the server takes `select 1;;` on the
+ * extended protocol without complaint.
+ *
+ * Which way a wrong answer goes is not symmetric, and the tests are built
+ * on that: saying *several* about one statement costs it its prepared
+ * plan and nothing else, while saying *one* about several reaches the
+ * caller as `42601 cannot insert multiple commands into a prepared
+ * statement`.
+ *
+ * One boundary, left as it is: under `standard_conforming_strings = off`
+ * a backslash escapes inside a plain `'...'` too, so `select 'a\'; select
+ * 2` is one malformed statement to the server and two to this. Both roads
+ * end in an error, nothing is decoded wrongly, and that setting has
+ * defaulted to `on` since PostgreSQL 9.1.
+ */
+export function isMultiStatement(sql) {
+    const len = sql.length;
+    let i = 0;
+    let separator = false;
+    let c;
+    while (i < len) {
+        c = sql.charCodeAt(i);
+        // Whatever follows a `;` decides what that `;` was: more whitespace,
+        // comments or semicolons leave it a terminator, and anything else
+        // makes it the seam between two statements.
+        if (separator && !isSpace(c) && c !== SEMI && c !== DASH && c !== SLASH)
+            return true;
+        if (c === SEMI) {
+            separator = true;
+            i++;
+        }
+        else if (c === QUOTE) {
+            i = skipQuoted(sql, len, i, QUOTE, escapesBackslash(sql, i));
+        }
+        else if (c === DQUOTE) {
+            i = skipQuoted(sql, len, i, DQUOTE, false);
+        }
+        else if (c === DOLLAR) {
+            const end = skipDollarQuoted(sql, len, i);
+            // Not a dollar quote - a `$1` placeholder, or a bare `$`.
+            i = end < 0 ? i + 1 : end;
+        }
+        else if (c === DASH && sql.charCodeAt(i + 1) === DASH) {
+            const nl = sql.indexOf('\n', i + 2);
+            i = nl < 0 ? len : nl + 1;
+        }
+        else if (c === SLASH && sql.charCodeAt(i + 1) === STAR) {
+            i = skipBlockComment(sql, len, i);
+        }
+        else {
+            // A `-` or `/` that began no comment is content like any other.
+            if (separator && !isSpace(c))
+                return true;
+            i++;
+        }
+    }
+    return false;
+}
+const SEMI = 59; // ;
+const QUOTE = 39; // '
+const DQUOTE = 34; // "
+const DOLLAR = 36; // $
+const DASH = 45; // -
+const SLASH = 47; // /
+const STAR = 42; // *
+const BACKSLASH = 92; // \
+const UNDERSCORE = 95; // _
+function isSpace(c) {
+    return c === 32 || c === 10 || c === 9 || c === 13 || c === 12;
+}
+function isDigit(c) {
+    return c >= 48 && c <= 57;
+}
+/** A letter or `_`, which is what a dollar-quote tag may start with. */
+function isIdentStart(c) {
+    return (c >= 65 && c <= 90) || (c >= 97 && c <= 122) || c === UNDERSCORE;
+}
+/**
+ * Whether the quote at `at` opens an `E'...'` literal, where a backslash
+ * escapes. The letter has to stand alone: the `e` of `value` is not a
+ * prefix.
+ */
+function escapesBackslash(sql, at) {
+    const prev = sql.charCodeAt(at - 1);
+    if (prev !== 69 /* E */ && prev !== 101 /* e */)
+        return false;
+    if (at < 2)
+        return true;
+    const before = sql.charCodeAt(at - 2);
+    return !(isIdentStart(before) ||
+        isDigit(before) ||
+        before === DOLLAR ||
+        before === UNDERSCORE);
+}
+/** Past the closing quote, or the end of the string if it never closes. */
+function skipQuoted(sql, len, start, quote, backslash) {
+    let i = start + 1;
+    let c;
+    while (i < len) {
+        c = sql.charCodeAt(i);
+        if (backslash && c === BACKSLASH)
+            i += 2;
+        else if (c !== quote)
+            i++;
+        // A doubled quote is an escaped one and the literal carries on.
+        else if (sql.charCodeAt(i + 1) === quote)
+            i += 2;
+        else
+            return i + 1;
+    }
+    return len;
+}
+/**
+ * Past `$tag$ ... $tag$`, or -1 when the `$` opens none - which is the
+ * common case, since `$1` is a parameter placeholder. The tag is read
+ * character by character so that a placeholder costs no allocation.
+ */
+function skipDollarQuoted(sql, len, start) {
+    let i = start + 1;
+    let c;
+    while (i < len) {
+        c = sql.charCodeAt(i);
+        if (c === DOLLAR)
+            break;
+        if (!(isIdentStart(c) || (i > start + 1 && isDigit(c))))
+            return -1;
+        i++;
+    }
+    if (i >= len)
+        return -1;
+    const tag = sql.substring(start, i + 1);
+    const close = sql.indexOf(tag, i + 1);
+    return close < 0 ? len : close + tag.length;
+}
+/** Past the matching `*\/`. PostgreSQL nests block comments. */
+function skipBlockComment(sql, len, start) {
+    let depth = 0;
+    let i = start;
+    while (i < len) {
+        if (sql.charCodeAt(i) === SLASH && sql.charCodeAt(i + 1) === STAR) {
+            depth++;
+            i += 2;
+        }
+        else if (sql.charCodeAt(i) === STAR && sql.charCodeAt(i + 1) === SLASH) {
+            i += 2;
+            if (--depth === 0)
+                return i;
+        }
+        else
+            i++;
+    }
+    return len;
+}

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