metal-orm 1.0.40 → 1.0.41

package/dist/index.d.ts

@@ -607,6 +607,7 @@ interface ScalarSubqueryNode {
     /** Optional alias for the subquery result */
     alias?: string;
 }
+type InExpressionRight = OperandNode[] | ScalarSubqueryNode;
 /**
  * AST node representing a CASE expression
  */
@@ -700,7 +701,7 @@ interface InExpressionNode {
     /** IN/NOT IN operator */
     operator: 'IN' | 'NOT IN';
     /** Values to check against */
-    right: OperandNode[];
+    right: InExpressionRight;
 }
 /**
  * AST node representing an EXISTS/NOT EXISTS expression
@@ -740,6 +741,9 @@ type ValueOperandInput = OperandNode | LiteralValue;
  */
 declare const valueToOperand: (value: ValueOperandInput) => OperandNode;
 declare const isValueOperandInput: (value: unknown) => value is ValueOperandInput;
+type SelectQueryInput = SelectQueryNode | {
+    getAST(): SelectQueryNode;
+};
 declare const columnOperand: (col: ColumnRef | ColumnNode) => ColumnNode;
 /**
  * Marks a column reference as an outer-scope reference for correlated subqueries.
@@ -841,6 +845,8 @@ declare const inList: (left: OperandNode | ColumnRef, values: (string | number |
  * @returns NOT IN expression node
  */
 declare const notInList: (left: OperandNode | ColumnRef, values: (string | number | LiteralNode)[]) => InExpressionNode;
+declare const inSubquery: (left: OperandNode | ColumnRef, subquery: SelectQueryInput) => InExpressionNode;
+declare const notInSubquery: (left: OperandNode | ColumnRef, subquery: SelectQueryInput) => InExpressionNode;
 /**
  * Creates a BETWEEN expression (value BETWEEN lower AND upper)
  * @param left - Operand to check
@@ -1200,14 +1206,25 @@ interface SelectQueryNode {
     /** Optional set operations chaining this query with others */
     setOps?: SetOperationNode[];
 }
+interface InsertValuesSourceNode {
+    type: 'InsertValues';
+    /** Rows of values for INSERT rows */
+    rows: OperandNode[][];
+}
+interface InsertSelectSourceNode {
+    type: 'InsertSelect';
+    /** SELECT query providing rows */
+    query: SelectQueryNode;
+}
+type InsertSourceNode = InsertValuesSourceNode | InsertSelectSourceNode;
 interface InsertQueryNode {
     type: 'InsertQuery';
     /** Target table */
     into: TableNode;
     /** Column order for inserted values */
     columns: ColumnNode[];
-    /** Rows of values to insert */
-    values: OperandNode[][];
+    /** Source of inserted rows (either literal values or a SELECT query) */
+    source: InsertSourceNode;
     /** Optional RETURNING clause */
     returning?: ColumnNode[];
 }
@@ -1221,6 +1238,10 @@ interface UpdateQueryNode {
     type: 'UpdateQuery';
     /** Table being updated */
     table: TableNode;
+    /** Optional FROM clause for multi-table updates */
+    from?: TableSourceNode;
+    /** Optional joins applied to the FROM/USING tables */
+    joins?: JoinNode[];
     /** Assignments for SET clause */
     set: UpdateAssignmentNode[];
     /** Optional WHERE clause */
@@ -1232,6 +1253,10 @@ interface DeleteQueryNode {
     type: 'DeleteQuery';
     /** Table to delete from */
     from: TableNode;
+    /** Optional USING clause for multi-table deletes */
+    using?: TableSourceNode;
+    /** Optional joins applied to the USING clause */
+    joins?: JoinNode[];
     /** Optional WHERE clause */
     where?: ExpressionNode;
     /** Optional RETURNING clause */
@@ -1982,10 +2007,17 @@ type QueryResult = {
     values: unknown[][];
 };
 interface DbExecutor {
+    /** Capability flags so the runtime can make correct decisions without relying on optional methods. */
+    readonly capabilities: {
+        /** True if begin/commit/rollback are real and should be used to provide atomicity. */
+        transactions: boolean;
+    };
     executeSql(sql: string, params?: unknown[]): Promise<QueryResult[]>;
-    beginTransaction?(): Promise<void>;
-    commitTransaction?(): Promise<void>;
-    rollbackTransaction?(): Promise<void>;
+    beginTransaction(): Promise<void>;
+    commitTransaction(): Promise<void>;
+    rollbackTransaction(): Promise<void>;
+    /** Release any underlying resources (connections, pool leases, etc). Must be idempotent. */
+    dispose(): Promise<void>;
 }
 /**
  * Convert an array of row objects into a QueryResult.
@@ -1996,17 +2028,20 @@ declare function rowsToQueryResult(rows: Array<Record<string, unknown>>): QueryR
  */
 interface SimpleQueryRunner {
     query(sql: string, params?: unknown[]): Promise<Array<Record<string, unknown>>>;
+    /** Optional: used to support real transactions. */
     beginTransaction?(): Promise<void>;
     commitTransaction?(): Promise<void>;
     rollbackTransaction?(): Promise<void>;
+    /** Optional: release resources (connection close, pool lease release, etc). */
+    dispose?(): Promise<void>;
 }
 /**
  * Generic factory: turn any SimpleQueryRunner into a DbExecutor.
  */
 declare function createExecutorFromQueryRunner(runner: SimpleQueryRunner): DbExecutor;
 
-type EntityConstructor = new (...args: any[]) => any;
-type EntityOrTableTarget = EntityConstructor | TableDef;
+type EntityConstructor<T = object> = new (...args: any[]) => T;
+type EntityOrTableTarget = EntityConstructor<any> | TableDef;
 type EntityOrTableTargetResolver = EntityOrTableTarget | (() => EntityOrTableTarget);
 
 /**
@@ -2133,30 +2168,74 @@ declare class InterceptorPipeline {
     run(ctx: QueryContext, executor: DbExecutor): Promise<QueryResult[]>;
 }
 
+/**
+ * Options for creating an ORM instance.
+ * @template E - The domain event type
+ */
 interface OrmOptions<E extends DomainEvent = OrmDomainEvent> {
+    /** The database dialect */
     dialect: Dialect;
+    /** The database executor factory */
     executorFactory: DbExecutorFactory;
+    /** Optional interceptors pipeline */
     interceptors?: InterceptorPipeline;
+    /** Optional naming strategy */
     namingStrategy?: NamingStrategy;
 }
+/**
+ * Database executor factory interface.
+ */
 interface DbExecutorFactory {
-    createExecutor(options?: {
-        tx?: ExternalTransaction;
-    }): DbExecutor;
+    /**
+     * Creates a database executor.
+     * @returns The database executor
+     */
+    createExecutor(): DbExecutor;
+    /**
+     * Creates a transactional database executor.
+     * @returns The transactional database executor
+     */
     createTransactionalExecutor(): DbExecutor;
+    /**
+     * Disposes any underlying resources (connection pools, background timers, etc).
+     */
+    dispose(): Promise<void>;
 }
-interface ExternalTransaction {
-}
+/**
+ * ORM (Object-Relational Mapping) main class.
+ * @template E - The domain event type
+ */
 declare class Orm<E extends DomainEvent = OrmDomainEvent> {
+    /** The database dialect */
     readonly dialect: Dialect;
+    /** The interceptors pipeline */
     readonly interceptors: InterceptorPipeline;
+    /** The naming strategy */
     readonly namingStrategy: NamingStrategy;
     private readonly executorFactory;
+    /**
+     * Creates a new ORM instance.
+     * @param opts - ORM options
+     */
     constructor(opts: OrmOptions<E>);
-    createSession(options?: {
-        tx?: ExternalTransaction;
-    }): OrmSession<E>;
+    /**
+     * Creates a new ORM session.
+     * @param options - Optional session options
+     * @returns The ORM session
+     */
+    createSession(): OrmSession<E>;
+    /**
+     * Executes a function within a transaction.
+     * @template T - The return type
+     * @param fn - The function to execute
+     * @returns The result of the function
+     * @throws If the transaction fails
+     */
     transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T>;
+    /**
+     * Shuts down the ORM and releases underlying resources (pools, timers).
+     */
+    dispose(): Promise<void>;
 }
 
 declare class IdentityMap {
@@ -2170,75 +2249,327 @@ declare class IdentityMap {
     private toIdentityKey;
 }
 
+/**
+ * Unit of Work pattern implementation for tracking entity changes.
+ */
 declare class UnitOfWork {
     private readonly dialect;
     private readonly executor;
     private readonly identityMap;
     private readonly hookContext;
     private readonly trackedEntities;
+    /**
+     * Creates a new UnitOfWork instance.
+     * @param dialect - The database dialect
+     * @param executor - The database executor
+     * @param identityMap - The identity map
+     * @param hookContext - Function to get the hook context
+     */
     constructor(dialect: Dialect, executor: DbExecutor, identityMap: IdentityMap, hookContext: () => unknown);
+    /**
+     * Gets the identity buckets map.
+     */
     get identityBuckets(): Map<string, Map<string, TrackedEntity>>;
+    /**
+     * Gets all tracked entities.
+     * @returns Array of tracked entities
+     */
     getTracked(): TrackedEntity[];
+    /**
+     * Gets an entity by table and primary key.
+     * @param table - The table definition
+     * @param pk - The primary key value
+     * @returns The entity or undefined if not found
+     */
     getEntity(table: TableDef, pk: string | number): any | undefined;
+    /**
+     * Gets all tracked entities for a specific table.
+     * @param table - The table definition
+     * @returns Array of tracked entities
+     */
     getEntitiesForTable(table: TableDef): TrackedEntity[];
+    /**
+     * Finds a tracked entity.
+     * @param entity - The entity to find
+     * @returns The tracked entity or undefined if not found
+     */
     findTracked(entity: any): TrackedEntity | undefined;
+    /**
+     * Sets an entity in the identity map.
+     * @param table - The table definition
+     * @param pk - The primary key value
+     * @param entity - The entity instance
+     */
     setEntity(table: TableDef, pk: string | number, entity: any): void;
+    /**
+     * Tracks a new entity.
+     * @param table - The table definition
+     * @param entity - The entity instance
+     * @param pk - Optional primary key value
+     */
     trackNew(table: TableDef, entity: any, pk?: string | number): void;
+    /**
+     * Tracks a managed entity.
+     * @param table - The table definition
+     * @param pk - The primary key value
+     * @param entity - The entity instance
+     */
     trackManaged(table: TableDef, pk: string | number, entity: any): void;
+    /**
+     * Marks an entity as dirty (modified).
+     * @param entity - The entity to mark as dirty
+     */
     markDirty(entity: any): void;
+    /**
+     * Marks an entity as removed.
+     * @param entity - The entity to mark as removed
+     */
     markRemoved(entity: any): void;
+    /**
+     * Flushes pending changes to the database.
+     */
     flush(): Promise<void>;
+    /**
+     * Resets the unit of work by clearing all tracked entities and identity map.
+     */
     reset(): void;
+    /**
+     * Flushes an insert operation for a new entity.
+     * @param tracked - The tracked entity to insert
+     */
     private flushInsert;
+    /**
+     * Flushes an update operation for a modified entity.
+     * @param tracked - The tracked entity to update
+     */
     private flushUpdate;
+    /**
+     * Flushes a delete operation for a removed entity.
+     * @param tracked - The tracked entity to delete
+     */
     private flushDelete;
+    /**
+     * Runs a table hook if defined.
+     * @param hook - The hook function
+     * @param tracked - The tracked entity
+     */
     private runHook;
+    /**
+     * Computes changes between current entity state and original snapshot.
+     * @param tracked - The tracked entity
+     * @returns Object with changed column values
+     */
     private computeChanges;
+    /**
+     * Extracts column values from an entity.
+     * @param table - The table definition
+     * @param entity - The entity instance
+     * @returns Object with column values
+     */
     private extractColumns;
+    /**
+     * Executes a compiled query.
+     * @param compiled - The compiled query
+     * @returns Query results
+     */
     private executeCompiled;
+    /**
+     * Gets columns for RETURNING clause.
+     * @param table - The table definition
+     * @returns Array of column nodes
+     */
     private getReturningColumns;
+    /**
+     * Applies RETURNING clause results to the tracked entity.
+     * @param tracked - The tracked entity
+     * @param results - Query results
+     */
     private applyReturningResults;
+    /**
+     * Normalizes a column name by removing quotes and table prefixes.
+     * @param column - The column name to normalize
+     * @returns Normalized column name
+     */
     private normalizeColumnName;
+    /**
+     * Registers an entity in the identity map.
+     * @param tracked - The tracked entity to register
+     */
     private registerIdentity;
+    /**
+     * Creates a snapshot of an entity's current state.
+     * @param table - The table definition
+     * @param entity - The entity instance
+     * @returns Object with entity state
+     */
     private createSnapshot;
+    /**
+     * Gets the primary key value from a tracked entity.
+     * @param tracked - The tracked entity
+     * @returns Primary key value or null
+     */
     private getPrimaryKeyValue;
 }
 
+/**
+ * Extracts domain events of a specific type.
+ * @template E - The domain event type
+ * @template TType - The specific event type
+ */
 type EventOfType<E extends DomainEvent, TType extends E['type']> = Extract<E, {
     type: TType;
 }>;
+/**
+ * Domain event handler function.
+ * @template E - The domain event type
+ * @template Context - The context type
+ * @param event - The domain event
+ * @param ctx - The context
+ */
 type DomainEventHandler<E extends DomainEvent, Context> = (event: E, ctx: Context) => Promise<void> | void;
+/**
+ * Initial handlers for domain events.
+ * @template E - The domain event type
+ * @template Context - The context type
+ */
 type InitialHandlers<E extends DomainEvent, Context> = {
     [K in E['type']]?: DomainEventHandler<EventOfType<E, K>, Context>[];
 };
+/**
+ * Domain event bus for managing and dispatching domain events.
+ * @template E - The domain event type
+ * @template Context - The context type
+ */
 declare class DomainEventBus<E extends DomainEvent, Context> {
     private readonly handlers;
+    /**
+     * Creates a new DomainEventBus instance.
+     * @param initialHandlers - Optional initial event handlers
+     */
     constructor(initialHandlers?: InitialHandlers<E, Context>);
+    /**
+     * Registers an event handler for a specific event type.
+     * @template TType - The event type
+     * @param type - The event type
+     * @param handler - The event handler
+     */
     on<TType extends E['type']>(type: TType, handler: DomainEventHandler<EventOfType<E, TType>, Context>): void;
+    /**
+     * Registers an event handler for a specific event type (alias for on).
+     * @template TType - The event type
+     * @param type - The event type
+     * @param handler - The event handler
+     */
     register<TType extends E['type']>(type: TType, handler: DomainEventHandler<EventOfType<E, TType>, Context>): void;
+    /**
+     * Dispatches domain events for tracked entities.
+     * @param trackedEntities - Iterable of tracked entities
+     * @param ctx - The context to pass to handlers
+     */
     dispatch(trackedEntities: Iterable<TrackedEntity>, ctx: Context): Promise<void>;
 }
+/**
+ * Adds a domain event to an entity.
+ * @template E - The domain event type
+ * @param entity - The entity to add the event to
+ * @param event - The domain event to add
+ */
 declare const addDomainEvent: <E extends DomainEvent>(entity: HasDomainEvents<E>, event: E) => void;
 
+/**
+ * Processes relation changes for entity relationships.
+ */
 declare class RelationChangeProcessor {
     private readonly unitOfWork;
     private readonly dialect;
     private readonly executor;
     private readonly relationChanges;
+    /**
+     * Creates a new RelationChangeProcessor instance.
+     * @param unitOfWork - The unit of work instance
+     * @param dialect - The database dialect
+     * @param executor - The database executor
+     */
     constructor(unitOfWork: UnitOfWork, dialect: Dialect, executor: DbExecutor);
+    /**
+     * Registers a relation change for processing.
+     * @param entry - The relation change entry
+     */
     registerChange(entry: RelationChangeEntry): void;
+    /**
+     * Resets the relation change processor by clearing all pending changes.
+     */
     reset(): void;
+    /**
+     * Processes all pending relation changes.
+     */
     process(): Promise<void>;
+    /**
+     * Handles changes for has-many relations.
+     * @param entry - The relation change entry
+     */
     private handleHasManyChange;
+    /**
+     * Handles changes for has-one relations.
+     * @param entry - The relation change entry
+     */
     private handleHasOneChange;
+    /**
+     * Handles changes for belongs-to relations.
+     * @param _entry - The relation change entry (reserved for future use)
+     */
     private handleBelongsToChange;
+    /**
+     * Handles changes for belongs-to-many relations.
+     * @param entry - The relation change entry
+     */
     private handleBelongsToManyChange;
+    /**
+     * Assigns a foreign key for has-many relations.
+     * @param child - The child entity
+     * @param relation - The has-many relation
+     * @param rootValue - The root entity's primary key value
+     */
     private assignHasManyForeignKey;
+    /**
+     * Detaches a child entity from has-many relations.
+     * @param child - The child entity
+     * @param relation - The has-many relation
+     */
     private detachHasManyChild;
+    /**
+     * Assigns a foreign key for has-one relations.
+     * @param child - The child entity
+     * @param relation - The has-one relation
+     * @param rootValue - The root entity's primary key value
+     */
     private assignHasOneForeignKey;
+    /**
+     * Detaches a child entity from has-one relations.
+     * @param child - The child entity
+     * @param relation - The has-one relation
+     */
     private detachHasOneChild;
+    /**
+     * Inserts a pivot row for belongs-to-many relations.
+     * @param relation - The belongs-to-many relation
+     * @param rootId - The root entity's primary key value
+     * @param targetId - The target entity's primary key value
+     */
     private insertPivotRow;
+    /**
+     * Deletes a pivot row for belongs-to-many relations.
+     * @param relation - The belongs-to-many relation
+     * @param rootId - The root entity's primary key value
+     * @param targetId - The target entity's primary key value
+     */
     private deletePivotRow;
+    /**
+     * Resolves the primary key value from an entity.
+     * @param entity - The entity
+     * @param table - The table definition
+     * @returns The primary key value or null
+     */
     private resolvePrimaryKeyValue;
 }
 
@@ -2297,52 +2628,226 @@ interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
     entityContext: EntityContext;
 }
 
+interface SaveGraphOptions {
+    /** Remove existing collection members that are not present in the payload */
+    pruneMissing?: boolean;
+}
+
+/**
+ * Interface for ORM interceptors that allow hooking into the flush lifecycle.
+ */
 interface OrmInterceptor {
+    /**
+     * Called before the flush operation begins.
+     * @param ctx - The entity context
+     */
     beforeFlush?(ctx: EntityContext): Promise<void> | void;
+    /**
+     * Called after the flush operation completes.
+     * @param ctx - The entity context
+     */
     afterFlush?(ctx: EntityContext): Promise<void> | void;
 }
+/**
+ * Options for creating an OrmSession instance.
+ * @template E - The domain event type
+ */
 interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
+    /** The ORM instance */
     orm: Orm<E>;
+    /** The database executor */
     executor: DbExecutor;
+    /** Optional query logger for debugging */
     queryLogger?: QueryLogger;
+    /** Optional interceptors for flush lifecycle hooks */
     interceptors?: OrmInterceptor[];
+    /** Optional domain event handlers */
     domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
 }
+/**
+ * ORM Session that manages entity lifecycle, identity mapping, and database operations.
+ * @template E - The domain event type
+ */
 declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements EntityContext {
+    /** The ORM instance */
     readonly orm: Orm<E>;
+    /** The database executor */
     readonly executor: DbExecutor;
+    /** The identity map for tracking entity instances */
     readonly identityMap: IdentityMap;
+    /** The unit of work for tracking entity changes */
     readonly unitOfWork: UnitOfWork;
+    /** The domain event bus */
     readonly domainEvents: DomainEventBus<E, OrmSession<E>>;
+    /** The relation change processor */
     readonly relationChanges: RelationChangeProcessor;
     private readonly interceptors;
+    /**
+     * Creates a new OrmSession instance.
+     * @param opts - Session options
+     */
     constructor(opts: OrmSessionOptions<E>);
+    /**
+     * Releases resources associated with this session (executor/pool leases) and resets tracking.
+     * Must be safe to call multiple times.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Gets the database dialect.
+     */
     get dialect(): Dialect;
+    /**
+     * Gets the identity buckets map.
+     */
     get identityBuckets(): Map<string, Map<string, TrackedEntity>>;
+    /**
+     * Gets all tracked entities.
+     */
     get tracked(): TrackedEntity[];
+    /**
+     * Gets an entity by table and primary key.
+     * @param table - The table definition
+     * @param pk - The primary key value
+     * @returns The entity or undefined if not found
+     */
     getEntity(table: TableDef, pk: any): any | undefined;
+    /**
+     * Sets an entity in the identity map.
+     * @param table - The table definition
+     * @param pk - The primary key value
+     * @param entity - The entity instance
+     */
     setEntity(table: TableDef, pk: any, entity: any): void;
+    /**
+     * Tracks a new entity.
+     * @param table - The table definition
+     * @param entity - The entity instance
+     * @param pk - Optional primary key value
+     */
     trackNew(table: TableDef, entity: any, pk?: any): void;
+    /**
+     * Tracks a managed entity.
+     * @param table - The table definition
+     * @param pk - The primary key value
+     * @param entity - The entity instance
+     */
     trackManaged(table: TableDef, pk: any, entity: any): void;
+    /**
+     * Marks an entity as dirty (modified).
+     * @param entity - The entity to mark as dirty
+     */
     markDirty(entity: any): void;
+    /**
+     * Marks an entity as removed.
+     * @param entity - The entity to mark as removed
+     */
     markRemoved(entity: any): void;
+    /**
+     * Registers a relation change.
+     * @param root - The root entity
+     * @param relationKey - The relation key
+     * @param rootTable - The root table definition
+     * @param relationName - The relation name
+     * @param relation - The relation definition
+     * @param change - The relation change
+     */
     registerRelationChange: (root: any, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<any>) => void;
+    /**
+     * Gets all tracked entities for a specific table.
+     * @param table - The table definition
+     * @returns Array of tracked entities
+     */
     getEntitiesForTable(table: TableDef): TrackedEntity[];
+    /**
+     * Registers an interceptor for flush lifecycle hooks.
+     * @param interceptor - The interceptor to register
+     */
     registerInterceptor(interceptor: OrmInterceptor): void;
+    /**
+     * Registers a domain event handler.
+     * @param type - The event type
+     * @param handler - The event handler
+     */
     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<EntityInstance<TTable> | null>;
+    /**
+     * Finds an entity by its primary key.
+     * @template TCtor - The entity constructor type
+     * @param entityClass - The entity constructor
+     * @param id - The primary key value
+     * @returns The entity instance or null if not found
+     * @throws If entity metadata is not bootstrapped or table has no primary key
+     */
+    find<TCtor extends EntityConstructor<any>>(entityClass: TCtor, id: any): Promise<InstanceType<TCtor> | null>;
+    /**
+     * Finds a single entity using a query builder.
+     * @template TTable - The table type
+     * @param qb - The query builder
+     * @returns The first entity instance or null if not found
+     */
     findOne<TTable extends TableDef>(qb: SelectQueryBuilder<any, TTable>): Promise<EntityInstance<TTable> | null>;
+    /**
+     * Finds multiple entities using a query builder.
+     * @template TTable - The table type
+     * @param qb - The query builder
+     * @returns Array of entity instances
+     */
     findMany<TTable extends TableDef>(qb: SelectQueryBuilder<any, TTable>): Promise<EntityInstance<TTable>[]>;
+    /**
+     * Saves an entity graph (root + nested relations) based on a DTO-like payload.
+     * @param entityClass - Root entity constructor
+     * @param payload - DTO payload containing column values and nested relations
+     * @param options - Graph save options
+     * @returns The root entity instance
+     */
+    saveGraph<TCtor extends EntityConstructor<any>>(entityClass: TCtor, payload: Record<string, any>, options?: SaveGraphOptions & {
+        transactional?: boolean;
+    }): Promise<InstanceType<TCtor>>;
+    /**
+     * Persists an entity (either inserts or updates).
+     * @param entity - The entity to persist
+     * @throws If entity metadata is not bootstrapped
+     */
     persist(entity: object): Promise<void>;
+    /**
+     * Marks an entity for removal.
+     * @param entity - The entity to remove
+     */
     remove(entity: object): Promise<void>;
+    /**
+     * Flushes pending changes to the database.
+     */
     flush(): Promise<void>;
+    /**
+     * Flushes pending changes with interceptors and relation processing.
+     */
     private flushWithHooks;
+    /**
+     * Commits the current transaction.
+     */
     commit(): Promise<void>;
+    /**
+     * Executes a function within a transaction.
+     * @template T - The return type
+     * @param fn - The function to execute
+     * @returns The result of the function
+     * @throws If the transaction fails
+     */
     transaction<T>(fn: (session: OrmSession<E>) => Promise<T>): Promise<T>;
+    /**
+     * Rolls back the current transaction.
+     */
     rollback(): Promise<void>;
+    /**
+     * Gets the execution context.
+     * @returns The execution context
+     */
     getExecutionContext(): ExecutionContext;
+    /**
+     * Gets the hydration context.
+     * @returns The hydration context
+     */
     getHydrationContext(): HydrationContext<E>;
 }
 
@@ -2804,7 +3309,12 @@ declare class InsertQueryState {
     readonly ast: InsertQueryNode;
     constructor(table: TableDef, ast?: InsertQueryNode);
     private clone;
+    private ensureColumnsFromRow;
+    private appendValues;
+    private getTableColumns;
     withValues(rows: Record<string, unknown>[]): InsertQueryState;
+    withColumns(columns: ColumnNode[]): InsertQueryState;
+    withSelect(query: SelectQueryNode, columns: ColumnNode[]): InsertQueryState;
     withReturning(columns: ColumnNode[]): InsertQueryState;
 }
 
@@ -2818,7 +3328,11 @@ declare class InsertQueryBuilder<T> {
     constructor(table: TableDef, state?: InsertQueryState);
     private clone;
     values(rowOrRows: Record<string, unknown> | Record<string, unknown>[]): InsertQueryBuilder<T>;
+    columns(...columns: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T>;
+    fromSelect(query: SelectQueryNode | SelectQueryBuilder<any, TableDef<any>>, columns?: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T>;
     returning(...columns: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T>;
+    private resolveColumnNodes;
+    private resolveSelectQuery;
     compile(compiler: InsertCompiler): CompiledQuery;
     compile(dialect: InsertDialectInput): CompiledQuery;
     toSql(arg: InsertCompiler | InsertDialectInput): string;
@@ -2836,6 +3350,9 @@ declare class UpdateQueryState {
     withSet(values: Record<string, unknown>): UpdateQueryState;
     withWhere(expr: ExpressionNode): UpdateQueryState;
     withReturning(columns: ColumnNode[]): UpdateQueryState;
+    withFrom(from: TableSourceNode): UpdateQueryState;
+    withJoin(join: JoinNode): UpdateQueryState;
+    withTableAlias(alias: string): UpdateQueryState;
 }
 
 type UpdateDialectInput = Dialect | DialectKey;
@@ -2847,9 +3364,14 @@ declare class UpdateQueryBuilder<T> {
     private readonly state;
     constructor(table: TableDef, state?: UpdateQueryState);
     private clone;
+    as(alias: string): UpdateQueryBuilder<T>;
+    from(source: TableDef | TableSourceNode): UpdateQueryBuilder<T>;
+    join(table: TableDef | TableSourceNode | string, condition: ExpressionNode, kind?: JoinKind, relationName?: string): UpdateQueryBuilder<T>;
     set(values: Record<string, unknown>): UpdateQueryBuilder<T>;
     where(expr: ExpressionNode): UpdateQueryBuilder<T>;
     returning(...columns: (ColumnDef | ColumnNode)[]): UpdateQueryBuilder<T>;
+    private resolveTableSource;
+    private resolveJoinTarget;
     compile(compiler: UpdateCompiler): CompiledQuery;
     compile(dialect: UpdateDialectInput): CompiledQuery;
     toSql(arg: UpdateCompiler | UpdateDialectInput): string;
@@ -2866,6 +3388,9 @@ declare class DeleteQueryState {
     private clone;
     withWhere(expr: ExpressionNode): DeleteQueryState;
     withReturning(columns: ColumnNode[]): DeleteQueryState;
+    withUsing(source: TableSourceNode): DeleteQueryState;
+    withJoin(join: JoinNode): DeleteQueryState;
+    withTableAlias(alias: string): DeleteQueryState;
 }
 
 type DeleteDialectInput = Dialect | DialectKey;
@@ -2878,7 +3403,12 @@ declare class DeleteQueryBuilder<T> {
     constructor(table: TableDef, state?: DeleteQueryState);
     private clone;
     where(expr: ExpressionNode): DeleteQueryBuilder<T>;
+    as(alias: string): DeleteQueryBuilder<T>;
+    using(source: TableDef | TableSourceNode): DeleteQueryBuilder<T>;
+    join(table: TableDef | TableSourceNode | string, condition: ExpressionNode, kind?: JoinKind, relationName?: string): DeleteQueryBuilder<T>;
     returning(...columns: (ColumnDef | ColumnNode)[]): DeleteQueryBuilder<T>;
+    private resolveTableSource;
+    private resolveJoinTarget;
     compile(compiler: DeleteCompiler): CompiledQuery;
     compile(dialect: DeleteDialectInput): CompiledQuery;
     toSql(arg: DeleteCompiler | DeleteDialectInput): string;
@@ -2929,11 +3459,12 @@ declare abstract class SqlDialectBase extends Dialect {
     private compileSelectWithSetOps;
     protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
     protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string;
+    private compileInsertSource;
     private compileInsertColumnList;
-    private compileInsertValues;
     private compileSelectCore;
     protected compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
     private compileUpdateAssignments;
+    protected compileQualifiedColumn(column: ColumnNode, table: TableNode): string;
     protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string;
     protected formatReturningColumns(returning: ColumnNode[]): string;
     protected compileDistinct(ast: SelectQueryNode): string;
@@ -2945,7 +3476,15 @@ declare abstract class SqlDialectBase extends Dialect {
     protected compileTableName(table: {
         name: string;
         schema?: string;
+        alias?: string;
     }): string;
+    protected compileTableReference(table: {
+        name: string;
+        schema?: string;
+        alias?: string;
+    }): string;
+    private compileUpdateFromClause;
+    private compileDeleteUsingClause;
     protected compileHaving(ast: SelectQueryNode, ctx: CompilerContext): string;
     protected stripTrailingSemicolon(sql: string): string;
     protected wrapSetOperand(sql: string): string;
@@ -2979,7 +3518,7 @@ declare class MySqlDialect extends SqlDialectBase {
 /**
  * Microsoft SQL Server dialect implementation
  */
-declare class SqlServerDialect extends Dialect {
+declare class SqlServerDialect extends SqlDialectBase {
     protected readonly dialect = "mssql";
     /**
      * Creates a new SqlServerDialect instance
@@ -3010,18 +3549,11 @@ declare class SqlServerDialect extends Dialect {
      * @returns SQL Server SQL string
      */
     protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
-    protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
-    protected compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
     protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string;
-    private compileSelectCore;
+    private compileSelectCoreForMssql;
     private compileOrderBy;
     private compilePagination;
-    private renderOrderByNulls;
-    private renderOrderByCollation;
-    private compileTableSource;
-    private compileDerivedTable;
     private compileCtes;
-    private wrapSetOperand;
 }
 
 /**
@@ -3045,6 +3577,7 @@ declare class SqliteDialect extends SqlDialectBase {
      * @returns SQLite JSON path expression
      */
     protected compileJsonPath(node: JsonPathNode): string;
+    protected compileQualifiedColumn(column: ColumnNode, _table: TableNode): string;
     protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string;
     protected formatReturningColumns(returning: ColumnNode[]): string;
     supportsReturning(): boolean;
@@ -3671,7 +4204,27 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
     private mapOp;
 }
 
+/**
+ * Creates an entity proxy with lazy loading capabilities.
+ * @template TTable - The table type
+ * @template TLazy - The lazy relation keys
+ * @param ctx - The entity context
+ * @param table - The table definition
+ * @param row - The database row
+ * @param lazyRelations - Optional lazy relations
+ * @returns The entity instance
+ */
 declare const createEntityProxy: <TTable extends TableDef, TLazy extends keyof RelationMap<TTable> = keyof RelationMap<TTable>>(ctx: EntityContext, table: TTable, row: Record<string, any>, lazyRelations?: TLazy[]) => EntityInstance<TTable>;
+/**
+ * Creates an entity instance from a database row.
+ * @template TTable - The table type
+ * @template TResult - The result type
+ * @param ctx - The entity context
+ * @param table - The table definition
+ * @param row - The database row
+ * @param lazyRelations - Optional lazy relations
+ * @returns The entity instance
+ */
 declare const createEntityFromRow: <TTable extends TableDef, TResult extends EntityInstance<TTable> = EntityInstance<TTable>>(ctx: EntityContext, table: TTable, row: Record<string, any>, lazyRelations?: (keyof RelationMap<TTable>)[]) => TResult;
 
 type Rows$3 = Record<string, any>[];
@@ -3843,8 +4396,60 @@ declare function BelongsTo(options: BelongsToOptions): DualModePropertyDecorator
 declare function BelongsToMany(options: BelongsToManyOptions): DualModePropertyDecorator;
 
 declare const bootstrapEntities: () => TableDef[];
-declare const getTableDefFromEntity: <TTable extends TableDef = TableDef>(ctor: EntityConstructor) => TTable | undefined;
-declare const selectFromEntity: <TTable extends TableDef = TableDef>(ctor: EntityConstructor) => SelectQueryBuilder<any, TTable>;
+declare const getTableDefFromEntity: <TTable extends TableDef = TableDef>(ctor: EntityConstructor<any>) => TTable | undefined;
+declare const selectFromEntity: <TTable extends TableDef = TableDef>(ctor: EntityConstructor<any>) => SelectQueryBuilder<any, TTable>;
+
+type PoolOptions = {
+    /** Maximum number of live resources (idle + leased). */
+    max: number;
+    /** Minimum number of idle resources to keep warm (best-effort). */
+    min?: number;
+    /** How long an idle resource can sit before being destroyed. */
+    idleTimeoutMillis?: number;
+    /** How often to reap idle resources. Defaults to idleTimeoutMillis / 2 (min 1s). */
+    reapIntervalMillis?: number;
+    /** How long callers wait for a resource before acquire() rejects. */
+    acquireTimeoutMillis?: number;
+};
+interface PoolAdapter<TResource> {
+    create(): Promise<TResource>;
+    destroy(resource: TResource): Promise<void>;
+    validate?(resource: TResource): Promise<boolean>;
+}
+interface PoolLease<TResource> {
+    readonly resource: TResource;
+    /** Returns the resource to the pool. Idempotent. */
+    release(): Promise<void>;
+    /** Permanently removes the resource from the pool. Idempotent. */
+    destroy(): Promise<void>;
+}
+
+declare class Pool<TResource> {
+    private readonly adapter;
+    private readonly options;
+    private destroyed;
+    private creating;
+    private leased;
+    private readonly idle;
+    private readonly waiters;
+    private reapTimer;
+    constructor(adapter: PoolAdapter<TResource>, options: PoolOptions);
+    /**
+     * Acquire a resource lease.
+     * The returned lease MUST be released or destroyed.
+     */
+    acquire(): Promise<PoolLease<TResource>>;
+    /** Destroy pool and all idle resources; waits for in-flight creations to settle. */
+    destroy(): Promise<void>;
+    private totalLive;
+    private makeLease;
+    private releaseResource;
+    private destroyResource;
+    private takeIdleValidated;
+    private reapIdle;
+    private warm;
+    private trimToMinMax;
+}
 
 interface PostgresClientLike {
     query(text: string, params?: unknown[]): Promise<{
@@ -3917,4 +4522,24 @@ 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 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 };
+interface PooledConnectionAdapter<TConn> {
+    query(conn: TConn, sql: string, params?: unknown[]): Promise<Array<Record<string, unknown>>>;
+    beginTransaction(conn: TConn): Promise<void>;
+    commitTransaction(conn: TConn): Promise<void>;
+    rollbackTransaction(conn: TConn): Promise<void>;
+}
+type PooledExecutorFactoryOptions<TConn> = {
+    pool: Pool<TConn>;
+    adapter: PooledConnectionAdapter<TConn>;
+};
+/**
+ * Creates a first-class DbExecutorFactory backed by MetalORM's Pool.
+ *
+ * Design goals:
+ * - No leaks by default: pool leases are always released in `finally`.
+ * - Correct transactions: one leased connection per transaction.
+ * - Session-friendly: createExecutor() supports transactions without permanently leasing a connection.
+ */
+declare function createPooledExecutorFactory<TConn>(opts: PooledExecutorFactoryOptions<TConn>): DbExecutorFactory;
+
+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 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 InExpressionRight, 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, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, 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 SelectQueryInput, 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, createPooledExecutorFactory, 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, inSubquery, 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, notInSubquery, 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 };