turbine-orm 0.67.0 → 0.70.0

package/dist/cjs/client.d.ts

@@ -21,10 +21,10 @@
  * 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 { PgCompatPool, PgCompatPoolClient } from './pg-types.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
 import { type DeferredQuery, type GlobalFilters, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy, type TemporalInfinityReading } from './query/index.js';
 import { type NotificationHandler, type Subscription } from './realtime.js';
@@ -38,75 +38,13 @@ export interface RetryOptions {
 }
 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.
+ * The pg-compatible driver contract. Declared in `pg-types.ts` (a leaf module
+ * with no imports) rather than here, so `query/` can name the same interfaces
+ * without an import edge back to the client, and so no `@types/pg` name
+ * reaches the published declarations. Re-exported so every existing
+ * `from './client.js'` import path keeps working.
  */
-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;
-}
+export type { PgCompatPool, PgCompatPoolClient, PgCompatQueryConfig, PgCompatQueryResult, } from './pg-types.js';
 /**
  * Driver-neutral seam. Bundles a pg-compatible connection pool with the SQL
  * {@link Dialect} that owns every piece of SQL text varying across engines -
@@ -618,7 +556,7 @@ export declare class TransactionClient {
     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, 
+    constructor(client: PgCompatPoolClient, 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
@@ -686,8 +624,19 @@ export declare class TransactionClient {
     private createTxPool;
 }
 export declare class TurbineClient {
-    /** The underlying pg.Pool, exposed for escape hatches */
-    readonly pool: pg.Pool;
+    /**
+     * The underlying connection pool, exposed for escape hatches.
+     *
+     * Typed as the driver-neutral {@link PgCompatPool} rather than `pg.Pool`,
+     * because it is only a `pg.Pool` when Turbine opened it: supply
+     * {@link TurbineConfig.pool} and this is whatever driver you passed (Neon,
+     * Vercel Postgres, Hyperdrive), and on the non-Postgres engines it is that
+     * engine's pool shim. `query` / `connect` / `end` are the members every
+     * driver has. For the pg-only surface (cursors, `copyFrom`/`copyTo`, pool
+     * events), import `Pool` from the pg package and cast:
+     * `db.pool as unknown as Pool`.
+     */
+    readonly pool: PgCompatPool;
     /** The schema metadata this client was built from */
     readonly schema: SchemaMetadata;
     private static int8ParserRegistered;
@@ -1052,8 +1001,14 @@ export declare class TurbineClient {
      */
     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.
+     * Execute a function within a database transaction on the raw driver
+     * connection. For the typed API, use `$transaction()` instead.
+     *
+     * The client is typed as {@link PgCompatPoolClient}, the driver-neutral
+     * contract: `query(text, values)` plus `release()`, which is all any
+     * supported driver guarantees. For the pg-only surface (cursors, COPY
+     * streams, the `QueryConfig` object form), import `PoolClient` from the pg
+     * package and cast: `client as unknown as PoolClient`.
      *
      * @example
      * ```ts
@@ -1062,7 +1017,7 @@ export declare class TurbineClient {
      * });
      * ```
      */
-    transaction<T>(fn: (client: pg.PoolClient) => Promise<T>): Promise<T>;
+    transaction<T>(fn: (client: PgCompatPoolClient) => Promise<T>): Promise<T>;
     /**
      * Execute a function within a database transaction with full typed table accessors.
      *

package/dist/cjs/client.js

@@ -585,8 +585,8 @@ class TransactionClient {
                         return await client.query(textOrConfig, values);
                     }
                     // Object form for prepared statements: { name, text, values }
-                    // pg.PoolClient.query accepts QueryConfig but the overloads make TS
-                    // unhappy with the union, so we cast through unknown.
+                    // A driver client accepts it, but the two-argument `query` in the
+                    // PgCompatPoolClient contract does not describe it, so we cast.
                     return await client.query(textOrConfig);
                 }
                 catch (err) {
@@ -610,7 +610,18 @@ exports.TransactionClient = TransactionClient;
 // TurbineClient
 // ---------------------------------------------------------------------------
 class TurbineClient {
-    /** The underlying pg.Pool, exposed for escape hatches */
+    /**
+     * The underlying connection pool, exposed for escape hatches.
+     *
+     * Typed as the driver-neutral {@link PgCompatPool} rather than `pg.Pool`,
+     * because it is only a `pg.Pool` when Turbine opened it: supply
+     * {@link TurbineConfig.pool} and this is whatever driver you passed (Neon,
+     * Vercel Postgres, Hyperdrive), and on the non-Postgres engines it is that
+     * engine's pool shim. `query` / `connect` / `end` are the members every
+     * driver has. For the pg-only surface (cursors, `copyFrom`/`copyTo`, pool
+     * events), import `Pool` from the pg package and cast:
+     * `db.pool as unknown as Pool`.
+     */
     pool;
     /** The schema metadata this client was built from */
     schema;
@@ -953,11 +964,15 @@ class TurbineClient {
             if (config.ssl !== undefined) {
                 poolConfig.ssl = config.ssl;
             }
-            this.pool = new pg_1.default.Pool(TurbineClient.withPlanCacheMode(poolConfig, this.planCacheMode));
-            this.ownsPool = true;
-            this.pool.on('error', (err) => {
+            // Held as a `pg.Pool` for the length of this block: `PgCompatPool.on` is
+            // optional (HTTP drivers have no pool events), and here we know we own a
+            // real pg pool that has one. Same shape as the replica loop below.
+            const ownPool = new pg_1.default.Pool(TurbineClient.withPlanCacheMode(poolConfig, this.planCacheMode));
+            ownPool.on('error', (err) => {
                 console.error('[turbine] Unexpected pool error:', err.message);
             });
+            this.pool = ownPool;
+            this.ownsPool = true;
             if (this.logging) {
                 console.log(`[turbine] Pool created, max ${poolConfig.max} connections, ${Object.keys(schema.tables).length} tables`);
             }
@@ -1413,10 +1428,9 @@ class TurbineClient {
     }
     /** Construct a QueryInterface bound to `pool` (honoring any injected factory). */
     buildTableQI(pool, name) {
-        const asPgPool = pool;
         return this.queryOptions?.queryInterfaceFactory
-            ? this.queryOptions.queryInterfaceFactory(asPgPool, name, this.schema, this.middlewares, this.queryOptions)
-            : new index_js_1.QueryInterface(asPgPool, name, this.schema, this.middlewares, this.queryOptions);
+            ? this.queryOptions.queryInterfaceFactory(pool, name, this.schema, this.middlewares, this.queryOptions)
+            : new index_js_1.QueryInterface(pool, name, this.schema, this.middlewares, this.queryOptions);
     }
     /**
      * Build the read/write routing proxy for a table. The proxy targets the
@@ -1596,8 +1610,14 @@ class TurbineClient {
     // Transaction support (raw, legacy)
     // -------------------------------------------------------------------------
     /**
-     * Execute a function within a database transaction (raw pg.PoolClient).
-     * For the typed API, use `$transaction()` instead.
+     * Execute a function within a database transaction on the raw driver
+     * connection. For the typed API, use `$transaction()` instead.
+     *
+     * The client is typed as {@link PgCompatPoolClient}, the driver-neutral
+     * contract: `query(text, values)` plus `release()`, which is all any
+     * supported driver guarantees. For the pg-only surface (cursors, COPY
+     * streams, the `QueryConfig` object form), import `PoolClient` from the pg
+     * package and cast: `client as unknown as PoolClient`.
      *
      * @example
      * ```ts

package/dist/cjs/introspect.d.ts

@@ -135,21 +135,98 @@ export declare function applyRelationRenames(schema: SchemaMetadata, renames: Re
  */
 export declare function introspectPostgresCatalog(options: IntrospectOptions): Promise<SchemaMetadata>;
 /**
- * Parse the indexed column names out of a `pg_indexes.indexdef` string.
+ * The index-definition key-list SCANNER, and the only one that reads an
+ * `indexdef` character by character.
  *
- * `indexdef` always reads `CREATE [UNIQUE] INDEX name ON tbl USING method
- * (col, ...) [WHERE predicate]`. We anchor on the `USING` clause's parenthesised
- * column list (the same precedent as `describeIndexDefMismatch` in
- * schema-sql.ts) so a PARTIAL index's trailing `WHERE (...)` parentheses are
- * never mistaken for the column list. The older greedy `/\((.+)\)/` swallowed
- * `) WHERE (` and spliced a raw predicate fragment into the column names, which
- * then leaked into generated compound-unique selector names.
+ * `pg_indexes.indexdef` always reads `CREATE [UNIQUE] INDEX name ON tbl USING
+ * method (key, ...) [INCLUDE (col, ...)] [WITH (...)] [TABLESPACE ts]
+ * [WHERE predicate]`. This returns the raw entries of the KEY LIST only, one per
+ * top-level comma, expression entries included and verbatim.
  *
- * Each column is de-quoted (Postgres quotes non-lowercase identifiers such as a
- * Prisma implicit m2m junction's `"A"` / `"B"`), so the names match the
- * unquoted column names carried elsewhere in the metadata. Expression columns
- * (anything containing a parenthesis) are dropped conservatively: a functional
- * index does not name a plain column.
+ * ## THREE indexdef parsers coexist in this repo. This is one of them.
+ *
+ * An earlier version of this comment said there was exactly one. There is not,
+ * and pretending otherwise is how hand-synced parsers drift here, so each of the
+ * three names the other two:
+ *
+ *   1. THIS scanner (with {@link indexKeyColumn} / {@link parseIndexColumns}).
+ *      Safe for any `indexdef` pg emits, including expression keys, quoted
+ *      identifiers holding commas or parens, string literals, INCLUDE lists and
+ *      partial predicates. Feeds generated metadata, compound-unique selectors,
+ *      the FK-index advisor and m2m detection, plus `cli/mcp.ts`.
+ *   2. {@link parsePlainUniqueIndexColumns}, below. Still the old
+ *      `USING \w+ \(([^)]*)\)` regex. It answers a NARROWER question ("is this a
+ *      plain, whole-table unique index over these exact columns") and returns
+ *      `null` on everything it cannot read, so its regex's known weaknesses cost
+ *      a missed hasOne flip rather than a wrong answer.
+ *   3. `describeIndexDefMismatch` in `schema-sql.ts`. Same old regex, same
+ *      fail-toward-a-warning posture.
+ *
+ * Unifying them is a separate change with its own risk: (2) and (3) both treat
+ * "cannot read this" as a safe refusal, and swapping in a parser that reads MORE
+ * turns some of those refusals into answers. Until then, prefer this scanner for
+ * any new caller, and do not assume a fix here reaches the other two.
+ *
+ * ## Why the mcp.ts copy is gone
+ *
+ * `cli/mcp.ts` kept its own weaker copy of this, and the two drifted: on
+ * `USING btree (id) INCLUDE (email)` the copy answered `['id) INCLUDE (email']`
+ * while this one answered `['id']`. Those columns feed `deriveCatalogRelations`,
+ * which decides hasOne-vs-hasMany and auto-m2m, so a UNIQUE index with INCLUDE
+ * columns was visible to `turbine generate` and invisible to the MCP server, and
+ * the two surfaces disagreed about which relations the schema has. The
+ * duplication is also what produced the predicate leak that
+ * {@link parseIndexColumns}'s own history records. So mcp.ts consumes this
+ * function now, and the split between the two callers is expressed as the two
+ * exports below rather than as two implementations.
+ *
+ * ## Why a scanner rather than a regex
+ *
+ * The regex this replaces (`/USING\s+\w+\s*\(([^)]*)\)/`) stops at the FIRST
+ * `)`, which is the wrong paren for any expression key (`lower(email)`), and a
+ * plain `.split(',')` cuts `coalesce(a, b)` in half. The scan tracks paren depth
+ * and single-quoted literals, so a comma or a paren inside an expression or a
+ * literal is not a boundary.
+ *
+ * The anchor requires `USING <method> (`, which no predicate, INCLUDE list, WITH
+ * list or literal can spell, so the key list is found positionally rather than
+ * by hoping the first paren is the right one. When the anchor is absent (not a
+ * shape pg emits) it falls back to the first parenthesised group, matching the
+ * previous behaviour.
+ */
+export declare function parseIndexKeyEntries(indexdef: string): string[];
+/**
+ * The plain COLUMN NAME an index key entry indexes, or `null` when the entry is
+ * an expression rather than a column.
+ *
+ * A key entry is `{ column | (expression) } [COLLATE c] [opclass [(params)]]
+ * [ASC|DESC] [NULLS FIRST|LAST]`, so the column is the LEADING token and
+ * everything after it is a modifier. Reading it that way is what makes
+ * `email COLLATE "C" text_pattern_ops` resolve to `email`; the previous
+ * suffix-stripping (`ASC`/`DESC` only) returned the whole entry verbatim as a
+ * "column name", which matches no real column.
+ *
+ * SCOPE OF THAT FIX, stated exactly because an earlier version of this comment
+ * overstated it: what changes is what {@link parseIndexColumns} reports, and so
+ * what its consumers see. Those are the generated `metadata.ts` index lists,
+ * the compound-unique selector derivation, the FK-index advisor's leading-column
+ * check, and m2m junction detection. Relation CARDINALITY is NOT among them: the
+ * `hasMany`/`hasOne` flip reads {@link parsePlainUniqueIndexColumns}, a separate
+ * parser this does not feed, and that one still answers `null` for an opclass'd
+ * UNIQUE index exactly as it did before.
+ *
+ * The name is de-quoted (Postgres quotes non-lowercase identifiers such as a
+ * Prisma implicit m2m junction's `"A"` / `"B"`) so it matches the unquoted names
+ * carried elsewhere in the metadata.
+ */
+export declare function indexKeyColumn(entry: string): string | null;
+/**
+ * Parse the indexed COLUMN names out of a `pg_indexes.indexdef` string.
+ *
+ * Expression keys are dropped, conservatively: a functional index does not name
+ * a plain column, and generated metadata has nowhere to say "there was a key
+ * here that is not a column". {@link parseIndexKeyEntries} is the variant that
+ * keeps them, for the one caller (`cli/mcp.ts`) that reports their presence.
  */
 export declare function parseIndexColumns(indexdef: string): string[];
 /**
@@ -198,10 +275,29 @@ export declare function isUnknownTsType(tsType: string): boolean;
  *     expression, not the raw FK column set.
  *
  * Anchors on the `USING <method> (` clause the same way
- * {@link describeIndexDefMismatch} does, so a partial index's `WHERE (...)`
- * parentheses are never mistaken for the column list. Every column token must be
- * a bare or double-quoted identifier; anything else (a function call, an
- * operator expression) fails the check and yields `null`.
+ * `describeIndexDefMismatch` (schema-sql.ts) does, so a partial index's
+ * `WHERE (...)` parentheses are never mistaken for the column list. Every column
+ * token must be a bare or double-quoted identifier; anything else (a function
+ * call, an operator expression) fails the check and yields `null`.
+ *
+ * ## Parser 2 of 3, and what it is safe for
+ *
+ * This is the second of the three indexdef parsers catalogued on
+ * {@link parseIndexKeyEntries}; the third is `describeIndexDefMismatch` in
+ * schema-sql.ts. It is still the `USING \w+ \(([^)]*)\)` regex that the scanner
+ * up there was written to replace, so it inherits that regex's weaknesses: it
+ * stops at the FIRST `)`, and it splits on every comma. On an expression key
+ * (`lower(email)`), on a quoted identifier containing a comma or a paren, and on
+ * an opclass'd key (`email text_pattern_ops`) it therefore reads a token that is
+ * not a bare identifier and returns `null`.
+ *
+ * That is SAFE HERE and only here, because `null` is this function's "I cannot
+ * vouch for this index" answer and its single consumer
+ * ({@link detectUniqueForeignKeySets}) treats it as "this index does not prove
+ * uniqueness". The cost of every misread is a relation left as `hasMany` that
+ * could have been `hasOne`, never a uniqueness claim the database does not back.
+ * Do NOT reuse it anywhere a wrong-but-plausible column list would be acted on;
+ * use the scanner for that.
  */
 export declare function parsePlainUniqueIndexColumns(indexdef: string): string[] | null;
 /**