turbine-orm 0.28.2 → 0.29.0

package/dist/cjs/client.js

@@ -911,14 +911,48 @@ class TurbineClient {
      * Execute a batch of {@link DeferredQuery} objects atomically inside one
      * transaction. Backs the `$transaction([...])` array overload. Reuses the raw
      * {@link transaction} machinery (BEGIN/COMMIT/ROLLBACK + connection release);
-     * queries run sequentially on the single transaction connection and each
-     * result is passed through its query's `transform`.
+     * each result is passed through its query's `transform`.
+     *
+     * Execution strategy on the single transaction connection:
+     *   - **Sequential (default).** Await each statement's reply before sending
+     *     the next. Safe on every driver; on a networked driver a batch of N
+     *     costs N round trips.
+     *   - **Pipelined.** When the checked-out connection advertises
+     *     {@link PgCompatPoolClient.supportsPipelining} (its `query()` accepts
+     *     concurrent calls and completes them in FIFO submission order), all
+     *     statements are dispatched in one write burst and the replies are
+     *     collected in order — ~1 round trip plus server time. Only taken when
+     *     the dialect's writes surface rows directly (`resultStrategy` !==
+     *     'reselect'): a reselect plan is itself a sequential write+read pair.
+     *
+     * The two paths share one failure contract: the first (lowest-index) failed
+     * statement's error is thrown (wrapped via {@link wrapPgError}) and the
+     * surrounding transaction rolls back, so no statement's effect survives. The
+     * pipelined path drains every in-flight reply (`Promise.allSettled`) before
+     * rethrowing, which keeps the connection's request/reply pairing intact and
+     * means ROLLBACK is only issued once no statement is still in flight.
      */
     async transactionBatch(queries) {
         if (queries.length === 0) {
             return [];
         }
         return this.transaction(async (client) => {
+            const pipelined = client.supportsPipelining === true &&
+                this.dialect.resultStrategy !== 'reselect';
+            if (pipelined) {
+                // Dispatch every statement before awaiting any reply. The driver's
+                // FIFO guarantee makes settled[i] the reply to queries[i].
+                const settled = await Promise.allSettled(queries.map((dq) => client.query(dq.sql, dq.params)));
+                const results = [];
+                for (let i = 0; i < settled.length; i++) {
+                    const outcome = settled[i];
+                    if (outcome.status === 'rejected') {
+                        throw (0, errors_js_1.wrapPgError)(outcome.reason);
+                    }
+                    results.push(queries[i].transform(outcome.value));
+                }
+                return results;
+            }
             const results = [];
             for (const dq of queries) {
                 let raw;

package/dist/cjs/generate.js

@@ -523,7 +523,7 @@ function generateIndex(schema) {
     const lines = [
         ...generatedFileHeader(),
         "import { TurbineClient as BaseTurbineClient, TransactionClient as BaseTransactionClient, QueryInterface } from 'turbine-orm';",
-        "import type { TurbineConfig, TransactionOptions } from 'turbine-orm';",
+        "import type { TurbineConfig, TransactionOptions, DeferredQuery, PipelineResults } from 'turbine-orm';",
         "import { SCHEMA } from './metadata.js';",
     ];
     // Import all entity types and relations maps
@@ -607,9 +607,13 @@ function generateIndex(schema) {
     lines.push('');
     // Augment TurbineClient via interface merging with a typed $transaction
     // overload. The callback parameter is narrowed to `TypedTransactionClient`
-    // so users get autocomplete on `tx.users`, `tx.posts`, etc. The base
-    // signature (callback parameter `BaseTransactionClient`) remains valid as
-    // an overload, so prior usage continues to typecheck.
+    // so users get autocomplete on `tx.users`, `tx.posts`, etc.
+    //
+    // IMPORTANT: the merged member must be compatible with the base class's
+    // $transaction ON ITS OWN (TS2415) — since v0.26 the base method also has a
+    // batch-array overload (`$transaction([...queries])`), so the merged
+    // interface must redeclare BOTH signatures. Emitting only the callback form
+    // makes every generated client fail `tsc` with "incorrectly extends".
     lines.push('export interface TurbineClient {');
     lines.push('  /**');
     lines.push('   * Run a callback inside a transaction. The callback receives a typed');
@@ -619,6 +623,13 @@ function generateIndex(schema) {
     lines.push('    fn: (tx: TypedTransactionClient) => Promise<R>,');
     lines.push('    options?: TransactionOptions,');
     lines.push('  ): Promise<R>;');
+    lines.push('  /**');
+    lines.push('   * Batch form: run several deferred queries in one transaction and get');
+    lines.push('   * their results as a tuple (same as the base client).');
+    lines.push('   */');
+    lines.push('  $transaction<T extends readonly DeferredQuery<unknown>[]>(');
+    lines.push('    queries: readonly [...T],');
+    lines.push('  ): Promise<PipelineResults<T>>;');
     lines.push('}');
     lines.push('');
     // Factory function with JSDoc

package/dist/cjs/powdb.js

@@ -23,8 +23,14 @@
  *     `string` PKs hold UUID strings.
  *   - **No JSON aggregation / link navigation** — single-query nested `with` is
  *     impossible → it degrades to batched N+1 loaders (Phase B).
- *   - **Single global write lock; no savepoints/isolation/pipelining** — nested
+ *   - **Single global write lock; no savepoints/isolation** — nested
  *     transactions / isolation / vector / LISTEN-NOTIFY / RLS throw.
+ *   - **The wire protocol pipelines** — `@zvndev/powdb-client` writes each
+ *     request frame immediately and matches replies FIFO, so multiple queries
+ *     may be in flight on one connection. {@link PowdbPool}'s checked-out
+ *     clients advertise `supportsPipelining`, which lets the batch
+ *     `$transaction([...])` overload dispatch all statements in one write
+ *     burst (~1 round trip) instead of one round trip per statement.
  *
  * `@zvndev/powdb-client` is an **optional peer dependency** loaded by dynamic
  * import; `npm i turbine-orm` still pulls only `pg`.
@@ -511,6 +517,16 @@ class PowdbPool {
         const client = await this.pool.acquire();
         let broken = false;
         return {
+            // The networked client's query() supports concurrent in-flight calls on
+            // one connection: every request frame is written to the socket
+            // immediately and replies are matched to callers in FIFO order. That
+            // lets the batch `$transaction([...])` path dispatch all statements in
+            // one write burst instead of paying a round trip per statement. Safe
+            // for the batch's rollback contract because a failed statement leaves
+            // the engine's transaction open (no aborted state, no auto-rollback) —
+            // later pipelined statements execute inside the same still-open
+            // transaction and the final `rollback` discards every effect.
+            supportsPipelining: true,
             // biome-ignore lint/suspicious/noExplicitAny: see query() above.
             query: async (text, values) => {
                 const { text: powql, params } = normalizeQueryArgs(text, values);

package/dist/client.d.ts

@@ -57,6 +57,17 @@ export interface PgCompatQueryResult<R = Record<string, unknown>> {
 export interface PgCompatPoolClient {
     query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<PgCompatQueryResult<R>>;
     release(err?: Error | boolean): void;
+    /**
+     * Optional driver capability: `true` when `query()` may be called again on
+     * this connection while earlier calls are still in flight, with replies
+     * delivered to callers in FIFO submission order. Drivers that set this let
+     * the batch `$transaction([...])` overload dispatch every statement in one
+     * write burst (~1 network round trip plus server time) instead of awaiting
+     * each reply before sending the next (N round trips). Leave unset for
+     * drivers (node-postgres included) whose batch path must stay strictly
+     * sequential.
+     */
+    readonly supportsPipelining?: boolean;
 }
 /**
  * Minimal pg-compatible pool. Pass any driver that satisfies this interface
@@ -564,8 +575,13 @@ export declare class TurbineClient {
      * of each query's transformed result; any failure rolls the whole batch back.
      *
      * Unlike {@link pipeline}, this never uses the extended-query pipeline
-     * protocol — it executes sequentially on the transaction connection, so it is
-     * safe on every driver (including HTTP/serverless pools).
+     * protocol. Statements run on the single transaction connection: strictly
+     * sequentially by default (safe on every driver, including HTTP/serverless
+     * pools), or — when the checked-out connection advertises
+     * {@link PgCompatPoolClient.supportsPipelining} — dispatched in one write
+     * burst with replies collected in order, saving a network round trip per
+     * statement. Either way the failure contract is identical: the first
+     * (lowest-index) failure aborts the batch and rolls everything back.
      *
      * @example
      * ```ts
@@ -580,8 +596,26 @@ export declare class TurbineClient {
      * Execute a batch of {@link DeferredQuery} objects atomically inside one
      * transaction. Backs the `$transaction([...])` array overload. Reuses the raw
      * {@link transaction} machinery (BEGIN/COMMIT/ROLLBACK + connection release);
-     * queries run sequentially on the single transaction connection and each
-     * result is passed through its query's `transform`.
+     * each result is passed through its query's `transform`.
+     *
+     * Execution strategy on the single transaction connection:
+     *   - **Sequential (default).** Await each statement's reply before sending
+     *     the next. Safe on every driver; on a networked driver a batch of N
+     *     costs N round trips.
+     *   - **Pipelined.** When the checked-out connection advertises
+     *     {@link PgCompatPoolClient.supportsPipelining} (its `query()` accepts
+     *     concurrent calls and completes them in FIFO submission order), all
+     *     statements are dispatched in one write burst and the replies are
+     *     collected in order — ~1 round trip plus server time. Only taken when
+     *     the dialect's writes surface rows directly (`resultStrategy` !==
+     *     'reselect'): a reselect plan is itself a sequential write+read pair.
+     *
+     * The two paths share one failure contract: the first (lowest-index) failed
+     * statement's error is thrown (wrapped via {@link wrapPgError}) and the
+     * surrounding transaction rolls back, so no statement's effect survives. The
+     * pipelined path drains every in-flight reply (`Promise.allSettled`) before
+     * rethrowing, which keeps the connection's request/reply pairing intact and
+     * means ROLLBACK is only issued once no statement is still in flight.
      */
     private transactionBatch;
     /**

package/dist/client.js

@@ -903,14 +903,48 @@ export class TurbineClient {
      * Execute a batch of {@link DeferredQuery} objects atomically inside one
      * transaction. Backs the `$transaction([...])` array overload. Reuses the raw
      * {@link transaction} machinery (BEGIN/COMMIT/ROLLBACK + connection release);
-     * queries run sequentially on the single transaction connection and each
-     * result is passed through its query's `transform`.
+     * each result is passed through its query's `transform`.
+     *
+     * Execution strategy on the single transaction connection:
+     *   - **Sequential (default).** Await each statement's reply before sending
+     *     the next. Safe on every driver; on a networked driver a batch of N
+     *     costs N round trips.
+     *   - **Pipelined.** When the checked-out connection advertises
+     *     {@link PgCompatPoolClient.supportsPipelining} (its `query()` accepts
+     *     concurrent calls and completes them in FIFO submission order), all
+     *     statements are dispatched in one write burst and the replies are
+     *     collected in order — ~1 round trip plus server time. Only taken when
+     *     the dialect's writes surface rows directly (`resultStrategy` !==
+     *     'reselect'): a reselect plan is itself a sequential write+read pair.
+     *
+     * The two paths share one failure contract: the first (lowest-index) failed
+     * statement's error is thrown (wrapped via {@link wrapPgError}) and the
+     * surrounding transaction rolls back, so no statement's effect survives. The
+     * pipelined path drains every in-flight reply (`Promise.allSettled`) before
+     * rethrowing, which keeps the connection's request/reply pairing intact and
+     * means ROLLBACK is only issued once no statement is still in flight.
      */
     async transactionBatch(queries) {
         if (queries.length === 0) {
             return [];
         }
         return this.transaction(async (client) => {
+            const pipelined = client.supportsPipelining === true &&
+                this.dialect.resultStrategy !== 'reselect';
+            if (pipelined) {
+                // Dispatch every statement before awaiting any reply. The driver's
+                // FIFO guarantee makes settled[i] the reply to queries[i].
+                const settled = await Promise.allSettled(queries.map((dq) => client.query(dq.sql, dq.params)));
+                const results = [];
+                for (let i = 0; i < settled.length; i++) {
+                    const outcome = settled[i];
+                    if (outcome.status === 'rejected') {
+                        throw wrapPgError(outcome.reason);
+                    }
+                    results.push(queries[i].transform(outcome.value));
+                }
+                return results;
+            }
             const results = [];
             for (const dq of queries) {
                 let raw;

package/dist/generate.js

@@ -516,7 +516,7 @@ export function generateIndex(schema) {
     const lines = [
         ...generatedFileHeader(),
         "import { TurbineClient as BaseTurbineClient, TransactionClient as BaseTransactionClient, QueryInterface } from 'turbine-orm';",
-        "import type { TurbineConfig, TransactionOptions } from 'turbine-orm';",
+        "import type { TurbineConfig, TransactionOptions, DeferredQuery, PipelineResults } from 'turbine-orm';",
         "import { SCHEMA } from './metadata.js';",
     ];
     // Import all entity types and relations maps
@@ -600,9 +600,13 @@ export function generateIndex(schema) {
     lines.push('');
     // Augment TurbineClient via interface merging with a typed $transaction
     // overload. The callback parameter is narrowed to `TypedTransactionClient`
-    // so users get autocomplete on `tx.users`, `tx.posts`, etc. The base
-    // signature (callback parameter `BaseTransactionClient`) remains valid as
-    // an overload, so prior usage continues to typecheck.
+    // so users get autocomplete on `tx.users`, `tx.posts`, etc.
+    //
+    // IMPORTANT: the merged member must be compatible with the base class's
+    // $transaction ON ITS OWN (TS2415) — since v0.26 the base method also has a
+    // batch-array overload (`$transaction([...queries])`), so the merged
+    // interface must redeclare BOTH signatures. Emitting only the callback form
+    // makes every generated client fail `tsc` with "incorrectly extends".
     lines.push('export interface TurbineClient {');
     lines.push('  /**');
     lines.push('   * Run a callback inside a transaction. The callback receives a typed');
@@ -612,6 +616,13 @@ export function generateIndex(schema) {
     lines.push('    fn: (tx: TypedTransactionClient) => Promise<R>,');
     lines.push('    options?: TransactionOptions,');
     lines.push('  ): Promise<R>;');
+    lines.push('  /**');
+    lines.push('   * Batch form: run several deferred queries in one transaction and get');
+    lines.push('   * their results as a tuple (same as the base client).');
+    lines.push('   */');
+    lines.push('  $transaction<T extends readonly DeferredQuery<unknown>[]>(');
+    lines.push('    queries: readonly [...T],');
+    lines.push('  ): Promise<PipelineResults<T>>;');
     lines.push('}');
     lines.push('');
     // Factory function with JSDoc

package/dist/powdb.d.ts

@@ -22,8 +22,14 @@
  *     `string` PKs hold UUID strings.
  *   - **No JSON aggregation / link navigation** — single-query nested `with` is
  *     impossible → it degrades to batched N+1 loaders (Phase B).
- *   - **Single global write lock; no savepoints/isolation/pipelining** — nested
+ *   - **Single global write lock; no savepoints/isolation** — nested
  *     transactions / isolation / vector / LISTEN-NOTIFY / RLS throw.
+ *   - **The wire protocol pipelines** — `@zvndev/powdb-client` writes each
+ *     request frame immediately and matches replies FIFO, so multiple queries
+ *     may be in flight on one connection. {@link PowdbPool}'s checked-out
+ *     clients advertise `supportsPipelining`, which lets the batch
+ *     `$transaction([...])` overload dispatch all statements in one write
+ *     burst (~1 round trip) instead of one round trip per statement.
  *
  * `@zvndev/powdb-client` is an **optional peer dependency** loaded by dynamic
  * import; `npm i turbine-orm` still pulls only `pg`.

package/dist/powdb.js

@@ -22,8 +22,14 @@
  *     `string` PKs hold UUID strings.
  *   - **No JSON aggregation / link navigation** — single-query nested `with` is
  *     impossible → it degrades to batched N+1 loaders (Phase B).
- *   - **Single global write lock; no savepoints/isolation/pipelining** — nested
+ *   - **Single global write lock; no savepoints/isolation** — nested
  *     transactions / isolation / vector / LISTEN-NOTIFY / RLS throw.
+ *   - **The wire protocol pipelines** — `@zvndev/powdb-client` writes each
+ *     request frame immediately and matches replies FIFO, so multiple queries
+ *     may be in flight on one connection. {@link PowdbPool}'s checked-out
+ *     clients advertise `supportsPipelining`, which lets the batch
+ *     `$transaction([...])` overload dispatch all statements in one write
+ *     burst (~1 round trip) instead of one round trip per statement.
  *
  * `@zvndev/powdb-client` is an **optional peer dependency** loaded by dynamic
  * import; `npm i turbine-orm` still pulls only `pg`.
@@ -464,6 +470,16 @@ export class PowdbPool {
         const client = await this.pool.acquire();
         let broken = false;
         return {
+            // The networked client's query() supports concurrent in-flight calls on
+            // one connection: every request frame is written to the socket
+            // immediately and replies are matched to callers in FIFO order. That
+            // lets the batch `$transaction([...])` path dispatch all statements in
+            // one write burst instead of paying a round trip per statement. Safe
+            // for the batch's rollback contract because a failed statement leaves
+            // the engine's transaction open (no aborted state, no auto-rollback) —
+            // later pipelined statements execute inside the same still-open
+            // transaction and the final `rollback` discards every effect.
+            supportsPipelining: true,
             // biome-ignore lint/suspicious/noExplicitAny: see query() above.
             query: async (text, values) => {
                 const { text: powql, params } = normalizeQueryArgs(text, values);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.28.2",
+  "version": "0.29.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {