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

package/build/Expr.d.cts

@@ -1,274 +0,0 @@
-import { ConditionInput, PredicateBrand, SqlCondition } from "./conditions.cjs";
-import { TypeInfo } from "./TypeInfo.cjs";
-import { ExpressionOrderBy, QueryCondition } from "./query.cjs";
-import { RawCondition } from "./QueryParser.cjs";
-//#region src/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;
-/**
- * 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. `sql.ref` on an unknown table
- */
-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;
-  /** `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;
-  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. `sql.ref(a, "ts_search")`; untracked at the type level. */
-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 };
-//# sourceMappingURL=Expr.d.cts.map

package/build/Expr.d.cts.map

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

package/build/Expr.d.mts

@@ -1,274 +0,0 @@
-import { ConditionInput, PredicateBrand, SqlCondition } from "./conditions.mjs";
-import { TypeInfo } from "./TypeInfo.mjs";
-import { ExpressionOrderBy, QueryCondition } from "./query.mjs";
-import { RawCondition } from "./QueryParser.mjs";
-//#region src/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;
-/**
- * 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. `sql.ref` on an unknown table
- */
-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;
-  /** `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;
-  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. `sql.ref(a, "ts_search")`; untracked at the type level. */
-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 };
-//# sourceMappingURL=Expr.d.mts.map

package/build/Expr.d.mts.map

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