turbine-orm 0.79.1 → 0.80.0

package/dist/cjs/query/writes.d.ts

@@ -44,22 +44,22 @@ export declare function coerceWriteValue(qi: BuilderCtx, key: string, value: unk
  * return rows from non-RETURNING engines. Reuses the same parameterized WHERE
  * builder as reads, so no user value is interpolated.
  */
-export declare function buildReselectByWhere(qi: BuilderCtx, whereObj: Record<string, unknown>): {
+export declare function buildReselectByWhere(qi: BuilderCtx, whereObj: Record<string, unknown>, projection?: WriteProjection): {
     sql: string;
     params: unknown[];
 };
-export declare function buildCreate<T extends object>(qi: BuilderCtx, args: CreateArgs<T>): DeferredQuery<T>;
+export declare function buildCreate<T extends object>(qi: BuilderCtx, args: CreateArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
 /**
  * Build the `'reselect'` plan for {@link buildCreate}: run the INSERT, then
  * `SELECT * WHERE pk = ?`. Returns `undefined` (skipped) unless the active
  * dialect's result strategy is `'reselect'`, so the PostgreSQL/RETURNING path
  * pays nothing. Not yet wired to a real non-RETURNING engine.
  */
-export declare function makeCreateReselect<T extends object>(qi: BuilderCtx, insertSql: string, insertParams: unknown[], data: Record<string, unknown>): DeferredQuery<T>['reselect'];
+export declare function makeCreateReselect<T extends object>(qi: BuilderCtx, insertSql: string, insertParams: unknown[], data: Record<string, unknown>, projection?: WriteProjection): DeferredQuery<T>['reselect'];
 export declare function buildCreateMany<T extends object>(qi: BuilderCtx, args: CreateManyArgs<T>): DeferredQuery<T[]>;
-export declare function buildUpdate<T extends object>(qi: BuilderCtx, args: UpdateArgs<T>): DeferredQuery<T>;
-export declare function buildDelete<T extends object>(qi: BuilderCtx, args: DeleteArgs<T>): DeferredQuery<T>;
-export declare function buildUpsert<T extends object>(qi: BuilderCtx, args: UpsertArgs<T>): DeferredQuery<T>;
+export declare function buildUpdate<T extends object>(qi: BuilderCtx, args: UpdateArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
+export declare function buildDelete<T extends object>(qi: BuilderCtx, args: DeleteArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
+export declare function buildUpsert<T extends object>(qi: BuilderCtx, args: UpsertArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
 export declare function buildUpdateMany<T extends object>(qi: BuilderCtx, args: UpdateManyArgs<T>): DeferredQuery<{
     count: number;
 }>;
@@ -83,6 +83,36 @@ export declare function piiColumns(_qi: BuilderCtx, meta: TableMetadata): Set<st
  * exclusion; you may still write PII fields freely).
  */
 export declare function piiFields(_qi: BuilderCtx, meta: TableMetadata): string[];
+/**
+ * A single-row write's caller-chosen return shape, from its `select` / `omit`.
+ *
+ * Resolved ONCE per call by builder.ts through `resolveProjection`, the same
+ * authority reads use, so a write and a read agree on every rule: a name must
+ * resolve to a column or the call throws E003, a relation name gets its own
+ * message, `select` must name something, `select` and `omit` are exclusive, the
+ * list is in TABLE order (a caller's key order must not mint distinct
+ * statements), and an explicit `select` of a PII column is the opt-in that
+ * returns it while `omit` leaves PII excluded. (builder.ts rather than this
+ * module because relations.ts already imports this one.)
+ *
+ * The point is bytes: `RETURNING *` sends back every column, a large JSON
+ * payload included, on every insert. Measured with a 3.1 KB jsonb column at
+ * concurrency 50, the same INSERT ran at 60,900/s with no RETURNING and at
+ * 34,500/s with `RETURNING *`.
+ */
+export interface WriteProjection {
+    /** Unquoted column names, in table order. Never empty. */
+    readonly columns: readonly string[];
+}
+/**
+ * The write-SQL cache segment for a projection. EMPTY for the default shape, so
+ * every existing key is byte-identical; a projected statement differs only in
+ * its RETURNING/OUTPUT text, and without this segment two calls with the same
+ * SET and WHERE but different `select`s would share one cached statement, i.e.
+ * the second caller would get the first caller's columns. NUL is the delimiter
+ * because it is the one byte a PostgreSQL identifier cannot contain.
+ */
+export declare function writeProjectionCacheSegment(projection: WriteProjection | undefined): string;
 /**
  * The `RETURNING` / `OUTPUT` selection for a write on this table. A table with
  * no PII column returns `'*'` (every column, byte-identical SQL to before);
@@ -119,13 +149,13 @@ export declare function piiFields(_qi: BuilderCtx, meta: TableMetadata): string[
  * time (`SET "updated_at" = $1, "updated_at" = $2`, PostgreSQL 42701).
  */
 export declare function applyUpdatedAtColumns(qi: BuilderCtx, data: Record<string, unknown>): Record<string, unknown>;
-export declare function writeReturningColumns(qi: BuilderCtx): ReturningSelection;
+export declare function writeReturningColumns(qi: BuilderCtx, projection?: WriteProjection): ReturningSelection;
 /**
  * String form of {@link writeReturningColumns} for a `SELECT` list (the
  * `'reselect'` result strategy re-fetches via a SELECT, not RETURNING).
  * `'*'` when there is no PII column; otherwise the comma-joined quoted list.
  */
-export declare function writeReselectSelection(qi: BuilderCtx): string;
+export declare function writeReselectSelection(qi: BuilderCtx, projection?: WriteProjection): string;
 /**
  * Parse a write's returned row (create/update/upsert/delete), then strip the
  * table's PII fields: the write-side read policy. On PII-tagged tables the
@@ -134,7 +164,7 @@ export declare function writeReselectSelection(qi: BuilderCtx): string;
  * no-op. Untagged tables incur only one `for` over a zero-length field list,
  * so behavior is unchanged.
  */
-export declare function parseWriteRow(qi: BuilderCtx, row: Record<string, unknown>): Record<string, unknown>;
+export declare function parseWriteRow(qi: BuilderCtx, row: Record<string, unknown>, projection?: WriteProjection): Record<string, unknown>;
 /**
  * Reject any write against a view (H4). Views are introspected with
  * `isView: true` and are read-only in every engine; a write raises a

package/dist/cjs/query/writes.js

@@ -57,6 +57,7 @@ exports.buildUpdateMany = buildUpdateMany;
 exports.buildDeleteMany = buildDeleteMany;
 exports.piiColumns = piiColumns;
 exports.piiFields = piiFields;
+exports.writeProjectionCacheSegment = writeProjectionCacheSegment;
 exports.applyUpdatedAtColumns = applyUpdatedAtColumns;
 exports.writeReturningColumns = writeReturningColumns;
 exports.writeReselectSelection = writeReselectSelection;
@@ -133,11 +134,11 @@ function utcDateTimeWrites(qi) {
  * return rows from non-RETURNING engines. Reuses the same parameterized WHERE
  * builder as reads, so no user value is interpolated.
  */
-function buildReselectByWhere(qi, whereObj) {
+function buildReselectByWhere(qi, whereObj, projection) {
     const params = [];
     const clause = whereMod.buildWhereClause(qi, whereObj, params);
     const where = clause ? ` WHERE ${clause}` : '';
-    return { sql: `SELECT ${writeReselectSelection(qi)} FROM ${qi.q(qi.table)}${where}`, params };
+    return { sql: `SELECT ${writeReselectSelection(qi, projection)} FROM ${qi.q(qi.table)}${where}`, params };
 }
 /**
  * Build the all-defaults INSERT for a `data` that names no column, via the
@@ -157,7 +158,7 @@ function buildReselectByWhere(qi, whereObj) {
  * A dialect predating the hook raises E017 rather than emitting SQL its engine
  * will reject.
  */
-function buildDefaultValuesInsert(qi, rowCount, skipDuplicates) {
+function buildDefaultValuesInsert(qi, rowCount, skipDuplicates, projection) {
     const build = qi.dialect.buildDefaultValuesInsertStatement;
     if (!build) {
         throw new errors_js_1.UnsupportedFeatureError('create/createMany with an empty data object', qi.dialect.name, 'This dialect has no all-defaults INSERT form; name at least one column in `data`.');
@@ -166,10 +167,10 @@ function buildDefaultValuesInsert(qi, rowCount, skipDuplicates) {
         table: qi.q(qi.table),
         rowCount,
         skipDuplicates,
-        returning: writeReturningColumns(qi),
+        returning: writeReturningColumns(qi, projection),
     });
 }
-function buildCreate(qi, args) {
+function buildCreate(qi, args, projection) {
     assertWritable(qi, 'create');
     assertNoGeneratedColumns(qi, args.data, 'create');
     const entries = writeEntries(qi, args.data);
@@ -179,12 +180,12 @@ function buildCreate(qi, args) {
     const placeholders = entries.map(([k], i) => `${qi.p(i + 1)}${whereMod.enumCastSuffix(qi, qi.toColumn(k))}`);
     // `data: {}` (or all-undefined) names no column: insert a row of defaults.
     const sql = entries.length === 0
-        ? buildDefaultValuesInsert(qi, 1)
+        ? buildDefaultValuesInsert(qi, 1, undefined, projection)
         : qi.dialect.buildInsertStatement({
             table: qi.q(qi.table),
             columns,
             valuePlaceholders: placeholders,
-            returning: writeReturningColumns(qi),
+            returning: writeReturningColumns(qi, projection),
         });
     return {
         sql,
@@ -198,12 +199,12 @@ function buildCreate(qi, args) {
                     message: `create on "${qi.table}" returned no row from RETURNING *; this should never happen.`,
                 });
             }
-            return parseWriteRow(qi, row);
+            return parseWriteRow(qi, row, projection);
         },
         tag: `${qi.table}.create`,
         // Non-RETURNING engines: INSERT, then re-fetch the new row by primary key
         // (provided value, else the driver's generated insert id).
-        reselect: makeCreateReselect(qi, sql, params, args.data),
+        reselect: makeCreateReselect(qi, sql, params, args.data, projection),
     };
 }
 /**
@@ -212,7 +213,7 @@ function buildCreate(qi, args) {
  * dialect's result strategy is `'reselect'`, so the PostgreSQL/RETURNING path
  * pays nothing. Not yet wired to a real non-RETURNING engine.
  */
-function makeCreateReselect(qi, insertSql, insertParams, data) {
+function makeCreateReselect(qi, insertSql, insertParams, data, projection) {
     if (qi.dialect.resultStrategy !== 'reselect')
         return undefined;
     return async (exec) => {
@@ -229,7 +230,7 @@ function makeCreateReselect(qi, insertSql, insertParams, data) {
             conds.push(`${qi.q(pk)} = ${qi.p(idx++)}`);
         }
         const where = conds.length > 0 ? ` WHERE ${conds.join(' AND ')}` : '';
-        return exec(`SELECT ${writeReselectSelection(qi)} FROM ${qi.q(qi.table)}${where}`, selParams);
+        return exec(`SELECT ${writeReselectSelection(qi, projection)} FROM ${qi.q(qi.table)}${where}`, selParams);
     };
 }
 /**
@@ -388,7 +389,7 @@ function buildCreateMany(qi, args) {
         tag: `${qi.table}.createMany`,
     };
 }
-function buildUpdate(qi, args) {
+function buildUpdate(qi, args, projection) {
     assertWritable(qi, 'update');
     qi.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
     // `updatedAt`-tagged columns are filled in before anything reads `data`, so
@@ -431,7 +432,7 @@ function buildUpdate(qi, args) {
     // version check that must still run.
     const hasSetData = Object.values(dataObj).some((v) => v !== undefined);
     if (!hasSetData && !lock) {
-        const sel = buildReselectByWhere(qi, whereObj);
+        const sel = buildReselectByWhere(qi, whereObj, projection);
         return {
             sql: sel.sql,
             params: sel.params,
@@ -439,14 +440,16 @@ function buildUpdate(qi, args) {
                 const row = result.rows[0];
                 if (!row)
                     throw new errors_js_1.NotFoundError({ table: qi.table, where: args.where, operation: 'update' });
-                return parseWriteRow(qi, row);
+                return parseWriteRow(qi, row, projection);
             },
             tag: `${qi.table}.update`,
         };
     }
     const setFp = fingerprintSet(qi, dataObj);
     const whereFp = whereMod.fingerprintWhere(qi, whereObj);
-    const ck = lock ? null : `u:${setFp}|${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;
+    const ck = lock
+        ? null
+        : `u:${setFp}|${whereFp}${whereMod.globalFilterCacheSegment(qi)}${writeProjectionCacheSegment(projection)}`;
     const params = [];
     const buildSql = (freshParams) => {
         const setEntries = writeEntries(qi, dataObj);
@@ -467,7 +470,7 @@ function buildUpdate(qi, args) {
         // `OUTPUT INSERTED.*` between SET and WHERE) override buildUpdateStatement;
         // absent → the trailing-clause PG/SQLite/MySQL form (byte-identical).
         // `returning` excludes PII columns on tagged tables (else '*').
-        const returning = writeReturningColumns(qi);
+        const returning = writeReturningColumns(qi, projection);
         return qi.dialect.buildUpdateStatement
             ? qi.dialect.buildUpdateStatement({ table: qi.q(qi.table), setClauses, whereSql, returning })
             : `UPDATE ${qi.q(qi.table)} SET ${setClauses.join(', ')}${whereSql}${qi.dialect.buildReturningClause(returning)}`;
@@ -512,7 +515,7 @@ function buildUpdate(qi, args) {
                     operation: 'update',
                 });
             }
-            return parseWriteRow(qi, row);
+            return parseWriteRow(qi, row, projection);
         },
         tag: `${qi.table}.update`,
         preparedName,
@@ -532,13 +535,13 @@ function buildUpdate(qi, args) {
                         expectedVersion: lock.expected,
                     });
                 }
-                const sel = buildReselectByWhere(qi, whereObj);
+                const sel = buildReselectByWhere(qi, whereObj, projection);
                 return exec(sel.sql, sel.params);
             }
             : undefined,
     };
 }
-function buildDelete(qi, args) {
+function buildDelete(qi, args, projection) {
     assertWritable(qi, 'delete');
     qi.currentSkip = (0, types_js_1.resolveSkipGlobalFilters)(args.skipGlobalFilters);
     // Prisma compound-unique selector → the column conjunction (before the guard).
@@ -552,7 +555,7 @@ function buildDelete(qi, args) {
         (0, compound_unique_js_1.assertMutationWhereIdentifiesOneRow)(qi.tableMeta, qi.table, userWhere, 'delete');
     const whereObj = (whereMod.mergeGlobalFilter(qi, userWhere) ?? {});
     const whereFp = whereMod.fingerprintWhere(qi, whereObj);
-    const ck = `d:${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;
+    const ck = `d:${whereFp}${whereMod.globalFilterCacheSegment(qi)}${writeProjectionCacheSegment(projection)}`;
     const params = [];
     const buildSql = (freshParams) => {
         const clause = whereMod.buildWhereClause(qi, whereObj, freshParams);
@@ -560,7 +563,7 @@ function buildDelete(qi, args) {
         // SQL Server injects `OUTPUT DELETED.*` between `DELETE FROM <t>` and WHERE;
         // absent override → the trailing-clause PG/SQLite/MySQL form (byte-identical).
         // `returning` excludes PII columns on tagged tables (else '*').
-        const returning = writeReturningColumns(qi);
+        const returning = writeReturningColumns(qi, projection);
         return qi.dialect.buildDeleteStatement
             ? qi.dialect.buildDeleteStatement({ table: qi.q(qi.table), whereSql, returning })
             : `DELETE FROM ${qi.q(qi.table)}${whereSql}${qi.dialect.buildReturningClause(returning)}`;
@@ -580,7 +583,7 @@ function buildDelete(qi, args) {
                     operation: 'delete',
                 });
             }
-            return parseWriteRow(qi, row);
+            return parseWriteRow(qi, row, projection);
         },
         tag: `${qi.table}.delete`,
         preparedName: entry.name,
@@ -588,7 +591,7 @@ function buildDelete(qi, args) {
         // by the same where, then run the DELETE, returning the captured row.
         reselect: qi.dialect.resultStrategy === 'reselect'
             ? async (exec) => {
-                const sel = buildReselectByWhere(qi, whereObj);
+                const sel = buildReselectByWhere(qi, whereObj, projection);
                 const pre = await exec(sel.sql, sel.params);
                 await exec(entry.sql, params, entry.name);
                 return pre;
@@ -596,7 +599,7 @@ function buildDelete(qi, args) {
             : undefined,
     };
 }
-function buildUpsert(qi, args) {
+function buildUpsert(qi, args, projection) {
     assertWritable(qi, 'upsert');
     assertNoGeneratedColumns(qi, args.create, 'upsert');
     assertNoGeneratedColumns(qi, args.update, 'upsert');
@@ -652,8 +655,23 @@ function buildUpsert(qi, args) {
     // unqualified column is ambiguous and PostgreSQL rejected EVERY upsert on a
     // globally filtered table at parse time (42702), insert path included.
     let updateWhere;
+    const upsertFilter = whereMod.resolveGlobalFilter(qi, qi.table);
+    if (upsertFilter && !qi.dialect.supportsUpsertUpdateWhere) {
+        // MySQL's `ON DUPLICATE KEY UPDATE` has no predicate slot and SQL Server's
+        // MERGE cannot take the builder's column references there, so on those
+        // engines the filter used to be DROPPED from the conflict update, silently.
+        // A tenant-scoped upsert whose key matched another tenant's row updated
+        // that row. Refused instead, when the filter would compile to anything:
+        // the global-filter contract is that it scopes every update, and an
+        // upsert that cannot honour it must not run as if it did.
+        if (whereMod.buildRenderedRefWhere(qi, qi.table, qi.tableMeta, qi.q(qi.table), upsertFilter, [])) {
+            throw new errors_js_1.UnsupportedFeatureError(`upsert on "${qi.table}", which has a global filter,`, qi.dialect.name, "This engine's upsert statement cannot carry the filter on its conflict update, so it could update a row " +
+                'the filter hides. Use findUnique, then update or create, inside $transaction; or pass ' +
+                '`skipGlobalFilters: UNSAFE` if the upsert is meant to reach every row.');
+        }
+    }
     if (qi.dialect.supportsUpsertUpdateWhere) {
-        const gf = whereMod.resolveGlobalFilter(qi, qi.table);
+        const gf = upsertFilter;
         if (gf) {
             // Compiled through a scope whose FROM-item reference is ALREADY RENDERED
             // (`"users"`), which is what the target table is inside `ON CONFLICT ...
@@ -678,7 +696,7 @@ function buildUpsert(qi, args) {
         conflictColumns,
         updateSetClauses: setClauses,
         updateWhere,
-        returning: writeReturningColumns(qi),
+        returning: writeReturningColumns(qi, projection),
     });
     return {
         sql,
@@ -703,14 +721,14 @@ function buildUpsert(qi, args) {
                         : `upsert on "${qi.table}" returned no row from RETURNING *; this should never happen.`,
                 });
             }
-            return parseWriteRow(qi, row);
+            return parseWriteRow(qi, row, projection);
         },
         tag: `${qi.table}.upsert`,
         // Non-RETURNING engines: run the upsert, then re-fetch by the where keys.
         reselect: qi.dialect.resultStrategy === 'reselect'
             ? async (exec) => {
                 await exec(sql, params);
-                const sel = buildReselectByWhere(qi, (whereMod.mergeGlobalFilter(qi, upsertWhere) ?? {}));
+                const sel = buildReselectByWhere(qi, (whereMod.mergeGlobalFilter(qi, upsertWhere) ?? {}), projection);
                 return exec(sel.sql, sel.params);
             }
             : undefined,
@@ -859,6 +877,17 @@ function piiFields(_qi, meta) {
     }
     return out;
 }
+/**
+ * The write-SQL cache segment for a projection. EMPTY for the default shape, so
+ * every existing key is byte-identical; a projected statement differs only in
+ * its RETURNING/OUTPUT text, and without this segment two calls with the same
+ * SET and WHERE but different `select`s would share one cached statement, i.e.
+ * the second caller would get the first caller's columns. NUL is the delimiter
+ * because it is the one byte a PostgreSQL identifier cannot contain.
+ */
+function writeProjectionCacheSegment(projection) {
+    return projection ? `|rt=${projection.columns.join('\u0000')}` : '';
+}
 /**
  * The `RETURNING` / `OUTPUT` selection for a write on this table. A table with
  * no PII column returns `'*'` (every column, byte-identical SQL to before);
@@ -925,7 +954,9 @@ function namedColumns(meta, data) {
     }
     return out;
 }
-function writeReturningColumns(qi) {
+function writeReturningColumns(qi, projection) {
+    if (projection)
+        return projection.columns.map((col) => qi.q(col));
     // The PK exemption used to be re-stated here as `|| pk.has(col)`. It now
     // lives in `piiColumns` so every projection inherits it and none can drift.
     const piiCols = piiColumns(qi, qi.tableMeta);
@@ -938,8 +969,8 @@ function writeReturningColumns(qi) {
  * `'reselect'` result strategy re-fetches via a SELECT, not RETURNING).
  * `'*'` when there is no PII column; otherwise the comma-joined quoted list.
  */
-function writeReselectSelection(qi) {
-    const cols = writeReturningColumns(qi);
+function writeReselectSelection(qi, projection) {
+    const cols = writeReturningColumns(qi, projection);
     return cols === '*' ? '*' : cols.join(', ');
 }
 /**
@@ -950,10 +981,17 @@ function writeReselectSelection(qi) {
  * no-op. Untagged tables incur only one `for` over a zero-length field list,
  * so behavior is unchanged.
  */
-function parseWriteRow(qi, row) {
+function parseWriteRow(qi, row, projection) {
     const parsed = qi.parseRow(row, qi.table);
-    for (const field of piiFields(qi, qi.tableMeta)) {
-        delete parsed[field];
+    // A column the caller named in `select` is the opt-in (see WriteProjection),
+    // so the strip spares exactly the projected columns and nothing else.
+    const pii = piiColumns(qi, qi.tableMeta);
+    if (pii.size === 0)
+        return parsed;
+    const requested = projection ? new Set(projection.columns) : undefined;
+    for (const col of qi.tableMeta.columns) {
+        if (pii.has(col.name) && !requested?.has(col.name))
+            delete parsed[col.field];
     }
     return parsed;
 }

package/dist/cjs/realtime.d.ts

@@ -24,6 +24,18 @@
  *   (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 type { PgCompatPool } from './client.js';
 /**
@@ -36,6 +48,34 @@ import type { PgCompatPool } from './client.js';
 export declare function validateChannel(channel: string): void;
 /** Handler invoked with the raw NOTIFY payload string (empty string if none). */
 export type NotificationHandler = (payload: string) => void;
+/** Backoff for re-establishing a subscription whose connection was lost. */
+export interface ListenReconnectOptions {
+    /** Delay before the first reconnect attempt. Default 100 ms. */
+    initialDelayMs?: number;
+    /** Ceiling for the doubling delay between attempts. Default 30,000 ms. */
+    maxDelayMs?: number;
+}
+/** Options for `$listen`. */
+export interface ListenOptions {
+    /**
+     * Re-establish the subscription after its connection is lost (a restart,
+     * failover, compute suspend, `pg_terminate_backend`). Default `true`. With
+     * `false` the subscription ends at the first loss, after `onError`.
+     */
+    reconnect?: boolean | ListenReconnectOptions;
+    /**
+     * Called when the connection is lost and after each failed reconnect
+     * attempt. Defaults to one `console.error` line per event. The subscription
+     * keeps retrying unless `reconnect` is `false`; call `unsubscribe()` to stop.
+     */
+    onError?: (err: Error) => void;
+    /**
+     * Called once `LISTEN` is active again on a fresh connection. Notifications
+     * sent while the subscription was disconnected were NOT delivered and never
+     * will be, so this is where to resynchronise from the source of truth.
+     */
+    onReconnect?: () => void;
+}
 /**
  * A live LISTEN subscription. Call `unsubscribe()` to UNLISTEN, detach the
  * handler, and release the dedicated connection back to the pool.
@@ -46,6 +86,7 @@ export interface Subscription {
     /**
      * Stop listening: runs `UNLISTEN "chan"`, removes the notification listener,
      * and releases the dedicated connection. Idempotent, safe to call twice.
+     * Also cancels a pending reconnect.
      */
     unsubscribe(): Promise<void>;
 }
@@ -59,12 +100,15 @@ export interface ActiveSubscription extends Subscription {
 }
 /**
  * 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 releases, so the client can
+ * @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 declare function createSubscription(pool: PgCompatPool, channel: string, quotedChannel: string, handler: NotificationHandler, onClosed: (sub: ActiveSubscription) => void): Promise<ActiveSubscription>;
+export declare function createSubscription(pool: PgCompatPool, channel: string, quotedChannel: string, handler: NotificationHandler, onClosed: (sub: ActiveSubscription) => void, options?: ListenOptions): Promise<ActiveSubscription>;