joist-core 2.3.0-next.96 → 2.3.0-next.98

package/build/query.d.cts

@@ -1,794 +0,0 @@
-import { SqlCondition, SqlPredicate, UnbrandedPredicate } from "./conditions.cjs";
-import { TypeInfo } from "./TypeInfo.cjs";
-import { EntityMetadata } from "./EntityMetadata.cjs";
-import { CheckInput, ExprFromInput, ExprInput, ExpressionSources, ExpressionValue } from "./expressions/types.cjs";
-import "./expressions/expression.cjs";
-import { BaseExpr, Expr, ExprContext, ExprLike, InnerJoin, LeftJoin, SqlFragment } from "./Expr.cjs";
-import { Table, TableBrand, referenceJoinSource, tableMgmt } from "./Tables.cjs";
-import { Entity } from "./Entity.cjs";
-import { ColumnCondition } from "./QueryParser.cjs";
-import { AliasAssigner } from "./AliasAssigner.cjs";
-//#region src/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 | null }[]   (null because of the LEFT join)
- *
- * `em.query(pojo)` runs it. `select` decides the row type: a bare table returns entities, a
- * `{ key: expr }` object returns typed POJOs, a bare subquery returns that subquery's 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 = Subquery<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 subquery. */
-interface SubqueryBrand<R, Name extends string> {
-  readonly __row: R;
-  readonly __name: Name;
-}
-/** Anything that can be a source or be joined: an entity table or a table-shaped subquery. */
-type QuerySource = {
-  readonly [tableMgmt]: TableBrand<any, string>;
-} | {
-  readonly [subqueryBrand]: SubqueryBrand<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 QueryJoins = readonly (QueryJoin | undefined)[];
-/**
- * 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 = Subquery<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. An undefined order prunes the complete entry. */
-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 `{ sort, order }` entries in the array form.
- */
-type OrderByKeys<S> = 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 three select shapes: a source, an existing scalar expression, or a POJO naming result columns. */
-type QuerySelect = QuerySource | ExprLike<unknown> | Record<string, SelectExpression>;
-/** A named projection value may be an existing expression or an inline expression literal. */
-type SelectExpression = ExprLike<unknown> | ExprInput;
-/** Checks expression literals only inside named projections. */
-type CheckSelect<S> = S extends QuerySource | ExprLike<unknown> ? 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 QueryJoins = QueryJoins> {
-  /**
-   * 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;
-  join?: J;
-  /** A boolean group, an exists/notExists query, or a bare condition such as `a.age.gte(18)`. */
-  where?: QueryCondition;
-  groupBy?: readonly ExprLike<any>[];
-  having?: QueryCondition;
-  select: S;
-  orderBy?: readonly (CheckedExpressionOrderBy<S> | OrderByKeys<S> | undefined)[] | 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 QueryJoins = QueryJoins> 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> | Subquery<unknown, string>> | Subquery<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 | null }`, 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, "join" extends keyof Q ? Extract<Q[keyof Q & "join"], QueryJoins> : []> : [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 | null }` produce `{ name: string | null }`. EXCEPT with those Author names on the
- * left retains `{ name: string }`; it neither adds the right side's NULL 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]: SubqueryBrand<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;
-} ? { 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, the value can be `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 `sql.ref` on an unknown table) 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 QueryJoins> = 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
- * - POJO mode is a mapped type over the select keys, with left-join nullability applied
- */
-type QueryRow<S, J extends QueryJoins = []> = S extends {
-  readonly [tableMgmt]: {
-    readonly __entity: infer T;
-  };
-} ? T : S extends {
-  readonly [subqueryBrand]: {
-    readonly __row: infer R;
-  };
-} ? R : S extends ExprLike<unknown> ? ExpressionValue<S, J> : { -readonly [K in keyof S]: S[K] extends SelectExpression ? ExpressionValue<S[K] extends ExprInput ? ExprFromInput<S[K]> : S[K], J> : 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, `Subquery<Row, Name>` maps the inner query's select keys to expressions.
- */
-type Subquery<R, Name extends string> = {
-  readonly [subqueryBrand]: SubqueryBrand<R, Name>;
-} & { readonly [K in keyof R]: Expr<R[K], 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<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); // Subquery<{ 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 QueryJoins, Name extends string> = S extends {
-  readonly [tableMgmt]: {
-    readonly __entity: infer T extends Entity;
-  };
-} ? EntityQuery<T> : S extends ExprLike<unknown> ? ScalarQuery<QueryRow<S, J>> : Subquery<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 QueryJoins> = 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 QueryJoins> = [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 [Record<string, SelectExpression>] ? {
-  select: { [K in keyof S]: CheckExpressionScope<S[K], InScope<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 QueryJoins, Name extends string> = Query<S, J> & {
-  from: F;
-  as?: Name;
-} & CheckScope<S, 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;
-}): Subquery<SetQueryRow<Q>, Name>;
-declare function query<F extends QuerySource, const S extends QuerySelect = never, J extends QueryJoins = [], Name extends string = "?">(q: QueryArg<F, S, J, Name>): QueryValue<S, J, Name>;
-/**
- * Builds a query value only when its user-supplied `where` survives pruning.
- *
- * Missing or empty conditions prune the value, including nested groups and `pruneIfUndefined`.
- * 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 QueryJoins = [], Name extends string = "?">(q: QueryArg<F, S, J, Name>): QueryValue<S, 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 QueryJoins>(name: Name, base: QueryArg<F, S, J, Name>, step: (self: Subquery<QueryRow<S, J>, Name>) => SetOperand, opts?: RecursiveOptions): Subquery<QueryRow<S, 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; it is untracked at the type level.
- * sql.ref<string>(a, "ts_search")
- * sql.condition`${sql.ref(a, "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;
-  var ref: <R = unknown>(source: QuerySource, column: string) => Expr<R, string>;
-}
-/**
- * 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 parseUserQuery(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): {
-  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` starts the handle on its base term, so
-   * the step term can read the CTE's columns while the body that will hold that step is still being
-   * built. The base term supplies the CTE's columns either way, PostgreSQL's rule for a recursive WITH.
-   */
-  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;
-  /** Resolve output metadata without parsing SQL or caching aliases from an enclosing query. */
-  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);
-  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;
-/**
- * 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[];
-/**
- * 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, NotWidened, OrderByDirection, OrderByKeys, ParsedCte, Plan, Query, QueryArg, QueryCondition, QueryJoin, QueryJoins, QueryOutput, QueryRow, QuerySelect, QuerySource, QueryValue, ReadQueryRow, RecursiveOptions, ScalarQuery, SelectExpression, SetOperand, SetOperation, SetQuery, SetQueryRow, Subquery, SubqueryBrand, SubqueryHandle, WithInput, WithSource, conditionToSql, entityQueryBrand, injectedConditions, isReadQueryValue, parseNestedQuery, parseUserQuery, projectionToSql, pruneCtes, query, queryMaybe, recursiveQuery, registerCtes, scalarQueryBrand, sql, subqueryBrand, withFragment };
-//# sourceMappingURL=query.d.cts.map