postgrejs 3.14.0 → 3.14.2

package/README.md

@@ -62,35 +62,40 @@ PostgreJS is a driver, not a framework, so what you build on top of it stays you
       <a href="https://www.sqbjs.org"><img src="https://www.postgrejs.com/img/sqb-logo.svg" alt="SQB" height="60"></a><br><br>
       <b><a href="https://www.sqbjs.org">SQB</a></b><br>
       <a href="https://www.npmjs.com/package/@sqb/postgres"><code>@sqb/postgres</code></a><br>
-      <sub>first-party adapter</sub>
+      <sub>built-in adapter</sub>
+    </td>
+    <td align="center" width="230" valign="top">
+      <a href="https://joist-orm.io"><img src="https://www.postgrejs.com/img/joist-logo.svg" alt="Joist" height="60"></a><br><br>
+      <b><a href="https://joist-orm.io">Joist</a></b><br>
+      <a href="https://www.npmjs.com/package/joist-orm"><code>joist-orm/postgrejs</code></a><br>
+      <sub>built-in driver</sub>
     </td>
     <td align="center" width="230" valign="top">
       <a href="https://kysely.dev"><img src="https://www.postgrejs.com/img/kysely-logo.svg" alt="Kysely" height="60"></a><br><br>
       <b><a href="https://kysely.dev">Kysely</a></b><br>
       <a href="https://github.com/panates/postgrejs-kysely"><code>kysely-postgrejs</code></a><br>
-      <sub>dialect</sub>
+      <sub>third-party dialect</sub>
     </td>
+  </tr>
+  <tr>
     <td align="center" width="230" valign="top">
       <a href="https://orm.drizzle.team"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.postgrejs.com/img/drizzle-logo-dark.svg"><img src="https://www.postgrejs.com/img/drizzle-logo-light.svg" alt="Drizzle ORM" height="34"></picture></a><br><br>
       <b><a href="https://orm.drizzle.team">Drizzle ORM</a></b><br>
       <a href="https://github.com/panates/postgrejs-drizzle"><code>drizzle-postgrejs</code></a><br>
-      <sub>driver</sub>
+      <sub>third-party driver</sub>
     </td>
-  </tr>
-  <tr>
     <td align="center" width="230" valign="top">
       <a href="https://typeorm.io"><img src="https://www.postgrejs.com/img/typeorm-icon.png" alt="TypeORM" height="60"></a><br><br>
       <b><a href="https://typeorm.io">TypeORM</a></b><br>
       <a href="https://github.com/panates/postgrejs-typeorm"><code>typeorm-postgrejs</code></a><br>
-      <sub>driver</sub>
+      <sub>third-party driver</sub>
     </td>
     <td align="center" width="230" valign="top">
       <a href="https://www.prisma.io"><img src="https://www.postgrejs.com/img/prisma-icon.svg" alt="Prisma" height="60"></a><br><br>
       <b><a href="https://www.prisma.io">Prisma</a></b><br>
       <a href="https://github.com/panates/postgrejs-prisma"><code>prisma-postgrejs</code></a><br>
-      <sub>driver adapter</sub>
+      <sub>third-party adapter</sub>
     </td>
-    <td width="230"></td>
   </tr>
 </table>
 
@@ -98,6 +103,9 @@ Each adapter hands the compiled SQL straight to this client, with no `pg` left a
 compared query by query against the driver it replaces - and, where the project ships a suite of its own, run
 against that too. So adopting one is a change to how the connection is created and nothing else.
 
+Joist's is the Joist project's own, and uses `RowDecoder` to leave each cell undecoded until an entity reads it.
+Codegen and migrations there still run on `pg`, though the runtime does not.
+
 ### 🌍 Runs Where You Run
 
 <!-- Same card shape as the adapters above, for the same reason: GitHub strips CSS, and a table
@@ -141,7 +149,7 @@ Upgrading from 3.5? See [doc/MIGRATION-v3.5-to-v3.6.md](doc/MIGRATION-v3.5-to-v3
 
 - **Language:** Pure JavaScript, with no native/binary dependencies to compile or ship.
 - **Strictly typed:** Written entirely in TypeScript, with types shipped alongside the package.
-- **Modern module format:** Ships as ESM; Node 20.19+/22.12+ can `require()` it from CommonJS code as well.
+- **Modern module format:** Ships as ESM; Node 22.12+ can `require()` it from CommonJS code as well.
 - **Promise-based API:** Every asynchronous operation returns a promise - no callbacks to wrangle.
 - **Rigorously tested:** A test suite covering the wire protocol, every data type, and connection-handling edge case,
   run on every push against PostgreSQL 12 through 18.
@@ -324,10 +332,10 @@ PostgreJS implements the full PostgreSQL wire protocol from scratch, with no dep
 [`doc/BENCHMARKS.md`](doc/BENCHMARKS.md) compares it against `pg` (node-postgres) and `postgres` (postgres.js)
 across connection setup, simple/prepared queries, mixed-type decoding, bulk fetches, cursor streaming and pool
 concurrency, each library run through its own idiomatic fast path. The numbers there are reproducible on your own
-machine via `npm run bench` against the repo's own
+machine via `pnpm run bench` against the repo's own
 `docker/docker-compose.yml` Postgres instance; see [`benchmark/README.md`](./benchmark/README.md) for details.
 
-The same suite runs under Bun via `npm run bench:bun`, where it also measures Bun's own built-in `Bun.sql` client as
+The same suite runs under Bun via `pnpm run bench:bun`, where it also measures Bun's own built-in `Bun.sql` client as
 a fourth library. Those results live in [`doc/BENCHMARKS-bun.md`](doc/BENCHMARKS-bun.md) and are deliberately kept
 in a separate report rather than merged into the Node one: GC instrumentation, cursor streaming and binary-format
 control all differ enough between the two runtimes that a single table would conflate a library difference with a
@@ -344,7 +352,7 @@ you open an issue please provide version of NodeJS and PostgreSQL server.
 
 ## Runtime Compatibility
 
-- Node.js >= 20.x
+- Node.js >= 22.x
 - Bun - the same test suite runs under Bun in CI against PostgreSQL 18 on every push, so Bun is a supported target
   rather than an untested coincidence. (Coverage is collected on the Node matrix only: `c8` instruments V8's
   coverage APIs, which JavaScriptCore doesn't have.)

package/connection/intl-connection.d.ts

@@ -64,6 +64,12 @@ export declare class IntlConnection extends SafeEventEmitter {
      * never close again.
      */
     private _preparing;
+    /**
+     * Resolves when the statement submitted before this one has written its
+     * own bytes - see _holdWireOrder(). Undefined whenever nothing is on its
+     * way to the wire, which is every statement that writes without waiting.
+     */
+    private _wireOrder?;
     /** SQL seen once but not yet prepared - see PREPARE_AFTER_USES. */
     private _preparedCandidates;
     private _preparedCounter;
@@ -313,6 +319,18 @@ export declare class IntlConnection extends SafeEventEmitter {
     protected _queryCached(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint: Maybe<string>, 
     /** Whether the CALL asked for text columns, not the connection. */
     callWantsFields: boolean): Promise<QueryResult>;
+    /**
+     * Keeps this statement's place in the wire order while it waits for
+     * something - today, the Parse round trip that names it.
+     *
+     * @returns `after`, the place held by the statement submitted before this
+     * one, to wait on before writing; and `wrote`, to call the moment this
+     * statement's own bytes are on the wire.
+     */
+    protected _holdWireOrder(): {
+        after?: Promise<void>;
+        wrote: () => void;
+    };
     /**
      * Gives this SQL a name and caches it, once, however many callers are
      * waiting. A Parse that fails caches nothing and reports itself; the

package/connection/intl-connection.js

@@ -195,6 +195,12 @@ export class IntlConnection extends SafeEventEmitter {
      * never close again.
      */
     _preparing = new Map();
+    /**
+     * Resolves when the statement submitted before this one has written its
+     * own bytes - see _holdWireOrder(). Undefined whenever nothing is on its
+     * way to the wire, which is every statement that writes without waiting.
+     */
+    _wireOrder;
     /** SQL seen once but not yet prepared - see PREPARE_AFTER_USES. */
     _preparedCandidates = new Map();
     _preparedCounter = 0;
@@ -975,8 +981,11 @@ export class IntlConnection extends SafeEventEmitter {
     /** Whether the CALL asked for text columns, not the connection. */
     callWantsFields) {
         const enabled = options.prepare ?? this.config.prepare ?? true;
-        if (!enabled)
+        if (!enabled) {
+            if (this._wireOrder)
+                await this._wireOrder;
             return this.queryOnce(sql, paramTypes, params, options, savepoint);
+        }
         const key = preparedCacheKey(sql, paramTypes);
         const cached = this._preparedCache.get(key);
         if (cached) {
@@ -984,6 +993,8 @@ export class IntlConnection extends SafeEventEmitter {
             this._preparedCache.delete(key);
             this._preparedCache.set(key, cached);
             try {
+                if (this._wireOrder)
+                    await this._wireOrder;
                 return await this.executeReused(cached.name, cached.fields, resolvedBindTypes(paramTypes, params, cached.resolvedParamTypes), params, options, savepoint);
             }
             catch (e) {
@@ -1024,8 +1035,11 @@ export class IntlConnection extends SafeEventEmitter {
         // on a statement's first run instead, and per-column codes from its
         // second, which is where the name arrives anyway.
         const needsFields = callWantsFields && options.columnFormat !== DataFormat.text;
-        if (!needsFields && !this._earnsAName(key))
+        if (!needsFields && !this._earnsAName(key)) {
+            if (this._wireOrder)
+                await this._wireOrder;
             return this.queryOnce(sql, paramTypes, params, options, savepoint);
+        }
         let preparing = this._preparing.get(key);
         if (!preparing) {
             // Registered before the first await inside, so everything that
@@ -1038,10 +1052,71 @@ export class IntlConnection extends SafeEventEmitter {
             // Someone else is already naming it. Waiting would cost a round
             // trip the one-shot path does not - the name is for the calls
             // after this burst, not for this one.
+            if (this._wireOrder)
+                await this._wireOrder;
             return this.queryOnce(sql, paramTypes, params, options, savepoint);
         }
-        const entry = await preparing;
-        return this.executeReused(entry.name, entry.fields, paramTypes, params, options, savepoint);
+        const place = this._holdWireOrder();
+        let running;
+        try {
+            const entry = await preparing;
+            if (place.after)
+                await place.after;
+            /* Called, not awaited: executeReused() runs as far as the socket
+               write before its first await, so by the time it hands back a
+               promise the bytes are away and the next statement may follow
+               them. Awaiting it here instead would hold the line until this
+               statement had its answer, which is pipelining switched off. */
+            running = this.executeReused(entry.name, entry.fields, paramTypes, params, options, savepoint);
+        }
+        finally {
+            // Also on the way out of a Parse that failed: this statement will
+            // never write, and whatever queued behind it must not wait forever.
+            place.wrote();
+        }
+        return running;
+    }
+    /**
+     * Keeps this statement's place in the wire order while it waits for
+     * something - today, the Parse round trip that names it.
+     *
+     * @returns `after`, the place held by the statement submitted before this
+     * one, to wait on before writing; and `wrote`, to call the moment this
+     * statement's own bytes are on the wire.
+     */
+    /* PostgreSQL executes what reaches it in the order it reaches it, and
+       cannot know what order the query() calls were made in. A statement
+       that has to await a Parse before it can Bind therefore lets every
+       later statement overtake it - invisibly, because the overtaking only
+       happens when one statement is cached and the other is not, which is a
+       property of the connection's history rather than of the code. Two
+       updates to one row then land in the opposite order on a connection
+       that had been running them correctly all along.
+    
+       Holding a place rather than the wire: the Parse still overlaps with
+       everything else, which is the point of pipelining. Only the Bind is
+       made to queue, and only behind calls that really were submitted
+       first.
+    
+       Nothing pending leaves `_wireOrder` undefined, so a statement that
+       writes without waiting - a cache hit, the common case - reads one
+       field and writes, paying no promise and no microtask for the
+       ordering. */
+    _holdWireOrder() {
+        const after = this._wireOrder;
+        let resolve;
+        const mine = new Promise(r => (resolve = r));
+        this._wireOrder = mine;
+        return {
+            after,
+            wrote: () => {
+                // Only if nobody queued behind this one in the meantime - their
+                // place is the one that must be waited on now.
+                if (this._wireOrder === mine)
+                    this._wireOrder = undefined;
+                resolve();
+            },
+        };
     }
     /**
      * Gives this SQL a name and caches it, once, however many callers are

package/constants.d.ts

@@ -1,6 +1,6 @@
 import { Protocol } from './protocol/protocol.js';
 import DataFormat = Protocol.DataFormat;
-export declare const version = "3.14.0";
+export declare const version = "3.14.2";
 export { DataFormat };
 /**
  * What columns come back in unless something asks otherwise.

package/constants.js

@@ -2,7 +2,7 @@ import { Protocol } from './protocol/protocol.js';
 var DataFormat = Protocol.DataFormat;
 // @ts-ignore
 Symbol.asyncDispose ??= Symbol('Symbol.asyncDispose');
-export const version = '3.14.0';
+export const version = '3.14.2';
 export { DataFormat };
 /**
  * What columns come back in unless something asks otherwise.

package/data-types/bytea-type.d.ts

@@ -1,5 +1,12 @@
 import type { DataType } from '../interfaces/data-type.js';
-/** `bytea`, as a `Buffer`. The binary format is the bytes themselves; the text one is `\\x`-prefixed hex, at two characters a byte. */
+/**
+ * `bytea`. A value read back is a `Buffer`; a value sent may be any
+ * ArrayBuffer view - a `Buffer`, a `Uint8Array` off `fetch` or `subarray`,
+ * a `DataView` - and only the bytes that view covers are sent.
+ *
+ * The binary format is the bytes themselves; the text one is `\\x`-prefixed
+ * hex, at two characters a byte.
+ */
 export declare const ByteaType: DataType;
 /** The `_bytea` array of {@link ByteaType}. */
 export declare const ArrayByteaType: DataType;

package/data-types/bytea-type.js

@@ -1,16 +1,42 @@
 import { DataTypeOIDs } from '../constants.js';
 import { parseBytea, parseByteaBuffer } from '../util/parse-bytea.js';
-/** `bytea`, as a `Buffer`. The binary format is the bytes themselves; the text one is `\\x`-prefixed hex, at two characters a byte. */
+/**
+ * Reads any ArrayBuffer view as a `Buffer` over exactly the bytes it covers.
+ *
+ * @param v The view to read.
+ * @returns It unchanged when it is already a `Buffer`, or a window onto the
+ * same memory - never a copy.
+ */
+/* `byteOffset`/`byteLength` are the whole point: a `subarray()` of a larger
+   buffer describes a window, and `Buffer.from(view.buffer)` would send
+   everything on both sides of it. */
+function asBuffer(v) {
+    return Buffer.isBuffer(v)
+        ? v
+        : Buffer.from(v.buffer, v.byteOffset, v.byteLength);
+}
+/**
+ * `bytea`. A value read back is a `Buffer`; a value sent may be any
+ * ArrayBuffer view - a `Buffer`, a `Uint8Array` off `fetch` or `subarray`,
+ * a `DataView` - and only the bytes that view covers are sent.
+ *
+ * The binary format is the bytes themselves; the text one is `\\x`-prefixed
+ * hex, at two characters a byte.
+ */
 export const ByteaType = {
     name: 'bytea',
     oid: DataTypeOIDs.bytea,
     jsType: 'Buffer',
     // The hex form PostgreSQL has emitted by default since 9.0.
     encodeText(v) {
-        return '\\x' + v.toString('hex');
+        return '\\x' + asBuffer(v).toString('hex');
     },
+    /* Through `asBuffer` rather than straight to `writeBytes`, which reaches
+       for `.copy()` - a `Buffer` method that a plain `Uint8Array` does not
+       have, and the `buffer.copy is not a function` an explicit
+       `BindParam(17, bytes)` used to fail with. */
     encodeBinary(buf, v) {
-        buf.writeBytes(v);
+        buf.writeBytes(asBuffer(v));
     },
     decodeBinary(v, offset = 0, len) {
         // A view, not a copy - the value handed back is the caller's own
@@ -20,7 +46,7 @@ export const ByteaType = {
     decodeText: parseBytea,
     decodeTextBuffer: parseByteaBuffer,
     isType(v) {
-        return v instanceof Buffer;
+        return ArrayBuffer.isView(v);
     },
 };
 /** The `_bytea` array of {@link ByteaType}. */

package/interfaces/query-options.d.ts

@@ -37,9 +37,14 @@ export interface QueryOptions extends DataMappingOptions {
      *
      * `false` asks for the wire to itself: the statement waits until
      * nothing else is running on the connection, and nothing else starts
-     * until it finishes, whichever mode those asked for. Nothing orders
-     * two pipelined statements against each other, so this is how a
-     * statement that depends on what another one left behind says so.
+     * until it finishes, whichever mode those asked for. It is not how a
+     * statement says it depends on an earlier one: pipelined statements on
+     * one connection execute in the order they were submitted. What this
+     * is for is a statement that needs the connection to itself for longer
+     * than the wire - session state another caller would see, or a result
+     * the caller has to read before it can decide what to send next.
+     * Statements on different pooled connections have no order between
+     * them at all.
      *
      * Some statements never share a *pooled* connection however this is
      * set, because they need one to themselves for longer than the call:

package/interfaces/script-execute-options.d.ts

@@ -32,9 +32,14 @@ export interface ScriptExecuteOptions extends DataMappingOptions {
      *
      * `false` asks for the wire to itself: the statement waits until
      * nothing else is running on the connection, and nothing else starts
-     * until it finishes, whichever mode those asked for. Nothing orders
-     * two pipelined statements against each other, so this is how a
-     * statement that depends on what another one left behind says so.
+     * until it finishes, whichever mode those asked for. It is not how a
+     * statement says it depends on an earlier one: pipelined statements on
+     * one connection execute in the order they were submitted. What this
+     * is for is a statement that needs the connection to itself for longer
+     * than the wire - session state another caller would see, or a result
+     * the caller has to read before it can decide what to send next.
+     * Statements on different pooled connections have no order between
+     * them at all.
      *
      * Some statements never share a *pooled* connection however this is
      * set, because they need one to themselves for longer than the call:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.14.0",
+  "version": "3.14.2",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {
@@ -12,7 +12,7 @@
     "power-tasks": "^1.14.2",
     "putil-promisify": "^1.10.1",
     "putil-varhelpers": "^1.7.0",
-    "tslib": "^2.8.1"
+    "tslib": "^2.9.1"
   },
   "type": "module",
   "module": "./index.js",
@@ -25,7 +25,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=20.0"
+    "node": ">=22.0"
   },
   "homepage": "https://www.postgrejs.com/",
   "contributors": [
@@ -36,7 +36,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/panates/postgrejs.git"
+    "url": "git+https://github.com/panates/postgrejs.git"
   },
   "keywords": [
     "postgresql",
@@ -65,4 +65,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}