metal-orm 1.0.62 → 1.0.64

package/dist/index.d.ts

@@ -883,6 +883,11 @@ type ExpressionNode = BinaryExpressionNode | LogicalExpressionNode | NullExpress
 
 type LiteralValue = LiteralNode['value'];
 type ValueOperandInput = OperandNode | LiteralValue;
+type TypedLike<T> = {
+    tsType?: T;
+} | {
+    __tsType: T;
+};
 /**
  * Converts a primitive or existing operand into an operand node
  * @param value - Value or operand to normalize
@@ -914,272 +919,481 @@ declare const aliasRef: (name: string) => AliasRefNode;
  */
 declare const correlateBy: (table: string, column: string) => ColumnNode;
 /**
- * Creates an equality expression (left = right)
- * @param left - Left operand
- * @param right - Right operand
- * @returns Binary expression node with equality operator
+ * Creates an equality expression (`left = right`).
+ *
+ * Supports type safety when used with `ColumnDef` objects containing strict type information.
+ *
+ * @param left - The left operand (column or value).
+ * @param right - The right operand (column or value).
+ * @returns A `BinaryExpressionNode` representing the equality check.
+ *
+ * @example
+ * // Basic usage
+ * eq(users.id, 1);
+ *
+ * // With strict typing (typescript will error if types mismatch)
+ * eq(users.firstName, 'Ada');
  */
-declare const eq: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number | boolean) => BinaryExpressionNode;
+declare function eq<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+declare function eq(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number | boolean): BinaryExpressionNode;
 /**
- * Creates a not equal expression (left != right)
+ * Creates a not equal expression (`left != right`).
+ *
+ * @param left - The left operand (column or value).
+ * @param right - The right operand (column or value).
+ * @returns A `BinaryExpressionNode` representing the inequality check.
+ *
+ * @example
+ * neq(users.status, 'inactive');
  */
-declare const neq: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number | boolean) => BinaryExpressionNode;
+declare function neq<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+declare function neq(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number | boolean): BinaryExpressionNode;
 /**
- * Creates a greater-than expression (left > right)
- * @param left - Left operand
- * @param right - Right operand
- * @returns Binary expression node with greater-than operator
+ * Creates a greater-than expression (`left > right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns A `BinaryExpressionNode`.
+ *
+ * @example
+ * gt(users.age, 18);
  */
-declare const gt: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BinaryExpressionNode;
+declare function gt<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+declare function gt(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode;
 /**
- * Creates a greater than or equal expression (left >= right)
+ * Creates a greater-than-or-equal expression (`left >= right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns A `BinaryExpressionNode`.
+ *
+ * @example
+ * gte(users.score, 100);
  */
-declare const gte: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BinaryExpressionNode;
+declare function gte<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+declare function gte(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode;
 /**
- * Creates a less-than expression (left < right)
- * @param left - Left operand
- * @param right - Right operand
- * @returns Binary expression node with less-than operator
+ * Creates a less-than expression (`left < right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns A `BinaryExpressionNode`.
+ *
+ * @example
+ * lt(inventory.stock, 5);
  */
-declare const lt: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BinaryExpressionNode;
+declare function lt<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+declare function lt(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode;
 /**
- * Creates a less than or equal expression (left <= right)
+ * Creates a less-than-or-equal expression (`left <= right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns A `BinaryExpressionNode`.
+ *
+ * @example
+ * lte(products.price, 50.00);
  */
-declare const lte: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BinaryExpressionNode;
+declare function lte<T>(left: TypedLike<T>, right: T | TypedLike<T>): BinaryExpressionNode;
+declare function lte(left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode;
 /**
- * Creates a LIKE pattern matching expression
- * @param left - Left operand
- * @param pattern - Pattern to match
- * @param escape - Optional escape character
- * @returns Binary expression node with LIKE operator
+ * Creates a `LIKE` pattern matching expression.
+ *
+ * @param left - The column or expression to check.
+ * @param pattern - The pattern string (e.g., 'A%').
+ * @param escape - Optional escape character.
+ * @returns A `BinaryExpressionNode`.
+ *
+ * @example
+ * like(users.email, '%@gmail.com');
  */
 declare const like: (left: OperandNode | ColumnRef, pattern: string, escape?: string) => BinaryExpressionNode;
 /**
- * Creates a NOT LIKE pattern matching expression
- * @param left - Left operand
- * @param pattern - Pattern to match
- * @param escape - Optional escape character
- * @returns Binary expression node with NOT LIKE operator
+ * Creates a `NOT LIKE` pattern matching expression.
+ *
+ * @param left - The column or expression to check.
+ * @param pattern - The pattern string.
+ * @param escape - Optional escape character.
+ * @returns A `BinaryExpressionNode`.
+ *
+ * @example
+ * notLike(users.email, 'test%');
  */
 declare const notLike: (left: OperandNode | ColumnRef, pattern: string, escape?: string) => BinaryExpressionNode;
 /**
- * Creates a logical AND expression
- * @param operands - Expressions to combine with AND
- * @returns Logical expression node with AND operator
+ * Creates a logical AND expression to combine multiple conditions.
+ *
+ * @param operands - One or more conditions to combine.
+ * @returns A `LogicalExpressionNode`.
+ *
+ * @example
+ * and(
+ *   eq(users.isActive, true),
+ *   gt(users.age, 18)
+ * );
  */
 declare const and: (...operands: ExpressionNode[]) => LogicalExpressionNode;
 /**
- * Creates a logical OR expression
- * @param operands - Expressions to combine with OR
- * @returns Logical expression node with OR operator
+ * Creates a logical OR expression to combine multiple conditions.
+ *
+ * @param operands - One or more conditions to combine.
+ * @returns A `LogicalExpressionNode`.
+ *
+ * @example
+ * or(
+ *   eq(users.role, 'admin'),
+ *   eq(users.role, 'moderator')
+ * );
  */
 declare const or: (...operands: ExpressionNode[]) => LogicalExpressionNode;
 /**
- * Creates an IS NULL expression
- * @param left - Operand to check for null
- * @returns Null expression node with IS NULL operator
+ * Creates an IS NULL check (`left IS NULL`).
+ *
+ * @param left - The operand to check.
+ * @returns A `NullExpressionNode`.
+ *
+ * @example
+ * isNull(users.deletedAt);
  */
 declare const isNull: (left: OperandNode | ColumnRef) => NullExpressionNode;
 /**
- * Creates an IS NOT NULL expression
- * @param left - Operand to check for non-null
- * @returns Null expression node with IS NOT NULL operator
+ * Creates an IS NOT NULL check (`left IS NOT NULL`).
+ *
+ * @param left - The operand to check.
+ * @returns A `NullExpressionNode`.
+ *
+ * @example
+ * isNotNull(users.email);
  */
 declare const isNotNull: (left: OperandNode | ColumnRef) => NullExpressionNode;
 /**
- * Creates an IN expression (value IN list)
- * @param left - Operand to check
- * @param values - Values to check against
- * @returns IN expression node
+ * Creates an IN list check (`left IN (v1, v2, ...)`).
+ *
+ * @param left - The operand to check.
+ * @param values - An array of values to check against.
+ * @returns An `InExpressionNode`.
+ *
+ * @example
+ * inList(users.status, ['active', 'pending']);
  */
 declare const inList: (left: OperandNode | ColumnRef, values: (string | number | LiteralNode)[]) => InExpressionNode;
 /**
- * Creates a NOT IN expression (value NOT IN list)
- * @param left - Operand to check
- * @param values - Values to check against
- * @returns NOT IN expression node
+ * Creates a NOT IN list check (`left NOT IN (v1, v2, ...)`).
+ *
+ * @param left - The operand to check.
+ * @param values - An array of values to check against.
+ * @returns An `InExpressionNode`.
+ *
+ * @example
+ * notInList(users.id, [1, 2, 3]);
  */
 declare const notInList: (left: OperandNode | ColumnRef, values: (string | number | LiteralNode)[]) => InExpressionNode;
+/**
+ * Creates an IN subquery check (`left IN (SELECT ...)`).
+ *
+ * @param left - The operand to check.
+ * @param subquery - The subquery to run.
+ * @returns An `InExpressionNode`.
+ *
+ * @example
+ * inSubquery(
+ *   posts.authorId,
+ *   selectFromEntity(User).select({ id: users.id }).where(eq(users.isActive, true))
+ * );
+ */
 declare const inSubquery: (left: OperandNode | ColumnRef, subquery: SelectQueryInput) => InExpressionNode;
+/**
+ * Creates a NOT IN subquery check (`left NOT IN (SELECT ...)`).
+ *
+ * @param left - The operand to check.
+ * @param subquery - The subquery to run.
+ * @returns An `InExpressionNode`.
+ *
+ * @example
+ * notInSubquery(
+ *   users.id,
+ *   selectFromEntity(Blacklist).select({ userId: blacklist.userId })
+ * );
+ */
 declare const notInSubquery: (left: OperandNode | ColumnRef, subquery: SelectQueryInput) => InExpressionNode;
 /**
- * Creates a BETWEEN expression (value BETWEEN lower AND upper)
- * @param left - Operand to check
- * @param lower - Lower bound
- * @param upper - Upper bound
- * @returns BETWEEN expression node
+ * Creates a BETWEEN check (`left BETWEEN lower AND upper`).
+ *
+ * @param left - The operand to check.
+ * @param lower - The lower bound (inclusive).
+ * @param upper - The upper bound (inclusive).
+ * @returns A `BetweenExpressionNode`.
+ *
+ * @example
+ * between(products.price, 10, 100);
  */
 declare const between: (left: OperandNode | ColumnRef, lower: OperandNode | ColumnRef | string | number, upper: OperandNode | ColumnRef | string | number) => BetweenExpressionNode;
 /**
- * Creates a NOT BETWEEN expression (value NOT BETWEEN lower AND upper)
- * @param left - Operand to check
- * @param lower - Lower bound
- * @param upper - Upper bound
- * @returns NOT BETWEEN expression node
+ * Creates a NOT BETWEEN check (`left NOT BETWEEN lower AND upper`).
+ *
+ * @param left - The operand to check.
+ * @param lower - The lower bound (inclusive).
+ * @param upper - The upper bound (inclusive).
+ * @returns A `BetweenExpressionNode`.
+ *
+ * @example
+ * notBetween(users.age, 20, 30);
  */
 declare const notBetween: (left: OperandNode | ColumnRef, lower: OperandNode | ColumnRef | string | number, upper: OperandNode | ColumnRef | string | number) => BetweenExpressionNode;
+/**
+ * Creates an addition expression (`left + right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns An `ArithmeticExpressionNode`.
+ */
 declare const add: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
+/**
+ * Creates a subtraction expression (`left - right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns An `ArithmeticExpressionNode`.
+ */
 declare const sub: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
+/**
+ * Creates a multiplication expression (`left * right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns An `ArithmeticExpressionNode`.
+ */
 declare const mul: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
+/**
+ * Creates a division expression (`left / right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns An `ArithmeticExpressionNode`.
+ */
 declare const div: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
 /**
- * Creates a bitwise AND expression (left & right)
+ * Creates a bitwise AND expression (`left & right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns A `BitwiseExpressionNode`.
  */
 declare const bitAnd: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BitwiseExpressionNode;
 /**
- * Creates a bitwise OR expression (left | right)
+ * Creates a bitwise OR expression (`left | right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns A `BitwiseExpressionNode`.
  */
 declare const bitOr: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BitwiseExpressionNode;
 /**
- * Creates a bitwise XOR expression (left ^ right)
+ * Creates a bitwise XOR expression (`left ^ right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand.
+ * @returns A `BitwiseExpressionNode`.
  */
 declare const bitXor: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BitwiseExpressionNode;
 /**
- * Creates a bitwise shift left expression (left << right)
+ * Creates a bitwise left-shift expression (`left << right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand (number of bits).
+ * @returns A `BitwiseExpressionNode`.
  */
 declare const shiftLeft: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BitwiseExpressionNode;
 /**
- * Creates a bitwise shift right expression (left >> right)
+ * Creates a bitwise right-shift expression (`left >> right`).
+ *
+ * @param left - The left operand.
+ * @param right - The right operand (number of bits).
+ * @returns A `BitwiseExpressionNode`.
  */
 declare const shiftRight: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BitwiseExpressionNode;
 /**
- * Creates a JSON path expression
- * @param col - Source column
- * @param path - JSON path expression
- * @returns JSON path node
+ * Creates a JSON path extraction expression.
+ *
+ * @param col - The source column (should be a JSON/JSONB column).
+ * @param path - The JSON path expression (e.g., '$.address.city').
+ * @returns A `JsonPathNode`.
+ *
+ * @example
+ * jsonPath(users.profile, '$.settings.theme');
  */
 declare const jsonPath: (col: ColumnRef | ColumnNode, path: string) => JsonPathNode;
 /**
- * Creates a CASE expression
- * @param conditions - Array of WHEN-THEN conditions
- * @param elseValue - Optional ELSE value
- * @returns CASE expression node
+ * Creates a CASE expression (`CASE WHEN ... THEN ... ELSE ... END`).
+ *
+ * @param conditions - An array of `{ when, then }` objects.
+ * @param elseValue - Optional value for the `ELSE` clause.
+ * @returns A `CaseExpressionNode`.
+ *
+ * @example
+ * caseWhen([
+ *   { when: gt(users.age, 65), then: 'Senior' },
+ *   { when: gt(users.age, 18), then: 'Adult' }
+ * ], 'Minor');
  */
 declare const caseWhen: (conditions: {
     when: ExpressionNode;
     then: OperandNode | ColumnRef | string | number | boolean | null;
 }[], elseValue?: OperandNode | ColumnRef | string | number | boolean | null) => CaseExpressionNode;
 /**
- * Builds a CAST expression node for casting values to SQL types.
+ * Creates a CAST expression (`CAST(expression AS type)`).
+ *
+ * @param expression - The expression to cast.
+ * @param castType - The target SQL type (e.g., 'VARCHAR', 'INTEGER').
+ * @returns A `CastExpressionNode`.
+ *
+ * @example
+ * cast(users.age, 'VARCHAR');
  */
 declare const cast: (expression: OperandNode | ColumnRef | string | number | boolean | null, castType: string) => CastExpressionNode;
 /**
- * Creates an EXISTS expression
- * @param subquery - Subquery to check for existence
- * @returns EXISTS expression node
+ * Creates an EXISTS check (`EXISTS (SELECT ...)`).
+ *
+ * @param subquery - The subquery to check.
+ * @returns An `ExistsExpressionNode`.
+ *
+ * @example
+ * exists(
+ *   selectFromEntity(Order).where(eq(orders.userId, users.id))
+ * );
  */
 declare const exists: (subquery: SelectQueryNode) => ExistsExpressionNode;
 /**
- * Creates a NOT EXISTS expression
- * @param subquery - Subquery to check for non-existence
- * @returns NOT EXISTS expression node
+ * Creates a NOT EXISTS check (`NOT EXISTS (SELECT ...)`).
+ *
+ * @param subquery - The subquery to check.
+ * @returns An `ExistsExpressionNode`.
+ *
+ * @example
+ * notExists(
+ *   selectFromEntity(Subscription).where(eq(subscriptions.userId, users.id))
+ * );
  */
 declare const notExists: (subquery: SelectQueryNode) => ExistsExpressionNode;
 /**
- * Creates a COLLATE expression (expression COLLATE collationName)
- * @param expression - Expression to be collated
- * @param collation - Collation name
- * @returns COLLATE expression node
+ * Creates a COLLATE expression (`expression COLLATE collation`).
+ *
+ * @param expression - The expression string.
+ * @param collation - The collation name (e.g., 'nocase').
+ * @returns A `CollateExpressionNode`.
+ *
+ * @example
+ * collate(users.email, 'nocase');
  */
 declare const collate: (expression: OperandNode | ColumnRef | string | number | boolean | null, collation: string) => CollateExpressionNode;
 
 /**
- * Creates a ROW_NUMBER window function
- * @returns Window function node for ROW_NUMBER
+ * Creates a ROW_NUMBER window function.
+ *
+ * @returns A `TypedExpression<number>` representing the `ROW_NUMBER` window function.
  */
-declare const rowNumber: () => WindowFunctionNode;
+declare const rowNumber: () => TypedExpression<number>;
 /**
- * Creates a RANK window function
- * @returns Window function node for RANK
+ * Creates a RANK window function.
+ *
+ * @returns A `TypedExpression<number>` representing the `RANK` window function.
  */
-declare const rank: () => WindowFunctionNode;
+declare const rank: () => TypedExpression<number>;
 /**
- * Creates a DENSE_RANK window function
- * @returns Window function node for DENSE_RANK
+ * Creates a DENSE_RANK window function.
+ *
+ * @returns A `TypedExpression<number>` representing the `DENSE_RANK` window function.
  */
-declare const denseRank: () => WindowFunctionNode;
+declare const denseRank: () => TypedExpression<number>;
 /**
- * Creates an NTILE window function
- * @param n - Number of buckets
- * @returns Window function node for NTILE
+ * Creates an NTILE window function.
+ *
+ * @param n - Number of buckets.
+ * @returns A `TypedExpression<number>` representing the `NTILE` window function.
  */
-declare const ntile: (n: number) => WindowFunctionNode;
+declare const ntile: (n: number) => TypedExpression<number>;
 /**
- * Creates a LAG window function
- * @param col - Column to lag
- * @param offset - Offset (defaults to 1)
- * @param defaultValue - Default value if no row exists
- * @returns Window function node for LAG
+ * Creates a LAG window function.
+ *
+ * @param col - Column or expression to lag.
+ * @param offset - Optional offset (defaults to 1).
+ * @param defaultValue - Optional default value.
+ * @returns A `TypedExpression<T>` representing the `LAG` window function.
  */
-declare const lag: (col: ColumnRef | ColumnNode, offset?: number, defaultValue?: LiteralNode["value"]) => WindowFunctionNode;
+declare const lag: <T = any>(col: ColumnRef | ColumnNode, offset?: number, defaultValue?: LiteralNode["value"]) => TypedExpression<T>;
 /**
- * Creates a LEAD window function
- * @param col - Column to lead
- * @param offset - Offset (defaults to 1)
- * @param defaultValue - Default value if no row exists
- * @returns Window function node for LEAD
+ * Creates a LEAD window function.
+ *
+ * @param col - Column or expression to lead.
+ * @param offset - Optional offset (defaults to 1).
+ * @param defaultValue - Optional default value.
+ * @returns A `TypedExpression<T>` representing the `LEAD` window function.
  */
-declare const lead: (col: ColumnRef | ColumnNode, offset?: number, defaultValue?: LiteralNode["value"]) => WindowFunctionNode;
+declare const lead: <T = any>(col: ColumnRef | ColumnNode, offset?: number, defaultValue?: LiteralNode["value"]) => TypedExpression<T>;
 /**
- * Creates a FIRST_VALUE window function
- * @param col - Column to get first value from
- * @returns Window function node for FIRST_VALUE
+ * Creates a FIRST_VALUE window function.
+ *
+ * @param col - Column or expression to get first value from.
+ * @returns A `TypedExpression<T>` representing the `FIRST_VALUE` window function.
  */
-declare const firstValue: (col: ColumnRef | ColumnNode) => WindowFunctionNode;
+declare const firstValue: <T = any>(col: ColumnRef | ColumnNode) => TypedExpression<T>;
 /**
- * Creates a LAST_VALUE window function
- * @param col - Column to get last value from
- * @returns Window function node for LAST_VALUE
+ * Creates a LAST_VALUE window function.
+ *
+ * @param col - Column or expression to get last value from.
+ * @returns A `TypedExpression<T>` representing the `LAST_VALUE` window function.
  */
-declare const lastValue: (col: ColumnRef | ColumnNode) => WindowFunctionNode;
+declare const lastValue: <T = any>(col: ColumnRef | ColumnNode) => TypedExpression<T>;
 /**
- * Creates a custom window function
- * @param name - Window function name
- * @param args - Function arguments
- * @param partitionBy - Optional PARTITION BY columns
- * @param orderBy - Optional ORDER BY clauses
- * @returns Window function node
+ * Creates a custom window function.
+ *
+ * @param name - Window function name.
+ * @param args - Function arguments.
+ * @param partitionBy - Optional PARTITION BY columns.
+ * @param orderBy - Optional ORDER BY clauses.
+ * @returns A `TypedExpression<T>` representing the window function.
  */
-declare const windowFunction: (name: string, args?: (ColumnRef | ColumnNode | LiteralNode | JsonPathNode)[], partitionBy?: (ColumnRef | ColumnNode)[], orderBy?: {
+declare const windowFunction: <T = any>(name: string, args?: (ColumnRef | ColumnNode | LiteralNode | JsonPathNode)[], partitionBy?: (ColumnRef | ColumnNode)[], orderBy?: {
     column: ColumnRef | ColumnNode;
     direction: OrderDirection;
-}[]) => WindowFunctionNode;
+}[]) => TypedExpression<T>;
 
 /**
  * Creates a COUNT function expression
  * @param col - Column to count
  * @returns Function node with COUNT
  */
-declare const count: (col: ColumnRef | ColumnNode) => FunctionNode;
+declare const count: (col: ColumnRef | ColumnNode) => TypedExpression<number>;
 /**
  * Creates a SUM function expression
  * @param col - Column to sum
  * @returns Function node with SUM
  */
-declare const sum: (col: ColumnRef | ColumnNode) => FunctionNode;
+declare const sum: (col: ColumnRef | ColumnNode) => TypedExpression<number>;
 /**
  * Creates an AVG function expression
  * @param col - Column to average
  * @returns Function node with AVG
  */
-declare const avg: (col: ColumnRef | ColumnNode) => FunctionNode;
+declare const avg: (col: ColumnRef | ColumnNode) => TypedExpression<number>;
 /**
  * Creates a MIN function expression
  * @param col - Column to take the minimum of
  * @returns Function node with MIN
  */
-declare const min: (col: ColumnRef | ColumnNode) => FunctionNode;
+declare const min: (col: ColumnRef | ColumnNode) => TypedExpression<number>;
 /**
  * Creates a MAX function expression
  * @param col - Column to take the maximum of
  * @returns Function node with MAX
  */
-declare const max: (col: ColumnRef | ColumnNode) => FunctionNode;
+declare const max: (col: ColumnRef | ColumnNode) => TypedExpression<number>;
 /**
  * Creates a COUNT(*) function expression.
- * @returns Function node with COUNT(*)
+ *
+ * @returns A `TypedExpression<number>` representing the `COUNT(*)` SQL function.
  */
-declare const countAll: () => FunctionNode;
+declare const countAll: () => TypedExpression<number>;
 type GroupConcatOrderByInput = {
     column: ColumnRef | ColumnNode;
     direction?: OrderDirection;
@@ -1190,20 +1404,27 @@ type GroupConcatOptions = {
 };
 /**
  * Aggregates grouped strings into a single value.
+ *
+ * @param col - Column or expression to aggregate.
+ * @param options - Optional separator and ordering.
+ * @returns A `TypedExpression<string>` representing the `GROUP_CONCAT` SQL function.
+ *
+ * @example
+ * groupConcat(users.name, { separator: ', ', orderBy: [{ column: users.name }] });
  */
-declare const groupConcat: (col: ColumnRef | ColumnNode, options?: GroupConcatOptions) => FunctionNode;
+declare const groupConcat: (col: ColumnRef | ColumnNode, options?: GroupConcatOptions) => TypedExpression<string>;
 /**
  * Creates a STDDEV function expression
  * @param col - Column to calculate standard deviation for
  * @returns Function node with STDDEV
  */
-declare const stddev: (col: ColumnRef | ColumnNode) => FunctionNode;
+declare const stddev: (col: ColumnRef | ColumnNode) => TypedExpression<number>;
 /**
  * Creates a VARIANCE function expression
  * @param col - Column to calculate variance for
  * @returns Function node with VARIANCE
  */
-declare const variance: (col: ColumnRef | ColumnNode) => FunctionNode;
+declare const variance: (col: ColumnRef | ColumnNode) => TypedExpression<number>;
 
 /**
  * Visitor for expression nodes
@@ -1274,6 +1495,16 @@ declare const toColumnRef: (col: ColumnRef | ColumnDef) => ColumnRef;
  */
 declare const toTableRef: (table: TableRef | TableDef) => TableRef;
 
+/**
+ * Expression AST nodes and builders.
+ * Re-exports components for building and visiting SQL expression trees.
+ */
+
+type TypedExpression<T> = (FunctionNode | CaseExpressionNode | WindowFunctionNode) & {
+    __tsType: T;
+};
+declare const asType: <T>(expr: FunctionNode | CaseExpressionNode | WindowFunctionNode) => TypedExpression<T>;
+
 /**
  * AST node representing a JOIN clause
  */
@@ -3494,7 +3725,12 @@ type RelationCallback = <TChildTable extends TableDef>(qb: SelectQueryBuilder<un
 
 type SelectDialectInput = Dialect | DialectKey;
 
-type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode;
+type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode | TypedExpression<unknown>;
+type SelectionValueType<TValue> = TValue extends TypedExpression<infer TRuntime> ? TRuntime : TValue extends ColumnDef ? ColumnToTs<TValue> : unknown;
+type SelectionResult<TSelection extends Record<string, ColumnSelectionValue>> = {
+    [K in keyof TSelection]: SelectionValueType<TSelection[K]>;
+};
+type SelectionFromKeys<TTable extends TableDef, K extends keyof TTable['columns'] & string> = Pick<InferRow<TTable>, K>;
 type DeepSelectEntry<TTable extends TableDef> = {
     type: 'root';
     columns: (keyof TTable['columns'] & string)[];
@@ -3509,7 +3745,7 @@ type DeepSelectConfig<TTable extends TableDef> = DeepSelectEntry<TTable>[];
  * @typeParam T - Result type for projections (unused)
  * @typeParam TTable - Table definition being queried
  */
-declare class SelectQueryBuilder<T = EntityInstance<any>, TTable extends TableDef = TableDef> {
+declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends TableDef = TableDef> {
     private readonly env;
     private readonly context;
     private readonly columnSelector;
@@ -3530,7 +3766,7 @@ declare class SelectQueryBuilder<T = EntityInstance<any>, TTable extends TableDe
      * @param hydration - Optional hydration manager
      * @param dependencies - Optional query builder dependencies
      */
-    constructor(table: TTable, state?: SelectQueryState, hydration?: HydrationManager, dependencies?: Partial<SelectQueryBuilderDependencies>, lazyRelations?: Set<string>, lazyRelationOptions?: Map<string, RelationIncludeOptions>, entityConstructor?: EntityConstructor<any>);
+    constructor(table: TTable, state?: SelectQueryState, hydration?: HydrationManager, dependencies?: Partial<SelectQueryBuilderDependencies>, lazyRelations?: Set<string>, lazyRelationOptions?: Map<string, RelationIncludeOptions>, entityConstructor?: EntityConstructor);
     /**
      * Creates a new SelectQueryBuilder instance with updated context and lazy relations
      * @param context - Updated query context
@@ -3580,8 +3816,8 @@ declare class SelectQueryBuilder<T = EntityInstance<any>, TTable extends TableDe
      *   fullName: concat(userTable.columns.firstName, ' ', userTable.columns.lastName)
      * });
      */
-    select<K extends keyof TTable['columns'] & string>(...args: K[]): SelectQueryBuilder<T, TTable>;
-    select(columns: Record<string, ColumnSelectionValue>): SelectQueryBuilder<T, TTable>;
+    select<K extends keyof TTable['columns'] & string>(...args: K[]): SelectQueryBuilder<T & SelectionFromKeys<TTable, K>, TTable>;
+    select<TSelection extends Record<string, ColumnSelectionValue>>(columns: TSelection): SelectQueryBuilder<T & SelectionResult<TSelection>, TTable>;
     /**
      * Selects raw column expressions
      * @param cols - Column expressions as strings
@@ -3670,7 +3906,7 @@ declare class SelectQueryBuilder<T = EntityInstance<any>, TTable extends TableDe
      * qb.select('id', 'name')
      *   .selectSubquery('postCount', postCount);
      */
-    selectSubquery<TSub extends TableDef>(alias: string, sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
+    selectSubquery<TValue = unknown, K extends string = string, TSub extends TableDef = TableDef>(alias: K, sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T & Record<K, TValue>, TTable>;
     /**
      * Adds a JOIN against a derived table (subquery with alias)
      * @param subquery - Subquery to join
@@ -4997,598 +5233,766 @@ declare const getSchemaIntrospector: (dialect: DialectName) => SchemaIntrospecto
 type OperandInput$5 = OperandNode | ColumnDef | string | number | boolean | null;
 /**
  * Converts a string to lowercase.
- * @param value - The string value.
- * @returns A FunctionNode representing the LOWER SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `LOWER` SQL function.
+ *
+ * @example
+ * lower(users.email);
  */
-declare const lower: (value: OperandInput$5) => FunctionNode;
+declare const lower: (value: OperandInput$5) => TypedExpression<string>;
 /**
  * Converts a string to uppercase.
- * @param value - The string value.
- * @returns A FunctionNode representing the UPPER SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `UPPER` SQL function.
+ *
+ * @example
+ * upper(users.firstName);
  */
-declare const upper: (value: OperandInput$5) => FunctionNode;
+declare const upper: (value: OperandInput$5) => TypedExpression<string>;
 /**
  * Returns the ASCII code of the first character of a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the ASCII SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<number>` representing the `ASCII` SQL function.
+ *
+ * @example
+ * ascii(users.initial);
  */
-declare const ascii: (value: OperandInput$5) => FunctionNode;
+declare const ascii: (value: OperandInput$5) => TypedExpression<number>;
 /**
  * Returns a string from one or more ASCII codes.
- * @param codes - The ASCII codes.
- * @returns A FunctionNode representing the CHAR SQL function.
+ *
+ * @param codes - One or more ASCII codes.
+ * @returns A `TypedExpression<string>` representing the `CHAR` SQL function.
+ *
+ * @example
+ * char(65, 66, 67); // 'ABC'
  */
-declare const char: (...codes: OperandInput$5[]) => FunctionNode;
+declare const char: (...codes: OperandInput$5[]) => TypedExpression<string>;
 /**
  * Returns the number of characters in a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the CHAR_LENGTH SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<number>` representing the `CHAR_LENGTH` SQL function.
+ *
+ * @example
+ * charLength(users.bio);
  */
-declare const charLength: (value: OperandInput$5) => FunctionNode;
+declare const charLength: (value: OperandInput$5) => TypedExpression<number>;
 /**
  * Returns the length of a string in bytes or characters.
- * @param value - The string value.
- * @returns A FunctionNode representing the LENGTH SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<number>` representing the `LENGTH` SQL function.
+ *
+ * @example
+ * length(users.password);
  */
-declare const length: (value: OperandInput$5) => FunctionNode;
+declare const length: (value: OperandInput$5) => TypedExpression<number>;
 /**
  * Removes leading and trailing whitespace or specified characters from a string.
- * @param value - The string value.
- * @param chars - The characters to trim (optional).
- * @returns A FunctionNode representing the TRIM SQL function.
+ *
+ * @param value - The string value or column.
+ * @param chars - Optional characters to trim.
+ * @returns A `TypedExpression<string>` representing the `TRIM` SQL function.
+ *
+ * @example
+ * trim(users.name);
+ * trim(users.path, '/');
  */
-declare const trim: (value: OperandInput$5, chars?: OperandInput$5) => FunctionNode;
+declare const trim: (value: OperandInput$5, chars?: OperandInput$5) => TypedExpression<string>;
 /**
  * Removes leading whitespace from a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the LTRIM SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `LTRIM` SQL function.
  */
-declare const ltrim: (value: OperandInput$5) => FunctionNode;
+declare const ltrim: (value: OperandInput$5) => TypedExpression<string>;
 /**
  * Removes trailing whitespace from a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the RTRIM SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `RTRIM` SQL function.
  */
-declare const rtrim: (value: OperandInput$5) => FunctionNode;
+declare const rtrim: (value: OperandInput$5) => TypedExpression<string>;
 /**
  * Concatenates two or more strings.
- * @param args - The strings to concatenate.
- * @returns A FunctionNode representing the CONCAT SQL function.
+ *
+ * @param args - The strings or columns to concatenate.
+ * @returns A `TypedExpression<string>` representing the `CONCAT` SQL function.
+ *
+ * @example
+ * concat(users.firstName, ' ', users.lastName);
  */
-declare const concat: (...args: OperandInput$5[]) => FunctionNode;
+declare const concat: (...args: OperandInput$5[]) => TypedExpression<string>;
 /**
  * Concatenates strings with a separator.
+ *
  * @param separator - The separator string.
- * @param args - The strings to concatenate.
- * @returns A FunctionNode representing the CONCAT_WS SQL function.
+ * @param args - The strings or columns to concatenate.
+ * @returns A `TypedExpression<string>` representing the `CONCAT_WS` SQL function.
+ *
+ * @example
+ * concatWs(', ', users.lastName, users.firstName);
  */
-declare const concatWs: (separator: OperandInput$5, ...args: OperandInput$5[]) => FunctionNode;
+declare const concatWs: (separator: OperandInput$5, ...args: OperandInput$5[]) => TypedExpression<string>;
 /**
  * Extracts a substring from a string.
- * @param value - The string value.
- * @param start - The starting position.
- * @param length - The length of the substring (optional).
- * @returns A FunctionNode representing the SUBSTR SQL function.
+ *
+ * @param value - The input string or column.
+ * @param start - The starting position (1-indexed).
+ * @param length - Optional length of the substring.
+ * @returns A `TypedExpression<string>` representing the `SUBSTR` SQL function.
+ *
+ * @example
+ * substr(users.token, 1, 8);
  */
-declare const substr: (value: OperandInput$5, start: OperandInput$5, length?: OperandInput$5) => FunctionNode;
+declare const substr: (value: OperandInput$5, start: OperandInput$5, length?: OperandInput$5) => TypedExpression<string>;
 /**
  * Returns the leftmost characters of a string.
- * @param value - The string value.
- * @param len - The number of characters to return.
- * @returns A FunctionNode representing the LEFT SQL function.
+ *
+ * @param value - The string value or column.
+ * @param len - Number of characters to return.
+ * @returns A `TypedExpression<string>` representing the `LEFT` SQL function.
  */
-declare const left: (value: OperandInput$5, len: OperandInput$5) => FunctionNode;
+declare const left: (value: OperandInput$5, len: OperandInput$5) => TypedExpression<string>;
 /**
  * Returns the rightmost characters of a string.
- * @param value - The string value.
- * @param len - The number of characters to return.
- * @returns A FunctionNode representing the RIGHT SQL function.
+ *
+ * @param value - The string value or column.
+ * @param len - Number of characters to return.
+ * @returns A `TypedExpression<string>` representing the `RIGHT` SQL function.
  */
-declare const right: (value: OperandInput$5, len: OperandInput$5) => FunctionNode;
+declare const right: (value: OperandInput$5, len: OperandInput$5) => TypedExpression<string>;
 /**
  * Returns the position of a substring in a string.
+ *
  * @param substring - The substring to search for.
- * @param value - The string to search in.
- * @returns A FunctionNode representing the POSITION SQL function.
+ * @param value - The string or column to search within.
+ * @returns A `TypedExpression<number>` representing the `POSITION` SQL function.
  */
-declare const position: (substring: OperandInput$5, value: OperandInput$5) => FunctionNode;
+declare const position: (substring: OperandInput$5, value: OperandInput$5) => TypedExpression<number>;
 /**
  * Returns the position of a substring in a string.
- * @param value - The string to search in.
+ *
+ * @param value - The string or column to search within.
  * @param substring - The substring to search for.
- * @returns A FunctionNode representing the INSTR SQL function.
+ * @returns A `TypedExpression<number>` representing the `INSTR` SQL function.
  */
-declare const instr: (value: OperandInput$5, substring: OperandInput$5) => FunctionNode;
+declare const instr: (value: OperandInput$5, substring: OperandInput$5) => TypedExpression<number>;
 /**
  * Returns the position of a substring in a string, optionally starting from a position.
- * @param substring - The substring to search for.
- * @param value - The string to search in.
- * @param start - The starting position (optional).
- * @returns A FunctionNode representing the LOCATE SQL function.
+ *
+ * @param substring - Substring to find.
+ * @param value - String/column to search.
+ * @param start - Optional starting position.
+ * @returns A `TypedExpression<number>` representing the `LOCATE` SQL function.
  */
-declare const locate: (substring: OperandInput$5, value: OperandInput$5, start?: OperandInput$5) => FunctionNode;
+declare const locate: (substring: OperandInput$5, value: OperandInput$5, start?: OperandInput$5) => TypedExpression<number>;
 /**
  * Replaces occurrences of a substring in a string.
- * @param value - The string to search in.
- * @param search - The substring to replace.
- * @param replacement - The replacement string.
- * @returns A FunctionNode representing the REPLACE SQL function.
+ *
+ * @param value - The original string or column.
+ * @param search - Substring to search for.
+ * @param replacement - Replacement string.
+ * @returns A `TypedExpression<string>` representing the `REPLACE` SQL function.
+ *
+ * @example
+ * replace(users.email, 'old.com', 'new.com');
  */
-declare const replace: (value: OperandInput$5, search: OperandInput$5, replacement: OperandInput$5) => FunctionNode;
+declare const replace: (value: OperandInput$5, search: OperandInput$5, replacement: OperandInput$5) => TypedExpression<string>;
 /**
  * Repeats a string a specified number of times.
+ *
  * @param value - The string to repeat.
- * @param count - The number of times to repeat.
- * @returns A FunctionNode representing the REPEAT SQL function.
+ * @param count - How many times to repeat.
+ * @returns A `TypedExpression<string>` representing the `REPEAT` SQL function.
  */
-declare const repeat: (value: OperandInput$5, count: OperandInput$5) => FunctionNode;
+declare const repeat: (value: OperandInput$5, count: OperandInput$5) => TypedExpression<string>;
 /**
  * Left-pads a string to a certain length with another string.
- * @param value - The string to pad.
- * @param len - The length to pad to.
- * @param pad - The padding string.
- * @returns A FunctionNode representing the LPAD SQL function.
+ *
+ * @param value - The string/column to pad.
+ * @param len - Target length.
+ * @param pad - Padding string.
+ * @returns A `TypedExpression<string>` representing the `LPAD` SQL function.
  */
-declare const lpad: (value: OperandInput$5, len: OperandInput$5, pad: OperandInput$5) => FunctionNode;
+declare const lpad: (value: OperandInput$5, len: OperandInput$5, pad: OperandInput$5) => TypedExpression<string>;
 /**
  * Right-pads a string to a certain length with another string.
- * @param value - The string to pad.
- * @param len - The length to pad to.
- * @param pad - The padding string.
- * @returns A FunctionNode representing the RPAD SQL function.
+ *
+ * @param value - The string/column to pad.
+ * @param len - Target length.
+ * @param pad - Padding string.
+ * @returns A `TypedExpression<string>` representing the `RPAD` SQL function.
  */
-declare const rpad: (value: OperandInput$5, len: OperandInput$5, pad: OperandInput$5) => FunctionNode;
+declare const rpad: (value: OperandInput$5, len: OperandInput$5, pad: OperandInput$5) => TypedExpression<string>;
 /**
  * Returns a string consisting of a specified number of spaces.
- * @param count - The number of spaces.
- * @returns A FunctionNode representing the SPACE SQL function.
+ *
+ * @param count - Number of spaces.
+ * @returns A `TypedExpression<string>` representing the `SPACE` SQL function.
  */
-declare const space: (count: OperandInput$5) => FunctionNode;
+declare const space: (count: OperandInput$5) => TypedExpression<string>;
 /**
  * Reverses a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the REVERSE SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `REVERSE` SQL function.
  */
-declare const reverse: (value: OperandInput$5) => FunctionNode;
+declare const reverse: (value: OperandInput$5) => TypedExpression<string>;
 /**
  * Capitalizes the first letter of each word in a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the INITCAP SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `INITCAP` SQL function.
  */
-declare const initcap: (value: OperandInput$5) => FunctionNode;
+declare const initcap: (value: OperandInput$5) => TypedExpression<string>;
 /**
  * Returns the MD5 hash of a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the MD5 SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `MD5` SQL function.
  */
-declare const md5: (value: OperandInput$5) => FunctionNode;
+declare const md5: (value: OperandInput$5) => TypedExpression<string>;
 /**
  * Returns the SHA-1 hash of a string.
- * @param value - The string value.
- * @returns A FunctionNode representing the SHA1 SQL function.
+ *
+ * @param value - The string value or column.
+ * @returns A `TypedExpression<string>` representing the `SHA1` SQL function.
  */
-declare const sha1: (value: OperandInput$5) => FunctionNode;
+declare const sha1: (value: OperandInput$5) => TypedExpression<string>;
 /**
  * Returns the SHA-2 hash of a string with a specified bit length.
- * @param value - The string value.
- * @param bits - The bit length (e.g., 224, 256, 384, 512).
- * @returns A FunctionNode representing the SHA2 SQL function.
+ *
+ * @param value - The input.
+ * @param bits - Bit length (e.g., 256, 512).
+ * @returns A `TypedExpression<string>` representing the `SHA2` SQL function.
  */
-declare const sha2: (value: OperandInput$5, bits: OperandInput$5) => FunctionNode;
+declare const sha2: (value: OperandInput$5, bits: OperandInput$5) => TypedExpression<string>;
 /**
  * Returns the length of a string in bits.
- * @param value - The string value.
- * @returns A FunctionNode representing the BIT_LENGTH SQL function.
+ *
+ * @param value - String value or column.
+ * @returns A `TypedExpression<number>` representing the `BIT_LENGTH` SQL function.
  */
-declare const bitLength: (value: OperandInput$5) => FunctionNode;
+declare const bitLength: (value: OperandInput$5) => TypedExpression<number>;
 /**
  * Returns the length of a string in bytes.
- * @param value - The string value.
- * @returns A FunctionNode representing the OCTET_LENGTH SQL function.
+ *
+ * @param value - String value or column.
+ * @returns A `TypedExpression<number>` representing the `OCTET_LENGTH` SQL function.
  */
-declare const octetLength: (value: OperandInput$5) => FunctionNode;
+declare const octetLength: (value: OperandInput$5) => TypedExpression<number>;
 /**
  * Returns a string from an ASCII code.
- * @param code - The ASCII code.
- * @returns A FunctionNode representing the CHR/CHAR SQL function.
+ *
+ * @param code - ASCII code.
+ * @returns A `TypedExpression<string>` representing the `CHR` SQL function.
  */
-declare const chr: (code: OperandInput$5) => FunctionNode;
+declare const chr: (code: OperandInput$5) => TypedExpression<string>;
 
 type OperandInput$4 = OperandNode | ColumnDef | string | number | boolean | null;
 /**
  * Returns the absolute value of a number.
- * @param value - The numeric value.
- * @returns A FunctionNode representing the ABS SQL function.
+ *
+ * @param value - The numeric value or column.
+ * @returns A `TypedExpression<number>` representing the `ABS` SQL function.
+ *
+ * @example
+ * abs(transactions.amount);
  */
-declare const abs: (value: OperandInput$4) => FunctionNode;
+declare const abs: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the arccosine (inverse cosine) of a number.
- * @param value - The numeric value.
- * @returns A FunctionNode representing the ACOS SQL function.
+ *
+ * @param value - The numeric value or column.
+ * @returns A `TypedExpression<number>` representing the `ACOS` SQL function.
  */
-declare const acos: (value: OperandInput$4) => FunctionNode;
+declare const acos: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the arcsine (inverse sine) of a number.
- * @param value - The numeric value.
- * @returns A FunctionNode representing the ASIN SQL function.
+ *
+ * @param value - The numeric value or column.
+ * @returns A `TypedExpression<number>` representing the `ASIN` SQL function.
  */
-declare const asin: (value: OperandInput$4) => FunctionNode;
+declare const asin: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the arctangent (inverse tangent) of a number.
- * @param value - The numeric value.
- * @returns A FunctionNode representing the ATAN SQL function.
+ *
+ * @param value - The numeric value or column.
+ * @returns A `TypedExpression<number>` representing the `ATAN` SQL function.
  */
-declare const atan: (value: OperandInput$4) => FunctionNode;
+declare const atan: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the arctangent of the two arguments.
+ *
  * @param y - The y-coordinate.
  * @param x - The x-coordinate.
- * @returns A FunctionNode representing the ATAN2 SQL function.
+ * @returns A `TypedExpression<number>` representing the `ATAN2` SQL function.
  */
-declare const atan2: (y: OperandInput$4, x: OperandInput$4) => FunctionNode;
+declare const atan2: (y: OperandInput$4, x: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the smallest integer greater than or equal to a number.
- * @param value - The numeric value.
- * @returns A FunctionNode representing the CEIL SQL function.
+ *
+ * @param value - The numeric value or column.
+ * @returns A `TypedExpression<number>` representing the `CEIL` SQL function.
  */
-declare const ceil: (value: OperandInput$4) => FunctionNode;
+declare const ceil: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Alias for ceil. Returns the smallest integer greater than or equal to a number.
- * @param value - The numeric value.
- * @returns A FunctionNode representing the CEILING SQL function.
+ *
+ * @param value - The numeric value or column.
+ * @returns A `TypedExpression<number>` representing the `CEILING` SQL function.
  */
-declare const ceiling: (value: OperandInput$4) => FunctionNode;
+declare const ceiling: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the cosine of a number (in radians).
+ *
  * @param value - The numeric value in radians.
- * @returns A FunctionNode representing the COS SQL function.
+ * @returns A `TypedExpression<number>` representing the `COS` SQL function.
  */
-declare const cos: (value: OperandInput$4) => FunctionNode;
+declare const cos: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the cotangent of a number.
+ *
  * @param value - The numeric value.
- * @returns A FunctionNode representing the COT SQL function.
+ * @returns A `TypedExpression<number>` representing the `COT` SQL function.
  */
-declare const cot: (value: OperandInput$4) => FunctionNode;
+declare const cot: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Converts radians to degrees.
+ *
  * @param value - The angle in radians.
- * @returns A FunctionNode representing the DEGREES SQL function.
+ * @returns A `TypedExpression<number>` representing the `DEGREES` SQL function.
  */
-declare const degrees: (value: OperandInput$4) => FunctionNode;
+declare const degrees: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns e raised to the power of the argument.
+ *
  * @param value - The exponent.
- * @returns A FunctionNode representing the EXP SQL function.
+ * @returns A `TypedExpression<number>` representing the `EXP` SQL function.
  */
-declare const exp: (value: OperandInput$4) => FunctionNode;
+declare const exp: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the largest integer less than or equal to a number.
+ *
  * @param value - The numeric value.
- * @returns A FunctionNode representing the FLOOR SQL function.
+ * @returns A `TypedExpression<number>` representing the `FLOOR` SQL function.
  */
-declare const floor: (value: OperandInput$4) => FunctionNode;
+declare const floor: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the natural logarithm (base e) of a number.
+ *
  * @param value - The numeric value.
- * @returns A FunctionNode representing the LN SQL function.
+ * @returns A `TypedExpression<number>` representing the `LN` SQL function.
  */
-declare const ln: (value: OperandInput$4) => FunctionNode;
+declare const ln: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the base-10 logarithm of a number.
+ *
  * @param value - The numeric value.
- * @returns A FunctionNode representing the LOG SQL function.
+ * @returns A `TypedExpression<number>` representing the `LOG` SQL function.
  */
-declare const log: (value: OperandInput$4) => FunctionNode;
+declare const log: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the base-10 logarithm of a number.
+ *
  * @param value - The numeric value.
- * @returns A FunctionNode representing the LOG10 SQL function.
+ * @returns A `TypedExpression<number>` representing the `LOG10` SQL function.
  */
-declare const log10: (value: OperandInput$4) => FunctionNode;
+declare const log10: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the logarithm of a number for a specific base.
+ *
  * @param base - The base of the logarithm.
  * @param value - The numeric value.
- * @returns A FunctionNode representing the LOG_BASE SQL function.
+ * @returns A `TypedExpression<number>` representing the `LOG_BASE` SQL function.
  */
-declare const logBase: (base: OperandInput$4, value: OperandInput$4) => FunctionNode;
+declare const logBase: (base: OperandInput$4, value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the remainder of dividing x by y.
+ *
  * @param x - The dividend.
  * @param y - The divisor.
- * @returns A FunctionNode representing the MOD SQL function.
+ * @returns A `TypedExpression<number>` representing the `MOD` SQL function.
  */
-declare const mod: (x: OperandInput$4, y: OperandInput$4) => FunctionNode;
+declare const mod: (x: OperandInput$4, y: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the value of PI (approximately 3.14159...).
- * @returns A FunctionNode representing the PI SQL function.
+ *
+ * @returns A `TypedExpression<number>` representing the `PI` SQL function.
  */
-declare const pi: () => FunctionNode;
+declare const pi: () => TypedExpression<number>;
 /**
  * Returns x raised to the power of y.
+ *
  * @param x - The base.
  * @param y - The exponent.
- * @returns A FunctionNode representing the POWER SQL function.
+ * @returns A `TypedExpression<number>` representing the `POWER` SQL function.
  */
-declare const power: (x: OperandInput$4, y: OperandInput$4) => FunctionNode;
+declare const power: (x: OperandInput$4, y: OperandInput$4) => TypedExpression<number>;
 /**
  * Alias for power. Returns x raised to the power of y.
+ *
  * @param x - The base.
  * @param y - The exponent.
- * @returns A FunctionNode representing the POW SQL function.
+ * @returns A `TypedExpression<number>` representing the `POW` SQL function.
  */
-declare const pow: (x: OperandInput$4, y: OperandInput$4) => FunctionNode;
+declare const pow: (x: OperandInput$4, y: OperandInput$4) => TypedExpression<number>;
 /**
  * Converts degrees to radians.
+ *
  * @param value - The angle in degrees.
- * @returns A FunctionNode representing the RADIANS SQL function.
+ * @returns A `TypedExpression<number>` representing the `RADIANS` SQL function.
  */
-declare const radians: (value: OperandInput$4) => FunctionNode;
+declare const radians: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns a random number between 0 and 1.
- * @returns A FunctionNode representing the RANDOM SQL function.
+ *
+ * @returns A `TypedExpression<number>` representing the `RANDOM` SQL function.
  */
-declare const random: () => FunctionNode;
+declare const random: () => TypedExpression<number>;
 /**
  * Alias for random. Returns a random number between 0 and 1.
- * @returns A FunctionNode representing the RAND SQL function.
+ *
+ * @returns A `TypedExpression<number>` representing the `RAND` SQL function.
  */
-declare const rand: () => FunctionNode;
+declare const rand: () => TypedExpression<number>;
 /**
  * Rounds a number to a specified number of decimal places.
+ *
  * @param value - The numeric value to round.
- * @param decimals - The number of decimal places (optional).
- * @returns A FunctionNode representing the ROUND SQL function.
+ * @param decimals - Optional number of decimal places.
+ * @returns A `TypedExpression<number>` representing the `ROUND` SQL function.
  */
-declare const round: (value: OperandInput$4, decimals?: OperandInput$4) => FunctionNode;
+declare const round: (value: OperandInput$4, decimals?: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the sign of a number (-1 for negative, 0 for zero, 1 for positive).
+ *
  * @param value - The numeric value.
- * @returns A FunctionNode representing the SIGN SQL function.
+ * @returns A `TypedExpression<number>` representing the `SIGN` SQL function.
  */
-declare const sign: (value: OperandInput$4) => FunctionNode;
+declare const sign: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the sine of a number (in radians).
+ *
  * @param value - The numeric value in radians.
- * @returns A FunctionNode representing the SIN SQL function.
+ * @returns A `TypedExpression<number>` representing the `SIN` SQL function.
  */
-declare const sin: (value: OperandInput$4) => FunctionNode;
+declare const sin: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the square root of a number.
- * @param value - The numeric value.
- * @returns A FunctionNode representing the SQRT SQL function.
+ *
+ * @param value - The numeric value or column.
+ * @returns A `TypedExpression<number>` representing the `SQRT` SQL function.
  */
-declare const sqrt: (value: OperandInput$4) => FunctionNode;
+declare const sqrt: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the tangent of a number (in radians).
+ *
  * @param value - The numeric value in radians.
- * @returns A FunctionNode representing the TAN SQL function.
+ * @returns A `TypedExpression<number>` representing the `TAN` SQL function.
  */
-declare const tan: (value: OperandInput$4) => FunctionNode;
+declare const tan: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Truncates a number to a specified number of decimal places without rounding.
+ *
  * @param value - The numeric value to truncate.
- * @param decimals - The number of decimal places (optional).
- * @returns A FunctionNode representing the TRUNC SQL function.
+ * @param decimals - Optional number of decimal places.
+ * @returns A `TypedExpression<number>` representing the `TRUNC` SQL function.
  */
-declare const trunc: (value: OperandInput$4, decimals?: OperandInput$4) => FunctionNode;
+declare const trunc: (value: OperandInput$4, decimals?: OperandInput$4) => TypedExpression<number>;
 /**
  * Alias for trunc. Truncates a number to a specified number of decimal places without rounding.
+ *
  * @param value - The numeric value to truncate.
  * @param decimals - The number of decimal places.
- * @returns A FunctionNode representing the TRUNCATE SQL function.
+ * @returns A `TypedExpression<number>` representing the `TRUNCATE` SQL function.
  */
-declare const truncate: (value: OperandInput$4, decimals: OperandInput$4) => FunctionNode;
+declare const truncate: (value: OperandInput$4, decimals: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the base-2 logarithm of a number.
- * @param value - The numeric value.
- * @returns A FunctionNode representing the LOG2 SQL function.
+ *
+ * @param value - The numeric value or column.
+ * @returns A `TypedExpression<number>` representing the `LOG2` SQL function.
  */
-declare const log2: (value: OperandInput$4) => FunctionNode;
+declare const log2: (value: OperandInput$4) => TypedExpression<number>;
 /**
  * Returns the cube root of a number.
- * @param value - The numeric value.
- * @returns A FunctionNode representing the CBRT SQL function.
+ *
+ * @param value - The numeric value or column.
+ * @returns A `TypedExpression<number>` representing the `CBRT` SQL function.
  */
-declare const cbrt: (value: OperandInput$4) => FunctionNode;
+declare const cbrt: (value: OperandInput$4) => TypedExpression<number>;
 
 type OperandInput$3 = OperandNode | ColumnDef | string | number | boolean | null;
 /**
  * Returns the current local date and time.
- * @returns A FunctionNode representing the NOW() SQL function.
+ *
+ * @returns A `TypedExpression<Date>` representing the `NOW()` SQL function.
  */
-declare const now: () => FunctionNode;
+declare const now: () => TypedExpression<Date>;
 /**
- * Returns the current date without time.
- * @returns A FunctionNode representing the CURRENT_DATE SQL function.
+ * Returns the current date (without time).
+ *
+ * @returns A `TypedExpression<Date>` representing the `CURRENT_DATE` SQL function.
  */
-declare const currentDate: () => FunctionNode;
+declare const currentDate: () => TypedExpression<Date>;
 /**
- * Returns the current time without date.
- * @returns A FunctionNode representing the CURRENT_TIME SQL function.
+ * Returns the current time (without date).
+ *
+ * @returns A `TypedExpression<Date>` representing the `CURRENT_TIME` SQL function.
  */
-declare const currentTime: () => FunctionNode;
+declare const currentTime: () => TypedExpression<Date>;
 /**
  * Returns the current UTC date and time.
- * @returns A FunctionNode representing the UTC_NOW() SQL function.
+ *
+ * @returns A `TypedExpression<Date>` representing the `UTC_NOW()` SQL function.
  */
-declare const utcNow: () => FunctionNode;
+declare const utcNow: () => TypedExpression<Date>;
 /**
  * Returns the current local time.
- * @returns A FunctionNode representing the LOCALTIME SQL function.
+ *
+ * @returns A `TypedExpression<Date>` representing the `LOCALTIME` SQL function.
  */
-declare const localTime: () => FunctionNode;
+declare const localTime: () => TypedExpression<Date>;
 /**
  * Returns the current local timestamp.
- * @returns A FunctionNode representing the LOCALTIMESTAMP SQL function.
+ *
+ * @returns A `TypedExpression<Date>` representing the `LOCALTIMESTAMP` SQL function.
  */
-declare const localTimestamp: () => FunctionNode;
+declare const localTimestamp: () => TypedExpression<Date>;
 /**
  * Extracts a specified part from a date or datetime value.
- * @param part - The date part to extract (e.g., 'YEAR', 'MONTH', 'DAY', 'HOUR', 'MINUTE', 'SECOND').
- * @param date - The date or datetime value to extract from.
- * @returns A FunctionNode representing the EXTRACT SQL function.
+ *
+ * @param part - The date part to extract (e.g., 'YEAR', 'MONTH', 'DAY').
+ * @param date - The date/datetime value or column.
+ * @returns A `TypedExpression<number>` representing the `EXTRACT` SQL function.
  */
-declare const extract: (part: OperandInput$3, date: OperandInput$3) => FunctionNode;
+declare const extract: (part: OperandInput$3, date: OperandInput$3) => TypedExpression<number>;
 /**
  * Extracts the year from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the YEAR SQL function.
+ *
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `YEAR` SQL function.
  */
-declare const year: (date: OperandInput$3) => FunctionNode;
+declare const year: (date: OperandInput$3) => TypedExpression<number>;
 /**
  * Extracts the month from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the MONTH SQL function.
+ *
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `MONTH` SQL function.
  */
-declare const month: (date: OperandInput$3) => FunctionNode;
+declare const month: (date: OperandInput$3) => TypedExpression<number>;
 /**
  * Extracts the day of the month from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the DAY SQL function.
+ *
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `DAY` SQL function.
  */
-declare const day: (date: OperandInput$3) => FunctionNode;
+declare const day: (date: OperandInput$3) => TypedExpression<number>;
 /**
  * Adds a specified time interval to a date or datetime value.
- * @param date - The date or datetime value to add to.
- * @param interval - The number of units to add.
- * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND').
- * @returns A FunctionNode representing the DATE_ADD SQL function.
+ *
+ * @param date - The base date.
+ * @param interval - The numeric interval to add.
+ * @param unit - The unit (e.g., 'DAY', 'MONTH').
+ * @returns A `TypedExpression<Date>` representing the `DATE_ADD` SQL function.
  */
-declare const dateAdd: (date: OperandInput$3, interval: OperandInput$3, unit: OperandInput$3) => FunctionNode;
+declare const dateAdd: (date: OperandInput$3, interval: OperandInput$3, unit: OperandInput$3) => TypedExpression<Date>;
 /**
  * Subtracts a specified time interval from a date or datetime value.
- * @param date - The date or datetime value to subtract from.
- * @param interval - The number of units to subtract.
- * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND').
- * @returns A FunctionNode representing the DATE_SUB SQL function.
+ *
+ * @param date - The base date.
+ * @param interval - The numeric interval to subtract.
+ * @param unit - The unit (e.g., 'DAY', 'MONTH').
+ * @returns A `TypedExpression<Date>` representing the `DATE_SUB` SQL function.
  */
-declare const dateSub: (date: OperandInput$3, interval: OperandInput$3, unit: OperandInput$3) => FunctionNode;
+declare const dateSub: (date: OperandInput$3, interval: OperandInput$3, unit: OperandInput$3) => TypedExpression<Date>;
 /**
  * Returns the difference between two dates in days.
- * @param date1 - The end date.
- * @param date2 - The start date.
- * @returns A FunctionNode representing the DATE_DIFF SQL function.
+ *
+ * @param date1 - End date.
+ * @param date2 - Start date.
+ * @returns A `TypedExpression<number>` representing the `DATE_DIFF` SQL function.
  */
-declare const dateDiff: (date1: OperandInput$3, date2: OperandInput$3) => FunctionNode;
+declare const dateDiff: (date1: OperandInput$3, date2: OperandInput$3) => TypedExpression<number>;
 /**
  * Converts a date or datetime value to a formatted string.
- * @param date - The date or datetime value to format.
- * @param format - The format string (dialect-specific).
- * @returns A FunctionNode representing the DATE_FORMAT SQL function.
+ *
+ * @param date - The date value.
+ * @param format - Dialect-specific format string.
+ * @returns A `TypedExpression<string>` representing the `DATE_FORMAT` SQL function.
  */
-declare const dateFormat: (date: OperandInput$3, format: OperandInput$3) => FunctionNode;
+declare const dateFormat: (date: OperandInput$3, format: OperandInput$3) => TypedExpression<string>;
 /**
- * Returns the current Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).
- * @returns A FunctionNode representing the UNIX_TIMESTAMP SQL function.
+ * Returns the current Unix timestamp (seconds since epoch).
+ *
+ * @returns A `TypedExpression<number>` representing the `UNIX_TIMESTAMP` SQL function.
  */
-declare const unixTimestamp: () => FunctionNode;
+declare const unixTimestamp: () => TypedExpression<number>;
 /**
- * Converts a Unix timestamp (seconds since 1970-01-01 00:00:00 UTC) to a date.
- * @param timestamp - Unix timestamp in seconds.
- * @returns A FunctionNode representing the FROM_UNIXTIME SQL function.
+ * Converts a Unix timestamp to a Date.
+ *
+ * @param timestamp - Seconds since epoch.
+ * @returns A `TypedExpression<Date>` representing the `FROM_UNIXTIME` SQL function.
  */
-declare const fromUnixTime: (timestamp: OperandInput$3) => FunctionNode;
+declare const fromUnixTime: (timestamp: OperandInput$3) => TypedExpression<Date>;
 /**
  * Returns the last day of the month for a given date.
+ *
  * @param date - The date value.
- * @returns A FunctionNode representing the END_OF_MONTH SQL function.
+ * @returns A `TypedExpression<Date>` representing the `END_OF_MONTH` SQL function.
  */
-declare const endOfMonth: (date: OperandInput$3) => FunctionNode;
+declare const endOfMonth: (date: OperandInput$3) => TypedExpression<Date>;
 /**
  * Returns the index of the weekday for a given date (1 = Sunday, 2 = Monday, etc.).
+ *
  * @param date - The date value.
- * @returns A FunctionNode representing the DAY_OF_WEEK SQL function.
+ * @returns A `TypedExpression<number>` representing the `DAY_OF_WEEK` SQL function.
  */
-declare const dayOfWeek: (date: OperandInput$3) => FunctionNode;
+declare const dayOfWeek: (date: OperandInput$3) => TypedExpression<number>;
 /**
  * Returns the week number of the year for a given date.
+ *
  * @param date - The date value.
- * @returns A FunctionNode representing the WEEK_OF_YEAR SQL function.
+ * @returns A `TypedExpression<number>` representing the `WEEK_OF_YEAR` SQL function.
  */
-declare const weekOfYear: (date: OperandInput$3) => FunctionNode;
+declare const weekOfYear: (date: OperandInput$3) => TypedExpression<number>;
 /**
- * Truncates a date or datetime value to a specified precision (e.g., first day of the month/year).
- * @param part - The truncation precision (e.g., 'YEAR', 'MONTH', 'DAY').
- * @param date - The date or datetime value to truncate.
- * @returns A FunctionNode representing the DATE_TRUNC SQL function.
+ * Truncates a date or datetime value to a specified precision.
+ *
+ * @param part - The precision (e.g., 'YEAR', 'MONTH').
+ * @param date - The date to truncate.
+ * @returns A `TypedExpression<Date>` representing the `DATE_TRUNC` SQL function.
  */
-declare const dateTrunc: (part: OperandInput$3, date: OperandInput$3) => FunctionNode;
+declare const dateTrunc: (part: OperandInput$3, date: OperandInput$3) => TypedExpression<Date>;
 /**
- * Returns the difference between two timestamps as an interval.
- * @param timestamp - The end timestamp.
- * @param baseTimestamp - The start timestamp (optional, defaults to current time).
- * @returns A FunctionNode representing the AGE SQL function.
+ * Returns the difference between two timestamps as an interval string.
+ *
+ * @param timestamp - End timestamp.
+ * @param baseTimestamp - Optional start timestamp.
+ * @returns A `TypedExpression<string>` representing the `AGE` SQL function.
  */
-declare const age: (timestamp: OperandInput$3, baseTimestamp?: OperandInput$3) => FunctionNode;
+declare const age: (timestamp: OperandInput$3, baseTimestamp?: OperandInput$3) => TypedExpression<string>;
 /**
  * Extracts the hour from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the HOUR SQL function.
+ *
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `HOUR` SQL function.
  */
-declare const hour: (date: OperandInput$3) => FunctionNode;
+declare const hour: (date: OperandInput$3) => TypedExpression<number>;
 /**
  * Extracts the minute from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the MINUTE SQL function.
+ *
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `MINUTE` SQL function.
  */
-declare const minute: (date: OperandInput$3) => FunctionNode;
+declare const minute: (date: OperandInput$3) => TypedExpression<number>;
 /**
  * Extracts the second from a date or datetime value.
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the SECOND SQL function.
+ *
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `SECOND` SQL function.
  */
-declare const second: (date: OperandInput$3) => FunctionNode;
+declare const second: (date: OperandInput$3) => TypedExpression<number>;
 /**
  * Extracts the quarter from a date or datetime value (1-4).
- * @param date - The date or datetime value.
- * @returns A FunctionNode representing the QUARTER SQL function.
+ *
+ * @param date - The date value.
+ * @returns A `TypedExpression<number>` representing the `QUARTER` SQL function.
  */
-declare const quarter: (date: OperandInput$3) => FunctionNode;
+declare const quarter: (date: OperandInput$3) => TypedExpression<number>;
 
 type OperandInput$2 = OperandNode | ColumnDef | string | number | boolean | null;
 /**
  * Returns the first non-null value in a list.
- * @param args - The list of values to check.
- * @returns A FunctionNode representing the COALESCE SQL function.
+ *
+ * @param args - The list of values or columns to check.
+ * @returns A `TypedExpression<T>` representing the `COALESCE` SQL function.
+ *
+ * @example
+ * coalesce(users.nickname, users.firstName, 'Guest');
  */
-declare const coalesce: (...args: OperandInput$2[]) => FunctionNode;
+declare const coalesce: <T = any>(...args: OperandInput$2[]) => TypedExpression<T>;
 /**
  * Returns null if the two arguments are equal, otherwise returns the first argument.
+ *
  * @param val1 - The first value.
- * @param val2 - The second value.
- * @returns A FunctionNode representing the NULLIF SQL function.
+ * @param val2 - The second value to compare against.
+ * @returns A `TypedExpression<T>` representing the `NULLIF` SQL function.
  */
-declare const nullif: (val1: OperandInput$2, val2: OperandInput$2) => FunctionNode;
+declare const nullif: <T = any>(val1: OperandInput$2, val2: OperandInput$2) => TypedExpression<T>;
 /**
  * Returns the largest value in a list.
- * @param args - The list of values to compare.
- * @returns A FunctionNode representing the GREATEST SQL function.
+ *
+ * @param args - The list of values or columns to compare.
+ * @returns A `TypedExpression<T>` representing the `GREATEST` SQL function.
  */
-declare const greatest: (...args: OperandInput$2[]) => FunctionNode;
+declare const greatest: <T = any>(...args: OperandInput$2[]) => TypedExpression<T>;
 /**
  * Returns the smallest value in a list.
- * @param args - The list of values to compare.
- * @returns A FunctionNode representing the LEAST SQL function.
+ *
+ * @param args - The list of values or columns to compare.
+ * @returns A `TypedExpression<T>` representing the `LEAST` SQL function.
  */
-declare const least: (...args: OperandInput$2[]) => FunctionNode;
+declare const least: <T = any>(...args: OperandInput$2[]) => TypedExpression<T>;
 /**
  * Returns the first argument if it is not null, otherwise returns the second argument.
+ *
  * @param val - The value to check.
  * @param defaultValue - The default value to return if val is null.
- * @returns A FunctionNode representing the COALESCE SQL function.
+ * @returns A `TypedExpression<T>` representing the `COALESCE` SQL function.
  */
-declare const ifNull: (val: OperandInput$2, defaultValue: OperandInput$2) => FunctionNode;
+declare const ifNull: <T = any>(val: OperandInput$2, defaultValue: OperandInput$2) => TypedExpression<T>;
 
 type OperandInput$1 = OperandNode | ColumnDef | string | number | boolean | null;
-declare const jsonLength: (target: OperandInput$1, path?: OperandInput$1) => FunctionNode;
-declare const jsonSet: (target: OperandInput$1, path: OperandInput$1, value: OperandInput$1) => FunctionNode;
-declare const jsonArrayAgg: (value: OperandInput$1) => FunctionNode;
-declare const jsonContains: (target: OperandInput$1, candidate: OperandInput$1, path?: OperandInput$1) => FunctionNode;
+/**
+ * Returns the number of elements in a JSON array or object.
+ *
+ * @param target - JSON column or value.
+ * @param path - Optional JSON path.
+ * @returns A `TypedExpression<number>` representing the `JSON_LENGTH` SQL function.
+ */
+declare const jsonLength: (target: OperandInput$1, path?: OperandInput$1) => TypedExpression<number>;
+/**
+ * Inserts or updates a value in a JSON document.
+ *
+ * @param target - JSON column or value.
+ * @param path - JSON path to set.
+ * @param value - Value to set.
+ * @returns A `TypedExpression<any>` representing the `JSON_SET` SQL function.
+ */
+declare const jsonSet: (target: OperandInput$1, path: OperandInput$1, value: OperandInput$1) => TypedExpression<any>;
+/**
+ * Aggregates values into a JSON array.
+ *
+ * @param value - Column or expression to aggregate.
+ * @returns A `TypedExpression<any[]>` representing the `JSON_ARRAYAGG` SQL function.
+ */
+declare const jsonArrayAgg: (value: OperandInput$1) => TypedExpression<any[]>;
+/**
+ * Checks if a JSON document contains a specific piece of data.
+ *
+ * @param target - JSON column or value.
+ * @param candidate - Data to look for.
+ * @param path - Optional JSON path to search within.
+ * @returns A `TypedExpression<boolean>` representing the `JSON_CONTAINS` SQL function.
+ */
+declare const jsonContains: (target: OperandInput$1, candidate: OperandInput$1, path?: OperandInput$1) => TypedExpression<boolean>;
 
 type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
-declare const arrayAppend: (array: OperandInput, value: OperandInput) => FunctionNode;
+/**
+ * Appends a value to the end of an array.
+ *
+ * @param array - Array column or value.
+ * @param value - Value to append.
+ * @returns A `TypedExpression<any[]>` representing the `ARRAY_APPEND` SQL function.
+ */
+declare const arrayAppend: (array: OperandInput, value: OperandInput) => TypedExpression<any[]>;
 
 /**
  * Browser-compatible implementation of AsyncLocalStorage.
@@ -6095,6 +6499,14 @@ declare class DefaultManyToManyCollection<TTarget, TPivot extends object | undef
  * @returns Promise resolving to array of entity instances
  */
 declare function executeHydrated<TTable extends TableDef>(session: OrmSession, qb: SelectQueryBuilder<unknown, TTable>): Promise<EntityInstance<TTable>[]>;
+/**
+ * Executes a hydrated query and returns plain row objects (no entity proxies).
+ * @template TTable - The table type
+ * @param session - The ORM session
+ * @param qb - The select query builder
+ * @returns Promise resolving to array of plain row objects
+ */
+declare function executeHydratedPlain<TTable extends TableDef>(session: OrmSession, qb: SelectQueryBuilder<unknown, TTable>): Promise<Record<string, unknown>[]>;
 /**
  * Executes a hydrated query using execution and hydration contexts.
  * @template TTable - The table type
@@ -6104,6 +6516,14 @@ declare function executeHydrated<TTable extends TableDef>(session: OrmSession, q
  * @returns Promise resolving to array of entity instances
  */
 declare function executeHydratedWithContexts<TTable extends TableDef>(execCtx: ExecutionContext, hydCtx: HydrationContext, qb: SelectQueryBuilder<unknown, TTable>): Promise<EntityInstance<TTable>[]>;
+/**
+ * Executes a hydrated query using execution context and returns plain row objects.
+ * @template TTable - The table type
+ * @param execCtx - The execution context
+ * @param qb - The select query builder
+ * @returns Promise resolving to array of plain row objects
+ */
+declare function executeHydratedPlainWithContexts<TTable extends TableDef>(execCtx: ExecutionContext, qb: SelectQueryBuilder<unknown, TTable>): Promise<Record<string, unknown>[]>;
 
 type JsonifyScalar<T> = T extends Date ? string : T;
 /**
@@ -6253,7 +6673,8 @@ type EntityTable<TEntity extends object> = Omit<TableDef<{
         [K in RelationKeys<TEntity>]: NonNullable<TEntity[K]> extends HasManyCollection<infer TChild> ? HasManyRelation<EntityTable<NonNullable<TChild> & object>> : NonNullable<TEntity[K]> extends ManyToManyCollection<infer TTarget, infer TPivot> ? BelongsToManyRelation<EntityTable<NonNullable<TTarget> & object>, TPivot extends object ? EntityTable<NonNullable<TPivot> & object> : TableDef> : NonNullable<TEntity[K]> extends HasOneReference<infer TChild> ? HasOneRelation<EntityTable<NonNullable<TChild> & object>> : NonNullable<TEntity[K]> extends BelongsToReference<infer TParent> ? BelongsToRelation<EntityTable<NonNullable<TParent> & object>> : NonNullable<TEntity[K]> extends object ? BelongsToRelation<EntityTable<NonNullable<TEntity[K]> & object>> : never;
     };
 };
-declare const selectFromEntity: <TEntity extends object>(ctor: EntityConstructor<TEntity>) => SelectQueryBuilder<TEntity, EntityTable<TEntity>>;
+type DecoratedEntityInstance<TEntity extends object> = TEntity & EntityInstance<EntityTable<TEntity>>;
+declare const selectFromEntity: <TEntity extends object>(ctor: EntityConstructor<TEntity>) => SelectQueryBuilder<DecoratedEntityInstance<TEntity>, EntityTable<TEntity>>;
 /**
  * Public API: opt-in ergonomic entity reference (decorator-level).
  *
@@ -6350,6 +6771,7 @@ declare class DefaultEntityMaterializer implements EntityMaterializer {
      * Simple heuristic to check if an object looks like an entity.
      */
     private isEntityLike;
+    private materializeEntityProxy;
 }
 /**
  * Convenience function to materialize query results as real class instances.
@@ -6524,4 +6946,4 @@ type PooledExecutorFactoryOptions<TConn> = {
  */
 declare function createPooledExecutorFactory<TConn>(opts: PooledExecutorFactoryOptions<TConn>): DbExecutorFactory;
 
-export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneReferenceApi, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type Primitive, PrototypeMaterializationStrategy, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SelectableKeys, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, materializeAs, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };
+export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, type DecoratedEntityInstance, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneReferenceApi, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type Primitive, PrototypeMaterializationStrategy, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SelectableKeys, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, type TypedExpression, type TypedLike, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, asType, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedPlain, executeHydratedPlainWithContexts, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, materializeAs, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };