metal-orm 1.0.16 → 1.0.17

package/dist/{select-BKZrMRCQ.d.ts → select-BPCn6MOH.d.ts}

@@ -348,6 +348,10 @@ interface TableDef<T extends Record<string, ColumnDef> = Record<string, ColumnDe
  */
 declare const defineTable: <T extends Record<string, ColumnDef>>(name: string, columns: T, relations?: Record<string, RelationDef>, hooks?: TableHooks, options?: TableOptions) => TableDef<T>;
 
+/**
+ * Resolves a relation definition to its target table type.
+ */
+type RelationTargetTable<TRel extends RelationDef> = TRel extends HasManyRelation<infer TTarget> ? TTarget : TRel extends HasOneRelation<infer TTarget> ? TTarget : TRel extends BelongsToRelation<infer TTarget> ? TTarget : TRel extends BelongsToManyRelation<infer TTarget> ? TTarget : never;
 /**
  * Maps a ColumnDef to its TypeScript type representation
  */
@@ -544,6 +548,12 @@ interface FunctionNode {
     args: OperandNode[];
     /** Optional alias for the function result */
     alias?: string;
+    /** Optional ORDER BY clause used by aggregations like GROUP_CONCAT */
+    orderBy?: OrderByNode[];
+    /** Optional separator argument used by GROUP_CONCAT-like functions */
+    separator?: OperandNode;
+    /** Optional DISTINCT modifier */
+    distinct?: boolean;
 }
 /**
  * AST node representing a JSON path expression
@@ -893,6 +903,8 @@ interface HydrationMetadata {
 interface FunctionRenderContext {
     node: FunctionNode;
     compiledArgs: string[];
+    /** Helper to compile additional operands (e.g., separators or ORDER BY columns) */
+    compileOperand: (operand: OperandNode) => string;
 }
 type FunctionRenderer = (ctx: FunctionRenderContext) => string;
 interface FunctionStrategy {
@@ -1587,6 +1599,101 @@ type EntityConstructor = new (...args: any[]) => any;
 type EntityOrTableTarget = EntityConstructor | TableDef;
 type EntityOrTableTargetResolver = EntityOrTableTarget | (() => EntityOrTableTarget);
 
+/**
+ * Entity status enum representing the lifecycle state of an entity
+ */
+declare enum EntityStatus {
+    /** Entity is newly created and not yet persisted */
+    New = "new",
+    /** Entity is managed by the ORM and synchronized with the database */
+    Managed = "managed",
+    /** Entity has been modified but not yet persisted */
+    Dirty = "dirty",
+    /** Entity has been marked for removal */
+    Removed = "removed",
+    /** Entity is detached from the ORM context */
+    Detached = "detached"
+}
+/**
+ * Represents an entity being tracked by the ORM
+ */
+interface TrackedEntity {
+    /** The table definition this entity belongs to */
+    table: TableDef;
+    /** The actual entity instance */
+    entity: any;
+    /** Primary key value of the entity */
+    pk: string | number | null;
+    /** Current status of the entity */
+    status: EntityStatus;
+    /** Original values of the entity when it was loaded */
+    original: Record<string, any> | null;
+}
+/**
+ * Type representing a key for relation navigation
+ */
+type RelationKey = string;
+/**
+ * Represents a change operation on a relation
+ * @typeParam T - Type of the related entity
+ */
+type RelationChange<T> = {
+    kind: 'add';
+    entity: T;
+} | {
+    kind: 'attach';
+    entity: T;
+} | {
+    kind: 'remove';
+    entity: T;
+} | {
+    kind: 'detach';
+    entity: T;
+};
+/**
+ * Represents a relation change entry in the unit of work
+ */
+interface RelationChangeEntry {
+    /** Root entity that owns the relation */
+    root: any;
+    /** Key of the relation being changed */
+    relationKey: RelationKey;
+    /** Table definition of the root entity */
+    rootTable: TableDef;
+    /** Name of the relation */
+    relationName: string;
+    /** Relation definition */
+    relation: RelationDef;
+    /** The change being applied */
+    change: RelationChange<any>;
+}
+/**
+ * Represents a domain event that can be emitted by entities
+ * @typeParam TType - Type of the event (string literal)
+ */
+interface DomainEvent<TType extends string = string> {
+    /** Type identifier for the event */
+    readonly type: TType;
+    /** Timestamp when the event occurred */
+    readonly occurredAt?: Date;
+}
+/**
+ * Type representing any domain event
+ */
+type AnyDomainEvent = DomainEvent<string>;
+/**
+ * Type representing ORM-specific domain events
+ */
+type OrmDomainEvent = AnyDomainEvent;
+/**
+ * Interface for entities that can emit domain events
+ * @typeParam E - Type of domain events this entity can emit
+ */
+interface HasDomainEvents<E extends DomainEvent = AnyDomainEvent> {
+    /** Array of domain events emitted by this entity */
+    domainEvents?: E[];
+}
+
 /**
  * Strategy interface for converting database names to TypeScript identifiers
  */
@@ -1616,7 +1723,7 @@ declare class InterceptorPipeline {
     run(ctx: QueryContext, executor: DbExecutor): Promise<QueryResult[]>;
 }
 
-interface OrmOptions {
+interface OrmOptions<E extends DomainEvent = OrmDomainEvent> {
     dialect: Dialect;
     executorFactory: DbExecutorFactory;
     interceptors?: InterceptorPipeline;
@@ -1630,56 +1737,16 @@ interface DbExecutorFactory {
 }
 interface ExternalTransaction {
 }
-declare class Orm {
+declare class Orm<E extends DomainEvent = OrmDomainEvent> {
     readonly dialect: Dialect;
     readonly interceptors: InterceptorPipeline;
     readonly namingStrategy: NamingStrategy;
     private readonly executorFactory;
-    constructor(opts: OrmOptions);
+    constructor(opts: OrmOptions<E>);
     createSession(options?: {
         tx?: ExternalTransaction;
-    }): OrmSession;
-    transaction<T>(fn: (session: OrmSession) => Promise<T>): Promise<T>;
-}
-
-declare enum EntityStatus {
-    New = "new",
-    Managed = "managed",
-    Dirty = "dirty",
-    Removed = "removed",
-    Detached = "detached"
-}
-interface TrackedEntity {
-    table: TableDef;
-    entity: any;
-    pk: string | number | null;
-    status: EntityStatus;
-    original: Record<string, any> | null;
-}
-type RelationKey = string;
-type RelationChange<T> = {
-    kind: 'add';
-    entity: T;
-} | {
-    kind: 'attach';
-    entity: T;
-} | {
-    kind: 'remove';
-    entity: T;
-} | {
-    kind: 'detach';
-    entity: T;
-};
-interface RelationChangeEntry {
-    root: any;
-    relationKey: RelationKey;
-    rootTable: TableDef;
-    relationName: string;
-    relation: RelationDef;
-    change: RelationChange<any>;
-}
-interface HasDomainEvents {
-    domainEvents?: any[];
+    }): OrmSession<E>;
+    transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T>;
 }
 
 declare class IdentityMap {
@@ -1727,15 +1794,21 @@ declare class UnitOfWork {
     private getPrimaryKeyValue;
 }
 
-type DomainEventHandler<Context> = (event: any, ctx: Context) => Promise<void> | void;
-declare class DomainEventBus<Context> {
+type EventOfType<E extends DomainEvent, TType extends E['type']> = Extract<E, {
+    type: TType;
+}>;
+type DomainEventHandler<E extends DomainEvent, Context> = (event: E, ctx: Context) => Promise<void> | void;
+type InitialHandlers<E extends DomainEvent, Context> = {
+    [K in E['type']]?: DomainEventHandler<EventOfType<E, K>, Context>[];
+};
+declare class DomainEventBus<E extends DomainEvent, Context> {
     private readonly handlers;
-    constructor(initialHandlers?: Record<string, DomainEventHandler<Context>[]>);
-    register(name: string, handler: DomainEventHandler<Context>): void;
+    constructor(initialHandlers?: InitialHandlers<E, Context>);
+    on<TType extends E['type']>(type: TType, handler: DomainEventHandler<EventOfType<E, TType>, Context>): void;
+    register<TType extends E['type']>(type: TType, handler: DomainEventHandler<EventOfType<E, TType>, Context>): void;
     dispatch(trackedEntities: Iterable<TrackedEntity>, ctx: Context): Promise<void>;
-    private getEventName;
 }
-declare const addDomainEvent: (entity: HasDomainEvents, event: any) => void;
+declare const addDomainEvent: <E extends DomainEvent>(entity: HasDomainEvents<E>, event: E) => void;
 
 declare class RelationChangeProcessor {
     private readonly unitOfWork;
@@ -1759,16 +1832,37 @@ declare class RelationChangeProcessor {
     private resolvePrimaryKeyValue;
 }
 
+/**
+ * Represents a single SQL query log entry
+ */
 interface QueryLogEntry {
+    /** The SQL query that was executed */
     sql: string;
+    /** Parameters used in the query */
     params?: unknown[];
 }
+/**
+ * Function type for query logging callbacks
+ * @param entry - The query log entry to process
+ */
 type QueryLogger = (entry: QueryLogEntry) => void;
+/**
+ * Creates a wrapped database executor that logs all SQL queries
+ * @param executor - Original database executor to wrap
+ * @param logger - Optional logger function to receive query log entries
+ * @returns Wrapped executor that logs queries before execution
+ */
 declare const createQueryLoggingExecutor: (executor: DbExecutor, logger?: QueryLogger) => DbExecutor;
 
+/**
+ * Context for SQL query execution
+ */
 interface ExecutionContext {
+    /** Database dialect to use for SQL generation */
     dialect: Dialect;
+    /** Database executor for running SQL queries */
     executor: DbExecutor;
+    /** Interceptor pipeline for query processing */
     interceptors: InterceptorPipeline;
 }
 
@@ -1785,10 +1879,10 @@ interface EntityContext {
     registerRelationChange(root: any, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<any>): void;
 }
 
-interface HydrationContext {
+interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
     identityMap: IdentityMap;
     unitOfWork: UnitOfWork;
-    domainEvents: DomainEventBus<any>;
+    domainEvents: DomainEventBus<E, OrmSession<E>>;
     relationChanges: RelationChangeProcessor;
     entityContext: EntityContext;
 }
@@ -1797,22 +1891,22 @@ interface OrmInterceptor {
     beforeFlush?(ctx: EntityContext): Promise<void> | void;
     afterFlush?(ctx: EntityContext): Promise<void> | void;
 }
-interface OrmSessionOptions {
-    orm: Orm;
+interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
+    orm: Orm<E>;
     executor: DbExecutor;
     queryLogger?: QueryLogger;
     interceptors?: OrmInterceptor[];
-    domainEventHandlers?: Record<string, DomainEventHandler<OrmSession>[]>;
+    domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
 }
-declare class OrmSession implements EntityContext {
-    readonly orm: Orm;
+declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements EntityContext {
+    readonly orm: Orm<E>;
     readonly executor: DbExecutor;
     readonly identityMap: IdentityMap;
     readonly unitOfWork: UnitOfWork;
-    readonly domainEvents: DomainEventBus<OrmSession>;
+    readonly domainEvents: DomainEventBus<E, OrmSession<E>>;
     readonly relationChanges: RelationChangeProcessor;
     private readonly interceptors;
-    constructor(opts: OrmSessionOptions);
+    constructor(opts: OrmSessionOptions<E>);
     get dialect(): Dialect;
     get identityBuckets(): Map<string, Map<string, TrackedEntity>>;
     get tracked(): TrackedEntity[];
@@ -1825,7 +1919,9 @@ declare class OrmSession implements EntityContext {
     registerRelationChange: (root: any, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<any>) => void;
     getEntitiesForTable(table: TableDef): TrackedEntity[];
     registerInterceptor(interceptor: OrmInterceptor): void;
-    registerDomainEventHandler(name: string, handler: DomainEventHandler<OrmSession>): void;
+    registerDomainEventHandler<TType extends E['type']>(type: TType, handler: DomainEventHandler<Extract<E, {
+        type: TType;
+    }>, OrmSession<E>>): void;
     find<TTable extends TableDef>(entityClass: EntityConstructor, id: any): Promise<Entity<TTable> | null>;
     findOne<TTable extends TableDef>(qb: SelectQueryBuilder<any, TTable>): Promise<Entity<TTable> | null>;
     findMany<TTable extends TableDef>(qb: SelectQueryBuilder<any, TTable>): Promise<Entity<TTable>[]>;
@@ -1835,11 +1931,17 @@ declare class OrmSession implements EntityContext {
     commit(): Promise<void>;
     rollback(): Promise<void>;
     getExecutionContext(): ExecutionContext;
-    getHydrationContext(): HydrationContext;
+    getHydrationContext(): HydrationContext<E>;
 }
 
 type SelectDialectInput = Dialect | DialectKey;
 
+type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode;
+type DeepSelectConfig<TTable extends TableDef> = {
+    root?: (keyof TTable['columns'] & string)[];
+} & {
+    [K in keyof TTable['relations'] & string]?: (keyof RelationTargetTable<TTable['relations'][K]>['columns'] & string)[];
+};
 /**
 
  * Main query builder class for constructing SQL SELECT queries
@@ -1884,7 +1986,12 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      * @returns New query builder instance with selected columns
   
      */
-    select(columns: Record<string, ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode>): SelectQueryBuilder<T, TTable>;
+    select(columns: Record<string, ColumnSelectionValue>): SelectQueryBuilder<T, TTable>;
+    /**
+     * Selects columns from the root table by name (typed).
+     * @param cols - Column names on the root table
+     */
+    selectColumns<K extends keyof TTable['columns'] & string>(...cols: K[]): SelectQueryBuilder<T, TTable>;
     /**
   
      * Selects raw column expressions
@@ -2010,6 +2117,18 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
      */
     include(relationName: string, options?: RelationIncludeOptions): SelectQueryBuilder<T, TTable>;
     includeLazy<K extends keyof RelationMap<TTable>>(relationName: K): SelectQueryBuilder<T, TTable>;
+    /**
+     * Selects columns for a related table in a single hop.
+     */
+    selectRelationColumns<K extends keyof TTable['relations'] & string, TRel extends RelationDef = TTable['relations'][K], TTarget extends TableDef = RelationTargetTable<TRel>, C extends keyof TTarget['columns'] & string = keyof TTarget['columns'] & string>(relationName: K, ...cols: C[]): SelectQueryBuilder<T, TTable>;
+    /**
+     * Convenience alias for selecting specific columns from a relation.
+     */
+    includePick<K extends keyof TTable['relations'] & string, TRel extends RelationDef = TTable['relations'][K], TTarget extends TableDef = RelationTargetTable<TRel>, C extends keyof TTarget['columns'] & string = keyof TTarget['columns'] & string>(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable>;
+    /**
+     * Selects columns for the root table and relations from a single config object.
+     */
+    selectColumnsDeep(config: DeepSelectConfig<TTable>): SelectQueryBuilder<T, TTable>;
     getLazyRelations(): (keyof RelationMap<TTable>)[];
     getTable(): TTable;
     execute(ctx: OrmSession): Promise<Entity<TTable>[]>;
@@ -2230,4 +2349,4 @@ declare const createColumn: (table: string, name: string) => ColumnNode;
  */
 declare const createLiteral: (val: string | number) => LiteralNode;
 
-export { type TableHooks as $, type BelongsToRelation as A, type BinaryExpressionNode as B, type ColumnRef as C, Dialect as D, type ExpressionNode as E, type FunctionNode as F, type BelongsToManyRelation as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type HasManyCollection as K, type LogicalExpressionNode as L, type BelongsToReference as M, type NullExpressionNode as N, type OperandNode as O, type ManyToManyCollection as P, OrmSession as Q, type RelationMap as R, type SelectQueryNode as S, type TableRef as T, type UpdateQueryNode as U, SelectQueryBuilder as V, type WindowFunctionNode as W, type ExecutionContext as X, type HydrationContext as Y, type CheckConstraint as Z, type TableOptions as _, type ColumnNode as a, defineTable as a0, type ColumnType as a1, type ReferentialAction as a2, type RawDefaultValue as a3, type DefaultValue as a4, col as a5, RelationKinds as a6, type RelationType as a7, type CascadeMode as a8, type RelationDef as a9, EntityStatus as aA, type TrackedEntity as aB, type RelationKey as aC, type RelationChange as aD, type RelationChangeEntry as aE, type HasDomainEvents as aF, type QueryLogEntry as aG, type QueryLogger as aH, createQueryLoggingExecutor as aI, type QueryResult as aJ, rowsToQueryResult as aK, type SimpleQueryRunner as aL, createExecutorFromQueryRunner as aM, type EntityOrTableTargetResolver as aN, type EntityConstructor as aO, hasMany as aa, hasOne as ab, belongsTo as ac, belongsToMany as ad, type ColumnToTs as ae, type InferRow as af, type HasOneReference as ag, createColumn as ah, createLiteral as ai, isOperandNode as aj, isFunctionNode as ak, isCaseExpressionNode as al, isWindowFunctionNode as am, isExpressionSelectionNode as an, type HydrationPivotPlan as ao, type HydrationRelationPlan as ap, type HydrationMetadata as aq, type OrmInterceptor as ar, type OrmSessionOptions as as, type OrmOptions as at, type DbExecutorFactory as au, type ExternalTransaction as av, Orm as aw, type DomainEventHandler as ax, DomainEventBus as ay, addDomainEvent as az, type LiteralNode as b, type BetweenExpressionNode as c, type CaseExpressionNode as d, type ExistsExpressionNode as e, type OrderDirection as f, type ScalarSubqueryNode as g, type ColumnDef as h, type TableDef as i, type InsertQueryNode as j, type InsertCompiler as k, type CompiledQuery as l, type DialectKey as m, type UpdateCompiler as n, type DeleteQueryNode as o, type DeleteCompiler as p, type CompilerContext as q, type ForeignKeyReference as r, type IndexColumn as s, type IndexDef as t, type DbExecutor as u, type NamingStrategy as v, type EntityContext as w, type Entity as x, type HasManyRelation as y, type HasOneRelation as z };
+export { type TableHooks as $, type BelongsToRelation as A, type BinaryExpressionNode as B, type ColumnRef as C, Dialect as D, type ExpressionNode as E, type FunctionNode as F, type BelongsToManyRelation as G, type HydrationPlan as H, type InExpressionNode as I, type JsonPathNode as J, type HasManyCollection as K, type LiteralNode as L, type BelongsToReference as M, type NullExpressionNode as N, type OperandNode as O, type ManyToManyCollection as P, OrmSession as Q, type RelationMap as R, type SelectQueryNode as S, type TableRef as T, type UpdateQueryNode as U, SelectQueryBuilder as V, type WindowFunctionNode as W, type ExecutionContext as X, type HydrationContext as Y, type CheckConstraint as Z, type TableOptions as _, type ColumnNode as a, defineTable as a0, type ColumnType as a1, type ReferentialAction as a2, type RawDefaultValue as a3, type DefaultValue as a4, col as a5, RelationKinds as a6, type RelationType as a7, type CascadeMode as a8, type RelationDef as a9, DomainEventBus as aA, addDomainEvent as aB, EntityStatus as aC, type TrackedEntity as aD, type RelationKey as aE, type RelationChange as aF, type RelationChangeEntry as aG, type DomainEvent as aH, type AnyDomainEvent as aI, type OrmDomainEvent as aJ, type HasDomainEvents as aK, type QueryLogEntry as aL, type QueryLogger as aM, createQueryLoggingExecutor as aN, type QueryResult as aO, rowsToQueryResult as aP, type SimpleQueryRunner as aQ, createExecutorFromQueryRunner as aR, type EntityOrTableTargetResolver as aS, type EntityConstructor as aT, hasMany as aa, hasOne as ab, belongsTo as ac, belongsToMany as ad, type RelationTargetTable as ae, type ColumnToTs as af, type InferRow as ag, type HasOneReference as ah, createColumn as ai, createLiteral as aj, isOperandNode as ak, isFunctionNode as al, isCaseExpressionNode as am, isWindowFunctionNode as an, isExpressionSelectionNode as ao, type HydrationPivotPlan as ap, type HydrationRelationPlan as aq, type HydrationMetadata as ar, type OrmInterceptor as as, type OrmSessionOptions as at, type OrmOptions as au, type DbExecutorFactory as av, type ExternalTransaction as aw, Orm as ax, type DomainEventHandler as ay, type InitialHandlers as az, type LogicalExpressionNode as b, type BetweenExpressionNode as c, type CaseExpressionNode as d, type ExistsExpressionNode as e, type OrderDirection as f, type ScalarSubqueryNode as g, type ColumnDef as h, type TableDef as i, type InsertQueryNode as j, type InsertCompiler as k, type CompiledQuery as l, type DialectKey as m, type UpdateCompiler as n, type DeleteQueryNode as o, type DeleteCompiler as p, type CompilerContext as q, type ForeignKeyReference as r, type IndexColumn as s, type IndexDef as t, type DbExecutor as u, type NamingStrategy as v, type EntityContext as w, type Entity as x, type HasManyRelation as y, type HasOneRelation as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "type": "module",
   "exports": {
     ".": {
@@ -46,6 +46,7 @@
   },
   "devDependencies": {
     "@vitest/ui": "^4.0.14",
+    "sqlite3": "^5.1.7",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "vitest": "^4.0.14"

package/src/core/ast/aggregate-functions.ts

@@ -1,6 +1,8 @@
 import { ColumnNode, FunctionNode } from './expression-nodes.js';
-import { columnOperand } from './expression-builders.js';
+import { columnOperand, valueToOperand, ValueOperandInput } from './expression-builders.js';
 import { ColumnRef } from './types.js';
+import { OrderByNode } from './query.js';
+import { ORDER_DIRECTIONS, OrderDirection } from '../sql/sql.js';
 
 const buildAggregate = (name: string) => (col: ColumnRef | ColumnNode): FunctionNode => ({
   type: 'Function',
@@ -25,6 +27,50 @@ export const sum = buildAggregate('SUM');
 /**
  * Creates an AVG function expression
  * @param col - Column to average
- * @returns Function node with AVG
- */
-export const avg = buildAggregate('AVG');
+ * @returns Function node with AVG
+ */
+export const avg = buildAggregate('AVG');
+
+/**
+ * Creates a MIN function expression
+ * @param col - Column to take the minimum of
+ * @returns Function node with MIN
+ */
+export const min = buildAggregate('MIN');
+
+/**
+ * Creates a MAX function expression
+ * @param col - Column to take the maximum of
+ * @returns Function node with MAX
+ */
+export const max = buildAggregate('MAX');
+
+type GroupConcatOrderByInput = {
+  column: ColumnRef | ColumnNode;
+  direction?: OrderDirection;
+};
+
+export type GroupConcatOptions = {
+  separator?: ValueOperandInput;
+  orderBy?: GroupConcatOrderByInput[];
+};
+
+const toOrderByNode = (order: GroupConcatOrderByInput): OrderByNode => ({
+  type: 'OrderBy',
+  column: columnOperand(order.column),
+  direction: order.direction ?? ORDER_DIRECTIONS.ASC
+});
+
+/**
+ * Aggregates grouped strings into a single value.
+ */
+export const groupConcat = (
+  col: ColumnRef | ColumnNode,
+  options?: GroupConcatOptions
+): FunctionNode => ({
+  type: 'Function',
+  name: 'GROUP_CONCAT',
+  args: [columnOperand(col)],
+  orderBy: options?.orderBy?.map(toOrderByNode),
+  separator: options?.separator !== undefined ? valueToOperand(options.separator) : undefined
+});

package/src/core/ast/expression-builders.ts

@@ -19,22 +19,23 @@ import {
   isOperandNode
 } from './expression-nodes.js';
 
+export type LiteralValue = LiteralNode['value'];
+export type ValueOperandInput = OperandNode | LiteralValue;
+
 /**
  * Converts a primitive or existing operand into an operand node
  * @param value - Value or operand to normalize
  * @returns OperandNode representing the value
  */
-export const valueToOperand = (value: unknown): OperandNode => {
-  if (
-    value === null ||
-    value === undefined ||
-    typeof value === 'string' ||
-    typeof value === 'number' ||
-    typeof value === 'boolean'
-  ) {
-    return { type: 'Literal', value: value === undefined ? null : value } as LiteralNode;
+export const valueToOperand = (value: ValueOperandInput): OperandNode => {
+  if (isOperandNode(value)) {
+    return value;
   }
-  return value as OperandNode;
+
+  return {
+    type: 'Literal',
+    value
+  } as LiteralNode;
 };
 
 const toNode = (col: ColumnRef | OperandNode): OperandNode => {
@@ -48,12 +49,18 @@ const toLiteralNode = (value: string | number | boolean | null): LiteralNode =>
   value
 });
 
-const toOperand = (val: OperandNode | ColumnRef | string | number | boolean | null): OperandNode => {
-  if (val === null) return { type: 'Literal', value: null };
-  if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean') {
-    return { type: 'Literal', value: val };
+const isLiteralValue = (value: unknown): value is LiteralValue =>
+  value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+
+export const isValueOperandInput = (value: unknown): value is ValueOperandInput =>
+  isOperandNode(value) || isLiteralValue(value);
+
+const toOperand = (val: OperandNode | ColumnRef | LiteralValue): OperandNode => {
+  if (isLiteralValue(val)) {
+    return valueToOperand(val);
   }
-  return toNode(val as OperandNode | ColumnRef);
+
+  return toNode(val);
 };
 
 export const columnOperand = (col: ColumnRef | ColumnNode): ColumnNode => toNode(col) as ColumnNode;

package/src/core/ast/expression-nodes.ts

@@ -37,6 +37,12 @@ export interface FunctionNode {
   args: OperandNode[];
   /** Optional alias for the function result */
   alias?: string;
+  /** Optional ORDER BY clause used by aggregations like GROUP_CONCAT */
+  orderBy?: OrderByNode[];
+  /** Optional separator argument used by GROUP_CONCAT-like functions */
+  separator?: OperandNode;
+  /** Optional DISTINCT modifier */
+  distinct?: boolean;
 }
 
 /**

package/src/core/ddl/introspect/functions/postgres.ts

@@ -1,14 +1,10 @@
 // Small helpers to build Postgres-specific function calls as AST FunctionNodes
-import { columnOperand, valueToOperand } from '../../../ast/expression-builders.js';
+import { valueToOperand } from '../../../ast/expression-builders.js';
 import type { OperandNode, FunctionNode } from '../../../ast/expression.js';
 
 type OperandInput = OperandNode | string | number | boolean | null;
 
-const toOperand = (v: OperandInput) => {
-  if (v === null) return valueToOperand(null);
-  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') return valueToOperand(v);
-  return v as OperandNode;
-};
+const toOperand = (v: OperandInput): OperandNode => valueToOperand(v);
 
 const fn = (name: string, args: OperandInput[]): FunctionNode => ({
   type: 'Function',

package/src/core/dialect/abstract.ts

@@ -476,12 +476,16 @@ export abstract class Dialect
   /**
    * Compiles a function operand, using the dialect's function strategy.
    */
-  protected compileFunctionOperand(fnNode: FunctionNode, ctx: CompilerContext): string {
-    const compiledArgs = fnNode.args.map(arg => this.compileOperand(arg, ctx));
-    const renderer = this.functionStrategy.getRenderer(fnNode.name);
-    if (renderer) {
-      return renderer({ node: fnNode, compiledArgs });
-    }
-    return `${fnNode.name}(${compiledArgs.join(', ')})`;
-  }
+  protected compileFunctionOperand(fnNode: FunctionNode, ctx: CompilerContext): string {
+    const compiledArgs = fnNode.args.map(arg => this.compileOperand(arg, ctx));
+    const renderer = this.functionStrategy.getRenderer(fnNode.name);
+    if (renderer) {
+      return renderer({
+        node: fnNode,
+        compiledArgs,
+        compileOperand: operand => this.compileOperand(operand, ctx)
+      });
+    }
+    return `${fnNode.name}(${compiledArgs.join(', ')})`;
+  }
 }

package/src/core/dialect/mssql/functions.ts

@@ -84,18 +84,27 @@ export class MssqlFunctionStrategy extends StandardFunctionStrategy {
             return `DATEPART(dw, ${compiledArgs[0]})`;
         });
 
-        this.add('WEEK_OF_YEAR', ({ compiledArgs }) => {
-            if (compiledArgs.length !== 1) throw new Error('WEEK_OF_YEAR expects 1 argument');
-            return `DATEPART(wk, ${compiledArgs[0]})`;
-        });
-
-        this.add('DATE_TRUNC', ({ node, compiledArgs }) => {
-            if (compiledArgs.length !== 2) throw new Error('DATE_TRUNC expects 2 arguments (part, date)');
-            const [, date] = compiledArgs;
-            const partArg = node.args[0] as LiteralNode;
-            const partClean = String(partArg.value).replace(/['"]/g, '').toLowerCase();
-            // SQL Server 2022+ has DATETRUNC
-            return `DATETRUNC(${partClean}, ${date})`;
-        });
-    }
-}
+        this.add('WEEK_OF_YEAR', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 1) throw new Error('WEEK_OF_YEAR expects 1 argument');
+            return `DATEPART(wk, ${compiledArgs[0]})`;
+        });
+
+        this.add('DATE_TRUNC', ({ node, compiledArgs }) => {
+            if (compiledArgs.length !== 2) throw new Error('DATE_TRUNC expects 2 arguments (part, date)');
+            const [, date] = compiledArgs;
+            const partArg = node.args[0] as LiteralNode;
+            const partClean = String(partArg.value).replace(/['"]/g, '').toLowerCase();
+            // SQL Server 2022+ has DATETRUNC
+            return `DATETRUNC(${partClean}, ${date})`;
+        });
+
+        this.add('GROUP_CONCAT', ctx => {
+            const arg = ctx.compiledArgs[0];
+            const separatorOperand = this.getGroupConcatSeparatorOperand(ctx);
+            const separator = ctx.compileOperand(separatorOperand);
+            const orderClause = this.buildOrderByExpression(ctx);
+            const withinGroup = orderClause ? ` WITHIN GROUP (${orderClause})` : '';
+            return `STRING_AGG(${arg}, ${separator})${withinGroup}`;
+        });
+    }
+}