metal-orm 1.0.55 → 1.0.57

package/dist/index.d.cts

@@ -533,6 +533,25 @@ declare const SQL_OPERATORS: {
     /** NOT EXISTS operator */
     readonly NOT_EXISTS: "NOT EXISTS";
 };
+/**
+ * SQL bitwise operators
+ */
+declare const BITWISE_OPERATORS: {
+    /** Bitwise AND */
+    readonly AND: "&";
+    /** Bitwise OR */
+    readonly OR: "|";
+    /** Bitwise XOR */
+    readonly XOR: "^";
+    /** Bitwise Shift Left */
+    readonly SHIFT_LEFT: "<<";
+    /** Bitwise Shift Right */
+    readonly SHIFT_RIGHT: ">>";
+};
+/**
+ * Type representing supported bitwise operators
+ */
+type BitwiseOperator = (typeof BITWISE_OPERATORS)[keyof typeof BITWISE_OPERATORS];
 /**
  * Type representing any supported SQL operator
  */
@@ -705,6 +724,16 @@ interface CastExpressionNode {
     /** Optional alias for the result */
     alias?: string;
 }
+/**
+ * AST node representing a COLLATE expression (expression COLLATE collationName).
+ */
+interface CollateExpressionNode {
+    type: 'Collate';
+    /** Expression to be collated */
+    expression: OperandNode;
+    /** Collation name */
+    collation: string;
+}
 /**
  * AST node representing a window function
  */
@@ -733,11 +762,12 @@ interface ArithmeticExpressionNode {
 /**
  * Union type representing any operand that can be used in expressions
  */
-type OperandNode = AliasRefNode | ColumnNode | LiteralNode | FunctionNode | JsonPathNode | ScalarSubqueryNode | CaseExpressionNode | CastExpressionNode | WindowFunctionNode | ArithmeticExpressionNode;
+type OperandNode = AliasRefNode | ColumnNode | LiteralNode | FunctionNode | JsonPathNode | ScalarSubqueryNode | CaseExpressionNode | CastExpressionNode | WindowFunctionNode | ArithmeticExpressionNode | BitwiseExpressionNode | CollateExpressionNode;
 declare const isOperandNode: (node: unknown) => node is OperandNode;
 declare const isFunctionNode: (node: unknown) => node is FunctionNode;
 declare const isCaseExpressionNode: (node: unknown) => node is CaseExpressionNode;
 declare const isCastExpressionNode: (node: unknown) => node is CastExpressionNode;
+declare const isCollateExpressionNode: (node: unknown) => node is CollateExpressionNode;
 declare const isWindowFunctionNode: (node: unknown) => node is WindowFunctionNode;
 declare const isExpressionSelectionNode: (node: ColumnRef | FunctionNode | CaseExpressionNode | CastExpressionNode | WindowFunctionNode) => node is FunctionNode | CaseExpressionNode | CastExpressionNode | WindowFunctionNode;
 /**
@@ -754,6 +784,18 @@ interface BinaryExpressionNode {
     /** Optional escape character for LIKE expressions */
     escape?: LiteralNode;
 }
+/**
+ * AST node representing a bitwise expression (e.g., a & b)
+ */
+interface BitwiseExpressionNode {
+    type: 'BitwiseExpression';
+    /** Left operand */
+    left: OperandNode;
+    /** Bitwise operator */
+    operator: BitwiseOperator;
+    /** Right operand */
+    right: OperandNode;
+}
 /**
  * AST node representing a logical expression (AND/OR)
  */
@@ -813,7 +855,7 @@ interface BetweenExpressionNode {
 /**
  * Union type representing any supported expression node
  */
-type ExpressionNode = BinaryExpressionNode | LogicalExpressionNode | NullExpressionNode | InExpressionNode | ExistsExpressionNode | BetweenExpressionNode | ArithmeticExpressionNode;
+type ExpressionNode = BinaryExpressionNode | LogicalExpressionNode | NullExpressionNode | InExpressionNode | ExistsExpressionNode | BetweenExpressionNode | ArithmeticExpressionNode | BitwiseExpressionNode;
 
 type LiteralValue = LiteralNode['value'];
 type ValueOperandInput = OperandNode | LiteralValue;
@@ -956,6 +998,26 @@ declare const add: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRe
 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 bitwise AND expression (left & right)
+ */
+declare const bitAnd: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BitwiseExpressionNode;
+/**
+ * Creates a bitwise OR expression (left | right)
+ */
+declare const bitOr: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BitwiseExpressionNode;
+/**
+ * Creates a bitwise XOR expression (left ^ right)
+ */
+declare const bitXor: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BitwiseExpressionNode;
+/**
+ * Creates a bitwise shift left expression (left << right)
+ */
+declare const shiftLeft: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BitwiseExpressionNode;
+/**
+ * Creates a bitwise shift right expression (left >> right)
+ */
+declare const shiftRight: (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number) => BitwiseExpressionNode;
 /**
  * Creates a JSON path expression
  * @param col - Source column
@@ -989,6 +1051,13 @@ declare const exists: (subquery: SelectQueryNode) => ExistsExpressionNode;
  * @returns NOT EXISTS expression node
  */
 declare const notExists: (subquery: SelectQueryNode) => ExistsExpressionNode;
+/**
+ * Creates a COLLATE expression (expression COLLATE collationName)
+ * @param expression - Expression to be collated
+ * @param collation - Collation name
+ * @returns COLLATE expression node
+ */
+declare const collate: (expression: OperandNode | ColumnRef | string | number | boolean | null, collation: string) => CollateExpressionNode;
 
 /**
  * Creates a ROW_NUMBER window function
@@ -1099,6 +1168,18 @@ type GroupConcatOptions = {
  * Aggregates grouped strings into a single value.
  */
 declare const groupConcat: (col: ColumnRef | ColumnNode, options?: GroupConcatOptions) => FunctionNode;
+/**
+ * Creates a STDDEV function expression
+ * @param col - Column to calculate standard deviation for
+ * @returns Function node with STDDEV
+ */
+declare const stddev: (col: ColumnRef | ColumnNode) => FunctionNode;
+/**
+ * Creates a VARIANCE function expression
+ * @param col - Column to calculate variance for
+ * @returns Function node with VARIANCE
+ */
+declare const variance: (col: ColumnRef | ColumnNode) => FunctionNode;
 
 /**
  * Visitor for expression nodes
@@ -1111,6 +1192,7 @@ interface ExpressionVisitor<R> {
     visitExistsExpression?(node: ExistsExpressionNode): R;
     visitBetweenExpression?(node: BetweenExpressionNode): R;
     visitArithmeticExpression?(node: ArithmeticExpressionNode): R;
+    visitBitwiseExpression?(node: BitwiseExpressionNode): R;
     otherwise?(node: ExpressionNode): R;
 }
 /**
@@ -1125,6 +1207,7 @@ interface OperandVisitor<R> {
     visitCaseExpression?(node: CaseExpressionNode): R;
     visitCast?(node: CastExpressionNode): R;
     visitWindowFunction?(node: WindowFunctionNode): R;
+    visitCollate?(node: CollateExpressionNode): R;
     visitAliasRef?(node: AliasRefNode): R;
     otherwise?(node: OperandNode): R;
 }
@@ -1199,6 +1282,7 @@ interface TableNode {
  */
 interface FunctionTableNode {
     type: 'FunctionTable';
+    key?: string;
     /** Function name */
     name: string;
     /** Optional schema for the function (some dialects) */
@@ -1445,6 +1529,17 @@ interface FunctionStrategy {
     getRenderer(functionName: string): FunctionRenderer | undefined;
 }
 
+interface TableFunctionRenderContext {
+    node: FunctionTableNode;
+    compiledArgs: string[];
+    compileOperand: (operand: OperandNode) => string;
+    quoteIdentifier: (id: string) => string;
+}
+type TableFunctionRenderer = (ctx: TableFunctionRenderContext) => string;
+interface TableFunctionStrategy {
+    getRenderer(key: string): TableFunctionRenderer | undefined;
+}
+
 /**
  * Context for SQL compilation with parameter management
  */
@@ -1564,13 +1659,14 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
     private readonly expressionCompilers;
     private readonly operandCompilers;
     protected readonly functionStrategy: FunctionStrategy;
-    protected constructor(functionStrategy?: FunctionStrategy);
+    protected readonly tableFunctionStrategy: TableFunctionStrategy;
+    protected constructor(functionStrategy?: FunctionStrategy, tableFunctionStrategy?: TableFunctionStrategy);
     /**
      * Creates a new Dialect instance (for testing purposes)
      * @param functionStrategy - Optional function strategy
      * @returns New Dialect instance
      */
-    static create(functionStrategy?: FunctionStrategy): Dialect;
+    static create(functionStrategy?: FunctionStrategy, tableFunctionStrategy?: TableFunctionStrategy): Dialect;
     /**
      * Registers an expression compiler for a specific node type
      * @param type - Expression node type
@@ -2353,6 +2449,80 @@ type EntityOrTableTarget = EntityConstructor | TableDef;
  * Resolver for entity or table target, can be direct or function.
  */
 type EntityOrTableTargetResolver = EntityOrTableTarget | (() => EntityOrTableTarget);
+/**
+ * Simplified column definition structure used during metadata registration.
+ * @template T - Concrete column definition type being extended
+ */
+type ColumnDefLike<T extends ColumnDef = ColumnDef> = Omit<T, 'name' | 'table'>;
+/**
+ * Common properties shared by all relation metadata types.
+ */
+interface BaseRelationMetadata {
+    /** The property key for the relation */
+    propertyKey: string;
+    /** The target entity or table */
+    target: EntityOrTableTargetResolver;
+    /** Optional cascade mode */
+    cascade?: CascadeMode;
+}
+/**
+ * Metadata for has many relations.
+ */
+interface HasManyRelationMetadata extends BaseRelationMetadata {
+    /** The relation kind */
+    kind: typeof RelationKinds.HasMany;
+    /** The foreign key */
+    foreignKey: string;
+    /** Optional local key */
+    localKey?: string;
+}
+/**
+ * Metadata for has one relations.
+ */
+interface HasOneRelationMetadata extends BaseRelationMetadata {
+    /** The relation kind */
+    kind: typeof RelationKinds.HasOne;
+    /** The foreign key */
+    foreignKey: string;
+    /** Optional local key */
+    localKey?: string;
+}
+/**
+ * Metadata for belongs to relations.
+ */
+interface BelongsToRelationMetadata extends BaseRelationMetadata {
+    /** The relation kind */
+    kind: typeof RelationKinds.BelongsTo;
+    /** The foreign key */
+    foreignKey: string;
+    /** Optional local key */
+    localKey?: string;
+}
+/**
+ * Metadata for belongs to many relations.
+ */
+interface BelongsToManyRelationMetadata extends BaseRelationMetadata {
+    /** The relation kind */
+    kind: typeof RelationKinds.BelongsToMany;
+    /** The pivot table */
+    pivotTable: EntityOrTableTargetResolver;
+    /** The pivot foreign key to root */
+    pivotForeignKeyToRoot: string;
+    /** The pivot foreign key to target */
+    pivotForeignKeyToTarget: string;
+    /** Optional local key */
+    localKey?: string;
+    /** Optional target key */
+    targetKey?: string;
+    /** Optional pivot primary key */
+    pivotPrimaryKey?: string;
+    /** Optional default pivot columns */
+    defaultPivotColumns?: string[];
+}
+/**
+ * Union type for all relation metadata.
+ */
+type RelationMetadata = HasManyRelationMetadata | HasOneRelationMetadata | BelongsToRelationMetadata | BelongsToManyRelationMetadata;
 
 /**
  * Entity status enum representing the lifecycle state of an entity
@@ -2472,6 +2642,10 @@ interface QueryContext {
     params: unknown[];
 }
 type QueryInterceptor = (ctx: QueryContext, next: () => Promise<QueryResult[]>) => Promise<QueryResult[]>;
+/**
+ * Pipeline for query interceptors.
+ * Interceptors can wrap query execution to add logging, tracing, caching, etc.
+ */
 declare class InterceptorPipeline {
     private interceptors;
     use(interceptor: QueryInterceptor): void;
@@ -2547,12 +2721,31 @@ declare class Orm<E extends DomainEvent = OrmDomainEvent> {
     dispose(): Promise<void>;
 }
 
+/**
+ * Simple identity map for tracking entities within a session.
+ * Ensures that the same database record is represented by a single entity instance.
+ */
 declare class IdentityMap {
     private readonly buckets;
     get bucketsMap(): Map<string, Map<string, TrackedEntity>>;
+    /**
+     * Retrieves an entity from the identity map if it exists.
+     * @param table The table definition of the entity.
+     * @param pk The primary key value.
+     * @returns The entity instance if found, undefined otherwise.
+     */
     getEntity(table: TableDef, pk: string | number): unknown | undefined;
+    /**
+     * Registers a tracked entity in the identity map.
+     * @param tracked The tracked entity metadata and instance.
+     */
     register(tracked: TrackedEntity): void;
     remove(tracked: TrackedEntity): void;
+    /**
+     * Returns all tracked entities for a specific table.
+     * @param table The table definition.
+     * @returns Array of tracked entities.
+     */
     getEntitiesForTable(table: TableDef): TrackedEntity[];
     clear(): void;
     private toIdentityKey;
@@ -2980,11 +3173,21 @@ interface EntityContext {
     registerRelationChange(root: unknown, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<unknown>): void;
 }
 
+/**
+ * Context used during the hydration of entities from database results.
+ * It carries necessary services and processors to handle identity management,
+ * unit of work registration, and relation changes.
+ */
 interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
+    /** The identity map used to track and reuse entity instances. */
     identityMap: IdentityMap;
+    /** The unit of work used to track changes in hydrated entities. */
     unitOfWork: UnitOfWork;
+    /** The bus used to dispatch domain events during or after hydration. */
     domainEvents: DomainEventBus<E, OrmSession<E>>;
+    /** Processor for handling changes in entity relations during hydration. */
     relationChanges: RelationChangeProcessor;
+    /** Context providing access to entity-specific metadata and services. */
     entityContext: EntityContext;
 }
 
@@ -3215,7 +3418,7 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
      */
     remove(entity: object): Promise<void>;
     /**
-     * Flushes pending changes to the database.
+     * Flushes pending changes to the database without session hooks, relation processing, or domain events.
      */
     flush(): Promise<void>;
     /**
@@ -4062,6 +4265,11 @@ interface ReturningStrategy {
     formatReturningColumns(returning: ColumnNode[], quoteIdentifier: (id: string) => string): string;
 }
 
+/**
+ * Base class for SQL dialects.
+ * Provides a common framework for compiling AST nodes into SQL strings.
+ * Specific dialects should extend this class and implement dialect-specific logic.
+ */
 declare abstract class SqlDialectBase extends Dialect {
     abstract quoteIdentifier(id: string): string;
     protected paginationStrategy: PaginationStrategy;
@@ -4431,75 +4639,75 @@ declare const registerSchemaIntrospector: (dialect: DialectName, introspector: S
  */
 declare const getSchemaIntrospector: (dialect: DialectName) => SchemaIntrospector | undefined;
 
-type OperandInput$2 = OperandNode | ColumnDef | string | number | boolean | null;
+type OperandInput$5 = OperandNode | ColumnDef | string | number | boolean | null;
 /**
  * Converts a string to lowercase.
  * @param value - The string value.
  * @returns A FunctionNode representing the LOWER SQL function.
  */
-declare const lower: (value: OperandInput$2) => FunctionNode;
+declare const lower: (value: OperandInput$5) => FunctionNode;
 /**
  * Converts a string to uppercase.
  * @param value - The string value.
  * @returns A FunctionNode representing the UPPER SQL function.
  */
-declare const upper: (value: OperandInput$2) => FunctionNode;
+declare const upper: (value: OperandInput$5) => FunctionNode;
 /**
  * Returns the ASCII code of the first character of a string.
  * @param value - The string value.
  * @returns A FunctionNode representing the ASCII SQL function.
  */
-declare const ascii: (value: OperandInput$2) => FunctionNode;
+declare const ascii: (value: OperandInput$5) => FunctionNode;
 /**
  * Returns a string from one or more ASCII codes.
  * @param codes - The ASCII codes.
  * @returns A FunctionNode representing the CHAR SQL function.
  */
-declare const char: (...codes: OperandInput$2[]) => FunctionNode;
+declare const char: (...codes: OperandInput$5[]) => FunctionNode;
 /**
  * Returns the number of characters in a string.
  * @param value - The string value.
  * @returns A FunctionNode representing the CHAR_LENGTH SQL function.
  */
-declare const charLength: (value: OperandInput$2) => FunctionNode;
+declare const charLength: (value: OperandInput$5) => FunctionNode;
 /**
  * Returns the length of a string in bytes or characters.
  * @param value - The string value.
  * @returns A FunctionNode representing the LENGTH SQL function.
  */
-declare const length: (value: OperandInput$2) => FunctionNode;
+declare const length: (value: OperandInput$5) => FunctionNode;
 /**
  * Removes leading and trailing whitespace or specified characters from a string.
  * @param value - The string value.
  * @param chars - The characters to trim (optional).
  * @returns A FunctionNode representing the TRIM SQL function.
  */
-declare const trim: (value: OperandInput$2, chars?: OperandInput$2) => FunctionNode;
+declare const trim: (value: OperandInput$5, chars?: OperandInput$5) => FunctionNode;
 /**
  * Removes leading whitespace from a string.
  * @param value - The string value.
  * @returns A FunctionNode representing the LTRIM SQL function.
  */
-declare const ltrim: (value: OperandInput$2) => FunctionNode;
+declare const ltrim: (value: OperandInput$5) => FunctionNode;
 /**
  * Removes trailing whitespace from a string.
  * @param value - The string value.
  * @returns A FunctionNode representing the RTRIM SQL function.
  */
-declare const rtrim: (value: OperandInput$2) => FunctionNode;
+declare const rtrim: (value: OperandInput$5) => FunctionNode;
 /**
  * Concatenates two or more strings.
  * @param args - The strings to concatenate.
  * @returns A FunctionNode representing the CONCAT SQL function.
  */
-declare const concat: (...args: OperandInput$2[]) => FunctionNode;
+declare const concat: (...args: OperandInput$5[]) => FunctionNode;
 /**
  * Concatenates strings with a separator.
  * @param separator - The separator string.
  * @param args - The strings to concatenate.
  * @returns A FunctionNode representing the CONCAT_WS SQL function.
  */
-declare const concatWs: (separator: OperandInput$2, ...args: OperandInput$2[]) => FunctionNode;
+declare const concatWs: (separator: OperandInput$5, ...args: OperandInput$5[]) => FunctionNode;
 /**
  * Extracts a substring from a string.
  * @param value - The string value.
@@ -4507,35 +4715,35 @@ declare const concatWs: (separator: OperandInput$2, ...args: OperandInput$2[]) =
  * @param length - The length of the substring (optional).
  * @returns A FunctionNode representing the SUBSTR SQL function.
  */
-declare const substr: (value: OperandInput$2, start: OperandInput$2, length?: OperandInput$2) => FunctionNode;
+declare const substr: (value: OperandInput$5, start: OperandInput$5, length?: OperandInput$5) => FunctionNode;
 /**
  * Returns the leftmost characters of a string.
  * @param value - The string value.
  * @param len - The number of characters to return.
  * @returns A FunctionNode representing the LEFT SQL function.
  */
-declare const left: (value: OperandInput$2, len: OperandInput$2) => FunctionNode;
+declare const left: (value: OperandInput$5, len: OperandInput$5) => FunctionNode;
 /**
  * Returns the rightmost characters of a string.
  * @param value - The string value.
  * @param len - The number of characters to return.
  * @returns A FunctionNode representing the RIGHT SQL function.
  */
-declare const right: (value: OperandInput$2, len: OperandInput$2) => FunctionNode;
+declare const right: (value: OperandInput$5, len: OperandInput$5) => FunctionNode;
 /**
  * Returns the position of a substring in a string.
  * @param substring - The substring to search for.
  * @param value - The string to search in.
  * @returns A FunctionNode representing the POSITION SQL function.
  */
-declare const position: (substring: OperandInput$2, value: OperandInput$2) => FunctionNode;
+declare const position: (substring: OperandInput$5, value: OperandInput$5) => FunctionNode;
 /**
  * Returns the position of a substring in a string.
  * @param value - The string to search in.
  * @param substring - The substring to search for.
  * @returns A FunctionNode representing the INSTR SQL function.
  */
-declare const instr: (value: OperandInput$2, substring: OperandInput$2) => FunctionNode;
+declare const instr: (value: OperandInput$5, substring: OperandInput$5) => FunctionNode;
 /**
  * Returns the position of a substring in a string, optionally starting from a position.
  * @param substring - The substring to search for.
@@ -4543,7 +4751,7 @@ declare const instr: (value: OperandInput$2, substring: OperandInput$2) => Funct
  * @param start - The starting position (optional).
  * @returns A FunctionNode representing the LOCATE SQL function.
  */
-declare const locate: (substring: OperandInput$2, value: OperandInput$2, start?: OperandInput$2) => FunctionNode;
+declare const locate: (substring: OperandInput$5, value: OperandInput$5, start?: OperandInput$5) => FunctionNode;
 /**
  * Replaces occurrences of a substring in a string.
  * @param value - The string to search in.
@@ -4551,14 +4759,14 @@ declare const locate: (substring: OperandInput$2, value: OperandInput$2, start?:
  * @param replacement - The replacement string.
  * @returns A FunctionNode representing the REPLACE SQL function.
  */
-declare const replace: (value: OperandInput$2, search: OperandInput$2, replacement: OperandInput$2) => FunctionNode;
+declare const replace: (value: OperandInput$5, search: OperandInput$5, replacement: OperandInput$5) => FunctionNode;
 /**
  * Repeats a string a specified number of times.
  * @param value - The string to repeat.
  * @param count - The number of times to repeat.
  * @returns A FunctionNode representing the REPEAT SQL function.
  */
-declare const repeat: (value: OperandInput$2, count: OperandInput$2) => FunctionNode;
+declare const repeat: (value: OperandInput$5, count: OperandInput$5) => FunctionNode;
 /**
  * Left-pads a string to a certain length with another string.
  * @param value - The string to pad.
@@ -4566,7 +4774,7 @@ declare const repeat: (value: OperandInput$2, count: OperandInput$2) => Function
  * @param pad - The padding string.
  * @returns A FunctionNode representing the LPAD SQL function.
  */
-declare const lpad: (value: OperandInput$2, len: OperandInput$2, pad: OperandInput$2) => FunctionNode;
+declare const lpad: (value: OperandInput$5, len: OperandInput$5, pad: OperandInput$5) => FunctionNode;
 /**
  * Right-pads a string to a certain length with another string.
  * @param value - The string to pad.
@@ -4574,120 +4782,169 @@ declare const lpad: (value: OperandInput$2, len: OperandInput$2, pad: OperandInp
  * @param pad - The padding string.
  * @returns A FunctionNode representing the RPAD SQL function.
  */
-declare const rpad: (value: OperandInput$2, len: OperandInput$2, pad: OperandInput$2) => FunctionNode;
+declare const rpad: (value: OperandInput$5, len: OperandInput$5, pad: OperandInput$5) => FunctionNode;
 /**
  * Returns a string consisting of a specified number of spaces.
  * @param count - The number of spaces.
  * @returns A FunctionNode representing the SPACE SQL function.
  */
-declare const space: (count: OperandInput$2) => FunctionNode;
+declare const space: (count: OperandInput$5) => FunctionNode;
+/**
+ * Reverses a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the REVERSE SQL function.
+ */
+declare const reverse: (value: OperandInput$5) => FunctionNode;
+/**
+ * Capitalizes the first letter of each word in a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the INITCAP SQL function.
+ */
+declare const initcap: (value: OperandInput$5) => FunctionNode;
+/**
+ * Returns the MD5 hash of a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the MD5 SQL function.
+ */
+declare const md5: (value: OperandInput$5) => FunctionNode;
+/**
+ * Returns the SHA-1 hash of a string.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the SHA1 SQL function.
+ */
+declare const sha1: (value: OperandInput$5) => FunctionNode;
+/**
+ * Returns the SHA-2 hash of a string with a specified bit length.
+ * @param value - The string value.
+ * @param bits - The bit length (e.g., 224, 256, 384, 512).
+ * @returns A FunctionNode representing the SHA2 SQL function.
+ */
+declare const sha2: (value: OperandInput$5, bits: OperandInput$5) => FunctionNode;
+/**
+ * Returns the length of a string in bits.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the BIT_LENGTH SQL function.
+ */
+declare const bitLength: (value: OperandInput$5) => FunctionNode;
+/**
+ * Returns the length of a string in bytes.
+ * @param value - The string value.
+ * @returns A FunctionNode representing the OCTET_LENGTH SQL function.
+ */
+declare const octetLength: (value: OperandInput$5) => FunctionNode;
+/**
+ * Returns a string from an ASCII code.
+ * @param code - The ASCII code.
+ * @returns A FunctionNode representing the CHR/CHAR SQL function.
+ */
+declare const chr: (code: OperandInput$5) => FunctionNode;
 
-type OperandInput$1 = OperandNode | ColumnDef | string | number | boolean | null;
+type OperandInput$4 = OperandNode | ColumnDef | string | number | boolean | null;
 /**
  * Returns the absolute value of a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the ABS SQL function.
  */
-declare const abs: (value: OperandInput$1) => FunctionNode;
+declare const abs: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the arccosine (inverse cosine) of a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the ACOS SQL function.
  */
-declare const acos: (value: OperandInput$1) => FunctionNode;
+declare const acos: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the arcsine (inverse sine) of a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the ASIN SQL function.
  */
-declare const asin: (value: OperandInput$1) => FunctionNode;
+declare const asin: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the arctangent (inverse tangent) of a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the ATAN SQL function.
  */
-declare const atan: (value: OperandInput$1) => FunctionNode;
+declare const atan: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the arctangent of the two arguments.
  * @param y - The y-coordinate.
  * @param x - The x-coordinate.
  * @returns A FunctionNode representing the ATAN2 SQL function.
  */
-declare const atan2: (y: OperandInput$1, x: OperandInput$1) => FunctionNode;
+declare const atan2: (y: OperandInput$4, x: OperandInput$4) => FunctionNode;
 /**
  * Returns the smallest integer greater than or equal to a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the CEIL SQL function.
  */
-declare const ceil: (value: OperandInput$1) => FunctionNode;
+declare const ceil: (value: OperandInput$4) => FunctionNode;
 /**
  * Alias for ceil. Returns the smallest integer greater than or equal to a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the CEILING SQL function.
  */
-declare const ceiling: (value: OperandInput$1) => FunctionNode;
+declare const ceiling: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the cosine of a number (in radians).
  * @param value - The numeric value in radians.
  * @returns A FunctionNode representing the COS SQL function.
  */
-declare const cos: (value: OperandInput$1) => FunctionNode;
+declare const cos: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the cotangent of a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the COT SQL function.
  */
-declare const cot: (value: OperandInput$1) => FunctionNode;
+declare const cot: (value: OperandInput$4) => FunctionNode;
 /**
  * Converts radians to degrees.
  * @param value - The angle in radians.
  * @returns A FunctionNode representing the DEGREES SQL function.
  */
-declare const degrees: (value: OperandInput$1) => FunctionNode;
+declare const degrees: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns e raised to the power of the argument.
  * @param value - The exponent.
  * @returns A FunctionNode representing the EXP SQL function.
  */
-declare const exp: (value: OperandInput$1) => FunctionNode;
+declare const exp: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the largest integer less than or equal to a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the FLOOR SQL function.
  */
-declare const floor: (value: OperandInput$1) => FunctionNode;
+declare const floor: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the natural logarithm (base e) of a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the LN SQL function.
  */
-declare const ln: (value: OperandInput$1) => FunctionNode;
+declare const ln: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the base-10 logarithm of a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the LOG SQL function.
  */
-declare const log: (value: OperandInput$1) => FunctionNode;
+declare const log: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the base-10 logarithm of a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the LOG10 SQL function.
  */
-declare const log10: (value: OperandInput$1) => FunctionNode;
+declare const log10: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the logarithm of a number for a specific base.
  * @param base - The base of the logarithm.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the LOG_BASE SQL function.
  */
-declare const logBase: (base: OperandInput$1, value: OperandInput$1) => FunctionNode;
+declare const logBase: (base: OperandInput$4, value: OperandInput$4) => FunctionNode;
 /**
  * Returns the remainder of dividing x by y.
  * @param x - The dividend.
  * @param y - The divisor.
  * @returns A FunctionNode representing the MOD SQL function.
  */
-declare const mod: (x: OperandInput$1, y: OperandInput$1) => FunctionNode;
+declare const mod: (x: OperandInput$4, y: OperandInput$4) => FunctionNode;
 /**
  * Returns the value of PI (approximately 3.14159...).
  * @returns A FunctionNode representing the PI SQL function.
@@ -4699,20 +4956,20 @@ declare const pi: () => FunctionNode;
  * @param y - The exponent.
  * @returns A FunctionNode representing the POWER SQL function.
  */
-declare const power: (x: OperandInput$1, y: OperandInput$1) => FunctionNode;
+declare const power: (x: OperandInput$4, y: OperandInput$4) => FunctionNode;
 /**
  * Alias for power. Returns x raised to the power of y.
  * @param x - The base.
  * @param y - The exponent.
  * @returns A FunctionNode representing the POW SQL function.
  */
-declare const pow: (x: OperandInput$1, y: OperandInput$1) => FunctionNode;
+declare const pow: (x: OperandInput$4, y: OperandInput$4) => FunctionNode;
 /**
  * Converts degrees to radians.
  * @param value - The angle in degrees.
  * @returns A FunctionNode representing the RADIANS SQL function.
  */
-declare const radians: (value: OperandInput$1) => FunctionNode;
+declare const radians: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns a random number between 0 and 1.
  * @returns A FunctionNode representing the RANDOM SQL function.
@@ -4729,47 +4986,59 @@ declare const rand: () => FunctionNode;
  * @param decimals - The number of decimal places (optional).
  * @returns A FunctionNode representing the ROUND SQL function.
  */
-declare const round: (value: OperandInput$1, decimals?: OperandInput$1) => FunctionNode;
+declare const round: (value: OperandInput$4, decimals?: OperandInput$4) => FunctionNode;
 /**
  * Returns the sign of a number (-1 for negative, 0 for zero, 1 for positive).
  * @param value - The numeric value.
  * @returns A FunctionNode representing the SIGN SQL function.
  */
-declare const sign: (value: OperandInput$1) => FunctionNode;
+declare const sign: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the sine of a number (in radians).
  * @param value - The numeric value in radians.
  * @returns A FunctionNode representing the SIN SQL function.
  */
-declare const sin: (value: OperandInput$1) => FunctionNode;
+declare const sin: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the square root of a number.
  * @param value - The numeric value.
  * @returns A FunctionNode representing the SQRT SQL function.
  */
-declare const sqrt: (value: OperandInput$1) => FunctionNode;
+declare const sqrt: (value: OperandInput$4) => FunctionNode;
 /**
  * Returns the tangent of a number (in radians).
  * @param value - The numeric value in radians.
  * @returns A FunctionNode representing the TAN SQL function.
  */
-declare const tan: (value: OperandInput$1) => FunctionNode;
+declare const tan: (value: OperandInput$4) => FunctionNode;
 /**
  * Truncates a number to a specified number of decimal places without rounding.
  * @param value - The numeric value to truncate.
  * @param decimals - The number of decimal places (optional).
  * @returns A FunctionNode representing the TRUNC SQL function.
  */
-declare const trunc: (value: OperandInput$1, decimals?: OperandInput$1) => FunctionNode;
+declare const trunc: (value: OperandInput$4, decimals?: OperandInput$4) => FunctionNode;
 /**
  * Alias for trunc. Truncates a number to a specified number of decimal places without rounding.
  * @param value - The numeric value to truncate.
  * @param decimals - The number of decimal places.
  * @returns A FunctionNode representing the TRUNCATE SQL function.
  */
-declare const truncate: (value: OperandInput$1, decimals: OperandInput$1) => FunctionNode;
+declare const truncate: (value: OperandInput$4, decimals: OperandInput$4) => FunctionNode;
+/**
+ * Returns the base-2 logarithm of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the LOG2 SQL function.
+ */
+declare const log2: (value: OperandInput$4) => FunctionNode;
+/**
+ * Returns the cube root of a number.
+ * @param value - The numeric value.
+ * @returns A FunctionNode representing the CBRT SQL function.
+ */
+declare const cbrt: (value: OperandInput$4) => FunctionNode;
 
-type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
+type OperandInput$3 = OperandNode | ColumnDef | string | number | boolean | null;
 /**
  * Returns the current local date and time.
  * @returns A FunctionNode representing the NOW() SQL function.
@@ -4790,31 +5059,41 @@ declare const currentTime: () => FunctionNode;
  * @returns A FunctionNode representing the UTC_NOW() SQL function.
  */
 declare const utcNow: () => FunctionNode;
+/**
+ * Returns the current local time.
+ * @returns A FunctionNode representing the LOCALTIME SQL function.
+ */
+declare const localTime: () => FunctionNode;
+/**
+ * Returns the current local timestamp.
+ * @returns A FunctionNode representing the LOCALTIMESTAMP SQL function.
+ */
+declare const localTimestamp: () => FunctionNode;
 /**
  * Extracts a specified part from a date or datetime value.
  * @param part - The date part to extract (e.g., 'YEAR', 'MONTH', 'DAY', 'HOUR', 'MINUTE', 'SECOND').
  * @param date - The date or datetime value to extract from.
  * @returns A FunctionNode representing the EXTRACT SQL function.
  */
-declare const extract: (part: OperandInput, date: OperandInput) => FunctionNode;
+declare const extract: (part: OperandInput$3, date: OperandInput$3) => FunctionNode;
 /**
  * Extracts the year from a date or datetime value.
  * @param date - The date or datetime value.
  * @returns A FunctionNode representing the YEAR SQL function.
  */
-declare const year: (date: OperandInput) => FunctionNode;
+declare const year: (date: OperandInput$3) => FunctionNode;
 /**
  * Extracts the month from a date or datetime value.
  * @param date - The date or datetime value.
  * @returns A FunctionNode representing the MONTH SQL function.
  */
-declare const month: (date: OperandInput) => FunctionNode;
+declare const month: (date: OperandInput$3) => FunctionNode;
 /**
  * Extracts the day of the month from a date or datetime value.
  * @param date - The date or datetime value.
  * @returns A FunctionNode representing the DAY SQL function.
  */
-declare const day: (date: OperandInput) => FunctionNode;
+declare const day: (date: OperandInput$3) => FunctionNode;
 /**
  * Adds a specified time interval to a date or datetime value.
  * @param date - The date or datetime value to add to.
@@ -4822,7 +5101,7 @@ declare const day: (date: OperandInput) => FunctionNode;
  * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND').
  * @returns A FunctionNode representing the DATE_ADD SQL function.
  */
-declare const dateAdd: (date: OperandInput, interval: OperandInput, unit: OperandInput) => FunctionNode;
+declare const dateAdd: (date: OperandInput$3, interval: OperandInput$3, unit: OperandInput$3) => FunctionNode;
 /**
  * Subtracts a specified time interval from a date or datetime value.
  * @param date - The date or datetime value to subtract from.
@@ -4830,21 +5109,21 @@ declare const dateAdd: (date: OperandInput, interval: OperandInput, unit: Operan
  * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND').
  * @returns A FunctionNode representing the DATE_SUB SQL function.
  */
-declare const dateSub: (date: OperandInput, interval: OperandInput, unit: OperandInput) => FunctionNode;
+declare const dateSub: (date: OperandInput$3, interval: OperandInput$3, unit: OperandInput$3) => FunctionNode;
 /**
  * Returns the difference between two dates in days.
  * @param date1 - The end date.
  * @param date2 - The start date.
  * @returns A FunctionNode representing the DATE_DIFF SQL function.
  */
-declare const dateDiff: (date1: OperandInput, date2: OperandInput) => FunctionNode;
+declare const dateDiff: (date1: OperandInput$3, date2: OperandInput$3) => FunctionNode;
 /**
  * Converts a date or datetime value to a formatted string.
  * @param date - The date or datetime value to format.
  * @param format - The format string (dialect-specific).
  * @returns A FunctionNode representing the DATE_FORMAT SQL function.
  */
-declare const dateFormat: (date: OperandInput, format: OperandInput) => FunctionNode;
+declare const dateFormat: (date: OperandInput$3, format: OperandInput$3) => FunctionNode;
 /**
  * Returns the current Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).
  * @returns A FunctionNode representing the UNIX_TIMESTAMP SQL function.
@@ -4855,32 +5134,106 @@ declare const unixTimestamp: () => FunctionNode;
  * @param timestamp - Unix timestamp in seconds.
  * @returns A FunctionNode representing the FROM_UNIXTIME SQL function.
  */
-declare const fromUnixTime: (timestamp: OperandInput) => FunctionNode;
+declare const fromUnixTime: (timestamp: OperandInput$3) => FunctionNode;
 /**
  * Returns the last day of the month for a given date.
  * @param date - The date value.
  * @returns A FunctionNode representing the END_OF_MONTH SQL function.
  */
-declare const endOfMonth: (date: OperandInput) => FunctionNode;
+declare const endOfMonth: (date: OperandInput$3) => FunctionNode;
 /**
  * Returns the index of the weekday for a given date (1 = Sunday, 2 = Monday, etc.).
  * @param date - The date value.
  * @returns A FunctionNode representing the DAY_OF_WEEK SQL function.
  */
-declare const dayOfWeek: (date: OperandInput) => FunctionNode;
+declare const dayOfWeek: (date: OperandInput$3) => FunctionNode;
 /**
  * Returns the week number of the year for a given date.
  * @param date - The date value.
  * @returns A FunctionNode representing the WEEK_OF_YEAR SQL function.
  */
-declare const weekOfYear: (date: OperandInput) => FunctionNode;
+declare const weekOfYear: (date: OperandInput$3) => FunctionNode;
 /**
  * Truncates a date or datetime value to a specified precision (e.g., first day of the month/year).
  * @param part - The truncation precision (e.g., 'YEAR', 'MONTH', 'DAY').
  * @param date - The date or datetime value to truncate.
  * @returns A FunctionNode representing the DATE_TRUNC SQL function.
  */
-declare const dateTrunc: (part: OperandInput, date: OperandInput) => FunctionNode;
+declare const dateTrunc: (part: OperandInput$3, date: OperandInput$3) => FunctionNode;
+/**
+ * Returns the difference between two timestamps as an interval.
+ * @param timestamp - The end timestamp.
+ * @param baseTimestamp - The start timestamp (optional, defaults to current time).
+ * @returns A FunctionNode representing the AGE SQL function.
+ */
+declare const age: (timestamp: OperandInput$3, baseTimestamp?: OperandInput$3) => FunctionNode;
+/**
+ * Extracts the hour from a date or datetime value.
+ * @param date - The date or datetime value.
+ * @returns A FunctionNode representing the HOUR SQL function.
+ */
+declare const hour: (date: OperandInput$3) => FunctionNode;
+/**
+ * Extracts the minute from a date or datetime value.
+ * @param date - The date or datetime value.
+ * @returns A FunctionNode representing the MINUTE SQL function.
+ */
+declare const minute: (date: OperandInput$3) => FunctionNode;
+/**
+ * Extracts the second from a date or datetime value.
+ * @param date - The date or datetime value.
+ * @returns A FunctionNode representing the SECOND SQL function.
+ */
+declare const second: (date: OperandInput$3) => FunctionNode;
+/**
+ * Extracts the quarter from a date or datetime value (1-4).
+ * @param date - The date or datetime value.
+ * @returns A FunctionNode representing the QUARTER SQL function.
+ */
+declare const quarter: (date: OperandInput$3) => FunctionNode;
+
+type OperandInput$2 = OperandNode | ColumnDef | string | number | boolean | null;
+/**
+ * Returns the first non-null value in a list.
+ * @param args - The list of values to check.
+ * @returns A FunctionNode representing the COALESCE SQL function.
+ */
+declare const coalesce: (...args: OperandInput$2[]) => FunctionNode;
+/**
+ * Returns null if the two arguments are equal, otherwise returns the first argument.
+ * @param val1 - The first value.
+ * @param val2 - The second value.
+ * @returns A FunctionNode representing the NULLIF SQL function.
+ */
+declare const nullif: (val1: OperandInput$2, val2: OperandInput$2) => FunctionNode;
+/**
+ * Returns the largest value in a list.
+ * @param args - The list of values to compare.
+ * @returns A FunctionNode representing the GREATEST SQL function.
+ */
+declare const greatest: (...args: OperandInput$2[]) => FunctionNode;
+/**
+ * Returns the smallest value in a list.
+ * @param args - The list of values to compare.
+ * @returns A FunctionNode representing the LEAST SQL function.
+ */
+declare const least: (...args: OperandInput$2[]) => FunctionNode;
+/**
+ * Returns the first argument if it is not null, otherwise returns the second argument.
+ * @param val - The value to check.
+ * @param defaultValue - The default value to return if val is null.
+ * @returns A FunctionNode representing the COALESCE SQL function.
+ */
+declare const ifNull: (val: OperandInput$2, defaultValue: OperandInput$2) => FunctionNode;
+
+type OperandInput$1 = OperandNode | ColumnDef | string | number | boolean | null;
+declare const jsonLength: (target: OperandInput$1, path?: OperandInput$1) => FunctionNode;
+declare const jsonSet: (target: OperandInput$1, path: OperandInput$1, value: OperandInput$1) => FunctionNode;
+declare const jsonArrayAgg: (value: OperandInput$1) => FunctionNode;
+declare const jsonContains: (target: OperandInput$1, candidate: OperandInput$1, path?: OperandInput$1) => FunctionNode;
+
+type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
+declare const arrayAppend: (array: OperandInput, value: OperandInput) => FunctionNode;
 
 /**
  * Browser-compatible implementation of AsyncLocalStorage.
@@ -4988,6 +5341,7 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
     visitCaseExpression(node: CaseExpressionNode): string;
     visitWindowFunction(node: WindowFunctionNode): string;
     visitCast(node: CastExpressionNode): string;
+    visitCollate(node: CollateExpressionNode): string;
     visitAliasRef(node: AliasRefNode): string;
     /**
      * Prints a binary expression to TypeScript code
@@ -5069,6 +5423,7 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
      */
     private printWindowFunctionOperand;
     private printCastOperand;
+    private printCollateOperand;
     /**
      * Converts method chain lines to inline format
      * @param lines - Method chain lines
@@ -5238,6 +5593,12 @@ declare class DefaultHasManyCollection<TChild> implements HasManyCollection<TChi
 }
 
 type Rows$1 = Record<string, unknown>;
+/**
+ * Default implementation of a belongs-to reference.
+ * Manages a reference to a parent entity from a child entity through a foreign key.
+ *
+ * @template TParent The type of the parent entity.
+ */
 declare class DefaultBelongsToReference<TParent> implements BelongsToReference<TParent> {
     private readonly ctx;
     private readonly meta;
@@ -5250,6 +5611,17 @@ declare class DefaultBelongsToReference<TParent> implements BelongsToReference<T
     private readonly targetKey;
     private loaded;
     private current;
+    /**
+     * @param ctx The entity context for tracking changes.
+     * @param meta Metadata for the child entity.
+     * @param root The child entity instance (carrying the foreign key).
+     * @param relationName The name of the relation.
+     * @param relation Relation definition.
+     * @param rootTable Table definition of the child entity.
+     * @param loader Function to load the parent entity.
+     * @param createEntity Function to create entity instances from rows.
+     * @param targetKey The primary key of the target (parent) table.
+     */
     constructor(ctx: EntityContext, meta: EntityMeta<TableDef>, root: unknown, relationName: string, relation: BelongsToRelation, rootTable: TableDef, loader: () => Promise<Map<string, Rows$1>>, createEntity: (row: Record<string, unknown>) => TParent, targetKey: string);
     load(): Promise<TParent | null>;
     get(): TParent | null;
@@ -5260,6 +5632,13 @@ declare class DefaultBelongsToReference<TParent> implements BelongsToReference<T
 }
 
 type Rows = Record<string, unknown>[];
+/**
+ * Default implementation of a many-to-many collection.
+ * Manages the relationship between two entities through a pivot table.
+ * Supports lazy loading, attaching/detaching entities, and syncing by IDs.
+ *
+ * @template TTarget The type of the target entities in the collection.
+ */
 declare class DefaultManyToManyCollection<TTarget> implements ManyToManyCollection<TTarget> {
     private readonly ctx;
     private readonly meta;
@@ -5272,11 +5651,45 @@ declare class DefaultManyToManyCollection<TTarget> implements ManyToManyCollecti
     private readonly localKey;
     private loaded;
     private items;
+    /**
+     * @param ctx The entity context for tracking changes.
+     * @param meta Metadata for the root entity.
+     * @param root The root entity instance.
+     * @param relationName The name of the relation.
+     * @param relation Relation definition.
+     * @param rootTable Table definition of the root entity.
+     * @param loader Function to load the collection items.
+     * @param createEntity Function to create entity instances from rows.
+     * @param localKey The local key used for joining.
+     */
     constructor(ctx: EntityContext, meta: EntityMeta<TableDef>, root: unknown, relationName: string, relation: BelongsToManyRelation, rootTable: TableDef, loader: () => Promise<Map<string, Rows>>, createEntity: (row: Record<string, unknown>) => TTarget, localKey: string);
+    /**
+     * Loads the collection items if not already loaded.
+     * @returns A promise that resolves to the array of target entities.
+     */
     load(): Promise<TTarget[]>;
+    /**
+     * Returns the currently loaded items.
+     * @returns Array of target entities.
+     */
     getItems(): TTarget[];
+    /**
+     * Attaches an entity to the collection.
+     * Registers an 'attach' change in the entity context.
+     * @param target Entity instance or its primary key value.
+     */
     attach(target: TTarget | number | string): void;
+    /**
+     * Detaches an entity from the collection.
+     * Registers a 'detach' change in the entity context.
+     * @param target Entity instance or its primary key value.
+     */
     detach(target: TTarget | number | string): void;
+    /**
+     * Syncs the collection with a list of IDs.
+     * Attaches missing IDs and detaches IDs not in the list.
+     * @param ids Array of primary key values to sync with.
+     */
     syncByIds(ids: (number | string)[]): Promise<void>;
     private ensureEntity;
     private extractId;
@@ -5343,6 +5756,26 @@ interface DualModeClassDecorator {
     <TFunction extends Function>(value: TFunction): void | TFunction;
     <TFunction extends Function>(value: TFunction, context: StandardDecoratorContext): void | TFunction;
 }
+/**
+ * Bag for storing decorator metadata during the decoration phase.
+ */
+interface DecoratorMetadataBag {
+    columns: Array<{
+        propertyName: string;
+        column: ColumnDefLike;
+    }>;
+    relations: Array<{
+        propertyName: string;
+        relation: RelationMetadata;
+    }>;
+}
+/**
+ * Public helper to read decorator metadata from a class constructor.
+ * Standard decorators only; legacy metadata is intentionally ignored.
+ * @param ctor - The entity constructor.
+ * @returns The metadata bag if present.
+ */
+declare const getDecoratorMetadata: (ctor: object) => DecoratorMetadataBag | undefined;
 
 /**
  * Options for defining an entity.
@@ -5532,6 +5965,11 @@ interface PostgresClientLike {
         rows: Array<Record<string, unknown>>;
     }>;
 }
+/**
+ * Creates a database executor for PostgreSQL.
+ * @param client A PostgreSQL client or pool instance.
+ * @returns A DbExecutor implementation for Postgres.
+ */
 declare function createPostgresExecutor(client: PostgresClientLike): DbExecutor;
 
 interface MysqlClientLike {
@@ -5540,6 +5978,11 @@ interface MysqlClientLike {
     commit?(): Promise<void>;
     rollback?(): Promise<void>;
 }
+/**
+ * Creates a database executor for MySQL.
+ * @param client A MySQL client instance.
+ * @returns A DbExecutor implementation for MySQL.
+ */
 declare function createMysqlExecutor(client: MysqlClientLike): DbExecutor;
 
 interface SqliteClientLike {
@@ -5549,6 +5992,11 @@ interface SqliteClientLike {
     commitTransaction?(): Promise<void>;
     rollbackTransaction?(): Promise<void>;
 }
+/**
+ * Creates a database executor for SQLite.
+ * @param client A SQLite client instance.
+ * @returns A DbExecutor implementation for SQLite.
+ */
 declare function createSqliteExecutor(client: SqliteClientLike): DbExecutor;
 
 interface MssqlClientLike {
@@ -5559,6 +6007,11 @@ interface MssqlClientLike {
     commit?(): Promise<void>;
     rollback?(): Promise<void>;
 }
+/**
+ * Creates a database executor for Microsoft SQL Server.
+ * @param client A SQL Server client instance.
+ * @returns A DbExecutor implementation for MSSQL.
+ */
 declare function createMssqlExecutor(client: MssqlClientLike): DbExecutor;
 interface TediousColumn {
     metadata: {
@@ -5618,4 +6071,4 @@ type PooledExecutorFactoryOptions<TConn> = {
  */
 declare function createPooledExecutorFactory<TConn>(opts: PooledExecutorFactoryOptions<TConn>): DbExecutorFactory;
 
-export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, 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 Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type 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, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, aliasRef, and, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bootstrapEntities, caseWhen, cast, ceil, ceiling, char, charLength, clearExpressionDispatchers, clearOperandDispatchers, col, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedWithContexts, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, getColumn, getSchemaIntrospector, getTableDefFromEntity, groupConcat, gt, gte, hasMany, hasOne, hydrateRows, inList, inSubquery, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonPath, jsonify, 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, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, or, outerRef, pi, position, pow, power, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, renderColumnDefinition, renderTypeWithArgs, repeat, replace, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, sel, selectFromEntity, sign, sin, space, sqrt, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };
+export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, 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 Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type 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, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedWithContexts, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFromEntity, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };