turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/client.d.ts

@@ -0,0 +1,837 @@
+/**
+ * turbine-orm — TurbineClient
+ *
+ * The main entry point for the Turbine TypeScript SDK.
+ * Manages connection pooling and provides typed table accessors.
+ *
+ * Schema-driven: call `table<T>(name)` to get a QueryInterface for any
+ * table in the introspected schema. Generated clients extend this with
+ * typed properties (e.g. `db.users`, `db.posts`).
+ *
+ * @example
+ * ```ts
+ * // With generated client (recommended):
+ * import { turbine } from './generated/turbine';
+ * const db = turbine({ connectionString: process.env.DATABASE_URL });
+ * const user = await db.users.findUnique({ where: { id: 1 } });
+ *
+ * // With base client (dynamic):
+ * import { TurbineClient } from 'turbine-orm';
+ * const db = new TurbineClient({ connectionString: '...' }, schema);
+ * const users = db.table<User>('users');
+ * ```
+ */
+import pg from 'pg';
+import { type Dialect } from './dialect.js';
+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 GlobalFilters, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy } 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;
+    maxDelay?: number;
+    onRetry?: (error: unknown, attempt: number) => void;
+}
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Minimal pg-compatible query result.
+ * `pg.Pool`, `@neondatabase/serverless` Pool, `@vercel/postgres` Pool and
+ * any driver speaking the node-postgres API all satisfy this shape.
+ */
+export interface PgCompatQueryResult<R = Record<string, unknown>> {
+    rows: R[];
+    rowCount: number | null;
+    fields?: Array<{
+        name: string;
+        dataTypeID: number;
+    }>;
+}
+/**
+ * Minimal pg-compatible client used by TurbineClient for transactions.
+ * `pg.PoolClient` satisfies this; so do Neon and Vercel's equivalents.
+ */
+export interface PgCompatPoolClient {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<PgCompatQueryResult<R>>;
+    release(err?: Error | boolean): void;
+    /**
+     * Optional driver capability: `true` when `query()` may be called again on
+     * this connection while earlier calls are still in flight, with replies
+     * delivered to callers in FIFO submission order. Drivers that set this let
+     * the batch `$transaction([...])` overload dispatch every statement in one
+     * write burst (~1 network round trip plus server time) instead of awaiting
+     * each reply before sending the next (N round trips). Leave unset for
+     * drivers (node-postgres included) whose batch path must stay strictly
+     * sequential.
+     */
+    readonly supportsPipelining?: boolean;
+    /**
+     * Optional engine seam: scope a transaction's user callback to its own
+     * async subtree. When present, `TurbineClient.transaction` / `$transaction`
+     * invoke the callback as `wrapTransactionCallback(() => fn(tx))` instead of
+     * `fn(tx)` directly. Single-writer engines (PowDB) implement it with
+     * `AsyncLocalStorage.run()` to plant their re-entrancy marker so that it
+     * exists ONLY inside the callback's async subtree: a transaction opened
+     * from inside the callback is detected as re-entrant (typed E017), while
+     * the CALLER's context stays unmarked, so same-tick sibling transactions
+     * queue FIFO instead of being falsely flagged. Absent on pg and every other
+     * engine, in which case the callback runs unwrapped (zero behavior change).
+     */
+    wrapTransactionCallback?<R>(fn: () => Promise<R>): Promise<R>;
+}
+/**
+ * Minimal pg-compatible pool. Pass any driver that satisfies this interface
+ * via `TurbineConfig.pool` — lets Turbine run on Neon HTTP, Vercel Postgres,
+ * Cloudflare Hyperdrive, or any other serverless Postgres driver.
+ *
+ * @example
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { TurbineClient } from 'turbine-orm';
+ *
+ * const neonPool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = new TurbineClient({ pool: neonPool }, schema);
+ * ```
+ */
+export interface PgCompatPool {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<PgCompatQueryResult<R>>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+    /** Optional — pools that expose stats (pg.Pool does; Neon HTTP does not) */
+    readonly totalCount?: number;
+    readonly idleCount?: number;
+    readonly waitingCount?: number;
+    /** Optional — pg.Pool supports 'error' event; HTTP drivers typically do not */
+    on?(event: 'error', listener: (err: Error) => void): this;
+}
+/**
+ * Driver-neutral seam. Bundles a pg-compatible connection pool with the SQL
+ * {@link Dialect} that owns every piece of SQL text varying across engines —
+ * parameter placeholders, transaction-control keywords (BEGIN/COMMIT/ROLLBACK/
+ * SAVEPOINT/isolation/set_config), streaming, and capability flags.
+ *
+ * This is the structural boundary that keeps hard-coded Postgres SQL out of
+ * `client.ts`: the pool provides connect/query/transaction/close, the dialect
+ * provides every literal keyword and the placeholder syntax. A future MySQL /
+ * SQLite engine ships a `{ pool, dialect }` pair instead of a raw `pg.Pool`,
+ * exactly as `turbineHttp` ships a serverless pool today.
+ */
+export interface TurbineDriver {
+    /** The underlying pg-compatible connection pool (connect/query/transaction/close). */
+    readonly pool: PgCompatPool;
+    /** SQL dialect: placeholders, transaction keywords, session-config, capability flags. */
+    readonly dialect: Dialect;
+}
+export interface TurbineConfig {
+    /**
+     * An external pg-compatible pool. Use this to plug in serverless drivers
+     * like `@neondatabase/serverless`, `@vercel/postgres`, or any other pg-API
+     * compatible pool. When provided, all connection-string fields are ignored
+     * and Turbine will NOT create its own pg.Pool.
+     */
+    pool?: PgCompatPool;
+    /** Postgres connection string (e.g. postgres://user:pass@host:5432/db) */
+    connectionString?: string;
+    /** Host (used if connectionString is not set) */
+    host?: string;
+    /** Port (default: 5432) */
+    port?: number;
+    /** Database name */
+    database?: string;
+    /** Username */
+    user?: string;
+    /** Password */
+    password?: string;
+    /** SSL/TLS options for the connection (required for most cloud providers) */
+    ssl?: boolean | {
+        rejectUnauthorized?: boolean;
+        ca?: string;
+        key?: string;
+        cert?: string;
+    };
+    /** Maximum number of connections in the pool (default: 10) */
+    poolSize?: number;
+    /** Idle timeout in ms before a connection is closed (default: 30000) */
+    idleTimeoutMs?: number;
+    /** Connection timeout in ms (default: 5000) */
+    connectionTimeoutMs?: number;
+    /** pg-style alias for {@link poolSize}; the explicit field wins when both are set. */
+    max?: number;
+    /** pg-style alias for {@link idleTimeoutMs}; the explicit field wins when both are set. */
+    idleTimeoutMillis?: number;
+    /** pg-style alias for {@link connectionTimeoutMs}; the explicit field wins when both are set. */
+    connectionTimeoutMillis?: number;
+    /** Enable query logging to console (default: false) */
+    logging?: boolean;
+    /** Default LIMIT applied to findMany() when no limit is specified (opt-in, default: undefined) */
+    defaultLimit?: number;
+    /**
+     * Log a warning when findMany() is called without a limit (default: false).
+     * Pass a per-table map (`{ users: false }`) to override the default for
+     * specific tables; per-call `warnOnUnlimited` on findMany args wins over both.
+     */
+    warnOnUnlimited?: boolean | Record<string, boolean>;
+    /**
+     * Interpret Postgres `timestamp` (without time zone) values as UTC — both
+     * at the driver level (OID 1114 type parser, registered only when Turbine
+     * owns the pool) and when coercing nested-relation JSON dates. This is the
+     * Prisma/Rails/Django convention and makes results independent of the
+     * server's local time zone. Default: `true`. Set `false` for the legacy
+     * local-time interpretation.
+     */
+    utcTimestamps?: boolean;
+    /**
+     * Default strategy for resolving `with`-clause relations, applied to every
+     * `findMany`/`findUnique`/`findFirst` unless overridden per query.
+     *
+     *   - `'join'`: one SQL statement using correlated
+     *     `json_agg(json_build_object(...))` subqueries. On PowDB, `'join'` opts
+     *     into native server-side joins where eligible instead.
+     *   - `'batched'`: run the base query, then one flat follow-up query per
+     *     relation (`WHERE fk = ANY($1)`), stitching children client-side. Wins
+     *     when child FK columns are unindexed or result sets are large.
+     *   - `'auto'` (the SQL-engine default since 0.41): per relation, use `'join'`
+     *     unless the introspected metadata PROVES the probe columns are unindexed,
+     *     in which case that relation falls back to the batched loader. Needs
+     *     DB-backed index metadata (a generated / introspected client); a
+     *     code-first `defineSchema`-only client behaves exactly like `'join'`.
+     *     Output shape is identical to `'join'`. See {@link RelationLoadStrategy}.
+     *
+     * Precedence: per-query `relationLoadStrategy` arg > this config > the engine
+     * default. On SQL engines the default is `'auto'`; on PowDB the default is the
+     * batched loaders (an ineligible relation falls back to them silently even
+     * under `'join'`; `'auto'` resolves to PowDB's own default).
+     */
+    relationLoadStrategy?: RelationLoadStrategy;
+    /**
+     * When `true`, every to-many `with` relation with no explicit `orderBy` is
+     * loaded ordered by the target table's primary key ascending, so unordered
+     * child arrays come back deterministically (json_agg / the batched loaders
+     * otherwise leave that order engine-dependent, and `'auto'` fallback can change
+     * it). An explicit per-relation `orderBy` always wins; a per-query
+     * `stableRelationOrder` overrides this. Default `false` (SQL is byte-identical
+     * when off). SQL engines only. See {@link RelationLoadStrategy}.
+     */
+    stableRelationOrder?: boolean;
+    /**
+     * When `true`, a `findMany` that paginates (`limit` / `take` / `offset`) but
+     * declares no `orderBy` is ordered by the table's primary key ascending
+     * (every column of a composite PK, in declaration order). An unordered
+     * `LIMIT` is non-deterministic: the same query can return different rows once
+     * the heap changes underneath it, so a row may appear on two pages or on
+     * none. An explicit `orderBy` always wins, PK-less tables are left alone, and
+     * `distinct` / `cursor` shapes are skipped.
+     *
+     * Default `false` in core, because switching it on would add an `ORDER BY` to
+     * SQL that existing applications already emit, changing both the rows a page
+     * returns and the plan the engine picks: a silent behavior change that waits
+     * for a major. `turbine-orm/prisma-compat` defaults it ON instead, since
+     * reproducing Prisma's semantics is that layer's contract. With it off the
+     * emitted SQL is byte-identical to before, and a dev-mode warning points at
+     * the affected queries.
+     */
+    implicitPkOrdering?: boolean;
+    /**
+     * Parent-row ceiling for the `relationLoadStrategy: 'auto'` to-one rule: a
+     * to-one relation stays in the single-statement join when the query's `limit`
+     * bounds the parent set at or under this many rows, and loads batched when the
+     * query is unbounded or bounded above it. Defaults to 1000 (see
+     * `AUTO_TO_ONE_JOIN_MAX_ROWS`). Only consulted under `'auto'`.
+     */
+    autoToOneJoinMaxRows?: number;
+    /**
+     * Round-trip time to the database, in milliseconds, used to DERIVE the
+     * `relationLoadStrategy: 'auto'` to-one threshold instead of guessing a row
+     * count. Prefer this over `autoToOneJoinMaxRows`: the break-even between the
+     * single-statement join and the batched follow-up is
+     * `roundTripMs / AUTO_JOIN_PENALTY_MS_PER_ROW`, and measurement shows the
+     * per-row penalty is a constant of the plan while the break-even moves ~17x
+     * between a loopback link and a 2.7ms one. Set it to what `ping` says (a
+     * Unix socket is ~0.05, same-region managed Postgres ~0.5-2, cross-region
+     * ~30-60). Defaults to `AUTO_ASSUMED_ROUND_TRIP_MS` (0.7ms, same-region),
+     * which reproduces the historical 1000-row threshold exactly. Overridden by
+     * an explicit `autoToOneJoinMaxRows`; only consulted under `'auto'`.
+     */
+    autoRoundTripMs?: number;
+    /**
+     * How nested-relation subqueries encode each row's JSON.
+     *
+     *   - `'object'` (default) — `json_agg(json_build_object('key', v, …))`. Every
+     *     key name is repeated in every nested object of every row.
+     *   - `'positional'` — `json_agg(json_build_array(v, …))`. Turbine knows the
+     *     column order at build time, so it emits a key-less array and maps
+     *     positions back to keys client-side. Same information, a fraction of the
+     *     bytes on wide/deeply-nested `with` trees. Parsed output is byte-identical
+     *     to `'object'`.
+     *
+     * Postgres-only in v1: setting `'positional'` on a non-Postgres engine throws
+     * `UnsupportedFeatureError` (E017) when a `with` clause is present. Default:
+     * `'object'` (today's behavior, byte-unchanged).
+     */
+    jsonEncoding?: 'object' | 'positional';
+    /**
+     * Controls how `NotFoundError` (and other where-aware errors) format their
+     * messages.
+     *
+     *   - `'safe'`    (default): the message includes only the keys of the where
+     *     clause (e.g. `where: { id, email }`). Values are redacted to avoid
+     *     leaking PII into error logs (Sentry, Datadog, etc.).
+     *   - `'verbose'`: the message includes the full JSON-serialized where
+     *     clause (e.g. `where: {"id":1,"email":"alice@x.com"}`).
+     *
+     * The full `where` object is always available as `err.where` for
+     * programmatic access regardless of mode.
+     */
+    errorMessages?: ErrorMessageMode;
+    /**
+     * Enable prepared statements. Queries are submitted with `{ name, text, values }`
+     * to the pg driver, which caches the parse+plan on the server per connection.
+     *
+     * Default: `true` for Turbine-owned pools, `false` for external pools (serverless
+     * drivers may not support named statements).
+     *
+     * Override with `TURBINE_DISABLE_PREPARED=1` env var.
+     */
+    preparedStatements?: boolean;
+    /**
+     * Enable the SQL template cache. Repeated queries with the same shape reuse
+     * cached SQL text instead of rebuilding from scratch.
+     *
+     * Default: `true`. Set to `false` as a nuclear kill switch.
+     */
+    sqlCache?: boolean;
+    /**
+     * Maximum number of distinct SQL templates each per-table LRU cache retains.
+     *
+     * Default: `1000`. Values are parameterized (`$1, $2, …`) and never fragment
+     * the cache, so this bounds distinct query SHAPES. Raise it for apps with a
+     * very large surface of query shapes to lift the hit rate at the cost of
+     * memory; lower it to cap memory. `0` disables caching entirely (identical to
+     * `sqlCache: false`); a negative value is ignored (treated as the default).
+     */
+    sqlCacheSize?: number;
+    /** SQL dialect implementation. Defaults to PostgreSQL. Internal Phase-1 seam for dialect packages. */
+    dialect?: Dialect;
+    /**
+     * Read replicas. When set, read-only operations issued outside a transaction
+     * (`findMany`, `findFirst`, `findUnique`, `*OrThrow`, `count`, `aggregate`,
+     * `groupBy`, `findManyStream`) are round-robin load-balanced across these
+     * pools; the primary handles them along with every write. ALL writes,
+     * `$transaction` bodies, `pipeline`, `raw`/`sql`, `$listen`/`$notify`, and
+     * observability flushes always use the primary.
+     *
+     *   - `string` entries are connection strings — Turbine constructs an owned
+     *     `pg.Pool` for each (same pool-tuning knobs as the primary, and the same
+     *     one-time, constructor-gated type-parser registration). `disconnect()`
+     *     closes them.
+     *   - `PgCompatPool` entries are external pools (Neon, Vercel, a shared
+     *     `pg.Pool`) — Turbine registers no type parsers on them and never ends
+     *     them; the caller owns their lifecycle.
+     *
+     * Use `client.$primary()` to get a view of the client that pins every
+     * operation (reads included) to the primary — e.g. to read your own write
+     * without replication lag. Omitting `replicas` (or passing `[]`) leaves the
+     * default single-pool path completely unchanged.
+     */
+    replicas?: readonly (string | PgCompatPool)[];
+    /**
+     * Automatic WHERE filters applied to every query, keyed by table accessor
+     * (`db[name]`). Each value is AND-merged into the compiled WHERE of every
+     * read and mutation on that table — and into every relation subquery that
+     * targets it — implementing soft-delete and multi-tenancy without repeating
+     * the predicate at each call site.
+     *
+     *   - A `WhereClause` value is a static filter (e.g. `{ deletedAt: null }`).
+     *   - A `() => WhereClause` value is evaluated at query-build time, so a
+     *     closure over per-request state (the current tenant id) yields a
+     *     request-scoped filter.
+     *
+     * `create`/`createMany` are never filtered. A per-query
+     * `skipGlobalFilters: true | string[]` opts out. The empty-`where` guard on
+     * `update`/`delete` still checks the USER-supplied `where`, so a global
+     * filter never turns an unguarded mass mutation into an allowed one.
+     *
+     * @example
+     * ```ts
+     * const db = turbine({ url, schema, globalFilters: {
+     *   posts: { deletedAt: null },              // soft-delete
+     *   orders: () => ({ tenantId: currentTenant() }), // per-request tenancy
+     * }});
+     * ```
+     */
+    globalFilters?: GlobalFilters;
+}
+/** Parameters passed to middleware functions */
+export interface MiddlewareParams {
+    /** The table/model being queried (e.g. 'users') */
+    model: string;
+    /** The operation being performed (e.g. 'findUnique', 'create', 'update') */
+    action: string;
+    /** The arguments passed to the query method */
+    args: Record<string, unknown>;
+}
+/** The next function in the middleware chain */
+export type MiddlewareNext = (params: MiddlewareParams) => Promise<unknown>;
+/** A middleware function that intercepts queries */
+export type Middleware = (params: MiddlewareParams, next: MiddlewareNext) => Promise<unknown>;
+export interface TransactionOptions {
+    /** Timeout in ms — transaction will be rolled back if exceeded */
+    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.
+ * All queries run on a dedicated connection within a BEGIN/COMMIT block.
+ * Supports nested transactions via SAVEPOINTs.
+ */
+export declare class TransactionClient {
+    private readonly client;
+    readonly schema: SchemaMetadata;
+    private readonly middlewares;
+    private readonly queryOptions?;
+    /**
+     * The parent pool this transaction runs on. Only its `readonly` and
+     * `capabilities` are read (both PowDB-only flags), so the transaction-scoped
+     * proxy pool built by {@link createTxPool} carries them through: without this
+     * a read-only client's `$transaction` writes bypass the E018 guard, and an
+     * older-engine client falls back to ALL_POWDB_CAPABILITIES inside the tx
+     * (emitting join PowQL a pre-0.13 engine rejects). Undefined / absent flags
+     * for a plain pg pool leave the proxy unchanged.
+     */
+    private readonly sourcePool?;
+    private readonly tableCache;
+    private savepointCounter;
+    /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
+    private readonly dialect;
+    constructor(client: pg.PoolClient, schema: SchemaMetadata, middlewares: Middleware[], queryOptions?: QueryInterfaceOptions | undefined, 
+    /**
+     * The parent pool this transaction runs on. Only its `readonly` and
+     * `capabilities` are read (both PowDB-only flags), so the transaction-scoped
+     * proxy pool built by {@link createTxPool} carries them through: without this
+     * a read-only client's `$transaction` writes bypass the E018 guard, and an
+     * older-engine client falls back to ALL_POWDB_CAPABILITIES inside the tx
+     * (emitting join PowQL a pre-0.13 engine rejects). Undefined / absent flags
+     * for a plain pg pool leave the proxy unchanged.
+     */
+    sourcePool?: {
+        readonly readonly?: boolean;
+        readonly capabilities?: unknown;
+    } | undefined);
+    /**
+     * Get a QueryInterface for a table within this transaction.
+     * Uses the dedicated transaction connection instead of the pool.
+     */
+    table<T extends object = Record<string, unknown>>(name: string): QueryInterface<T>;
+    /**
+     * Execute a nested transaction via SAVEPOINT.
+     * If the inner function throws, only the savepoint is rolled back.
+     */
+    $transaction<R>(fn: (tx: TransactionClient) => Promise<R>): Promise<R>;
+    /**
+     * Execute a raw SQL query within this transaction.
+     */
+    raw<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    /**
+     * Create a pool-like wrapper around the transaction client.
+     * This allows QueryInterface to work with the transaction connection
+     * without knowing it's in a transaction.
+     *
+     * pg driver errors thrown by queries are translated into typed Turbine
+     * errors via wrapPgError so transaction-scoped queries surface the same
+     * typed errors as pool-scoped queries.
+     */
+    private createTxPool;
+}
+export declare class TurbineClient {
+    /** The underlying pg.Pool — exposed for escape hatches */
+    readonly pool: pg.Pool;
+    /** The schema metadata this client was built from */
+    readonly schema: SchemaMetadata;
+    private static int8ParserRegistered;
+    private static utcTimestampParserRegistered;
+    private readonly logging;
+    /** Active SQL dialect — owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
+    private readonly dialect;
+    private readonly tableCache;
+    private readonly middlewares;
+    private readonly queryListeners;
+    private queryOptions;
+    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;
+    /**
+     * Read-replica pools in round-robin order. Empty when no replicas are
+     * configured, in which case `table()` takes the original single-pool path.
+     */
+    private readonly replicaPools;
+    /**
+     * The subset of {@link replicaPools} that Turbine created from connection
+     * strings and must close on `disconnect()`. External replica pools are not
+     * listed here (caller owns their lifecycle).
+     */
+    private readonly ownedReplicaPools;
+    /** Rotating index for round-robin replica selection (advances per read op). */
+    private replicaCursor;
+    /** Per-replica `table → QueryInterface` caches, indexed like {@link replicaPools}. */
+    private readonly replicaTableCaches;
+    /** Cache of per-table routing proxies (only used when replicas are present). */
+    private readonly routingProxyCache;
+    /** Lazily-built, cached primary-only view returned by {@link $primary}. */
+    private primaryView?;
+    constructor(config: TurbineConfig | undefined, schema: SchemaMetadata);
+    /**
+     * Register a middleware function that runs around every query.
+     *
+     * Middleware can inspect and log query parameters, measure timing, and
+     * transform the result returned by `next()`. Note: query SQL is generated
+     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * mutating it does NOT change the executed SQL. Cross-cutting filters
+     * (e.g. soft deletes) belong in the query itself: pass an explicit
+     * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
+     *
+     * @example
+     * ```ts
+     * // Query timing middleware
+     * db.$use(async (params, next) => {
+     *   const before = Date.now();
+     *   const result = await next(params);
+     *   console.log(`${params.model}.${params.action} took ${Date.now() - before}ms`);
+     *   return result;
+     * });
+     *
+     * // Result transformation middleware — redact a field on the way out
+     * db.$use(async (params, next) => {
+     *   const result = await next(params);
+     *   if (params.model === 'users' && Array.isArray(result)) {
+     *     for (const row of result as { email?: string }[]) row.email = '[redacted]';
+     *   }
+     *   return result;
+     * });
+     * ```
+     */
+    $use(middleware: Middleware): void;
+    $on(_event: 'query', listener: QueryEventListener): void;
+    $off(_event: 'query', listener: QueryEventListener): void;
+    private observeEngine?;
+    $observe(config: ObserveConfig): Promise<ObserveHandle>;
+    /**
+     * Get a QueryInterface for a table.
+     * Results are cached — calling `table('users')` twice returns the same instance.
+     *
+     * When read replicas are configured, this returns a thin routing proxy: the
+     * read-only operations in {@link READ_OPERATIONS} are dispatched to a
+     * round-robin replica-bound QueryInterface (so an entire read — base rows and
+     * any batched sub-queries — runs against a single consistent replica), while
+     * writes and every other member fall through to the primary-bound instance.
+     * With no replicas the original single-pool instance is returned directly.
+     */
+    table<T extends object = Record<string, unknown>>(name: string): QueryInterface<T>;
+    /** Get (and cache) the primary-pool-bound QueryInterface for a table. */
+    private primaryTableQI;
+    /**
+     * Advance the round-robin cursor and return the QueryInterface bound to the
+     * selected replica pool for `name` (cached per replica).
+     */
+    private nextReplicaTableQI;
+    /** Construct a QueryInterface bound to `pool` (honoring any injected factory). */
+    private buildTableQI;
+    /**
+     * Build the read/write routing proxy for a table. The proxy targets the
+     * primary QueryInterface (so writes, `build*`, and every non-read member work
+     * unchanged); read operations are intercepted and dispatched to a replica.
+     */
+    private createRoutingAccessor;
+    /**
+     * Return a view of this client that pins EVERY operation — reads included —
+     * to the primary pool, bypassing replica routing. Use it to read your own
+     * write without replication lag, or for any read that must see the latest
+     * committed data.
+     *
+     * The view shares the primary pool, schema, dialect, query options, and
+     * middleware; it owns nothing, so its `disconnect()` is a no-op. When no
+     * replicas are configured this simply returns the client itself (already
+     * primary-only). The view is cached — repeated calls return the same instance.
+     *
+     * @example
+     * ```ts
+     * await db.users.create({ data: { email: 'a@b.com' } });
+     * // Read-after-write: guaranteed to see the row just inserted.
+     * const user = await db.$primary().users.findFirst({ where: { email: 'a@b.com' } });
+     * ```
+     */
+    $primary(): TurbineClient;
+    /**
+     * Execute multiple queries in a single database round-trip.
+     *
+     * Two call styles:
+     *   - `db.pipeline(q1, q2, q3)` — rest params (backward-compatible)
+     *   - `db.pipeline([q1, q2, q3], { transactional: false })` — array + options
+     *
+     * On pg.Pool-backed connections with TCP, this uses the real Postgres
+     * extended-query pipeline protocol (one TCP flush, one round-trip).
+     * On HTTP-based drivers it falls back to sequential execution.
+     */
+    pipeline<T extends readonly DeferredQuery<unknown>[]>(...args: T | [T, PipelineOptions?]): Promise<PipelineResults<T>>;
+    /**
+     * Check whether the underlying pool supports the real pipeline protocol.
+     * Returns `true` for standard pg.Pool TCP connections, `false` for HTTP
+     * drivers (Neon HTTP, Vercel Postgres, etc.) and mock pools.
+     */
+    pipelineSupported(): Promise<boolean>;
+    /**
+     * Execute a raw SQL query with parameter interpolation via tagged templates.
+     *
+     * @example
+     * ```ts
+     * const result = await db.raw<{ day: Date; count: number }>`
+     *   SELECT DATE_TRUNC('day', created_at) as day, COUNT(*)::int as count
+     *   FROM posts WHERE org_id = ${orgId}
+     *   GROUP BY day ORDER BY day
+     * `;
+     * ```
+     */
+    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.
+     *
+     * @example
+     * ```ts
+     * await db.transaction(async (client) => {
+     *   await client.query('INSERT INTO users (name) VALUES ($1)', ['Alice']);
+     * });
+     * ```
+     */
+    transaction<T>(fn: (client: pg.PoolClient) => Promise<T>): Promise<T>;
+    /**
+     * Execute a function within a database transaction with full typed table accessors.
+     *
+     * The `tx` object provides the same table accessor API as the main client.
+     * Supports nested transactions via SAVEPOINTs, timeouts, and isolation levels.
+     *
+     * @example
+     * ```ts
+     * await db.$transaction(async (tx) => {
+     *   const user = await tx.users.create({ data: { email: 'a@b.com' } });
+     *   await tx.posts.create({ data: { userId: user.id, title: 'Hello' } });
+     * });
+     *
+     * // With options:
+     * await db.$transaction(async (tx) => {
+     *   // ...
+     * }, { timeout: 5000, isolationLevel: 'Serializable' });
+     * ```
+     */
+    $transaction<R>(fn: (tx: TransactionClient) => Promise<R>, options?: TransactionOptions): Promise<R>;
+    /**
+     * Batch form — run a tuple of {@link DeferredQuery} objects (produced by the
+     * `build*()` methods, e.g. `db.users.buildFindMany(...)`) atomically inside a
+     * single `BEGIN…COMMIT` on one connection. Returns a positionally-typed tuple
+     * of each query's transformed result; any failure rolls the whole batch back.
+     *
+     * Unlike {@link pipeline}, this never uses the extended-query pipeline
+     * protocol. Statements run on the single transaction connection: strictly
+     * sequentially by default (safe on every driver, including HTTP/serverless
+     * pools), or — when the checked-out connection advertises
+     * {@link PgCompatPoolClient.supportsPipelining} — dispatched in one write
+     * burst with replies collected in order, saving a network round trip per
+     * statement. Either way the failure contract is identical: the first
+     * (lowest-index) failure aborts the batch and rolls everything back.
+     *
+     * @example
+     * ```ts
+     * const [user, count] = await db.$transaction([
+     *   db.users.buildFindUnique({ where: { id: 1 } }),
+     *   db.posts.buildCount({ where: { userId: 1 } }),
+     * ]);
+     * ```
+     */
+    $transaction<T extends readonly DeferredQuery<unknown>[]>(queries: readonly [...T]): Promise<PipelineResults<T>>;
+    /**
+     * Execute a batch of {@link DeferredQuery} objects atomically inside one
+     * transaction. Backs the `$transaction([...])` array overload. Reuses the raw
+     * {@link transaction} machinery (BEGIN/COMMIT/ROLLBACK + connection release);
+     * each result is passed through its query's `transform`.
+     *
+     * Execution strategy on the single transaction connection:
+     *   - **Sequential (default).** Await each statement's reply before sending
+     *     the next. Safe on every driver; on a networked driver a batch of N
+     *     costs N round trips.
+     *   - **Pipelined.** When the checked-out connection advertises
+     *     {@link PgCompatPoolClient.supportsPipelining} (its `query()` accepts
+     *     concurrent calls and completes them in FIFO submission order), all
+     *     statements are dispatched in one write burst and the replies are
+     *     collected in order — ~1 round trip plus server time. Only taken when
+     *     the dialect's writes surface rows directly (`resultStrategy` !==
+     *     'reselect'): a reselect plan is itself a sequential write+read pair.
+     *
+     * The two paths share one failure contract: the first (lowest-index) failed
+     * statement's error is thrown (wrapped via {@link wrapPgError}) and the
+     * surrounding transaction rolls back, so no statement's effect survives. The
+     * pipelined path drains every in-flight reply (`Promise.allSettled`) before
+     * rethrowing, which keeps the connection's request/reply pairing intact and
+     * means ROLLBACK is only issued once no statement is still in flight.
+     */
+    private transactionBatch;
+    /**
+     * 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.
+     *
+     * Only errors with `isRetryable === true` (DeadlockError, SerializationFailureError)
+     * are retried. Uses exponential backoff with jitter.
+     *
+     * @example
+     * ```ts
+     * const result = await db.$retry(() =>
+     *   db.$transaction(async (tx) => {
+     *     // ... serializable transaction logic
+     *   }, { isolationLevel: 'Serializable' })
+     * );
+     * ```
+     */
+    $retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+    /**
+     * Test the database connection.
+     * Throws if the connection fails.
+     */
+    connect(): Promise<void>;
+    /**
+     * Gracefully shut down the connection pool.
+     *
+     * If Turbine was given an external pool via `TurbineConfig.pool`, this
+     * method is a no-op — the caller is responsible for the pool's lifecycle.
+     */
+    disconnect(): Promise<void>;
+    /** Alias for disconnect() */
+    end(): Promise<void>;
+    /**
+     * Pool statistics for monitoring. Returns zeros for pools that don't
+     * expose connection counts (e.g., stateless HTTP drivers like Neon).
+     */
+    get stats(): {
+        totalCount: number;
+        idleCount: number;
+        waitingCount: number;
+    };
+}