turbine-orm 0.79.1 → 0.80.0

package/dist/cjs/client.js

@@ -29,6 +29,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TurbineClient = exports.TransactionClient = exports.READ_OPERATIONS = void 0;
 exports.withRetry = withRetry;
 const _pg_1 = __importDefault(require("pg"));
+const checkout_js_1 = require("./checkout.js");
+const connection_guard_js_1 = require("./connection-guard.js");
 const connection_url_js_1 = require("./connection-url.js");
 const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
@@ -363,29 +365,6 @@ const ISOLATION_LEVELS = Object.assign(Object.create(null), {
  * loops, and a loop keyed on it would never fire for the commit-time conflicts
  * that are the main reason to run SERIALIZABLE at all.
  */
-/**
- * Check out a pooled connection, translating a driver failure into a typed
- * Turbine error.
- *
- * `pool.connect()` is where the first-run failures actually land: wrong
- * password (SQLSTATE 28P01), no such database (3D000), nothing listening
- * (ECONNREFUSED), an unverifiable TLS certificate. Unwrapped, every one of
- * those left `$transaction`, `transaction()` and `connect()` as a raw pg
- * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
- * puts `TURBINE_E0NN` in, so the single error a new user is most likely to see
- * was the one error the typed-error contract did not cover.
- *
- * Query paths need no equivalent: `pool.query()` opens the connection itself
- * and rejects with the connect error, which the query boundary already wraps.
- */
-async function acquireConnection(pool) {
-    try {
-        return await pool.connect();
-    }
-    catch (err) {
-        throw (0, errors_js_1.wrapPgError)(err);
-    }
-}
 async function runTxControl(client, sql) {
     try {
         await client.query(sql);
@@ -982,6 +961,11 @@ class TurbineClient {
             ownPool.on('error', (err) => {
                 console.error('[turbine] Unexpected pool error:', err.message);
             });
+            (0, connection_guard_js_1.absorbCheckedOutErrors)(ownPool);
+            // After a freeze (a serverless function between invocations), wait one
+            // loop turn before reusing a long-idle connection, so the pool has read
+            // any close the server sent meanwhile. See connection-guard.ts.
+            (0, connection_guard_js_1.settleLongIdleCheckouts)(ownPool);
             this.pool = ownPool;
             this.ownsPool = true;
             if (this.logging) {
@@ -1005,6 +989,8 @@ class TurbineClient {
                 replicaPool.on('error', (err) => {
                     console.error('[turbine] Unexpected replica pool error:', err.message);
                 });
+                (0, connection_guard_js_1.absorbCheckedOutErrors)(replicaPool);
+                (0, connection_guard_js_1.settleLongIdleCheckouts)(replicaPool);
                 this.replicaPools.push(replicaPool);
                 this.ownedReplicaPools.push(replicaPool);
             }
@@ -1708,19 +1694,15 @@ class TurbineClient {
      * ```
      */
     async transaction(fn) {
-        const client = await acquireConnection(this.pool);
-        /**
-         * Only true once BEGIN has actually succeeded. If BEGIN itself throws
-         * (e.g. a single-writer engine's transaction gate times out or rejects a
-         * re-entrant begin), issuing a "best-effort" ROLLBACK would be a stray
-         * statement from a context that never opened a transaction, on a driver
-         * with one shared engine handle (PowDB embedded) it would roll back a
-         * DIFFERENT caller's open transaction.
-         */
-        let began = false;
+        // BEGIN runs inside openCheckout, which sends it once more on a fresh
+        // connection when the first one turns out to be dead. A BEGIN that fails
+        // for good throws from there with the connection already released, so the
+        // catch below only ever sees a transaction that began: its ROLLBACK can
+        // never be a stray statement from a context that opened none, which on a
+        // driver with one shared engine handle (PowDB embedded) would roll back a
+        // DIFFERENT caller's open transaction.
+        const { client, checkout } = await (0, checkout_js_1.openCheckout)(this.pool, (c) => runTxControl(c, this.dialect.beginStatement()));
         try {
-            await runTxControl(client, this.dialect.beginStatement());
-            began = true;
             // Engine seam: single-writer engines scope their transaction re-entrancy
             // marker to the callback's async subtree (see
             // PgCompatPoolClient.wrapTransactionCallback). Absent everywhere else.
@@ -1731,18 +1713,16 @@ class TurbineClient {
             return result;
         }
         catch (err) {
-            if (began) {
-                try {
-                    await client.query(this.dialect.rollbackStatement());
-                }
-                catch {
-                    // Best-effort rollback, the connection may have died mid-query.
-                }
+            try {
+                await client.query(this.dialect.rollbackStatement());
             }
-            throw err;
+            catch {
+                // Best-effort rollback, the connection may have died mid-query.
+            }
+            throw (0, errors_js_1.explainConnectionLoss)(err, checkout.lostWith);
         }
         finally {
-            client.release();
+            checkout.release();
         }
     }
     async $transaction(fnOrQueries, options) {
@@ -1761,7 +1741,13 @@ class TurbineClient {
         // Resolve the isolation level BEFORE taking a pool slot: a bad argument is
         // the caller's bug and should not cost a connection to discover.
         const isolationSql = resolveIsolationLevel(options?.isolationLevel);
-        const client = await acquireConnection(this.pool);
+        // BEGIN with optional isolation level, the dialect owns the keyword and
+        // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`). It
+        // runs inside openCheckout, which sends it once more on a fresh connection
+        // when the first one turns out to be dead, and which releases the
+        // connection itself when BEGIN fails for good. So everything below runs in
+        // a transaction that began.
+        const { client, checkout } = await (0, checkout_js_1.openCheckout)(this.pool, (c) => runTxControl(c, this.dialect.beginStatement(isolationSql)));
         const timeout = options?.timeout;
         /**
          * Track whether the connection has already been released so the finally
@@ -1774,27 +1760,14 @@ class TurbineClient {
                 return;
             released = true;
             try {
-                client.release(err);
+                checkout.release(err);
             }
             catch {
                 // pg may throw if the client is already released, swallow.
             }
         };
         let timedOut = false;
-        /**
-         * Only true once BEGIN has actually succeeded. If BEGIN itself throws -
-         * e.g. a single-writer engine's transaction gate times out in its FIFO
-         * queue or rejects a re-entrant begin (PowDB, E002/E017), this context
-         * never opened a transaction, so the catch below must NOT issue its
-         * best-effort ROLLBACK: on a driver with one shared engine handle that
-         * stray ROLLBACK would tear down a DIFFERENT caller's open transaction.
-         */
-        let began = false;
         try {
-            // BEGIN with optional isolation level, the dialect owns the keyword and
-            // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`).
-            await runTxControl(client, this.dialect.beginStatement(isolationSql));
-            began = true;
             // Apply transaction-local session context (RLS / multi-tenant GUCs).
             // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
             // user fn. Any error here propagates to the catch below and rolls back
@@ -1875,11 +1848,9 @@ class TurbineClient {
             // If the timeout fired we already destroyed the connection, issuing a
             // ROLLBACK on a released client would throw "Client has already been
             // released". Skip the rollback in that case (the backend rolled back
-            // when its socket was closed). Likewise skip it when BEGIN never
-            // succeeded (`began` false), there is no transaction to roll back and
-            // the stray statement could hit another caller's transaction on a
-            // shared-handle engine.
-            if (began && !timedOut && !released) {
+            // when its socket was closed). A BEGIN that failed never gets here, see
+            // openCheckout above, so there is always a transaction to roll back.
+            if (!timedOut && !released) {
                 try {
                     await client.query(this.dialect.rollbackStatement());
                 }
@@ -1890,7 +1861,7 @@ class TurbineClient {
             if (this.logging) {
                 console.log('[turbine] Transaction rolled back');
             }
-            throw err;
+            throw (0, errors_js_1.explainConnectionLoss)(err, checkout.lostWith);
         }
         finally {
             releaseOnce();
@@ -2001,17 +1972,27 @@ class TurbineClient {
      * cannot do this, `$listen` throws a `ConnectionError` rather than hang.
      * `$notify` works on every driver.
      *
+     * **Connection loss:** if the subscription's connection dies (a restart,
+     * failover, compute suspend, `pg_terminate_backend`), it reconnects with
+     * exponential backoff and re-issues `LISTEN`; `options.reconnect: false`
+     * ends it instead. Postgres does not hold notifications for a disconnected
+     * listener, so anything sent during the gap is lost: use
+     * `options.onReconnect` to resynchronise. `options.onError` receives the loss
+     * and each failed attempt (default: one `console.error` line each).
+     *
      * @example
      * ```ts
      * const sub = await db.$listen('order_created', (payload) => {
      *   const order = JSON.parse(payload);
      *   console.log('new order', order.id);
+     * }, {
+     *   onReconnect: () => refreshOrdersFromDatabase(),
      * });
      * // ...later
      * await sub.unsubscribe();
      * ```
      */
-    async $listen(channel, handler) {
+    async $listen(channel, handler, options) {
         if (!this.dialect.supportsListenNotify) {
             throw new errors_js_1.UnsupportedFeatureError('$listen (LISTEN/NOTIFY realtime)', this.dialect.name, 'Realtime pub/sub requires PostgreSQL.');
         }
@@ -2022,7 +2003,7 @@ class TurbineClient {
         }
         const sub = await (0, realtime_js_1.createSubscription)(this.pool, channel, quoted, handler, (closed) => {
             this.activeSubscriptions.delete(closed);
-        });
+        }, options);
         this.activeSubscriptions.add(sub);
         return sub;
     }
@@ -2083,15 +2064,20 @@ class TurbineClient {
      * Throws if the connection fails.
      */
     async connect() {
-        const client = await acquireConnection(this.pool);
-        try {
-            await client.query('SELECT 1');
-            if (this.logging) {
-                console.log('[turbine] Connection verified');
+        // A connection the server closed while idle says nothing about whether
+        // the database is reachable, so the check runs on a fresh one when the
+        // first turns out to be dead (see openCheckout).
+        const { checkout } = await (0, checkout_js_1.openCheckout)(this.pool, async (client) => {
+            try {
+                await client.query('SELECT 1');
             }
-        }
-        finally {
-            client.release();
+            catch (err) {
+                throw (0, errors_js_1.wrapPgError)(err);
+            }
+        });
+        checkout.release();
+        if (this.logging) {
+            console.log('[turbine] Connection verified');
         }
     }
     /**

package/dist/cjs/connection-guard.d.ts

@@ -0,0 +1,120 @@
+/**
+ * turbine-orm, connection error guard
+ *
+ * A pg client emits `'error'` when its socket dies: a database restart, a
+ * failover, a serverless compute suspend, `pg_terminate_backend`. pg-pool keeps
+ * a listener on every IDLE client and removes it at checkout, so for as long as
+ * a client is checked out nobody is listening unless the borrower is, and an
+ * `'error'` event with no listener is thrown by Node's EventEmitter. The
+ * process exits. Every place Turbine holds a connection across an await
+ * (`$transaction`, `transaction()`, nested writes, cursor streams, pipelines,
+ * `$listen`, Studio and MCP requests) was one database restart away from taking
+ * the application down with it.
+ *
+ * The fix is a listener for exactly the checkout window: attached right after
+ * `pool.connect()` resolves (a promise continuation, so no socket event can
+ * slip in before it), removed right after `release()`, which is where pg-pool
+ * re-attaches its own. The listener does not need to reject anything itself:
+ * pg already fails the in-flight query and every queued one, and any later
+ * query on the dead client rejects with "not queryable", so the pending call
+ * always rejects on its own. What was missing was only the listener that stops
+ * the event from being fatal. It also records the first error, for two reasons:
+ * `release()` passes it on so the pool destroys the connection instead of
+ * lending it out again, and callers can report the ORIGINAL cause (say, 57P01
+ * `terminating connection due to administrator command`) rather than the
+ * follow-on "Client has encountered a connection error and is not queryable".
+ *
+ * ZERO imports, same reason as connection-url.ts: `query/`, `cli/` and
+ * client.ts all check connections out, and a leaf is the only place all three
+ * can share without a new edge in the import graph.
+ */
+/** Anything checked out of a pool: a `release()` plus, on pg, the emitter surface. */
+interface Releasable {
+    release(err?: Error | boolean): void;
+}
+export interface ConnectionGuard {
+    /** The first error the connection emitted while guarded, if it emitted one. */
+    readonly lostWith: Error | undefined;
+    /** Remove the listener. Idempotent. For clients Turbine owns outright (a bare `pg.Client`). */
+    detach(): void;
+}
+export interface CheckoutGuard extends ConnectionGuard {
+    /**
+     * Hand the client back to its pool and remove the listener. Idempotent. A
+     * connection that errored while checked out is released WITH that error, so
+     * pg-pool destroys it rather than returning it to the idle set; an explicit
+     * `err` argument takes precedence.
+     */
+    release(err?: Error | boolean): void;
+}
+/**
+ * Keep every connection a pool opens from ever emitting an unheard `'error'`.
+ * For pools Turbine creates itself, where it can: pg-pool listens on IDLE
+ * clients only, so a checkout made outside Turbine's own guarded paths
+ * (`db.pool.connect()` in application code, a CLI server's request handler) is
+ * otherwise one database restart from exiting the process. The listener
+ * absorbs nothing that matters: the borrower's pending query still rejects,
+ * and pg-pool still evicts a client that failed. A pool with no `connect`
+ * event (an engine shim) is left alone.
+ */
+export declare function absorbCheckedOutErrors(pool: unknown): void;
+/**
+ * Guard a connection for as long as the caller holds it. Use {@link guardCheckout}
+ * for a pooled checkout; this form is for a client whose whole lifetime the
+ * caller owns (`new pg.Client()` in a CLI command or `schemaPush`).
+ *
+ * `onLost` runs once, on the first error, for a holder that has no query in
+ * flight to learn about the loss from (a LISTEN connection waiting for
+ * notifications).
+ */
+export declare function guardConnection(client: unknown, onLost?: (err: Error) => void): ConnectionGuard;
+/** Guard a pooled checkout from `pool.connect()` until its `release()`. */
+export declare function guardCheckout(client: Releasable, onLost?: (err: Error) => void): CheckoutGuard;
+/**
+ * Resolve after the event loop has run at least one full poll phase.
+ *
+ * Two `setImmediate` hops, not one: a continuation that starts in the poll
+ * phase would reach its first hop in the SAME iteration's check phase, before
+ * any socket event that arrived meanwhile has been read. The second hop is
+ * queued for the next iteration, which polls first. `setTimeout` stands in on
+ * runtimes without `setImmediate` (edge), where one timer turn also polls.
+ */
+export declare function settleEventLoop(): Promise<void>;
+/**
+ * How long a pool must have gone without a connection coming back before the
+ * next checkout waits for {@link settleEventLoop}. Long enough that a pool in
+ * steady use never pays it; short enough to cover a serverless freeze between
+ * invocations, which is where dead idle connections come from.
+ */
+export declare const LONG_IDLE_SETTLE_MS = 1000;
+/**
+ * Stop a pool from lending out a connection the server has already closed.
+ *
+ * pg-pool evicts an idle connection when its socket reports the close, which
+ * needs the event loop to read the socket. When the loop has NOT run (a
+ * serverless function frozen between invocations, a long synchronous block),
+ * a restart, failover, pooler recycle or compute suspend in that window leaves
+ * every idle connection dead but still in the idle list. The first checkout
+ * after the thaw runs before the loop polls, so it gets one, and so does every
+ * concurrent caller: measured on PostgreSQL 17 with the loop blocked across a
+ * `pg_terminate_backend` of all five idle connections, five concurrent queries
+ * all failed with 57P01. Awake, the same terminate costs nothing, because the
+ * closes are read as they arrive.
+ *
+ * So a checkout that would reuse a connection idle for at least
+ * {@link LONG_IDLE_SETTLE_MS} first waits for one poll phase. Every close that
+ * arrived during the freeze is read then, pg-pool evicts those connections,
+ * and the checkout gets a live one or opens a fresh one. No round trip: a
+ * `SELECT 1` validation would cost one on every such checkout, and the loop
+ * turn is what actually carries the information. A pool in steady use returns
+ * a connection far more often than once a second and never pays it.
+ *
+ * Idle age is taken from the last clean `'release'`: pg-pool reuses the most
+ * recently returned connection first, so that is the age of the one the next
+ * checkout gets. Wrapping `connect` covers `pool.query` too, which checks out
+ * through `this.connect`. Pools without pg-pool's `'release'` event (engine
+ * shims, HTTP pools) are left alone. For pools Turbine creates only: a
+ * caller's own pool is not Turbine's to patch.
+ */
+export declare function settleLongIdleCheckouts(pool: unknown, idleMs?: number): void;
+export {};

package/dist/cjs/connection-guard.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * turbine-orm, connection error guard
+ *
+ * A pg client emits `'error'` when its socket dies: a database restart, a
+ * failover, a serverless compute suspend, `pg_terminate_backend`. pg-pool keeps
+ * a listener on every IDLE client and removes it at checkout, so for as long as
+ * a client is checked out nobody is listening unless the borrower is, and an
+ * `'error'` event with no listener is thrown by Node's EventEmitter. The
+ * process exits. Every place Turbine holds a connection across an await
+ * (`$transaction`, `transaction()`, nested writes, cursor streams, pipelines,
+ * `$listen`, Studio and MCP requests) was one database restart away from taking
+ * the application down with it.
+ *
+ * The fix is a listener for exactly the checkout window: attached right after
+ * `pool.connect()` resolves (a promise continuation, so no socket event can
+ * slip in before it), removed right after `release()`, which is where pg-pool
+ * re-attaches its own. The listener does not need to reject anything itself:
+ * pg already fails the in-flight query and every queued one, and any later
+ * query on the dead client rejects with "not queryable", so the pending call
+ * always rejects on its own. What was missing was only the listener that stops
+ * the event from being fatal. It also records the first error, for two reasons:
+ * `release()` passes it on so the pool destroys the connection instead of
+ * lending it out again, and callers can report the ORIGINAL cause (say, 57P01
+ * `terminating connection due to administrator command`) rather than the
+ * follow-on "Client has encountered a connection error and is not queryable".
+ *
+ * ZERO imports, same reason as connection-url.ts: `query/`, `cli/` and
+ * client.ts all check connections out, and a leaf is the only place all three
+ * can share without a new edge in the import graph.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LONG_IDLE_SETTLE_MS = void 0;
+exports.absorbCheckedOutErrors = absorbCheckedOutErrors;
+exports.guardConnection = guardConnection;
+exports.guardCheckout = guardCheckout;
+exports.settleEventLoop = settleEventLoop;
+exports.settleLongIdleCheckouts = settleLongIdleCheckouts;
+/**
+ * Keep every connection a pool opens from ever emitting an unheard `'error'`.
+ * For pools Turbine creates itself, where it can: pg-pool listens on IDLE
+ * clients only, so a checkout made outside Turbine's own guarded paths
+ * (`db.pool.connect()` in application code, a CLI server's request handler) is
+ * otherwise one database restart from exiting the process. The listener
+ * absorbs nothing that matters: the borrower's pending query still rejects,
+ * and pg-pool still evicts a client that failed. A pool with no `connect`
+ * event (an engine shim) is left alone.
+ */
+function absorbCheckedOutErrors(pool) {
+    const emitter = pool;
+    if (typeof emitter.on !== 'function')
+        return;
+    emitter.on('connect', (client) => {
+        client.on?.('error', () => { });
+    });
+}
+/**
+ * Guard a connection for as long as the caller holds it. Use {@link guardCheckout}
+ * for a pooled checkout; this form is for a client whose whole lifetime the
+ * caller owns (`new pg.Client()` in a CLI command or `schemaPush`).
+ *
+ * `onLost` runs once, on the first error, for a holder that has no query in
+ * flight to learn about the loss from (a LISTEN connection waiting for
+ * notifications).
+ */
+function guardConnection(client, onLost) {
+    const emitter = client;
+    let lostWith;
+    let attached = false;
+    const onError = (err) => {
+        if (lostWith)
+            return;
+        lostWith = err;
+        onLost?.(err);
+    };
+    if (typeof emitter.on === 'function') {
+        emitter.on('error', onError);
+        attached = true;
+    }
+    return {
+        get lostWith() {
+            return lostWith;
+        },
+        detach() {
+            if (!attached)
+                return;
+            attached = false;
+            emitter.removeListener?.('error', onError);
+        },
+    };
+}
+/** Guard a pooled checkout from `pool.connect()` until its `release()`. */
+function guardCheckout(client, onLost) {
+    const guard = guardConnection(client, onLost);
+    let released = false;
+    return {
+        get lostWith() {
+            return guard.lostWith;
+        },
+        detach: guard.detach,
+        release(err) {
+            if (released)
+                return;
+            released = true;
+            try {
+                client.release(err ?? guard.lostWith);
+            }
+            finally {
+                // After release, not before: pg-pool re-attaches its idle listener
+                // inside release(), so detaching second leaves no window with none.
+                // A connection that already failed keeps the listener: it is being
+                // destroyed, pg emits 'error' a second time when the socket finally
+                // ends, and a pool that does not re-listen on release would let that
+                // one through. A live connection must shed it, or listeners pile up
+                // across checkouts.
+                if (!guard.lostWith)
+                    guard.detach();
+            }
+        },
+    };
+}
+/**
+ * Resolve after the event loop has run at least one full poll phase.
+ *
+ * Two `setImmediate` hops, not one: a continuation that starts in the poll
+ * phase would reach its first hop in the SAME iteration's check phase, before
+ * any socket event that arrived meanwhile has been read. The second hop is
+ * queued for the next iteration, which polls first. `setTimeout` stands in on
+ * runtimes without `setImmediate` (edge), where one timer turn also polls.
+ */
+function settleEventLoop() {
+    const hop = typeof setImmediate === 'function' ? setImmediate : (fn) => setTimeout(fn, 0);
+    return new Promise((resolve) => {
+        hop(() => hop(resolve));
+    });
+}
+/**
+ * How long a pool must have gone without a connection coming back before the
+ * next checkout waits for {@link settleEventLoop}. Long enough that a pool in
+ * steady use never pays it; short enough to cover a serverless freeze between
+ * invocations, which is where dead idle connections come from.
+ */
+exports.LONG_IDLE_SETTLE_MS = 1000;
+/**
+ * Stop a pool from lending out a connection the server has already closed.
+ *
+ * pg-pool evicts an idle connection when its socket reports the close, which
+ * needs the event loop to read the socket. When the loop has NOT run (a
+ * serverless function frozen between invocations, a long synchronous block),
+ * a restart, failover, pooler recycle or compute suspend in that window leaves
+ * every idle connection dead but still in the idle list. The first checkout
+ * after the thaw runs before the loop polls, so it gets one, and so does every
+ * concurrent caller: measured on PostgreSQL 17 with the loop blocked across a
+ * `pg_terminate_backend` of all five idle connections, five concurrent queries
+ * all failed with 57P01. Awake, the same terminate costs nothing, because the
+ * closes are read as they arrive.
+ *
+ * So a checkout that would reuse a connection idle for at least
+ * {@link LONG_IDLE_SETTLE_MS} first waits for one poll phase. Every close that
+ * arrived during the freeze is read then, pg-pool evicts those connections,
+ * and the checkout gets a live one or opens a fresh one. No round trip: a
+ * `SELECT 1` validation would cost one on every such checkout, and the loop
+ * turn is what actually carries the information. A pool in steady use returns
+ * a connection far more often than once a second and never pays it.
+ *
+ * Idle age is taken from the last clean `'release'`: pg-pool reuses the most
+ * recently returned connection first, so that is the age of the one the next
+ * checkout gets. Wrapping `connect` covers `pool.query` too, which checks out
+ * through `this.connect`. Pools without pg-pool's `'release'` event (engine
+ * shims, HTTP pools) are left alone. For pools Turbine creates only: a
+ * caller's own pool is not Turbine's to patch.
+ */
+function settleLongIdleCheckouts(pool, idleMs = exports.LONG_IDLE_SETTLE_MS) {
+    const p = pool;
+    const connect = p.connect;
+    if (typeof p.on !== 'function' || typeof connect !== 'function')
+        return;
+    let lastReturnedAt = performance.now();
+    p.on('release', (err) => {
+        if (!err)
+            lastReturnedAt = performance.now();
+    });
+    p.connect = (...args) => {
+        if (!((p.idleCount ?? 0) > 0) || performance.now() - lastReturnedAt < idleMs)
+            return connect.apply(p, args);
+        const settled = settleEventLoop().then(() => connect.apply(p, args));
+        // Callback form (pool.query's internal checkout): the callback carries the
+        // result, and pg-pool returns nothing in that form either.
+        return typeof args[0] === 'function' ? undefined : settled;
+    };
+}

package/dist/cjs/errors.d.ts

@@ -556,6 +556,32 @@ export declare class ReadOnlyError extends TurbineError {
         reason?: 'snapshot' | 'rbac';
     });
 }
+/**
+ * Report the error that KILLED a held connection instead of its follow-on.
+ *
+ * When a connection dies while a transaction callback is between queries, the
+ * next query fails with "Client has encountered a connection error and is not
+ * queryable", which says nothing about why. The connection guard recorded the
+ * real cause (`lostWith`, e.g. 57P01 `terminating connection due to
+ * administrator command`), so a not-queryable ConnectionError is swapped for
+ * that one. Anything else passes through: an error the caller threw, or a
+ * query that was IN FLIGHT when the connection died, which already carries the
+ * server's own message.
+ */
+export declare function explainConnectionLoss(err: unknown, lostWith: Error | undefined): unknown;
+/**
+ * Whether `err` says a connection that was already open is gone, so the same
+ * statement on a fresh connection can succeed. Accepts the raw driver error or
+ * the {@link ConnectionError} wrapPgError made of it.
+ *
+ * Narrower than "is a ConnectionError" on purpose. A connection that could not
+ * be OPENED (refused, DNS, auth, a connect timeout, 57P03 while the server
+ * starts) will not open on an immediate second try either, and retrying it
+ * only doubles the wait before the caller hears about it. Nor does it cover
+ * `Connection terminated` without "unexpectedly", which is the pool itself
+ * shutting down.
+ */
+export declare function isStaleConnectionError(err: unknown): boolean;
 /**
  * Translate a pg driver error into a typed Turbine error.
  *