joist-core 2.3.0 → 2.4.0-next.10

package/build/queries/sql/Expr.d.cts

@@ -0,0 +1,284 @@
+import { RawCondition } from "../parsedConditions.cjs";
+import { ConditionInput, PredicateBrand, SqlCondition } from "../conditions.cjs";
+import { TypeInfo } from "../../serde/TypeInfo.cjs";
+import { ExpressionOrderBy, QueryCondition } from "./query.cjs";
+//#region src/queries/sql/Expr.d.ts
+/**
+ * The shared expression protocol for `em.query`.
+ *
+ * Table columns (`a.first_name`), aggregates (`b.id.count()`), `sql` templates, subquery columns
+ * (`bookStats.bookCount`), and scalar subqueries all implement it, so any of them can appear in
+ * `select`, `where`, `groupBy`, `having`, `orderBy`, and inside other expressions.
+ *
+ * This module is a leaf on purpose: `Tables.ts` extends `BaseExpr` at load time, so nothing here may
+ * import (at runtime) a module that leads back to `Tables.ts`. Anything that needs metadata, alias
+ * binding, or SQL generation for conditions is reached through the `ExprContext` the query parser passes in.
+ */
+declare const exprBrand: unique symbol;
+/** Carries a column's table property name so array selects can infer and decode named result rows. */
+declare const selectKeyBrand: unique symbol;
+/**
+ * Phantom type information carried by every `Expr`.
+ *
+ * `R` is the decoded result type.
+ *
+ * `Src` is the expression's *source key*: the type-level identity of the table it reads from. An entity
+ * table's key is its type name (`table(Author)` gives `"Author"`) or the explicit name in
+ * `table(Author, "m")`; a subquery's key is its `as: "book_stats"`, or the shared sentinel `"?"` when it
+ * has no `as`. Exactly two questions are asked of a source key, and nothing else:
+ *
+ * - `MaybeNull` asks "is my source key among the LEFT-joined sources in this query's join list?" If yes,
+ *   the value can be `null`.
+ * - `CheckScope` asks "is my source key among `from` + `join` at all?" If no, the query reads from a
+ *   table it never joined.
+ *
+ * Two special keys opt out of both questions:
+ *
+ * - `Expr<number, never>` reads from nothing that can be left-joined away, i.e. `b.id.count()`
+ * - `Expr<number, string>` (the default) is untracked, i.e. a table whose entity type is not statically known
+ */
+interface ExprBrand<R, Src extends string> {
+  readonly __result: R;
+  readonly __source: Src;
+}
+/**
+ * "Any expression whose result is `R`", checked by brand alone.
+ *
+ * Method parameters use this instead of `Expr<R>` so that `Expr` stays covariant in `R`: checking
+ * `Expr<AuthorId>` against `Expr<AuthorId | null>` then only compares the phantom `__result`, not every
+ * method's parameter list (which would make `Expr` invariant, and break `select: b.author_id` dispatch and
+ * polymorphic joins).
+ */
+type ExprLike<R> = {
+  readonly [exprBrand]: ExprBrand<R, any>;
+};
+/** Controls which values enter an array aggregate and their order within the array. */
+interface ArrayAggOptions {
+  distinct?: boolean;
+  /** With DISTINCT, PostgreSQL requires ordering expressions to match the aggregate argument. */
+  orderBy?: readonly (ExpressionOrderBy | undefined)[];
+  /** Undefined conditions are pruned, as in a query's where clause. */
+  filter?: QueryCondition;
+}
+/**
+ * A typed SQL expression: a table column, an aggregate, a `sql` template, or a scalar subquery.
+ *
+ * Conditions and SQL functions are methods, so they need no import. Aggregates keep `Src` so scope
+ * checking still sees through `bs.x.max()`; `count` is source-less because `count(x)` is 0, not null,
+ * when `x`'s table is left-joined away; `coalesce` drops `Src` on purpose, since its whole job is to
+ * remove the nullability a left join adds.
+ */
+interface Expr<R, Src extends string = string> {
+  readonly [exprBrand]: ExprBrand<R, Src>;
+  eq(value: R | ExprLike<R> | undefined): SqlCondition;
+  ne(value: R | ExprLike<R> | undefined): SqlCondition;
+  gt(value: R | ExprLike<R> | undefined): SqlCondition;
+  gte(value: R | ExprLike<R> | undefined): SqlCondition;
+  lt(value: R | ExprLike<R> | undefined): SqlCondition;
+  lte(value: R | ExprLike<R> | undefined): SqlCondition;
+  in(values: readonly R[] | ExprLike<R | null> | undefined): SqlCondition;
+  nin(values: readonly R[] | ExprLike<R | null> | undefined): SqlCondition;
+  /** Prefixes this expression and a space to a raw predicate; write .is`IS NULL`, not .is`NULL`. */
+  is(strings: TemplateStringsArray, ...values: unknown[]): SqlCondition;
+  /** Orders by this expression in ascending order. */
+  asc(): ExpressionOrderBy;
+  /** Orders by this expression in descending order. */
+  desc(): ExpressionOrderBy;
+  /** `count(x)::int`; `count(a.id)` is `count(*)` for the FROM table, and the matched-row count for a left-joined one. */
+  count(): Expr<number, never>;
+  countDistinct(): Expr<number, never>;
+  sum(this: Expr<number | null, Src>): Expr<number | null, Src>;
+  avg(this: Expr<number | null, Src>): Expr<number | null, Src>;
+  min(): Expr<R | null, Src>;
+  max(): Expr<R | null, Src>;
+  /** PG keeps element NULLs (a left-joined empty group aggregates as `[null]`), and zero rows aggregate as NULL. */
+  arrayAgg(options?: ArrayAggOptions): Expr<R[] | null, Src>;
+  stringAgg(this: Expr<string | null, Src>, delimiter: string): Expr<string | null, Src>;
+  coalesce(fallback: NonNullable<R>): Expr<NonNullable<R>, never>;
+}
+/**
+ * A join entry: the join kind is the key, the joined source is the value, plus `on`. `inner?: never` /
+ * `left?: never` keep an entry to one kind (the `SqlCondition` `and`/`or` trick).
+ *
+ * `on` is required. A join is pruned when nothing references it anymore, not by an `undefined` ON;
+ * `keep: true` pins a join that would otherwise prune, i.e. an inner join used as an existence filter,
+ * the way em.find's `keepAliases` does. It is a boolean so callers can pass a flag.
+ *
+ * Declared here (not `query.ts`) so the relation join factories in `Tables.ts` (i.e. `a.books.as(b)`) can
+ * return them without importing `query.ts`; `query.ts` re-constrains `A` to its `QuerySource`.
+ */
+interface InnerJoin<A, C = SqlCondition> {
+  readonly inner: A;
+  readonly left?: never;
+  readonly on: C;
+  readonly keep?: boolean;
+}
+interface LeftJoin<A, C = SqlCondition> {
+  readonly left: A;
+  readonly inner?: never;
+  readonly on: C;
+  readonly keep?: boolean;
+}
+/** SQL plus its `?` bindings plus the SQL aliases it references, i.e. for join pruning. */
+interface SqlFragment {
+  sql: string;
+  bindings: any[];
+  refs: string[];
+}
+/**
+ * What an expression needs from the query it is generating SQL for: the SQL alias assigned to each
+ * source, and a way to turn nested conditions into SQL (which needs `ConditionBuilder`, so it lives in `query.ts`).
+ */
+interface ExprContext {
+  /** Returns the SQL alias for a table's `TableMgmt` or a subquery handle, searching enclosing queries. */
+  aliasFor(handle: object): string;
+  /** Turns a user-facing condition into SQL; `undefined` if it pruned away entirely. */
+  conditionToSql(cond: QueryCondition): SqlFragment | undefined;
+}
+declare function isExpr(value: unknown): value is ExprLike<any>;
+/** Every `Expr` is a `BaseExpr` at runtime; this cast keeps `isExpr` a plain type guard so unions narrow. */
+declare function asNode(expr: ExprLike<any>): BaseExpr;
+declare const deferredSym: unique symbol;
+/**
+ * A condition whose SQL depends on aliases that are only known once the query is parsed, i.e.
+ * `bookStats.bookCount.gt(1)` or `bs.authorId.eq(a.id)`.
+ *
+ * It is shaped like a `RawCondition` with a SQL brand so it can sit in any `SqlCondition`; `resolveDeferredConditions`
+ * snapshots `condition`, `bindings`, and `aliases` before the filter is parsed. Domain alias conditions
+ * use a separate protocol in the `em.find` parser.
+ */
+interface DeferredCondition extends RawCondition, PredicateBrand<"sql"> {
+  [deferredSym]: (ctx: ExprContext) => RawCondition;
+}
+declare function isDeferredCondition(cond: unknown): cond is DeferredCondition;
+/** Creates a `DeferredCondition` that generates its SQL with `fn` once the query's aliases are known. */
+declare function deferredCondition(fn: (ctx: ExprContext) => SqlFragment): DeferredCondition;
+/**
+ * Resolve each condition occurrence and snapshot it before resolving the next one. A nested subquery
+ * may reuse the same condition under another alias; it must not overwrite this occurrence's SQL.
+ */
+declare function resolveDeferredConditions(cond: ConditionInput | undefined, ctx: ExprContext): ConditionInput | undefined;
+/** Concatenates SQL fragments with `sep`, keeping bindings and refs in order. */
+declare function joinFragments(parts: SqlFragment[], sep: string): SqlFragment;
+/**
+ * The methods every expression shares. Subclasses provide `toSql`, and usually `decode`/`encode`.
+ *
+ * Table columns can override comparisons to apply column-specific conversions. Domain aliases do not
+ * implement this protocol.
+ */
+declare abstract class BaseExpr {
+  readonly [exprBrand]: any;
+  /** Produces this expression's SQL so it can be embedded in a larger expression, i.e. a subquery gets parens. */
+  abstract toSql(ctx: ExprContext): SqlFragment;
+  /** Only an actual scalar/IN subquery exposes its selected expression, not an ordinary ID expression. */
+  get subquerySelect(): BaseExpr | undefined;
+  /** Known SQL representation and logical domain; raw SQL and unmodeled refs remain unknown. */
+  get outputType(): TypeInfo | undefined;
+  /** Physical SQL nullability; undefined means unknown, not a NOT NULL guarantee. */
+  get sqlNullable(): boolean | undefined;
+  /** The source of a direct column reference, whose value becomes NULL under an unmatched LEFT join. */
+  get sqlSource(): object | undefined;
+  /** Produces the SQL without the outer parens a subquery normally gets; only differs for subqueries. */
+  toSqlBare(ctx: ExprContext): SqlFragment;
+  /** Converts a result-set value into the domain value, i.e. an int into a tagged id. */
+  decode(value: unknown): unknown;
+  /** Converts a domain value into the database value, i.e. a tagged id into an int, for bindings. */
+  encode(value: unknown): unknown;
+  eq(value: unknown): SqlCondition;
+  ne(value: unknown): SqlCondition;
+  gt(value: unknown): SqlCondition;
+  gte(value: unknown): SqlCondition;
+  lt(value: unknown): SqlCondition;
+  lte(value: unknown): SqlCondition;
+  in(values: unknown): SqlCondition;
+  nin(values: unknown): SqlCondition;
+  /** Prefixes this expression to a SQL template, retaining bindings and referenced aliases. */
+  is(strings: TemplateStringsArray, ...values: unknown[]): SqlCondition;
+  /** Orders by this expression in ascending order. */
+  asc(): ExpressionOrderBy;
+  /** Orders by this expression in descending order. */
+  desc(): ExpressionOrderBy;
+  count(): Expr<number, never>;
+  countDistinct(): Expr<number, never>;
+  sum(): Expr<number | null, any>;
+  avg(): Expr<number | null, any>;
+  min(): Expr<any, any>;
+  max(): Expr<any, any>;
+  arrayAgg(options?: ArrayAggOptions): Expr<any, any>;
+  stringAgg(delimiter: string): Expr<string | null, any>;
+  coalesce(fallback: unknown): Expr<any, never>;
+  /** `this op value`, where `value` may be `undefined` (pruned), `null`, another expression, or a literal. */
+  protected compare(op: string, value: unknown): SqlCondition;
+  /** `this IN (subquery)` or `this = ANY(?)` for a list; `NOT IN` / `!= ALL(?)` for `nin`. */
+  protected inList(op: "IN" | "NOT IN", values: unknown): SqlCondition;
+}
+/**
+ * A SQL function applied to expressions, i.e. `count(a."id")::int` or `coalesce(bs."n", ?)`.
+ *
+ * By default decoding is identity and encoding follows the first argument. Callers explicitly supply
+ * a decoder and output type when needed (`max(a.id)` is still an id); numeric aggregates supply their
+ * own decoder/encoder, since `count(a.id)` is a number, not an id. Unknown functions have no output type.
+ */
+declare class FnExpr extends BaseExpr {
+  private name;
+  private args;
+  private opts;
+  constructor(name: string, args: BaseExpr[], opts: {
+    prefix?: string;
+    suffix?: string;
+    decode?: (value: unknown) => unknown;
+    encode?: (value: unknown) => unknown;
+    outputType?: TypeInfo;
+    aggregate?: ArrayAggOptions;
+  });
+  get outputType(): TypeInfo | undefined;
+  get sqlNullable(): boolean | undefined;
+  /**
+   * Renders function arguments, aggregate ordering, and the filter in SQL binding order.
+   * Keep references from all three so aggregate-only joins are retained.
+   */
+  toSql(ctx: ExprContext): SqlFragment;
+  decode(value: unknown): unknown;
+  encode(value: unknown): unknown;
+}
+/** A bound literal, i.e. the `?` in `coalesce(x, ?)`. */
+declare class BindingExpr extends BaseExpr {
+  private value;
+  constructor(value: unknown);
+  get sqlNullable(): boolean;
+  toSql(): SqlFragment;
+}
+/** An unmodeled column on a known source, i.e. `a.column("ts_search")`. */
+declare class RefExpr extends BaseExpr {
+  private handle;
+  private column;
+  constructor(handle: object, column: string);
+  get sqlSource(): object;
+  toSql(ctx: ExprContext): SqlFragment;
+}
+/**
+ * A `sql` tagged template.
+ *
+ * For an Author table `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"]
+ * ```
+ */
+declare class TemplateExpr extends BaseExpr {
+  private strings;
+  private values;
+  constructor(strings: TemplateStringsArray, values: unknown[]);
+  toSql(ctx: ExprContext): SqlFragment;
+}
+/** Turns one `${...}` of a `sql` template into SQL: an expression, a condition, or a bound value. */
+declare function interpolationToSql(value: unknown, ctx: ExprContext): SqlFragment;
+/** True for the user-facing condition shapes: `{ and }`, `{ or }`, `ColumnCondition`, `RawCondition`. */
+declare function isConditionLike(value: unknown): boolean;
+/** Renders an expression order for either a query or an aggregate, or prunes an undefined order. */
+declare function orderByToSql(o: ExpressionOrderBy, ctx: ExprContext): SqlFragment | undefined;
+//#endregion
+export { ArrayAggOptions, BaseExpr, BindingExpr, DeferredCondition, Expr, ExprBrand, ExprContext, ExprLike, FnExpr, InnerJoin, LeftJoin, RefExpr, SqlFragment, TemplateExpr, asNode, deferredCondition, deferredSym, exprBrand, interpolationToSql, isConditionLike, isDeferredCondition, isExpr, joinFragments, orderByToSql, resolveDeferredConditions, selectKeyBrand };
+//# sourceMappingURL=Expr.d.cts.map

package/build/queries/sql/Expr.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Expr.d.cts","names":[],"sources":["../../../src/queries/sql/Expr.ts"],"mappings":"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"}

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

@@ -0,0 +1,284 @@
+import { RawCondition } from "../parsedConditions.mjs";
+import { ConditionInput, PredicateBrand, SqlCondition } from "../conditions.mjs";
+import { TypeInfo } from "../../serde/TypeInfo.mjs";
+import { ExpressionOrderBy, QueryCondition } from "./query.mjs";
+//#region src/queries/sql/Expr.d.ts
+/**
+ * The shared expression protocol for `em.query`.
+ *
+ * Table columns (`a.first_name`), aggregates (`b.id.count()`), `sql` templates, subquery columns
+ * (`bookStats.bookCount`), and scalar subqueries all implement it, so any of them can appear in
+ * `select`, `where`, `groupBy`, `having`, `orderBy`, and inside other expressions.
+ *
+ * This module is a leaf on purpose: `Tables.ts` extends `BaseExpr` at load time, so nothing here may
+ * import (at runtime) a module that leads back to `Tables.ts`. Anything that needs metadata, alias
+ * binding, or SQL generation for conditions is reached through the `ExprContext` the query parser passes in.
+ */
+declare const exprBrand: unique symbol;
+/** Carries a column's table property name so array selects can infer and decode named result rows. */
+declare const selectKeyBrand: unique symbol;
+/**
+ * Phantom type information carried by every `Expr`.
+ *
+ * `R` is the decoded result type.
+ *
+ * `Src` is the expression's *source key*: the type-level identity of the table it reads from. An entity
+ * table's key is its type name (`table(Author)` gives `"Author"`) or the explicit name in
+ * `table(Author, "m")`; a subquery's key is its `as: "book_stats"`, or the shared sentinel `"?"` when it
+ * has no `as`. Exactly two questions are asked of a source key, and nothing else:
+ *
+ * - `MaybeNull` asks "is my source key among the LEFT-joined sources in this query's join list?" If yes,
+ *   the value can be `null`.
+ * - `CheckScope` asks "is my source key among `from` + `join` at all?" If no, the query reads from a
+ *   table it never joined.
+ *
+ * Two special keys opt out of both questions:
+ *
+ * - `Expr<number, never>` reads from nothing that can be left-joined away, i.e. `b.id.count()`
+ * - `Expr<number, string>` (the default) is untracked, i.e. a table whose entity type is not statically known
+ */
+interface ExprBrand<R, Src extends string> {
+  readonly __result: R;
+  readonly __source: Src;
+}
+/**
+ * "Any expression whose result is `R`", checked by brand alone.
+ *
+ * Method parameters use this instead of `Expr<R>` so that `Expr` stays covariant in `R`: checking
+ * `Expr<AuthorId>` against `Expr<AuthorId | null>` then only compares the phantom `__result`, not every
+ * method's parameter list (which would make `Expr` invariant, and break `select: b.author_id` dispatch and
+ * polymorphic joins).
+ */
+type ExprLike<R> = {
+  readonly [exprBrand]: ExprBrand<R, any>;
+};
+/** Controls which values enter an array aggregate and their order within the array. */
+interface ArrayAggOptions {
+  distinct?: boolean;
+  /** With DISTINCT, PostgreSQL requires ordering expressions to match the aggregate argument. */
+  orderBy?: readonly (ExpressionOrderBy | undefined)[];
+  /** Undefined conditions are pruned, as in a query's where clause. */
+  filter?: QueryCondition;
+}
+/**
+ * A typed SQL expression: a table column, an aggregate, a `sql` template, or a scalar subquery.
+ *
+ * Conditions and SQL functions are methods, so they need no import. Aggregates keep `Src` so scope
+ * checking still sees through `bs.x.max()`; `count` is source-less because `count(x)` is 0, not null,
+ * when `x`'s table is left-joined away; `coalesce` drops `Src` on purpose, since its whole job is to
+ * remove the nullability a left join adds.
+ */
+interface Expr<R, Src extends string = string> {
+  readonly [exprBrand]: ExprBrand<R, Src>;
+  eq(value: R | ExprLike<R> | undefined): SqlCondition;
+  ne(value: R | ExprLike<R> | undefined): SqlCondition;
+  gt(value: R | ExprLike<R> | undefined): SqlCondition;
+  gte(value: R | ExprLike<R> | undefined): SqlCondition;
+  lt(value: R | ExprLike<R> | undefined): SqlCondition;
+  lte(value: R | ExprLike<R> | undefined): SqlCondition;
+  in(values: readonly R[] | ExprLike<R | null> | undefined): SqlCondition;
+  nin(values: readonly R[] | ExprLike<R | null> | undefined): SqlCondition;
+  /** Prefixes this expression and a space to a raw predicate; write .is`IS NULL`, not .is`NULL`. */
+  is(strings: TemplateStringsArray, ...values: unknown[]): SqlCondition;
+  /** Orders by this expression in ascending order. */
+  asc(): ExpressionOrderBy;
+  /** Orders by this expression in descending order. */
+  desc(): ExpressionOrderBy;
+  /** `count(x)::int`; `count(a.id)` is `count(*)` for the FROM table, and the matched-row count for a left-joined one. */
+  count(): Expr<number, never>;
+  countDistinct(): Expr<number, never>;
+  sum(this: Expr<number | null, Src>): Expr<number | null, Src>;
+  avg(this: Expr<number | null, Src>): Expr<number | null, Src>;
+  min(): Expr<R | null, Src>;
+  max(): Expr<R | null, Src>;
+  /** PG keeps element NULLs (a left-joined empty group aggregates as `[null]`), and zero rows aggregate as NULL. */
+  arrayAgg(options?: ArrayAggOptions): Expr<R[] | null, Src>;
+  stringAgg(this: Expr<string | null, Src>, delimiter: string): Expr<string | null, Src>;
+  coalesce(fallback: NonNullable<R>): Expr<NonNullable<R>, never>;
+}
+/**
+ * A join entry: the join kind is the key, the joined source is the value, plus `on`. `inner?: never` /
+ * `left?: never` keep an entry to one kind (the `SqlCondition` `and`/`or` trick).
+ *
+ * `on` is required. A join is pruned when nothing references it anymore, not by an `undefined` ON;
+ * `keep: true` pins a join that would otherwise prune, i.e. an inner join used as an existence filter,
+ * the way em.find's `keepAliases` does. It is a boolean so callers can pass a flag.
+ *
+ * Declared here (not `query.ts`) so the relation join factories in `Tables.ts` (i.e. `a.books.as(b)`) can
+ * return them without importing `query.ts`; `query.ts` re-constrains `A` to its `QuerySource`.
+ */
+interface InnerJoin<A, C = SqlCondition> {
+  readonly inner: A;
+  readonly left?: never;
+  readonly on: C;
+  readonly keep?: boolean;
+}
+interface LeftJoin<A, C = SqlCondition> {
+  readonly left: A;
+  readonly inner?: never;
+  readonly on: C;
+  readonly keep?: boolean;
+}
+/** SQL plus its `?` bindings plus the SQL aliases it references, i.e. for join pruning. */
+interface SqlFragment {
+  sql: string;
+  bindings: any[];
+  refs: string[];
+}
+/**
+ * What an expression needs from the query it is generating SQL for: the SQL alias assigned to each
+ * source, and a way to turn nested conditions into SQL (which needs `ConditionBuilder`, so it lives in `query.ts`).
+ */
+interface ExprContext {
+  /** Returns the SQL alias for a table's `TableMgmt` or a subquery handle, searching enclosing queries. */
+  aliasFor(handle: object): string;
+  /** Turns a user-facing condition into SQL; `undefined` if it pruned away entirely. */
+  conditionToSql(cond: QueryCondition): SqlFragment | undefined;
+}
+declare function isExpr(value: unknown): value is ExprLike<any>;
+/** Every `Expr` is a `BaseExpr` at runtime; this cast keeps `isExpr` a plain type guard so unions narrow. */
+declare function asNode(expr: ExprLike<any>): BaseExpr;
+declare const deferredSym: unique symbol;
+/**
+ * A condition whose SQL depends on aliases that are only known once the query is parsed, i.e.
+ * `bookStats.bookCount.gt(1)` or `bs.authorId.eq(a.id)`.
+ *
+ * It is shaped like a `RawCondition` with a SQL brand so it can sit in any `SqlCondition`; `resolveDeferredConditions`
+ * snapshots `condition`, `bindings`, and `aliases` before the filter is parsed. Domain alias conditions
+ * use a separate protocol in the `em.find` parser.
+ */
+interface DeferredCondition extends RawCondition, PredicateBrand<"sql"> {
+  [deferredSym]: (ctx: ExprContext) => RawCondition;
+}
+declare function isDeferredCondition(cond: unknown): cond is DeferredCondition;
+/** Creates a `DeferredCondition` that generates its SQL with `fn` once the query's aliases are known. */
+declare function deferredCondition(fn: (ctx: ExprContext) => SqlFragment): DeferredCondition;
+/**
+ * Resolve each condition occurrence and snapshot it before resolving the next one. A nested subquery
+ * may reuse the same condition under another alias; it must not overwrite this occurrence's SQL.
+ */
+declare function resolveDeferredConditions(cond: ConditionInput | undefined, ctx: ExprContext): ConditionInput | undefined;
+/** Concatenates SQL fragments with `sep`, keeping bindings and refs in order. */
+declare function joinFragments(parts: SqlFragment[], sep: string): SqlFragment;
+/**
+ * The methods every expression shares. Subclasses provide `toSql`, and usually `decode`/`encode`.
+ *
+ * Table columns can override comparisons to apply column-specific conversions. Domain aliases do not
+ * implement this protocol.
+ */
+declare abstract class BaseExpr {
+  readonly [exprBrand]: any;
+  /** Produces this expression's SQL so it can be embedded in a larger expression, i.e. a subquery gets parens. */
+  abstract toSql(ctx: ExprContext): SqlFragment;
+  /** Only an actual scalar/IN subquery exposes its selected expression, not an ordinary ID expression. */
+  get subquerySelect(): BaseExpr | undefined;
+  /** Known SQL representation and logical domain; raw SQL and unmodeled refs remain unknown. */
+  get outputType(): TypeInfo | undefined;
+  /** Physical SQL nullability; undefined means unknown, not a NOT NULL guarantee. */
+  get sqlNullable(): boolean | undefined;
+  /** The source of a direct column reference, whose value becomes NULL under an unmatched LEFT join. */
+  get sqlSource(): object | undefined;
+  /** Produces the SQL without the outer parens a subquery normally gets; only differs for subqueries. */
+  toSqlBare(ctx: ExprContext): SqlFragment;
+  /** Converts a result-set value into the domain value, i.e. an int into a tagged id. */
+  decode(value: unknown): unknown;
+  /** Converts a domain value into the database value, i.e. a tagged id into an int, for bindings. */
+  encode(value: unknown): unknown;
+  eq(value: unknown): SqlCondition;
+  ne(value: unknown): SqlCondition;
+  gt(value: unknown): SqlCondition;
+  gte(value: unknown): SqlCondition;
+  lt(value: unknown): SqlCondition;
+  lte(value: unknown): SqlCondition;
+  in(values: unknown): SqlCondition;
+  nin(values: unknown): SqlCondition;
+  /** Prefixes this expression to a SQL template, retaining bindings and referenced aliases. */
+  is(strings: TemplateStringsArray, ...values: unknown[]): SqlCondition;
+  /** Orders by this expression in ascending order. */
+  asc(): ExpressionOrderBy;
+  /** Orders by this expression in descending order. */
+  desc(): ExpressionOrderBy;
+  count(): Expr<number, never>;
+  countDistinct(): Expr<number, never>;
+  sum(): Expr<number | null, any>;
+  avg(): Expr<number | null, any>;
+  min(): Expr<any, any>;
+  max(): Expr<any, any>;
+  arrayAgg(options?: ArrayAggOptions): Expr<any, any>;
+  stringAgg(delimiter: string): Expr<string | null, any>;
+  coalesce(fallback: unknown): Expr<any, never>;
+  /** `this op value`, where `value` may be `undefined` (pruned), `null`, another expression, or a literal. */
+  protected compare(op: string, value: unknown): SqlCondition;
+  /** `this IN (subquery)` or `this = ANY(?)` for a list; `NOT IN` / `!= ALL(?)` for `nin`. */
+  protected inList(op: "IN" | "NOT IN", values: unknown): SqlCondition;
+}
+/**
+ * A SQL function applied to expressions, i.e. `count(a."id")::int` or `coalesce(bs."n", ?)`.
+ *
+ * By default decoding is identity and encoding follows the first argument. Callers explicitly supply
+ * a decoder and output type when needed (`max(a.id)` is still an id); numeric aggregates supply their
+ * own decoder/encoder, since `count(a.id)` is a number, not an id. Unknown functions have no output type.
+ */
+declare class FnExpr extends BaseExpr {
+  private name;
+  private args;
+  private opts;
+  constructor(name: string, args: BaseExpr[], opts: {
+    prefix?: string;
+    suffix?: string;
+    decode?: (value: unknown) => unknown;
+    encode?: (value: unknown) => unknown;
+    outputType?: TypeInfo;
+    aggregate?: ArrayAggOptions;
+  });
+  get outputType(): TypeInfo | undefined;
+  get sqlNullable(): boolean | undefined;
+  /**
+   * Renders function arguments, aggregate ordering, and the filter in SQL binding order.
+   * Keep references from all three so aggregate-only joins are retained.
+   */
+  toSql(ctx: ExprContext): SqlFragment;
+  decode(value: unknown): unknown;
+  encode(value: unknown): unknown;
+}
+/** A bound literal, i.e. the `?` in `coalesce(x, ?)`. */
+declare class BindingExpr extends BaseExpr {
+  private value;
+  constructor(value: unknown);
+  get sqlNullable(): boolean;
+  toSql(): SqlFragment;
+}
+/** An unmodeled column on a known source, i.e. `a.column("ts_search")`. */
+declare class RefExpr extends BaseExpr {
+  private handle;
+  private column;
+  constructor(handle: object, column: string);
+  get sqlSource(): object;
+  toSql(ctx: ExprContext): SqlFragment;
+}
+/**
+ * A `sql` tagged template.
+ *
+ * For an Author table `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"]
+ * ```
+ */
+declare class TemplateExpr extends BaseExpr {
+  private strings;
+  private values;
+  constructor(strings: TemplateStringsArray, values: unknown[]);
+  toSql(ctx: ExprContext): SqlFragment;
+}
+/** Turns one `${...}` of a `sql` template into SQL: an expression, a condition, or a bound value. */
+declare function interpolationToSql(value: unknown, ctx: ExprContext): SqlFragment;
+/** True for the user-facing condition shapes: `{ and }`, `{ or }`, `ColumnCondition`, `RawCondition`. */
+declare function isConditionLike(value: unknown): boolean;
+/** Renders an expression order for either a query or an aggregate, or prunes an undefined order. */
+declare function orderByToSql(o: ExpressionOrderBy, ctx: ExprContext): SqlFragment | undefined;
+//#endregion
+export { ArrayAggOptions, BaseExpr, BindingExpr, DeferredCondition, Expr, ExprBrand, ExprContext, ExprLike, FnExpr, InnerJoin, LeftJoin, RefExpr, SqlFragment, TemplateExpr, asNode, deferredCondition, deferredSym, exprBrand, interpolationToSql, isConditionLike, isDeferredCondition, isExpr, joinFragments, orderByToSql, resolveDeferredConditions, selectKeyBrand };
+//# sourceMappingURL=Expr.d.mts.map

package/build/queries/sql/Expr.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Expr.d.mts","names":[],"sources":["../../../src/queries/sql/Expr.ts"],"mappings":"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"}