postgrejs 3.1.3 → 3.4.0

package/protocol/pg-socket.js

@@ -26,8 +26,6 @@ export class PgSocket extends SafeEventEmitter {
     _secretKey;
     _protocolNegotiation;
     _captureQueue = new DoublyLinked();
-    _pendingWrites = [];
-    _flushScheduled = false;
     _hosts = [];
     _hostIndex = 0;
     _sessionAttrsChecked = false;
@@ -240,15 +238,61 @@ export class PgSocket extends SafeEventEmitter {
      * statement/portal at the next Parse/Bind referencing the unnamed name.
      */
     sendExtendedQueryMessages(args, cb) {
-        const data = [
-            this._frontend.getParseMessage(args.parse),
-            this._frontend.getBindMessage(args.bind),
-            this._frontend.getDescribeMessage(args.describe),
-            this._frontend.getExecuteMessage(args.execute),
-            this._frontend.getSyncMessage(),
-        ];
+        if (!args.before && !args.after) {
+            const data = [
+                this._frontend.getParseMessage(args.parse),
+                this._frontend.getBindMessage(args.bind),
+                this._frontend.getDescribeMessage(args.describe),
+                this._frontend.getExecuteMessage(args.execute),
+                this._frontend.getSyncMessage(),
+            ];
+            return this._sendAndCapture(data, cb, 'sendExtendedQueryMessages', args);
+        }
+        const data = [];
+        if (args.before)
+            this._pushUtilityStatement(data, args.before, args.bind);
+        data.push(this._frontend.getParseMessage(args.parse), this._frontend.getBindMessage(args.bind), this._frontend.getDescribeMessage(args.describe), this._frontend.getExecuteMessage(args.execute));
+        if (args.after)
+            this._pushUtilityStatement(data, args.after, args.bind);
+        data.push(this._frontend.getSyncMessage());
         return this._sendAndCapture(data, cb, 'sendExtendedQueryMessages', args);
     }
+    /**
+     * Parse + Bind + Describe(portal) + Execute per statement, then a SINGLE
+     * Sync for the lot - the wire shape behind Connection.pipeline().
+     *
+     * The same framing as sendBatchBindExecuteMessages(), and the same
+     * consequences, except that each statement carries its own Parse rather
+     * than reusing one prepared statement: the statements share one implicit
+     * transaction, and PostgreSQL discards everything between an error and
+     * the Sync, so a rejected statement stops the ones behind it.
+     *
+     * Describe is not optional here even though nothing caches its answer.
+     * Without it the server sends DataRows for a row-returning statement with
+     * no RowDescription in front of them, leaving the column names and types
+     * unknown - the reason the one-shot path in sendExtendedQueryMessages()
+     * includes it too. It costs about a quarter of a millisecond across
+     * twenty statements, measured.
+     *
+     * Every Execute is unlimited (fetchCount 0): a portal that suspended
+     * mid-pipeline would answer PortalSuspended instead of CommandComplete
+     * and desynchronise the positional statement-to-result mapping.
+     */
+    sendPipelineMessages(args, cb) {
+        const l = args.statements.length;
+        const data = new Array(l * 4 + 1);
+        let i;
+        let st;
+        for (i = 0; i < l; i++) {
+            st = args.statements[i];
+            data[i * 4] = this._frontend.getParseMessage(st.parse);
+            data[i * 4 + 1] = this._frontend.getBindMessage(st.bind);
+            data[i * 4 + 2] = this._frontend.getDescribeMessage(st.describe);
+            data[i * 4 + 3] = this._frontend.getExecuteMessage(st.execute);
+        }
+        data[l * 4] = this._frontend.getSyncMessage();
+        return this._sendAndCapture(data, cb, 'sendPipelineMessages', args);
+    }
     /**
      * Parse + Describe(statement) + Sync as a single round trip - used by
      * PreparedStatement.prepare() instead of a separate awaited Parse then a
@@ -274,13 +318,56 @@ export class PgSocket extends SafeEventEmitter {
      * auto-clears an unnamed portal at the next Bind naming it.
      */
     sendBindExecuteMessages(args, cb) {
-        const data = [
-            this._frontend.getBindMessage(args.bind),
-            this._frontend.getExecuteMessage(args.execute),
-            this._frontend.getSyncMessage(),
-        ];
+        if (!args.before && !args.after) {
+            const data = [
+                this._frontend.getBindMessage(args.bind),
+                this._frontend.getExecuteMessage(args.execute),
+                this._frontend.getSyncMessage(),
+            ];
+            return this._sendAndCapture(data, cb, 'sendBindExecuteMessages', args);
+        }
+        const data = [];
+        if (args.before)
+            this._pushUtilityStatement(data, args.before, args.bind);
+        data.push(this._frontend.getBindMessage(args.bind), this._frontend.getExecuteMessage(args.execute));
+        if (args.after)
+            this._pushUtilityStatement(data, args.after, args.bind);
+        data.push(this._frontend.getSyncMessage());
         return this._sendAndCapture(data, cb, 'sendBindExecuteMessages', args);
     }
+    /**
+     * One Bind+Execute pair per parameter set against the same prepared
+     * statement, then a SINGLE Sync for the lot - the wire shape behind
+     * PreparedStatement.executeBatch().
+     *
+     * The single Sync is the whole point, and it is also what gives the
+     * batch its semantics. Sending Bind/Execute/Sync per set (what N
+     * separate execute() calls do, even pipelined) makes the server finish
+     * an implicit transaction and answer ReadyForQuery every time; one Sync
+     * at the end collapses that to one, which is where the bulk of the
+     * speedup comes from. It also means the sets share one implicit
+     * transaction, and that PostgreSQL discards everything between an error
+     * and the Sync - so a set that fails stops the ones behind it from
+     * running at all. Both of those are inherent to this framing rather
+     * than choices made above it.
+     *
+     * Every Execute here must be unlimited (fetchCount 0): a portal that
+     * suspends mid-batch would answer PortalSuspended instead of
+     * CommandComplete and desynchronise the positional set-to-result
+     * mapping the caller relies on.
+     */
+    sendBatchBindExecuteMessages(args, cb) {
+        const binds = args.binds;
+        const l = binds.length;
+        const data = new Array(l * 2 + 1);
+        let i;
+        for (i = 0; i < l; i++) {
+            data[i * 2] = this._frontend.getBindMessage(binds[i]);
+            data[i * 2 + 1] = this._frontend.getExecuteMessage(args.execute);
+        }
+        data[l * 2] = this._frontend.getSyncMessage();
+        return this._sendAndCapture(data, cb, 'sendBatchBindExecuteMessages', args);
+    }
     /**
      * Bind + Describe(portal) + Flush as a single round trip (NOT Sync - see
      * Portal.bindAndRetrieveFields()'s doc comment for why a Sync here would
@@ -407,6 +494,29 @@ export class PgSocket extends SafeEventEmitter {
             }
         });
     }
+    /**
+     * Parse + Bind + Execute for a parameterless utility statement, appended
+     * to a message list that is about to be closed by one Sync - how
+     * sendBindExecuteMessages() and sendExtendedQueryMessages() carry their
+     * `before`/`after` SQL (today, SAVEPOINT and RELEASE) in the same round
+     * trip as the statement itself rather than as a round trip each.
+     *
+     * Everything here goes through the unnamed statement and the unnamed
+     * portal. That is safe in this order: the caller's own Bind names a
+     * prepared statement rather than the unnamed one, and PostgreSQL
+     * processes the messages in sequence, so each Bind only ever discards an
+     * unnamed portal whose Execute has already run.
+     *
+     * No Describe: neither statement returns rows, so there is no
+     * RowDescription worth asking for. Result formats come from the caller's
+     * own Bind args, which likewise cost nothing against no columns.
+     */
+    _pushUtilityStatement(data, sql, bind) {
+        data.push(this._frontend.getParseMessage({ sql }), this._frontend.getBindMessage({
+            typeMap: bind.typeMap,
+            queryOptions: bind.queryOptions,
+        }), this._frontend.getExecuteMessage({}));
+    }
     _removeListeners() {
         if (!this._socket)
             return;
@@ -421,9 +531,6 @@ export class PgSocket extends SafeEventEmitter {
         this._processID = undefined;
         this._secretKey = undefined;
         this._saslSession = undefined;
-        // Anything still queued belonged to the connection being reset - it
-        // must never reach a freshly connected socket.
-        this._pendingWrites = [];
     }
     _handleConnect() {
         const socket = this._socket;
@@ -740,65 +847,38 @@ export class PgSocket extends SafeEventEmitter {
             result.rowCount = parseInt(m[2], 10);
         return result;
     }
-    /**
-     * Queues `data` for the socket instead of writing it straight through:
-     * everything handed to _send() during the same synchronous burst (e.g.
-     * many concurrent query() calls fired via Promise.all over one
-     * connection) is flushed together on the next tick, corked, so Node
-     * turns the whole batch into a single underlying writev rather than one
-     * socket write per call. Measured against postgres.js, which coalesces
-     * the same way at the application level (its connection.js write()/
-     * nextWrite() pair, flushing on a 1KB threshold or setImmediate): 50
-     * concurrent prepared executes cost it 3 socket writes where this cost
-     * us 50, and that write path was the single largest non-idle item in a
-     * CPU profile of the scenario.
-     *
-     * nextTick rather than setImmediate, deliberately: it still batches a
-     * whole synchronous burst, but a lone query doesn't have to wait for the
-     * event loop's check phase before its bytes go out - which would trade
-     * away the sequential/single-query scenarios to win the concurrent ones.
-     *
-     * Returns whether the socket could accept the data at all; the write
-     * itself is reported through `cb` (and a socket that dies before the
-     * flush rejects every pending capture via _failPendingCaptures()).
-     */
     _send(data, cb) {
-        if (!this._socket || !this._socket.writable)
+        const socket = this._socket;
+        if (!socket || !socket.writable)
             return false;
-        if (Array.isArray(data)) {
+        if (!Array.isArray(data)) {
+            socket.write(data, cb);
+            return true;
+        }
+        socket.cork();
+        try {
             const l = data.length;
-            for (let i = 0; i < l; i++)
-                this._pendingWrites.push({
-                    data: data[i],
-                    cb: i === l - 1 ? cb : undefined,
-                });
+            let i;
+            for (i = 0; i < l; i++)
+                socket.write(data[i], i === l - 1 ? cb : undefined);
         }
-        else
-            this._pendingWrites.push({ data, cb });
-        if (this._captureQueue.length > 1) {
-            if (!this._flushScheduled) {
-                this._flushScheduled = true;
-                process.nextTick(this._flushPendingWrites);
-            }
+        finally {
+            socket.uncork();
         }
-        else
-            this._flushPendingWrites();
         return true;
     }
     /**
-     * Writes COPY bytes straight through instead of queueing them for the
-     * next tick like _send() does. Two reasons: during a copy the capture
-     * queue holds exactly one entry (the Query that opened it), so _send()'s
-     * "batch only when more than one request is in flight" test would never
-     * fire and every chunk would be written on its own anyway; and the
-     * caller needs write()'s own return value to know when to stop, which a
-     * deferred write cannot give it.
+     * Same write as _send(), but reporting backpressure instead of
+     * writability: a COPY IN producer needs write()'s own return value to
+     * know when to stop pushing, whereas _send()'s callers only need to know
+     * whether the socket could take the bytes at all. Kept separate rather
+     * than folded into _send() precisely so those two meanings of `false`
+     * cannot be confused at a call site.
      */
     _sendCopy(data, cb) {
         const socket = this._socket;
         if (!socket || !socket.writable)
             return false;
-        this._flushPendingWrites();
         if (!Array.isArray(data))
             return socket.write(data, cb);
         socket.cork();
@@ -814,27 +894,4 @@ export class PgSocket extends SafeEventEmitter {
             socket.uncork();
         }
     }
-    /** Arrow property, not a method: used as a bare process.nextTick callback. */
-    _flushPendingWrites = () => {
-        this._flushScheduled = false;
-        const pending = this._pendingWrites;
-        if (!pending.length)
-            return;
-        this._pendingWrites = [];
-        const socket = this._socket;
-        if (!socket || !socket.writable)
-            return;
-        socket.cork();
-        try {
-            const l = pending.length;
-            let i;
-            for (i = 0; i < l; i++) {
-                const { data, cb } = pending[i];
-                socket.write(data, cb);
-            }
-        }
-        finally {
-            socket.uncork();
-        }
-    };
 }

package/protocol/pgoutput.js

@@ -106,7 +106,7 @@ export class PgOutputDecoder {
                 const lsn = readLsn(io);
                 const prefix = io.readCString();
                 const length = io.readUInt32BE();
-                return { kind: 'message', prefix, lsn, content: io.readBuffer(length) };
+                return { kind: 'message', prefix, lsn, content: io.readBytes(length) };
             }
             default:
                 return { kind: 'unknown', code };
@@ -134,7 +134,7 @@ export class PgOutputDecoder {
             }
             else {
                 const length = io.readUInt32BE();
-                out[column.name] = io.readBuffer(length).toString('utf8');
+                out[column.name] = io.readBytes(length).toString('utf8');
             }
         }
         return out;

package/protocol/smart-buffer.d.ts

@@ -1,37 +1,19 @@
-import { BufferReader } from './buffer-reader.js';
+import { FlexyBuffer } from 'flexy-buffer';
 export interface SmartBufferConfig {
     pageSize?: number;
     maxLength?: number;
-    houseKeepInterval?: number;
+    houseKeepMs?: number;
 }
-export declare class SmartBuffer extends BufferReader {
+/**
+ * Adds the PostgreSQL wire format's two string encodings on top of
+ * flexy-buffer's `FlexyBuffer`: a NUL-terminated C string, and a
+ * length-prefixed string where a `null`/`undefined` value is written as a
+ * length of -1 with no bytes following.
+ */
+export declare class SmartBuffer extends FlexyBuffer {
     static DEFAULT_PAGE_SIZE: number;
     static DEFAULT_MAX_SIZE: number;
-    private readonly _houseKeepInterval;
-    private _houseKeepTimer?;
-    private _stMaxPages;
-    private _length;
-    readonly pageSize: number;
-    readonly maxSize: number;
     constructor(cfg?: SmartBufferConfig);
-    get capacity(): number;
-    get length(): number;
-    start(): this;
-    flush(): Buffer;
-    growSize(len: number): this;
-    writeCString(str: string, encoding?: BufferEncoding): this;
-    writeLString(str?: string, encoding?: BufferEncoding): this;
-    writeString(str: string, encoding?: BufferEncoding): this;
-    writeInt8(n: number): this;
-    writeUInt8(n: number): this;
-    writeUInt16BE(n: number): this;
-    writeUInt32BE(n: number): this;
-    writeInt16BE(n: number): this;
-    writeInt32BE(n: number): this;
-    writeBigInt64BE(n: bigint | number): this;
-    writeFloatBE(n: number): this;
-    writeDoubleBE(n: number): this;
-    writeBuffer(buffer: Buffer): this;
-    private ensureSize;
-    private _houseKeep;
+    writeCString(str: string, encoding?: BufferEncoding): number;
+    writeLString(str?: string, encoding?: BufferEncoding): number;
 }

package/protocol/smart-buffer.js

@@ -1,172 +1,29 @@
+import { FlexyBuffer } from 'flexy-buffer';
 import * as os from 'os';
-import { writeBigUInt64BE } from '../util/bigint-methods.js';
-import { BufferReader } from './buffer-reader.js';
-export class SmartBuffer extends BufferReader {
+/**
+ * Adds the PostgreSQL wire format's two string encodings on top of
+ * flexy-buffer's `FlexyBuffer`: a NUL-terminated C string, and a
+ * length-prefixed string where a `null`/`undefined` value is written as a
+ * length of -1 with no bytes following.
+ */
+export class SmartBuffer extends FlexyBuffer {
     static DEFAULT_PAGE_SIZE = 512;
     static DEFAULT_MAX_SIZE = Math.min(Math.floor(os.totalmem() / 2), 1024 * 1024 * 1024 * 2);
-    _houseKeepInterval;
-    _houseKeepTimer;
-    _stMaxPages = 1;
-    _length = 0;
-    pageSize;
-    maxSize;
     constructor(cfg) {
-        super(Buffer.allocUnsafe(cfg?.pageSize || SmartBuffer.DEFAULT_PAGE_SIZE));
-        this._houseKeepInterval = cfg?.houseKeepInterval || 5000;
-        this.pageSize = this.buffer.length;
-        this.maxSize = cfg?.maxLength || SmartBuffer.DEFAULT_MAX_SIZE;
-        this._length = 0;
-    }
-    get capacity() {
-        return this.buffer.length;
-    }
-    get length() {
-        return this._length;
-    }
-    start() {
-        this.offset = 0;
-        this._length = 0;
-        if (this._houseKeepTimer) {
-            clearTimeout(this._houseKeepTimer);
-            this._houseKeepTimer = undefined;
-        }
-        return this;
-    }
-    flush() {
-        if (this._houseKeepTimer)
-            clearTimeout(this._houseKeepTimer);
-        const length = this.length;
-        this._length = 0;
-        const out = Buffer.from(this.buffer.subarray(0, length));
-        const pages = length ? Math.ceil(length / this.pageSize) : 1;
-        this._stMaxPages = Math.max(this._stMaxPages, pages);
-        this._houseKeep();
-        if (this.buffer.length > this.pageSize) {
-            this._houseKeepTimer = setTimeout(() => {
-                this._houseKeepTimer = undefined;
-                this._houseKeep();
-            }, this._houseKeepInterval).unref();
-        }
-        return out;
-    }
-    growSize(len) {
-        const endOffset = this.offset + len;
-        if (this.capacity < endOffset) {
-            if (endOffset > this.maxSize)
-                throw new Error('Buffer limit exceeded.');
-            const byPage = Math.ceil(endOffset / this.pageSize) * this.pageSize;
-            const newSize = Math.min(Math.max(byPage, this.capacity * 2), this.maxSize);
-            const newBuffer = Buffer.allocUnsafe(newSize);
-            this.buffer.copy(newBuffer);
-            this.buffer = newBuffer;
-        }
-        this._length = Math.max(this.length, endOffset);
-        return this;
+        super({
+            pageSize: cfg?.pageSize || SmartBuffer.DEFAULT_PAGE_SIZE,
+            maxLength: cfg?.maxLength || SmartBuffer.DEFAULT_MAX_SIZE,
+            houseKeepMs: cfg?.houseKeepMs,
+        });
     }
     writeCString(str, encoding) {
-        const len = str ? Buffer.byteLength(str, encoding) : 0;
-        this.ensureSize(len + 1);
-        if (str) {
-            this.buffer.write(str, this.offset, encoding);
-            this.offset += len;
-        }
-        this.writeUInt8(0);
-        return this;
+        const written = this.writeString(str, encoding);
+        return written + this.writeUInt8(0);
     }
     writeLString(str, encoding) {
-        const len = str ? Buffer.byteLength(str, encoding) : 0;
-        this.ensureSize(len + 4);
-        this.writeInt32BE(str == null ? -1 : len);
-        if (str) {
-            if (encoding)
-                this.offset += this.buffer.write(str, this.offset, encoding);
-            else
-                this.offset += this.buffer.write(str, this.offset);
-        }
-        return this;
-    }
-    writeString(str, encoding) {
-        if (str) {
-            const len = Buffer.byteLength(str, encoding);
-            this.ensureSize(len);
-            this.offset += this.buffer.write(str, this.offset, encoding);
-        }
-        return this;
-    }
-    writeInt8(n) {
-        this.ensureSize(1);
-        this.buffer.writeInt8(n, this.offset);
-        this.offset++;
-        return this;
-    }
-    writeUInt8(n) {
-        this.ensureSize(1);
-        this.buffer.writeUInt8(n, this.offset);
-        this.offset++;
-        return this;
-    }
-    writeUInt16BE(n) {
-        this.ensureSize(2);
-        this.buffer.writeUInt16BE(n, this.offset);
-        this.offset += 2;
-        return this;
-    }
-    writeUInt32BE(n) {
-        this.ensureSize(4);
-        this.buffer.writeUInt32BE(n, this.offset);
-        this.offset += 4;
-        return this;
-    }
-    writeInt16BE(n) {
-        this.ensureSize(2);
-        this.buffer.writeInt16BE(n, this.offset);
-        this.offset += 2;
-        return this;
-    }
-    writeInt32BE(n) {
-        this.ensureSize(4);
-        this.buffer.writeInt32BE(n, this.offset);
-        this.offset += 4;
-        return this;
-    }
-    writeBigInt64BE(n) {
-        n = typeof n === 'bigint' ? n : BigInt(n);
-        this.ensureSize(8);
-        if (typeof this.buffer.writeBigInt64BE === 'function')
-            this.buffer.writeBigInt64BE(n, this.offset);
-        else
-            writeBigUInt64BE(this.buffer, n, this.offset);
-        this.offset += 8;
-        return this;
-    }
-    writeFloatBE(n) {
-        this.ensureSize(4);
-        this.buffer.writeFloatBE(n, this.offset);
-        this.offset += 4;
-        return this;
-    }
-    writeDoubleBE(n) {
-        this.ensureSize(8);
-        this.buffer.writeDoubleBE(n, this.offset);
-        this.offset += 8;
-        return this;
-    }
-    writeBuffer(buffer) {
-        this.ensureSize(buffer.length);
-        buffer.copy(this.buffer, this.offset, 0, buffer.length);
-        this.offset += buffer.length;
-        return this;
-    }
-    ensureSize(len) {
-        const n = this.offset + len - this.length;
-        if (n > 0)
-            this.growSize(n);
-        return this;
-    }
-    _houseKeep() {
-        const needSize = this._stMaxPages * this.pageSize;
-        if (this.buffer.length > needSize)
-            this.buffer = Buffer.allocUnsafe(needSize);
-        this._stMaxPages = this.length ? Math.ceil(this.length / this.pageSize) : 1;
+        if (str == null)
+            return this.writeInt32BE(-1);
+        const len = Buffer.byteLength(str, encoding);
+        return this.writeInt32BE(len) + this.writeString(str, encoding);
     }
 }

package/types.d.ts

@@ -5,7 +5,19 @@ export type Maybe<T> = T | undefined;
 export type Nullable<T> = T | null;
 export type Row = any;
 export type Callback = (err?: Error | null) => void;
-export type DecodeBinaryFunction = (buf: Buffer, offset: number, options: DataMappingOptions & Record<string, any>) => any;
+/**
+ * What a DataType's own `decodeBinary` implements. `buf` is a shared
+ * buffer - the whole row, or the whole array - and this value occupies
+ * exactly `len` bytes starting at `offset`.
+ *
+ * Honouring `len` is the implementation's responsibility, and reading past
+ * it is not a bounds error: it silently returns the next column's or
+ * element's bytes. A type whose binary form says how long it is - a fixed
+ * width like int4's four bytes, or a count it carries itself like
+ * numeric's - can ignore `len`; anything that would otherwise read "to the
+ * end of the buffer" must not.
+ */
+export type DecodeBinaryFunction = (buf: Buffer, offset: number, len: number, options: DataMappingOptions & Record<string, any>) => any;
 export type DecodeTextBufferFunction = (buf: Buffer, offset: number, len: number, options: DataMappingOptions & Record<string, any>) => any;
 export type EncodeBinaryFunction = (buf: SmartBuffer, v: any, options: DataMappingOptions) => void;
 export type EncodeCalculateDimFunction = (v: any[]) => number[];

package/util/assert-integer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Returns `v` coerced to an integer, or throws when it cannot be one.
+ *
+ * `fastParseInt()` already answers NaN for a value with no integer reading
+ * - `'abc'`, `{}`, `[]`, `true` - but `Buffer.writeInt32BE(NaN)` then
+ * stores a silent zero, so the answer is lost exactly where it matters.
+ * Nothing downstream can tell that apart from a real zero afterwards: the
+ * row inserts, the copy succeeds, and the wrong number is in the table.
+ *
+ * Floats are deliberately not rejected: truncating 3.7 to 3 is the
+ * long-standing behaviour of these encoders and is usually what a caller
+ * writing into an integer column means. Only "this is not a number at all"
+ * is refused.
+ *
+ * Unlike the integer types, float4/float8/numeric leave NaN alone - it is a
+ * value PostgreSQL stores and returns as NaN, distinct from NULL, on every
+ * supported server version.
+ */
+export declare function assertInteger(v: number, typeName: string): number;
+/**
+ * Returns `parsed` when a value that was NOT already a number coerced to
+ * one, and throws when it did not.
+ *
+ * Kept apart from assertInteger() because the two families disagree about
+ * NaN on purpose. float4/float8/numeric all store NaN as a value distinct
+ * from NULL, so a caller passing the number NaN means it and it never
+ * reaches here - the encoders take `typeof v === 'number'` straight
+ * through. What does reach here is `'abc'`, `{}` or `true`, whose coercion
+ * produced NaN because they have no numeric reading at all; writing those
+ * as NaN would be indistinguishable afterwards from a NaN that was meant.
+ */
+export declare function assertCoercedNumber(parsed: number, typeName: string): number;
+/**
+ * Refuses a value that only has an integer reading through a coercion
+ * nobody asked for.
+ *
+ * int8 goes to `BigInt` rather than through `fastParseInt()`, and BigInt is
+ * happy to convert things that are not numbers at all: `BigInt([])` is 0n
+ * because an empty array stringifies to "", and `BigInt(true)` is 1n. A
+ * bad value in a bigint column would land as a plausible-looking 0 or 1,
+ * so only the types that genuinely carry an integer are let through.
+ */
+export declare function assertBigIntSource(v: any, typeName: string): bigint | number;

package/util/assert-integer.js

@@ -0,0 +1,58 @@
+/**
+ * Returns `v` coerced to an integer, or throws when it cannot be one.
+ *
+ * `fastParseInt()` already answers NaN for a value with no integer reading
+ * - `'abc'`, `{}`, `[]`, `true` - but `Buffer.writeInt32BE(NaN)` then
+ * stores a silent zero, so the answer is lost exactly where it matters.
+ * Nothing downstream can tell that apart from a real zero afterwards: the
+ * row inserts, the copy succeeds, and the wrong number is in the table.
+ *
+ * Floats are deliberately not rejected: truncating 3.7 to 3 is the
+ * long-standing behaviour of these encoders and is usually what a caller
+ * writing into an integer column means. Only "this is not a number at all"
+ * is refused.
+ *
+ * Unlike the integer types, float4/float8/numeric leave NaN alone - it is a
+ * value PostgreSQL stores and returns as NaN, distinct from NULL, on every
+ * supported server version.
+ */
+export function assertInteger(v, typeName) {
+    if (Number.isNaN(v)) {
+        throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
+    }
+    return v;
+}
+/**
+ * Returns `parsed` when a value that was NOT already a number coerced to
+ * one, and throws when it did not.
+ *
+ * Kept apart from assertInteger() because the two families disagree about
+ * NaN on purpose. float4/float8/numeric all store NaN as a value distinct
+ * from NULL, so a caller passing the number NaN means it and it never
+ * reaches here - the encoders take `typeof v === 'number'` straight
+ * through. What does reach here is `'abc'`, `{}` or `true`, whose coercion
+ * produced NaN because they have no numeric reading at all; writing those
+ * as NaN would be indistinguishable afterwards from a NaN that was meant.
+ */
+export function assertCoercedNumber(parsed, typeName) {
+    if (Number.isNaN(parsed)) {
+        throw new TypeError(`Cannot encode value as ${typeName}: it has no numeric value`);
+    }
+    return parsed;
+}
+/**
+ * Refuses a value that only has an integer reading through a coercion
+ * nobody asked for.
+ *
+ * int8 goes to `BigInt` rather than through `fastParseInt()`, and BigInt is
+ * happy to convert things that are not numbers at all: `BigInt([])` is 0n
+ * because an empty array stringifies to "", and `BigInt(true)` is 1n. A
+ * bad value in a bigint column would land as a plausible-looking 0 or 1,
+ * so only the types that genuinely carry an integer are let through.
+ */
+export function assertBigIntSource(v, typeName) {
+    const t = typeof v;
+    if (t === 'bigint' || t === 'number' || t === 'string')
+        return v;
+    throw new TypeError(`Cannot encode value as ${typeName}: it has no integer value`);
+}