postgrejs 3.1.2 → 3.3.0

package/util/parse-pg-timestamp.js

@@ -0,0 +1,199 @@
+/**
+ * Reads a fixed 2-digit field at `i`, or -1 when it runs past `end` or
+ * either byte isn't a digit. Module level, not a closure inside the
+ * scanner: a closure allocated per parsed value would cost more than the
+ * parse it speeds up.
+ *
+ * `end` is load-bearing, not a formality: this reads a row's own slice of
+ * a shared buffer, so a read past the end would silently pick up the next
+ * column's bytes - and accept a truncated timestamp if they happened to be
+ * digits, rather than declining it.
+ */
+function read2(buf, i, end) {
+    if (i + 1 >= end)
+        return -1;
+    const a = buf[i] - 48;
+    if (a < 0 || a > 9)
+        return -1;
+    const b = buf[i + 1] - 48;
+    if (b < 0 || b > 9)
+        return -1;
+    return a * 10 + b;
+}
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/**
+ * Days between the Unix epoch and a proleptic-Gregorian Y/M/D (Howard
+ * Hinnant's days_from_civil). `Date.UTC()` produces the same number but
+ * costs roughly twice as much, because it also has to coerce and normalise
+ * arbitrarily out-of-range arguments - which every caller here has already
+ * ruled out. Only correct for the in-range, already-validated values the
+ * scanner feeds it (years 1000-9999, so every intermediate stays positive
+ * and `| 0` truncation is the same as flooring).
+ */
+function epochDays(year, month, day) {
+    const y = month <= 2 ? year - 1 : year;
+    const era = (y / 400) | 0;
+    const yoe = y - era * 400;
+    const doy = (((153 * (month + (month > 2 ? -3 : 9)) + 2) / 5) | 0) + day - 1;
+    const doe = yoe * 365 + ((yoe / 4) | 0) - ((yoe / 100) | 0) + doy;
+    return era * 146097 + doe - 719468;
+}
+/**
+ * Decodes the exact shape PostgreSQL's own ISO output uses -
+ * `YYYY-MM-DD HH:MM:SS[.f+][(+|-)HH[:MM]]` - straight out of the wire
+ * bytes, instead of building a string and handing that to the engine's
+ * general-purpose date parser. `new Date(str)` costs ~150ns per value and
+ * dominates decode time on timestamp-heavy result sets; even the string
+ * this replaces costs ~43ns to materialise before any parsing starts.
+ *
+ * Returns undefined for anything that isn't *exactly* that shape, so every
+ * other input (compact forms, `T` separators, a `BC` suffix, years outside
+ * 1000-9999, LMT-style ±HH:MM:SS offsets) falls through to the original
+ * `new Date()`/regex path and keeps its existing result - including the
+ * engine's own quirks, which callers may already depend on:
+ * `0001-01-01` parsing as year 2001, and `-04:56:02` offsets being
+ * rejected outright.
+ *
+ * A missing offset means local time, matching what `new Date(str)` does
+ * with a space-separated, offset-less timestamp.
+ */
+export function parsePgTimestampBuffer(buf, offset, end) {
+    if (end - offset < 19)
+        return undefined;
+    // Year must be a plain 1000-9999: a leading zero would hit the engine's
+    // legacy two-digit-year mapping (`0001` -> 2001) that the fallback path
+    // still produces.
+    const y0 = buf[offset] - 48;
+    if (y0 < 1 || y0 > 9)
+        return undefined;
+    if (buf[offset + 4] !== 45 || // -
+        buf[offset + 7] !== 45 || // -
+        buf[offset + 10] !== 32 || // space
+        buf[offset + 13] !== 58 || // :
+        buf[offset + 16] !== 58 // :
+    )
+        return undefined;
+    let n;
+    let year = y0;
+    for (let i = offset + 1; i < offset + 4; i++) {
+        n = buf[i] - 48;
+        if (n < 0 || n > 9)
+            return undefined;
+        year = year * 10 + n;
+    }
+    // month, day, hour, minute, second - each a 2-digit field at a fixed
+    // offset. Every field is range-checked rather than just parsed: the
+    // fallback path handles out-of-range values inconsistently (month 0,
+    // day 0, minute 60 and second 60 are rejected outright, while a day past
+    // the end of its month rolls over into the next one), so rather than
+    // reproduce that split, only unambiguously valid values are taken here
+    // and everything else is left to it, exactly as before.
+    const month = read2(buf, offset + 5, end);
+    if (month < 1 || month > 12)
+        return undefined;
+    const day = read2(buf, offset + 8, end);
+    if (day < 1 || day > 31)
+        return undefined;
+    const hour = read2(buf, offset + 11, end);
+    if (hour < 0 || hour > 23)
+        return undefined;
+    const minute = read2(buf, offset + 14, end);
+    if (minute < 0 || minute > 59)
+        return undefined;
+    const second = read2(buf, offset + 17, end);
+    if (second < 0 || second > 59)
+        return undefined;
+    if (day > DAYS_IN_MONTH[month - 1]) {
+        // February 29th is the one day this table can't answer on its own.
+        if (month !== 2 || day !== 29)
+            return undefined;
+        if (year % 4 !== 0 || (year % 100 === 0 && year % 400 !== 0))
+            return undefined;
+    }
+    let pos = offset + 19;
+    let ms = 0;
+    if (pos < end && buf[pos] === 46) {
+        // Fractional seconds: milliseconds are the first 3 digits, zero-padded
+        // when fewer are present (".5" is 500ms) and truncated when more are
+        // (".123456" is 123ms) - both matching the existing paths exactly.
+        pos++;
+        let digits = 0;
+        while (pos < end) {
+            n = buf[pos] - 48;
+            if (n < 0 || n > 9)
+                break;
+            if (digits < 3)
+                ms = ms * 10 + n;
+            digits++;
+            pos++;
+        }
+        if (!digits)
+            return undefined;
+        if (digits === 1)
+            ms *= 100;
+        else if (digits === 2)
+            ms *= 10;
+    }
+    if (pos === end)
+        return new Date(year, month - 1, day, hour, minute, second, ms);
+    const sign = buf[pos];
+    if (sign !== 43 && sign !== 45)
+        return undefined; // + or -
+    pos++;
+    const offHour = read2(buf, pos, end);
+    if (offHour < 0 || offHour > 23)
+        return undefined;
+    pos += 2;
+    let offMinute = 0;
+    if (pos < end) {
+        if (buf[pos] !== 58)
+            return undefined; // :
+        offMinute = read2(buf, pos + 1, end);
+        if (offMinute < 0 || offMinute > 59)
+            return undefined;
+        pos += 3;
+        // A trailing ":SS" (PostgreSQL emits these for pre-standard-time
+        // dates) is deliberately not handled: `new Date()` rejects those
+        // outright today, so they must keep falling through to do the same.
+        if (pos !== end)
+            return undefined;
+    }
+    const offsetMinutes = (offHour * 60 + offMinute) * (sign === 45 ? -1 : 1);
+    return new Date((epochDays(year, month, day) * 86400 +
+        hour * 3600 +
+        (minute - offsetMinutes) * 60 +
+        second) *
+        1000 +
+        ms);
+}
+// Big enough for any timestamp PostgreSQL prints (the longest is
+// "YYYY-MM-DD HH:MM:SS.ffffff+HH:MM", 32 bytes); anything longer is left to
+// the fallback, which produces the same value it always did.
+const scratch = Buffer.allocUnsafe(64);
+/**
+ * The same scan for a value that is already a string - the array-element
+ * and string-parameter paths, which never see the wire bytes.
+ *
+ * Copying into a scratch buffer first still beats scanning the string
+ * directly through a second, parallel implementation: the copy costs about
+ * half of what materialising the string cost in the first place, and there
+ * is only one scanner to keep correct. Safe to share one buffer because
+ * the copy and the scan that reads it are a single synchronous step.
+ */
+export function parsePgTimestampString(str) {
+    const len = str.length;
+    if (len < 19 || len > scratch.length)
+        return undefined;
+    let c;
+    for (let i = 0; i < len; i++) {
+        c = str.charCodeAt(i);
+        // A code point above 255 would be truncated on the way into the buffer
+        // and could land on a digit, turning a string the scanner should
+        // reject into one it accepts. Nothing in the shape it scans is
+        // non-ASCII, so anything that isn't goes to the fallback.
+        if (c > 255)
+            return undefined;
+        scratch[i] = c;
+    }
+    return parsePgTimestampBuffer(scratch, 0, len);
+}

package/util/parse-row.js

@@ -21,7 +21,127 @@ export function parseRow(parsers, data, columnCount, options) {
     }
     return row;
 }
+/**
+ * Rows decoded against one `FieldInfo[]` before compiling a factory for it.
+ *
+ * Compiling costs ~0.8µs when the engine can reuse its own compilation
+ * cache for identical source and several µs when it can't, against ~0.1µs
+ * saved per row - so a query returning a handful of rows would pay more
+ * than it ever got back. Since wrapRowDescription() builds a fresh fields
+ * array per query, a single-row query executed in a loop would otherwise
+ * recompile on every call. Waiting a few rows keeps that case free while
+ * giving up well under 1% of the win on a result worth compiling for.
+ */
+const OBJECT_ROW_FACTORY_THRESHOLD = 8;
+/**
+ * Holds only factories that were actually compiled - never the row counts
+ * leading up to one. Writing a fresh key here costs ~67ns plus the garbage
+ * it leaves behind, which a single-row query (a new fields array every
+ * time, never looked up again) would pay on every call for nothing.
+ *
+ * Keyed weakly, so a finished query's factory goes away with its fields;
+ * an entry earns its keep only when the same fields array is decoded
+ * against again after something else interrupted it.
+ */
+const objectRowFactories = new WeakMap();
+// Rows of one result arrive in a run, so a single entry in front of the
+// WeakMap answers nearly every lookup with one identity check - and is
+// also where the pre-threshold row count lives, keeping it out of the
+// WeakMap entirely.
+let memoFields;
+let memoFactory = null;
+let memoRows = 0;
+// Set when this shape can never be compiled, so the attempt isn't
+// repeated for every remaining row of the result.
+let memoDeclined = false;
+/**
+ * Compiles a function that builds this query's row object in one shot,
+ * from a single object literal with every column name in it.
+ *
+ * Assigning the columns one at a time instead (`row[name] = value`) walks
+ * the object through one hidden-class transition per column, per row -
+ * measured at ~6.8x the cost of handing the engine a literal whose shape
+ * it can lay out once and reuse for every row of the result.
+ *
+ * Returns null when that isn't possible, leaving the caller on the
+ * assignment path: a column named `__proto__` would set the prototype
+ * rather than become an own property if it appeared as a literal key, and
+ * Function construction itself can be unavailable (a Content-Security-
+ * Policy without 'unsafe-eval').
+ */
+function buildObjectRowFactory(fields, columnCount) {
+    let src = 'return{';
+    let name;
+    let i;
+    for (i = 0; i < columnCount; i++) {
+        name = fields[i].fieldName;
+        if (name === '__proto__')
+            return null;
+        if (i)
+            src += ',';
+        // JSON.stringify() quotes and escapes the name into a string literal,
+        // so any column name is embedded safely, whatever it contains.
+        src += JSON.stringify(name) + ':v[' + i + ']';
+    }
+    try {
+        return new Function('v', src + '}');
+        /* c8 ignore next 3 - needs a runtime with Function construction disabled */
+    }
+    catch {
+        return null;
+    }
+}
+function getObjectRowFactory(fields, columnCount) {
+    if (fields !== memoFields) {
+        // A different result than the last row belonged to. A hit here means
+        // an earlier, long-enough run already paid to compile this exact
+        // fields array; otherwise start counting it from scratch.
+        memoFields = fields;
+        memoRows = 1;
+        memoDeclined = false;
+        memoFactory = objectRowFactories.get(fields) ?? null;
+        return memoFactory;
+    }
+    if (memoFactory || memoDeclined)
+        return memoFactory;
+    if (++memoRows < OBJECT_ROW_FACTORY_THRESHOLD)
+        return null;
+    const factory = buildObjectRowFactory(fields, columnCount);
+    if (!factory) {
+        memoDeclined = true;
+        return null;
+    }
+    memoFactory = factory;
+    objectRowFactories.set(fields, factory);
+    return factory;
+}
 export function parseObjectRow(parsers, data, columnCount, options, fields) {
+    // A compiled factory is built against `fields`, so it can only be used
+    // when the row really does have one value per field.
+    const factory = fields.length === columnCount
+        ? getObjectRowFactory(fields, columnCount)
+        : null;
+    if (factory) {
+        const values = new Array(columnCount);
+        let offset = 0;
+        let len;
+        let i;
+        for (i = 0; i < columnCount; i++) {
+            len = data.readInt32BE(offset);
+            offset += 4;
+            if (len < 0) {
+                values[i] = null;
+            }
+            else {
+                values[i] = parsers[i](data, offset, len, options);
+                offset += len;
+            }
+        }
+        return factory(values);
+    }
+    return parseObjectRowByAssignment(parsers, data, columnCount, options, fields);
+}
+function parseObjectRowByAssignment(parsers, data, columnCount, options, fields) {
     const row = {};
     let offset = 0;
     let len;

package/util/row-decoder.d.ts

@@ -0,0 +1,49 @@
+import type { DataMappingOptions } from '../interfaces/data-mapping-options.js';
+import type { FieldInfo } from '../interfaces/field-info.js';
+import type { AnyParseFunction } from '../types.js';
+/**
+ * Extension point for turning one row's raw wire data into whatever shape a
+ * caller wants. `data` is the row's own zero-copy buffer view and
+ * `columnCount`/`parsers` are exactly what `parseRow`/`parseObjectRow` take -
+ * a subclass is free to defer decoding individual columns (e.g. lazily, on
+ * first access) instead of eagerly decoding the whole row up front.
+ *
+ * Contract: `data` is never written to or reused by PostgreJS once `decode()`
+ * is called with it - it's safe to retain a reference to it (or a
+ * `Buffer.subarray()` of it) for as long as you want, e.g. to defer decoding
+ * a column until it's actually read. The only cost of doing so is memory:
+ * `data` is itself a zero-copy view into the socket's own read buffer (up to
+ * ~64KB), so holding onto even one row's `data` keeps that whole chunk (and
+ * every other row's bytes in it) alive until released.
+ */
+export declare abstract class RowDecoder {
+    abstract decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): any;
+}
+export declare class ArrayRowDecoder extends RowDecoder {
+    decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions): any[];
+}
+export declare class ObjectRowDecoder extends RowDecoder {
+    decode(parsers: AnyParseFunction[], data: Buffer, columnCount: number, options: DataMappingOptions, fields: FieldInfo[]): object;
+}
+export declare const DEFAULT_ARRAY_ROW_DECODER: ArrayRowDecoder;
+export declare const DEFAULT_OBJECT_ROW_DECODER: ObjectRowDecoder;
+interface RowDecoderOptions {
+    rowDecoder?: 'array' | 'object' | RowDecoder;
+    objectRows?: boolean;
+}
+/**
+ * Collapses the `rowDecoder`/`objectRows` query options into one RowDecoder
+ * instance - the single place this union gets resolved, so every call site
+ * (queryOnce/executeReused/the simple-query path/Cursor) applies the same
+ * precedence: an explicit `rowDecoder` wins over the deprecated `objectRows`
+ * boolean.
+ */
+export declare function resolveRowDecoder(options: RowDecoderOptions): RowDecoder;
+/**
+ * The `rowType` string surfaced on `QueryResult`/`Cursor.rowType`. `'custom'`
+ * when the caller supplied their own RowDecoder subclass - there's no way to
+ * know what shape it returns - otherwise the same `'array' | 'object'` this
+ * option has always reported.
+ */
+export declare function resolveRowType(options: RowDecoderOptions): 'array' | 'object' | 'custom';
+export {};

package/util/row-decoder.js

@@ -0,0 +1,63 @@
+import { parseObjectRow, parseRow } from './parse-row.js';
+/**
+ * Extension point for turning one row's raw wire data into whatever shape a
+ * caller wants. `data` is the row's own zero-copy buffer view and
+ * `columnCount`/`parsers` are exactly what `parseRow`/`parseObjectRow` take -
+ * a subclass is free to defer decoding individual columns (e.g. lazily, on
+ * first access) instead of eagerly decoding the whole row up front.
+ *
+ * Contract: `data` is never written to or reused by PostgreJS once `decode()`
+ * is called with it - it's safe to retain a reference to it (or a
+ * `Buffer.subarray()` of it) for as long as you want, e.g. to defer decoding
+ * a column until it's actually read. The only cost of doing so is memory:
+ * `data` is itself a zero-copy view into the socket's own read buffer (up to
+ * ~64KB), so holding onto even one row's `data` keeps that whole chunk (and
+ * every other row's bytes in it) alive until released.
+ */
+export class RowDecoder {
+}
+export class ArrayRowDecoder extends RowDecoder {
+    decode(parsers, data, columnCount, options) {
+        return parseRow(parsers, data, columnCount, options);
+    }
+}
+export class ObjectRowDecoder extends RowDecoder {
+    decode(parsers, data, columnCount, options, fields) {
+        return parseObjectRow(parsers, data, columnCount, options, fields);
+    }
+}
+export const DEFAULT_ARRAY_ROW_DECODER = new ArrayRowDecoder();
+export const DEFAULT_OBJECT_ROW_DECODER = new ObjectRowDecoder();
+/**
+ * Collapses the `rowDecoder`/`objectRows` query options into one RowDecoder
+ * instance - the single place this union gets resolved, so every call site
+ * (queryOnce/executeReused/the simple-query path/Cursor) applies the same
+ * precedence: an explicit `rowDecoder` wins over the deprecated `objectRows`
+ * boolean.
+ */
+export function resolveRowDecoder(options) {
+    const { rowDecoder } = options;
+    if (rowDecoder instanceof RowDecoder)
+        return rowDecoder;
+    if (rowDecoder === 'object')
+        return DEFAULT_OBJECT_ROW_DECODER;
+    if (rowDecoder === 'array')
+        return DEFAULT_ARRAY_ROW_DECODER;
+    return options.objectRows
+        ? DEFAULT_OBJECT_ROW_DECODER
+        : DEFAULT_ARRAY_ROW_DECODER;
+}
+/**
+ * The `rowType` string surfaced on `QueryResult`/`Cursor.rowType`. `'custom'`
+ * when the caller supplied their own RowDecoder subclass - there's no way to
+ * know what shape it returns - otherwise the same `'array' | 'object'` this
+ * option has always reported.
+ */
+export function resolveRowType(options) {
+    const decoder = resolveRowDecoder(options);
+    if (decoder instanceof ObjectRowDecoder)
+        return 'object';
+    if (decoder instanceof ArrayRowDecoder)
+        return 'array';
+    return 'custom';
+}