turbine-orm 0.7.1 → 0.9.0

package/dist/cjs/pipeline.js

@@ -8,25 +8,74 @@
  * How it works:
  *   1. Each query method (findUnique, count, etc.) can produce a DeferredQuery descriptor
  *      containing the SQL, params, and a transform function.
- *   2. pipeline() collects these descriptors, executes them in a single Postgres
- *      pipeline/transaction, and maps each result through its transform.
+ *   2. pipeline() collects these descriptors, checks whether the underlying pool client
+ *      supports the extended-query pipeline protocol, and either:
+ *      (a) executes them via real Postgres pipeline protocol (one TCP flush), or
+ *      (b) falls back to sequential execution on a single connection.
  *
- * In the production Turbine engine, this would go through the Rust proxy which uses
- * actual Postgres pipeline protocol (libpq PQpipelineEnter). For the TS SDK prototype,
- * we simulate it by running queries concurrently on a single connection or via
- * a multi-statement batch.
+ * Real pipeline mode uses `src/pipeline-submittable.ts` which drives the pg Connection's
+ * wire-protocol methods (parse/bind/describe/execute/sync) directly with listener-swap.
+ *
+ * Sequential fallback covers HTTP-based drivers (Neon HTTP, Vercel Postgres, Cloudflare
+ * Hyperdrive), mock pools in tests, and any pool that doesn't expose pg internals.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executePipeline = executePipeline;
+exports.pipelineSupported = pipelineSupported;
 const errors_js_1 = require("./errors.js");
+const pipeline_submittable_js_1 = require("./pipeline-submittable.js");
+/**
+ * Execute queries sequentially on an already-acquired connection.
+ * This is the fallback path for clients that don't support the extended-query
+ * pipeline protocol (HTTP drivers, mocks, etc.).
+ *
+ * The caller is responsible for acquiring the client and releasing it after
+ * this function completes (in the finally block).
+ */
+async function runSequential(client, queries, options = {}) {
+    const { transactional = true } = options;
+    try {
+        if (transactional) {
+            await client.query('BEGIN');
+        }
+        const results = [];
+        for (const q of queries) {
+            let raw;
+            try {
+                raw = await client.query(q.sql, q.params);
+            }
+            catch (err) {
+                throw (0, errors_js_1.wrapPgError)(err);
+            }
+            results.push(q.transform(raw));
+        }
+        if (transactional) {
+            await client.query('COMMIT');
+        }
+        return results;
+    }
+    catch (err) {
+        if (transactional) {
+            try {
+                await client.query('ROLLBACK');
+            }
+            catch {
+                // Best-effort rollback
+            }
+        }
+        throw err;
+    }
+}
 // ---------------------------------------------------------------------------
-// Pipeline executor
+// Pipeline executor (public)
 // ---------------------------------------------------------------------------
 /**
  * Execute multiple deferred queries in a single batch.
  *
- * Uses a single connection from the pool and runs all queries within
- * a transaction to guarantee consistency and minimize round-trips.
+ * On pg.Pool-backed connections with the standard TCP driver, this uses the
+ * real Postgres extended-query pipeline protocol for true 1-RTT execution.
+ * On HTTP-based drivers (Neon HTTP, Vercel Postgres, etc.) or mock pools,
+ * it falls back to sequential execution on a single connection.
  *
  * @example
  * ```ts
@@ -37,42 +86,46 @@ const errors_js_1 = require("./errors.js");
  * ]);
  * ```
  */
-async function executePipeline(pool, queries) {
+async function executePipeline(pool, queries, options) {
     if (queries.length === 0) {
         return [];
     }
-    // Acquire a single connection for the entire batch
+    // Acquire a single client — reused for both capability check and execution
     const client = await pool.connect();
     try {
-        // Wrap in a transaction for consistency
-        await client.query('BEGIN');
-        // Execute all queries on the same connection — in sequence on a single
-        // connection this avoids pool checkout overhead, and the Postgres server
-        // processes them as a tight batch.
-        //
-        // Execute queries sequentially on the same connection to avoid the
-        // "already executing a query" deprecation in pg@8. This is still faster
-        // than separate pool checkouts because we skip N-1 acquire/release cycles.
-        // Future: use actual Postgres pipeline protocol for true pipelining.
-        const results = [];
-        for (const q of queries) {
-            let raw;
-            try {
-                raw = await client.query(q.sql, q.params);
-            }
-            catch (err) {
-                throw (0, errors_js_1.wrapPgError)(err);
-            }
-            results.push(q.transform(raw));
+        if ((0, pipeline_submittable_js_1.supportsExtendedPipeline)(client)) {
+            // Real pipeline path — uses extended-query protocol wire methods
+            const pipelineOptions = {
+                transactional: options?.transactional ?? true,
+                timeout: options?.timeout,
+            };
+            const results = await (0, pipeline_submittable_js_1.runPipelined)(client, queries, pipelineOptions);
+            return results;
         }
-        await client.query('COMMIT');
-        return results;
-    }
-    catch (err) {
-        await client.query('ROLLBACK');
-        throw err;
+        // Sequential fallback — reuses the same client
+        return await runSequential(client, queries, options);
     }
     finally {
         client.release();
     }
 }
+/**
+ * Check whether a pool supports the real pipeline protocol.
+ * Call this to determine at runtime whether pipelines will use the fast path
+ * or fall back to sequential execution.
+ *
+ * Note: This acquires and immediately releases a connection to inspect it.
+ */
+async function pipelineSupported(pool) {
+    let client;
+    try {
+        client = await pool.connect();
+        return (0, pipeline_submittable_js_1.supportsExtendedPipeline)(client);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        client?.release();
+    }
+}