turbine-orm 0.18.0 → 0.19.1

package/dist/query.d.ts

@@ -1,878 +0,0 @@
-/**
- * turbine-orm — Query builder
- *
- * Each table accessor (db.users, db.posts, etc.) returns a QueryInterface<T>
- * that builds parameterized SQL and executes it through the connection pool.
- *
- * Nested relations use json_build_object + json_agg subqueries for single-query
- * resolution — a PostgreSQL-native approach that eliminates N+1 query patterns.
- *
- * Schema-driven: all column names, types, and relations come from introspected
- * metadata — nothing is hardcoded.
- */
-import type pg from 'pg';
-import type { SchemaMetadata } from './schema.js';
-/**
- * Quote a SQL identifier (table name, column name) using Postgres double-quote
- * rules: wrap in double quotes, escape internal double quotes by doubling them.
- *
- * @example
- *   quoteIdent('users')       → '"users"'
- *   quoteIdent('my"table')    → '"my""table"'
- *   quoteIdent('user name')   → '"user name"'
- */
-export declare function quoteIdent(name: string): string;
-export type OrderDirection = 'asc' | 'desc';
-/** Operator object for advanced where filtering */
-export interface WhereOperator<V = unknown> {
-    gt?: V;
-    gte?: V;
-    lt?: V;
-    lte?: V;
-    not?: V | null;
-    in?: V[];
-    notIn?: V[];
-    contains?: string;
-    startsWith?: string;
-    endsWith?: string;
-    /** Set to 'insensitive' to use ILIKE instead of LIKE for string comparisons */
-    mode?: 'default' | 'insensitive';
-}
-/**
- * A where value can be:
- * - A plain value (equality: column = $N)
- * - null (column IS NULL)
- * - An operator object ({ gt: 5, lte: 10 })
- * - A JSONB filter object ({ contains, equals, path, hasKey })
- * - An array filter object ({ has, hasEvery, hasSome, isEmpty })
- */
-export type WhereValue<V = unknown> = V | WhereOperator<V> | JsonFilter | ArrayFilter | null;
-/**
- * Where clause type: each field can be a plain value, null, or operator object.
- * Special keys: OR for disjunctive conditions.
- * Relation names can be used with some/every/none sub-filters.
- */
-export type WhereClause<T> = {
-    [K in keyof T]?: WhereValue<T[K]>;
-} & {
-    OR?: WhereClause<T>[];
-    AND?: WhereClause<T>[];
-    NOT?: WhereClause<T>;
-    /** Relation filters — keyed by relation name, value is { some, every, none } */
-    [relationName: string]: unknown;
-};
-/**
- * Unparameterized with clause — accepts any relation name.
- * Used internally by the query builder at runtime.
- */
-export interface WithClause {
-    [relation: string]: true | WithOptions;
-}
-/**
- * Relation-aware with clause. When R (the relations map) is provided,
- * only keys from R are autocompleted. Used in public method signatures
- * so the compiler can narrow the return type.
- *
- * For typed maps, each relation accepts either `true` (default include) or a
- * {@link WithOptions} object whose nested `with` is keyed against the relation
- * target's own relations interface — this is what enables deep
- * `WithResult` inference.
- */
-export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ? WithClause : {
-    [K in keyof R]?: true | WithOptions<RelationRelations<R[K]> & object>;
-};
-/**
- * Options for an included relation.
- *
- * Generic over `NestedR` — the relations interface of the *target* entity —
- * so the nested `with` clause is autocompleted with the correct relation keys
- * and so {@link WithResult} can recursively infer the return type. Defaults to
- * `{}` (no relation suggestions) for callers that use the unparameterized
- * {@link WithClause}.
- */
-export interface WithOptions<NestedR extends object = {}> {
-    with?: TypedWithClause<NestedR>;
-    where?: Record<string, unknown>;
-    orderBy?: Record<string, OrderDirection>;
-    limit?: number;
-    /** Only include these fields from the relation */
-    select?: Record<string, boolean>;
-    /** Exclude these fields from the relation */
-    omit?: Record<string, boolean>;
-}
-/**
- * A relation descriptor used by generated `*Relations` interfaces to make deep
- * `with` clause inference work. It bundles three pieces of information that
- * `WithResult` needs to recurse through nested relations:
- *
- *  - `__target`     — the target entity type (e.g. `Post`)
- *  - `__cardinality`— `'many'` for hasMany, `'one'` for belongsTo / hasOne
- *  - `__relations`  — the target entity's relations interface (for further recursion)
- *
- * **Generator contract (Track 3):** the code generator emits `*Relations`
- * interfaces in the following shape so that `WithResult` can walk arbitrary
- * nesting depth:
- *
- * ```ts
- * export interface UserRelations {
- *   posts:   RelationDescriptor<Post,    'many', PostRelations>;
- *   profile: RelationDescriptor<Profile, 'one',  ProfileRelations>;
- * }
- * ```
- *
- * The brand fields are phantom — they exist only for type inference and have
- * no runtime representation. The runtime always sees the parsed entity values
- * (arrays for hasMany, single object or null for belongsTo / hasOne) — see the
- * cardinality projection inside {@link WithResult}.
- *
- * **Backward compatibility:** legacy generated code emitted bare types
- * (`posts: Post[]`, `profile: Profile | null`). `WithResult` still accepts that
- * shape via a fallback branch — it just cannot recurse into nested `with` for
- * those relations until the generator is updated.
- *
- * @typeParam Target      - The entity type the relation points at.
- * @typeParam Cardinality - `'many'` (array) or `'one'` (single object | null).
- * @typeParam Relations   - The target entity's own `*Relations` interface, or
- *                          `{}` if the target has no relations of its own.
- */
-export interface RelationDescriptor<Target, Cardinality extends 'one' | 'many', Relations extends object = {}> {
-    readonly __target?: Target;
-    readonly __cardinality?: Cardinality;
-    readonly __relations?: Relations;
-}
-/** Extract the target entity from a relation descriptor or bare relation type. */
-type RelationTarget<Rel> = Rel extends RelationDescriptor<infer Target, infer _C, infer _R> ? Target : Rel extends Array<infer Item> ? Item : Rel extends infer One | null ? One : Rel;
-/** Extract the target's relations map from a relation descriptor (or `{}` for bare types). */
-type RelationRelations<Rel> = Rel extends RelationDescriptor<infer _T, infer _C, infer R> ? R : {};
-/** Project the target type into its runtime shape (array for many, single for one). */
-type ApplyCardinality<Rel, Resolved> = Rel extends RelationDescriptor<infer _T, infer Cardinality, infer _R> ? Cardinality extends 'many' ? Resolved[] : Resolved | null : Rel extends Array<infer _Item> ? Resolved[] : Resolved | null;
-/**
- * Compute the result type when relations are included via `with`.
- *
- * Recursively walks the `with` clause, looking up each relation in `R` and:
- *
- *  1. If the relation is included with `true` (or no nested `with`), the
- *     relation's bare resolved type is grafted onto `T` (e.g. `posts: Post[]`).
- *  2. If the relation is included with a nested `with: {...}`, the recursion
- *     looks up the target entity's relations interface (via the
- *     {@link RelationDescriptor} brand fields the generator emits) and
- *     recursively applies `WithResult` to the nested target. Cardinality is
- *     re-applied at each level so a hasMany relation stays an array even after
- *     deep nesting.
- *
- * **When `R` is `{}` (the default):** the recursion short-circuits and the
- * function returns plain `T` — preserving the existing untyped escape hatch
- * for callers that have not generated typed clients.
- *
- * **When `R` does not contain the requested relations:** the unknown keys are
- * ignored (the runtime will throw a `RelationError`, but the type system stays
- * permissive so the legacy `WithClause` index signature still typechecks).
- *
- * @typeParam T - Base entity type (e.g. `User`).
- * @typeParam R - Relations map for `T` (e.g.
- *                `{ posts: RelationDescriptor<Post, 'many', PostRelations>; ... }`).
- *                Legacy bare shapes (`{ posts: Post[]; profile: Profile | null }`)
- *                are also accepted, but cannot recurse beyond one level.
- * @typeParam W - The `with` clause the user passed (e.g. `{ posts: true }` or
- *                `{ posts: { with: { comments: true } } }`).
- */
-export type WithResult<T, R extends object, W> = [keyof R] extends [never] ? T : W extends object ? [keyof W & keyof R] extends [never] ? T : T & {
-    [K in keyof W & keyof R]: W[K] extends true ? ApplyCardinality<R[K], RelationTarget<R[K]>> : W[K] extends {
-        with?: infer NestedW;
-    } ? NestedW extends object ? ApplyCardinality<R[K], WithResult<RelationTarget<R[K]>, RelationRelations<R[K]> & object, NestedW>> : ApplyCardinality<R[K], RelationTarget<R[K]>> : ApplyCardinality<R[K], RelationTarget<R[K]>>;
-} : T;
-export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> {
-    where: WhereClause<T>;
-    select?: Record<string, boolean>;
-    omit?: Record<string, boolean>;
-    with?: W;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-}
-export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> {
-    where?: WhereClause<T>;
-    select?: Record<string, boolean>;
-    omit?: Record<string, boolean>;
-    orderBy?: Record<string, OrderDirection>;
-    limit?: number;
-    offset?: number;
-    with?: W;
-    /** Cursor-based pagination: start after this row */
-    cursor?: Partial<T>;
-    /** Number of records to take (used with cursor) */
-    take?: number;
-    /** De-duplicate results by specified fields */
-    distinct?: (keyof T & string)[];
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-}
-export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> extends FindManyArgs<T, R, W> {
-    /**
-     * Number of rows to fetch per internal FETCH batch (default: 1000).
-     *
-     * Trade-off: larger batches reduce network round-trips (important for
-     * high-latency connections like Neon) but increase per-batch memory.
-     * At 1000 rows x ~500 bytes/row the default is ~500 KB per batch.
-     *
-     * When the total result set fits within one batch, the stream avoids
-     * cursor overhead entirely (no BEGIN / DECLARE / CLOSE / COMMIT) by
-     * using a speculative `SELECT ... LIMIT batchSize+1` first.
-     */
-    batchSize?: number;
-}
-export interface CreateArgs<T> {
-    data: Partial<T>;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-}
-export interface CreateManyArgs<T> {
-    data: Partial<T>[];
-    /** When true, adds ON CONFLICT DO NOTHING to skip duplicate rows */
-    skipDuplicates?: boolean;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-}
-/**
- * Atomic update operators for a field.
- *
- * `set` works on any type; `increment`, `decrement`, `multiply`, and `divide`
- * are only valid on numeric fields. They generate SQL like
- * `col = col + $n` (and the corresponding `-`, `*`, `/` variants) instead of
- * plain absolute assignments, so they are safe against concurrent writers —
- * the database performs the math atomically.
- *
- * @example
- *   db.posts.update({ where: { id: 5 }, data: { viewCount: { increment: 1 } } });
- */
-export type UpdateOperatorInput<V> = {
-    set: V;
-} | (V extends number ? {
-    increment: number;
-} : never) | (V extends number ? {
-    decrement: number;
-} : never) | (V extends number ? {
-    multiply: number;
-} : never) | (V extends number ? {
-    divide: number;
-} : never);
-/**
- * Update data — each field can be a plain value or an atomic operator object.
- * Back-compatible with `Partial<T>`: plain values still typecheck unchanged.
- */
-export type UpdateInput<T> = {
-    [K in keyof T]?: T[K] | UpdateOperatorInput<T[K]>;
-};
-export interface UpdateArgs<T> {
-    where: WhereClause<T>;
-    data: UpdateInput<T>;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-    /**
-     * Opt in to running this mutation when `where` resolves to an empty
-     * predicate (e.g. `{}` or `{ id: undefined }`). Default `false` — an
-     * empty predicate throws `ValidationError` to catch the common case of
-     * a filter value accidentally being `undefined`. Set this to `true` only
-     * when an unconditional mutation is the intended behaviour.
-     */
-    allowFullTableScan?: boolean;
-}
-export interface UpdateManyArgs<T> {
-    where: WhereClause<T>;
-    data: UpdateInput<T>;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-    /** See {@link UpdateArgs.allowFullTableScan}. */
-    allowFullTableScan?: boolean;
-}
-export interface DeleteArgs<T> {
-    where: WhereClause<T>;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-    /** See {@link UpdateArgs.allowFullTableScan}. */
-    allowFullTableScan?: boolean;
-}
-export interface DeleteManyArgs<T> {
-    where: WhereClause<T>;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-    /** See {@link UpdateArgs.allowFullTableScan}. */
-    allowFullTableScan?: boolean;
-}
-export interface UpsertArgs<T> {
-    where: WhereClause<T>;
-    create: Partial<T>;
-    update: Partial<T>;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-}
-export interface CountArgs<T> {
-    where?: WhereClause<T>;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-}
-export interface GroupByArgs<T> {
-    by: (keyof T & string)[];
-    where?: WhereClause<T>;
-    /** Include count of each group */
-    _count?: true;
-    /** Sum of numeric fields in each group */
-    _sum?: Partial<Record<keyof T & string, boolean>>;
-    /** Average of numeric fields in each group */
-    _avg?: Partial<Record<keyof T & string, boolean>>;
-    /** Minimum value of fields in each group */
-    _min?: Partial<Record<keyof T & string, boolean>>;
-    /** Maximum value of fields in each group */
-    _max?: Partial<Record<keyof T & string, boolean>>;
-    /** Order groups */
-    orderBy?: Record<string, OrderDirection>;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-}
-/** Arguments for the standalone aggregate method */
-export interface AggregateArgs<T> {
-    where?: WhereClause<T>;
-    /** Count all rows matching the filter */
-    _count?: true | Partial<Record<keyof T & string, boolean>>;
-    /** Sum of numeric fields */
-    _sum?: Partial<Record<keyof T & string, boolean>>;
-    /** Average of numeric fields */
-    _avg?: Partial<Record<keyof T & string, boolean>>;
-    /** Minimum value of fields */
-    _min?: Partial<Record<keyof T & string, boolean>>;
-    /** Maximum value of fields */
-    _max?: Partial<Record<keyof T & string, boolean>>;
-    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
-    timeout?: number;
-}
-/** Result type for aggregate queries */
-export interface AggregateResult<T> {
-    _count?: number | Record<string, number>;
-    _sum?: Partial<Record<keyof T & string, number | null>>;
-    _avg?: Partial<Record<keyof T & string, number | null>>;
-    _min?: Partial<Record<keyof T & string, unknown>>;
-    _max?: Partial<Record<keyof T & string, unknown>>;
-}
-/** Relation filter operators for where clauses */
-export interface RelationFilter {
-    some?: Record<string, unknown>;
-    every?: Record<string, unknown>;
-    none?: Record<string, unknown>;
-}
-/** JSONB query operators for where clauses */
-export interface JsonFilter {
-    /** Access nested path via #>> operator */
-    path?: string[];
-    /** Exact match: column @> value::jsonb (containment) */
-    equals?: unknown;
-    /** Containment check: column @> value::jsonb */
-    contains?: unknown;
-    /** Key existence check: column ? key */
-    hasKey?: string;
-}
-/** Array query operators for where clauses */
-export interface ArrayFilter {
-    /** Check if array contains a single value: value = ANY(column) */
-    has?: unknown;
-    /** Check if array contains ALL values: column @> ARRAY[...] */
-    hasEvery?: unknown[];
-    /** Check if array has ANY of the values: column && ARRAY[...] */
-    hasSome?: unknown[];
-    /** Check if array is empty: array_length(column, 1) IS NULL */
-    isEmpty?: boolean;
-}
-/** Cached SQL template paired with its prepared-statement name. */
-export interface SqlCacheEntry {
-    sql: string;
-    name: string;
-}
-/**
- * FNV-1a 64-bit hash returning 16 lowercase hex chars.
- * Single-loop string iteration. Uses BigInt for 64-bit math.
- *
- * @internal Exported for testing only.
- */
-export declare function fnv1a64Hex(s: string): string;
-/**
- * Derive a prepared-statement name from a SQL string.
- * Format: `t_<16hex>` — always 18 chars, well under NAMEDATALEN (63).
- *
- * @internal Exported for testing only.
- */
-export declare function sqlToPreparedName(sql: string): string;
-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;
-    /** Tag for debugging / logging */
-    tag: string;
-    /** Prepared statement name (t_<16hex>). Set when SQL cache is enabled. */
-    preparedName?: string;
-}
-/** Middleware function type — imported from client to avoid circular deps */
-type MiddlewareFn = (params: {
-    model: string;
-    action: string;
-    args: Record<string, unknown>;
-}, next: (params: {
-    model: string;
-    action: string;
-    args: Record<string, unknown>;
-}) => Promise<unknown>) => Promise<unknown>;
-/** Options passed from TurbineClient to QueryInterface */
-export interface QueryInterfaceOptions {
-    /** Default LIMIT applied to findMany() when no limit is specified */
-    defaultLimit?: number;
-    /**
-     * Log a one-time warning when {@link QueryInterface.findMany} is called
-     * without a `limit`. Defaults to `true` so that accidental unbounded
-     * queries are surfaced loudly during development. Pass `false` to silence
-     * the warning entirely (e.g. for CLI tooling that intentionally streams
-     * full tables).
-     */
-    warnOnUnlimited?: boolean;
-    /**
-     * Enable prepared statements. When true, queries are submitted with a
-     * `{ name, text, values }` object 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).
-     */
-    preparedStatements?: boolean;
-    /**
-     * Enable the SQL template cache. When true, repeated queries with the
-     * same shape (same keys, operators, relations — different values) reuse
-     * cached SQL text instead of rebuilding from scratch.
-     *
-     * Default: `true`. Set to `false` as a nuclear kill switch.
-     */
-    sqlCache?: boolean;
-}
-export declare class QueryInterface<T extends object, R extends object = {}> {
-    private readonly pool;
-    private readonly table;
-    private readonly schema;
-    private readonly tableMeta;
-    /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
-    private readonly sqlTemplateCache;
-    private readonly middlewares;
-    private readonly defaultLimit?;
-    private readonly warnOnUnlimited;
-    private readonly preparedStatementsEnabled;
-    private readonly sqlCacheEnabled;
-    /**
-     * Tracks tables that have already triggered an unlimited-query warning so
-     * the user is not spammed once per row. Per-instance state — each
-     * QueryInterface is bound to a single table, so this set will only ever
-     * contain at most one entry, but using a Set keeps the API consistent with
-     * the audit's "Set<string>" guidance and leaves room for future
-     * cross-table sharing.
-     */
-    private readonly warnedTables;
-    /** Cache hit/miss counters for diagnostics */
-    private cacheHits;
-    private cacheMisses;
-    /** Pre-computed column type lookups (avoids linear scans per query) */
-    private readonly columnPgTypeMap;
-    private readonly columnArrayTypeMap;
-    constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
-    /**
-     * Return cache hit/miss statistics for this QueryInterface instance.
-     * Useful for monitoring and benchmarking.
-     */
-    cacheStats(): {
-        hits: number;
-        misses: number;
-        hitRate: number;
-        size: number;
-    };
-    /**
-     * Look up or build a SQL template in the cache.
-     * On miss, calls `build()` to generate the SQL, stores the entry, and returns it.
-     * On hit, increments counters and returns the cached entry.
-     *
-     * When `sqlCache` is disabled, always calls `build()` without caching.
-     */
-    private acquireSql;
-    /**
-     * Reset the per-instance unlimited-query warning dedupe set.
-     * Exposed for tests so a single test process can verify the warning fires
-     * exactly once per table without bleeding state between assertions.
-     */
-    resetUnlimitedWarnings(): void;
-    /**
-     * Execute a pool.query with an optional timeout.
-     * If timeout is set, races the query against a timer and rejects on expiry.
-     * pg driver errors are translated to typed Turbine errors via wrapPgError.
-     */
-    private queryWithTimeout;
-    /**
-     * Execute a query through the middleware chain.
-     * If no middlewares are registered, executes directly.
-     *
-     * Middleware can inspect and log query parameters, modify results after execution,
-     * and measure timing. Note: query SQL is generated before middleware runs, so
-     * modifying params.args in middleware will NOT affect the executed SQL.
-     * To intercept queries before SQL generation, use the raw() method instead.
-     */
-    private executeWithMiddleware;
-    findUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
-    buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T | null>;
-    findMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>[]>;
-    /**
-     * Emit a one-time `console.warn` when {@link findMany} is called without an
-     * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.
-     *
-     * Deduped per QueryInterface instance via {@link warnedTables} so a busy
-     * loop calling `db.users.findMany()` thousands of times only logs once.
-     * Suppressed when `defaultLimit` is configured (the caller has already
-     * opted in to a bounded query) and when the user passed an explicit
-     * `limit`, `take`, or `cursor`.
-     */
-    private maybeWarnUnlimited;
-    buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T[]>;
-    /**
-     * Stream rows from a findMany query using PostgreSQL cursors.
-     * Returns an AsyncIterable that yields individual rows, fetching in batches internally.
-     *
-     * **Speculative fast-path:** Before opening a cursor, issues a single
-     * `SELECT ... LIMIT batchSize+1`. If the result fits within `batchSize`,
-     * all rows are yielded immediately with zero cursor overhead (no BEGIN /
-     * DECLARE / CLOSE / COMMIT). Only when the result overflows does the
-     * method fall back to the full cursor path.
-     *
-     * **Cursor path:** Uses DECLARE CURSOR within a dedicated transaction on a
-     * single pooled connection. The cursor is automatically closed and the
-     * connection released when iteration completes or is terminated early
-     * (e.g. `break` from `for await`).
-     *
-     * **Snapshot semantics note:** The speculative fast-path runs outside a
-     * transaction. If the result overflows and the cursor path is opened, the
-     * cursor runs in its own transaction — spanning two separate snapshots.
-     * For strict single-snapshot semantics, wrap the call in `$transaction`.
-     *
-     * @example
-     * ```ts
-     * for await (const user of db.users.findManyStream({ where: { orgId: 1 }, batchSize: 500 })) {
-     *   process.stdout.write(`${user.email}\n`);
-     * }
-     * ```
-     */
-    findManyStream<W extends TypedWithClause<R> = {}>(args?: FindManyStreamArgs<T, R, W>): AsyncGenerator<WithResult<T, R, W>, void, undefined>;
-    findFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
-    buildFindFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T | null>;
-    findFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>>;
-    buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T>;
-    findUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W>>;
-    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T>;
-    create(args: CreateArgs<T>): Promise<T>;
-    buildCreate(args: CreateArgs<T>): DeferredQuery<T>;
-    createMany(args: CreateManyArgs<T>): Promise<T[]>;
-    buildCreateMany(args: CreateManyArgs<T>): DeferredQuery<T[]>;
-    update(args: UpdateArgs<T>): Promise<T>;
-    buildUpdate(args: UpdateArgs<T>): DeferredQuery<T>;
-    delete(args: DeleteArgs<T>): Promise<T>;
-    buildDelete(args: DeleteArgs<T>): DeferredQuery<T>;
-    upsert(args: UpsertArgs<T>): Promise<T>;
-    buildUpsert(args: UpsertArgs<T>): DeferredQuery<T>;
-    updateMany(args: UpdateManyArgs<T>): Promise<{
-        count: number;
-    }>;
-    buildUpdateMany(args: UpdateManyArgs<T>): DeferredQuery<{
-        count: number;
-    }>;
-    deleteMany(args: DeleteManyArgs<T>): Promise<{
-        count: number;
-    }>;
-    buildDeleteMany(args: DeleteManyArgs<T>): DeferredQuery<{
-        count: number;
-    }>;
-    count(args?: CountArgs<T>): Promise<number>;
-    buildCount(args?: CountArgs<T>): DeferredQuery<number>;
-    groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
-    buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
-    aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
-    buildAggregate(args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;
-    /**
-     * Resolve select/omit options into a list of snake_case column names.
-     * Returns null if neither is provided (meaning all columns).
-     */
-    private resolveColumns;
-    /** Convert camelCase field name to snake_case column name (unquoted, for non-SQL uses) */
-    private toColumn;
-    /** Convert camelCase field name to a double-quoted SQL identifier */
-    private toSqlColumn;
-    /**
-     * Build a single SET clause entry for update/updateMany.
-     *
-     * Supports plain values and atomic operator objects ({ set, increment,
-     * decrement, multiply, divide }). An operator object is detected ONLY when
-     * it has EXACTLY one key that is one of the 5 operator keys — this avoids
-     * misinterpreting JSON column values like `{ set: 'x' }` as operators
-     * (real operator objects always have exactly one key, and a plain JSON
-     * payload that happens to have a single `set` key is extremely unusual).
-     * Multi-key objects are always treated as plain (JSON) values.
-     *
-     * Returns the SQL fragment (e.g., `"view_count" = "view_count" + $3`) and
-     * pushes any required params onto the shared params array so that WHERE
-     * clause numbering continues correctly afterward.
-     */
-    private buildSetClause;
-    /**
-     * Produce a value-invariant fingerprint of a where clause.
-     * Same keys + same operator shapes + same combinator structure => same string.
-     * Different values (e.g. id=1 vs id=999) => identical fingerprint.
-     *
-     * @internal Exposed as package-private for testing via class access.
-     */
-    fingerprintWhere(where: Record<string, unknown>): string;
-    /**
-     * Fingerprint a relation filter sub-where for some/every/none.
-     */
-    private fingerprintRelFilter;
-    /**
-     * Walk a where clause and push ONLY values into `params`, in the EXACT same
-     * order that `buildWhereClause` pushes them. Used on cache hit to fill params
-     * without rebuilding SQL.
-     *
-     * @internal Exposed as package-private for testing.
-     */
-    collectWhereParams(where: Record<string, unknown>, params: unknown[]): void;
-    /** Collect params from a relation filter sub-where. Mirrors buildSubWhereForRelation. */
-    private collectRelFilterParams;
-    /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
-    private collectOperatorParams;
-    /** Collect params from JSON filter. Mirrors buildJsonFilterClauses. */
-    private collectJsonFilterParams;
-    /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
-    private collectArrayFilterParams;
-    /**
-     * Produce a fingerprint for a `with` clause tree. Recursion mirrors
-     * buildSelectWithRelations / buildRelationSubquery.
-     *
-     * @internal Exposed as package-private for testing.
-     */
-    withFingerprint(withClause: WithClause | undefined, table?: string, depth?: number): string;
-    /**
-     * Collect params from a `with` clause tree. Mirrors buildSelectWithRelations +
-     * buildRelationSubquery param-push order.
-     */
-    private collectWithParams;
-    /**
-     * Collect params from a single relation subquery. Mirrors buildRelationSubquery.
-     */
-    private collectRelationSubqueryParams;
-    /**
-     * Fingerprint SET clauses for update/updateMany.
-     * Captures key names + operator types (set/increment/etc) but not values.
-     */
-    private fingerprintSet;
-    /**
-     * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
-     */
-    private collectSetParams;
-    /** Build WHERE clause from a where object (supports operators, NULL, OR) */
-    private buildWhere;
-    /**
-     * Refuse mutations with an empty predicate unless explicitly opted in.
-     *
-     * An empty `where` (e.g. `{}` or `{ id: undefined }`) resolves to a
-     * mutation with no filter — a common footgun when a caller's filter
-     * value accidentally resolves to `undefined`. This guard throws
-     * `ValidationError` in that case unless `allowFullTableScan: true`.
-     */
-    private assertMutationHasPredicate;
-    /**
-     * Build the inner WHERE expression (without the WHERE keyword).
-     * Returns null if no conditions exist.
-     * Supports: equality, operators, NULL, OR, AND, NOT, relation filters (some/every/none).
-     */
-    private buildWhereClause;
-    /**
-     * Build relation filter SQL: WHERE EXISTS / NOT EXISTS subquery
-     * Supports: some (EXISTS), every (NOT EXISTS ... NOT), none (NOT EXISTS)
-     */
-    private buildRelationFilter;
-    /**
-     * Build WHERE clause conditions for a relation filter subquery.
-     * Uses the target table's column mapping to resolve field names.
-     */
-    private buildSubWhereForRelation;
-    /**
-     * Build SQL clauses for a single operator object on a column.
-     * Each operator key becomes its own clause, all ANDed together.
-     */
-    private buildOperatorClauses;
-    /** Build ORDER BY clause from an object */
-    private buildOrderBy;
-    /** Parse a flat row: convert snake_case to camelCase + Date coercion */
-    private parseRow;
-    /** Parse a row that may contain JSON nested relation columns */
-    private parseNestedRow;
-    /**
-     * Build a SELECT clause that includes both base columns and nested relation subqueries.
-     *
-     * For each relation specified in the `with` clause, this method generates a correlated
-     * subquery using PostgreSQL's `json_agg(json_build_object(...))` pattern. The result
-     * is a single SQL SELECT clause that resolves the full object tree in one query --
-     * no N+1 problem.
-     *
-     * **How it works:**
-     * 1. Resolves the base columns for the root table (all columns, or a subset via `columnsList`).
-     * 2. Iterates over each key in the `with` clause, looking up the relation definition.
-     * 3. For each relation, delegates to {@link buildRelationSubquery} to generate a
-     *    correlated subquery that returns JSON (array for hasMany, object for belongsTo/hasOne).
-     * 4. Each subquery is aliased as the relation name in the final SELECT.
-     *
-     * **aliasCounter:** A shared `{ n: number }` object is passed through all nesting levels.
-     * Each call to `buildRelationSubquery` increments it to produce unique table aliases
-     * (`t0`, `t1`, `t2`, ...) across arbitrarily deep relation trees, preventing alias
-     * collisions in the generated SQL.
-     *
-     * **Example output:**
-     * ```sql
-     * "users"."id", "users"."name", "users"."email",
-     * (SELECT COALESCE(json_agg(json_build_object('id', t0."id", 'title', t0."title")), '[]'::json)
-     *   FROM "posts" t0 WHERE t0."user_id" = "users"."id") AS "posts"
-     * ```
-     *
-     * @param table - The root table name (e.g. `"users"`).
-     * @param withClause - An object mapping relation names to their include specs
-     *                     (`true` for default inclusion, or `WithOptions` for select/omit/where/orderBy/limit).
-     * @param params - Shared parameter array for parameterized values (`$1`, `$2`, ...).
-     *                 Nested where/limit values are pushed here to prevent SQL injection.
-     * @param columnsList - Optional subset of columns to include in the SELECT. When `null`
-     *                      or omitted, all columns from the table's schema metadata are used.
-     * @param depth - Current nesting depth, passed through to {@link buildRelationSubquery}
-     *                for circular-relation detection. Defaults to `0` at the top level.
-     * @param path - Breadcrumb trail of relation names traversed so far, used in error
-     *               messages when circular or too-deep nesting is detected.
-     * @returns A complete SELECT clause string (without the `SELECT` keyword) containing
-     *          base columns and relation subqueries.
-     */
-    private buildSelectWithRelations;
-    /**
-     * Generate a correlated subquery that returns JSON for a single relation.
-     *
-     * This is the core of Turbine's single-query nested relation strategy. For a given
-     * relation (e.g. `posts` on a `users` query), it produces a self-contained SQL subquery
-     * that PostgreSQL evaluates per parent row, returning either a JSON array (hasMany) or
-     * a single JSON object (belongsTo / hasOne).
-     *
-     * ### Algorithm overview
-     *
-     * 1. **Alias generation:** Allocates a unique alias (`t0`, `t1`, ...) from the shared
-     *    `aliasCounter` so that deeply nested subqueries never collide.
-     *
-     * 2. **Column resolution:** Honors `select` / `omit` options to control which columns
-     *    appear in the output JSON.
-     *
-     * 3. **`json_build_object`:** Builds a JSON object for each row by mapping camelCase
-     *    field names to their column values:
-     *    ```sql
-     *    json_build_object('id', t0."id", 'title', t0."title", 'createdAt', t0."created_at")
-     *    ```
-     *
-     * 4. **`json_agg` wrapping (hasMany):** For one-to-many relations, wraps the
-     *    `json_build_object` call in `json_agg(...)` to aggregate all matching child rows
-     *    into a JSON array. Uses `COALESCE(..., '[]'::json)` so the result is never NULL.
-     *    For belongsTo / hasOne, no aggregation is used -- just the single JSON object
-     *    with `LIMIT 1`.
-     *
-     * 5. **Correlation (WHERE clause):** Links the subquery to the parent row:
-     *    - **hasMany:** `alias.foreignKey = parentRef.referenceKey`
-     *      (e.g. `t0."user_id" = "users"."id"` -- child FK points to parent PK)
-     *    - **belongsTo / hasOne:** `alias.referenceKey = parentRef.foreignKey`
-     *      (e.g. `t0."id" = "posts"."author_id"` -- parent FK points to child PK)
-     *
-     * 6. **Recursion:** If the spec includes a nested `with` clause, this method calls
-     *    itself recursively for each nested relation, passing the current alias as
-     *    `parentRef`. The nested subquery appears as an additional key in the
-     *    `json_build_object` call, wrapped in `COALESCE(..., '[]'::json)`.
-     *    Depth is incremented and capped at 10 to guard against circular relations.
-     *
-     * 7. **LIMIT / ORDER BY wrapping:** For hasMany relations with `limit` or `orderBy`,
-     *    the query is restructured into a two-level form:
-     *    ```sql
-     *    SELECT COALESCE(json_agg(json_build_object(...)), '[]'::json)
-     *    FROM (
-     *      SELECT t0.* FROM "posts" t0
-     *      WHERE t0."user_id" = "users"."id"
-     *      ORDER BY t0."created_at" DESC
-     *      LIMIT $1
-     *    ) t0i
-     *    ```
-     *    This ensures LIMIT and ORDER BY apply to the raw rows *before* `json_agg`
-     *    aggregation. Without the inner subquery, LIMIT would be meaningless because
-     *    `json_agg` produces a single aggregated row.
-     *
-     * 8. **Parameter threading:** All user-supplied values (where filters, limit) are
-     *    pushed to the shared `params` array with `$N` placeholders. No string
-     *    interpolation of user data ever occurs -- all identifiers go through
-     *    `quoteIdent()` and all values are parameterized.
-     *
-     * ### Example output (hasMany with nested relation)
-     * ```sql
-     * SELECT COALESCE(json_agg(json_build_object(
-     *   'id', t0."id",
-     *   'title', t0."title",
-     *   'comments', COALESCE((
-     *     SELECT COALESCE(json_agg(json_build_object('id', t1."id", 'body', t1."body")), '[]'::json)
-     *     FROM "comments" t1 WHERE t1."post_id" = t0."id"
-     *   ), '[]'::json)
-     * )), '[]'::json) FROM "posts" t0 WHERE t0."user_id" = "users"."id"
-     * ```
-     *
-     * @param relDef - The relation definition from schema metadata (contains `to`, `type`,
-     *                 `foreignKey`, `referenceKey`).
-     * @param spec - Either `true` (include with defaults) or a `WithOptions` object that
-     *               can specify `select`, `omit`, `where`, `orderBy`, `limit`, and nested `with`.
-     * @param params - Shared parameter array. User-supplied values are pushed here and
-     *                 referenced as `$1`, `$2`, etc. in the generated SQL.
-     * @param parentRef - The alias (e.g. `"t0"`) or table name (e.g. `"users"`) of the
-     *                    parent query. Used to build the correlated WHERE clause that ties
-     *                    child rows to their parent row.
-     * @param aliasCounter - Shared mutable counter (`{ n: number }`) for generating unique
-     *                       table aliases (`t0`, `t1`, `t2`, ...) across all nesting levels.
-     *                       Each call increments `n` by 1.
-     * @param depth - Current nesting depth (starts at `0`). Incremented on each recursive
-     *                call. If it reaches 10, a {@link CircularRelationError} is thrown.
-     * @param path - Breadcrumb trail of relation/table names traversed so far
-     *               (e.g. `["users", "posts", "comments"]`). Used in the error message
-     *               when circular or too-deep nesting is detected.
-     * @returns A complete SQL subquery string (without surrounding parentheses) that
-     *          evaluates to a JSON array (hasMany) or a JSON object (belongsTo/hasOne).
-     */
-    private buildRelationSubquery;
-    /**
-     * Get the Postgres type for a column (e.g. 'jsonb', 'text', '_int4').
-     * Used to detect JSONB/array columns for specialized operators.
-     * Uses pre-computed Map for O(1) lookup instead of linear scan.
-     */
-    private getColumnPgType;
-    /**
-     * Get the Postgres base element type for an array column.
-     * E.g. '_text' → 'text', '_int4' → 'integer'
-     */
-    private getArrayElementType;
-    /**
-     * Build SQL clauses for JSONB filter operators on a column.
-     * Supports: path, equals, contains, hasKey.
-     */
-    private buildJsonFilterClauses;
-    /**
-     * Build SQL clauses for Array filter operators on a column.
-     * Supports: has, hasEvery, hasSome, isEmpty.
-     */
-    private buildArrayFilterClauses;
-    /**
-     * Get the Postgres array type for a column (used by UNNEST in createMany).
-     * Uses pre-computed Map for O(1) lookup instead of linear scan.
-     */
-    private getColumnArrayType;
-}
-export {};
-//# sourceMappingURL=query.d.ts.map