joist-orm 2.3.0-next.41 → 2.3.0-next.43

package/build/drivers/WireRowData.js

@@ -1,430 +1,370 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.WireRowData = void 0;
-exports.executeRowDataQuery = executeRowDataQuery;
-exports.isRowDataCapableClient = isRowDataCapableClient;
-const pg_1 = __importDefault(require("pg"));
-const binaryParsers_1 = require("./binaryParsers");
-// pg's internal-but-exported Query class; subclassing it reuses its extended-protocol
-// submit/bind logic while letting us intercept row handling (the same seam pg-cursor uses).
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const PgQuery = require("pg/lib/query");
-// Each row is three consecutive entries in the `#rowSlices` table: chunk index, start, length
+import { getBinaryTypeParser } from "./binaryParsers.js";
+import { createRequire } from "node:module";
+import "joist-core";
+import pg from "pg";
+//#region src/drivers/WireRowData.ts
+const PgQuery = createRequire(import.meta.url)("pg/lib/query");
 const ROW_STRIDE = 3;
 /** The row-length sentinel for rows dropped by `finalize` compaction. */
-const DROPPED = 0xffffffff;
+const DROPPED = 4294967295;
 /** Only compact when dropped rows hold more than this fraction of the payload bytes. */
-const COMPACT_THRESHOLD = 0.2;
+const COMPACT_THRESHOLD = .2;
 /**
- * Only allocate the adaptive scan cursor once a fault targets at least this ordinal: shallower
- * scans cost less than the cursor's bookkeeping, i.e. hydrate-only results (id is ordinal ~0)
- * and narrow reads never pay the 6 bytes/row.
- */
+* Only allocate the adaptive scan cursor once a fault targets at least this ordinal: shallower
+* scans cost less than the cursor's bookkeeping, i.e. hydrate-only results (id is ordinal ~0)
+* and narrow reads never pay the 6 bytes/row.
+*/
 const SCAN_CURSOR_MIN_ORDINAL = 8;
 /**
- * A lazy wire-row {@link RowData} over raw Postgres `DataRow` payload bytes.
- *
- * Each query produces its own `WireRowData` — one query, one result; results are never combined
- * or appended across queries, and the payload is read-only after the query completes (entity
- * mutations go into `InstanceData.data`, never back into the row bytes).
- *
- * Rows are kept in their row-major wire format (`int16 fieldCount` + length-prefixed cells) as
- * zero-copy views over the parser's own immutable buffers: `addRow` records each DataRow's
- * `(bytes, offset, length)` by reference, deduping the socket chunk that consecutive rows
- * share. (Our pg-protocol patch guarantees message bytes are never rewritten — chunks parse in
- * place and straddling messages get a buffer of their own; see `patchPgProtocol.ts`.) A
- * `row × column` cell is decoded on first field access by scanning the row's length-prefixed
- * cells to the column's ordinal ("row-lazy" decode, see JS-ROW-STORE-DESIGN.md §3/C2). This is
- * deferred decoding of row-major data, not a columnar layout.
- *
- * Because chunks are whole socket reads, retaining any row pins its ~64KiB chunk (plus whatever
- * protocol frames share it); `finalize`'s compaction copies retained rows out into an
- * exact-size owned buffer when enough of the payload was dropped.
- *
- * Text-format cells go through the same active text parsers node-postgres would resolve for
- * the query (i.e. honoring pool/client `TypeOverrides`), so they parse identically to classic
- * rows. Binary-format cells decode via `wireBinaryParser`: wire bytes -> value directly for
- * default-parsed scalar types (no intermediate string), else rendered to pg's canonical text
- * and fed through the active text parser for parity. (Classic node-postgres cannot do binary
- * at all — it round-trips cells through a UTF-8 string, corrupting bytes >= 0x80.)
- *
- * Because decoding is deferred, a custom parser that throws will do so on first field access
- * (or `toRow`/`toRows`), not while awaiting the query; `id` and inheritance-discriminator cells
- * still decode during hydration.
- *
- * After hydration, `finalize` trims unused capacity and, when some rows were not retained (i.e.
- * their entities were already in the identity map), compacts the payload down to only the
- * retained rows, so retained memory tracks live entities rather than query history.
- *
- * Small results deliberately stay lazy — there is NO row-count threshold below which we
- * materialize to a `PojoRowData` instead. Measured (benchmark-rowdata-small.ts, 40-col rows):
- * for the typical sparse access pattern (~6 of 40 columns read), keeping the lazy result wins at
- * every size including a single row (n=1: 4.3µs vs 7.6µs; n=1000: 0.76ms vs 3.0ms), because
- * materialization eagerly decodes every column while lazy faults only what is read. Even full
- * column coverage no longer flips the winner: with binary decode and `#readCell`'s adaptive
- * scan cursor, reading all ~36 columns of every row measures ~parity with classic end-to-end
- * (benchmark-lazy-parsing.ts), and small finds (n <= 10) are statistically identical.
- */
-class WireRowData {
-    #chunks = [];
-    /** Where each row's bytes live: `(chunk index, start, length)` slices, `ROW_STRIDE` entries per row. */
-    #rowSlices = new Uint32Array(16 * ROW_STRIDE);
-    #rowCount = 0;
-    #payloadBytes = 0;
-    #retained = undefined;
-    #columns = new Map();
-    #fields = [];
-    /** The adaptive scan cursor: per row, the furthest scanned ordinal + its offset (see #readCell). */
-    #scanOrdinal = undefined;
-    #scanOffset = undefined;
-    get rowCount() {
-        return this.#rowCount;
-    }
-    /** The DataRow payload bytes currently indexed; drops when compaction discards rows. */
-    get payloadBytes() {
-        return this.#payloadBytes;
-    }
-    /** The bytes currently held by payload chunks + the row-slice table, i.e. for benchmarks. */
-    get memoryBytes() {
-        let bytes = this.#rowSlices.byteLength;
-        for (const chunk of this.#chunks)
-            bytes += chunk.length;
-        return bytes;
-    }
-    get(rowIndex, columnName) {
-        const column = this.#columns.get(columnName);
-        // Tolerate probes for columns the query didn't select, i.e. `__class` on non-CTI queries
-        if (column === undefined)
-            return undefined;
-        const base = this.#rowBase(rowIndex);
-        const slices = this.#rowSlices;
-        const start = slices[base + 1];
-        return this.#readCell(this.#chunks[slices[base]], start, start + slices[base + 2], column, rowIndex);
-    }
-    /** Materializes one row as a POJO, i.e. for debugging and differential tests; values are not cached. */
-    toRow(rowIndex) {
-        const base = this.#rowBase(rowIndex);
-        const slices = this.#rowSlices;
-        const chunk = this.#chunks[slices[base]];
-        const start = slices[base + 1];
-        const end = start + slices[base + 2];
-        const row = {};
-        let pos = start + 2;
-        for (const field of this.#fields) {
-            const len = this.#cellLength(chunk, pos, end, rowIndex);
-            pos += 4;
-            if (len === -1) {
-                row[field.name] = null;
-            }
-            else {
-                row[field.name] = field.decode(chunk, pos, len);
-                pos += len;
-            }
-        }
-        return row;
-    }
-    /** Materializes classic POJO rows, i.e. for `afterFind` observation or debugging; not cached. */
-    toRows() {
-        const rows = new Array(this.#rowCount);
-        for (let i = 0; i < this.#rowCount; i++)
-            rows[i] = this.toRow(i);
-        return rows;
-    }
-    /**
-     * Resolves each column's decoder from the query's RowDescription.
-     *
-     * Binary-format fields decode through Joist's own binary registry only (see
-     * `setBinaryTypeParser`) — `pg.types`/`TypeOverrides` are never consulted, and a column whose
-     * oid has no registered binary parser fails the query here, before any rows arrive, rather
-     * than guessing at a lossy decoding. Text-format fields (the `binary: false` escape hatch)
-     * decode by utf8-slicing the cell into the active text parser, resolved via `getTypeParser`
-     * (i.e. the pool/client `TypeOverrides` chain) or the global registry.
-     */
-    setRowDescription(fields, getTypeParser) {
-        for (let i = 0; i < fields.length; i++) {
-            const { name, dataTypeID, format } = fields[i];
-            let decode;
-            if (format === "binary") {
-                decode = (0, binaryParsers_1.getBinaryTypeParser)(dataTypeID);
-                if (decode === undefined) {
-                    throw new Error(`joist-orm: no binary type parser registered for oid ${dataTypeID} (column "${name}");` +
-                        ` register one with setBinaryTypeParser (i.e. binaryTextParser for text-like types)`);
-                }
-            }
-            else {
-                const parse = getTypeParser?.(dataTypeID) ?? pg_1.default.types.getTypeParser(dataTypeID, "text");
-                decode = textCellDecoder(parse);
-            }
-            const column = { name, ordinal: i, decode };
-            this.#columns.set(name, column);
-            this.#fields.push(column);
-        }
-    }
-    /**
-     * Records one DataRow payload *by reference* (zero-copy); called synchronously from the wire
-     * parser, whose patched buffer management guarantees the bytes are never rewritten.
-     *
-     * Consecutive rows usually share one socket chunk, so `bytes` is deduped against the last
-     * chunk ref; retaining any row of a chunk pins the whole chunk, which `finalize`'s compaction
-     * resolves by copying retained rows out when enough of the payload was dropped.
-     */
-    addRow(bytes, offset, payloadLength) {
-        if (payloadLength < 2 || offset + payloadLength > bytes.length) {
-            throw new Error(`Malformed DataRow payload (length ${payloadLength})`);
-        }
-        let chunkIndex = this.#chunks.length - 1;
-        if (chunkIndex === -1 || this.#chunks[chunkIndex] !== bytes) {
-            this.#chunks.push(bytes);
-            chunkIndex++;
-        }
-        let slices = this.#rowSlices;
-        const base = this.#rowCount * ROW_STRIDE;
-        if (base === slices.length) {
-            const grown = new Uint32Array(slices.length * 2);
-            grown.set(slices);
-            slices = this.#rowSlices = grown;
-        }
-        slices[base] = chunkIndex;
-        slices[base + 1] = offset;
-        slices[base + 2] = payloadLength;
-        this.#rowCount++;
-        this.#payloadBytes += payloadLength;
-    }
-    /** Marks `rowIndex` as retained by a hydrated entity; unmarked rows can be compacted away. */
-    retain(rowIndex) {
-        (this.#retained ??= []).push(rowIndex);
-    }
-    /**
-     * Trims unused capacity, and compacts down to only `retain`-ed rows when enough rows were not
-     * retained to be worth the copy.
-     *
-     * Compaction exists to release pinned socket buffers to the GC: rows are zero-copy views into
-     * whole ~64KiB chunks, so keeping any row alive pins its entire chunk — and unretained rows
-     * are typically duplicates whose entities were *already in memory* (identity-map hits that
-     * keep their original `rowData`), making the newly-arrived bytes dead weight. Copying the
-     * retained rows into one exact-size owned buffer lets every chunk reference drop.
-     *
-     * The copy re-copies every retained byte, so it only pays off when it buys back a meaningful
-     * fraction of the payload: we compact when the dropped rows hold more than 20% of the payload
-     * bytes, and otherwise just trim, accepting the (bounded) leftover bytes. Called once after
-     * hydration + sidecar reads (`_tags`, preload aggregates) are complete; retained entities keep
-     * their original `rowIndex`, and un-compacted unretained rows simply remain readable-but-unused.
-     */
-    finalize() {
-        const retained = this.#retained ?? [];
-        this.#retained = undefined;
-        if (retained.length < this.#rowCount) {
-            let retainedBytes = 0;
-            for (const i of retained)
-                retainedBytes += this.#rowSlices[i * ROW_STRIDE + 2];
-            const droppedBytes = this.#payloadBytes - retainedBytes;
-            if (droppedBytes > this.#payloadBytes * COMPACT_THRESHOLD) {
-                this.#compact(retained, retainedBytes);
-                return;
-            }
-        }
-        // Just shrink the row-slice table to its used size
-        if (this.#rowCount * ROW_STRIDE < this.#rowSlices.length) {
-            this.#rowSlices = this.#rowSlices.slice(0, this.#rowCount * ROW_STRIDE);
-        }
-    }
-    /** Copies retained rows into one owned buffer, releasing the pinned socket chunks to the GC. */
-    #compact(retained, bytes) {
-        const chunks = bytes > 0 ? [Buffer.allocUnsafe(bytes)] : [];
-        const slices = new Uint32Array(this.#rowCount * ROW_STRIDE);
-        for (let i = 0; i < this.#rowCount; i++)
-            slices[i * ROW_STRIDE + 2] = DROPPED;
-        let used = 0;
-        for (const i of retained) {
-            const base = i * ROW_STRIDE;
-            const source = this.#chunks[this.#rowSlices[base]];
-            const start = this.#rowSlices[base + 1];
-            const len = this.#rowSlices[base + 2];
-            source.copy(chunks[0], used, start, start + len);
-            slices[base] = 0;
-            slices[base + 1] = used;
-            slices[base + 2] = len;
-            used += len;
-        }
-        this.#chunks = chunks;
-        this.#rowSlices = slices;
-        this.#payloadBytes = used;
-        // The scan cursor survives: its cached offsets are relative to each row's (copied) payload
-    }
-    /** Validates `rowIndex` and returns its base index into the `#rowSlices` table. */
-    #rowBase(rowIndex) {
-        if (!(rowIndex >= 0 && rowIndex < this.#rowCount)) {
-            throw new Error(`Invalid rowIndex ${rowIndex} (rowCount ${this.#rowCount})`);
-        }
-        const base = rowIndex * ROW_STRIDE;
-        if (this.#rowSlices[base + 2] === DROPPED) {
-            throw new Error(`Row ${rowIndex} was compacted away (its entity was already loaded)`);
-        }
-        return base;
-    }
-    /**
-     * Scans a row's cells to `column`'s ordinal and decodes it.
-     *
-     * An adaptive per-row scan cursor caches the furthest cell boundary already scanned — the
-     * ordinal whose row-relative offset is known (`#scanOrdinal`/`#scanOffset`) — so ascending
-     * reads resume instead of re-scanning from the row start: a dense in-order read of all C
-     * columns costs one linear pass rather than O(C^2) length-prefix skips. Out-of-order
-     * (descending) faults simply scan from the start, i.e. never worse than without the cursor.
-     * The arrays are a fixed 6 bytes/row, allocated lazily on the first fault deep enough for
-     * resuming to matter, and — being row-relative — stay valid across compaction.
-     */
-    #readCell(chunk, start, end, column, rowIndex) {
-        const fieldCount = chunk.readInt16BE(start);
-        const { ordinal } = column;
-        if (ordinal >= fieldCount) {
-            throw new Error(`Row ${rowIndex} has ${fieldCount} cells but column ${column.name} is #${column.ordinal}`);
-        }
-        let pos = start + 2;
-        let c = 0;
-        let scanOrdinal = this.#scanOrdinal;
-        if (scanOrdinal === undefined && ordinal >= SCAN_CURSOR_MIN_ORDINAL) {
-            scanOrdinal = this.#scanOrdinal = new Uint16Array(this.#rowCount);
-            this.#scanOffset = new Uint32Array(this.#rowCount);
-        }
-        if (scanOrdinal !== undefined && rowIndex < scanOrdinal.length) {
-            // 0 = unset: caching cell #0 would be pointless (it is always at offset 2), so any real
-            // entry is the ordinal, >= 1, whose row-relative offset is in #scanOffset
-            const known = scanOrdinal[rowIndex];
-            if (known !== 0 && known <= ordinal) {
-                c = known;
-                pos = start + this.#scanOffset[rowIndex];
-            }
-        }
-        for (; c < ordinal; c++) {
-            const len = this.#cellLength(chunk, pos, end, rowIndex);
-            pos += len > 0 ? len + 4 : 4;
-        }
-        const len = this.#cellLength(chunk, pos, end, rowIndex);
-        if (scanOrdinal !== undefined && rowIndex < scanOrdinal.length && ordinal + 1 > scanOrdinal[rowIndex]) {
-            // advance-only: after reading cell #ordinal we know where cell #ordinal+1 starts
-            scanOrdinal[rowIndex] = ordinal + 1;
-            this.#scanOffset[rowIndex] = pos + 4 + (len > 0 ? len : 0) - start;
-        }
-        if (len === -1)
-            return null;
-        return column.decode(chunk, pos + 4, len);
-    }
-    /** Reads + validates one cell's length prefix. */
-    #cellLength(chunk, pos, end, rowIndex) {
-        if (pos + 4 > end)
-            throw new Error(`Truncated DataRow payload in row ${rowIndex}`);
-        const len = chunk.readInt32BE(pos);
-        if (len < -1 || (len > 0 && pos + 4 + len > end)) {
-            throw new Error(`Malformed cell length ${len} in row ${rowIndex}`);
-        }
-        return len;
-    }
-}
-exports.WireRowData = WireRowData;
+* A lazy wire-row {@link RowData} over raw Postgres `DataRow` payload bytes.
+*
+* Each query produces its own `WireRowData` — one query, one result; results are never combined
+* or appended across queries, and the payload is read-only after the query completes (entity
+* mutations go into `InstanceData.data`, never back into the row bytes).
+*
+* Rows are kept in their row-major wire format (`int16 fieldCount` + length-prefixed cells) as
+* zero-copy views over the parser's own immutable buffers: `addRow` records each DataRow's
+* `(bytes, offset, length)` by reference, deduping the socket chunk that consecutive rows
+* share. (Our pg-protocol patch guarantees message bytes are never rewritten — chunks parse in
+* place and straddling messages get a buffer of their own; see `patchPgProtocol.ts`.) A
+* `row × column` cell is decoded on first field access by scanning the row's length-prefixed
+* cells to the column's ordinal ("row-lazy" decode, see JS-ROW-STORE-DESIGN.md §3/C2). This is
+* deferred decoding of row-major data, not a columnar layout.
+*
+* Because chunks are whole socket reads, retaining any row pins its ~64KiB chunk (plus whatever
+* protocol frames share it); `finalize`'s compaction copies retained rows out into an
+* exact-size owned buffer when enough of the payload was dropped.
+*
+* Text-format cells go through the same active text parsers node-postgres would resolve for
+* the query (i.e. honoring pool/client `TypeOverrides`), so they parse identically to classic
+* rows. Binary-format cells decode via `wireBinaryParser`: wire bytes -> value directly for
+* default-parsed scalar types (no intermediate string), else rendered to pg's canonical text
+* and fed through the active text parser for parity. (Classic node-postgres cannot do binary
+* at all — it round-trips cells through a UTF-8 string, corrupting bytes >= 0x80.)
+*
+* Because decoding is deferred, a custom parser that throws will do so on first field access
+* (or `toRow`/`toRows`), not while awaiting the query; `id` and inheritance-discriminator cells
+* still decode during hydration.
+*
+* After hydration, `finalize` trims unused capacity and, when some rows were not retained (i.e.
+* their entities were already in the identity map), compacts the payload down to only the
+* retained rows, so retained memory tracks live entities rather than query history.
+*
+* Small results deliberately stay lazy — there is NO row-count threshold below which we
+* materialize to a `PojoRowData` instead. Measured (benchmark-rowdata-small.ts, 40-col rows):
+* for the typical sparse access pattern (~6 of 40 columns read), keeping the lazy result wins at
+* every size including a single row (n=1: 4.3µs vs 7.6µs; n=1000: 0.76ms vs 3.0ms), because
+* materialization eagerly decodes every column while lazy faults only what is read. Even full
+* column coverage no longer flips the winner: with binary decode and `#readCell`'s adaptive
+* scan cursor, reading all ~36 columns of every row measures ~parity with classic end-to-end
+* (benchmark-lazy-parsing.ts), and small finds (n <= 10) are statistically identical.
+*/
+var WireRowData = class {
+	#chunks = [];
+	/** Where each row's bytes live: `(chunk index, start, length)` slices, `ROW_STRIDE` entries per row. */
+	#rowSlices = /* @__PURE__ */ new Uint32Array(48);
+	#rowCount = 0;
+	#payloadBytes = 0;
+	#retained = void 0;
+	#columns = /* @__PURE__ */ new Map();
+	#fields = [];
+	/** The adaptive scan cursor: per row, the furthest scanned ordinal + its offset (see #readCell). */
+	#scanOrdinal = void 0;
+	#scanOffset = void 0;
+	get rowCount() {
+		return this.#rowCount;
+	}
+	/** The DataRow payload bytes currently indexed; drops when compaction discards rows. */
+	get payloadBytes() {
+		return this.#payloadBytes;
+	}
+	/** The bytes currently held by payload chunks + the row-slice table, i.e. for benchmarks. */
+	get memoryBytes() {
+		let bytes = this.#rowSlices.byteLength;
+		for (const chunk of this.#chunks) bytes += chunk.length;
+		return bytes;
+	}
+	get(rowIndex, columnName) {
+		const column = this.#columns.get(columnName);
+		if (column === void 0) return void 0;
+		const base = this.#rowBase(rowIndex);
+		const slices = this.#rowSlices;
+		const start = slices[base + 1];
+		return this.#readCell(this.#chunks[slices[base]], start, start + slices[base + 2], column, rowIndex);
+	}
+	/** Materializes one row as a POJO, i.e. for debugging and differential tests; values are not cached. */
+	toRow(rowIndex) {
+		const base = this.#rowBase(rowIndex);
+		const slices = this.#rowSlices;
+		const chunk = this.#chunks[slices[base]];
+		const start = slices[base + 1];
+		const end = start + slices[base + 2];
+		const row = {};
+		let pos = start + 2;
+		for (const field of this.#fields) {
+			const len = this.#cellLength(chunk, pos, end, rowIndex);
+			pos += 4;
+			if (len === -1) row[field.name] = null;
+			else {
+				row[field.name] = field.decode(chunk, pos, len);
+				pos += len;
+			}
+		}
+		return row;
+	}
+	/** Materializes classic POJO rows, i.e. for `afterFind` observation or debugging; not cached. */
+	toRows() {
+		const rows = new Array(this.#rowCount);
+		for (let i = 0; i < this.#rowCount; i++) rows[i] = this.toRow(i);
+		return rows;
+	}
+	/**
+	* Resolves each column's decoder from the query's RowDescription.
+	*
+	* Binary-format fields decode through Joist's own binary registry only (see
+	* `setBinaryTypeParser`) — `pg.types`/`TypeOverrides` are never consulted, and a column whose
+	* oid has no registered binary parser fails the query here, before any rows arrive, rather
+	* than guessing at a lossy decoding. Text-format fields (the `binary: false` escape hatch)
+	* decode by utf8-slicing the cell into the active text parser, resolved via `getTypeParser`
+	* (i.e. the pool/client `TypeOverrides` chain) or the global registry.
+	*/
+	setRowDescription(fields, getTypeParser) {
+		for (let i = 0; i < fields.length; i++) {
+			const { name, dataTypeID, format } = fields[i];
+			let decode;
+			if (format === "binary") {
+				decode = getBinaryTypeParser(dataTypeID);
+				if (decode === void 0) throw new Error(`joist-orm: no binary type parser registered for oid ${dataTypeID} (column "${name}"); register one with setBinaryTypeParser (i.e. binaryTextParser for text-like types)`);
+			} else decode = textCellDecoder(getTypeParser?.(dataTypeID) ?? pg.types.getTypeParser(dataTypeID, "text"));
+			const column = {
+				name,
+				ordinal: i,
+				decode
+			};
+			this.#columns.set(name, column);
+			this.#fields.push(column);
+		}
+	}
+	/**
+	* Records one DataRow payload *by reference* (zero-copy); called synchronously from the wire
+	* parser, whose patched buffer management guarantees the bytes are never rewritten.
+	*
+	* Consecutive rows usually share one socket chunk, so `bytes` is deduped against the last
+	* chunk ref; retaining any row of a chunk pins the whole chunk, which `finalize`'s compaction
+	* resolves by copying retained rows out when enough of the payload was dropped.
+	*/
+	addRow(bytes, offset, payloadLength) {
+		if (payloadLength < 2 || offset + payloadLength > bytes.length) throw new Error(`Malformed DataRow payload (length ${payloadLength})`);
+		let chunkIndex = this.#chunks.length - 1;
+		if (chunkIndex === -1 || this.#chunks[chunkIndex] !== bytes) {
+			this.#chunks.push(bytes);
+			chunkIndex++;
+		}
+		let slices = this.#rowSlices;
+		const base = this.#rowCount * ROW_STRIDE;
+		if (base === slices.length) {
+			const grown = new Uint32Array(slices.length * 2);
+			grown.set(slices);
+			slices = this.#rowSlices = grown;
+		}
+		slices[base] = chunkIndex;
+		slices[base + 1] = offset;
+		slices[base + 2] = payloadLength;
+		this.#rowCount++;
+		this.#payloadBytes += payloadLength;
+	}
+	/** Marks `rowIndex` as retained by a hydrated entity; unmarked rows can be compacted away. */
+	retain(rowIndex) {
+		(this.#retained ??= []).push(rowIndex);
+	}
+	/**
+	* Trims unused capacity, and compacts down to only `retain`-ed rows when enough rows were not
+	* retained to be worth the copy.
+	*
+	* Compaction exists to release pinned socket buffers to the GC: rows are zero-copy views into
+	* whole ~64KiB chunks, so keeping any row alive pins its entire chunk — and unretained rows
+	* are typically duplicates whose entities were *already in memory* (identity-map hits that
+	* keep their original `rowData`), making the newly-arrived bytes dead weight. Copying the
+	* retained rows into one exact-size owned buffer lets every chunk reference drop.
+	*
+	* The copy re-copies every retained byte, so it only pays off when it buys back a meaningful
+	* fraction of the payload: we compact when the dropped rows hold more than 20% of the payload
+	* bytes, and otherwise just trim, accepting the (bounded) leftover bytes. Called once after
+	* hydration + sidecar reads (`_tags`, preload aggregates) are complete; retained entities keep
+	* their original `rowIndex`, and un-compacted unretained rows simply remain readable-but-unused.
+	*/
+	finalize() {
+		const retained = this.#retained ?? [];
+		this.#retained = void 0;
+		if (retained.length < this.#rowCount) {
+			let retainedBytes = 0;
+			for (const i of retained) retainedBytes += this.#rowSlices[i * ROW_STRIDE + 2];
+			if (this.#payloadBytes - retainedBytes > this.#payloadBytes * COMPACT_THRESHOLD) {
+				this.#compact(retained, retainedBytes);
+				return;
+			}
+		}
+		if (this.#rowCount * ROW_STRIDE < this.#rowSlices.length) this.#rowSlices = this.#rowSlices.slice(0, this.#rowCount * ROW_STRIDE);
+	}
+	/** Copies retained rows into one owned buffer, releasing the pinned socket chunks to the GC. */
+	#compact(retained, bytes) {
+		const chunks = bytes > 0 ? [Buffer.allocUnsafe(bytes)] : [];
+		const slices = new Uint32Array(this.#rowCount * ROW_STRIDE);
+		for (let i = 0; i < this.#rowCount; i++) slices[i * ROW_STRIDE + 2] = DROPPED;
+		let used = 0;
+		for (const i of retained) {
+			const base = i * ROW_STRIDE;
+			const source = this.#chunks[this.#rowSlices[base]];
+			const start = this.#rowSlices[base + 1];
+			const len = this.#rowSlices[base + 2];
+			source.copy(chunks[0], used, start, start + len);
+			slices[base] = 0;
+			slices[base + 1] = used;
+			slices[base + 2] = len;
+			used += len;
+		}
+		this.#chunks = chunks;
+		this.#rowSlices = slices;
+		this.#payloadBytes = used;
+	}
+	/** Validates `rowIndex` and returns its base index into the `#rowSlices` table. */
+	#rowBase(rowIndex) {
+		if (!(rowIndex >= 0 && rowIndex < this.#rowCount)) throw new Error(`Invalid rowIndex ${rowIndex} (rowCount ${this.#rowCount})`);
+		const base = rowIndex * ROW_STRIDE;
+		if (this.#rowSlices[base + 2] === DROPPED) throw new Error(`Row ${rowIndex} was compacted away (its entity was already loaded)`);
+		return base;
+	}
+	/**
+	* Scans a row's cells to `column`'s ordinal and decodes it.
+	*
+	* An adaptive per-row scan cursor caches the furthest cell boundary already scanned — the
+	* ordinal whose row-relative offset is known (`#scanOrdinal`/`#scanOffset`) — so ascending
+	* reads resume instead of re-scanning from the row start: a dense in-order read of all C
+	* columns costs one linear pass rather than O(C^2) length-prefix skips. Out-of-order
+	* (descending) faults simply scan from the start, i.e. never worse than without the cursor.
+	* The arrays are a fixed 6 bytes/row, allocated lazily on the first fault deep enough for
+	* resuming to matter, and — being row-relative — stay valid across compaction.
+	*/
+	#readCell(chunk, start, end, column, rowIndex) {
+		const fieldCount = chunk.readInt16BE(start);
+		const { ordinal } = column;
+		if (ordinal >= fieldCount) throw new Error(`Row ${rowIndex} has ${fieldCount} cells but column ${column.name} is #${column.ordinal}`);
+		let pos = start + 2;
+		let c = 0;
+		let scanOrdinal = this.#scanOrdinal;
+		if (scanOrdinal === void 0 && ordinal >= SCAN_CURSOR_MIN_ORDINAL) {
+			scanOrdinal = this.#scanOrdinal = new Uint16Array(this.#rowCount);
+			this.#scanOffset = new Uint32Array(this.#rowCount);
+		}
+		if (scanOrdinal !== void 0 && rowIndex < scanOrdinal.length) {
+			const known = scanOrdinal[rowIndex];
+			if (known !== 0 && known <= ordinal) {
+				c = known;
+				pos = start + this.#scanOffset[rowIndex];
+			}
+		}
+		for (; c < ordinal; c++) {
+			const len = this.#cellLength(chunk, pos, end, rowIndex);
+			pos += len > 0 ? len + 4 : 4;
+		}
+		const len = this.#cellLength(chunk, pos, end, rowIndex);
+		if (scanOrdinal !== void 0 && rowIndex < scanOrdinal.length && ordinal + 1 > scanOrdinal[rowIndex]) {
+			scanOrdinal[rowIndex] = ordinal + 1;
+			this.#scanOffset[rowIndex] = pos + 4 + (len > 0 ? len : 0) - start;
+		}
+		if (len === -1) return null;
+		return column.decode(chunk, pos + 4, len);
+	}
+	/** Reads + validates one cell's length prefix. */
+	#cellLength(chunk, pos, end, rowIndex) {
+		if (pos + 4 > end) throw new Error(`Truncated DataRow payload in row ${rowIndex}`);
+		const len = chunk.readInt32BE(pos);
+		if (len < -1 || len > 0 && pos + 4 + len > end) throw new Error(`Malformed cell length ${len} in row ${rowIndex}`);
+		return len;
+	}
+};
 /**
- * Executes `sql` on an already-checked-out client, returning a {@link RowData} instead of
- * materialized POJO rows.
- *
- * Uses a `pg` Query subclass that records each DataRow's raw payload bytes into the result
- * (via the lazy DataRow message from `patchPgProtocol`) and never materializes per-cell
- * strings or per-row objects. If the client's connection turns out to use an unpatched
- * pg-protocol copy (i.e. the app's pool was built from a different `pg` install than the one
- * joist-orm patched), the query fails with a descriptive error — a misconfiguration any CI
- * build/smoketest will surface immediately, so we fail loudly rather than silently degrade.
- * The rows already streamed are discarded; the connection itself stays usable.
- *
- * By default the query requests *binary* result format (via the extended protocol), so scalar
- * cells decode wire-bytes -> value with no intermediate strings; see `wireBinaryParser` for the
- * parity strategy. Pass `binary: false` for classic text-format results, or set
- * `JOIST_LAZY_BINARY=0` to flip the default while the binary path is a prototype (i.e. for
- * A/B benchmarking or as an escape hatch).
- */
-// The prototype escape hatch for binary results, i.e. for A/B benchmarking; read once at load
+* Executes `sql` on an already-checked-out client, returning a {@link RowData} instead of
+* materialized POJO rows.
+*
+* Uses a `pg` Query subclass that records each DataRow's raw payload bytes into the result
+* (via the lazy DataRow message from `patchPgProtocol`) and never materializes per-cell
+* strings or per-row objects. If the client's connection turns out to use an unpatched
+* pg-protocol copy (i.e. the app's pool was built from a different `pg` install than the one
+* joist-orm patched), the query fails with a descriptive error — a misconfiguration any CI
+* build/smoketest will surface immediately, so we fail loudly rather than silently degrade.
+* The rows already streamed are discarded; the connection itself stays usable.
+*
+* By default the query requests *binary* result format (via the extended protocol), so scalar
+* cells decode wire-bytes -> value with no intermediate strings; see `wireBinaryParser` for the
+* parity strategy. Pass `binary: false` for classic text-format results, or set
+* `JOIST_LAZY_BINARY=0` to flip the default while the binary path is a prototype (i.e. for
+* A/B benchmarking or as an escape hatch).
+*/
 const BINARY_BY_DEFAULT = process.env.JOIST_LAZY_BINARY !== "0";
 function executeRowDataQuery(client, sql, bindings, opts) {
-    const binary = opts?.binary ?? BINARY_BY_DEFAULT;
-    return new Promise((resolve, reject) => {
-        const query = new RowDataQuery(
-        // Binary results require the extended protocol; `queryMode` forces it for bindings-less queries
-        binary
-            ? { text: sql, values: bindings, binary: true, queryMode: "extended" }
-            : { text: sql, values: bindings }, (err) => {
-            if (err)
-                reject(err);
-            else
-                resolve(query.rowData);
-        });
-        client.query(query);
-    });
+	const binary = opts?.binary ?? BINARY_BY_DEFAULT;
+	return new Promise((resolve, reject) => {
+		const query = new RowDataQuery(binary ? {
+			text: sql,
+			values: bindings,
+			binary: true,
+			queryMode: "extended"
+		} : {
+			text: sql,
+			values: bindings
+		}, (err) => {
+			if (err) reject(err);
+			else resolve(query.rowData);
+		});
+		client.query(query);
+	});
 }
 /** Returns whether `client` supports the lazy row-data query path, before submitting anything. */
 function isRowDataCapableClient(client) {
-    // Require the pure-JS pg client (pg-native has no `connection` and different query internals)
-    return (typeof client === "object" &&
-        client !== null &&
-        typeof client.query === "function" &&
-        client.connection !== undefined &&
-        client.native === undefined);
+	return typeof client === "object" && client !== null && typeof client.query === "function" && client.connection !== void 0 && client.native === void 0;
 }
 /** A pg Query that diverts DataRows into a {@link WireRowData} instead of a `Result`. */
-class RowDataQuery extends PgQuery {
-    #wire = new WireRowData();
-    constructor(config, callback) {
-        super(config, undefined, callback);
-    }
-    /**
-     * The query's result rows, i.e. once our callback has fired.
-     *
-     * If a small-result materialization threshold ever seems attractive, this is where it would
-     * go — but see the "Small results deliberately stay lazy" note on {@link WireRowData}: lazy
-     * won the measured comparison at every row count for sparse access, so no threshold exists.
-     */
-    get rowData() {
-        return this.#wire;
-    }
-    handleRowDescription(msg) {
-        if (this._canceledDueToError)
-            return;
-        try {
-            super.handleRowDescription(msg);
-            // Resolve active *text* parsers through the client's TypeOverrides chain (client.js
-            // injects `_types` at submit time); we can't reuse `Result._parsers` because in binary
-            // mode those resolve to pg's (broken) binary registry, while our binary decode path is
-            // built on text-parser parity — see `wireBinaryParser`
-            const types = this._result?._types;
-            this.#wire.setRowDescription(msg.fields, types && ((oid) => types.getTypeParser(oid, "text")));
-        }
-        catch (err) {
-            // Mirror pg's Query error containment: record + reject at ReadyForQuery, keeping the
-            // connection's protocol state intact
-            this._canceledDueToError = err;
-        }
-    }
-    handleDataRow(msg) {
-        if (this._canceledDueToError)
-            return;
-        try {
-            if (msg.bytes === undefined) {
-                // This connection's pg-protocol copy is unpatched (i.e. the pool came from a different
-                // `pg` install than the one joist-orm patched), so lazyRows cannot work — fail loudly
-                // rather than silently degrade; any CI build/smoketest will surface this immediately
-                throw new Error("joist-orm: lazyRows is enabled, but this connection's pg-protocol emits classic" +
-                    " DataRows (likely a duplicate pg install); fix the install or disable lazyRows.");
-            }
-            // `msg.length` includes the int32 length field itself, so the payload is `length - 4`;
-            // our patched message carries the real length from `handlePacket`'s argument
-            this.#wire.addRow(msg.bytes, msg.offset, msg.length - 4);
-        }
-        catch (err) {
-            this._canceledDueToError = err;
-        }
-    }
-}
+var RowDataQuery = class extends PgQuery {
+	#wire = new WireRowData();
+	constructor(config, callback) {
+		super(config, void 0, callback);
+	}
+	/**
+	* The query's result rows, i.e. once our callback has fired.
+	*
+	* If a small-result materialization threshold ever seems attractive, this is where it would
+	* go — but see the "Small results deliberately stay lazy" note on {@link WireRowData}: lazy
+	* won the measured comparison at every row count for sparse access, so no threshold exists.
+	*/
+	get rowData() {
+		return this.#wire;
+	}
+	handleRowDescription(msg) {
+		if (this._canceledDueToError) return;
+		try {
+			super.handleRowDescription(msg);
+			const types = this._result?._types;
+			this.#wire.setRowDescription(msg.fields, types && ((oid) => types.getTypeParser(oid, "text")));
+		} catch (err) {
+			this._canceledDueToError = err;
+		}
+	}
+	handleDataRow(msg) {
+		if (this._canceledDueToError) return;
+		try {
+			if (msg.bytes === void 0) throw new Error("joist-orm: lazyRows is enabled, but this connection's pg-protocol emits classic DataRows (likely a duplicate pg install); fix the install or disable lazyRows.");
+			this.#wire.addRow(msg.bytes, msg.offset, msg.length - 4);
+		} catch (err) {
+			this._canceledDueToError = err;
+		}
+	}
+};
 /** Builds a text-format cell decoder: utf8-slice the cell bytes into the active text parser. */
 function textCellDecoder(parse) {
-    return (chunk, start, length) => parse(chunk.toString("utf8", start, start + length));
+	return (chunk, start, length) => parse(chunk.toString("utf8", start, start + length));
 }
+//#endregion
+export { WireRowData, executeRowDataQuery, isRowDataCapableClient };
+
 //# sourceMappingURL=WireRowData.js.map