turbine-orm 0.67.0 → 0.70.0

package/dist/introspect.js

@@ -658,40 +658,196 @@ export async function introspectPostgresCatalog(options) {
     }
 }
 /**
- * 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 function parseIndexColumns(indexdef) {
-    const m = indexdef.match(/USING\s+\w+\s*\(([^)]*)\)/i) ?? indexdef.match(/\(([^)]*)\)/);
-    if (!m)
+export function parseIndexKeyEntries(indexdef) {
+    const anchor = /USING\s+\w+\s*\(/i.exec(indexdef);
+    const open = anchor ? anchor.index + anchor[0].length : indexdef.indexOf('(') + 1;
+    if (open === 0)
         return [];
-    return m[1]
-        .split(',')
-        .map((c) => unquoteIndexIdent(c
-        .trim()
-        .replace(/\s+(ASC|DESC)$/i, '')
-        .trim()))
-        .filter((c) => c.length > 0 && !c.includes('(') && !c.includes(')'));
+    const entries = [];
+    let depth = 0;
+    let inLiteral = false;
+    let inQuotedIdent = false;
+    let start = open;
+    for (let i = open; i < indexdef.length; i++) {
+        const char = indexdef[i];
+        // A doubled quote inside a literal (or a quoted identifier) toggles twice,
+        // which is the same as not toggling, so pg's `''` / `""` escapes need no
+        // special case. Identifier quoting is tracked as well as literal quoting: a
+        // column named `it's` renders as `"it's"`, and reading its apostrophe as the
+        // start of a literal swallows the rest of the definition.
+        if (char === "'" && !inQuotedIdent) {
+            inLiteral = !inLiteral;
+            continue;
+        }
+        if (char === '"' && !inLiteral) {
+            inQuotedIdent = !inQuotedIdent;
+            continue;
+        }
+        if (inLiteral || inQuotedIdent)
+            continue;
+        if (char === '(')
+            depth++;
+        else if (char === ')') {
+            if (depth === 0) {
+                entries.push(indexdef.slice(start, i));
+                return entries.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+            }
+            depth--;
+        }
+        else if (char === ',' && depth === 0) {
+            entries.push(indexdef.slice(start, i));
+            start = i + 1;
+        }
+    }
+    // Unterminated key list: the definition does not parse, so it names no
+    // columns. Never "all of it" - the one input this cannot read must not be the
+    // one it forwards.
+    return [];
 }
-/** Strip one pair of surrounding double quotes and unescape doubled `""`. */
-function unquoteIndexIdent(col) {
-    if (col.length >= 2 && col.startsWith('"') && col.endsWith('"')) {
-        return col.slice(1, -1).replace(/""/g, '"');
+/**
+ * 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 function indexKeyColumn(entry) {
+    const trimmed = entry.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (trimmed.startsWith('"')) {
+        // A quoted identifier ends at the first unpaired `"`; anything after it is a
+        // modifier. `""` inside is one escaped quote and does not end it.
+        let i = 1;
+        let name = '';
+        while (i < trimmed.length) {
+            if (trimmed[i] === '"') {
+                if (trimmed[i + 1] === '"') {
+                    name += '"';
+                    i += 2;
+                    continue;
+                }
+                // The SAME trailing-modifier rule the unquoted branch applies below,
+                // and for the same reason: what follows the name must be whitespace
+                // (a COLLATE clause, an opclass, ASC/DESC/NULLS) or nothing. Returning
+                // at the closing quote without asking read `"MyFunc"(email)` as a
+                // column named `MyFunc`, synthesizing a column that does not exist and
+                // handing it to generated metadata, the FK-advisor lead-column check,
+                // compound-unique selectors and m2m junction detection alike.
+                const rest = trimmed.slice(i + 1);
+                if (rest.length > 0 && !/^\s/.test(rest))
+                    return null;
+                return name;
+            }
+            name += trimmed[i];
+            i++;
+        }
+        return null; // unterminated quote: not a name this can vouch for
     }
-    return col;
+    // An expression key is anything that is not a bare leading identifier, which
+    // includes every parenthesised or operator-bearing form pg renders.
+    // Non-ASCII letters are identifier characters to Postgres and are left
+    // unquoted in `indexdef`, so the class has to admit them or a `café` column
+    // reads as an expression and disappears.
+    const leading = /^[A-Za-z_\u0080-\uFFFF][A-Za-z0-9_$\u0080-\uFFFF]*/.exec(trimmed);
+    if (!leading)
+        return null;
+    const rest = trimmed.slice(leading[0].length);
+    // The rest must be modifiers (whitespace-separated words / quoted collation /
+    // opclass parameters), never a continuation of an expression: `lower(email)`
+    // has a leading identifier too, and it is not a column.
+    if (rest.length > 0 && !/^\s/.test(rest))
+        return null;
+    return leading[0];
+}
+/**
+ * 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 function parseIndexColumns(indexdef) {
+    return parseIndexKeyEntries(indexdef)
+        .map(indexKeyColumn)
+        .filter((column) => column !== null);
 }
 /**
  * Whether an `indexdef` carries a top-level `WHERE` predicate (a PARTIAL index).
@@ -783,10 +939,29 @@ function columnSetsEqual(a, b) {
  *     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 function parsePlainUniqueIndexColumns(indexdef) {
     // Partial index: uniqueness is scoped to the WHERE predicate.
@@ -1210,9 +1385,28 @@ export function deriveCatalogRelations(inputs) {
     // Prisma's implicit m2m junctions have no primary key (just a two-column
     // UNIQUE index over the FK columns), so pass the introspected two-column
     // unique indexes as the fallback junction-key source.
+    //
+    // `idx.columns` is the key list with EXPRESSION keys already dropped, so its
+    // length is not the index's arity and cannot stand in for it. On
+    // `UNIQUE (a, lower(b), c)` it reads `['a', 'c']`, which looks exactly like a
+    // two-column junction key while the pair `(a, c)` is not unique at all, only
+    // `(a, lower(b), c)` is. A manyToMany derived from it returns DUPLICATE ROWS.
+    // So the arity is re-read from the raw definition and the two must agree:
+    // an index with any expression key is not a junction key this can vouch for.
+    // A PARTIAL unique index is refused for the same reason and is the MAINSTREAM
+    // shape of it: `UNIQUE (post_id, tag_id) WHERE deleted_at IS NULL` on a
+    // soft-deleted junction guarantees uniqueness only over the rows matching the
+    // predicate, so the pair can repeat across the whole table and the derived
+    // manyToMany returns duplicate rows. `IndexMetadata.partial` already exists and
+    // already documents this, and the hasOne path already honours it (see
+    // parsePlainUniqueIndexColumns, which refuses a definition carrying a WHERE).
+    // This filter was simply the one place that did not read it, so the two
+    // cardinality paths disagreed about whether the same index proved uniqueness.
     const uniqueIndexColsByTable = new Map();
     for (const [tbl, idxs] of indexesByTable) {
-        const twoColUniques = idxs.filter((idx) => idx.unique && idx.columns.length === 2).map((idx) => idx.columns);
+        const twoColUniques = idxs
+            .filter((idx) => idx.unique && !idx.partial && idx.columns.length === 2 && parseIndexKeyEntries(idx.definition).length === 2)
+            .map((idx) => idx.columns);
         if (twoColUniques.length > 0)
             uniqueIndexColsByTable.set(tbl, twoColUniques);
     }

package/dist/pg-types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * turbine-orm, the pg-compatible driver contract
+ *
+ * WHY THIS MODULE EXISTS, AND WHY IT IMPORTS NOTHING. The `pg` package ships
+ * no type declarations of its own, so every `@types/pg` name that reaches an
+ * EXPORTED declaration makes TypeScript emit an import of the pg module into
+ * the published `.d.ts`, which turns `@types/pg` into a hard requirement for
+ * any consumer compiling under `strict` - a runtime-free types package that
+ * nonetheless has to sit in `dependencies` for consumer builds to typecheck.
+ * That is the v0.28.1 regression: `@types/pg` was moved to `devDependencies`
+ * while the declaration surface still named `pg.Pool` / `pg.PoolClient` /
+ * `pg.QueryResult`, and consumer `tsc` broke. The order matters and it is
+ * one-way: clear the declaration surface FIRST, then move the dependency.
+ * The published declarations are checked for pg references on every release,
+ * so the surface cannot silently grow one back.
+ *
+ * So these are the pg shapes, declared natively. They are not a new parallel
+ * abstraction: `PgCompatPool` / `PgCompatPoolClient` / `PgCompatQueryResult`
+ * are the SAME interfaces the external-pool seam has used since the serverless
+ * binding shipped (`TurbineConfig.pool`, `turbineHttp`, and the `SqlitePool` /
+ * `MysqlPool` / `MssqlPool` / `PowdbPool` engine shims), lifted out of
+ * client.ts so that `query/` can name them without an import edge back to the
+ * client (see `scripts/check-import-cycles.mjs`). client.ts re-exports all of
+ * them, so every existing `from './client.js'` import path is unchanged.
+ *
+ * A genuine `pg.Pool`, `pg.PoolClient` and `pg.QueryResult` each satisfy the
+ * matching interface here structurally, which is what keeps `pg` usable at
+ * every position Turbine accepts one. The reverse is NOT true and never was:
+ * an HTTP driver's pool is not a `pg.Pool`, which is why the fields pg alone
+ * provides (`totalCount`, the `error` event) are optional.
+ *
+ * `pg` itself remains a real runtime dependency. This module is about the
+ * TYPE surface only.
+ *
+ * @module
+ */
+/**
+ * One column of a result's row description. `rows` is what Turbine reads; a
+ * driver that describes its columns supplies these too.
+ *
+ * `name` and `dataTypeID` are required because a driver that reports fields at
+ * all reports those two. The rest are pg's, optional so that a genuine
+ * `pg.FieldDef` object LITERAL is accepted (excess-property checking makes
+ * literal-level compatibility a real thing callers hit when they hand-write a
+ * fake result), and so that a driver reporting only the two is accepted as
+ * well.
+ */
+export interface PgCompatFieldDef {
+    name: string;
+    dataTypeID: number;
+    tableID?: number;
+    columnID?: number;
+    dataTypeSize?: number;
+    dataTypeModifier?: number;
+    format?: string;
+}
+/**
+ * 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.
+ *
+ * `rows` and `rowCount` are the contract: they are the only two members
+ * Turbine reads, and the two every supported driver produces. `command` /
+ * `oid` / `fields` are pg's and therefore OPTIONAL, which is what makes this
+ * interface a structural supertype of `pg.QueryResult` rather than a
+ * lookalike. That direction is the one that matters, since this type appears
+ * in PARAMETER position throughout the public surface
+ * ({@link PgCompatPool.query}'s result, `DeferredQuery.transform`'s argument):
+ * whatever pg hands back must be accepted, while the engine shims that return
+ * only `{ rows, rowCount }` must be accepted too.
+ */
+export interface PgCompatQueryResult<R = Record<string, unknown>> {
+    rows: R[];
+    rowCount: number | null;
+    fields?: PgCompatFieldDef[];
+    /** pg-family drivers: the completed command tag (`SELECT`, `INSERT`, ...). */
+    command?: string;
+    /** pg-family drivers: the legacy inserted-row OID, `0` for everything else. */
+    oid?: number;
+}
+/**
+ * The object form of a query, `{ name, text, values }`, which node-postgres
+ * accepts in place of `(text, values)` in order to name a prepared statement.
+ *
+ * Deliberately NOT a second overload on {@link PgCompatPool.query}. The engine
+ * pool shims implement that interface and speak only the two-argument form, so
+ * requiring the object form of every implementer would be a contract they
+ * cannot meet. Named prepared statements are a Postgres-path optimization, and
+ * the one call site that uses them casts to this shape.
+ */
+export interface PgCompatQueryConfig {
+    /** Prepared-statement name. Omit for an unnamed (re-parsed) statement. */
+    name?: string;
+    text: string;
+    values?: unknown[];
+}
+/**
+ * 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;
+}

package/dist/pg-types.js

@@ -0,0 +1,37 @@
+/**
+ * turbine-orm, the pg-compatible driver contract
+ *
+ * WHY THIS MODULE EXISTS, AND WHY IT IMPORTS NOTHING. The `pg` package ships
+ * no type declarations of its own, so every `@types/pg` name that reaches an
+ * EXPORTED declaration makes TypeScript emit an import of the pg module into
+ * the published `.d.ts`, which turns `@types/pg` into a hard requirement for
+ * any consumer compiling under `strict` - a runtime-free types package that
+ * nonetheless has to sit in `dependencies` for consumer builds to typecheck.
+ * That is the v0.28.1 regression: `@types/pg` was moved to `devDependencies`
+ * while the declaration surface still named `pg.Pool` / `pg.PoolClient` /
+ * `pg.QueryResult`, and consumer `tsc` broke. The order matters and it is
+ * one-way: clear the declaration surface FIRST, then move the dependency.
+ * The published declarations are checked for pg references on every release,
+ * so the surface cannot silently grow one back.
+ *
+ * So these are the pg shapes, declared natively. They are not a new parallel
+ * abstraction: `PgCompatPool` / `PgCompatPoolClient` / `PgCompatQueryResult`
+ * are the SAME interfaces the external-pool seam has used since the serverless
+ * binding shipped (`TurbineConfig.pool`, `turbineHttp`, and the `SqlitePool` /
+ * `MysqlPool` / `MssqlPool` / `PowdbPool` engine shims), lifted out of
+ * client.ts so that `query/` can name them without an import edge back to the
+ * client (see `scripts/check-import-cycles.mjs`). client.ts re-exports all of
+ * them, so every existing `from './client.js'` import path is unchanged.
+ *
+ * A genuine `pg.Pool`, `pg.PoolClient` and `pg.QueryResult` each satisfy the
+ * matching interface here structurally, which is what keeps `pg` usable at
+ * every position Turbine accepts one. The reverse is NOT true and never was:
+ * an HTTP driver's pool is not a `pg.Pool`, which is why the fields pg alone
+ * provides (`totalCount`, the `error` event) are optional.
+ *
+ * `pg` itself remains a real runtime dependency. This module is about the
+ * TYPE surface only.
+ *
+ * @module
+ */
+export {};

package/dist/pipeline.d.ts

@@ -18,7 +18,7 @@
  * Sequential fallback covers HTTP-based drivers (Neon HTTP, Vercel Postgres, Cloudflare
  * Hyperdrive), mock pools in tests, and any pool that doesn't expose pg internals.
  */
-import type pg from 'pg';
+import type { PgCompatPool } from './pg-types.js';
 import type { DeferredQuery } from './query/index.js';
 export interface PipelineOptions {
     /**
@@ -52,7 +52,7 @@ export interface PipelineOptions {
  * ]);
  * ```
  */
-export declare function executePipeline<T extends readonly DeferredQuery<unknown>[]>(pool: pg.Pool, queries: T, options?: PipelineOptions): Promise<PipelineResults<T>>;
+export declare function executePipeline<T extends readonly DeferredQuery<unknown>[]>(pool: PgCompatPool, queries: T, options?: PipelineOptions): Promise<PipelineResults<T>>;
 /**
  * Check whether a pool supports the real pipeline protocol.
  * Call this to determine at runtime whether pipelines will use the fast path
@@ -60,7 +60,7 @@ export declare function executePipeline<T extends readonly DeferredQuery<unknown
  *
  * Note: This acquires and immediately releases a connection to inspect it.
  */
-export declare function pipelineSupported(pool: pg.Pool): Promise<boolean>;
+export declare function pipelineSupported(pool: PgCompatPool): Promise<boolean>;
 /**
  * Extract the result types from a tuple of DeferredQuery objects.
  * If you pass [DeferredQuery<User>, DeferredQuery<number>, DeferredQuery<Post[]>],

package/dist/query/batched-loader.d.ts

@@ -53,8 +53,8 @@
  *
  * @module
  */
-import type pg from 'pg';
 import type { PartitionLimitInput } from '../dialect.js';
+import type { PgCompatQueryResult } from '../pg-types.js';
 import { type RelationDef, type SchemaMetadata, type TableMetadata } from '../schema.js';
 import type { ReselectExecutor } from './builder.js';
 import type { SkipGlobalFilters, Unsafe, WithClause, WithCount } from './types.js';
@@ -66,7 +66,7 @@ interface Deferred {
     sql: string;
     params: unknown[];
     preparedName?: string;
-    transform: (result: pg.QueryResult) => unknown;
+    transform: (result: PgCompatQueryResult) => unknown;
 }
 /**
  * The read surface the loader needs from a child QueryInterface: build (but do

package/dist/query/builder.d.ts

@@ -10,7 +10,7 @@
  * Schema-driven: all column names, types, and relations come from introspected
  * metadata, nothing is hardcoded.
  */
-import type pg from 'pg';
+import type { PgCompatPool } from '../pg-types.js';
 import type { SchemaMetadata } from '../schema.js';
 import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, GroupByResult, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
 /**
@@ -381,7 +381,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * class-resident primitives they need without widening the public surface.
      */
     private readonly ctx;
-    constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    constructor(pool: PgCompatPool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
     /**
      * Dev-only, once per table: the columns whose database type is absent from
      * BOTH the column entry and the table-level type maps, the residual case

package/dist/query/builder.js

@@ -1897,9 +1897,18 @@ export class QueryInterface {
         const action = this.currentAction;
         // Build the query argument, use object form with `name` for prepared
         // statements, or the plain (text, values) form otherwise.
+        //
+        // The object form is not part of the PgCompatPool contract (the engine
+        // pool shims only speak `(text, values)`), so it is reached through a
+        // cast. Guarded at runtime by `preparedStatementsEnabled`, which only the
+        // drivers that accept it turn on.
         const usePrepared = preparedName && this.preparedStatementsEnabled;
         const exec = usePrepared
-            ? this.pool.query({ name: preparedName, text: sql, values: params })
+            ? this.pool.query({
+                name: preparedName,
+                text: sql,
+                values: params,
+            })
             : this.pool.query(sql, params);
         if (!timeout) {
             try {

package/dist/query/deferred.d.ts

@@ -3,8 +3,8 @@
  *
  * Split from builder.ts so the class file focuses on SQL assembly / execution.
  */
-import type pg from 'pg';
 import type { Dialect } from '../dialect.js';
+import type { PgCompatPool, PgCompatQueryResult } from '../pg-types.js';
 import type { SchemaMetadata } from '../schema.js';
 import type { QueryInterface } from './builder.js';
 import type { GlobalFilters, RelationLoadStrategy } from './types.js';
@@ -13,14 +13,14 @@ import type { GlobalFilters, RelationLoadStrategy } from './types.js';
  * {@link DeferredQuery.reselect} plan so it can run the write and the follow-up
  * SELECT through the same timeout/instrumentation path as the primary query.
  */
-export type ReselectExecutor = (sql: string, params: unknown[], preparedName?: string) => Promise<pg.QueryResult>;
+export type ReselectExecutor = (sql: string, params: unknown[], preparedName?: string) => Promise<PgCompatQueryResult>;
 export interface DeferredQuery<T> {
     /** SQL text with $1, $2 placeholders */
     sql: string;
     /** Bound parameter values */
     params: unknown[];
-    /** How to transform the raw pg.QueryResult into the final value */
-    transform: (result: pg.QueryResult) => T;
+    /** How to transform the raw driver result into the final value */
+    transform: (result: PgCompatQueryResult) => T;
     /** Tag for debugging / logging */
     tag: string;
     /** Prepared statement name (t_<16hex>). Set when SQL cache is enabled. */
@@ -33,7 +33,7 @@ export interface DeferredQuery<T> {
      * Absent for `'returning'`/`'output'` dialects (the statement returns its own
      * rows), so the PostgreSQL path never allocates or consults it.
      */
-    reselect?: (exec: ReselectExecutor) => Promise<pg.QueryResult>;
+    reselect?: (exec: ReselectExecutor) => Promise<PgCompatQueryResult>;
 }
 /**
  * How the ORM hands back a Postgres temporal `infinity` / `-infinity`.
@@ -269,5 +269,5 @@ export interface QueryInterfaceOptions {
      * own query language instead of SQL. The SQL dialects never set this, so their
      * `table()` behavior is byte-identical.
      */
-    queryInterfaceFactory?: (pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares: MiddlewareFn[], options: QueryInterfaceOptions) => QueryInterface<object>;
+    queryInterfaceFactory?: (pool: PgCompatPool, table: string, schema: SchemaMetadata, middlewares: MiddlewareFn[], options: QueryInterfaceOptions) => QueryInterface<object>;
 }

package/dist/query/filters.d.ts

@@ -46,17 +46,23 @@ export declare const COLUMN_REF_OPERATORS: Set<string>;
  * dependency is fixed: `cli/` and the prisma-compat shim may import from the
  * query path, and the query path may never import from `cli/`
  * (`scripts/check-import-cycles.mjs`).
+ *
+ * ## STATUS: a landing spot, not yet a deduplication. Read this before trusting it.
+ *
+ * NOTHING IMPORTS THIS YET. The three copies listed above are all still in
+ * place and still hand-synced; declaring the canonical home did not by itself
+ * move any of them onto it. It is kept, rather than deleted as unused, because
+ * `cli/pii-predicate-guard.ts` names this module as where its own copy wants to
+ * go, and deleting the destination is the one change that makes converging
+ * harder. Wiring the copies up is a separate change: each one sits on a
+ * different walk, so each has to be re-tested on its own.
+ *
+ * So do not read this constant as evidence that the walkers agree. The comment
+ * on each copy is still the only thing holding them in step.
  */
 export declare const RELATION_FILTER_WRAPPERS: readonly ["some", "none", "every", "is", "isNot"];
 /** {@link RELATION_FILTER_WRAPPERS} as a membership set, for the walkers. */
 export declare const RELATION_FILTER_WRAPPER_SET: ReadonlySet<string>;
-/**
- * True when a normalized relation-filter body carries at least one cardinality
- * wrapper. THE predicate the SQL compiler branches on: a key that names a
- * relation but whose value is not one of these falls through to the scalar
- * path.
- */
-export declare function hasRelationFilterWrapper(filterObj: Record<string, unknown>): boolean;
 /**
  * Check if an operator value is a column reference: a plain object whose ONLY
  * key is `col` with a string value. Anything else (extra keys, non-string