turbine-orm 0.79.1 → 0.80.0

package/dist/realtime.js

@@ -24,7 +24,20 @@
  *   (Neon HTTP, Vercel Postgres over fetch) cannot hold such a connection, so
  *   `$listen` will surface a clear error rather than hang. `$notify` works
  *   everywhere, it's a single round-trip `SELECT pg_notify(...)`.
+ *
+ * Connection loss:
+ *
+ *   A subscription's connection is held indefinitely with no query in flight,
+ *   so a database restart, failover or `pg_terminate_backend` reaches it only
+ *   as an `'error'` event. That event used to have no listener, which exits the
+ *   process. It is now guarded (connection-guard.ts), and the subscription
+ *   RECONNECTS by default: the dead connection is destroyed, a fresh one is
+ *   checked out with exponential backoff, and `LISTEN` is re-issued. Postgres
+ *   does not queue notifications for a listener that is not connected, so
+ *   anything NOTIFYed during the gap is gone for good; `onReconnect` is the
+ *   caller's cue to resynchronise from the source of truth.
  */
+import { guardCheckout } from './connection-guard.js';
 import { ConnectionError, ValidationError, wrapPgError } from './errors.js';
 // ---------------------------------------------------------------------------
 // Identifier validation
@@ -58,17 +71,12 @@ export function validateChannel(channel) {
             '(letters, digits, underscores; cannot start with a digit)');
     }
 }
+const DEFAULT_RECONNECT = { initialDelayMs: 100, maxDelayMs: 30_000 };
 /**
- * Acquire a dedicated connection, run `LISTEN "channel"`, and wire the handler.
- *
- * @param pool        the pg-compatible pool to check a long-lived client out of
- * @param channel     channel name, MUST already be validated by the caller
- * @param quotedChannel  the channel run through quoteIdent (interpolated into SQL)
- * @param handler     called with each notification's payload
- * @param onClosed    invoked when the subscription releases, so the client can
- *                    drop it from its active-subscription registry
+ * Check out a dedicated connection, wire the handler and run `LISTEN`. Throws
+ * (typed) on failure, having given the connection back.
  */
-export async function createSubscription(pool, channel, quotedChannel, handler, onClosed) {
+async function openListenConnection(pool, channel, quotedChannel, handler, onLost) {
     let client;
     try {
         client = (await pool.connect());
@@ -81,11 +89,12 @@ export async function createSubscription(pool, channel, quotedChannel, handler,
     // forever waiting for messages that can never arrive, so fail loudly now and
     // give the connection straight back.
     if (typeof client.on !== 'function') {
-        client.release?.();
+        client.release();
         throw new ConnectionError('$listen requires a persistent connection that can push notifications. ' +
             'The configured pool returned a client with no event support (stateless HTTP drivers ' +
             'like Neon HTTP / Vercel Postgres cannot LISTEN). Use a TCP pg.Pool for LISTEN/NOTIFY.');
     }
+    const checkout = guardCheckout(client, onLost);
     const onNotification = (msg) => {
         // pg delivers ALL notifications for the connection to every listener; a
         // dedicated connection only ever LISTENs on one channel, but guard anyway.
@@ -99,43 +108,139 @@ export async function createSubscription(pool, channel, quotedChannel, handler,
     }
     catch (err) {
         client.removeListener?.('notification', onNotification);
-        client.release?.();
+        checkout.release(err instanceof Error ? err : true);
         throw wrapPgError(err);
     }
+    return { client, checkout, onNotification };
+}
+/**
+ * Acquire a dedicated connection, run `LISTEN "channel"`, and wire the handler.
+ * A failure here is thrown to the `$listen` caller; only a connection lost
+ * AFTER the subscription is established is retried.
+ *
+ * @param pool        the pg-compatible pool to check a long-lived client out of
+ * @param channel     channel name, MUST already be validated by the caller
+ * @param quotedChannel  the channel run through quoteIdent (interpolated into SQL)
+ * @param handler     called with each notification's payload
+ * @param onClosed    invoked when the subscription ends, so the client can
+ *                    drop it from its active-subscription registry
+ * @param options     reconnect policy and loss/reconnect callbacks
+ */
+export async function createSubscription(pool, channel, quotedChannel, handler, onClosed, options = {}) {
+    const backoff = options.reconnect === false
+        ? undefined
+        : { ...DEFAULT_RECONNECT, ...(typeof options.reconnect === 'object' ? options.reconnect : {}) };
+    const reportError = options.onError ??
+        ((err) => {
+            console.error(`[turbine] $listen "${channel}": ${err.message}${backoff && !closed ? ', reconnecting' : ''}`);
+        });
     let closed = false;
+    let current;
+    let timer;
+    let delay = backoff?.initialDelayMs ?? 0;
+    /** Let go of the held connection. A lost one is destroyed, never pooled. */
+    const dropCurrent = (destroy) => {
+        const conn = current;
+        if (!conn)
+            return;
+        current = undefined;
+        conn.client.removeListener?.('notification', conn.onNotification);
+        conn.checkout.release(destroy);
+    };
+    const scheduleReconnect = () => {
+        if (closed || !backoff)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void attemptReconnect();
+        }, delay);
+        // A process with nothing else to do should not stay alive just to retry.
+        timer.unref?.();
+        delay = Math.min(delay * 2, backoff.maxDelayMs);
+    };
+    const onLost = (err) => {
+        if (closed || !current)
+            return;
+        dropCurrent(err);
+        const lost = wrapPgError(err);
+        reportError(lost instanceof Error ? lost : err);
+        if (!backoff) {
+            closed = true;
+            onClosed(sub);
+            return;
+        }
+        delay = backoff.initialDelayMs;
+        scheduleReconnect();
+    };
+    const attemptReconnect = async () => {
+        if (closed)
+            return;
+        let conn;
+        try {
+            conn = await openListenConnection(pool, channel, quotedChannel, handler, onLost);
+        }
+        catch (err) {
+            if (closed)
+                return;
+            reportError(err instanceof Error ? err : new Error(String(err)));
+            scheduleReconnect();
+            return;
+        }
+        if (closed) {
+            // unsubscribe() or disconnect() ran while this attempt was in flight.
+            conn.client.removeListener?.('notification', conn.onNotification);
+            conn.checkout.release(true);
+            return;
+        }
+        current = conn;
+        if (backoff)
+            delay = backoff.initialDelayMs;
+        options.onReconnect?.();
+    };
+    current = await openListenConnection(pool, channel, quotedChannel, handler, onLost);
+    const stop = () => {
+        closed = true;
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    };
     const sub = {
         channel,
         async unsubscribe() {
             if (closed)
                 return;
-            closed = true;
+            stop();
+            const conn = current;
+            if (!conn) {
+                // Between connections: nothing is LISTENing, so there is nothing to undo.
+                onClosed(sub);
+                return;
+            }
             try {
-                await client.query(`UNLISTEN ${quotedChannel}`);
+                await conn.client.query(`UNLISTEN ${quotedChannel}`);
             }
             catch (err) {
                 // Best-effort: the connection may already be dead. Still detach +
                 // release below so we don't leak the pool slot.
-                client.removeListener?.('notification', onNotification);
-                client.release?.();
+                dropCurrent(true);
                 onClosed(sub);
                 throw wrapPgError(err);
             }
-            client.removeListener?.('notification', onNotification);
-            client.release?.();
+            dropCurrent(undefined);
             onClosed(sub);
         },
         _forceRelease() {
             if (closed)
                 return;
-            closed = true;
-            client.removeListener?.('notification', onNotification);
+            stop();
             // Destroy the connection (release(true)) rather than return it to the pool:
             // we skip UNLISTEN here (the pool is being torn down), so a recycled
             // connection would otherwise carry a stale LISTEN registration. Destroying
             // it guarantees no pooled backend keeps receiving NOTIFY traffic. Matters
             // most for external/serverless pools, where disconnect() is a no-op and the
             // pool outlives this client.
-            client.release?.(true);
+            dropCurrent(true);
             onClosed(sub);
         },
     };

package/dist/schema-sql.js

@@ -6,6 +6,7 @@
  */
 import pg from 'pg';
 import { DESTRUCTIVE_KIND_LABEL, scanDestructiveSql } from './cli/destructive.js';
+import { guardConnection } from './connection-guard.js';
 import { postgresDialect } from './dialect.js';
 import { UnsupportedFeatureError, ValidationError } from './errors.js';
 import { pgConfActionToReferential, stripCheckWrapper } from './introspect.js';
@@ -597,6 +598,9 @@ export async function schemaDiff(schema, connectionString, options = {}) {
     // `pgSchema` because `schema` is already the SchemaDef in this function.
     const pgSchema = options.schema ?? 'public';
     const client = new pg.Client({ connectionString });
+    // A bare client with no 'error' listener exits the process if the server
+    // drops it mid-diff; guarded, the pending query rejects instead.
+    guardConnection(client);
     await client.connect();
     try {
         // Get existing tables in the target schema
@@ -1616,6 +1620,8 @@ export async function schemaPush(schema, connectionString, options = {}) {
     }
     // Execute all statements in a transaction
     const client = new pg.Client({ connectionString });
+    // Same as schemaDiff: a dropped connection must reject the push, not exit.
+    guardConnection(client);
     await client.connect();
     try {
         await client.query('BEGIN');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.79.1",
+  "version": "0.80.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": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",
@@ -176,7 +176,9 @@
     "check:package-types": "node scripts/check-no-pg-types.mjs",
     "//check:edge": "The edge-runtime gate for turbine-orm/serverless: bundles dist/serverless.js (the ESM build, which is what edge bundlers resolve) with esbuild under the edge-light/worker/browser conditions and fails on any pg-family import, any Node builtin but node:async_hooks, or any other package. Every other gate here runs on Node, which is how a static `import pg from 'pg'` in a shared module broke every edge build while CI stayed green. A CONTROL bundle under Node conditions must reach pg first, or the scan refuses to pass. Reads dist/, so it runs after `npm run build`: in prepublishOnly, and in the build job of ci.yml and the test job of release.yml.",
     "check:edge": "node scripts/check-edge-bundle.mjs",
-    "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm run test:unit && npm run test:coverage:cli && npm run check:error-codes && npm run check:error-prefix && npm run check:changelog && npm run check:cycles && npm run check:skip-gates && npm run check:private-terms && npm run check:package && npm run check:package-types && npm run check:edge && npm run size && npm run check:release-tests",
+    "//check:pg-floor": "Installs the packed tarball next to EXACTLY the floor of dependencies.pg and imports every published entry point under both import and require. CI and dev machines only ever install the newest pg in range, so the floor is otherwise never exercised: a ^8.13.1 range shipped code that read pg.utils at load time, which pg first exports in 8.15.0, and 6 of the 8 entry points failed to import on 8.13 and 8.14. Packs dist/ itself when given no tarball, so it runs after `npm run build`. Called from prepublishOnly and from the pack-smoke job of both ci.yml and release.yml.",
+    "check:pg-floor": "node scripts/check-pg-floor.mjs",
+    "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm run test:unit && npm run test:coverage:cli && npm run check:error-codes && npm run check:error-prefix && npm run check:changelog && npm run check:cycles && npm run check:skip-gates && npm run check:private-terms && npm run check:package && npm run check:package-types && npm run check:edge && npm run check:pg-floor && npm run size && npm run check:release-tests",
     "prepack": "node scripts/strip-prepare.mjs",
     "postpack": "node scripts/restore-prepare.mjs",
     "size": "size-limit",
@@ -199,7 +201,7 @@
   },
   "//dependencies": "EXACTLY ONE runtime dependency, `pg`. `@types/pg` sat here until 0.70.0 because the published declarations named `pg.Pool` / `pg.PoolClient` / `pg.QueryResult`, which makes a types-only package a hard requirement for every consumer compiling under strict (the v0.28.1 regression). The declaration surface is now pg-free (see src/pg-types.ts) and the `consumer-types` CI job proves it against the real tarball, so the types package is a devDependency. The order is one-way: clear the surface FIRST, then move the dependency.",
   "dependencies": {
-    "pg": "^8.13.1"
+    "pg": "^8.15.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",