@m2k-5f/pgtx 2.7.1 → 2.7.3

package/README.md

@@ -3,9 +3,7 @@
 [![Tests](https://github.com/M2K-5F/pgtx/actions/workflows/tests.yaml/badge.svg)](https://github.com/M2K-5F/pgtx/actions/workflows/tests.yaml)
 [![npm version](https://img.shields.io/npm/v/@m2k-5f/pgtx.svg)](https://www.npmjs.com/package/@m2k-5f/pgtx)
 
-A PostgreSQL driver for Node.js that pipelines everything by default, caches prepared statements without asking, and doesn't ship a single dependency.
-
-It exists because `pg` leaves throughput on the table and `postgres.js`, while fast, still isn't fast enough once you actually saturate a connection pool. Pgtx is built around one idea: batch what can be batched, write to the socket once, and get out of the way.
+A PostgreSQL driver for Node.js with an API that doesn't require a manual to use. Built for regular applications, not for people who need four different flavors of the same stream implementation or a config object with forty optional fields you'll never touch.
 
 ```bash
 npm install @m2k-5f/pgtx
@@ -25,8 +23,9 @@ const pool = new Pool({
 
 const [user] = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
 
+// returns rows → query, doesn't → execute
 await pool.execute`
-  INSERT INTO users ${sql.insert([{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }])}
+  INSERT INTO users ${sql.insert<User>([{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }])}
 `
 
 await pool.begin(async tx => {
@@ -43,18 +42,34 @@ Benchmarks run on GitHub Actions (Ubuntu, 2 vCPUs), reproducible, sources in thi
  
 **HTTP throughput against `postgres.js` and Bun's own native `Bun.sql` driver, on Bun:**
  
-| Connections | Pgtx | Postgres.js | Bun.sql | vs Postgres.js | vs Bun.sql |
-|---:|---:|---:|---:|---:|---:|
-| 50 | **27,885 req/s** | 8,967 req/s | 10,170 req/s | 3.11× | 2.74× |
-| 200 | **31,975 req/s** | 9,861 req/s | 11,725 req/s | 3.24× | 2.73× |
-| 500 | **31,245 req/s** | 8,289 req/s | 11,005 req/s | 3.77× | 2.84× |
+| Connections | Pgtx | Postgres.js | Bun.sql |
+|---:|---:|---:|---:|
+| 50 | **21,093 req/s** | 8,967 req/s | 10,170 req/s |
+| 200 | **22,731 req/s** | 9,861 req/s | 11,725 req/s |
+| 500 | **22,673 req/s** | 8,289 req/s | 11,005 req/s |
  
-Bun.sql is Bun's own built-in driver, written in native code and generally treated as the speed baseline in that ecosystem. Pgtx stays 2.7-2.8× ahead of it at every concurrency level tested — the gap doesn't come from JS-vs-native, it comes from the protocol.
+Bun.sql is Bun's own built-in driver, written in native code and generally treated as the speed baseline in that ecosystem. Pgtx stays ahead of it at every concurrency level tested — the gap doesn't come from JS-vs-native, it comes from the protocol implementation.
  
 **How:** everything you fire concurrently against the same connection gets folded into one pipelined write — Parse/Bind/Execute for every query in the batch goes out in a single `socket.write()`, and results get demuxed as they come back, in order, without buffering rows you haven't asked for yet. Prepared statements are cached and deduplicated automatically, row descriptions are cached alongside them, and the binary protocol skips text (de)serialization where it can. None of this requires you to change how you write queries.
 
 ## The parts worth knowing about
 
+
+### Every query is its own commit boundary
+
+Fire off several queries in the same batch and one of them fails — the others aren't affected. Each query gets its own Sync, which means its own implicit transaction: an error in query B doesn't undo query A, even if A already returned and B is still in flight on the same pipelined write.
+
+```typescript
+const [a, b] = await Promise.allSettled([
+  pool.execute`UPDATE accounts SET balance = balance + 100 WHERE id = ${1}`,
+  pool.execute`INSERT INTO accounts (id) VALUES (${1})` // duplicate key, fails
+])
+// a: fulfilled, the balance update is committed regardless of b's outcome
+```
+
+This isolation is per-statement, not free-standing atomicity across statements — if you need several queries to succeed or fail together, that's what `begin()` and `savepoint()` are for. Outside a transaction, every query stands on its own.
+
+
 ### Errors you can pattern-match on
 
 Every call returns a `Future<T[], PostgresError>` from [fluent-future](https://www.npmjs.com/package/fluent-future) instead of a bare `Promise`. `await` still works exactly like you'd expect — but you also get typed errors and a way to handle them without a `try/catch` pyramid:
@@ -66,9 +81,24 @@ const users = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
   .tapErr(err => logger.error(err))
 ```
 
+
+### Transactions and savepoints
+
+```typescript
+await pool.begin(async tx => {
+  await tx.execute`INSERT INTO orders (user_id) VALUES (${userId})`
+
+  await tx.savepoint('reserve_stock', async stx => {
+    await stx.execute`UPDATE stock SET count = count - 1 WHERE product_id = ${productId}`
+    if (outOfStock) throw new Error('out of stock') // only the savepoint rolls back
+  }).tapErr(console.log)
+})
+```
+
+
 ### Pipelining is automatic, not opt-in
 
-`Bind`/`.bind` from fluent-future group independent queries into the same pipeline batch for you:
+`Bind`/`.bind` from [fluent-future](https://www.npmjs.com/package/fluent-future) group independent queries into the same pipeline batch for you:
 
 ```typescript
 // 5 queries, 2 round-trips
@@ -94,29 +124,16 @@ for await (const log of pool.stream<Log>`SELECT * FROM application_logs WHERE le
 }
 ```
 
+
 It's a real Web Streams object, so it drops straight into an HTTP response body:
 
 ```typescript
-export default {
-  async fetch(req) {
-    const stream = pool.stream`SELECT id, email FROM giant_user_table`
-    return new Response(stream, { headers: { "Content-Type": "application/json" } })
-  }
+fetch(req) {
+  const stream = pool.stream`SELECT id, email FROM giant_user_table`
+  return new Response(stream, { headers: { "Content-Type": "application/json" } })
 }
 ```
 
-### Transactions and savepoints
-
-```typescript
-await pool.begin(async tx => {
-  await tx.execute`INSERT INTO orders (user_id) VALUES (${userId})`
-
-  await tx.savepoint('reserve_stock', async stx => {
-    await stx.execute`UPDATE stock SET count = count - 1 WHERE product_id = ${productId}`
-    if (outOfStock) throw new Error('out of stock') // only the savepoint rolls back
-  }).tapErr(console.log)
-})
-```
 
 ### LISTEN / NOTIFY without babysitting a connection
 
@@ -199,10 +216,10 @@ interface ConnectionPartialConfig {
   host: string
   port: number
   database: string
-  logLevel?: 'error' | 'notice' | 'query'   // default 'error'
+  logLevel?: 'error' | 'notice' | 'query' | "none"   // default 'error'
   int8toBigint?: boolean                     // default false
-  queryTimeout?: number                      // default 30000
-  syncShedule?: 'beforeMicrotask' | 'afterMicrotask' | 'Immediate'  // default 'afterMicrotask'
+  queryTimeout?: number                      // default 30000 (ms)
+  syncShedule?: 'beforeMicrotask' | 'afterMicrotask' | 'Immediate'  // default 'Immediate'
   ssl?: 'disable' | 'prefer' | 'require' // defaut 'prefer' 
   caPath?: string // forces `ssl` to 'require' if provided
 }

package/dist/batch.d.ts

@@ -7,9 +7,12 @@ export declare class Batch {
     constructor(buffer: ConnectionRequestWriter);
     registerParse(query: PostgresQuery): void;
     registerQuery(query: PostgresQuery): void;
+    get hasMore(): boolean;
     end(): ConnectionRequestWriter;
     get current(): PostgresQuery;
     next(): void;
-    reject(cause: PostgresError): number;
+    get shift(): PostgresQuery;
+    error(cause: PostgresError): void;
+    get residual(): PostgresQuery[];
 }
 //# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,qBAAa,KAAK;IACd,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,OAAO,CAAyB;gBAE5B,MAAM,EAAE,uBAAuB;IAM3C,aAAa,CAAC,KAAK,EAAE,aAAa;IAOlC,aAAa,CAAC,KAAK,EAAE,aAAa;IAQlC,GAAG;IAIH,IAAI,OAAO,kBAEV;IAED,IAAI;IAIJ,MAAM,CAAC,KAAK,EAAE,aAAa;CAS9B"}
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,qBAAa,KAAK;IACd,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,OAAO,CAAyB;gBAE5B,MAAM,EAAE,uBAAuB;IAM3C,aAAa,CAAC,KAAK,EAAE,aAAa;IAOlC,aAAa,CAAC,KAAK,EAAE,aAAa;IASlC,IAAI,OAAO,YAEV;IAED,GAAG;IAIH,IAAI,OAAO,kBAEV;IAED,IAAI;IAIJ,IAAI,KAAK,kBAER;IAED,KAAK,CAAC,KAAK,EAAE,aAAa;IAM1B,IAAI,QAAQ,oBAEX;CACJ"}

package/dist/batch.js

@@ -13,10 +13,14 @@ export class Batch {
         this._queryQueue.push(query);
         this._buffer
             .writeBind("", query.statement, query.args)
-            .writeExecute("");
+            .writeExecute("")
+            .writeSync();
+    }
+    get hasMore() {
+        return this._queryQueue.hasMore;
     }
     end() {
-        return this._buffer.writeSync();
+        return this._buffer;
     }
     get current() {
         return this._queryQueue.current;
@@ -24,12 +28,15 @@ export class Batch {
     next() {
         this._queryQueue.next();
     }
-    reject(cause) {
-        let counter = 0;
+    get shift() {
+        return this._queryQueue.shift;
+    }
+    error(cause) {
         while (this._queryQueue.hasMore) {
-            counter++;
-            this._queryQueue.shift.reject(cause);
+            this._queryQueue.shift.error(cause);
         }
-        return counter;
+    }
+    get residual() {
+        return this._queryQueue.residual;
     }
 }

package/dist/clauses/fragment.clause.js

@@ -1,5 +1,5 @@
 import { Clause, } from "./abstract.clause";
-import { compileSqlTemplate } from "../utils/template-compiler";
+import { compileSqlTemplate } from "../utils";
 export class FragmentClause extends Clause {
     constructor(templates, args) {
         super();

package/dist/connection.d.ts

@@ -14,26 +14,28 @@ import { PostgresError } from "./error";
  */
 export declare class Connection {
     private readonly config;
-    private _activeBatch;
+    private _writer;
+    private _sheduled;
+    private _queue;
     private _closing;
     private _closed;
     private _reconnecting;
-    private _cachedBuffer;
     private _socket;
-    private _batchQueue;
     private _parsed;
     private _parsing;
     private _listeningCallbacks;
     private _stmtCounter;
     private _nextStatement;
+    private _registerShedule;
+    private _shedule;
+    private _parseQuery;
+    private _registerQuery;
     private constructor();
     /**
      * Opens a new connection and authenticates.
      * @throws {PostgresError} if authentication fails or the connection can't be established
      */
     static new(config: ConnectionPartialConfig): Future<Connection, PostgresError>;
-    private _registerBatch;
-    private _sync;
     /**
      * Runs a query, binding template values as `$1, $2, ...`.
      * Parameterized queries are cached as prepared statements.
@@ -51,6 +53,15 @@ export declare class Connection {
      */
     execute(templates: TemplateStringsArray, ...params: any[]): Future<void, PostgresError>;
     private _performExecute;
+    /**
+     * Streams query results as a `ReadableStream`, without buffering rows in memory.
+     * Ideal for large result sets or piping straight into an HTTP response.
+     *
+     * @example
+     * for await (const row of conn.stream<User>`SELECT * FROM orders`) { ... }
+     */
+    stream<T extends Row>(templates: TemplateStringsArray, ...params: any[]): ReadableStream<T>;
+    private _performStream;
     /**
      * Runs `txCallback` inside `BEGIN`/`COMMIT`, rolling back on error.
      *
@@ -66,21 +77,11 @@ export declare class Connection {
     listen(channelName: string, callback: (payload: string) => void): Future<void, PostgresError>;
     /** Unsubscribes `callback`, issuing `UNLISTEN` once no callbacks remain. */
     unlisten(channelName: string, callback: (payload: string) => void): Future<void, PostgresError>;
-    /**
-     * Streams query results as a `ReadableStream`, without buffering rows in memory.
-     * Ideal for large result sets or piping straight into an HTTP response.
-     *
-     * @example
-     * for await (const row of conn.stream<User>`SELECT * FROM orders`) { ... }
-     */
-    stream<T extends Row>(templates: TemplateStringsArray, ...params: any[]): ReadableStream<T>;
-    private _performStream;
     private _reconnect;
     private _performReconnect;
     private _restoreSubscriptions;
-    private _getCurrentQuery;
+    private get _currentQuery();
     private _handlePacket;
-    private get _hasQueries();
     /** Whether the connection is alive and usable. */
     get isOpened(): boolean;
     /** Whether the connection is closed or closing. */

package/dist/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAKA,OAAO,EAAiC,uBAAuB,EAAmC,GAAG,EAAiB,MAAM,SAAS,CAAA;AACrI,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAK3C,OAAO,EAAS,MAAM,EAAM,MAAM,eAAe,CAAA;AACjD,OAAO,EAAkD,aAAa,EAAE,MAAM,SAAS,CAAA;AAcvF;;;;;;;;;GASG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAsD;IACtE,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,aAAa,CAA2C;IAChE,OAAO,CAAC,aAAa,CAAgC;IAErD,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,WAAW,CAA4B;IAE/C,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,QAAQ,CAAsC;IAEtD,OAAO,CAAC,mBAAmB,CAAyD;IACpF,OAAO,CAAC,YAAY,CAAI;IAGxB,OAAO,CAAC,cAAc;IAKtB,OAAO;IAYP;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,uBAAuB;IAkB1C,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,KAAK;IASb;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,SAAS,GAAG,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IAStE,OAAO,CAAC,aAAa;IA4CrB;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IASzD,OAAO,CAAC,eAAe;IAsCvB;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC;IAoB7D,2EAA2E;IAC3E,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW;IAOhD,sFAAsF;IACtF,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;IAe/D,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC;IAoB/F;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,SAAS,GAAG,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IAyBvE,OAAO,CAAC,cAAc;IA2CtB,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,iBAAiB;IA6BzB,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,aAAa;IAoIrB,OAAO,KAAK,WAAW,GAEtB;IAGD,kDAAkD;IAClD,IAAI,QAAQ,YAEX;IAGD,mDAAmD;IACnD,IAAI,QAAQ,YAEX;IAGD;;OAEG;IACH,KAAK;CAwBR"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiC,uBAAuB,EAAuC,GAAG,EAAiB,MAAM,SAAS,CAAA;AACzI,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAK3C,OAAO,EAAS,MAAM,EAAM,MAAM,eAAe,CAAA;AACjD,OAAO,EAAkD,aAAa,EAAE,MAAM,SAAS,CAAA;AAevF;;;;;;;;;GASG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,MAAM,CAA6B;IAE3C,OAAO,CAAC,QAAQ,CAAsD;IACtE,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,aAAa,CAA2C;IAEhE,OAAO,CAAC,OAAO,CAAiB;IAEhC,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,QAAQ,CAAuC;IAEvD,OAAO,CAAC,mBAAmB,CAAyD;IACpF,OAAO,CAAC,YAAY,CAAI;IAExB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,cAAc;IAYtB,OAAO;IAYP;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,uBAAuB;IAkB1C;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,SAAS,GAAG,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IAatE,OAAO,CAAC,aAAa;IA4CrB;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IAazD,OAAO,CAAC,eAAe;IA2CvB;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,SAAS,GAAG,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IA2BvE,OAAO,CAAC,cAAc;IA8CtB;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC;IAoB7D,2EAA2E;IAC3E,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAW;IAOhD,sFAAsF;IACtF,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;IAe/D,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC;IAoB/F,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,iBAAiB;IA6BzB,OAAO,CAAC,qBAAqB;IAW7B,OAAO,KAAK,aAAa,GAExB;IAGD,OAAO,CAAC,aAAa;IAgIrB,kDAAkD;IAClD,IAAI,QAAQ,YAEX;IAGD,mDAAmD;IACnD,IAAI,QAAQ,YAEX;IAGD;;OAEG;IACH,KAAK;CAwBR"}