metal-orm 1.0.39 → 1.0.40

package/dist/index.d.cts

@@ -543,6 +543,14 @@ interface LiteralNode {
     /** The literal value (string, number, boolean, or null) */
     value: string | number | boolean | null;
 }
+/**
+ * AST node representing a reference to a SELECT alias (for ORDER BY / GROUP BY).
+ */
+interface AliasRefNode {
+    type: 'AliasRef';
+    /** Alias name to reference */
+    name: string;
+}
 /**
  * AST node representing a column reference
  */
@@ -630,10 +638,19 @@ interface WindowFunctionNode {
     /** Optional alias for the result */
     alias?: string;
 }
+/**
+ * AST node representing an arithmetic expression (e.g., a + b)
+ */
+interface ArithmeticExpressionNode {
+    type: 'ArithmeticExpression';
+    left: OperandNode;
+    operator: '+' | '-' | '*' | '/';
+    right: OperandNode;
+}
 /**
  * Union type representing any operand that can be used in expressions
  */
-type OperandNode = ColumnNode | LiteralNode | FunctionNode | JsonPathNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode;
+type OperandNode = AliasRefNode | ColumnNode | LiteralNode | FunctionNode | JsonPathNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode;
 declare const isOperandNode: (node: any) => node is OperandNode;
 declare const isFunctionNode: (node: any) => node is FunctionNode;
 declare const isCaseExpressionNode: (node: any) => node is CaseExpressionNode;
@@ -712,7 +729,7 @@ interface BetweenExpressionNode {
 /**
  * Union type representing any supported expression node
  */
-type ExpressionNode = BinaryExpressionNode | LogicalExpressionNode | NullExpressionNode | InExpressionNode | ExistsExpressionNode | BetweenExpressionNode;
+type ExpressionNode = BinaryExpressionNode | LogicalExpressionNode | NullExpressionNode | InExpressionNode | ExistsExpressionNode | BetweenExpressionNode | ArithmeticExpressionNode;
 
 type LiteralValue = LiteralNode['value'];
 type ValueOperandInput = OperandNode | LiteralValue;
@@ -729,6 +746,10 @@ declare const columnOperand: (col: ColumnRef | ColumnNode) => ColumnNode;
  * Primarily semantic; SQL rendering still uses the provided table/alias name.
  */
 declare const outerRef: (col: ColumnRef | ColumnNode) => ColumnNode;
+/**
+ * References a SELECT alias (useful for ORDER BY / GROUP BY).
+ */
+declare const aliasRef: (name: string) => AliasRefNode;
 /**
  * Creates an outer-scoped column reference using a specific table or alias name.
  */
@@ -836,6 +857,10 @@ declare const between: (left: OperandNode | ColumnRef, lower: OperandNode | Colu
  * @returns NOT BETWEEN expression node
  */
 declare const notBetween: (left: OperandNode | ColumnRef, lower: OperandNode | ColumnRef | string | number, upper: OperandNode | ColumnRef | string | number) => BetweenExpressionNode;
+declare const add: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
+declare const sub: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
+declare const mul: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
+declare const div: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
 /**
  * Creates a JSON path expression
  * @param col - Source column
@@ -981,6 +1006,7 @@ interface ExpressionVisitor<R> {
     visitInExpression?(node: InExpressionNode): R;
     visitExistsExpression?(node: ExistsExpressionNode): R;
     visitBetweenExpression?(node: BetweenExpressionNode): R;
+    visitArithmeticExpression?(node: ArithmeticExpressionNode): R;
     otherwise?(node: ExpressionNode): R;
 }
 /**
@@ -994,6 +1020,7 @@ interface OperandVisitor<R> {
     visitScalarSubquery?(node: ScalarSubqueryNode): R;
     visitCaseExpression?(node: CaseExpressionNode): R;
     visitWindowFunction?(node: WindowFunctionNode): R;
+    visitAliasRef?(node: AliasRefNode): R;
     otherwise?(node: OperandNode): R;
 }
 type ExpressionDispatch = <R>(node: any, visitor: ExpressionVisitor<R>) => R;
@@ -1095,15 +1122,23 @@ interface DerivedTableNode {
     columnAliases?: string[];
 }
 type TableSourceNode = TableNode | FunctionTableNode | DerivedTableNode;
+/**
+ * Any expression that can appear in ORDER BY / GROUP BY terms.
+ */
+type OrderingTerm = OperandNode | ExpressionNode | AliasRefNode;
 /**
  * AST node representing an ORDER BY clause
  */
 interface OrderByNode {
     type: 'OrderBy';
-    /** Column to order by */
-    column: ColumnNode;
+    /** Expression/operand/alias to order by */
+    term: OrderingTerm;
     /** Order direction (ASC or DESC) */
     direction: OrderDirection;
+    /** Optional nulls ordering (NULLS FIRST/LAST) */
+    nulls?: 'FIRST' | 'LAST';
+    /** Optional collation */
+    collation?: string;
 }
 /**
  * AST node representing a Common Table Expression (CTE)
@@ -1149,7 +1184,7 @@ interface SelectQueryNode {
     /** Optional WHERE clause */
     where?: ExpressionNode;
     /** Optional GROUP BY clause */
-    groupBy?: ColumnNode[];
+    groupBy?: OrderingTerm[];
     /** Optional HAVING clause */
     having?: ExpressionNode;
     /** Optional ORDER BY clause */
@@ -1423,6 +1458,10 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
      * @returns Compiled SQL operand
      */
     protected compileOperand(node: OperandNode, ctx: CompilerContext): string;
+    /**
+     * Compiles an ordering term (operand, expression, or alias reference).
+     */
+    protected compileOrderingTerm(term: OrderingTerm, ctx: CompilerContext): string;
     private registerDefaultExpressionCompilers;
     private registerDefaultOperandCompilers;
     protected compileJsonPath(node: JsonPathNode): string;
@@ -1494,10 +1533,10 @@ declare class SelectQueryState {
     withHaving(predicate: ExpressionNode): SelectQueryState;
     /**
      * Adds GROUP BY columns to the query
-     * @param columns - Columns to group by
+     * @param columns - Terms to group by
      * @returns New SelectQueryState with GROUP BY clause
      */
-    withGroupBy(columns: ColumnNode[]): SelectQueryState;
+    withGroupBy(columns: OrderingTerm[]): SelectQueryState;
     /**
      * Adds ORDER BY clauses to the query
      * @param orderBy - ORDER BY nodes
@@ -1660,6 +1699,7 @@ declare class HydrationManager {
     private getProjectionNames;
     private buildProjectionAliasMap;
     private mapOrderBy;
+    private mapOrderingTerm;
     private buildPagingColumns;
 }
 
@@ -1746,7 +1786,7 @@ declare class QueryAstService {
      * @param col - Column to group by
      * @returns Updated query state with GROUP BY clause
      */
-    withGroupBy(col: ColumnDef | ColumnNode): SelectQueryState;
+    withGroupBy(col: ColumnDef | OrderingTerm): SelectQueryState;
     /**
      * Adds a HAVING clause to the query
      * @param expr - Expression for the HAVING clause
@@ -1759,7 +1799,7 @@ declare class QueryAstService {
      * @param direction - Order direction (ASC/DESC)
      * @returns Updated query state with ORDER BY clause
      */
-    withOrderBy(col: ColumnDef | ColumnNode, direction: OrderDirection): SelectQueryState;
+    withOrderBy(term: ColumnDef | OrderingTerm, direction: OrderDirection, nulls?: 'FIRST' | 'LAST', collation?: string): SelectQueryState;
     /**
      * Adds a DISTINCT clause to the query
      * @param cols - Columns to make distinct
@@ -1785,6 +1825,7 @@ declare class QueryAstService {
      * @returns Combined expression
      */
     private combineExpressions;
+    private normalizeOrderingTerm;
 }
 
 /**
@@ -2543,15 +2584,11 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      */
     where(expr: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
-  
      * Adds a GROUP BY clause to the query
-  
-     * @param col - Column definition or column node to group by
-  
+     * @param term - Column definition or ordering term to group by
      * @returns New query builder instance with the GROUP BY clause
-  
      */
-    groupBy(col: ColumnDef | ColumnNode): SelectQueryBuilder<T, TTable>;
+    groupBy(term: ColumnDef | OrderingTerm): SelectQueryBuilder<T, TTable>;
     /**
   
      * Adds a HAVING condition to the query
@@ -2563,17 +2600,16 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      */
     having(expr: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
-  
      * Adds an ORDER BY clause to the query
-  
-     * @param col - Column definition or column node to order by
-  
-     * @param direction - Order direction (defaults to ASC)
-  
+     * @param term - Column definition or ordering term to order by
+     * @param directionOrOptions - Order direction or options (defaults to ASC)
      * @returns New query builder instance with the ORDER BY clause
-  
      */
-    orderBy(col: ColumnDef | ColumnNode, direction?: OrderDirection): SelectQueryBuilder<T, TTable>;
+    orderBy(term: ColumnDef | OrderingTerm, directionOrOptions?: OrderDirection | {
+        direction?: OrderDirection;
+        nulls?: 'FIRST' | 'LAST';
+        collation?: string;
+    }): SelectQueryBuilder<T, TTable>;
     /**
   
      * Adds a DISTINCT clause to the query
@@ -2913,6 +2949,8 @@ declare abstract class SqlDialectBase extends Dialect {
     protected compileHaving(ast: SelectQueryNode, ctx: CompilerContext): string;
     protected stripTrailingSemicolon(sql: string): string;
     protected wrapSetOperand(sql: string): string;
+    protected renderOrderByNulls(order: OrderByNode): string | undefined;
+    protected renderOrderByCollation(order: OrderByNode): string | undefined;
 }
 
 /**
@@ -2978,6 +3016,8 @@ declare class SqlServerDialect extends Dialect {
     private compileSelectCore;
     private compileOrderBy;
     private compilePagination;
+    private renderOrderByNulls;
+    private renderOrderByCollation;
     private compileTableSource;
     private compileDerivedTable;
     private compileCtes;
@@ -3519,12 +3559,17 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
      * @returns TypeScript code representation
      */
     private printOperand;
+    /**
+     * Prints an ordering term (operand/expression/alias) to TypeScript code.
+     */
+    private printOrderingTerm;
     visitBinaryExpression(binary: BinaryExpressionNode): string;
     visitLogicalExpression(logical: LogicalExpressionNode): string;
     visitNullExpression(nullExpr: NullExpressionNode): string;
     visitInExpression(inExpr: InExpressionNode): string;
     visitExistsExpression(existsExpr: ExistsExpressionNode): string;
     visitBetweenExpression(betweenExpr: BetweenExpressionNode): string;
+    visitArithmeticExpression(arithExpr: ArithmeticExpressionNode): string;
     visitColumn(node: ColumnNode): string;
     visitLiteral(node: LiteralNode): string;
     visitFunction(node: FunctionNode): string;
@@ -3532,6 +3577,7 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
     visitScalarSubquery(node: ScalarSubqueryNode): string;
     visitCaseExpression(node: CaseExpressionNode): string;
     visitWindowFunction(node: WindowFunctionNode): string;
+    visitAliasRef(node: AliasRefNode): string;
     /**
      * Prints a binary expression to TypeScript code
      * @param binary - Binary expression node
@@ -3544,6 +3590,7 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
      * @returns TypeScript code representation
      */
     private printLogicalExpression;
+    private printArithmeticExpression;
     /**
      * Prints an IN expression to TypeScript code
      * @param inExpr - IN expression node
@@ -3870,4 +3917,4 @@ interface CreateTediousClientOptions {
 declare function createTediousMssqlClient(connection: TediousConnectionLike, { Request, TYPES }: TediousModule, options?: CreateTediousClientOptions): MssqlClientLike;
 declare function createTediousExecutor(connection: TediousConnectionLike, module: TediousModule, options?: CreateTediousClientOptions): DbExecutor;
 
-export { type AnyDomainEvent, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type CascadeMode, type CaseExpressionNode, type CheckConstraint, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ExternalTransaction, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, 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, type PostgresClientLike, PostgresDialect, PrimaryKey, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, addDomainEvent, and, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bootstrapEntities, caseWhen, ceil, ceiling, char, charLength, clearExpressionDispatchers, clearOperandDispatchers, col, columnOperand, concat, concatWs, correlateBy, cos, cot, count, createColumn, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createLiteral, createMssqlExecutor, createMysqlExecutor, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, endOfMonth, eq, esel, executeHydrated, executeHydratedWithContexts, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, getSchemaIntrospector, getTableDefFromEntity, groupConcat, gt, gte, hasMany, hasOne, hydrateRows, inList, instr, introspectSchema, isCaseExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonPath, lag, lastValue, lead, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, locate, log, log10, logBase, lower, lpad, lt, lte, ltrim, max, min, mod, month, neq, notBetween, notExists, notInList, notLike, now, ntile, or, outerRef, pi, position, pow, power, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, renderColumnDefinition, repeat, replace, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, sel, selectFromEntity, sign, sin, space, sqrt, substr, sum, synchronizeSchema, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };
+export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type CascadeMode, type CaseExpressionNode, type CheckConstraint, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ExternalTransaction, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, 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, type PostgresClientLike, PostgresDialect, PrimaryKey, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type 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, aliasRef, and, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bootstrapEntities, caseWhen, ceil, ceiling, char, charLength, clearExpressionDispatchers, clearOperandDispatchers, col, columnOperand, concat, concatWs, correlateBy, cos, cot, count, createColumn, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createLiteral, createMssqlExecutor, createMysqlExecutor, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, div, endOfMonth, eq, esel, executeHydrated, executeHydratedWithContexts, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, getSchemaIntrospector, getTableDefFromEntity, groupConcat, gt, gte, hasMany, hasOne, hydrateRows, inList, instr, introspectSchema, isCaseExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonPath, lag, lastValue, lead, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, locate, log, log10, logBase, lower, lpad, lt, lte, ltrim, max, min, mod, month, mul, neq, notBetween, notExists, notInList, notLike, now, ntile, or, outerRef, pi, position, pow, power, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, renderColumnDefinition, repeat, replace, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, sel, selectFromEntity, sign, sin, space, sqrt, sub, substr, sum, synchronizeSchema, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };

package/dist/index.d.ts

@@ -543,6 +543,14 @@ interface LiteralNode {
     /** The literal value (string, number, boolean, or null) */
     value: string | number | boolean | null;
 }
+/**
+ * AST node representing a reference to a SELECT alias (for ORDER BY / GROUP BY).
+ */
+interface AliasRefNode {
+    type: 'AliasRef';
+    /** Alias name to reference */
+    name: string;
+}
 /**
  * AST node representing a column reference
  */
@@ -630,10 +638,19 @@ interface WindowFunctionNode {
     /** Optional alias for the result */
     alias?: string;
 }
+/**
+ * AST node representing an arithmetic expression (e.g., a + b)
+ */
+interface ArithmeticExpressionNode {
+    type: 'ArithmeticExpression';
+    left: OperandNode;
+    operator: '+' | '-' | '*' | '/';
+    right: OperandNode;
+}
 /**
  * Union type representing any operand that can be used in expressions
  */
-type OperandNode = ColumnNode | LiteralNode | FunctionNode | JsonPathNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode;
+type OperandNode = AliasRefNode | ColumnNode | LiteralNode | FunctionNode | JsonPathNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode;
 declare const isOperandNode: (node: any) => node is OperandNode;
 declare const isFunctionNode: (node: any) => node is FunctionNode;
 declare const isCaseExpressionNode: (node: any) => node is CaseExpressionNode;
@@ -712,7 +729,7 @@ interface BetweenExpressionNode {
 /**
  * Union type representing any supported expression node
  */
-type ExpressionNode = BinaryExpressionNode | LogicalExpressionNode | NullExpressionNode | InExpressionNode | ExistsExpressionNode | BetweenExpressionNode;
+type ExpressionNode = BinaryExpressionNode | LogicalExpressionNode | NullExpressionNode | InExpressionNode | ExistsExpressionNode | BetweenExpressionNode | ArithmeticExpressionNode;
 
 type LiteralValue = LiteralNode['value'];
 type ValueOperandInput = OperandNode | LiteralValue;
@@ -729,6 +746,10 @@ declare const columnOperand: (col: ColumnRef | ColumnNode) => ColumnNode;
  * Primarily semantic; SQL rendering still uses the provided table/alias name.
  */
 declare const outerRef: (col: ColumnRef | ColumnNode) => ColumnNode;
+/**
+ * References a SELECT alias (useful for ORDER BY / GROUP BY).
+ */
+declare const aliasRef: (name: string) => AliasRefNode;
 /**
  * Creates an outer-scoped column reference using a specific table or alias name.
  */
@@ -836,6 +857,10 @@ declare const between: (left: OperandNode | ColumnRef, lower: OperandNode | Colu
  * @returns NOT BETWEEN expression node
  */
 declare const notBetween: (left: OperandNode | ColumnRef, lower: OperandNode | ColumnRef | string | number, upper: OperandNode | ColumnRef | string | number) => BetweenExpressionNode;
+declare const add: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
+declare const sub: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
+declare const mul: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
+declare const div: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => ArithmeticExpressionNode;
 /**
  * Creates a JSON path expression
  * @param col - Source column
@@ -981,6 +1006,7 @@ interface ExpressionVisitor<R> {
     visitInExpression?(node: InExpressionNode): R;
     visitExistsExpression?(node: ExistsExpressionNode): R;
     visitBetweenExpression?(node: BetweenExpressionNode): R;
+    visitArithmeticExpression?(node: ArithmeticExpressionNode): R;
     otherwise?(node: ExpressionNode): R;
 }
 /**
@@ -994,6 +1020,7 @@ interface OperandVisitor<R> {
     visitScalarSubquery?(node: ScalarSubqueryNode): R;
     visitCaseExpression?(node: CaseExpressionNode): R;
     visitWindowFunction?(node: WindowFunctionNode): R;
+    visitAliasRef?(node: AliasRefNode): R;
     otherwise?(node: OperandNode): R;
 }
 type ExpressionDispatch = <R>(node: any, visitor: ExpressionVisitor<R>) => R;
@@ -1095,15 +1122,23 @@ interface DerivedTableNode {
     columnAliases?: string[];
 }
 type TableSourceNode = TableNode | FunctionTableNode | DerivedTableNode;
+/**
+ * Any expression that can appear in ORDER BY / GROUP BY terms.
+ */
+type OrderingTerm = OperandNode | ExpressionNode | AliasRefNode;
 /**
  * AST node representing an ORDER BY clause
  */
 interface OrderByNode {
     type: 'OrderBy';
-    /** Column to order by */
-    column: ColumnNode;
+    /** Expression/operand/alias to order by */
+    term: OrderingTerm;
     /** Order direction (ASC or DESC) */
     direction: OrderDirection;
+    /** Optional nulls ordering (NULLS FIRST/LAST) */
+    nulls?: 'FIRST' | 'LAST';
+    /** Optional collation */
+    collation?: string;
 }
 /**
  * AST node representing a Common Table Expression (CTE)
@@ -1149,7 +1184,7 @@ interface SelectQueryNode {
     /** Optional WHERE clause */
     where?: ExpressionNode;
     /** Optional GROUP BY clause */
-    groupBy?: ColumnNode[];
+    groupBy?: OrderingTerm[];
     /** Optional HAVING clause */
     having?: ExpressionNode;
     /** Optional ORDER BY clause */
@@ -1423,6 +1458,10 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
      * @returns Compiled SQL operand
      */
     protected compileOperand(node: OperandNode, ctx: CompilerContext): string;
+    /**
+     * Compiles an ordering term (operand, expression, or alias reference).
+     */
+    protected compileOrderingTerm(term: OrderingTerm, ctx: CompilerContext): string;
     private registerDefaultExpressionCompilers;
     private registerDefaultOperandCompilers;
     protected compileJsonPath(node: JsonPathNode): string;
@@ -1494,10 +1533,10 @@ declare class SelectQueryState {
     withHaving(predicate: ExpressionNode): SelectQueryState;
     /**
      * Adds GROUP BY columns to the query
-     * @param columns - Columns to group by
+     * @param columns - Terms to group by
      * @returns New SelectQueryState with GROUP BY clause
      */
-    withGroupBy(columns: ColumnNode[]): SelectQueryState;
+    withGroupBy(columns: OrderingTerm[]): SelectQueryState;
     /**
      * Adds ORDER BY clauses to the query
      * @param orderBy - ORDER BY nodes
@@ -1660,6 +1699,7 @@ declare class HydrationManager {
     private getProjectionNames;
     private buildProjectionAliasMap;
     private mapOrderBy;
+    private mapOrderingTerm;
     private buildPagingColumns;
 }
 
@@ -1746,7 +1786,7 @@ declare class QueryAstService {
      * @param col - Column to group by
      * @returns Updated query state with GROUP BY clause
      */
-    withGroupBy(col: ColumnDef | ColumnNode): SelectQueryState;
+    withGroupBy(col: ColumnDef | OrderingTerm): SelectQueryState;
     /**
      * Adds a HAVING clause to the query
      * @param expr - Expression for the HAVING clause
@@ -1759,7 +1799,7 @@ declare class QueryAstService {
      * @param direction - Order direction (ASC/DESC)
      * @returns Updated query state with ORDER BY clause
      */
-    withOrderBy(col: ColumnDef | ColumnNode, direction: OrderDirection): SelectQueryState;
+    withOrderBy(term: ColumnDef | OrderingTerm, direction: OrderDirection, nulls?: 'FIRST' | 'LAST', collation?: string): SelectQueryState;
     /**
      * Adds a DISTINCT clause to the query
      * @param cols - Columns to make distinct
@@ -1785,6 +1825,7 @@ declare class QueryAstService {
      * @returns Combined expression
      */
     private combineExpressions;
+    private normalizeOrderingTerm;
 }
 
 /**
@@ -2543,15 +2584,11 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      */
     where(expr: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
-  
      * Adds a GROUP BY clause to the query
-  
-     * @param col - Column definition or column node to group by
-  
+     * @param term - Column definition or ordering term to group by
      * @returns New query builder instance with the GROUP BY clause
-  
      */
-    groupBy(col: ColumnDef | ColumnNode): SelectQueryBuilder<T, TTable>;
+    groupBy(term: ColumnDef | OrderingTerm): SelectQueryBuilder<T, TTable>;
     /**
   
      * Adds a HAVING condition to the query
@@ -2563,17 +2600,16 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      */
     having(expr: ExpressionNode): SelectQueryBuilder<T, TTable>;
     /**
-  
      * Adds an ORDER BY clause to the query
-  
-     * @param col - Column definition or column node to order by
-  
-     * @param direction - Order direction (defaults to ASC)
-  
+     * @param term - Column definition or ordering term to order by
+     * @param directionOrOptions - Order direction or options (defaults to ASC)
      * @returns New query builder instance with the ORDER BY clause
-  
      */
-    orderBy(col: ColumnDef | ColumnNode, direction?: OrderDirection): SelectQueryBuilder<T, TTable>;
+    orderBy(term: ColumnDef | OrderingTerm, directionOrOptions?: OrderDirection | {
+        direction?: OrderDirection;
+        nulls?: 'FIRST' | 'LAST';
+        collation?: string;
+    }): SelectQueryBuilder<T, TTable>;
     /**
   
      * Adds a DISTINCT clause to the query
@@ -2913,6 +2949,8 @@ declare abstract class SqlDialectBase extends Dialect {
     protected compileHaving(ast: SelectQueryNode, ctx: CompilerContext): string;
     protected stripTrailingSemicolon(sql: string): string;
     protected wrapSetOperand(sql: string): string;
+    protected renderOrderByNulls(order: OrderByNode): string | undefined;
+    protected renderOrderByCollation(order: OrderByNode): string | undefined;
 }
 
 /**
@@ -2978,6 +3016,8 @@ declare class SqlServerDialect extends Dialect {
     private compileSelectCore;
     private compileOrderBy;
     private compilePagination;
+    private renderOrderByNulls;
+    private renderOrderByCollation;
     private compileTableSource;
     private compileDerivedTable;
     private compileCtes;
@@ -3519,12 +3559,17 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
      * @returns TypeScript code representation
      */
     private printOperand;
+    /**
+     * Prints an ordering term (operand/expression/alias) to TypeScript code.
+     */
+    private printOrderingTerm;
     visitBinaryExpression(binary: BinaryExpressionNode): string;
     visitLogicalExpression(logical: LogicalExpressionNode): string;
     visitNullExpression(nullExpr: NullExpressionNode): string;
     visitInExpression(inExpr: InExpressionNode): string;
     visitExistsExpression(existsExpr: ExistsExpressionNode): string;
     visitBetweenExpression(betweenExpr: BetweenExpressionNode): string;
+    visitArithmeticExpression(arithExpr: ArithmeticExpressionNode): string;
     visitColumn(node: ColumnNode): string;
     visitLiteral(node: LiteralNode): string;
     visitFunction(node: FunctionNode): string;
@@ -3532,6 +3577,7 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
     visitScalarSubquery(node: ScalarSubqueryNode): string;
     visitCaseExpression(node: CaseExpressionNode): string;
     visitWindowFunction(node: WindowFunctionNode): string;
+    visitAliasRef(node: AliasRefNode): string;
     /**
      * Prints a binary expression to TypeScript code
      * @param binary - Binary expression node
@@ -3544,6 +3590,7 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
      * @returns TypeScript code representation
      */
     private printLogicalExpression;
+    private printArithmeticExpression;
     /**
      * Prints an IN expression to TypeScript code
      * @param inExpr - IN expression node
@@ -3870,4 +3917,4 @@ interface CreateTediousClientOptions {
 declare function createTediousMssqlClient(connection: TediousConnectionLike, { Request, TYPES }: TediousModule, options?: CreateTediousClientOptions): MssqlClientLike;
 declare function createTediousExecutor(connection: TediousConnectionLike, module: TediousModule, options?: CreateTediousClientOptions): DbExecutor;
 
-export { type AnyDomainEvent, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type CascadeMode, type CaseExpressionNode, type CheckConstraint, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ExternalTransaction, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, 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, type PostgresClientLike, PostgresDialect, PrimaryKey, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, addDomainEvent, and, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bootstrapEntities, caseWhen, ceil, ceiling, char, charLength, clearExpressionDispatchers, clearOperandDispatchers, col, columnOperand, concat, concatWs, correlateBy, cos, cot, count, createColumn, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createLiteral, createMssqlExecutor, createMysqlExecutor, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, endOfMonth, eq, esel, executeHydrated, executeHydratedWithContexts, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, getSchemaIntrospector, getTableDefFromEntity, groupConcat, gt, gte, hasMany, hasOne, hydrateRows, inList, instr, introspectSchema, isCaseExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonPath, lag, lastValue, lead, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, locate, log, log10, logBase, lower, lpad, lt, lte, ltrim, max, min, mod, month, neq, notBetween, notExists, notInList, notLike, now, ntile, or, outerRef, pi, position, pow, power, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, renderColumnDefinition, repeat, replace, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, sel, selectFromEntity, sign, sin, space, sqrt, substr, sum, synchronizeSchema, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };
+export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type CascadeMode, type CaseExpressionNode, type CheckConstraint, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ExternalTransaction, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, 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, type PostgresClientLike, PostgresDialect, PrimaryKey, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type 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, aliasRef, and, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bootstrapEntities, caseWhen, ceil, ceiling, char, charLength, clearExpressionDispatchers, clearOperandDispatchers, col, columnOperand, concat, concatWs, correlateBy, cos, cot, count, createColumn, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createLiteral, createMssqlExecutor, createMysqlExecutor, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, div, endOfMonth, eq, esel, executeHydrated, executeHydratedWithContexts, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, getSchemaIntrospector, getTableDefFromEntity, groupConcat, gt, gte, hasMany, hasOne, hydrateRows, inList, instr, introspectSchema, isCaseExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonPath, lag, lastValue, lead, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, locate, log, log10, logBase, lower, lpad, lt, lte, ltrim, max, min, mod, month, mul, neq, notBetween, notExists, notInList, notLike, now, ntile, or, outerRef, pi, position, pow, power, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, renderColumnDefinition, repeat, replace, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, sel, selectFromEntity, sign, sin, space, sqrt, sub, substr, sum, synchronizeSchema, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };