postgrejs 3.12.2 → 3.14.0

package/protocol/smart-buffer.js

@@ -6,9 +6,29 @@ import * as os from 'os';
  * length-prefixed string where a `null`/`undefined` value is written as a
  * length of -1 with no bytes following.
  */
+/** The ceiling on `maxSizeFor`, and its answer when there is no machine to measure. */
+const HARD_MAX = 1024 * 1024 * 1024 * 2; // 2 GB
+/**
+ * The most a buffer may ever hold, given how much memory the machine has.
+ *
+ * @param totalMemory Bytes of memory, or 0 when that cannot be known.
+ * @returns Half of it, capped - or the cap alone when it is unknown.
+ */
+/* `os.totalmem()` answers 0 where there is no machine to ask about:
+   measured under Cloudflare's workerd, where `node:os` resolves and
+   returns zeros rather than throwing. Taking the minimum of that was a
+   maximum size of zero, which worked only because flexy-buffer reads a
+   falsy `maxLength` as "use the default" - an accident, and one that
+   would have become a buffer refusing every write the day that default
+   changed. */
+export function maxSizeFor(totalMemory) {
+    return totalMemory > 0
+        ? Math.min(Math.floor(totalMemory / 2), HARD_MAX)
+        : HARD_MAX;
+}
 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);
+    static DEFAULT_MAX_SIZE = maxSizeFor(typeof os.totalmem === 'function' ? os.totalmem() : 0);
     constructor(cfg) {
         super({
             pageSize: cfg?.pageSize || SmartBuffer.DEFAULT_PAGE_SIZE,

package/protocol/workerd-socket.d.ts

@@ -0,0 +1,87 @@
+import { SafeEventEmitter } from '../safe-event-emitter.js';
+/** What `cloudflare:sockets` hands back, as much of it as is used here. */
+interface CfSocket {
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+    closed: Promise<void>;
+    close(): Promise<void>;
+    startTls(options: {
+        expectedServerHostname?: string;
+    }): CfSocket;
+}
+/** The one function `cloudflare:sockets` is reached for. */
+export type CfConnect = (address: string, options?: {
+    secureTransport?: 'off' | 'on' | 'starttls';
+}) => CfSocket;
+/**
+ * A `net.Socket`-shaped view of a Cloudflare socket, for the part of it
+ * this client uses: `connect`, `write`, `destroy`, and `data`/`error`/
+ * `close` events, plus `startTls()`, which is the one thing Node's
+ * `tls.connect({ socket })` cannot do on that runtime.
+ *
+ * Reads are a loop over the stream rather than a `'data'` event the
+ * runtime emits, so the loop is what turns one into the other.
+ */
+export declare class WorkerdSocket extends SafeEventEmitter {
+    private readonly _wantsTls;
+    private readonly _connect;
+    private _cf?;
+    private _writer?;
+    private _reader?;
+    private _upgrading;
+    private _destroyed;
+    private _paused?;
+    private _resume?;
+    constructor(_wantsTls: boolean, _connect?: () => Promise<CfConnect>);
+    /** Whether a TLS upgrade has been asked for and completed. */
+    get secure(): boolean;
+    private _secure;
+    /** Whether `destroy()` has been called. */
+    get destroyed(): boolean;
+    /** Whether writes are still accepted. */
+    get writable(): boolean;
+    cork(): void;
+    uncork(): void;
+    setNoDelay(): this;
+    setKeepAlive(): this;
+    setTimeout(): this;
+    /** Stops reading, so the sender is made to wait. */
+    pause(): this;
+    /** Starts reading again. */
+    resume(): this;
+    /** Closes the connection once anything already written has gone. */
+    end(): this;
+    /**
+     * Opens the connection and emits `connect` once it is writable.
+     *
+     * @param port The port to reach.
+     * @param host The host to reach.
+     */
+    connect(port: number, host: string): void;
+    /**
+     * Reads one chunk and hands it over, without starting the loop.
+     *
+     * @param cb Called with the bytes, or with nothing if the connection
+     * ended first.
+     */
+    readOnce(cb: (data?: Buffer) => void): void;
+    /**
+     * Upgrades the connection in place.
+     *
+     * @param servername The name to check the certificate against.
+     */
+    startTls(servername?: string): void;
+    /**
+     * Writes to the connection.
+     *
+     * @param data The bytes to send.
+     * @param cb Called once they are written, or with the error.
+     * @returns True - the runtime offers no "buffer is full" answer.
+     */
+    write(data: Uint8Array, cb?: (err?: Error | null) => void): boolean;
+    /** Closes the connection; `close` follows once the runtime agrees. */
+    destroy(): this;
+    protected _attach(cf: CfSocket, readLoop: boolean): void;
+    protected _read(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void>;
+}
+export {};

package/protocol/workerd-socket.js

@@ -0,0 +1,245 @@
+import { SafeEventEmitter } from '../safe-event-emitter.js';
+/* Imported where it is called rather than at the top of the file: the
+   specifier does not resolve off workerd, and this module is reachable
+   from a Node build through `pg-socket.ts`. Nothing awaits it unless a
+   connection is actually being made on that runtime. */
+const importCfConnect = async () => (await import(/* webpackIgnore: true */ 'cloudflare:sockets'))
+    .connect;
+/**
+ * A `net.Socket`-shaped view of a Cloudflare socket, for the part of it
+ * this client uses: `connect`, `write`, `destroy`, and `data`/`error`/
+ * `close` events, plus `startTls()`, which is the one thing Node's
+ * `tls.connect({ socket })` cannot do on that runtime.
+ *
+ * Reads are a loop over the stream rather than a `'data'` event the
+ * runtime emits, so the loop is what turns one into the other.
+ */
+/* Written here rather than taken from `pg-cloudflare`, which does the
+   same job for `pg`: the adapter is a hundred lines whose lifecycle this
+   client would otherwise not control, and only the upgrade is actually
+   needed - the plain path on workerd already works through `node:net`.
+
+   The setNoDelay/setKeepAlive/setTimeout trio answers nothing because
+   the runtime exposes no equivalent; they are here so the connect path
+   above can treat both socket kinds the same way. */
+export class WorkerdSocket extends SafeEventEmitter {
+    _wantsTls;
+    _connect;
+    _cf;
+    _writer;
+    _reader;
+    /* True between startTls() and the old socket's `closed` settling: that
+       promise resolves because the socket was replaced, not because the
+       connection went away, and reporting it as a close would end the
+       session in the middle of its handshake. */
+    _upgrading = false;
+    _destroyed = false;
+    _paused;
+    _resume;
+    constructor(_wantsTls, _connect = importCfConnect) {
+        super();
+        this._wantsTls = _wantsTls;
+        this._connect = _connect;
+    }
+    /** Whether a TLS upgrade has been asked for and completed. */
+    get secure() {
+        return this._secure;
+    }
+    _secure = false;
+    /** Whether `destroy()` has been called. */
+    get destroyed() {
+        return this._destroyed;
+    }
+    /** Whether writes are still accepted. */
+    get writable() {
+        return !this._destroyed && !!this._writer;
+    }
+    /* `cork`/`uncork` gather several small writes into one syscall on
+       Node. There is no syscall to gather here - a write is a promise
+       against a stream - so the pair is accepted and does nothing, which
+       is what it means on this runtime. */
+    cork() {
+        /* nothing to gather */
+    }
+    uncork() {
+        /* nothing to gather */
+    }
+    setNoDelay() {
+        return this;
+    }
+    setKeepAlive() {
+        return this;
+    }
+    setTimeout() {
+        return this;
+    }
+    /** Stops reading, so the sender is made to wait. */
+    /* Real backpressure rather than a no-op: the read loop is what pulls
+       from the stream, so not pulling is the whole of it. `pause()` during
+       a COPY TO is the only caller, and a stream left unread is how the
+       runtime learns to stop. */
+    pause() {
+        if (!this._paused)
+            this._paused = new Promise(r => (this._resume = r));
+        return this;
+    }
+    /** Starts reading again. */
+    resume() {
+        const go = this._resume;
+        this._paused = undefined;
+        this._resume = undefined;
+        go?.();
+        return this;
+    }
+    /** Closes the connection once anything already written has gone. */
+    end() {
+        return this.destroy();
+    }
+    /**
+     * Opens the connection and emits `connect` once it is writable.
+     *
+     * @param port The port to reach.
+     * @param host The host to reach.
+     */
+    connect(port, host) {
+        void (async () => {
+            try {
+                const connect = await this._connect();
+                this._cf = connect(`${host}:${port}`, {
+                    // `starttls` leaves the connection in the clear and allows a
+                    // later upgrade, which is what the SSLRequest exchange needs.
+                    secureTransport: this._wantsTls ? 'starttls' : 'off',
+                });
+                /* No read loop yet when a TLS upgrade is coming: `releaseLock()`
+                   throws on a reader with an outstanding read, and a loop parked
+                   in `reader.read()` is exactly that. The negotiation asks for
+                   the one byte it expects through `readOnce()`, and the loop
+                   starts on the upgraded socket. */
+                this._attach(this._cf, !this._wantsTls);
+                await this._writer.ready;
+                this.emit('connect');
+            }
+            catch (e) {
+                this.emit('error', e);
+            }
+        })();
+    }
+    /**
+     * Reads one chunk and hands it over, without starting the loop.
+     *
+     * @param cb Called with the bytes, or with nothing if the connection
+     * ended first.
+     */
+    /* What the SSLRequest exchange needs: a single answer, read while no
+       loop holds the reader, so the lock can be released for the upgrade
+       that follows. */
+    readOnce(cb) {
+        const reader = this._reader;
+        if (!reader)
+            return cb();
+        reader.read().then(({ done, value }) => cb(done || !value ? undefined : Buffer.from(value)), (e) => {
+            this.emit('error', e);
+            cb();
+        });
+    }
+    /**
+     * Upgrades the connection in place.
+     *
+     * @param servername The name to check the certificate against.
+     */
+    /* The locks have to go back before the socket is replaced, and the new
+       one needs its own reader and writer and its own read loop. */
+    startTls(servername) {
+        const cf = this._cf;
+        if (!cf) {
+            this.emit('error', new Error('Cannot upgrade a socket that is not connected'));
+            return;
+        }
+        try {
+            this._writer.releaseLock();
+            this._reader.releaseLock();
+            this._upgrading = true;
+            this._cf = cf.startTls(servername ? { expectedServerHostname: servername } : {});
+            this._attach(this._cf, true);
+            void this._writer.ready.then(() => {
+                this._secure = true;
+                this.emit('secureConnect');
+            }, (e) => this.emit('error', e));
+        }
+        catch (e) {
+            this.emit('error', e);
+        }
+    }
+    /**
+     * Writes to the connection.
+     *
+     * @param data The bytes to send.
+     * @param cb Called once they are written, or with the error.
+     * @returns True - the runtime offers no "buffer is full" answer.
+     */
+    write(data, cb) {
+        const writer = this._writer;
+        if (!writer) {
+            cb?.(new Error('Socket is not connected'));
+            return true;
+        }
+        writer.write(data).then(() => cb?.(), (e) => {
+            cb?.(e);
+            this.emit('error', e);
+        });
+        return true;
+    }
+    /** Closes the connection; `close` follows once the runtime agrees. */
+    destroy() {
+        if (this._destroyed)
+            return this;
+        this._destroyed = true;
+        const cf = this._cf;
+        this._cf = undefined;
+        cf?.close().catch(() => undefined);
+        return this;
+    }
+    _attach(cf, readLoop) {
+        this._writer = cf.writable.getWriter();
+        this._reader = cf.readable.getReader();
+        if (readLoop)
+            void this._read(this._reader);
+        cf.closed.then(() => {
+            if (this._upgrading) {
+                this._upgrading = false;
+                return;
+            }
+            this.emit('close');
+        }, (e) => {
+            if (this._upgrading) {
+                this._upgrading = false;
+                return;
+            }
+            this.emit('error', e);
+        });
+    }
+    async _read(reader) {
+        try {
+            for (;;) {
+                if (this._paused)
+                    await this._paused;
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                /* Asked again on the way out: a pause() during a read already in
+                   flight cannot un-await it, and delivering that chunk anyway
+                   would be data arriving after the consumer said stop. */
+                if (this._paused)
+                    await this._paused;
+                if (value?.length)
+                    this.emit('data', Buffer.from(value));
+            }
+        }
+        catch (e) {
+            // A read that ends because the socket was replaced is the upgrade
+            // happening, not a failure to report.
+            if (!this._upgrading && !this._destroyed)
+                this.emit('error', e);
+        }
+    }
+}

package/util/resolved-bind-type.d.ts

@@ -0,0 +1,15 @@
+import type { Maybe, OID } from '../types.js';
+/**
+ * The types to encode a Bind's parameters against, given what the caller
+ * declared and what the server resolved.
+ *
+ * Returns `declared` unchanged unless some parameter can be improved, so
+ * the common call allocates nothing.
+ *
+ * @param declared What went into Parse - `0`/undefined where this client
+ * declared nothing and left the type to the server.
+ * @param params The values about to be written.
+ * @param resolved What the server answered for this statement, in order.
+ * @returns The types to hand `getBindMessage`.
+ */
+export declare function resolvedBindTypes(declared: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, resolved: Maybe<OID[]>): Maybe<Maybe<OID>[]>;

package/util/resolved-bind-type.js

@@ -0,0 +1,85 @@
+import { DataTypeOIDs } from '../constants.js';
+import { arrayLeaf } from './array-leaf.js';
+/**
+ * The types a `Date` is allowed to be encoded into binary against, by
+ * whether the value is an array.
+ */
+/* Deliberately short. `time` and `timetz` are left out because
+   TimeType.encodeBinary() multiplies the whole epoch by 1000 and
+   overflows for any ordinary Date - measured, every one of four test
+   instants answered 22008 "time out of range", where the text path
+   stores the wall clock correctly. Nothing else here may be reached
+   until it has been checked the same way. */
+const DATE_SCALARS = new Set([
+    DataTypeOIDs.timestamptz,
+    DataTypeOIDs.timestamp,
+    DataTypeOIDs.date,
+]);
+const DATE_ARRAYS = new Set([
+    DataTypeOIDs._timestamptz,
+    DataTypeOIDs._timestamp,
+    DataTypeOIDs._date,
+]);
+/**
+ * The types to encode a Bind's parameters against, given what the caller
+ * declared and what the server resolved.
+ *
+ * Returns `declared` unchanged unless some parameter can be improved, so
+ * the common call allocates nothing.
+ *
+ * @param declared What went into Parse - `0`/undefined where this client
+ * declared nothing and left the type to the server.
+ * @param params The values about to be written.
+ * @param resolved What the server answered for this statement, in order.
+ * @returns The types to hand `getBindMessage`.
+ */
+/* A Date goes out as text because nothing but the server knows whether
+   the column is an instant or a wall clock - see `isUnspecifiedParam()`.
+   Once the statement has a name, the server has already said which, and
+   saying it does not have to be repeated: a prepared statement's
+   parameter types are fixed at Parse, so a later Bind may send binary
+   against them with no re-Parse. Checked on the wire: Parse with no
+   declared types resolves `$1` to 1184, and a Bind of eight binary bytes
+   against that statement reads back correctly.
+
+   Worth it only because the text is wide and the binary is not. Measured
+   over a loopback connection, 20 000 elements:
+
+       timestamptz[]   text 625 KB / 11.61ms    binary 234 KB / 3.79ms
+
+   The same measurement is why this is not done for numbers: an int4[] of
+   ordinary values is 380 KB of text against 781 KB of binary, because
+   the binary array format carries a 4-byte length per element whatever
+   its magnitude - there, text is both smaller and twice as fast.
+
+   Binary and text store the same value, which is the thing that had to
+   be true before any of this: checked for timestamptz, timestamp and
+   date, over four instants spanning a DST boundary and including
+   milliseconds, and for the array forms of two of them. */
+export function resolvedBindTypes(declared, params, resolved) {
+    if (!resolved || !params)
+        return declared;
+    const l = params.length;
+    let out;
+    let i;
+    for (i = 0; i < l; i++) {
+        // A type the caller named is an answer, not a guess - left alone.
+        if (declared?.[i])
+            continue;
+        const oid = resolved[i];
+        if (!oid)
+            continue;
+        const v = params[i];
+        if (!(arrayLeaf(v) instanceof Date))
+            continue;
+        // An array value needs an array type and a scalar needs a scalar
+        // one: getBindMessage() picks its encoder from the type alone and
+        // would hand an array to a scalar encoder.
+        if (!(Array.isArray(v) ? DATE_ARRAYS : DATE_SCALARS).has(oid))
+            continue;
+        if (!out)
+            out = declared ? declared.slice() : new Array(l).fill(0);
+        out[i] = oid;
+    }
+    return out || declared;
+}

package/util/runtime.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether this client is running inside a Cloudflare Worker.
+ *
+ * @returns True on workerd, false on Node.js, Bun and anything else.
+ */
+export declare function isWorkerd(): boolean;

package/util/runtime.js

@@ -0,0 +1,19 @@
+/**
+ * Whether this client is running inside a Cloudflare Worker.
+ *
+ * @returns True on workerd, false on Node.js, Bun and anything else.
+ */
+/* The documented tell, and the one `pg` uses: since the
+   `global_navigator` compatibility flag went on, workerd defines
+   `navigator.userAgent` and sets it to exactly this. Node and Bun define
+   `navigator` too, with a userAgent of their own, so the test is for the
+   whole string rather than a substring of it.
+
+   Asked on each call rather than read once at load: it is reached once
+   per connection, where the cost is nothing, and a value frozen at
+   module load cannot be tested from both sides. */
+export function isWorkerd() {
+    return (typeof navigator === 'object' &&
+        navigator !== null &&
+        navigator.userAgent === 'Cloudflare-Workers');
+}

package/util/stringify-arrayliteral.js

@@ -1,5 +1,6 @@
 import { arrayCalculateDim } from './array-calculatedim.js';
 import { arrayLeaf } from './array-leaf.js';
+import { unspecifiedText } from './unspecified-value.js';
 /**
  * What a number's own text looks like: digits, one optional dot, an
  * optional exponent, an optional leading minus. An element that matches
@@ -66,7 +67,11 @@ export function stringifyArrayLiteral(value, options, encode) {
             const isNumber = typeof x === 'number' || typeof x === 'bigint';
             if (encode)
                 x = encode(x, options || {});
-            const s = '' + x;
+            // With an encoder the element's text is the type's to produce;
+            // without one this is an undeclared array, where a value that
+            // knows how to write itself does, and a plain object goes out as
+            // JSON rather than as `[object Object]`.
+            const s = encode ? '' + x : unspecifiedText(x);
             out += isNumber && BARE_NUMBER.test(s) ? s : escapeArrayItem(s);
         }
         return out + '}';
@@ -241,7 +246,9 @@ export function writeArrayLiteral(io, value, options, encode) {
             // of its spelling - the same rule the string path states: a
             // string's own text is quoted whatever it looks like.
             const isNumber = typeof x === 'number' || typeof x === 'bigint';
-            s = '' + x;
+            // This lane is only entered with no element encoder, so the same
+            // rules the string path applies without one apply here.
+            s = unspecifiedText(x);
             const bare = isNumber && BARE_NUMBER.test(s);
             if (!bare)
                 s =

package/util/unspecified-param.d.ts

@@ -30,6 +30,9 @@
  *   bigint[] = integer[]`, and `numeric[] = double precision[]` the
  *   same. The scalars are left declared because they do have those
  *   operators - `1::int8 = $1` and `1.5::numeric = $1` both resolve.
+ *   That is true of the operators *inside* the numeric family and not
+ *   of the casts out of it, which is what `needsNumericParam()` below
+ *   exists for.
  *
  * A scalar number, a boolean, a Buffer, and an array of anything but
  * numbers keep their declared types: an array of booleans, of Buffers
@@ -64,3 +67,14 @@
  * answer rather than a guess.
  */
 export declare function isUnspecifiedParam(v: any): boolean;
+/**
+ * Whether a number must be declared `numeric` rather than the `float8`
+ * its value suggests.
+ *
+ * True for a finite non-integer, false for everything else - an integer,
+ * a bigint, a non-finite number, and anything that is not a number.
+ *
+ * @param v The value a parameter is about to be declared for.
+ * @returns Whether to declare `numeric` instead of asking `determine()`.
+ */
+export declare function needsNumericParam(v: any): boolean;

package/util/unspecified-param.js

@@ -31,6 +31,9 @@ import { arrayLeaf } from './array-leaf.js';
  *   bigint[] = integer[]`, and `numeric[] = double precision[]` the
  *   same. The scalars are left declared because they do have those
  *   operators - `1::int8 = $1` and `1.5::numeric = $1` both resolve.
+ *   That is true of the operators *inside* the numeric family and not
+ *   of the casts out of it, which is what `needsNumericParam()` below
+ *   exists for.
  *
  * A scalar number, a boolean, a Buffer, and an array of anything but
  * numbers keep their declared types: an array of booleans, of Buffers
@@ -70,3 +73,40 @@ export function isUnspecifiedParam(v) {
         return true;
     return Array.isArray(v) && (typeof x === 'number' || typeof x === 'bigint');
 }
+/**
+ * Whether a number must be declared `numeric` rather than the `float8`
+ * its value suggests.
+ *
+ * True for a finite non-integer, false for everything else - an integer,
+ * a bigint, a non-finite number, and anything that is not a number.
+ *
+ * @param v The value a parameter is about to be declared for.
+ * @returns Whether to declare `numeric` instead of asking `determine()`.
+ */
+/* `determine()` answers by value, so 12 is int4 and 12.34 is float8 -
+   and `int4 -> money` is an assignment cast while `float8 -> money` has
+   no pg_cast row at all. So `select ($1::money)::text` worked with 12
+   and failed 42846 with 12.34: the same SQL, the same column, decided by
+   whether the amount happened to have a fractional part, which for money
+   it usually does. A test written with 12 passed and production failed
+   on 12.34. `numeric -> money` is an assignment cast, which an explicit
+   `::money` accepts, and `numeric -> float8` is implicit, so a float8
+   column is unaffected.
+
+   Measured, inserting into a float8 column over a loopback connection,
+   three interleaved rounds of 3000: 0.197ms a call against float8's
+   0.198, and 51 bytes on the socket against 47. Round-tripping a double
+   through numeric is exact - checked against float8 for 0.1, 5e-324,
+   1.7976931348623157e308, 0.30000000000000004 and pi, among others.
+
+   Non-finite values keep float8 deliberately: `numeric` only grew
+   Infinity in PostgreSQL 14, and NaN would be the only one of the three
+   that worked on 12 and 13.
+
+   This does not close `$1::interval` from a number, which fails the same
+   way - there is no cast to interval from any numeric type, so only an
+   undeclared parameter reaches it. An integer scalar is left declared,
+   and `new BindParam(0, 5)` is the way to say it. */
+export function needsNumericParam(v) {
+    return typeof v === 'number' && Number.isFinite(v) && !Number.isInteger(v);
+}

package/util/unspecified-value.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Follows a value's `toPostgres()` until it reaches one that has none.
+ *
+ * `toPostgres()` is `pg`'s extension point for a type that knows how to
+ * write itself: a library with its own geometry, money or domain class
+ * implements it, and the value goes out as that class says rather than
+ * as whatever `String()` makes of it. The result is followed rather than
+ * returned, because what it hands back may itself be a `Date`, an array,
+ * a `Buffer` or another such value.
+ *
+ * @param v The value a parameter is about to be written from.
+ * @returns The value to write, which is `v` itself unless it had one.
+ * @throws TypeError if the values form a cycle.
+ */
+export declare function resolveToPostgres(v: any): any;
+/**
+ * The text an undeclared parameter - or one element of an undeclared
+ * array - goes out as.
+ *
+ * Follows `toPostgres()` first, then writes a plain object as JSON and
+ * anything else as its own text.
+ *
+ * @param v The value to render.
+ * @returns What to put on the wire, before any array quoting.
+ */
+export declare function unspecifiedText(v: any): string;