@m2k-5f/pgtx 2.7.2 → 2.8.0

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,32 +42,74 @@ 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.
+**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. None of this requires you to change how you write queries.
+
 
 ## The parts worth knowing about
 
-### 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:
+### Error handling
+
+Every query returns a `Future<T[], PostgresError>` instead of a bare `Promise`. `await` works as usual, while `Future` also provides typed error handling and recovery without a `try/catch` pyramid.
+
+Queries in the same pipeline are isolated from each other. Each query gets its own `Sync`, so an error in one query does not affect other queries that were sent in the same batch.
 
 ```typescript
-const users = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
-  .recoverIf(err => err.code === '42P01', [])  // undefined_table → []
-  .recoverIf(err => err.code === '23505', [])  // unique_violation → []
+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
+// b: rejected — the duplicate key error only affects this query
+```
+
+Errors can be matched and recovered directly on the `Future`:
+
+```typescript
+const users = await pool.query<User>`
+  SELECT * FROM users WHERE id = ${1}
+`
+  .recoverIf(err => err.code === '42P01', []) // undefined_table → []
+  .recoverIf(err => err.code === '23505', []) // unique_violation → []
   .tapErr(err => logger.error(err))
 ```
 
+This isolation is per statement, not atomicity across multiple statements. If several queries must succeed or fail together, use `begin()` and `savepoint()`.
+
+
+### PostgreSQL Type Support
+
+The driver provides **100% support for PostgreSQL data types using the full binary protocol**. All supported types are encoded and decoded directly in PostgreSQL's binary wire format, without falling back to text-based parsing.
+
+For a complete list of supported PostgreSQL types, their JavaScript input/output types, and string formats, see the [PostgreSQL Data Types](./DATATYPES.md) reference.
+
+
+### 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 +135,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 +227,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 _executingCounter;
     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 _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;IAC3C,OAAO,CAAC,iBAAiB,CAAI;IAE7B,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,CAA8D;IAE9E,OAAO,CAAC,mBAAmB,CAAyD;IACpF,OAAO,CAAC,YAAY,CAAI;IAExB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,cAAc;IA6BtB,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;IA+DrB;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IAazD,OAAO,CAAC,eAAe;IA+DvB;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,SAAS,GAAG,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE;IA2BvE,OAAO,CAAC,cAAc;IAkEtB;;;;;;;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;IA8BzB,OAAO,CAAC,qBAAqB;IAW7B,OAAO,KAAK,aAAa,GAExB;IAGD,OAAO,CAAC,aAAa;IA6HrB,kDAAkD;IAClD,IAAI,QAAQ,YAEX;IAGD,mDAAmD;IACnD,IAAI,QAAQ,YAEX;IAGD;;OAEG;IACH,KAAK;CAwBR"}