joist-core 2.3.0 → 2.4.0-next.10

package/build/queries/sql/query.d.mts

@@ -0,0 +1,887 @@
+import { ColumnCondition } from "../parsedConditions.mjs";
+import { SqlCondition, SqlPredicate, UnbrandedPredicate } from "../conditions.mjs";
+import { TypeInfo } from "../../serde/TypeInfo.mjs";
+import { EntityMetadata } from "../../EntityMetadata.mjs";
+import { AliasAssigner } from "./AliasAssigner.mjs";
+import { CheckInput, ExprFromInput, ExprInput, ExpressionSources, ExpressionValue } from "./expressions/types.mjs";
+import "./expressions/expression.mjs";
+import { Table, TableBrand, TableFor, TableSourceBrand, referenceJoinSource, tableMgmt } from "./Tables.mjs";
+import { BaseExpr, Expr, ExprContext, ExprLike, InnerJoin, LeftJoin, SqlFragment, selectKeyBrand } from "./Expr.mjs";
+import { CheckJoinInput, TreeEntries } from "./JoinTree.mjs";
+import { Entity } from "../../Entity.mjs";
+//#region src/queries/sql/query.d.ts
+/**
+ * `em.query`: SQL-shaped queries as plain object literals.
+ *
+ * A query is data, a `Query<S, J>` POJO, `{ from, join, where, groupBy, having, select, orderBy, ... }`
+ * in SQL evaluation order:
+ *
+ *   const [a, b] = tables(Author, Book);
+ *   const bookStats = query({ from: b, groupBy: [b.author_id], select: { authorId: b.author_id, n: b.id.count() } });
+ *   const rows = await em.query({
+ *     from: a,
+ *     join: [{ left: bookStats, on: bookStats.authorId.eq(a.id) }],
+ *     select: { name: a.first_name, n: bookStats.n },
+ *     orderBy: { n: "DESC" },
+ *   });
+ *   // rows: { name: string; n: number | undefined }[]   (undefined because of the LEFT join)
+ *
+ * `em.query(pojo)` runs it. `select` decides the row type: a bare table returns entities, an array of
+ * columns or a `{ key: expr }` object returns typed POJOs, and a bare subquery returns its rows.
+ *
+ * `query(pojo)` turns the *same* POJO into a value: a derived table with typed columns, a scalar
+ * expression, or an entity list. It is the one non-POJO step, and the subquery analog of `table(Author)`:
+ * to reference a query's columns, the outer query needs *values* for them, and no POJO can manufacture
+ * values keyed off its own `select` keys.
+ *
+ * `table()`/`tables()` and `query()` are the only free functions a query needs, plus the `sql` tagged
+ * template as the escape hatch for SQL with no modeled shape. Everything else is in-DSL: join kinds are
+ * keyword keys (`{ left: b, on }`), SQL functions are methods on
+ * expressions (`b.id.count()`, `b.title.max()`, `x.coalesce(0)`), conditions are methods
+ * (`a.age.gte(18)`), and pruning is `undefined`: an `undefined` condition drops out, and a join nothing
+ * references anymore drops with it (see "Pruning" below).
+ *
+ * User documentation: `docs/src/content/docs/features/queries-raw.md`.
+ */
+declare const subqueryBrand: unique symbol;
+declare const entityQueryBrand: unique symbol;
+declare const scalarQueryBrand: unique symbol;
+/** A query(...) value with any projection, for EXISTS and NOT EXISTS predicates. */
+type ExistsQuery = QueryTable<unknown, string> | EntityQuery<Entity> | {
+  readonly [scalarQueryBrand]: true;
+};
+/**
+ * A condition for a query's where, having, or join on clause. Combine conditions with and/or,
+ * or use exists/notExists to check whether a query(...) value returns any rows.
+ *
+ * I.e. `{ and: [a.age.gte(18), { exists: booksForAuthor }] }` selects adult Authors with Books,
+ * where `booksForAuthor` is `query({ from: b, where: b.author_id.eq(a.id), select: b.id })`.
+ */
+type QueryCondition = SqlPredicate | UnbrandedPredicate | (({
+  and: readonly (QueryCondition | undefined)[];
+  or?: never;
+  exists?: never;
+  notExists?: never;
+} | {
+  or: readonly (QueryCondition | undefined)[];
+  and?: never;
+  exists?: never;
+  notExists?: never;
+}) & {
+  pruneIfUndefined?: "any" | "all";
+}) | {
+  exists: ExistsQuery | undefined;
+  notExists?: never;
+  and?: never;
+  or?: never;
+} | {
+  notExists: ExistsQuery | undefined;
+  exists?: never;
+  and?: never;
+  or?: never;
+};
+/** Phantom type information carried by a table-shaped `query(...)` value. */
+interface QueryTableBrand<R, Name extends string> {
+  readonly __row: R;
+  readonly __name: Name;
+}
+/** @deprecated Renamed to `QueryTableBrand`; a `query(...)` value is a table shape, not only a subquery. */
+type SubqueryBrand<R, Name extends string> = QueryTableBrand<R, Name>;
+/** Anything that can be a source or be joined: an entity table or a table-shaped subquery. */
+type QuerySource = {
+  readonly [tableMgmt]: TableSourceBrand<string>;
+} | {
+  readonly [subqueryBrand]: QueryTableBrand<any, string>;
+};
+/** A generated entity table or table-shaped subquery that supports `select: source`. */
+type SelectableQuerySource = {
+  readonly [tableMgmt]: TableBrand<any, string>;
+} | {
+  readonly [subqueryBrand]: QueryTableBrand<any, string>;
+};
+/**
+ * A join entry (see `InnerJoin`/`LeftJoin` in `Expr.ts`): the expanded `{ inner: b, on }` form, or the
+ * entry a relation join factory returns (`a.books.as(b)`); joins to a subquery are always the expanded
+ * form, since a subquery has no FK metadata.
+ */
+type QueryJoin = InnerJoin<QuerySource, QueryCondition> | LeftJoin<QuerySource, QueryCondition>;
+type QueryJoinList = readonly (QueryJoin | undefined)[];
+/** A flat SQL join list or a domain relationship tree rooted at from. */
+type QueryJoinInput = QueryJoinList | Readonly<Record<string, unknown>>;
+/**
+ * Resolves tree bindings to join types for scope and result nullability.
+ * Deferring the extracted entry union avoids expanding recursive constraints in generic query signatures.
+ */
+type ResolvedJoins<F, J> = J extends QueryJoinList ? J : F extends TableFor<infer T extends Entity> ? TreeEntries<T, J> extends (infer E) ? readonly Extract<E, QueryJoin>[] : never : [];
+/**
+ * A CTE declaration: a `query(...)` value with named columns, i.e. a POJO or set-operation select.
+ *
+ * Entity-mode and scalar `query(...)` shapes are excluded: a CTE must be a table shape, so it needs
+ * columns.
+ */
+type WithSource = QueryTable<unknown, string>;
+/** One CTE or an array of them; an `undefined` entry prunes, like any other clause. */
+type WithInput = WithSource | readonly (WithSource | undefined)[];
+/** How a recursive CTE combines its two terms: `UNION ALL` keeps every row, `UNION` drops duplicates. */
+interface RecursiveOptions {
+  /** Defaults to `"all"`. `"distinct"` emits UNION, which stops a cyclic graph from looping forever. */
+  union?: "all" | "distinct";
+}
+/** An expression order-by entry, also returned by `expr.asc()` and `expr.desc()`. An undefined order prunes it. */
+type ExpressionOrderBy = {
+  readonly sort: ExprLike<unknown>;
+  readonly order: "ASC" | "DESC" | undefined;
+  readonly nulls?: "first" | "last";
+};
+type OrderByDirection = "ASC" | "DESC" | "ASC NULLS FIRST" | "ASC NULLS LAST" | "DESC NULLS FIRST" | "DESC NULLS LAST";
+/**
+ * A keyed `orderBy` entry, used alone or in an array, like `em.find`'s `orderBy: [{ firstName: "ASC" }]`.
+ *
+ * The keys are the keys of a POJO/subquery `select` (rendered as SQL output-column names, so ordering
+ * by an aggregate does not repeat its expression), or the entity's sortable fields in entity mode.
+ * An `undefined` direction prunes the entry, like any other condition. For expressions that are not
+ * in `select`, mix in `expr.asc()`/`expr.desc()` or `{ sort, order }` entries in the array form.
+ */
+type OrderByKeys<S> = S extends readonly NamedSelectExpression[] ? { readonly [K in SelectKey<S[number]>]?: OrderByDirection | undefined; } : S extends {
+  readonly [tableMgmt]: {
+    readonly __entity: infer T;
+  };
+} ? T extends Entity ? { readonly [K in keyof Table<T> as Table<T>[K] extends ExprLike<any> ? K : never]?: OrderByDirection | undefined; } : never : S extends ExprLike<unknown> ? never : { readonly [K in keyof S & string]?: OrderByDirection | undefined; };
+/** All sortable keys across select variants, not just the keys shared by every variant. */
+type OrderByKey<S> = S extends unknown ? keyof OrderByKeys<S> : never;
+/** Prevents a selected keyed sort from being silently mixed into an expression entry. */
+type CheckedExpressionOrderBy<S> = ExpressionOrderBy & (string extends OrderByKey<S> ? unknown : [S] extends [{
+  readonly [tableMgmt]: unknown;
+}] ? unknown : { readonly [K in Exclude<OrderByKey<S>, keyof ExpressionOrderBy>]?: never; });
+/** The select shapes: a source, scalar expression, named column array, or POJO naming result columns. */
+type QuerySelect = SelectableQuerySource | ExprLike<unknown> | readonly NamedSelectExpression[] | Record<string, SelectExpression>;
+/** A named projection value may be an existing expression or an inline expression literal. */
+type SelectExpression = ExprLike<unknown> | ExprInput;
+/** A physical or subquery column that retains the field name used for array-select result rows. */
+type NamedSelectExpression = ExprLike<unknown> & {
+  readonly [selectKeyBrand]: string;
+};
+/** Extracts the table property name carried by a column expression for array selects. */
+type SelectKey<S> = S extends {
+  readonly [selectKeyBrand]: infer K extends string;
+} ? K : never;
+/** Checks expression literals only inside named projections. */
+type CheckSelect<S> = S extends QuerySource | ExprLike<unknown> | readonly NamedSelectExpression[] ? unknown : { readonly [K in keyof S]: S[K] extends ExprInput ? CheckInput<S[K]> : unknown; };
+/**
+ * Everything but the source, in SQL evaluation order: FROM/JOIN, WHERE, GROUP BY, HAVING, SELECT,
+ * ORDER BY, LIMIT.
+ *
+ * `S` and `J` are generic so callers keep the literal shape of `select` and `join`; the defaults let
+ * a standalone object use `satisfies Query` (or `satisfies Clauses` for a source-less fragment).
+ */
+interface Clauses<S extends QuerySelect = QuerySelect, J extends QueryJoinInput = QueryJoinInput> {
+  /**
+   * CTEs to include in a `WITH` clause, declared as `query(...)` values; either a single value or an array.
+   *
+   * I.e. `{ with: bookStats, from: a, join: [{ left: bookStats, on: ... }], select: { n: bookStats.n } }`.
+   *
+   * An `undefined` entry is ignored, and a CTE that nothing else in the query references will be pruned,
+   * the same pruning `join` gets (see "Pruning"); `pruneJoins: false` keeps every CTE.
+   */
+  with?: WithInput;
+  /** A flat join list, or a domain relationship tree rooted at the entity table in from. */
+  join?: J;
+  /**
+   * An `{ and: [...] }` or `{ or: [...] }` group, an exists/notExists query, or a bare condition such as `a.age.gte(18)`.
+   *
+   * Arrays are shorthand for `{ and: [...] }`; undefined conditions are pruned.
+   */
+  where?: QueryCondition | readonly (QueryCondition | undefined)[];
+  groupBy?: readonly ExprLike<any>[];
+  having?: QueryCondition;
+  select: S;
+  orderBy?: readonly (CheckedExpressionOrderBy<S> | OrderByKeys<S> | undefined)[] | CheckedExpressionOrderBy<S> | OrderByKeys<S>;
+  limit?: number;
+  offset?: number;
+  distinct?: boolean;
+  /** Defaults to true. `false` keeps every join, em.find's opt-out. */
+  pruneJoins?: boolean;
+  /**
+   * Defaults to `"exclude"`, em.find's rule: a soft-deletable entity in `from` gains a
+   * `deleted_at IS NULL` condition in WHERE, and a joined one gains it in its join's ON (so a LEFT
+   * join nulls its columns out instead of dropping rows). `"include"` turns the injection off for
+   * this query; subqueries read their own key.
+   */
+  softDeletes?: "include" | "exclude";
+}
+/** A whole query: `Clauses` plus its source. `query(q)` turns it into a value; `em.query(q)` runs it. */
+interface Query<S extends QuerySelect = QuerySelect, J extends QueryJoinInput = QueryJoinInput> extends Clauses<S, J>, Partial<Record<SetOperation | MutationKey | "ctes", never>> {
+  from: QuerySource;
+}
+/**
+ * The six PostgreSQL set operations. Each compound root has exactly one operation.
+ *
+ * I.e. `union` removes duplicate projected Author names; `unionAll` keeps every copy.
+ */
+type SetOperation = "union" | "unionAll" | "intersect" | "intersectAll" | "except" | "exceptAll";
+/** Mutation clauses are forbidden even on nonliteral read inputs. */
+type MutationKey = "insert" | "update" | "delete" | "values" | "set" | "returning" | "allowAll";
+/**
+ * For set operations like UNION, this is one read operand with named POJO columns: an ordinary query,
+ * a reusable query value, or another compound.
+ * Scalar queries, expressions, and entity hydration are excluded.
+ *
+ * I.e. `{ from: a, select: { id: a.id } }` and its `query(...)` value can contribute Author IDs to a
+ * union. `{ from: a, select: a.id }` cannot: even one-column set operands must give that column a name.
+ */
+type SetOperand = Query<Record<string, SelectExpression> | QueryTable<unknown, string>> | QueryTable<unknown, string> | SetQuery<readonly SetOperand[]>;
+/**
+ * SQL-shaped compound input; use `satisfies SetQuery` to retain the operands' literal row types.
+ *
+ * I.e. for Author alias `a` and Book alias `b`:
+ * ```ts
+ * const names = {
+ *   union: [
+ *     { from: a, select: { name: a.first_name } },
+ *     { from: b, select: { name: b.title } },
+ *   ],
+ *   orderBy: { name: "ASC" },
+ * } satisfies SetQuery;
+ * ```
+ *
+ * The default operand tuple requires at least two reads. `query` and `em.query` also infer dynamically
+ * sized arrays; `CheckSetQuery` validates their row types, and runtime validation checks their length.
+ * This input shape checks direction values; `CheckSetQuery` checks the inferred output keys in orderBy.
+ */
+type SetQuery<Operands extends readonly SetOperand[] = readonly [SetOperand, SetOperand, ...SetOperand[]]> = { [K in SetOperation]: { readonly [P in K]: Operands; } & { readonly [P in Exclude<SetOperation, K>]?: never; }; }[SetOperation] & {
+  /** CTEs for the combined query, declared once and in scope for every operand; see `Clauses.with`. */
+  readonly with?: WithInput;
+  readonly orderBy?: Readonly<Record<string, OrderByDirection | undefined>> | readonly (Readonly<Record<string, OrderByDirection | undefined>> | undefined)[];
+  readonly limit?: number;
+  readonly offset?: number;
+  readonly as?: string;
+} & { readonly [K in "from" | "select" | "join" | "where" | "groupBy" | "having" | "distinct" | "softDeletes" | "pruneJoins" | MutationKey | "ctes"]?: never; };
+/**
+ * Extracts the operand collection from each possible compound root, ignoring pagination and ordering.
+ *
+ * I.e. for `Q = { union: readonly [typeof authorNames, typeof bookNames]; limit: 10 }`, the result is
+ * `readonly [typeof authorNames, typeof bookNames]`. Distributing over Q also handles a runtime choice
+ * between different operations; Extract discards optional, unused operation keys whose value is undefined.
+ */
+type OperandsOf<Q> = Q extends unknown ? Extract<Q[keyof Q & SetOperation], readonly SetOperand[]> : never;
+/**
+ * Gets the left operand, which supplies canonical output keys and the retained row type for EXCEPT/INTERSECT.
+ *
+ * I.e. `FirstOperand<{ except: readonly [typeof authorNames, typeof bookNames] }>` is `typeof authorNames`.
+ * For a dynamic array, the exact first element is unknown, so this is the array's element type instead.
+ */
+type FirstOperand<Q> = OperandsOf<Q>[0];
+/**
+ * Resolves the named rows of an ordinary or compound read operand, including its LEFT join nullability.
+ *
+ * I.e. a query from Author `a` with a LEFT-joined Book `b` and `select: { title: b.title }` has row type
+ * `{ title: string | undefined }`, even though Book.title is required. A reusable `query(...)` value already
+ * stores that row type in its brand; a nested compound combines its own operands recursively.
+ */
+type ReadQueryRow<Q> = SetOperand extends Q ? unknown : Q extends {
+  readonly [subqueryBrand]: {
+    readonly __row: infer R;
+  };
+} ? R : Q extends {
+  select: infer S;
+} ? QueryRow<S, ResolvedJoins<Q[keyof Q & "from"], "join" extends keyof Q ? Extract<Q[keyof Q & "join"], QueryJoinInput> : []>> : [OperandsOf<Q>] extends [never] ? never : SetQueryRow<Q>;
+/**
+ * UNION combines each column's values; INTERSECT and EXCEPT conservatively retain the left row.
+ *
+ * I.e. Author first names projected as `{ name: string }` unioned with LEFT-joined Book titles projected
+ * as `{ name: string | undefined }` produce `{ name: string | undefined }`. EXCEPT with those Author names on
+ * the left retains `{ name: string }`; it neither adds the right side's absence nor promises narrower values.
+ *
+ * The outer conditional distributes over a TypeScript union of alternative queries. I.e. a runtime
+ * choice between an Author-name UNION and a Book-order EXCEPT must retain `{ name: string } | { order: number }`.
+ */
+type SetQueryRow<Q> = Q extends unknown ? { -readonly [K in keyof ReadQueryRow<FirstOperand<Q>>]: ColumnValue<Q extends {
+  union: readonly SetOperand[];
+} | {
+  unionAll: readonly SetOperand[];
+} ? ReadQueryRow<OperandsOf<Q>[number]> : ReadQueryRow<FirstOperand<Q>>, K>; } : never;
+/**
+ * Collects column K's value from each row alternative in R, rather than requiring K on every alternative.
+ *
+ * I.e. `ColumnValue<{ name: string } | { name: string | null }, "name">` is `string | null`.
+ * An alternative without K contributes never; `CompatibleRow` separately rejects mismatched operand keys.
+ */
+type ColumnValue<R, K extends PropertyKey> = R extends unknown ? (K extends keyof R ? R[K] : never) : never;
+/**
+ * Checks whether either non-null value type is assignable to the other, without requiring equal nullability.
+ *
+ * I.e. `CompatibleValue<number, number | null>` is true, while `CompatibleValue<AuthorId, BookId>` is false.
+ * This is only a TypeScript check: Author.age and Author.age.sum() both pass as numbers, but runtime
+ * output-type checks must still reject their different int4/int8 representations.
+ */
+type CompatibleValue<L, R> = [NonNullable<L>] extends [NonNullable<R>] ? true : [NonNullable<R>] extends [NonNullable<L>] ? true : false;
+/**
+ * Requires exactly the same output keys and compatible TypeScript values for every column.
+ *
+ * I.e. `L = { name: string; age: number }` and `R = { age: number | null; name: string }` are compatible despite
+ * key order and nullability. `{ name: string }` and `{ title: string }` are not. SQL representations and
+ * codec domains still need runtime validation; this boolean does not establish decoder compatibility.
+ */
+type CompatibleRow<L, R> = [keyof L] extends [keyof R] ? [keyof R] extends [keyof L] ? false extends { [K in keyof L]: CompatibleValue<L[K], ColumnValue<R, K>>; }[keyof L] ? false : true : false : false;
+/**
+ * Produces a constraint for Q: unknown leaves a valid operand unchanged, while a message rejects it.
+ *
+ * I.e. First can select Author.firstName as `name` and Q can select Book.title as `name`. Both pass.
+ * Changing Q's key to `title` produces the key/value diagnostic. A nested compound must also pass its own
+ * arity and ordering checks, not merely expose a compatible result row.
+ */
+type CheckOperand<First, Q> = CompatibleRow<ReadQueryRow<First>, ReadQueryRow<Q>> extends true ? Q extends SetQuery<readonly SetOperand[]> ? CheckSetQuery<Q> : CheckReadQuery<Q> : "set operands must have the same keys and compatible column values";
+/**
+ * Checks every operand against O[0] while preserving the collection's tuple shape and readonly modifier.
+ *
+ * I.e. compatible operands `O = readonly [typeof authorNames, typeof bookNames]` produce
+ * `readonly [unknown, unknown]` constraints. Mapping O directly preserves length instead of validating
+ * array methods and the length property as though they were additional query operands.
+ */
+type CheckOperands<O extends readonly SetOperand[]> = { readonly [I in keyof O]: CheckOperand<O[0], O[I]>; };
+/**
+ * Restricts each ordering hash to Keys, including hashes supplied through variables or readonly arrays.
+ *
+ * I.e. with `Keys = "name"`, `{ name: "ASC" }` and `[undefined, { name: "DESC" }]` pass, but a `title`
+ * key receives a diagnostic. SetQuery already restricts direction values; this check does not replace them.
+ */
+type CheckSetOrder<O, Keys> = O extends readonly unknown[] ? { readonly [I in keyof O]: CheckSetOrder<O[I], Keys>; } : { readonly [K in keyof O]: K extends Keys ? unknown : "orderBy must name a set output column"; };
+/**
+ * Validate known tuples and output ordering without widening the inferred operand projections.
+ * Preserve optional keys when TypeScript infers a runtime choice between different operations.
+ *
+ * I.e. `{ union: [authorNames] as const }` fails minimum arity; a `typeof authorNames[]` can pass the
+ * static checks but still needs a runtime length check. If authorNames and bookNames both expose only
+ * `name`, combining them with `orderBy: { title: "ASC" }` fails the output-key check.
+ *
+ * The result is intersected with the inferred input Q. Unknown constraints leave its literal types
+ * intact; error messages make the offending operands or ordering keys incompatible with that input.
+ */
+type CheckSetQuery<Q extends SetQuery<readonly SetOperand[]>> = Q extends unknown ? SetOperand extends FirstOperand<Q> ? "set operands were typed too generically; use `satisfies SetQuery` instead" : { readonly [K in keyof Q]: K extends SetOperation ? Q[K] extends readonly SetOperand[] ? number extends Q[K]["length"] ? CheckOperands<Q[K]> : Q[K] extends readonly [SetOperand, SetOperand, ...SetOperand[]] ? CheckOperands<Q[K]> : "set operations require at least two operands" : never : unknown; } & CheckReadQuery<Q> & {
+  readonly orderBy?: CheckSetOrder<Q["orderBy"], keyof ReadQueryRow<FirstOperand<Q>>>;
+} : never;
+/**
+ * Rejects unknown clauses on concrete read inputs, recursively through compound operands.
+ * Intersect this with an inferred Q; a widened annotation cannot reveal keys already erased from its type.
+ * I.e. an INSERT source with `select: { title: b.title }` and `ctes: [...]` must not silently discard the CTEs.
+ */
+type CheckReadQuery<Q> = SetOperand extends Q ? unknown : Q extends readonly unknown[] ? { readonly [I in keyof Q]: CheckReadQuery<Q[I]>; } : Q extends {
+  readonly [subqueryBrand]: QueryTableBrand<infer R, string>;
+} ? { readonly [K in keyof Q]: K extends keyof R | typeof subqueryBrand ? unknown : never; } : Q extends {
+  readonly [entityQueryBrand]: unknown;
+} ? { readonly [K in keyof Q]: K extends typeof entityQueryBrand ? unknown : never; } : Q extends {
+  readonly from: unknown;
+  readonly select: unknown;
+} ? CheckJoinInput<Q["from"], "join" extends keyof Q ? Exclude<Q[keyof Q & "join"], undefined> : []> & { readonly [K in keyof Q]: K extends "select" ? CheckSelect<Q[K]> : K extends keyof Clauses | "from" | "as" ? unknown : never; } : { readonly [K in keyof Q]: K extends SetOperation ? Q[K] extends readonly unknown[] ? CheckReadQuery<Q[K]> : unknown : K extends "with" | "orderBy" | "limit" | "offset" | "as" ? unknown : never; };
+/** The type-level name of a table or subquery, i.e. `"Author"` or `"book_stats"`. */
+type NameOf<A> = A extends {
+  readonly [tableMgmt]: {
+    readonly __name: infer N;
+  };
+} ? N : A extends {
+  readonly [subqueryBrand]: {
+    readonly __name: infer N;
+  };
+} ? N : never;
+/** The names of every alias that was LEFT JOINed; `X` is a naked type parameter so this distributes. */
+type LeftJoined<X> = X extends LeftJoin<infer A> ? NameOf<A> : never;
+/** Adds default reference targets whose source is already nullable; explicit INNER joins do not inherit. */
+type InheritedLeft<X, Left> = X extends {
+  readonly [referenceJoinSource]: infer Src;
+  readonly inner: infer A;
+} ? [Extract<Src, Left>] extends [never] ? never : NameOf<A> : never;
+/**
+ * Finds all aliases that can be NULL through LEFT joins and subsequent reference joins.
+ * I.e. LEFT Book adds Author via Book.author.as(a), then further required references inherit Author's NULL.
+ * Alias-name collisions are conservative, as they are for explicit LEFT joins; runtime uses exact handles.
+ */
+type NullableSources<X, Left = LeftJoined<X>> = [Exclude<InheritedLeft<X, Left>, Left>] extends [never] ? Left : NullableSources<X, Left | InheritedLeft<X, Left>>;
+/**
+ * Asks: is this expression's source key among the LEFT-joined sources in this query's join list? If
+ * yes, SQL can return NULL, so `R` becomes `R | null`; if no, `R` is unchanged.
+ *
+ * I.e. `MaybeNull<number, "book_stats", [LeftJoin<typeof bookStats>]>` is `number | null`,
+ * because `book_stats` is in `NullableSources<J[number]>`; with an inner join it stays `number`.
+ * Default references from nullable sources are included transitively.
+ *
+ * Source-less expressions (`Src` is `never`, i.e. `b.id.count()`) are never nullified. Untracked ones
+ * (`Src` is `string`, i.e. a table whose entity type is not statically known) might come from any left-joined table,
+ * so they are conservatively nullified whenever the query has a left join at all.
+ *
+ * `string` must never be a *table's* name: `Extract<"Author", string>` matches, so one left-joined
+ * table named `string` would nullify every column in the query. That is why anonymous subqueries
+ * share the literal sentinel `"?"` instead.
+ */
+type MaybeNull<R, Src extends string, J extends QueryJoinList> = string extends Src ? [NullableSources<J[number]>] extends [never] ? R : R | null : [Extract<Src, NullableSources<J[number]>>] extends [never] ? R : R | null;
+/**
+ * The result row for a query with select `S` and joins `J`.
+ *
+ * - entity mode (`select: a`) is the entity
+ * - subquery mode (`select: bookStats`) is the subquery's row, i.e. `select *`
+ * - single expression (`select: b.id.count()`) is that expression's value, used by scalar subqueries
+ * - column array mode uses each column's field name as the result key
+ * - POJO mode is a mapped type over the select keys, with left-join nullability applied
+ */
+type QueryRow<S, J extends QueryJoinList = []> = S extends {
+  readonly [tableMgmt]: {
+    readonly __entity: infer T;
+  };
+} ? T : S extends {
+  readonly [subqueryBrand]: {
+    readonly __row: infer R;
+  };
+} ? R : S extends ExprLike<unknown> ? QueryResultValue<ExpressionValue<S, J>> : S extends readonly NamedSelectExpression[] ? { -readonly [E in S[number] as SelectKey<E>]: QueryResultValue<ExpressionValue<E, J>>; } : { -readonly [K in keyof S]: S[K] extends SelectExpression ? QueryResultValue<ExpressionValue<S[K] extends ExprInput ? ExprFromInput<S[K]> : S[K], J>> : never; };
+/**
+ * Converts top-level SQL NULL to Joist's public undefined convention.
+ *
+ * Column metadata and expressions retain `T | null` because null is an explicit SQL value used by
+ * predicates, assignments, and functions such as COALESCE. Undefined instead means an omitted input.
+ * Keeping that distinction also lets reusable queries become SQL expressions without changing domains.
+ * The conversion therefore happens only at the executed-row boundary; nested array and JSON nulls remain null.
+ */
+type QueryResultValue<V> = Exclude<V, null> | (null extends V ? undefined : never);
+/**
+ * Restores SQL NULL when a public query result is reused as an expression or mutation source.
+ *
+ * A future alternative is to retain both domains on every expression, i.e.
+ * `Expr<Sql, Src extends string = string, Result = QueryResultValue<Sql>>`. QueryRow could then use Result
+ * while predicates and reusable queries use Sql, avoiding this reverse conversion without making the
+ * common expression declaration verbose.
+ */
+type SqlExpressionValue<V> = Exclude<V, undefined> | (undefined extends V ? null : never);
+/**
+ * A table-shaped query: one `Expr` per select key, each tagged with the table's name as its `Src`,
+ * plus a brand carrying the row type. This is the direct analog of `Table<T>`: `Table<T>` maps physical
+ * columns to expressions, `QueryTable<Row, Name>` maps the inner query's select keys to expressions.
+ *
+ * It is a table, not only a subquery: the same value can be the `from`, be joined, or be a `with` entry.
+ */
+type QueryTable<R, Name extends string> = {
+  readonly [subqueryBrand]: QueryTableBrand<R, Name>;
+} & { readonly [K in keyof R]: Expr<SqlExpressionValue<R[K]>, Name> & {
+  readonly [selectKeyBrand]: Extract<K, string>;
+}; };
+/** @deprecated Renamed to `QueryTable`; the value is a table shape, usable as a `with` entry too. */
+type Subquery<R, Name extends string> = QueryTable<R, Name>;
+/** An entity-mode query (`select: a`): runnable, but it has no columns to reference. */
+type EntityQuery<T extends Entity> = {
+  readonly [entityQueryBrand]: {
+    readonly __row: T;
+  };
+} & Partial<Record<MutationKey | "with" | "ctes", never>>;
+/** A scalar/list query that remains distinguishable from ordinary expressions for EXISTS. */
+type ScalarQuery<R> = Expr<SqlExpressionValue<R> | null, never> & {
+  readonly [scalarQueryBrand]: true;
+};
+/**
+ * Rejects a `select` that a `: Query` annotation widened to the whole `QuerySelect` union.
+ *
+ * `satisfies Query` checks the shape but keeps the literal type of `select`, so `S` infers as
+ * `{ name: Expr<string, "Author"> }`. A `: Query` annotation replaces that type with the annotation, so
+ * `S` infers as `QuerySelect` itself, and without this guard `query(q)` returned a useless union with no
+ * error at all.
+ *
+ * A widened `S` is the only kind of `S` the whole `QuerySelect` union is assignable to (a POJO, an
+ * `Expr`, or a `Table` never is), so `QuerySelect extends S` detects it, and intersecting the parameter
+ * with `{ select: "<message>" }` fails the call on `select` with that message, for `query()` and
+ * `em.query()` alike:
+ *
+ *   const narrow = { from: a, select: { name: a.first_name } } satisfies Query;
+ *   query(narrow); // QueryTable<{ name: string }, "?">
+ *
+ *   const widened: Query = { from: a, select: { name: a.first_name } };
+ *   query(widened);
+ *   // error: Type 'QuerySelect' is not assignable to type
+ *   //   '"select was typed too generically; use `satisfies Query` instead of `: Query`"'
+ *
+ * `S` also defaults to `never`, so a *missing* `select` is reported as "Property 'select' is missing"
+ * against `Query<never, []>` instead of tripping this guard.
+ */
+type NotWidened<S> = QuerySelect extends S ? {
+  select: "select was typed too generically; use `satisfies Query` instead of `: Query`";
+} : unknown;
+/** What `query()` returns, by select shape: an entity list, a scalar/list subquery, or a derived table. */
+type QueryValue<S, J extends QueryJoinList, Name extends string> = S extends {
+  readonly [tableMgmt]: {
+    readonly __entity: infer T extends Entity;
+  };
+} ? EntityQuery<T> : S extends ExprLike<unknown> ? ScalarQuery<QueryRow<S, J>> : QueryTable<QueryRow<S, J>, Name>;
+/** The names of every alias in scope for a query: the source alias plus every joined alias. */
+type JoinedName<X> = X extends {
+  readonly inner: infer A;
+} ? NameOf<A> : X extends {
+  readonly left: infer A;
+} ? NameOf<A> : never;
+type InScope<F, J extends QueryJoinList> = NameOf<F> | JoinedName<J[number]>;
+/**
+ * Asks, for every column of a POJO select: is its source key among `from` + `join` at all? If no, the
+ * query reads from a table it never joined, and that select key's type becomes an error message.
+ *
+ * Because `Expr` already carries `Src`, this is nearly free: for each select key, if `Src` is tracked
+ * and any of its names is outside `InScope`, intersect that key's type with an error string, so the
+ * caller sees `Type 'Expr<number, "book_stats">' is not assignable to type '... is not in from/join'`.
+ * Untracked (`string`) and source-less (`never`) expressions always pass. Tables with the same
+ * type-level name (two bare `table(Author)`, or two anonymous tables) cannot be told apart, so a miss
+ * there goes unreported; the check never gives a false positive, only false negatives on collisions.
+ *
+ * `[S] extends [...]` keeps this non-distributive, and `never` is skipped outright: `query()` defaults
+ * `S` to `never` when `select` is missing, and a distributive conditional over `never` would swallow the
+ * whole parameter type.
+ */
+type CheckScope<S, F, J extends QueryJoinInput> = [S] extends [never] ? unknown : [S] extends [QuerySource] ? NameOf<S> extends NameOf<F> ? unknown : {
+  select: `'${NameOf<S> & string}' is a joined source, not the from; select its columns individually`;
+} : [S] extends [readonly NamedSelectExpression[]] ? {
+  select: { [K in keyof S]: CheckExpressionScope<S[K], InScope<F, ResolvedJoins<F, J>>>; };
+} : [S] extends [Record<string, SelectExpression>] ? {
+  select: { [K in keyof S]: CheckExpressionScope<S[K], InScope<F, ResolvedJoins<F, J>>>; };
+} : unknown;
+/** Includes columns nested in inline CASE values and fallbacks in the existing scope check. */
+type CheckExpressionScope<V, Scope> = string extends ExpressionSources<V> ? unknown : [Exclude<ExpressionSources<V>, Scope>] extends [never] ? unknown : `table '${Exclude<ExpressionSources<V>, Scope> & string}' is not in from/join`;
+/** The one argument type `query()` and `em.query()` share: a `Query` POJO plus its source, name, and checks. */
+type QueryArg<F extends QuerySource, S extends QuerySelect, J extends QueryJoinInput, Name extends string> = Query<S, J> & {
+  from: F;
+  as?: Name;
+} & CheckScope<S, F, J> & NoInfer<CheckJoinInput<F, J>> & NotWidened<S> & {
+  select: CheckSelect<NoInfer<S>>;
+};
+/**
+ * Turns a `Query` POJO into a value. The select shape decides which (`QueryValue`):
+ *
+ * - a single expression is a scalar subquery or an IN list (`Expr<R | null>`; a scalar subquery can
+ *   return no row, so use `.coalesce(0)` when the SQL guarantees a value, i.e. an ungrouped `count`)
+ * - an entity table is an entity list, runnable via `em.query`
+ * - a POJO is a derived table whose columns are `Expr`s; it can be a source, be joined, or be run
+ *
+ * `as` is the SQL alias and the type-level identity, the same role the second argument of
+ * `table(Author, "m")` plays. Without it the SQL alias is generated, like `table(Author)`, and all
+ * anonymous tables share the type-level identity `"?"`: precise against every named alias, and
+ * conservative (a left-joined anonymous table nullifies every anonymous table's columns) only among
+ * themselves. This is the same collision two bare `table(Author)` have.
+ *
+ * Ordinary SELECT shapes share one signature: separate scalar/entity/POJO overloads hid `as` from
+ * completions and cost 15-28% check time. The separate compound root has one additional signature;
+ * `NotWidened` still rejects a SELECT widened by a `: Query` annotation.
+ */
+declare function query<const Q extends SetQuery<readonly SetOperand[]>, Name extends string = "?">(q: Q & CheckSetQuery<Q> & {
+  as?: Name;
+}): QueryTable<SetQueryRow<Q>, Name>;
+declare function query<F extends QuerySource, const S extends QuerySelect = never, J extends QueryJoinInput = [], Name extends string = "?">(q: QueryArg<F, S, J, Name>): QueryValue<S, ResolvedJoins<F, J>, Name>;
+/**
+ * Builds a query value only when its user-supplied `where` or join-tree filters survive pruning.
+ *
+ * Missing or empty conditions prune the value, including nested groups and `pruneIfUndefined`.
+ * Alias-only joins, HAVING, and implicit soft-delete/STI conditions do not keep the value alive.
+ *
+ * I.e. `queryMaybe({ from: b, where: b.authorId.eq(enabled ? a.id : undefined), select: b.id })`
+ * returns `undefined` when `enabled` is false, so an enclosing `notExists` also prunes.
+ */
+declare function queryMaybe<F extends QuerySource, const S extends QuerySelect = never, J extends QueryJoinInput = [], Name extends string = "?">(q: QueryArg<F, S, J, Name>): QueryValue<S, ResolvedJoins<F, J>, Name> | undefined;
+/**
+ * Declares a `WITH RECURSIVE` CTE from its two terms, and returns the CTE as a readable value.
+ *
+ * `base` is the non-recursive term, which seeds the rows and, as in PostgreSQL, supplies the CTE's
+ * columns. `step` is the recursive term: it receives the CTE itself, so it can join back to the rows
+ * found so far. The two terms are combined with UNION ALL, or UNION when `union: "distinct"` drops
+ * duplicates, which is how a cyclic graph is kept from looping forever.
+ *
+ * ```ts
+ * const [a] = tables(Author);
+ * const tree = recursiveQuery(
+ *   "tree",
+ *   { from: a, where: a.mentor_id.isNull(), select: { id: a.id, mentorId: a.mentor_id } },
+ *   (self) => ({
+ *     from: a,
+ *     join: [{ inner: self, on: a.mentor_id.eq(self.id) }],
+ *     select: { id: a.id, mentorId: a.mentor_id },
+ *   }),
+ * );
+ * const rows = await em.query({ with: tree, from: tree, select: tree });
+ * ```
+ *
+ * Unlike `query()`, the name is required, because the step term must name it.
+ */
+declare function recursiveQuery<Name extends string, F extends QuerySource, const S extends QuerySelect, J extends QueryJoinInput>(name: Name, base: QueryArg<F, S, J, Name>, step: (self: QueryTable<QueryRow<S, ResolvedJoins<F, J>>, Name>) => SetOperand, opts?: RecursiveOptions): QueryTable<QueryRow<S, ResolvedJoins<F, J>>, Name>;
+/**
+ * Builds a SQL expression from a tagged template.
+ *
+ * For an Author alias `a` assigned the SQL alias `a1`:
+ *
+ * ```ts
+ * sql`${a.age} * 2`     // Expression: a1.age * 2
+ * sql`${a.age.gte(18)}` // Condition: (a1.age >= ?), bindings [18]
+ * sql`${"Alice"}`      // Value: ?, bindings ["Alice"]
+ *
+ * // Selecting this expression keeps the join to Book b.
+ * sql.number`${b.order} * ${2}`
+ *
+ * // Reference an unmodeled column; prefer the table's own `column`, which keeps its source key.
+ * a.column<string>("ts_search")
+ * sql.condition`${a.column("ts_search")} @@ plainto_tsquery(${term})`
+ * ```
+ */
+declare function sql<R = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Expr<R, never>;
+declare namespace sql {
+  var number: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<number, never>;
+  var numberOrNull: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<number | null, never>;
+  var numberArray: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<number[], never>;
+  var numberArrayOrNull: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<number[] | null, never>;
+  var string: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<string, never>;
+  var stringOrNull: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<string | null, never>;
+  var stringArray: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<string[], never>;
+  var stringArrayOrNull: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<string[] | null, never>;
+  var boolean: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<boolean, never>;
+  var booleanOrNull: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<boolean | null, never>;
+  var booleanArray: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<boolean[], never>;
+  var booleanArrayOrNull: (strings: TemplateStringsArray, ...values: unknown[]) => Expr<boolean[] | null, never>;
+  var condition: (strings: TemplateStringsArray, ...values: unknown[]) => SqlCondition;
+}
+/**
+ * Parses `arg` (a `Query` POJO or `query(...)` value) into a runnable `Plan`.
+ *
+ * `EntityManager.query` runs the plan; this module deliberately does not import `EntityManager` (see
+ * `EntityHydrator`), so it parses and hands back `{ sql, bindings, decodeRows }` instead of executing.
+ */
+declare function parseRootQuery(arg: unknown): Plan;
+/**
+ * Parses a read that sits inside another statement, i.e. an INSERT's SELECT source, so it resolves that
+ * statement's CTEs and shares its alias space instead of generating names that could collide with them.
+ */
+declare function parseNestedQuery(arg: unknown, parent: Ctx, assigner: AliasAssigner): Plan;
+/** Recognizes read brands, including malformed hybrids that must reach read validation rather than mutation execution. */
+declare function isReadQueryValue(arg: unknown): boolean;
+/**
+ * Compiles scalar or nonempty named expression projections, shared by SELECT and mutation RETURNING.
+ * Source-shaped values need read hydration/source rules and are deliberately excluded here.
+ */
+declare function projectionToSql(select: unknown, ctx: Ctx, joins?: QueryJoinList): {
+  selects: SqlFragment[];
+  decodeRows: Plan["decodeRows"];
+  output: QueryOutput;
+};
+/**
+ * The one `EntityManager` capability that row decoding needs, typed structurally.
+ *
+ * Importing `EntityManager.ts` here would complete an `EntityManager.ts` <-> `query.ts` declaration
+ * cycle (`EntityManager.query` imports this module's types), which correlated with a tsc 7.0.2
+ * incremental-build bug: after tsdown rewrites `build/`, `tsc --build` sporadically reports thousands
+ * of phantom "Module 'joist-orm' has no exported member ..." errors and caches them in `.tsbuildinfo`.
+ */
+interface EntityHydrator {
+  hydrate(cstr: any, rows: readonly any[]): any[];
+}
+interface Plan {
+  sql: string;
+  bindings: any[];
+  /** Aliases of enclosing queries this (sub)query referenced. */
+  outerRefs: string[];
+  /** Ordered SQL output columns and their existing expression codecs, before JS row decoding. */
+  output: QueryOutput;
+  decodeRows(em: EntityHydrator, rows: any[]): any[];
+}
+type AnyQuery = Query<any, any> & {
+  as?: string;
+};
+type AnyReadQuery = AnyQuery | SetQuery<readonly SetOperand[]>;
+/** Only POJO outputs can be set operands; ordinary scalar reads also expose an ordered output column. */
+interface QueryOutput {
+  kind: "entity" | "scalar" | "pojo";
+  /** Expressions retain codecs and physical nullability after LEFT joins and set operations. */
+  columns: readonly (readonly [string, BaseExpr])[];
+}
+/** The runtime identity of a `query(...)` value; `Ctx.aliasFor` keys on it, like a table's `TableMgmt`. */
+declare class SubqueryHandle {
+  #private;
+  readonly recursive: boolean;
+  constructor(q: AnyReadQuery, recursive?: boolean);
+  get q(): AnyReadQuery;
+  /**
+   * Gives a recursive CTE its finished body.
+   *
+   * `recursiveQuery(name, base, step)` cannot hand us the real body up front: it has to call `step` to
+   * get it, and `step` needs this handle first, because the recursive half of the query references the
+   * CTE's own columns. So the handle starts out holding `base` alone, and the real body, `base UNION
+   * step`, arrives here afterwards. Either way PostgreSQL takes the CTE's column names from `base`.
+   */
+  setBody(q: AnyReadQuery): void;
+  get name(): string | undefined;
+  /** The select keys, for `select: <subquery>` and for reporting unknown columns. */
+  columnKeys(): string[];
+  /** The inner expression behind `key`, for its decoder/encoder. */
+  columnExpr(key: string): BaseExpr;
+  /**
+   * The output columns, in order, with the codec for each; worked out without generating any SQL.
+   *
+   * Cached, because the answer is expensive to work out and gets asked for a lot:
+   *
+   * - `queryOutput` re-checks the whole query, converts a `join: { books: ... }` relationship tree
+   *   back into a flat list of joins, and repeats all of that for every operand of a set query.
+   * - A `query(...)` value has no real properties. `bookStats.n` runs a `Proxy` get that builds a new
+   *   column expression, and building one needs this method's answer to find `n`. So selecting two of
+   *   a value's columns asked for the whole shape twice, before parsing then asked a third time.
+   *
+   * `setBody` is the only thing that changes the shape, so it is the only thing that clears this.
+   */
+  output(): QueryOutput;
+  column(key: string): SubqueryColumnExpr;
+  describe(): string;
+}
+/** A column of a joined/from'd subquery, i.e. `bookStats.bookCount`, which becomes `book_stats."bookCount"`. */
+declare class SubqueryColumnExpr extends BaseExpr {
+  private handle;
+  private key;
+  private inner;
+  constructor(handle: SubqueryHandle, key: string, inner: BaseExpr);
+  get [selectKeyBrand](): string;
+  toSql(ctx: ExprContext): SqlFragment;
+  decode(value: unknown): unknown;
+  encode(value: unknown): unknown;
+  get outputType(): TypeInfo | undefined;
+  get sqlNullable(): boolean | undefined;
+  get sqlSource(): object;
+}
+/**
+ * What an expression needs from the query it is generating SQL for.
+ *
+ * Each (sub)query gets its own `Ctx`; a lookup that misses locally walks up to the enclosing query and
+ * records the hit in `outerRefs`, which is how a correlated subquery reports the outer aliases it
+ * depends on (the way `ExistsCondition.outerAliases` does), so join pruning keeps them.
+ */
+declare class Ctx implements ExprContext {
+  readonly assigner: AliasAssigner;
+  private parent;
+  private aliases;
+  /**
+   * The subset of `aliases` that are CTE names. A `from`/`join` on one of these emits just the name,
+   * i.e. `FROM book_stats`, where an ordinary `query(...)` value emits its whole body inline, i.e.
+   * `FROM (SELECT ...) AS sq`.
+   */
+  private ctes;
+  /**
+   * `with` entries named but not yet turned into SQL. `registerCtes` names every entry first, then
+   * generates the bodies one at a time, so while one body is being generated the entries after it sit
+   * here. Reading one of those is a forward reference.
+   */
+  private pendingCtes;
+  /** CTEs already read by this query's `from`/`join`, so a second read fails instead of colliding. */
+  private usedCtes;
+  /** The recursive CTE whose body this query is part of, if any; see `recursiveSelf`. */
+  private ownRecursiveSelf;
+  readonly outerRefs: Set<string>;
+  constructor(assigner: AliasAssigner, parent: Ctx | undefined);
+  /**
+   * One handle can hold only one alias per query, so a value used twice must be told apart, not
+   * silently collapsed into the second registration's alias.
+   */
+  register(handle: object, alias: string): void;
+  /** Names every `with` entry up front, so a CTE reading a later sibling is reported, not inlined. */
+  declareCte(handle: object, alias: string): void;
+  /** Brings a pending CTE into scope, for the sources and columns that may now read it. */
+  promoteCte(handle: object): void;
+  /**
+   * The CTE name for `handle`, looking in the enclosing queries too, because a CTE is in scope for the
+   * whole statement.
+   *
+   * Unlike `aliasFor`, a hit in an enclosing query is not added to `outerRefs`: reading a CTE by name
+   * is not a correlated reference, so it must not keep an enclosing join alive.
+   */
+  cteAliasFor(handle: object): string | undefined;
+  /**
+   * The recursive CTE this query's terms belong to, inherited from the enclosing query.
+   *
+   * PostgreSQL requires a recursive term to reference its own CTE, so that reference is not optional
+   * and must survive pruning, unlike an ordinary explicit join that nothing else reads.
+   */
+  get recursiveSelf(): SubqueryHandle | undefined;
+  setRecursiveSelf(handle: SubqueryHandle): void;
+  /** Whether `handle` is a CTE with no SQL yet, i.e. itself or a later `with` entry. */
+  isPendingCte(handle: object): boolean;
+  /**
+   * Fails if this query already reads `handle`. A `Ctx` maps each handle to a single alias, so two
+   * reads of one CTE value would render as the same name, i.e. `FROM tree JOIN tree`, and neither the
+   * SQL nor a column expression could say which one it meant. Each read needs its own `query(...)`.
+   *
+   * Only this query is checked, not the enclosing ones: a nested subquery has its own FROM, so reading
+   * the same CTE in there is fine.
+   */
+  useCte(handle: object): void;
+  aliasFor(handle: object): string;
+  conditionToSql(cond: QueryCondition): SqlFragment | undefined;
+}
+/** A parsed `with` entry: the CTE's name and its body, ready to render into the WITH clause. */
+interface ParsedCte {
+  alias: string;
+  plan: Plan;
+  /** A recursive CTE reads itself, and makes the whole clause `WITH RECURSIVE`. */
+  recursive: boolean;
+}
+/**
+ * Per-source soft-delete injections: `alias.deleted_at IS NULL` for a soft-deletable entity.
+ * CTI subtypes are skipped because their deleted-at column belongs to the base table (see
+ * `filterSoftDeletes`). STI sources read all physical rows without discriminator predicates.
+ *
+ * The conditions go into the from's WHERE or the join's ON, and never keep an otherwise unreferenced
+ * join alive, which is what `pruneable: true` means on em.find's side.
+ */
+declare function injectedConditions(source: {
+  meta: EntityMetadata | undefined;
+  alias: string;
+}, softDeletes: "include" | "exclude"): ColumnCondition[];
+/**
+ * Parses a user-facing condition (a single condition or an `{ and }`/`{ or }` filter) with the same
+ * `ConditionBuilder` `em.find` uses, so `undefined` members drop out, empty groups drop, and
+ * `pruneIfUndefined` applies unchanged. Deferred SQL expression conditions are resolved
+ * against the context first.
+ */
+declare function conditionToSql(cond: QueryCondition | undefined, ctx: Ctx, topLevel: boolean): SqlFragment | undefined;
+/**
+ * Accepts only own enumerable POJO fields, so nothing a caller supplied can be silently ignored: the
+ * compilers read these POJOs back with `Object.entries`/`Object.keys`, which skip inherited,
+ * non-enumerable, and symbol keys, so a field hidden behind one of those would never reach the SQL.
+ * I.e. an UPDATE whose `set` carries `title` on a prototype would leave `title` unchanged and still
+ * report success.
+ *
+ * Conditions, mutation clauses, and assignment POJOs all share this rule; `allowed` may include symbol
+ * keys, i.e. a condition's predicate brand and SQL resolver. Read-query clauses instead use
+ * `validateQueryKeys`, which walks the prototype chain and reports mutation clauses by name.
+ */
+declare function checkPojoKeys(value: object, allowed: readonly PropertyKey[], description: string): void;
+/**
+ * Names and parses each `with` entry, in declaration order.
+ *
+ * Each entry is in scope before the next is parsed, so a CTE can read an *earlier* sibling by name,
+ * PostgreSQL's rule for a non-recursive WITH. A forward reference, or a CTE reading the query's own
+ * `from`, fails as "not in this query's from/join", the same error any out-of-scope source gets.
+ *
+ * I.e. `with: [totals, ranked]` parses `totals` first, so `ranked` can join it, but not the reverse.
+ */
+declare function registerCtes(q: {
+  with?: WithInput;
+}, ctx: Ctx, assigner: AliasAssigner): ParsedCte[];
+/**
+ * Puts a statement's surviving `with` entries in front of it, dropping the ones nothing reads.
+ *
+ * `referenced` is the aliases the rest of the statement used. The WITH clause leads the statement, so
+ * its bindings lead the statement's bindings too.
+ */
+declare function prependCtes(ctes: ParsedCte[], referenced: Set<string>, sql: string, bindings: any[]): {
+  sql: string;
+  bindings: any[];
+};
+/**
+ * Drops the CTEs that nothing reads, given the aliases the rest of the statement referenced.
+ *
+ * A CTE can only read earlier siblings, so going last to first means every CTE that could read this one
+ * was already visited, and its own reads are already in `referenced`. That makes one pass enough; first
+ * to last would have to repeat until the set stopped growing. `unshift` restores WITH order.
+ */
+declare function pruneCtes(ctes: ParsedCte[], referenced: Set<string>): ParsedCte[];
+/**
+ * Renders `WITH a AS (...), b AS (...) `, whose bindings lead the statement, as their SQL does.
+ *
+ * One recursive CTE makes the whole clause `WITH RECURSIVE`, PostgreSQL's rule: the keyword is on the
+ * clause, not on the entry that needs it, and it does not force the other entries to be recursive.
+ */
+declare function withFragment(ctes: ParsedCte[]): SqlFragment;
+//#endregion
+export { CheckReadQuery, CheckScope, CheckSetQuery, Clauses, CompatibleValue, Ctx, EntityHydrator, EntityQuery, ExistsQuery, ExpressionOrderBy, MaybeNull, NameOf, NamedSelectExpression, NotWidened, OrderByDirection, OrderByKeys, ParsedCte, Plan, Query, QueryArg, QueryCondition, QueryJoin, QueryJoinInput, QueryJoinList, QueryOutput, QueryRow, QuerySelect, QuerySource, QueryTable, QueryTableBrand, QueryValue, ReadQueryRow, RecursiveOptions, ResolvedJoins, ScalarQuery, SelectExpression, SetOperand, SetOperation, SetQuery, SetQueryRow, SqlExpressionValue, Subquery, SubqueryBrand, SubqueryHandle, WithInput, WithSource, checkPojoKeys, conditionToSql, entityQueryBrand, injectedConditions, isReadQueryValue, parseNestedQuery, parseRootQuery, prependCtes, projectionToSql, pruneCtes, query, queryMaybe, recursiveQuery, registerCtes, scalarQueryBrand, sql, subqueryBrand, withFragment };
+//# sourceMappingURL=query.d.mts.map