turbine-orm 0.16.0 → 0.18.0

package/dist/cjs/realtime.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * turbine-orm — LISTEN/NOTIFY realtime pub/sub
+ *
+ * Postgres LISTEN/NOTIFY is a first-class realtime primitive that neither
+ * Prisma nor Drizzle expose ergonomically. This module backs the thin
+ * `$listen` / `$notify` methods on TurbineClient.
+ *
+ * Design — **one dedicated connection per subscription**:
+ *
+ *   Each `$listen(channel, handler)` acquires its OWN long-lived client from
+ *   the pool, runs `LISTEN "chan"`, and keeps that connection checked out for
+ *   the life of the subscription. This is the simplest correct model: each
+ *   subscription owns its lifecycle, `unsubscribe()` cleanly UNLISTENs and
+ *   releases exactly one connection, and there is no shared multiplexing
+ *   state to reason about. The trade-off is one pool slot per active channel
+ *   — for the handful of channels a typical app listens on, that's a fine
+ *   price for clarity. (A future optimization could multiplex many channels
+ *   over a single shared notification connection.)
+ *
+ * Serverless / HTTP-pool caveat:
+ *
+ *   LISTEN requires a *persistent* TCP connection that can push asynchronous
+ *   notification messages back to the client. Stateless HTTP drivers
+ *   (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(...)`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateChannel = validateChannel;
+exports.createSubscription = createSubscription;
+const errors_js_1 = require("./errors.js");
+// ---------------------------------------------------------------------------
+// Identifier validation
+// ---------------------------------------------------------------------------
+/**
+ * Strict Postgres identifier: a letter or underscore followed by letters,
+ * digits, or underscores. Channel names CANNOT be parameterized in
+ * LISTEN/UNLISTEN (`LISTEN $1` is a syntax error), so the channel is the one
+ * place an identifier is interpolated into SQL — it MUST pass this regex AND
+ * go through `quoteIdent` before reaching the SQL string.
+ */
+const CHANNEL_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Postgres NAMEDATALEN caps identifiers at 63 bytes. */
+const MAX_CHANNEL_LEN = 63;
+/**
+ * Validate a LISTEN/NOTIFY channel name. Throws ValidationError on anything
+ * that isn't a plain, reasonable-length SQL identifier. This is enforced for
+ * BOTH `$listen` (where the channel is interpolated) and `$notify` (where the
+ * channel is a bound param) — defensive parity, and it catches user typos
+ * loudly.
+ */
+function validateChannel(channel) {
+    if (typeof channel !== 'string' || channel.length === 0) {
+        throw new errors_js_1.ValidationError('[turbine] $listen/$notify channel must be a non-empty string');
+    }
+    if (channel.length > MAX_CHANNEL_LEN) {
+        throw new errors_js_1.ValidationError(`[turbine] $listen/$notify channel "${channel}" exceeds the ${MAX_CHANNEL_LEN}-character Postgres identifier limit`);
+    }
+    if (!CHANNEL_REGEX.test(channel)) {
+        throw new errors_js_1.ValidationError(`[turbine] Invalid $listen/$notify channel "${channel}" — must match /^[A-Za-z_][A-Za-z0-9_]*$/ ` +
+            '(letters, digits, underscores; cannot start with a digit)');
+    }
+}
+/**
+ * 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
+ */
+async function createSubscription(pool, channel, quotedChannel, handler, onClosed) {
+    let client;
+    try {
+        client = (await pool.connect());
+    }
+    catch (err) {
+        throw (0, errors_js_1.wrapPgError)(err);
+    }
+    // Verify the checked-out client can actually receive async notifications.
+    // Stateless HTTP drivers return a client with no `.on` — LISTEN would hang
+    // 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?.();
+        throw new errors_js_1.ConnectionError('[turbine] $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 onNotification = (msg) => {
+        // pg delivers ALL notifications for the connection to every listener; a
+        // dedicated connection only ever LISTENs on one channel, but guard anyway.
+        if (msg.channel === channel) {
+            handler(msg.payload ?? '');
+        }
+    };
+    try {
+        client.on('notification', onNotification);
+        await client.query(`LISTEN ${quotedChannel}`);
+    }
+    catch (err) {
+        client.removeListener?.('notification', onNotification);
+        client.release?.();
+        throw (0, errors_js_1.wrapPgError)(err);
+    }
+    let closed = false;
+    const sub = {
+        channel,
+        async unsubscribe() {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                await 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?.();
+                onClosed(sub);
+                throw (0, errors_js_1.wrapPgError)(err);
+            }
+            client.removeListener?.('notification', onNotification);
+            client.release?.();
+            onClosed(sub);
+        },
+        _forceRelease() {
+            if (closed)
+                return;
+            closed = true;
+            client.removeListener?.('notification', onNotification);
+            // 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);
+            onClosed(sub);
+        },
+    };
+    return sub;
+}

package/dist/cjs/schema-builder.js

@@ -27,6 +27,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.camelToSnake = exports.column = exports.ColumnBuilder = void 0;
 exports.defineSchema = defineSchema;
 exports.table = table;
+exports.applyManyToManyRelations = applyManyToManyRelations;
 /** Maps shorthand names to actual Postgres type strings */
 const TYPE_MAP = {
     serial: 'BIGSERIAL',
@@ -102,7 +103,17 @@ function defineSchema(input) {
             const raw = value;
             const columns = {};
             let pk;
+            let m2m;
             for (const [fieldName, def] of Object.entries(raw)) {
+                if (fieldName === 'manyToMany') {
+                    if (def !== undefined) {
+                        if (!Array.isArray(def)) {
+                            throw new Error(`Table "${accessor}": "manyToMany" must be an array of relation declarations`);
+                        }
+                        m2m = def;
+                    }
+                    continue;
+                }
                 if (fieldName === 'primaryKey') {
                     // Top-level composite primary key declaration
                     if (def !== undefined) {
@@ -142,6 +153,7 @@ function defineSchema(input) {
                 accessor,
                 columns,
                 ...(pk && pk.length > 0 ? { primaryKey: pk } : {}),
+                ...(m2m && m2m.length > 0 ? { manyToMany: m2m } : {}),
             };
         }
     }
@@ -303,6 +315,80 @@ function table(columns) {
     return { name: '', accessor: '', columns: built };
 }
 // ---------------------------------------------------------------------------
+// Explicit many-to-many: merge declared relations into introspected metadata
+// ---------------------------------------------------------------------------
+/**
+ * Merge the explicit `manyToMany` declarations from a code-first {@link SchemaDef}
+ * into an introspected {@link SchemaMetadata}, returning a new metadata object
+ * with the `manyToMany` {@link RelationDef}s added.
+ *
+ * This is the runtime bridge for the code-first m2m API: `defineSchema` only
+ * produces DDL, so after `introspect()`ing the live database you call this to
+ * attach the m2m relations you declared. It is PURELY ADDITIVE — existing
+ * belongsTo/hasMany/hasOne relations are preserved, and a declared relation is
+ * skipped (not overwritten) if its name already exists on the source table.
+ *
+ * @example
+ * ```ts
+ * const def = defineSchema({
+ *   posts: { id: { type: 'serial', primaryKey: true },
+ *            manyToMany: [{ name: 'tags', target: 'tags', through: 'postsTags',
+ *                           sourceKey: 'postId', targetKey: 'tagId' }] },
+ *   tags:  { id: { type: 'serial', primaryKey: true } },
+ *   postsTags: { postId: { type: 'integer', references: 'posts.id' },
+ *                tagId:  { type: 'integer', references: 'tags.id' },
+ *                primaryKey: ['postId', 'tagId'] },
+ * });
+ * let meta = await introspect({ connectionString });
+ * meta = applyManyToManyRelations(meta, def);
+ * ```
+ */
+function applyManyToManyRelations(meta, def) {
+    // Map accessor (camelCase key) → DDL snake_case table name.
+    const accessorToTable = new Map();
+    for (const [accessor, t] of Object.entries(def.tables)) {
+        accessorToTable.set(accessor, t.name);
+    }
+    const resolveTable = (accessor) => accessorToTable.get(accessor) ?? camelToSnakeLocal(accessor);
+    const resolveCols = (k) => {
+        if (Array.isArray(k))
+            return k.map(camelToSnakeLocal);
+        return camelToSnakeLocal(k);
+    };
+    // Deep-ish clone of the tables we touch so the input metadata is not mutated.
+    const tables = { ...meta.tables };
+    for (const tableDef of Object.values(def.tables)) {
+        if (!tableDef.manyToMany || tableDef.manyToMany.length === 0)
+            continue;
+        const sourceTable = tableDef.name;
+        const sourceMeta = tables[sourceTable];
+        if (!sourceMeta)
+            continue; // table not present in introspected metadata — skip
+        const relations = { ...sourceMeta.relations };
+        for (const m of tableDef.manyToMany) {
+            // Additive-only: never clobber an existing relation name.
+            if (relations[m.name])
+                continue;
+            const ref = m.references ?? 'id';
+            relations[m.name] = {
+                type: 'manyToMany',
+                name: m.name,
+                from: sourceTable,
+                to: resolveTable(m.target),
+                referenceKey: resolveCols(ref),
+                foreignKey: resolveCols(ref),
+                through: {
+                    table: resolveTable(m.through),
+                    sourceKey: resolveCols(m.sourceKey),
+                    targetKey: resolveCols(m.targetKey),
+                },
+            };
+        }
+        tables[sourceTable] = { ...sourceMeta, relations };
+    }
+    return { ...meta, tables };
+}
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 var schema_js_1 = require("./schema.js");

package/dist/cjs/schema.js

@@ -76,6 +76,16 @@ const PG_TO_TS = {
     // TSVector
     tsvector: 'string',
     tsquery: 'string',
+    // pgvector — embeddings. Mapped to `number[]` for DX (the natural shape an app
+    // passes when inserting / comparing embeddings). NOTE: like `numeric` above,
+    // there is a runtime caveat — pg has no built-in parser for the `vector` type,
+    // so over the wire a fetched vector arrives as a string literal like
+    // '[1,2,3]' unless the app registers its own parser (e.g. via pgvector's
+    // `registerType`). Turbine never auto-registers one (no side-effecting type
+    // parsers outside the client constructor). The query-side helpers (KNN
+    // orderBy, distance WHERE) always bind the query vector as a `$n::vector`
+    // param, so writing/comparing is unaffected by the read-side caveat.
+    vector: 'number[]',
 };
 const DATE_TYPES = new Set(['timestamptz', 'timestamp', 'date']);
 const PG_TO_ARRAY = {

package/dist/cjs/typed-sql.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * turbine-orm — Typed raw SQL (Turbine's answer to Prisma's TypedSQL)
+ *
+ * `client.raw()` returns untyped rows. This module adds a *typed* escape hatch:
+ * a generic tagged template where the caller supplies the row shape, and the
+ * builder yields a typed result that can be awaited as an array of rows, or
+ * narrowed to a single row (`.one()`) or a single scalar value (`.scalar()`).
+ *
+ * Design goals & guarantees:
+ *
+ *  1. **Compile-time only types.** `T` is supplied by the caller and never
+ *     validated at runtime — exactly like Prisma's TypedSQL and the existing
+ *     `raw<T>()`. Postgres still returns whatever the SQL selects; the generic
+ *     is a convenience for autocomplete and downstream type-checking.
+ *
+ *  2. **Mandatory parameterization.** Only the *static* string segments of the
+ *     template literal ever reach the SQL text. Every interpolated `${value}`
+ *     becomes a `$N` placeholder and is passed in the params array — it is
+ *     impossible to string-concatenate a value into the query through this API.
+ *     This is the whole point of the tagged-template shape: the literal segments
+ *     are frozen by the compiler (`TemplateStringsArray`), and the only way to
+ *     get a runtime value into the query is via `${...}`, which we bind.
+ *
+ *  3. **Rows are returned as-is (no snake→camel mapping).** This matches the
+ *     existing `client.raw()` behavior: a typed raw query is a literal escape
+ *     hatch, so the result columns are whatever your `SELECT` names them. Alias
+ *     columns in SQL (`SELECT created_at AS "createdAt"`) if you want camelCase.
+ *
+ * @example
+ * ```ts
+ * // Awaited directly -> rows
+ * const rows = await db.sql<{ id: number; name: string }>`
+ *   SELECT id, name FROM users WHERE org_id = ${orgId}
+ * `;
+ * //    ^? { id: number; name: string }[]
+ *
+ * // .one() -> single row or null
+ * const user = await db.sql<{ id: number; name: string }>`
+ *   SELECT id, name FROM users WHERE id = ${userId}
+ * `.one();
+ * //    ^? { id: number; name: string } | null
+ *
+ * // .scalar() -> first column of first row, or null
+ * const total = await db.sql<{ count: number }>`
+ *   SELECT COUNT(*)::int AS count FROM users WHERE org_id = ${orgId}
+ * `.scalar();
+ * //    ^? number | null
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypedSqlQuery = void 0;
+exports.buildTypedSql = buildTypedSql;
+const errors_js_1 = require("./errors.js");
+/**
+ * Build a `(sql, params)` pair from a tagged-template invocation.
+ *
+ * Each interpolated value is replaced by a positional `$N` placeholder and
+ * pushed to the params array in order. The static string segments are the only
+ * thing concatenated into the SQL text. This is the single point that
+ * guarantees parameterization for the entire typed-SQL surface.
+ *
+ * Exported for unit testing the parameterization invariant without a database.
+ */
+function buildTypedSql(strings, values) {
+    // The tagged-template API guarantees `strings.length === values.length + 1`.
+    // Guard the directly-callable (exported) surface so a mismatched call can't
+    // silently desync `$N` placeholders from params (pg would reject it, but fail
+    // loudly here instead).
+    if (strings.length !== values.length + 1) {
+        throw new errors_js_1.ValidationError(`[turbine] sql template segment/value count mismatch: ${strings.length} segments, ${values.length} values.`);
+    }
+    let sql = '';
+    for (let i = 0; i < strings.length; i++) {
+        sql += strings[i];
+        if (i < values.length) {
+            sql += `$${i + 1}`;
+        }
+    }
+    return { sql, params: values.slice() };
+}
+/**
+ * A pending typed raw SQL query. Implements the thenable contract, so it can be
+ * `await`ed directly to get `T[]`, or refined via `.one()` / `.scalar()` first.
+ *
+ * The query is executed lazily and exactly once per terminal call (`then`,
+ * `one`, `scalar`). Each terminal method runs the query independently — this is
+ * an escape hatch, not a cached query object, so don't call two terminals on
+ * the same builder expecting a single round-trip; build a fresh template each
+ * time (the common pattern is `await db.sql\`...\`` inline).
+ */
+class TypedSqlQuery {
+    pool;
+    sql;
+    params;
+    logging;
+    constructor(pool, sql, params, logging) {
+        this.pool = pool;
+        this.sql = sql;
+        this.params = params;
+        this.logging = logging;
+    }
+    /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
+    async run() {
+        if (this.logging) {
+            console.log(`[turbine] Typed SQL: ${this.sql.trim().substring(0, 120)}...`);
+        }
+        try {
+            const result = await this.pool.query(this.sql, this.params);
+            return result.rows;
+        }
+        catch (err) {
+            throw (0, errors_js_1.wrapPgError)(err);
+        }
+    }
+    /**
+     * PromiseLike implementation: `await db.sql<T>\`...\`` resolves to `T[]`.
+     */
+    // biome-ignore lint/suspicious/noThenProperty: intentional thenable — this IS the PromiseLike contract that makes `await db.sql\`...\`` resolve to rows
+    then(onfulfilled, onrejected) {
+        return this.run().then(onfulfilled, onrejected);
+    }
+    /**
+     * Execute and return the first row, or `null` if the query returns no rows.
+     * Use for queries you expect to match at most one row.
+     */
+    async one() {
+        const rows = await this.run();
+        return rows.length > 0 ? rows[0] : null;
+    }
+    /**
+     * Execute and return the first column of the first row, or `null` if there
+     * are no rows. Useful for `SELECT COUNT(*)`, `SELECT EXISTS(...)`, etc.
+     *
+     * The generic `V` defaults to the value type of `T`'s first property, but you
+     * can override it: `db.sql<{ count: number }>\`...\`.scalar<number>()`.
+     */
+    async scalar() {
+        const rows = await this.run();
+        if (rows.length === 0)
+            return null;
+        const first = rows[0];
+        const keys = Object.keys(first);
+        if (keys.length === 0)
+            return null;
+        return first[keys[0]];
+    }
+}
+exports.TypedSqlQuery = TypedSqlQuery;

package/dist/cli/studio.js

@@ -60,7 +60,11 @@ export async function startStudio(options) {
     const authToken = randomBytes(24).toString('hex');
     const stateDir = pathResolve(options.stateDir ?? '.turbine');
     const statementTimeout = options.adapter?.statementTimeout?.(30) ?? {
-        sql: `SET LOCAL statement_timeout = $1`,
+        // Postgres rejects parameters in `SET LOCAL` (`SET LOCAL ... = $1` is a
+        // syntax error). `set_config(name, value, is_local=true)` is the
+        // parameterizable, transaction-local equivalent and works on every
+        // Postgres-compatible engine.
+        sql: `SELECT set_config('statement_timeout', $1, true)`,
         params: ['30s'],
     };
     const rateLimiter = new Map();

package/dist/client.d.ts

@@ -27,7 +27,9 @@ import { type ErrorMessageMode } from './errors.js';
 import { type ObserveConfig, type ObserveHandle } from './observe.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
 import { type DeferredQuery, type QueryEventListener, QueryInterface, type QueryInterfaceOptions } from './query/index.js';
+import { type NotificationHandler, type Subscription } from './realtime.js';
 import type { SchemaMetadata } from './schema.js';
+import { TypedSqlQuery } from './typed-sql.js';
 export interface RetryOptions {
     maxAttempts?: number;
     baseDelay?: number;
@@ -172,6 +174,30 @@ export interface TransactionOptions {
     timeout?: number;
     /** Isolation level for the transaction */
     isolationLevel?: 'ReadUncommitted' | 'ReadCommitted' | 'RepeatableRead' | 'Serializable';
+    /**
+     * Transaction-local session GUCs to set after BEGIN. The canonical use case
+     * is multi-tenant Postgres row-level security (RLS): your policies filter on
+     * `current_setting('app.current_tenant')`, and you set that value here so
+     * every query inside the transaction sees it.
+     *
+     * Each entry is applied via `SELECT set_config($1, $2, true)` — `is_local=true`
+     * scopes the value to this transaction, so it auto-resets on COMMIT/ROLLBACK
+     * and never leaks onto the pooled connection. Both the name and value are
+     * bound parameters (never interpolated); the GUC name is additionally
+     * validated against a strict identifier regex.
+     *
+     * @example
+     * ```ts
+     * await db.$transaction(
+     *   async (tx) => {
+     *     // every query here sees current_setting('app.current_tenant') = '42'
+     *     return tx.invoices.findMany();
+     *   },
+     *   { sessionContext: { 'app.current_tenant': '42', 'app.current_user': userId } },
+     * );
+     * ```
+     */
+    sessionContext?: Record<string, string | number | boolean>;
 }
 /**
  * A transaction-scoped client that provides the same table accessor API as TurbineClient.
@@ -225,6 +251,8 @@ export declare class TurbineClient {
     private readonly errorMessagesSafe;
     /** True when Turbine created the pool and is responsible for tearing it down */
     private readonly ownsPool;
+    /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
+    private readonly activeSubscriptions;
     constructor(config: TurbineConfig | undefined, schema: SchemaMetadata);
     /**
      * Register a middleware function that runs before/after every query.
@@ -298,6 +326,37 @@ export declare class TurbineClient {
      * ```
      */
     raw<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    /**
+     * Execute a **typed** raw SQL query — Turbine's answer to Prisma's TypedSQL.
+     *
+     * Like {@link raw}, every interpolated `${value}` becomes a `$N` parameter
+     * (never string-concatenated), so it is injection-safe by construction. The
+     * difference is the caller-supplied row type and the chainable result: the
+     * returned {@link TypedSqlQuery} can be `await`ed directly for `T[]`, or
+     * refined with `.one()` (→ `T | null`) or `.scalar<V>()` (→ `V | null`).
+     *
+     * Rows are returned as-is — no snake→camel mapping (matching `raw()`). Alias
+     * columns in SQL if you want camelCase keys.
+     *
+     * @example
+     * ```ts
+     * // rows
+     * const rows = await db.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE org_id = ${orgId}
+     * `;
+     *
+     * // single row or null
+     * const user = await db.sql<{ id: number; name: string }>`
+     *   SELECT id, name FROM users WHERE id = ${userId}
+     * `.one();
+     *
+     * // scalar
+     * const total = await db.sql<{ count: number }>`
+     *   SELECT COUNT(*)::int AS count FROM users
+     * `.scalar();
+     * ```
+     */
+    sql<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): TypedSqlQuery<T>;
     /**
      * Execute a function within a database transaction (raw pg.PoolClient).
      * For the typed API, use `$transaction()` instead.
@@ -330,6 +389,67 @@ export declare class TurbineClient {
      * ```
      */
     $transaction<R>(fn: (tx: TransactionClient) => Promise<R>, options?: TransactionOptions): Promise<R>;
+    /**
+     * Convenience wrapper around `$transaction` for the multi-tenant / RLS case:
+     * runs `fn` inside a transaction with the given session GUCs applied via
+     * `set_config(..., is_local=true)`. Equivalent to
+     * `$transaction(fn, { sessionContext: context })`.
+     *
+     * @example
+     * ```ts
+     * const invoices = await db.$withSession(
+     *   { 'app.current_tenant': tenantId },
+     *   (tx) => tx.invoices.findMany(),
+     * );
+     * ```
+     */
+    $withSession<R>(context: Record<string, string | number | boolean>, fn: (tx: TransactionClient) => Promise<R>): Promise<R>;
+    /**
+     * Subscribe to a Postgres NOTIFY channel. The handler fires with each
+     * notification's payload string (the empty string when a payload-less
+     * NOTIFY is sent) for as long as the subscription is active.
+     *
+     * Each `$listen` checks out its OWN dedicated long-lived connection from the
+     * pool and runs `LISTEN "channel"` on it; `subscription.unsubscribe()`
+     * UNLISTENs, detaches the handler, and releases that connection. Active
+     * subscriptions are tracked and force-released on `disconnect()` so shutdown
+     * never hangs.
+     *
+     * The channel name CANNOT be a bound parameter (`LISTEN $1` is a syntax
+     * error), so it is validated against a strict identifier regex AND quoted via
+     * `quoteIdent` before interpolation — it is the only identifier this method
+     * places into SQL text.
+     *
+     * **Serverless caveat:** LISTEN needs a persistent connection that can push
+     * async notifications. Stateless HTTP drivers (Neon HTTP, Vercel Postgres)
+     * cannot do this — `$listen` throws a `ConnectionError` rather than hang.
+     * `$notify` works on every driver.
+     *
+     * @example
+     * ```ts
+     * const sub = await db.$listen('order_created', (payload) => {
+     *   const order = JSON.parse(payload);
+     *   console.log('new order', order.id);
+     * });
+     * // ...later
+     * await sub.unsubscribe();
+     * ```
+     */
+    $listen(channel: string, handler: NotificationHandler): Promise<Subscription>;
+    /**
+     * Send a Postgres NOTIFY on `channel` with an optional payload string.
+     *
+     * Issued as `SELECT pg_notify($1, $2)` — both the channel and payload are
+     * BOUND parameters (no quoting/injection concern). The channel is still
+     * validated against the identifier regex for parity with `$listen` and to
+     * catch typos loudly. Works on every driver, including serverless HTTP pools.
+     *
+     * @example
+     * ```ts
+     * await db.$notify('order_created', JSON.stringify({ id: 7 }));
+     * ```
+     */
+    $notify(channel: string, payload?: string): Promise<void>;
     /**
      * Execute an async function with automatic retry on retryable errors.
      *