metal-orm 1.0.42 → 1.0.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/README.md +195 -37
  2. package/dist/index.cjs +1014 -538
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +1267 -371
  5. package/dist/index.d.ts +1267 -371
  6. package/dist/index.js +1012 -536
  7. package/dist/index.js.map +1 -1
  8. package/package.json +8 -2
  9. package/scripts/run-eslint.mjs +34 -0
  10. package/src/codegen/typescript.ts +32 -15
  11. package/src/core/ast/adapters.ts +8 -2
  12. package/src/core/ast/builders.ts +105 -76
  13. package/src/core/ast/expression-builders.ts +430 -392
  14. package/src/core/ast/expression-nodes.ts +14 -5
  15. package/src/core/ast/expression-visitor.ts +56 -14
  16. package/src/core/ast/helpers.ts +23 -0
  17. package/src/core/ast/join-node.ts +18 -2
  18. package/src/core/ast/query.ts +6 -6
  19. package/src/core/ast/window-functions.ts +10 -2
  20. package/src/core/ddl/dialects/base-schema-dialect.ts +37 -4
  21. package/src/core/ddl/dialects/index.ts +1 -0
  22. package/src/core/ddl/dialects/mssql-schema-dialect.ts +5 -0
  23. package/src/core/ddl/dialects/mysql-schema-dialect.ts +3 -0
  24. package/src/core/ddl/dialects/postgres-schema-dialect.ts +14 -1
  25. package/src/core/ddl/dialects/render-reference.test.ts +69 -0
  26. package/src/core/ddl/dialects/sqlite-schema-dialect.ts +10 -0
  27. package/src/core/ddl/introspect/catalogs/index.ts +1 -0
  28. package/src/core/ddl/introspect/catalogs/postgres.ts +2 -0
  29. package/src/core/ddl/introspect/context.ts +6 -0
  30. package/src/core/ddl/introspect/functions/postgres.ts +13 -0
  31. package/src/core/ddl/introspect/mssql.ts +53 -8
  32. package/src/core/ddl/introspect/mysql.ts +32 -6
  33. package/src/core/ddl/introspect/postgres.ts +102 -34
  34. package/src/core/ddl/introspect/registry.ts +14 -0
  35. package/src/core/ddl/introspect/run-select.ts +19 -4
  36. package/src/core/ddl/introspect/sqlite.ts +78 -11
  37. package/src/core/ddl/introspect/types.ts +0 -1
  38. package/src/core/ddl/introspect/utils.ts +21 -3
  39. package/src/core/ddl/naming-strategy.ts +6 -0
  40. package/src/core/ddl/schema-dialect.ts +20 -6
  41. package/src/core/ddl/schema-diff.ts +22 -0
  42. package/src/core/ddl/schema-generator.ts +26 -12
  43. package/src/core/ddl/schema-plan-executor.ts +6 -0
  44. package/src/core/ddl/schema-types.ts +6 -0
  45. package/src/core/ddl/sql-writing.ts +4 -4
  46. package/src/core/dialect/abstract.ts +19 -7
  47. package/src/core/dialect/base/function-table-formatter.ts +3 -2
  48. package/src/core/dialect/base/join-compiler.ts +5 -3
  49. package/src/core/dialect/base/returning-strategy.ts +1 -0
  50. package/src/core/dialect/base/sql-dialect.ts +3 -3
  51. package/src/core/dialect/mssql/functions.ts +24 -25
  52. package/src/core/dialect/mssql/index.ts +1 -4
  53. package/src/core/dialect/mysql/functions.ts +0 -1
  54. package/src/core/dialect/postgres/functions.ts +33 -34
  55. package/src/core/dialect/postgres/index.ts +1 -0
  56. package/src/core/dialect/sqlite/functions.ts +18 -19
  57. package/src/core/dialect/sqlite/index.ts +2 -0
  58. package/src/core/execution/db-executor.ts +1 -1
  59. package/src/core/execution/executors/mysql-executor.ts +2 -2
  60. package/src/core/execution/executors/postgres-executor.ts +1 -1
  61. package/src/core/execution/pooling/pool.ts +12 -5
  62. package/src/core/functions/datetime.ts +58 -34
  63. package/src/core/functions/numeric.ts +96 -31
  64. package/src/core/functions/standard-strategy.ts +35 -0
  65. package/src/core/functions/text.ts +84 -23
  66. package/src/core/functions/types.ts +23 -8
  67. package/src/decorators/bootstrap.ts +42 -11
  68. package/src/decorators/column.ts +20 -11
  69. package/src/decorators/decorator-metadata.ts +30 -9
  70. package/src/decorators/entity.ts +29 -5
  71. package/src/decorators/index.ts +3 -0
  72. package/src/decorators/relations.ts +34 -11
  73. package/src/orm/als.ts +34 -9
  74. package/src/orm/entity-context.ts +62 -8
  75. package/src/orm/entity-meta.ts +8 -8
  76. package/src/orm/entity-metadata.ts +131 -16
  77. package/src/orm/entity.ts +28 -29
  78. package/src/orm/execute.ts +19 -4
  79. package/src/orm/hydration.ts +42 -39
  80. package/src/orm/identity-map.ts +1 -1
  81. package/src/orm/lazy-batch.ts +74 -104
  82. package/src/orm/orm-session.ts +24 -23
  83. package/src/orm/orm.ts +2 -5
  84. package/src/orm/relation-change-processor.ts +12 -11
  85. package/src/orm/relations/belongs-to.ts +11 -11
  86. package/src/orm/relations/has-many.ts +54 -10
  87. package/src/orm/relations/has-one.ts +8 -7
  88. package/src/orm/relations/many-to-many.ts +13 -13
  89. package/src/orm/runtime-types.ts +4 -4
  90. package/src/orm/save-graph.ts +31 -25
  91. package/src/orm/unit-of-work.ts +17 -17
  92. package/src/query/index.ts +74 -0
  93. package/src/query/target.ts +46 -0
  94. package/src/query-builder/delete-query-state.ts +30 -0
  95. package/src/query-builder/delete.ts +64 -18
  96. package/src/query-builder/hydration-manager.ts +52 -5
  97. package/src/query-builder/insert-query-state.ts +30 -0
  98. package/src/query-builder/insert.ts +58 -10
  99. package/src/query-builder/query-ast-service.ts +7 -2
  100. package/src/query-builder/query-resolution.ts +78 -0
  101. package/src/query-builder/raw-column-parser.ts +7 -1
  102. package/src/query-builder/relation-alias.ts +7 -0
  103. package/src/query-builder/relation-conditions.ts +61 -48
  104. package/src/query-builder/relation-service.ts +68 -63
  105. package/src/query-builder/relation-utils.ts +3 -0
  106. package/src/query-builder/select/cte-facet.ts +40 -0
  107. package/src/query-builder/select/from-facet.ts +80 -0
  108. package/src/query-builder/select/join-facet.ts +62 -0
  109. package/src/query-builder/select/predicate-facet.ts +103 -0
  110. package/src/query-builder/select/projection-facet.ts +69 -0
  111. package/src/query-builder/select/relation-facet.ts +81 -0
  112. package/src/query-builder/select/setop-facet.ts +36 -0
  113. package/src/query-builder/select-helpers.ts +15 -2
  114. package/src/query-builder/select-query-builder-deps.ts +19 -1
  115. package/src/query-builder/select-query-state.ts +2 -1
  116. package/src/query-builder/select.ts +795 -1163
  117. package/src/query-builder/update-query-state.ts +52 -0
  118. package/src/query-builder/update.ts +69 -18
  119. package/src/schema/column.ts +26 -26
  120. package/src/schema/table-guards.ts +31 -0
  121. package/src/schema/table.ts +47 -18
  122. package/src/schema/types.ts +22 -22
package/dist/index.d.cts CHANGED
@@ -50,7 +50,7 @@ interface ColumnDef<T extends ColumnType = ColumnType, TRuntime = unknown> {
50
50
  /** Column comment/description */
51
51
  comment?: string;
52
52
  /** Additional arguments for the column type (e.g., VARCHAR length) */
53
- args?: any[];
53
+ args?: unknown[];
54
54
  /** Table name this column belongs to (filled at runtime by defineTable) */
55
55
  table?: string;
56
56
  }
@@ -312,12 +312,12 @@ interface TableOptions {
312
312
  collation?: string;
313
313
  }
314
314
  interface TableHooks {
315
- beforeInsert?(ctx: unknown, entity: any): Promise<void> | void;
316
- afterInsert?(ctx: unknown, entity: any): Promise<void> | void;
317
- beforeUpdate?(ctx: unknown, entity: any): Promise<void> | void;
318
- afterUpdate?(ctx: unknown, entity: any): Promise<void> | void;
319
- beforeDelete?(ctx: unknown, entity: any): Promise<void> | void;
320
- afterDelete?(ctx: unknown, entity: any): Promise<void> | void;
315
+ beforeInsert?(ctx: unknown, entity: unknown): Promise<void> | void;
316
+ afterInsert?(ctx: unknown, entity: unknown): Promise<void> | void;
317
+ beforeUpdate?(ctx: unknown, entity: unknown): Promise<void> | void;
318
+ afterUpdate?(ctx: unknown, entity: unknown): Promise<void> | void;
319
+ beforeDelete?(ctx: unknown, entity: unknown): Promise<void> | void;
320
+ afterDelete?(ctx: unknown, entity: unknown): Promise<void> | void;
321
321
  }
322
322
  /**
323
323
  * Definition of a database table with its columns and relationships
@@ -386,6 +386,22 @@ type TableRef$1<T extends TableDef> = T & {
386
386
  * t.$.name is the "name" column (escape hatch)
387
387
  */
388
388
  declare const tableRef: <T extends TableDef>(table: T) => TableRef$1<T>;
389
+ /**
390
+ * Public API: dynamic column lookup by string key.
391
+ *
392
+ * Useful when the column name is only known at runtime, or when a column name
393
+ * collides with a real table field (e.g. "name").
394
+ *
395
+ * @example
396
+ * ```ts
397
+ * const t = tableRef(todos);
398
+ * const key = runtimeKey();
399
+ * where(eq(getColumn(t, key), 123));
400
+ * // or: t.$.name (escape hatch)
401
+ * ```
402
+ */
403
+ declare function getColumn<T extends TableDef, K extends keyof T['columns'] & string>(table: T, key: K): T['columns'][K];
404
+ declare function getColumn<T extends TableDef>(table: T, key: string): ColumnDef;
389
405
 
390
406
  /**
391
407
  * Resolves a relation definition to its target table type.
@@ -404,7 +420,7 @@ type InferRow<TTable extends TableDef> = {
404
420
  [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
405
421
  };
406
422
  type RelationResult$1<T extends RelationDef> = T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] : T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null : T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null : T extends BelongsToManyRelation<infer TTarget> ? (InferRow<TTarget> & {
407
- _pivot?: any;
423
+ _pivot?: unknown;
408
424
  })[] : never;
409
425
  /**
410
426
  * Maps relation names to the expected row results
@@ -673,10 +689,10 @@ interface ArithmeticExpressionNode {
673
689
  * Union type representing any operand that can be used in expressions
674
690
  */
675
691
  type OperandNode = AliasRefNode | ColumnNode | LiteralNode | FunctionNode | JsonPathNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode;
676
- declare const isOperandNode: (node: any) => node is OperandNode;
677
- declare const isFunctionNode: (node: any) => node is FunctionNode;
678
- declare const isCaseExpressionNode: (node: any) => node is CaseExpressionNode;
679
- declare const isWindowFunctionNode: (node: any) => node is WindowFunctionNode;
692
+ declare const isOperandNode: (node: unknown) => node is OperandNode;
693
+ declare const isFunctionNode: (node: unknown) => node is FunctionNode;
694
+ declare const isCaseExpressionNode: (node: unknown) => node is CaseExpressionNode;
695
+ declare const isWindowFunctionNode: (node: unknown) => node is WindowFunctionNode;
680
696
  declare const isExpressionSelectionNode: (node: ColumnRef | FunctionNode | CaseExpressionNode | WindowFunctionNode) => node is FunctionNode | CaseExpressionNode | WindowFunctionNode;
681
697
  /**
682
698
  * AST node representing a binary expression (e.g., column = value)
@@ -765,6 +781,12 @@ declare const isValueOperandInput: (value: unknown) => value is ValueOperandInpu
765
781
  type SelectQueryInput = SelectQueryNode | {
766
782
  getAST(): SelectQueryNode;
767
783
  };
784
+ /**
785
+ * Converts a ColumnRef or ColumnNode to a ColumnNode
786
+ * @param col - Column reference or node
787
+ * @returns ColumnNode
788
+ * @throws Error if ColumnRef doesn't have a table specified
789
+ */
768
790
  declare const columnOperand: (col: ColumnRef | ColumnNode) => ColumnNode;
769
791
  /**
770
792
  * Marks a column reference as an outer-scope reference for correlated subqueries.
@@ -946,7 +968,7 @@ declare const ntile: (n: number) => WindowFunctionNode;
946
968
  * @param defaultValue - Default value if no row exists
947
969
  * @returns Window function node for LAG
948
970
  */
949
- declare const lag: (col: ColumnRef | ColumnNode, offset?: number, defaultValue?: any) => WindowFunctionNode;
971
+ declare const lag: (col: ColumnRef | ColumnNode, offset?: number, defaultValue?: LiteralNode["value"]) => WindowFunctionNode;
950
972
  /**
951
973
  * Creates a LEAD window function
952
974
  * @param col - Column to lead
@@ -954,7 +976,7 @@ declare const lag: (col: ColumnRef | ColumnNode, offset?: number, defaultValue?:
954
976
  * @param defaultValue - Default value if no row exists
955
977
  * @returns Window function node for LEAD
956
978
  */
957
- declare const lead: (col: ColumnRef | ColumnNode, offset?: number, defaultValue?: any) => WindowFunctionNode;
979
+ declare const lead: (col: ColumnRef | ColumnNode, offset?: number, defaultValue?: LiteralNode["value"]) => WindowFunctionNode;
958
980
  /**
959
981
  * Creates a FIRST_VALUE window function
960
982
  * @param col - Column to get first value from
@@ -1050,8 +1072,8 @@ interface OperandVisitor<R> {
1050
1072
  visitAliasRef?(node: AliasRefNode): R;
1051
1073
  otherwise?(node: OperandNode): R;
1052
1074
  }
1053
- type ExpressionDispatch = <R>(node: any, visitor: ExpressionVisitor<R>) => R;
1054
- type OperandDispatch = <R>(node: any, visitor: OperandVisitor<R>) => R;
1075
+ type ExpressionDispatch = <R>(node: ExpressionNode, visitor: ExpressionVisitor<R>) => R;
1076
+ type OperandDispatch = <R>(node: OperandNode, visitor: OperandVisitor<R>) => R;
1055
1077
  /**
1056
1078
  * Registers a dispatcher for a custom expression node type.
1057
1079
  * Allows new node kinds without modifying the core switch.
@@ -1126,7 +1148,7 @@ interface FunctionTableNode {
1126
1148
  /** Optional schema for the function (some dialects) */
1127
1149
  schema?: string;
1128
1150
  /** Function arguments as operand nodes */
1129
- args?: any[];
1151
+ args?: OperandNode[];
1130
1152
  /** Optional alias for the function table */
1131
1153
  alias?: string;
1132
1154
  /** LATERAL flag */
@@ -1337,17 +1359,32 @@ interface HydrationMetadata {
1337
1359
  [key: string]: unknown;
1338
1360
  }
1339
1361
 
1362
+ /**
1363
+ * Context provided to function renderers.
1364
+ */
1340
1365
  interface FunctionRenderContext {
1366
+ /** The function node being rendered. */
1341
1367
  node: FunctionNode;
1368
+ /** The compiled arguments for the function. */
1342
1369
  compiledArgs: string[];
1343
- /** Helper to compile additional operands (e.g., separators or ORDER BY columns) */
1370
+ /** Helper to compile additional operands (e.g., separators or ORDER BY columns). */
1344
1371
  compileOperand: (operand: OperandNode) => string;
1345
1372
  }
1373
+ /**
1374
+ * A function that renders a SQL function call.
1375
+ * @param ctx - The rendering context.
1376
+ * @returns The rendered SQL string.
1377
+ */
1346
1378
  type FunctionRenderer = (ctx: FunctionRenderContext) => string;
1379
+ /**
1380
+ * Strategy for rendering SQL functions in a specific dialect.
1381
+ */
1347
1382
  interface FunctionStrategy {
1348
1383
  /**
1349
1384
  * Returns a renderer for a specific function name (e.g. "DATE_ADD").
1350
1385
  * Returns undefined if this dialect doesn't support the function.
1386
+ * @param functionName - The name of the function.
1387
+ * @returns The renderer function or undefined.
1351
1388
  */
1352
1389
  getRenderer(functionName: string): FunctionRenderer | undefined;
1353
1390
  }
@@ -1421,7 +1458,7 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
1421
1458
  * @returns SQL WHERE clause or empty string
1422
1459
  */
1423
1460
  protected compileWhere(where: ExpressionNode | undefined, ctx: CompilerContext): string;
1424
- protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string;
1461
+ protected compileReturning(returning: ColumnNode[] | undefined, _ctx: CompilerContext): string;
1425
1462
  /**
1426
1463
  * Generates subquery for EXISTS expressions
1427
1464
  * Rule: Always forces SELECT 1, ignoring column list
@@ -1442,12 +1479,12 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
1442
1479
  * @param index - Parameter index
1443
1480
  * @returns Formatted placeholder string
1444
1481
  */
1445
- protected formatPlaceholder(index: number): string;
1482
+ protected formatPlaceholder(_index: number): string;
1446
1483
  /**
1447
1484
  * Whether the current dialect supports a given set operation.
1448
1485
  * Override in concrete dialects to restrict support.
1449
1486
  */
1450
- protected supportsSetOperation(kind: SetOperationKind): boolean;
1487
+ protected supportsSetOperation(_kind: SetOperationKind): boolean;
1451
1488
  /**
1452
1489
  * Validates set-operation semantics:
1453
1490
  * - Ensures the dialect supports requested operators.
@@ -1510,7 +1547,7 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
1510
1547
  protected compileOrderingTerm(term: OrderingTerm, ctx: CompilerContext): string;
1511
1548
  private registerDefaultExpressionCompilers;
1512
1549
  private registerDefaultOperandCompilers;
1513
- protected compileJsonPath(node: JsonPathNode): string;
1550
+ protected compileJsonPath(_node: JsonPathNode): string;
1514
1551
  /**
1515
1552
  * Compiles a function operand, using the dialect's function strategy.
1516
1553
  */
@@ -1730,6 +1767,11 @@ declare class HydrationManager {
1730
1767
  * applied to parent rows when eager-loading multiplicative relations.
1731
1768
  */
1732
1769
  private requiresParentPagination;
1770
+ /**
1771
+ * Checks if the hydration plan contains relations that multiply rows
1772
+ * @param plan - Hydration plan to check
1773
+ * @returns True if plan has HasMany or BelongsToMany relations
1774
+ */
1733
1775
  private hasMultiplyingRelations;
1734
1776
  /**
1735
1777
  * Rewrites the query using CTEs so LIMIT/OFFSET target distinct parent rows
@@ -1741,11 +1783,52 @@ declare class HydrationManager {
1741
1783
  * - Join the base CTE against the paged ids to retrieve the joined rows for just that page.
1742
1784
  */
1743
1785
  private wrapForParentPagination;
1786
+ /**
1787
+ * Generates a unique CTE name by appending a suffix if needed
1788
+ * @param existing - Existing CTE nodes
1789
+ * @param baseName - Base name for the CTE
1790
+ * @returns Unique CTE name
1791
+ */
1744
1792
  private nextCteName;
1793
+ /**
1794
+ * Extracts projection names from column nodes
1795
+ * @param columns - Projection nodes
1796
+ * @returns Array of names or undefined if any column lacks name/alias
1797
+ */
1745
1798
  private getProjectionNames;
1799
+ /**
1800
+ * Builds a map of column keys to their aliases from projection nodes
1801
+ * @param columns - Projection nodes
1802
+ * @returns Map of 'table.name' to alias
1803
+ */
1746
1804
  private buildProjectionAliasMap;
1805
+ /**
1806
+ * Maps order by nodes to use base CTE alias
1807
+ * @param orderBy - Original order by nodes
1808
+ * @param plan - Hydration plan
1809
+ * @param projectionAliases - Map of column aliases
1810
+ * @param baseAlias - Base CTE alias
1811
+ * @param availableColumns - Set of available column names
1812
+ * @returns Mapped order by nodes, null if cannot map
1813
+ */
1747
1814
  private mapOrderBy;
1815
+ /**
1816
+ * Maps a single ordering term to use base CTE alias
1817
+ * @param term - Ordering term to map
1818
+ * @param plan - Hydration plan
1819
+ * @param projectionAliases - Map of column aliases
1820
+ * @param baseAlias - Base CTE alias
1821
+ * @param availableColumns - Set of available column names
1822
+ * @returns Mapped term or null if cannot map
1823
+ */
1748
1824
  private mapOrderingTerm;
1825
+ /**
1826
+ * Builds column nodes for paging CTE
1827
+ * @param primaryKey - Primary key name
1828
+ * @param orderBy - Order by nodes
1829
+ * @param tableAlias - Table alias for columns
1830
+ * @returns Array of column nodes for paging
1831
+ */
1749
1832
  private buildPagingColumns;
1750
1833
  }
1751
1834
 
@@ -1871,6 +1954,11 @@ declare class QueryAstService {
1871
1954
  * @returns Combined expression
1872
1955
  */
1873
1956
  private combineExpressions;
1957
+ /**
1958
+ * Normalizes an ordering term to a standard OrderingTerm
1959
+ * @param term - Column definition or ordering term to normalize
1960
+ * @returns Normalized ordering term
1961
+ */
1874
1962
  private normalizeOrderingTerm;
1875
1963
  }
1876
1964
 
@@ -1984,6 +2072,115 @@ declare class RelationService {
1984
2072
  private rootTableName;
1985
2073
  }
1986
2074
 
2075
+ /**
2076
+ * Type for column selection input
2077
+ */
2078
+ type ColumnSelectionInput = Record<string, ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode>;
2079
+ /**
2080
+ * Handles column selection operations for the query builder
2081
+ */
2082
+ declare class ColumnSelector {
2083
+ private readonly env;
2084
+ /**
2085
+ * Creates a new ColumnSelector instance
2086
+ * @param env - Query builder environment
2087
+ */
2088
+ constructor(env: SelectQueryBuilderEnvironment);
2089
+ /**
2090
+ * Selects columns for the query
2091
+ * @param context - Current query context
2092
+ * @param columns - Columns to select
2093
+ * @returns Updated query context with selected columns
2094
+ */
2095
+ select(context: SelectQueryBuilderContext, columns: ColumnSelectionInput): SelectQueryBuilderContext;
2096
+ /**
2097
+ * Selects raw column expressions
2098
+ * @param context - Current query context
2099
+ * @param columns - Raw column expressions
2100
+ * @returns Updated query context with raw column selections
2101
+ */
2102
+ selectRaw(context: SelectQueryBuilderContext, columns: string[]): SelectQueryBuilderContext;
2103
+ /**
2104
+ * Selects a subquery as a column
2105
+ * @param context - Current query context
2106
+ * @param alias - Alias for the subquery
2107
+ * @param query - Subquery to select
2108
+ * @returns Updated query context with subquery selection
2109
+ */
2110
+ selectSubquery(context: SelectQueryBuilderContext, alias: string, query: SelectQueryNode): SelectQueryBuilderContext;
2111
+ /**
2112
+ * Adds DISTINCT clause to the query
2113
+ * @param context - Current query context
2114
+ * @param columns - Columns to make distinct
2115
+ * @returns Updated query context with DISTINCT clause
2116
+ */
2117
+ distinct(context: SelectQueryBuilderContext, columns: (ColumnDef | ColumnNode)[]): SelectQueryBuilderContext;
2118
+ }
2119
+
2120
+ /**
2121
+ * Manages relation operations (joins, includes, etc.) for query building
2122
+ */
2123
+ declare class RelationManager {
2124
+ private readonly env;
2125
+ /**
2126
+ * Creates a new RelationManager instance
2127
+ * @param env - Query builder environment
2128
+ */
2129
+ constructor(env: SelectQueryBuilderEnvironment);
2130
+ /**
2131
+ * Matches records based on a relation with an optional predicate
2132
+ * @param context - Current query context
2133
+ * @param relationName - Name of the relation to match
2134
+ * @param predicate - Optional predicate expression
2135
+ * @returns Updated query context with relation match
2136
+ */
2137
+ match(context: SelectQueryBuilderContext, relationName: string, predicate?: ExpressionNode): SelectQueryBuilderContext;
2138
+ /**
2139
+ * Joins a relation to the query
2140
+ * @param context - Current query context
2141
+ * @param relationName - Name of the relation to join
2142
+ * @param joinKind - Type of join to use
2143
+ * @param extraCondition - Additional join condition
2144
+ * @returns Updated query context with relation join
2145
+ */
2146
+ joinRelation(context: SelectQueryBuilderContext, relationName: string, joinKind: JoinKind, extraCondition?: ExpressionNode): SelectQueryBuilderContext;
2147
+ /**
2148
+ * Includes a relation in the query result
2149
+ * @param context - Current query context
2150
+ * @param relationName - Name of the relation to include
2151
+ * @param options - Options for relation inclusion
2152
+ * @returns Updated query context with included relation
2153
+ */
2154
+ include(context: SelectQueryBuilderContext, relationName: string, options?: RelationIncludeOptions): SelectQueryBuilderContext;
2155
+ /**
2156
+ * Applies relation correlation to a query AST
2157
+ * @param context - Current query context
2158
+ * @param relationName - Name of the relation
2159
+ * @param ast - Query AST to modify
2160
+ * @returns Modified query AST with relation correlation
2161
+ */
2162
+ applyRelationCorrelation(context: SelectQueryBuilderContext, relationName: string, ast: SelectQueryNode, additionalCorrelation?: ExpressionNode): SelectQueryNode;
2163
+ /**
2164
+ * Creates a relation service instance
2165
+ * @param context - Current query context
2166
+ * @returns Relation service instance
2167
+ */
2168
+ private createService;
2169
+ }
2170
+
2171
+ /**
2172
+ * Context for query building operations
2173
+ */
2174
+ interface SelectQueryBuilderContext {
2175
+ /**
2176
+ * Current query state
2177
+ */
2178
+ readonly state: SelectQueryState;
2179
+ /**
2180
+ * Hydration manager for the query
2181
+ */
2182
+ readonly hydration: HydrationManager;
2183
+ }
1987
2184
  /**
1988
2185
  * Dependencies for query builder operations
1989
2186
  */
@@ -2021,6 +2218,31 @@ interface SelectQueryBuilderDependencies {
2021
2218
  * @returns New relation service
2022
2219
  */
2023
2220
  createRelationService: (table: TableDef, state: SelectQueryState, hydration: HydrationManager) => RelationService;
2221
+ /**
2222
+ * Creates a new column selector
2223
+ * @param env - Query builder environment
2224
+ * @returns New column selector
2225
+ */
2226
+ createColumnSelector: (env: SelectQueryBuilderEnvironment) => ColumnSelector;
2227
+ /**
2228
+ * Creates a new relation manager
2229
+ * @param env - Query builder environment
2230
+ * @returns New relation manager
2231
+ */
2232
+ createRelationManager: (env: SelectQueryBuilderEnvironment) => RelationManager;
2233
+ }
2234
+ /**
2235
+ * Environment for query builder operations
2236
+ */
2237
+ interface SelectQueryBuilderEnvironment {
2238
+ /**
2239
+ * Table definition
2240
+ */
2241
+ readonly table: TableDef;
2242
+ /**
2243
+ * Query builder dependencies
2244
+ */
2245
+ readonly deps: SelectQueryBuilderDependencies;
2024
2246
  }
2025
2247
 
2026
2248
  type QueryResult = {
@@ -2061,8 +2283,19 @@ interface SimpleQueryRunner {
2061
2283
  */
2062
2284
  declare function createExecutorFromQueryRunner(runner: SimpleQueryRunner): DbExecutor;
2063
2285
 
2064
- type EntityConstructor<T = object> = new (...args: any[]) => T;
2065
- type EntityOrTableTarget = EntityConstructor<any> | TableDef;
2286
+ /**
2287
+ * Constructor type for entities.
2288
+ * Supports any constructor signature for maximum flexibility with decorator-based entities.
2289
+ * @template T - The entity type
2290
+ */
2291
+ type EntityConstructor<T = object> = new (...args: never[]) => T;
2292
+ /**
2293
+ * Target that can be an entity constructor or table definition.
2294
+ */
2295
+ type EntityOrTableTarget = EntityConstructor | TableDef;
2296
+ /**
2297
+ * Resolver for entity or table target, can be direct or function.
2298
+ */
2066
2299
  type EntityOrTableTargetResolver = EntityOrTableTarget | (() => EntityOrTableTarget);
2067
2300
 
2068
2301
  /**
@@ -2087,13 +2320,13 @@ interface TrackedEntity {
2087
2320
  /** The table definition this entity belongs to */
2088
2321
  table: TableDef;
2089
2322
  /** The actual entity instance */
2090
- entity: any;
2323
+ entity: unknown;
2091
2324
  /** Primary key value of the entity */
2092
2325
  pk: string | number | null;
2093
2326
  /** Current status of the entity */
2094
2327
  status: EntityStatus;
2095
2328
  /** Original values of the entity when it was loaded */
2096
- original: Record<string, any> | null;
2329
+ original: Record<string, unknown> | null;
2097
2330
  }
2098
2331
  /**
2099
2332
  * Type representing a key for relation navigation
@@ -2121,7 +2354,7 @@ type RelationChange<T> = {
2121
2354
  */
2122
2355
  interface RelationChangeEntry {
2123
2356
  /** Root entity that owns the relation */
2124
- root: any;
2357
+ root: unknown;
2125
2358
  /** Key of the relation being changed */
2126
2359
  relationKey: RelationKey;
2127
2360
  /** Table definition of the root entity */
@@ -2131,7 +2364,7 @@ interface RelationChangeEntry {
2131
2364
  /** Relation definition */
2132
2365
  relation: RelationDef;
2133
2366
  /** The change being applied */
2134
- change: RelationChange<any>;
2367
+ change: RelationChange<unknown>;
2135
2368
  }
2136
2369
  /**
2137
2370
  * Represents a domain event that can be emitted by entities
@@ -2191,9 +2424,8 @@ declare class InterceptorPipeline {
2191
2424
 
2192
2425
  /**
2193
2426
  * Options for creating an ORM instance.
2194
- * @template E - The domain event type
2195
2427
  */
2196
- interface OrmOptions<E extends DomainEvent = OrmDomainEvent> {
2428
+ interface OrmOptions {
2197
2429
  /** The database dialect */
2198
2430
  dialect: Dialect;
2199
2431
  /** The database executor factory */
@@ -2238,7 +2470,7 @@ declare class Orm<E extends DomainEvent = OrmDomainEvent> {
2238
2470
  * Creates a new ORM instance.
2239
2471
  * @param opts - ORM options
2240
2472
  */
2241
- constructor(opts: OrmOptions<E>);
2473
+ constructor(opts: OrmOptions);
2242
2474
  /**
2243
2475
  * Creates a new ORM session.
2244
2476
  * @param options - Optional session options
@@ -2262,7 +2494,7 @@ declare class Orm<E extends DomainEvent = OrmDomainEvent> {
2262
2494
  declare class IdentityMap {
2263
2495
  private readonly buckets;
2264
2496
  get bucketsMap(): Map<string, Map<string, TrackedEntity>>;
2265
- getEntity(table: TableDef, pk: string | number): any | undefined;
2497
+ getEntity(table: TableDef, pk: string | number): unknown | undefined;
2266
2498
  register(tracked: TrackedEntity): void;
2267
2499
  remove(tracked: TrackedEntity): void;
2268
2500
  getEntitiesForTable(table: TableDef): TrackedEntity[];
@@ -2302,7 +2534,7 @@ declare class UnitOfWork {
2302
2534
  * @param pk - The primary key value
2303
2535
  * @returns The entity or undefined if not found
2304
2536
  */
2305
- getEntity(table: TableDef, pk: string | number): any | undefined;
2537
+ getEntity(table: TableDef, pk: string | number): unknown | undefined;
2306
2538
  /**
2307
2539
  * Gets all tracked entities for a specific table.
2308
2540
  * @param table - The table definition
@@ -2314,38 +2546,38 @@ declare class UnitOfWork {
2314
2546
  * @param entity - The entity to find
2315
2547
  * @returns The tracked entity or undefined if not found
2316
2548
  */
2317
- findTracked(entity: any): TrackedEntity | undefined;
2549
+ findTracked(entity: unknown): TrackedEntity | undefined;
2318
2550
  /**
2319
2551
  * Sets an entity in the identity map.
2320
2552
  * @param table - The table definition
2321
2553
  * @param pk - The primary key value
2322
2554
  * @param entity - The entity instance
2323
2555
  */
2324
- setEntity(table: TableDef, pk: string | number, entity: any): void;
2556
+ setEntity(table: TableDef, pk: string | number, entity: unknown): void;
2325
2557
  /**
2326
2558
  * Tracks a new entity.
2327
2559
  * @param table - The table definition
2328
2560
  * @param entity - The entity instance
2329
2561
  * @param pk - Optional primary key value
2330
2562
  */
2331
- trackNew(table: TableDef, entity: any, pk?: string | number): void;
2563
+ trackNew(table: TableDef, entity: unknown, pk?: string | number): void;
2332
2564
  /**
2333
2565
  * Tracks a managed entity.
2334
2566
  * @param table - The table definition
2335
2567
  * @param pk - The primary key value
2336
2568
  * @param entity - The entity instance
2337
2569
  */
2338
- trackManaged(table: TableDef, pk: string | number, entity: any): void;
2570
+ trackManaged(table: TableDef, pk: string | number, entity: unknown): void;
2339
2571
  /**
2340
2572
  * Marks an entity as dirty (modified).
2341
2573
  * @param entity - The entity to mark as dirty
2342
2574
  */
2343
- markDirty(entity: any): void;
2575
+ markDirty(entity: unknown): void;
2344
2576
  /**
2345
2577
  * Marks an entity as removed.
2346
2578
  * @param entity - The entity to mark as removed
2347
2579
  */
2348
- markRemoved(entity: any): void;
2580
+ markRemoved(entity: unknown): void;
2349
2581
  /**
2350
2582
  * Flushes pending changes to the database.
2351
2583
  */
@@ -2628,17 +2860,68 @@ interface ExecutionContext {
2628
2860
  interceptors: InterceptorPipeline;
2629
2861
  }
2630
2862
 
2863
+ /**
2864
+ * Interface for entity context providing entity tracking and management.
2865
+ */
2631
2866
  interface EntityContext {
2867
+ /** The database dialect */
2632
2868
  dialect: Dialect;
2869
+ /** The database executor */
2633
2870
  executor: DbExecutor;
2634
- getEntity(table: TableDef, pk: any): any;
2635
- setEntity(table: TableDef, pk: any, entity: any): void;
2636
- trackNew(table: TableDef, entity: any, pk?: any): void;
2637
- trackManaged(table: TableDef, pk: any, entity: any): void;
2638
- markDirty(entity: any): void;
2639
- markRemoved(entity: any): void;
2871
+ /**
2872
+ * Gets an entity by table and primary key.
2873
+ * @param table - The table definition
2874
+ * @param pk - The primary key value
2875
+ * @returns The entity or undefined
2876
+ */
2877
+ getEntity(table: TableDef, pk: unknown): unknown;
2878
+ /**
2879
+ * Sets an entity in the context.
2880
+ * @param table - The table definition
2881
+ * @param pk - The primary key value
2882
+ * @param entity - The entity to set
2883
+ */
2884
+ setEntity(table: TableDef, pk: unknown, entity: unknown): void;
2885
+ /**
2886
+ * Tracks a new entity.
2887
+ * @param table - The table definition
2888
+ * @param entity - The new entity
2889
+ * @param pk - Optional primary key
2890
+ */
2891
+ trackNew(table: TableDef, entity: unknown, pk?: unknown): void;
2892
+ /**
2893
+ * Tracks a managed entity.
2894
+ * @param table - The table definition
2895
+ * @param pk - The primary key
2896
+ * @param entity - The managed entity
2897
+ */
2898
+ trackManaged(table: TableDef, pk: unknown, entity: unknown): void;
2899
+ /**
2900
+ * Marks an entity as dirty.
2901
+ * @param entity - The entity to mark
2902
+ */
2903
+ markDirty(entity: unknown): void;
2904
+ /**
2905
+ * Marks an entity as removed.
2906
+ * @param entity - The entity to mark
2907
+ */
2908
+ markRemoved(entity: unknown): void;
2909
+ /**
2910
+ * Gets all tracked entities for a table.
2911
+ * @param table - The table definition
2912
+ * @returns Array of tracked entities
2913
+ */
2640
2914
  getEntitiesForTable(table: TableDef): TrackedEntity[];
2641
- registerRelationChange(root: any, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<any>): void;
2915
+ /**
2916
+ * Registers a relation change.
2917
+ * @param root - The root entity
2918
+ * @param relationKey - The relation key
2919
+ * @param rootTable - The root table definition
2920
+ * @param relationName - The relation name
2921
+ * @param relation - The relation definition
2922
+ * @param change - The relation change
2923
+ */
2924
+ registerRelationChange(root: unknown, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<unknown>): void;
2642
2925
  }
2643
2926
 
2644
2927
  interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
@@ -2731,38 +3014,38 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
2731
3014
  * @param pk - The primary key value
2732
3015
  * @returns The entity or undefined if not found
2733
3016
  */
2734
- getEntity(table: TableDef, pk: any): any | undefined;
3017
+ getEntity(table: TableDef, pk: unknown): unknown | undefined;
2735
3018
  /**
2736
3019
  * Sets an entity in the identity map.
2737
3020
  * @param table - The table definition
2738
3021
  * @param pk - The primary key value
2739
3022
  * @param entity - The entity instance
2740
3023
  */
2741
- setEntity(table: TableDef, pk: any, entity: any): void;
3024
+ setEntity(table: TableDef, pk: unknown, entity: unknown): void;
2742
3025
  /**
2743
3026
  * Tracks a new entity.
2744
3027
  * @param table - The table definition
2745
3028
  * @param entity - The entity instance
2746
3029
  * @param pk - Optional primary key value
2747
3030
  */
2748
- trackNew(table: TableDef, entity: any, pk?: any): void;
3031
+ trackNew(table: TableDef, entity: unknown, pk?: unknown): void;
2749
3032
  /**
2750
3033
  * Tracks a managed entity.
2751
3034
  * @param table - The table definition
2752
3035
  * @param pk - The primary key value
2753
3036
  * @param entity - The entity instance
2754
3037
  */
2755
- trackManaged(table: TableDef, pk: any, entity: any): void;
3038
+ trackManaged(table: TableDef, pk: unknown, entity: unknown): void;
2756
3039
  /**
2757
3040
  * Marks an entity as dirty (modified).
2758
3041
  * @param entity - The entity to mark as dirty
2759
3042
  */
2760
- markDirty(entity: any): void;
3043
+ markDirty(entity: unknown): void;
2761
3044
  /**
2762
3045
  * Marks an entity as removed.
2763
3046
  * @param entity - The entity to mark as removed
2764
3047
  */
2765
- markRemoved(entity: any): void;
3048
+ markRemoved(entity: unknown): void;
2766
3049
  /**
2767
3050
  * Registers a relation change.
2768
3051
  * @param root - The root entity
@@ -2772,7 +3055,7 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
2772
3055
  * @param relation - The relation definition
2773
3056
  * @param change - The relation change
2774
3057
  */
2775
- registerRelationChange: (root: any, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<any>) => void;
3058
+ registerRelationChange: (root: unknown, relationKey: RelationKey, rootTable: TableDef, relationName: string, relation: RelationDef, change: RelationChange<unknown>) => void;
2776
3059
  /**
2777
3060
  * Gets all tracked entities for a specific table.
2778
3061
  * @param table - The table definition
@@ -2800,21 +3083,21 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
2800
3083
  * @returns The entity instance or null if not found
2801
3084
  * @throws If entity metadata is not bootstrapped or table has no primary key
2802
3085
  */
2803
- find<TCtor extends EntityConstructor<any>>(entityClass: TCtor, id: any): Promise<InstanceType<TCtor> | null>;
3086
+ find<TCtor extends EntityConstructor<object>>(entityClass: TCtor, id: unknown): Promise<InstanceType<TCtor> | null>;
2804
3087
  /**
2805
3088
  * Finds a single entity using a query builder.
2806
3089
  * @template TTable - The table type
2807
3090
  * @param qb - The query builder
2808
3091
  * @returns The first entity instance or null if not found
2809
3092
  */
2810
- findOne<TTable extends TableDef>(qb: SelectQueryBuilder<any, TTable>): Promise<EntityInstance<TTable> | null>;
3093
+ findOne<TTable extends TableDef>(qb: SelectQueryBuilder<unknown, TTable>): Promise<EntityInstance<TTable> | null>;
2811
3094
  /**
2812
3095
  * Finds multiple entities using a query builder.
2813
3096
  * @template TTable - The table type
2814
3097
  * @param qb - The query builder
2815
3098
  * @returns Array of entity instances
2816
3099
  */
2817
- findMany<TTable extends TableDef>(qb: SelectQueryBuilder<any, TTable>): Promise<EntityInstance<TTable>[]>;
3100
+ findMany<TTable extends TableDef>(qb: SelectQueryBuilder<unknown, TTable>): Promise<EntityInstance<TTable>[]>;
2818
3101
  /**
2819
3102
  * Saves an entity graph (root + nested relations) based on a DTO-like payload.
2820
3103
  * @param entityClass - Root entity constructor
@@ -2822,7 +3105,7 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
2822
3105
  * @param options - Graph save options
2823
3106
  * @returns The root entity instance
2824
3107
  */
2825
- saveGraph<TCtor extends EntityConstructor<any>>(entityClass: TCtor, payload: Record<string, any>, options?: SaveGraphOptions & {
3108
+ saveGraph<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: Record<string, unknown>, options?: SaveGraphOptions & {
2826
3109
  transactional?: boolean;
2827
3110
  }): Promise<InstanceType<TCtor>>;
2828
3111
  /**
@@ -2875,109 +3158,116 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
2875
3158
  type SelectDialectInput = Dialect | DialectKey;
2876
3159
 
2877
3160
  type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode;
2878
- type DeepSelectConfig<TTable extends TableDef> = {
2879
- root?: (keyof TTable['columns'] & string)[];
2880
- } & {
2881
- [K in keyof TTable['relations'] & string]?: (keyof RelationTargetTable<TTable['relations'][K]>['columns'] & string)[];
3161
+ type DeepSelectEntry<TTable extends TableDef> = {
3162
+ type: 'root';
3163
+ columns: (keyof TTable['columns'] & string)[];
3164
+ } | {
3165
+ type: 'relation';
3166
+ relationName: keyof TTable['relations'] & string;
3167
+ columns: string[];
2882
3168
  };
3169
+ type DeepSelectConfig<TTable extends TableDef> = DeepSelectEntry<TTable>[];
2883
3170
  type WhereHasOptions = {
2884
3171
  correlate?: ExpressionNode;
2885
3172
  };
2886
- type RelationCallback = <TChildTable extends TableDef>(qb: SelectQueryBuilder<any, TChildTable>) => SelectQueryBuilder<any, TChildTable>;
3173
+ type RelationCallback = <TChildTable extends TableDef>(qb: SelectQueryBuilder<unknown, TChildTable>) => SelectQueryBuilder<unknown, TChildTable>;
2887
3174
  /**
2888
-
2889
3175
  * Main query builder class for constructing SQL SELECT queries
2890
-
2891
3176
  * @typeParam T - Result type for projections (unused)
2892
-
2893
3177
  * @typeParam TTable - Table definition being queried
2894
-
2895
3178
  */
2896
- declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
3179
+ declare class SelectQueryBuilder<T = unknown, TTable extends TableDef = TableDef> {
2897
3180
  private readonly env;
2898
3181
  private readonly context;
2899
3182
  private readonly columnSelector;
2900
3183
  private readonly relationManager;
2901
3184
  private readonly lazyRelations;
2902
3185
  /**
2903
-
2904
3186
  * Creates a new SelectQueryBuilder instance
2905
-
2906
3187
  * @param table - Table definition to query
2907
-
2908
3188
  * @param state - Optional initial query state
2909
-
2910
3189
  * @param hydration - Optional hydration manager
2911
-
2912
3190
  * @param dependencies - Optional query builder dependencies
2913
-
2914
3191
  */
2915
3192
  constructor(table: TTable, state?: SelectQueryState, hydration?: HydrationManager, dependencies?: Partial<SelectQueryBuilderDependencies>, lazyRelations?: Set<string>);
3193
+ /**
3194
+ * Creates a new SelectQueryBuilder instance with updated context and lazy relations
3195
+ * @param context - Updated query context
3196
+ * @param lazyRelations - Updated lazy relations set
3197
+ * @returns New SelectQueryBuilder instance
3198
+ */
2916
3199
  private clone;
2917
3200
  /**
2918
3201
  * Applies an alias to the root FROM table.
2919
3202
  * @param alias - Alias to apply
2920
3203
  */
2921
3204
  as(alias: string): SelectQueryBuilder<T, TTable>;
2922
- private resolveQueryNode;
3205
+ /**
3206
+ * Applies correlation expression to the query AST
3207
+ * @param ast - Query AST to modify
3208
+ * @param correlation - Correlation expression
3209
+ * @returns Modified AST with correlation applied
3210
+ */
2923
3211
  private applyCorrelation;
3212
+ /**
3213
+ * Creates a new child query builder for a related table
3214
+ * @param table - Table definition for the child builder
3215
+ * @returns New SelectQueryBuilder instance for the child table
3216
+ */
2924
3217
  private createChildBuilder;
3218
+ /**
3219
+ * Applies an AST mutation using the query AST service
3220
+ * @param context - Current query context
3221
+ * @param mutator - Function that mutates the AST
3222
+ * @returns Updated query context
3223
+ */
2925
3224
  private applyAst;
3225
+ /**
3226
+ * Applies a join to the query context
3227
+ * @param context - Current query context
3228
+ * @param table - Table to join
3229
+ * @param condition - Join condition
3230
+ * @param kind - Join kind
3231
+ * @returns Updated query context with join applied
3232
+ */
2926
3233
  private applyJoin;
3234
+ /**
3235
+ * Applies a set operation to the query
3236
+ * @param operator - Set operation kind
3237
+ * @param query - Query to combine with
3238
+ * @returns Updated query context with set operation
3239
+ */
2927
3240
  private applySetOperation;
2928
3241
  /**
2929
-
2930
- * Selects specific columns for the query
2931
-
2932
- * @param columns - Record of column definitions, function nodes, case expressions, or window functions
2933
-
3242
+ * Selects columns for the query (unified overloaded method).
3243
+ * Can be called with column names or a projection object.
3244
+ * @param args - Column names or projection object
2934
3245
  * @returns New query builder instance with selected columns
2935
-
2936
3246
  */
3247
+ select<K extends keyof TTable['columns'] & string>(...args: K[]): SelectQueryBuilder<T, TTable>;
2937
3248
  select(columns: Record<string, ColumnSelectionValue>): SelectQueryBuilder<T, TTable>;
2938
3249
  /**
2939
- * Selects columns from the root table by name (typed).
2940
- * @param cols - Column names on the root table
2941
- */
2942
- selectColumns<K extends keyof TTable['columns'] & string>(...cols: K[]): SelectQueryBuilder<T, TTable>;
2943
- /**
2944
-
2945
3250
  * Selects raw column expressions
2946
-
2947
3251
  * @param cols - Column expressions as strings
2948
-
2949
3252
  * @returns New query builder instance with raw column selections
2950
-
2951
3253
  */
2952
3254
  selectRaw(...cols: string[]): SelectQueryBuilder<T, TTable>;
2953
3255
  /**
2954
-
2955
3256
  * Adds a Common Table Expression (CTE) to the query
2956
-
2957
3257
  * @param name - Name of the CTE
2958
-
2959
3258
  * @param query - Query builder or query node for the CTE
2960
-
2961
3259
  * @param columns - Optional column names for the CTE
2962
-
2963
3260
  * @returns New query builder instance with the CTE
2964
-
2965
3261
  */
2966
- with(name: string, query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable>;
3262
+ with<TSub extends TableDef>(name: string, query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable>;
2967
3263
  /**
2968
-
2969
3264
  * Adds a recursive Common Table Expression (CTE) to the query
2970
-
2971
3265
  * @param name - Name of the CTE
2972
-
2973
3266
  * @param query - Query builder or query node for the CTE
2974
-
2975
3267
  * @param columns - Optional column names for the CTE
2976
-
2977
3268
  * @returns New query builder instance with the recursive CTE
2978
-
2979
3269
  */
2980
- withRecursive(name: string, query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable>;
3270
+ withRecursive<TSub extends TableDef>(name: string, query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T, TTable>;
2981
3271
  /**
2982
3272
  * Replaces the FROM clause with a derived table (subquery with alias)
2983
3273
  * @param subquery - Subquery to use as the FROM source
@@ -2985,19 +3275,27 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
2985
3275
  * @param columnAliases - Optional column alias list
2986
3276
  * @returns New query builder instance with updated FROM
2987
3277
  */
2988
- fromSubquery(subquery: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, alias: string, columnAliases?: string[]): SelectQueryBuilder<T, TTable>;
3278
+ fromSubquery<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, alias: string, columnAliases?: string[]): SelectQueryBuilder<T, TTable>;
3279
+ /**
3280
+ * Replaces the FROM clause with a function table expression.
3281
+ * @param name - Function name
3282
+ * @param args - Optional function arguments
3283
+ * @param alias - Optional alias for the function table
3284
+ * @param options - Optional function-table metadata (lateral, ordinality, column aliases, schema)
3285
+ */
3286
+ fromFunctionTable(name: string, args?: OperandNode[], alias?: string, options?: {
3287
+ lateral?: boolean;
3288
+ withOrdinality?: boolean;
3289
+ columnAliases?: string[];
3290
+ schema?: string;
3291
+ }): SelectQueryBuilder<T, TTable>;
2989
3292
  /**
2990
-
2991
3293
  * Selects a subquery as a column
2992
-
2993
3294
  * @param alias - Alias for the subquery column
2994
-
2995
3295
  * @param sub - Query builder or query node for the subquery
2996
-
2997
3296
  * @returns New query builder instance with the subquery selection
2998
-
2999
3297
  */
3000
- selectSubquery(alias: string, sub: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3298
+ selectSubquery<TSub extends TableDef>(alias: string, sub: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3001
3299
  /**
3002
3300
  * Adds a JOIN against a derived table (subquery with alias)
3003
3301
  * @param subquery - Subquery to join
@@ -3007,81 +3305,70 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
3007
3305
  * @param columnAliases - Optional column alias list for the derived table
3008
3306
  * @returns New query builder instance with the derived-table join
3009
3307
  */
3010
- joinSubquery(subquery: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, alias: string, condition: BinaryExpressionNode, joinKind?: JoinKind, columnAliases?: string[]): SelectQueryBuilder<T, TTable>;
3308
+ joinSubquery<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, alias: string, condition: BinaryExpressionNode, joinKind?: JoinKind, columnAliases?: string[]): SelectQueryBuilder<T, TTable>;
3309
+ /**
3310
+ * Adds a join against a function table (e.g., `generate_series`) using `fnTable` internally.
3311
+ * @param name - Function name
3312
+ * @param args - Optional arguments passed to the function
3313
+ * @param alias - Alias for the function table so columns can be referenced
3314
+ * @param condition - Join condition expression
3315
+ * @param joinKind - Kind of join (defaults to INNER)
3316
+ * @param options - Optional metadata (lateral, ordinality, column aliases, schema)
3317
+ */
3318
+ joinFunctionTable(name: string, args: OperandNode[], alias: string, condition: BinaryExpressionNode, joinKind?: JoinKind, options?: {
3319
+ lateral?: boolean;
3320
+ withOrdinality?: boolean;
3321
+ columnAliases?: string[];
3322
+ schema?: string;
3323
+ }): SelectQueryBuilder<T, TTable>;
3011
3324
  /**
3012
-
3013
3325
  * Adds an INNER JOIN to the query
3014
-
3015
3326
  * @param table - Table to join
3016
-
3017
3327
  * @param condition - Join condition expression
3018
-
3019
3328
  * @returns New query builder instance with the INNER JOIN
3020
-
3021
3329
  */
3022
3330
  innerJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable>;
3023
3331
  /**
3024
-
3025
3332
  * Adds a LEFT JOIN to the query
3026
-
3027
3333
  * @param table - Table to join
3028
-
3029
3334
  * @param condition - Join condition expression
3030
-
3031
3335
  * @returns New query builder instance with the LEFT JOIN
3032
-
3033
3336
  */
3034
3337
  leftJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable>;
3035
3338
  /**
3036
-
3037
3339
  * Adds a RIGHT JOIN to the query
3038
-
3039
3340
  * @param table - Table to join
3040
-
3041
3341
  * @param condition - Join condition expression
3042
-
3043
3342
  * @returns New query builder instance with the RIGHT JOIN
3044
-
3045
3343
  */
3046
3344
  rightJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T, TTable>;
3047
3345
  /**
3048
-
3049
3346
  * Matches records based on a relationship
3050
-
3051
3347
  * @param relationName - Name of the relationship to match
3052
-
3053
3348
  * @param predicate - Optional predicate expression
3054
-
3055
3349
  * @returns New query builder instance with the relationship match
3056
-
3057
3350
  */
3058
- match(relationName: string, predicate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3351
+ match<K extends keyof TTable['relations'] & string>(relationName: K, predicate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3059
3352
  /**
3060
-
3061
3353
  * Joins a related table
3062
-
3063
3354
  * @param relationName - Name of the relationship to join
3064
-
3065
3355
  * @param joinKind - Type of join (defaults to INNER)
3066
-
3067
3356
  * @param extraCondition - Optional additional join condition
3068
-
3069
3357
  * @returns New query builder instance with the relationship join
3070
-
3071
3358
  */
3072
- joinRelation(relationName: string, joinKind?: JoinKind, extraCondition?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3359
+ joinRelation<K extends keyof TTable['relations'] & string>(relationName: K, joinKind?: JoinKind, extraCondition?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3073
3360
  /**
3074
-
3075
3361
  * Includes related data in the query results
3076
-
3077
3362
  * @param relationName - Name of the relationship to include
3078
-
3079
3363
  * @param options - Optional include options
3080
-
3081
3364
  * @returns New query builder instance with the relationship inclusion
3082
-
3083
3365
  */
3084
- include(relationName: string, options?: RelationIncludeOptions): SelectQueryBuilder<T, TTable>;
3366
+ include<K extends keyof TTable['relations'] & string>(relationName: K, options?: RelationIncludeOptions): SelectQueryBuilder<T, TTable>;
3367
+ /**
3368
+ * Includes a relation lazily in the query results
3369
+ * @param relationName - Name of the relation to include lazily
3370
+ * @returns New query builder instance with lazy relation inclusion
3371
+ */
3085
3372
  includeLazy<K extends keyof RelationMap<TTable>>(relationName: K): SelectQueryBuilder<T, TTable>;
3086
3373
  /**
3087
3374
  * Selects columns for a related table in a single hop.
@@ -3092,21 +3379,38 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
3092
3379
  */
3093
3380
  includePick<K extends keyof TTable['relations'] & string, TRel extends RelationDef = TTable['relations'][K], TTarget extends TableDef = RelationTargetTable<TRel>, C extends keyof TTarget['columns'] & string = keyof TTarget['columns'] & string>(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable>;
3094
3381
  /**
3095
- * Selects columns for the root table and relations from a single config object.
3382
+ * Selects columns for the root table and relations from an array of entries
3383
+ * @param config - Configuration array for deep column selection
3384
+ * @returns New query builder instance with deep column selections
3096
3385
  */
3097
3386
  selectColumnsDeep(config: DeepSelectConfig<TTable>): SelectQueryBuilder<T, TTable>;
3387
+ /**
3388
+ * Gets the list of lazy relations
3389
+ * @returns Array of lazy relation names
3390
+ */
3098
3391
  getLazyRelations(): (keyof RelationMap<TTable>)[];
3392
+ /**
3393
+ * Gets the table definition for this query builder
3394
+ * @returns Table definition
3395
+ */
3099
3396
  getTable(): TTable;
3397
+ /**
3398
+ * Executes the query and returns hydrated results
3399
+ * @param ctx - ORM session context
3400
+ * @returns Promise of entity instances
3401
+ */
3100
3402
  execute(ctx: OrmSession): Promise<EntityInstance<TTable>[]>;
3403
+ /**
3404
+ * Executes the query with provided execution and hydration contexts
3405
+ * @param execCtx - Execution context
3406
+ * @param hydCtx - Hydration context
3407
+ * @returns Promise of entity instances
3408
+ */
3101
3409
  executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<EntityInstance<TTable>[]>;
3102
3410
  /**
3103
-
3104
3411
  * Adds a WHERE condition to the query
3105
-
3106
3412
  * @param expr - Expression for the WHERE clause
3107
-
3108
3413
  * @returns New query builder instance with the WHERE condition
3109
-
3110
3414
  */
3111
3415
  where(expr: ExpressionNode): SelectQueryBuilder<T, TTable>;
3112
3416
  /**
@@ -3116,13 +3420,9 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
3116
3420
  */
3117
3421
  groupBy(term: ColumnDef | OrderingTerm): SelectQueryBuilder<T, TTable>;
3118
3422
  /**
3119
-
3120
3423
  * Adds a HAVING condition to the query
3121
-
3122
3424
  * @param expr - Expression for the HAVING clause
3123
-
3124
3425
  * @returns New query builder instance with the HAVING condition
3125
-
3126
3426
  */
3127
3427
  having(expr: ExpressionNode): SelectQueryBuilder<T, TTable>;
3128
3428
  /**
@@ -3137,190 +3437,121 @@ declare class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
3137
3437
  collation?: string;
3138
3438
  }): SelectQueryBuilder<T, TTable>;
3139
3439
  /**
3140
-
3141
3440
  * Adds a DISTINCT clause to the query
3142
-
3143
3441
  * @param cols - Columns to make distinct
3144
-
3145
3442
  * @returns New query builder instance with the DISTINCT clause
3146
-
3147
3443
  */
3148
3444
  distinct(...cols: (ColumnDef | ColumnNode)[]): SelectQueryBuilder<T, TTable>;
3149
3445
  /**
3150
-
3151
3446
  * Adds a LIMIT clause to the query
3152
-
3153
3447
  * @param n - Maximum number of rows to return
3154
-
3155
3448
  * @returns New query builder instance with the LIMIT clause
3156
-
3157
3449
  */
3158
3450
  limit(n: number): SelectQueryBuilder<T, TTable>;
3159
3451
  /**
3160
-
3161
3452
  * Adds an OFFSET clause to the query
3162
-
3163
3453
  * @param n - Number of rows to skip
3164
-
3165
3454
  * @returns New query builder instance with the OFFSET clause
3166
-
3167
3455
  */
3168
3456
  offset(n: number): SelectQueryBuilder<T, TTable>;
3169
3457
  /**
3170
-
3171
3458
  * Combines this query with another using UNION
3172
-
3173
3459
  * @param query - Query to union with
3174
-
3175
3460
  * @returns New query builder instance with the set operation
3176
-
3177
3461
  */
3178
- union(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3462
+ union<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3179
3463
  /**
3180
-
3181
3464
  * Combines this query with another using UNION ALL
3182
-
3183
3465
  * @param query - Query to union with
3184
-
3185
3466
  * @returns New query builder instance with the set operation
3186
-
3187
3467
  */
3188
- unionAll(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3468
+ unionAll<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3189
3469
  /**
3190
-
3191
3470
  * Combines this query with another using INTERSECT
3192
-
3193
3471
  * @param query - Query to intersect with
3194
-
3195
3472
  * @returns New query builder instance with the set operation
3196
-
3197
3473
  */
3198
- intersect(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3474
+ intersect<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3199
3475
  /**
3200
-
3201
3476
  * Combines this query with another using EXCEPT
3202
-
3203
3477
  * @param query - Query to subtract
3204
-
3205
3478
  * @returns New query builder instance with the set operation
3206
-
3207
3479
  */
3208
- except(query: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3480
+ except<TSub extends TableDef>(query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode): SelectQueryBuilder<T, TTable>;
3209
3481
  /**
3210
-
3211
3482
  * Adds a WHERE EXISTS condition to the query
3212
-
3213
3483
  * @param subquery - Subquery to check for existence
3214
-
3215
3484
  * @returns New query builder instance with the WHERE EXISTS condition
3216
-
3217
3485
  */
3218
- whereExists(subquery: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, correlate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3486
+ whereExists<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, correlate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3219
3487
  /**
3220
-
3221
3488
  * Adds a WHERE NOT EXISTS condition to the query
3222
-
3223
3489
  * @param subquery - Subquery to check for non-existence
3224
-
3225
3490
  * @returns New query builder instance with the WHERE NOT EXISTS condition
3226
-
3227
3491
  */
3228
- whereNotExists(subquery: SelectQueryBuilder<any, TableDef<any>> | SelectQueryNode, correlate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3492
+ whereNotExists<TSub extends TableDef>(subquery: SelectQueryBuilder<unknown, TSub> | SelectQueryNode, correlate?: ExpressionNode): SelectQueryBuilder<T, TTable>;
3229
3493
  /**
3230
-
3231
3494
  * Adds a WHERE EXISTS condition based on a relationship
3232
-
3233
3495
  * @param relationName - Name of the relationship to check
3234
-
3235
3496
  * @param callback - Optional callback to modify the relationship query
3236
-
3237
3497
  * @returns New query builder instance with the relationship existence check
3238
-
3239
3498
  */
3240
- whereHas(relationName: string, callbackOrOptions?: RelationCallback | WhereHasOptions, maybeOptions?: WhereHasOptions): SelectQueryBuilder<T, TTable>;
3499
+ whereHas<K extends keyof TTable['relations'] & string>(relationName: K, callbackOrOptions?: RelationCallback | WhereHasOptions, maybeOptions?: WhereHasOptions): SelectQueryBuilder<T, TTable>;
3241
3500
  /**
3242
-
3243
3501
  * Adds a WHERE NOT EXISTS condition based on a relationship
3244
-
3245
3502
  * @param relationName - Name of the relationship to check
3246
-
3247
3503
  * @param callback - Optional callback to modify the relationship query
3248
-
3249
3504
  * @returns New query builder instance with the relationship non-existence check
3250
-
3251
3505
  */
3252
- whereHasNot(relationName: string, callbackOrOptions?: RelationCallback | WhereHasOptions, maybeOptions?: WhereHasOptions): SelectQueryBuilder<T, TTable>;
3506
+ whereHasNot<K extends keyof TTable['relations'] & string>(relationName: K, callbackOrOptions?: RelationCallback | WhereHasOptions, maybeOptions?: WhereHasOptions): SelectQueryBuilder<T, TTable>;
3253
3507
  /**
3254
-
3255
3508
  * Compiles the query to SQL for a specific dialect
3256
-
3257
3509
  * @param dialect - Database dialect to compile for
3258
-
3259
3510
  * @returns Compiled query with SQL and parameters
3260
-
3261
3511
  */
3262
3512
  compile(dialect: SelectDialectInput): CompiledQuery;
3263
3513
  /**
3264
-
3265
3514
  * Converts the query to SQL string for a specific dialect
3266
-
3267
3515
  * @param dialect - Database dialect to generate SQL for
3268
-
3269
3516
  * @returns SQL string representation of the query
3270
-
3271
3517
  */
3272
3518
  toSql(dialect: SelectDialectInput): string;
3273
3519
  /**
3274
-
3275
3520
  * Gets the hydration plan for the query
3276
-
3277
3521
  * @returns Hydration plan or undefined if none exists
3278
-
3279
3522
  */
3280
3523
  getHydrationPlan(): HydrationPlan | undefined;
3281
3524
  /**
3282
-
3283
3525
  * Gets the Abstract Syntax Tree (AST) representation of the query
3284
-
3285
3526
  * @returns Query AST with hydration applied
3286
-
3287
3527
  */
3288
3528
  getAST(): SelectQueryNode;
3289
3529
  }
3290
- /**
3291
-
3292
- * Creates a column node for use in expressions
3293
-
3294
- * @param table - Table name
3295
-
3296
- * @param name - Column name
3297
-
3298
- * @returns ColumnNode with the specified table and name
3299
-
3300
- */
3301
- declare const createColumn: (table: string, name: string) => ColumnNode;
3302
- /**
3303
-
3304
- * Creates a literal value node for use in expressions
3305
-
3306
- * @param val - Literal value (string or number)
3307
-
3308
- * @returns LiteralNode with the specified value
3309
-
3310
- */
3311
- declare const createLiteral: (val: string | number) => LiteralNode;
3312
3530
 
3313
3531
  /**
3314
3532
  * Build a typed selection map from a TableDef.
3533
+ * @template TTable - The table definition type
3534
+ * @template K - The column name keys
3535
+ * @param table - The table definition to select columns from
3536
+ * @param cols - Column names to include in the selection
3537
+ * @returns A typed record mapping column names to their definitions
3538
+ * @throws Error if a specified column is not found on the table
3315
3539
  */
3316
3540
  declare function sel<TTable extends TableDef, K extends keyof TTable['columns'] & string>(table: TTable, ...cols: K[]): Record<K, TTable['columns'][K]>;
3317
3541
  type Ctor<T> = {
3318
- new (...args: any[]): T;
3542
+ new (...args: unknown[]): T;
3319
3543
  };
3320
3544
  /**
3321
3545
  * Build a typed selection map from an entity constructor.
3322
- */
3323
- declare function esel<TEntity, K extends keyof TEntity & string>(entity: Ctor<TEntity>, ...props: K[]): Record<K, ColumnDef>;
3546
+ * @template TEntity - The entity type
3547
+ * @template K - The property name keys
3548
+ * @param entity - The entity constructor to get table definition from
3549
+ * @param props - Property names to include in the selection
3550
+ * @returns A record mapping property names to their column definitions
3551
+ * @throws Error if no table definition is registered for the entity
3552
+ * @throws Error if a specified property is not found as a column
3553
+ */
3554
+ declare function esel<TEntity extends object, K extends keyof TEntity & string>(entity: Ctor<TEntity>, ...props: K[]): Record<K, ColumnDef>;
3324
3555
 
3325
3556
  /**
3326
3557
  * Maintains immutable state for building INSERT queries
@@ -3328,14 +3559,44 @@ declare function esel<TEntity, K extends keyof TEntity & string>(entity: Ctor<TE
3328
3559
  declare class InsertQueryState {
3329
3560
  readonly table: TableDef;
3330
3561
  readonly ast: InsertQueryNode;
3562
+ /**
3563
+ * Creates a new InsertQueryState instance
3564
+ * @param table - The table definition for the INSERT query
3565
+ * @param ast - Optional initial AST node, defaults to a basic INSERT query
3566
+ */
3331
3567
  constructor(table: TableDef, ast?: InsertQueryNode);
3332
3568
  private clone;
3333
3569
  private ensureColumnsFromRow;
3334
3570
  private appendValues;
3335
3571
  private getTableColumns;
3572
+ /**
3573
+ * Adds VALUES clause to the INSERT query
3574
+ * @param rows - Array of row objects to insert
3575
+ * @returns A new InsertQueryState with the VALUES clause added
3576
+ * @throws Error if mixing VALUES with SELECT source
3577
+ * @throws Error if invalid values are provided
3578
+ */
3336
3579
  withValues(rows: Record<string, unknown>[]): InsertQueryState;
3580
+ /**
3581
+ * Sets the columns for the INSERT query
3582
+ * @param columns - Column nodes to insert into
3583
+ * @returns A new InsertQueryState with the specified columns
3584
+ */
3337
3585
  withColumns(columns: ColumnNode[]): InsertQueryState;
3586
+ /**
3587
+ * Adds SELECT source to the INSERT query
3588
+ * @param query - The SELECT query to use as source
3589
+ * @param columns - Target columns for the INSERT
3590
+ * @returns A new InsertQueryState with the SELECT source
3591
+ * @throws Error if mixing SELECT with VALUES source
3592
+ * @throws Error if no destination columns specified
3593
+ */
3338
3594
  withSelect(query: SelectQueryNode, columns: ColumnNode[]): InsertQueryState;
3595
+ /**
3596
+ * Adds a RETURNING clause to the INSERT query
3597
+ * @param columns - Columns to return after insertion
3598
+ * @returns A new InsertQueryState with the RETURNING clause added
3599
+ */
3339
3600
  withReturning(columns: ColumnNode[]): InsertQueryState;
3340
3601
  }
3341
3602
 
@@ -3346,17 +3607,63 @@ type InsertDialectInput = Dialect | DialectKey;
3346
3607
  declare class InsertQueryBuilder<T> {
3347
3608
  private readonly table;
3348
3609
  private readonly state;
3610
+ /**
3611
+ * Creates a new InsertQueryBuilder instance
3612
+ * @param table - The table definition for the INSERT query
3613
+ * @param state - Optional initial query state, defaults to a new InsertQueryState
3614
+ */
3349
3615
  constructor(table: TableDef, state?: InsertQueryState);
3350
3616
  private clone;
3617
+ /**
3618
+ * Adds VALUES to the INSERT query
3619
+ * @param rowOrRows - Single row object or array of row objects to insert
3620
+ * @returns A new InsertQueryBuilder with the VALUES clause added
3621
+ */
3351
3622
  values(rowOrRows: Record<string, unknown> | Record<string, unknown>[]): InsertQueryBuilder<T>;
3623
+ /**
3624
+ * Specifies the columns for the INSERT query
3625
+ * @param columns - Column definitions or nodes to insert into
3626
+ * @returns A new InsertQueryBuilder with the specified columns
3627
+ */
3352
3628
  columns(...columns: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T>;
3353
- fromSelect(query: SelectQueryNode | SelectQueryBuilder<any, TableDef<any>>, columns?: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T>;
3629
+ /**
3630
+ * Sets the source of the INSERT query to a SELECT query
3631
+ * @template TSource - The source table type
3632
+ * @param query - The SELECT query or query builder to use as source
3633
+ * @param columns - Optional target columns for the INSERT
3634
+ * @returns A new InsertQueryBuilder with the SELECT source
3635
+ */
3636
+ fromSelect<TSource extends TableDef>(query: SelectQueryNode | SelectQueryBuilder<unknown, TSource>, columns?: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T>;
3637
+ /**
3638
+ * Adds a RETURNING clause to the INSERT query
3639
+ * @param columns - Columns to return after insertion
3640
+ * @returns A new InsertQueryBuilder with the RETURNING clause added
3641
+ */
3354
3642
  returning(...columns: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T>;
3355
3643
  private resolveColumnNodes;
3356
3644
  private resolveSelectQuery;
3645
+ /**
3646
+ * Compiles the INSERT query
3647
+ * @param compiler - The INSERT compiler to use
3648
+ * @returns The compiled query with SQL and parameters
3649
+ */
3357
3650
  compile(compiler: InsertCompiler): CompiledQuery;
3651
+ /**
3652
+ * Compiles the INSERT query for the specified dialect
3653
+ * @param dialect - The SQL dialect to compile for
3654
+ * @returns The compiled query with SQL and parameters
3655
+ */
3358
3656
  compile(dialect: InsertDialectInput): CompiledQuery;
3657
+ /**
3658
+ * Returns the SQL string for the INSERT query
3659
+ * @param arg - The compiler or dialect to generate SQL for
3660
+ * @returns The SQL string representation of the query
3661
+ */
3359
3662
  toSql(arg: InsertCompiler | InsertDialectInput): string;
3663
+ /**
3664
+ * Returns the Abstract Syntax Tree (AST) representation of the query
3665
+ * @returns The AST node for the INSERT query
3666
+ */
3360
3667
  getAST(): InsertQueryNode;
3361
3668
  }
3362
3669
 
@@ -3366,13 +3673,53 @@ declare class InsertQueryBuilder<T> {
3366
3673
  declare class UpdateQueryState {
3367
3674
  readonly table: TableDef;
3368
3675
  readonly ast: UpdateQueryNode;
3676
+ /**
3677
+ * Creates a new UpdateQueryState instance
3678
+ * @param table - Table definition for the update
3679
+ * @param ast - Optional existing AST
3680
+ */
3369
3681
  constructor(table: TableDef, ast?: UpdateQueryNode);
3682
+ /**
3683
+ * Creates a new UpdateQueryState with updated AST
3684
+ * @param nextAst - Updated AST
3685
+ * @returns New UpdateQueryState instance
3686
+ */
3370
3687
  private clone;
3688
+ /**
3689
+ * Sets the columns to update with their new values
3690
+ * @param values - Record of column names to values
3691
+ * @returns New UpdateQueryState with SET clause
3692
+ */
3371
3693
  withSet(values: Record<string, unknown>): UpdateQueryState;
3694
+ /**
3695
+ * Adds a WHERE condition to the update query
3696
+ * @param expr - WHERE expression
3697
+ * @returns New UpdateQueryState with WHERE clause
3698
+ */
3372
3699
  withWhere(expr: ExpressionNode): UpdateQueryState;
3700
+ /**
3701
+ * Adds a RETURNING clause to the update query
3702
+ * @param columns - Columns to return
3703
+ * @returns New UpdateQueryState with RETURNING clause
3704
+ */
3373
3705
  withReturning(columns: ColumnNode[]): UpdateQueryState;
3706
+ /**
3707
+ * Sets the FROM clause for the update query
3708
+ * @param from - Table source for FROM
3709
+ * @returns New UpdateQueryState with FROM clause
3710
+ */
3374
3711
  withFrom(from: TableSourceNode): UpdateQueryState;
3712
+ /**
3713
+ * Adds a JOIN to the update query
3714
+ * @param join - Join node to add
3715
+ * @returns New UpdateQueryState with JOIN
3716
+ */
3375
3717
  withJoin(join: JoinNode): UpdateQueryState;
3718
+ /**
3719
+ * Applies an alias to the table being updated
3720
+ * @param alias - Alias for the table
3721
+ * @returns New UpdateQueryState with table alias
3722
+ */
3376
3723
  withTableAlias(alias: string): UpdateQueryState;
3377
3724
  }
3378
3725
 
@@ -3383,19 +3730,76 @@ type UpdateDialectInput = Dialect | DialectKey;
3383
3730
  declare class UpdateQueryBuilder<T> {
3384
3731
  private readonly table;
3385
3732
  private readonly state;
3733
+ /**
3734
+ * Creates a new UpdateQueryBuilder instance
3735
+ * @param table - The table definition for the UPDATE query
3736
+ * @param state - Optional initial query state, defaults to a new UpdateQueryState
3737
+ */
3386
3738
  constructor(table: TableDef, state?: UpdateQueryState);
3387
3739
  private clone;
3740
+ /**
3741
+ * Sets an alias for the table in the UPDATE query
3742
+ * @param alias - The alias to assign to the table
3743
+ * @returns A new UpdateQueryBuilder with the table alias set
3744
+ */
3388
3745
  as(alias: string): UpdateQueryBuilder<T>;
3746
+ /**
3747
+ * Adds a FROM clause to the UPDATE query
3748
+ * @param source - The table source to use in the FROM clause
3749
+ * @returns A new UpdateQueryBuilder with the FROM clause added
3750
+ */
3389
3751
  from(source: TableDef | TableSourceNode): UpdateQueryBuilder<T>;
3752
+ /**
3753
+ * Adds a JOIN clause to the UPDATE query
3754
+ * @param table - The table to join with
3755
+ * @param condition - The join condition expression
3756
+ * @param kind - The type of join (defaults to INNER)
3757
+ * @param relationName - Optional name for the relation
3758
+ * @returns A new UpdateQueryBuilder with the JOIN clause added
3759
+ */
3390
3760
  join(table: TableDef | TableSourceNode | string, condition: ExpressionNode, kind?: JoinKind, relationName?: string): UpdateQueryBuilder<T>;
3761
+ /**
3762
+ * Adds a SET clause to the UPDATE query
3763
+ * @param values - The column-value pairs to update
3764
+ * @returns A new UpdateQueryBuilder with the SET clause added
3765
+ */
3391
3766
  set(values: Record<string, unknown>): UpdateQueryBuilder<T>;
3767
+ /**
3768
+ * Adds a WHERE clause to the UPDATE query
3769
+ * @param expr - The expression to use as the WHERE condition
3770
+ * @returns A new UpdateQueryBuilder with the WHERE clause added
3771
+ */
3392
3772
  where(expr: ExpressionNode): UpdateQueryBuilder<T>;
3773
+ /**
3774
+ * Adds a RETURNING clause to the UPDATE query
3775
+ * @param columns - Columns to return after update
3776
+ * @returns A new UpdateQueryBuilder with the RETURNING clause added
3777
+ */
3393
3778
  returning(...columns: (ColumnDef | ColumnNode)[]): UpdateQueryBuilder<T>;
3394
3779
  private resolveTableSource;
3395
3780
  private resolveJoinTarget;
3396
- compile(compiler: UpdateCompiler): CompiledQuery;
3781
+ /**
3782
+ * Compiles the UPDATE query for the specified dialect
3783
+ * @param dialect - The SQL dialect to compile for
3784
+ * @returns The compiled query with SQL and parameters
3785
+ */
3397
3786
  compile(dialect: UpdateDialectInput): CompiledQuery;
3398
- toSql(arg: UpdateCompiler | UpdateDialectInput): string;
3787
+ /**
3788
+ * Returns the SQL string for the UPDATE query
3789
+ * @param dialect - The SQL dialect to generate SQL for
3790
+ * @returns The SQL string representation of the query
3791
+ */
3792
+ toSql(dialect: UpdateDialectInput): string;
3793
+ /**
3794
+ * Executes the UPDATE query using the provided session
3795
+ * @param session - The ORM session to execute the query with
3796
+ * @returns A promise that resolves to the query results
3797
+ */
3798
+ execute(session: OrmSession): Promise<QueryResult[]>;
3799
+ /**
3800
+ * Returns the Abstract Syntax Tree (AST) representation of the query
3801
+ * @returns The AST node for the UPDATE query
3802
+ */
3399
3803
  getAST(): UpdateQueryNode;
3400
3804
  }
3401
3805
 
@@ -3405,12 +3809,42 @@ declare class UpdateQueryBuilder<T> {
3405
3809
  declare class DeleteQueryState {
3406
3810
  readonly table: TableDef;
3407
3811
  readonly ast: DeleteQueryNode;
3812
+ /**
3813
+ * Creates a new DeleteQueryState instance
3814
+ * @param table - The table definition for the DELETE query
3815
+ * @param ast - Optional initial AST node, defaults to a basic DELETE query
3816
+ */
3408
3817
  constructor(table: TableDef, ast?: DeleteQueryNode);
3409
3818
  private clone;
3819
+ /**
3820
+ * Adds a WHERE clause to the DELETE query
3821
+ * @param expr - The expression to use as the WHERE condition
3822
+ * @returns A new DeleteQueryState with the WHERE clause added
3823
+ */
3410
3824
  withWhere(expr: ExpressionNode): DeleteQueryState;
3825
+ /**
3826
+ * Adds a RETURNING clause to the DELETE query
3827
+ * @param columns - The columns to return after deletion
3828
+ * @returns A new DeleteQueryState with the RETURNING clause added
3829
+ */
3411
3830
  withReturning(columns: ColumnNode[]): DeleteQueryState;
3831
+ /**
3832
+ * Adds a USING clause to the DELETE query
3833
+ * @param source - The table source to use in the USING clause
3834
+ * @returns A new DeleteQueryState with the USING clause added
3835
+ */
3412
3836
  withUsing(source: TableSourceNode): DeleteQueryState;
3837
+ /**
3838
+ * Adds a JOIN clause to the DELETE query
3839
+ * @param join - The join node to add
3840
+ * @returns A new DeleteQueryState with the JOIN clause added
3841
+ */
3413
3842
  withJoin(join: JoinNode): DeleteQueryState;
3843
+ /**
3844
+ * Sets an alias for the table in the DELETE query
3845
+ * @param alias - The alias to assign to the table
3846
+ * @returns A new DeleteQueryState with the table alias set
3847
+ */
3414
3848
  withTableAlias(alias: string): DeleteQueryState;
3415
3849
  }
3416
3850
 
@@ -3421,18 +3855,70 @@ type DeleteDialectInput = Dialect | DialectKey;
3421
3855
  declare class DeleteQueryBuilder<T> {
3422
3856
  private readonly table;
3423
3857
  private readonly state;
3858
+ /**
3859
+ * Creates a new DeleteQueryBuilder instance
3860
+ * @param table - The table definition for the DELETE query
3861
+ * @param state - Optional initial query state, defaults to a new DeleteQueryState
3862
+ */
3424
3863
  constructor(table: TableDef, state?: DeleteQueryState);
3425
3864
  private clone;
3865
+ /**
3866
+ * Adds a WHERE clause to the DELETE query
3867
+ * @param expr - The expression to use as the WHERE condition
3868
+ * @returns A new DeleteQueryBuilder with the WHERE clause added
3869
+ */
3426
3870
  where(expr: ExpressionNode): DeleteQueryBuilder<T>;
3871
+ /**
3872
+ * Sets an alias for the table in the DELETE query
3873
+ * @param alias - The alias to assign to the table
3874
+ * @returns A new DeleteQueryBuilder with the table alias set
3875
+ */
3427
3876
  as(alias: string): DeleteQueryBuilder<T>;
3877
+ /**
3878
+ * Adds a USING clause to the DELETE query
3879
+ * @param source - The table source to use in the USING clause
3880
+ * @returns A new DeleteQueryBuilder with the USING clause added
3881
+ */
3428
3882
  using(source: TableDef | TableSourceNode): DeleteQueryBuilder<T>;
3883
+ /**
3884
+ * Adds a JOIN clause to the DELETE query
3885
+ * @param table - The table to join with
3886
+ * @param condition - The join condition expression
3887
+ * @param kind - The type of join (defaults to INNER)
3888
+ * @param relationName - Optional name for the relation
3889
+ * @returns A new DeleteQueryBuilder with the JOIN clause added
3890
+ */
3429
3891
  join(table: TableDef | TableSourceNode | string, condition: ExpressionNode, kind?: JoinKind, relationName?: string): DeleteQueryBuilder<T>;
3892
+ /**
3893
+ * Adds a RETURNING clause to the DELETE query
3894
+ * @param columns - The columns to return after deletion
3895
+ * @returns A new DeleteQueryBuilder with the RETURNING clause added
3896
+ */
3430
3897
  returning(...columns: (ColumnDef | ColumnNode)[]): DeleteQueryBuilder<T>;
3431
3898
  private resolveTableSource;
3432
3899
  private resolveJoinTarget;
3433
- compile(compiler: DeleteCompiler): CompiledQuery;
3900
+ /**
3901
+ * Compiles the DELETE query for the specified dialect
3902
+ * @param dialect - The SQL dialect to compile for
3903
+ * @returns The compiled query with SQL and parameters
3904
+ */
3434
3905
  compile(dialect: DeleteDialectInput): CompiledQuery;
3435
- toSql(arg: DeleteCompiler | DeleteDialectInput): string;
3906
+ /**
3907
+ * Returns the SQL string for the DELETE query
3908
+ * @param dialect - The SQL dialect to generate SQL for
3909
+ * @returns The SQL string representation of the query
3910
+ */
3911
+ toSql(dialect: DeleteDialectInput): string;
3912
+ /**
3913
+ * Executes the DELETE query using the provided session
3914
+ * @param session - The ORM session to execute the query with
3915
+ * @returns A promise that resolves to the query results
3916
+ */
3917
+ execute(session: OrmSession): Promise<QueryResult[]>;
3918
+ /**
3919
+ * Returns the Abstract Syntax Tree (AST) representation of the query
3920
+ * @returns The AST node for the DELETE query
3921
+ */
3436
3922
  getAST(): DeleteQueryNode;
3437
3923
  }
3438
3924
 
@@ -3629,12 +4115,14 @@ declare class PostgresDialect extends SqlDialectBase {
3629
4115
  supportsReturning(): boolean;
3630
4116
  }
3631
4117
 
4118
+ /** Represents the differences detected in a database column's properties. */
3632
4119
  interface ColumnDiff {
3633
4120
  typeChanged?: boolean;
3634
4121
  nullabilityChanged?: boolean;
3635
4122
  defaultChanged?: boolean;
3636
4123
  autoIncrementChanged?: boolean;
3637
4124
  }
4125
+ /** Represents a column in the database schema. */
3638
4126
  interface DatabaseColumn {
3639
4127
  name: string;
3640
4128
  type: string;
@@ -3646,16 +4134,19 @@ interface DatabaseColumn {
3646
4134
  references?: ForeignKeyReference;
3647
4135
  check?: string;
3648
4136
  }
4137
+ /** Represents an index in the database schema. */
3649
4138
  interface DatabaseIndex {
3650
4139
  name: string;
3651
4140
  columns: IndexColumn[];
3652
4141
  unique?: boolean;
3653
4142
  where?: string;
3654
4143
  }
4144
+ /** Represents a check constraint in the database schema. */
3655
4145
  interface DatabaseCheck {
3656
4146
  name?: string;
3657
4147
  expression: string;
3658
4148
  }
4149
+ /** Represents a table in the database schema. */
3659
4150
  interface DatabaseTable {
3660
4151
  name: string;
3661
4152
  schema?: string;
@@ -3664,45 +4155,90 @@ interface DatabaseTable {
3664
4155
  indexes?: DatabaseIndex[];
3665
4156
  checks?: DatabaseCheck[];
3666
4157
  }
4158
+ /** Represents the overall database schema. */
3667
4159
  interface DatabaseSchema {
3668
4160
  tables: DatabaseTable[];
3669
4161
  }
3670
4162
 
4163
+ /** The name of a database dialect. */
3671
4164
  type DialectName = 'postgres' | 'mysql' | 'sqlite' | 'mssql' | (string & {});
4165
+ /** Interface for schema dialect implementations that handle database-specific DDL operations. */
3672
4166
  interface SchemaDialect {
4167
+ /** The name of the dialect. */
3673
4168
  readonly name: DialectName;
4169
+ /** Quotes an identifier for use in SQL. */
3674
4170
  quoteIdentifier(id: string): string;
4171
+ /** Formats the table name for SQL. */
3675
4172
  formatTableName(table: TableDef | DatabaseTable): string;
4173
+ /** Renders the column type for SQL. */
3676
4174
  renderColumnType(column: ColumnDef): string;
4175
+ /** Renders the default value for SQL. */
3677
4176
  renderDefault(value: unknown, column: ColumnDef): string;
4177
+ /** Renders the auto-increment clause for SQL. */
3678
4178
  renderAutoIncrement(column: ColumnDef, table: TableDef): string | undefined;
4179
+ /** Renders a foreign key reference for SQL. */
3679
4180
  renderReference(ref: ForeignKeyReference, table: TableDef): string;
4181
+ /** Renders an index for SQL. */
3680
4182
  renderIndex(table: TableDef, index: IndexDef): string;
4183
+ /** Renders table options for SQL. */
3681
4184
  renderTableOptions(table: TableDef): string | undefined;
4185
+ /** Checks if the dialect supports partial indexes. */
3682
4186
  supportsPartialIndexes(): boolean;
4187
+ /** Checks if the dialect prefers inline primary key auto-increment. */
4188
+ preferInlinePkAutoincrement(column: ColumnDef, table: TableDef, pk: string[]): boolean;
4189
+ /** Generates SQL to drop a column. */
3683
4190
  dropColumnSql?(table: DatabaseTable, column: string): string[];
4191
+ /** Generates SQL to drop an index. */
3684
4192
  dropIndexSql?(table: DatabaseTable, index: string): string[];
4193
+ /** Generates SQL to drop a table. */
3685
4194
  dropTableSql?(table: DatabaseTable): string[];
4195
+ /** Returns a warning message for dropping a column. */
3686
4196
  warnDropColumn?(table: DatabaseTable, column: string): string | undefined;
4197
+ /** Generates SQL to alter a column. */
3687
4198
  alterColumnSql?(table: TableDef, column: ColumnDef, actualColumn: DatabaseColumn, diff: ColumnDiff): string[];
4199
+ /** Returns a warning message for altering a column. */
3688
4200
  warnAlterColumn?(table: TableDef, column: ColumnDef, actualColumn: DatabaseColumn, diff: ColumnDiff): string | undefined;
3689
4201
  }
3690
4202
 
4203
+ /** Result of generating schema SQL. */
3691
4204
  interface SchemaGenerateResult {
3692
4205
  tableSql: string;
3693
4206
  indexSql: string[];
3694
4207
  }
4208
+ /** Options for rendering column definitions. */
3695
4209
  interface RenderColumnOptions {
3696
4210
  includePrimary?: boolean;
3697
4211
  }
4212
+ /**
4213
+ * Renders a column definition for SQL.
4214
+ * @param table - The table definition.
4215
+ * @param col - The column definition.
4216
+ * @param dialect - The schema dialect.
4217
+ * @param options - Options for rendering.
4218
+ * @returns The rendered SQL and whether primary key is inline.
4219
+ */
3698
4220
  declare const renderColumnDefinition: (table: TableDef, col: ColumnDef, dialect: SchemaDialect, options?: RenderColumnOptions) => {
3699
4221
  sql: string;
3700
4222
  inlinePrimary: boolean;
3701
4223
  };
4224
+ /**
4225
+ * Generates SQL to create a table.
4226
+ * @param table - The table definition.
4227
+ * @param dialect - The schema dialect.
4228
+ * @returns The table SQL and index SQL.
4229
+ */
3702
4230
  declare const generateCreateTableSql: (table: TableDef, dialect: SchemaDialect) => SchemaGenerateResult;
4231
+ /**
4232
+ * Generates SQL for creating multiple tables.
4233
+ * @param tables - The table definitions.
4234
+ * @param dialect - The schema dialect.
4235
+ * @returns The SQL statements.
4236
+ */
3703
4237
  declare const generateSchemaSql: (tables: TableDef[], dialect: SchemaDialect) => string[];
3704
4238
 
4239
+ /** The kind of schema change. */
3705
4240
  type SchemaChangeKind = 'createTable' | 'dropTable' | 'addColumn' | 'dropColumn' | 'alterColumn' | 'addIndex' | 'dropIndex';
4241
+ /** Represents a single schema change. */
3706
4242
  interface SchemaChange {
3707
4243
  kind: SchemaChangeKind;
3708
4244
  table: string;
@@ -3710,22 +4246,48 @@ interface SchemaChange {
3710
4246
  statements: string[];
3711
4247
  safe: boolean;
3712
4248
  }
4249
+ /** Represents a plan of schema changes. */
3713
4250
  interface SchemaPlan {
3714
4251
  changes: SchemaChange[];
3715
4252
  warnings: string[];
3716
4253
  }
4254
+ /** Options for schema diffing. */
3717
4255
  interface SchemaDiffOptions {
3718
4256
  /** Allow destructive operations (drops) */
3719
4257
  allowDestructive?: boolean;
3720
4258
  }
4259
+ /**
4260
+ * Computes the differences between expected and actual database schemas.
4261
+ * @param expectedTables - The expected table definitions.
4262
+ * @param actualSchema - The actual database schema.
4263
+ * @param dialect - The schema dialect.
4264
+ * @param options - Options for the diff.
4265
+ * @returns The schema plan with changes and warnings.
4266
+ */
3721
4267
  declare const diffSchema: (expectedTables: TableDef[], actualSchema: DatabaseSchema, dialect: SchemaDialect, options?: SchemaDiffOptions) => SchemaPlan;
4268
+ /** Options for schema synchronization. */
3722
4269
  interface SynchronizeOptions extends SchemaDiffOptions {
3723
4270
  dryRun?: boolean;
3724
4271
  }
4272
+ /**
4273
+ * Synchronizes the database schema with the expected tables.
4274
+ * @param expectedTables - The expected table definitions.
4275
+ * @param actualSchema - The actual database schema.
4276
+ * @param dialect - The schema dialect.
4277
+ * @param executor - The database executor.
4278
+ * @param options - Options for synchronization.
4279
+ * @returns The schema plan with changes and warnings.
4280
+ */
3725
4281
  declare const synchronizeSchema: (expectedTables: TableDef[], actualSchema: DatabaseSchema, dialect: SchemaDialect, executor: DbExecutor, options?: SynchronizeOptions) => Promise<SchemaPlan>;
3726
4282
 
4283
+ /**
4284
+ * Context for schema introspection operations.
4285
+ * Provides the necessary components to perform database schema introspection.
4286
+ */
3727
4287
  interface IntrospectContext {
4288
+ /** The database dialect used for introspection. */
3728
4289
  dialect: Dialect;
4290
+ /** The database executor for running introspection queries. */
3729
4291
  executor: DbExecutor;
3730
4292
  }
3731
4293
 
@@ -3750,342 +4312,528 @@ interface SchemaIntrospector {
3750
4312
  */
3751
4313
  declare const introspectSchema: (executor: DbExecutor, dialect: DialectName, options?: IntrospectOptions) => Promise<DatabaseSchema>;
3752
4314
 
4315
+ /**
4316
+ * Registers a schema introspector for a dialect.
4317
+ * @param dialect - The dialect name.
4318
+ * @param introspector - The schema introspector.
4319
+ */
3753
4320
  declare const registerSchemaIntrospector: (dialect: DialectName, introspector: SchemaIntrospector) => void;
4321
+ /**
4322
+ * Gets the schema introspector for a dialect.
4323
+ * @param dialect - The dialect name.
4324
+ * @returns The schema introspector or undefined if not found.
4325
+ */
3754
4326
  declare const getSchemaIntrospector: (dialect: DialectName) => SchemaIntrospector | undefined;
3755
4327
 
3756
4328
  type OperandInput$2 = OperandNode | ColumnDef | string | number | boolean | null;
3757
4329
  /**
3758
- * Helper: LOWER(str)
4330
+ * Converts a string to lowercase.
4331
+ * @param value - The string value.
4332
+ * @returns A FunctionNode representing the LOWER SQL function.
3759
4333
  */
3760
4334
  declare const lower: (value: OperandInput$2) => FunctionNode;
3761
4335
  /**
3762
- * Helper: UPPER(str)
4336
+ * Converts a string to uppercase.
4337
+ * @param value - The string value.
4338
+ * @returns A FunctionNode representing the UPPER SQL function.
3763
4339
  */
3764
4340
  declare const upper: (value: OperandInput$2) => FunctionNode;
3765
4341
  /**
3766
- * Helper: ASCII(str)
4342
+ * Returns the ASCII code of the first character of a string.
4343
+ * @param value - The string value.
4344
+ * @returns A FunctionNode representing the ASCII SQL function.
3767
4345
  */
3768
4346
  declare const ascii: (value: OperandInput$2) => FunctionNode;
3769
4347
  /**
3770
- * Helper: CHAR(code[, code...])
4348
+ * Returns a string from one or more ASCII codes.
4349
+ * @param codes - The ASCII codes.
4350
+ * @returns A FunctionNode representing the CHAR SQL function.
3771
4351
  */
3772
4352
  declare const char: (...codes: OperandInput$2[]) => FunctionNode;
3773
4353
  /**
3774
- * Helper: CHAR_LENGTH(str)
4354
+ * Returns the number of characters in a string.
4355
+ * @param value - The string value.
4356
+ * @returns A FunctionNode representing the CHAR_LENGTH SQL function.
3775
4357
  */
3776
4358
  declare const charLength: (value: OperandInput$2) => FunctionNode;
3777
4359
  /**
3778
- * Helper: LENGTH(str)
4360
+ * Returns the length of a string in bytes or characters.
4361
+ * @param value - The string value.
4362
+ * @returns A FunctionNode representing the LENGTH SQL function.
3779
4363
  */
3780
4364
  declare const length: (value: OperandInput$2) => FunctionNode;
3781
4365
  /**
3782
- * Helper: TRIM([chars FROM] str)
4366
+ * Removes leading and trailing whitespace or specified characters from a string.
4367
+ * @param value - The string value.
4368
+ * @param chars - The characters to trim (optional).
4369
+ * @returns A FunctionNode representing the TRIM SQL function.
3783
4370
  */
3784
4371
  declare const trim: (value: OperandInput$2, chars?: OperandInput$2) => FunctionNode;
3785
4372
  /**
3786
- * Helper: LTRIM(str)
4373
+ * Removes leading whitespace from a string.
4374
+ * @param value - The string value.
4375
+ * @returns A FunctionNode representing the LTRIM SQL function.
3787
4376
  */
3788
4377
  declare const ltrim: (value: OperandInput$2) => FunctionNode;
3789
4378
  /**
3790
- * Helper: RTRIM(str)
4379
+ * Removes trailing whitespace from a string.
4380
+ * @param value - The string value.
4381
+ * @returns A FunctionNode representing the RTRIM SQL function.
3791
4382
  */
3792
4383
  declare const rtrim: (value: OperandInput$2) => FunctionNode;
3793
4384
  /**
3794
- * Helper: CONCAT(arg1, arg2, ...)
4385
+ * Concatenates two or more strings.
4386
+ * @param args - The strings to concatenate.
4387
+ * @returns A FunctionNode representing the CONCAT SQL function.
3795
4388
  */
3796
4389
  declare const concat: (...args: OperandInput$2[]) => FunctionNode;
3797
4390
  /**
3798
- * Helper: CONCAT_WS(separator, arg1, arg2, ...)
4391
+ * Concatenates strings with a separator.
4392
+ * @param separator - The separator string.
4393
+ * @param args - The strings to concatenate.
4394
+ * @returns A FunctionNode representing the CONCAT_WS SQL function.
3799
4395
  */
3800
4396
  declare const concatWs: (separator: OperandInput$2, ...args: OperandInput$2[]) => FunctionNode;
3801
4397
  /**
3802
- * Helper: SUBSTR(str, start[, length])
4398
+ * Extracts a substring from a string.
4399
+ * @param value - The string value.
4400
+ * @param start - The starting position.
4401
+ * @param length - The length of the substring (optional).
4402
+ * @returns A FunctionNode representing the SUBSTR SQL function.
3803
4403
  */
3804
4404
  declare const substr: (value: OperandInput$2, start: OperandInput$2, length?: OperandInput$2) => FunctionNode;
3805
4405
  /**
3806
- * Helper: LEFT(str, length)
4406
+ * Returns the leftmost characters of a string.
4407
+ * @param value - The string value.
4408
+ * @param len - The number of characters to return.
4409
+ * @returns A FunctionNode representing the LEFT SQL function.
3807
4410
  */
3808
4411
  declare const left: (value: OperandInput$2, len: OperandInput$2) => FunctionNode;
3809
4412
  /**
3810
- * Helper: RIGHT(str, length)
4413
+ * Returns the rightmost characters of a string.
4414
+ * @param value - The string value.
4415
+ * @param len - The number of characters to return.
4416
+ * @returns A FunctionNode representing the RIGHT SQL function.
3811
4417
  */
3812
4418
  declare const right: (value: OperandInput$2, len: OperandInput$2) => FunctionNode;
3813
4419
  /**
3814
- * Helper: POSITION(substring IN string)
4420
+ * Returns the position of a substring in a string.
4421
+ * @param substring - The substring to search for.
4422
+ * @param value - The string to search in.
4423
+ * @returns A FunctionNode representing the POSITION SQL function.
3815
4424
  */
3816
4425
  declare const position: (substring: OperandInput$2, value: OperandInput$2) => FunctionNode;
3817
4426
  /**
3818
- * Helper: INSTR(string, substring)
4427
+ * Returns the position of a substring in a string.
4428
+ * @param value - The string to search in.
4429
+ * @param substring - The substring to search for.
4430
+ * @returns A FunctionNode representing the INSTR SQL function.
3819
4431
  */
3820
4432
  declare const instr: (value: OperandInput$2, substring: OperandInput$2) => FunctionNode;
3821
4433
  /**
3822
- * Helper: LOCATE(substring, string[, start])
4434
+ * Returns the position of a substring in a string, optionally starting from a position.
4435
+ * @param substring - The substring to search for.
4436
+ * @param value - The string to search in.
4437
+ * @param start - The starting position (optional).
4438
+ * @returns A FunctionNode representing the LOCATE SQL function.
3823
4439
  */
3824
4440
  declare const locate: (substring: OperandInput$2, value: OperandInput$2, start?: OperandInput$2) => FunctionNode;
3825
4441
  /**
3826
- * Helper: REPLACE(string, search, replace)
4442
+ * Replaces occurrences of a substring in a string.
4443
+ * @param value - The string to search in.
4444
+ * @param search - The substring to replace.
4445
+ * @param replacement - The replacement string.
4446
+ * @returns A FunctionNode representing the REPLACE SQL function.
3827
4447
  */
3828
4448
  declare const replace: (value: OperandInput$2, search: OperandInput$2, replacement: OperandInput$2) => FunctionNode;
3829
4449
  /**
3830
- * Helper: REPEAT(string, count)
4450
+ * Repeats a string a specified number of times.
4451
+ * @param value - The string to repeat.
4452
+ * @param count - The number of times to repeat.
4453
+ * @returns A FunctionNode representing the REPEAT SQL function.
3831
4454
  */
3832
4455
  declare const repeat: (value: OperandInput$2, count: OperandInput$2) => FunctionNode;
3833
4456
  /**
3834
- * Helper: LPAD(string, length, padstr)
4457
+ * Left-pads a string to a certain length with another string.
4458
+ * @param value - The string to pad.
4459
+ * @param len - The length to pad to.
4460
+ * @param pad - The padding string.
4461
+ * @returns A FunctionNode representing the LPAD SQL function.
3835
4462
  */
3836
4463
  declare const lpad: (value: OperandInput$2, len: OperandInput$2, pad: OperandInput$2) => FunctionNode;
3837
4464
  /**
3838
- * Helper: RPAD(string, length, padstr)
4465
+ * Right-pads a string to a certain length with another string.
4466
+ * @param value - The string to pad.
4467
+ * @param len - The length to pad to.
4468
+ * @param pad - The padding string.
4469
+ * @returns A FunctionNode representing the RPAD SQL function.
3839
4470
  */
3840
4471
  declare const rpad: (value: OperandInput$2, len: OperandInput$2, pad: OperandInput$2) => FunctionNode;
3841
4472
  /**
3842
- * Helper: SPACE(count)
4473
+ * Returns a string consisting of a specified number of spaces.
4474
+ * @param count - The number of spaces.
4475
+ * @returns A FunctionNode representing the SPACE SQL function.
3843
4476
  */
3844
4477
  declare const space: (count: OperandInput$2) => FunctionNode;
3845
4478
 
3846
4479
  type OperandInput$1 = OperandNode | ColumnDef | string | number | boolean | null;
3847
4480
  /**
3848
- * Helper: ABS(x) - Returns the absolute value of a number
4481
+ * Returns the absolute value of a number.
4482
+ * @param value - The numeric value.
4483
+ * @returns A FunctionNode representing the ABS SQL function.
3849
4484
  */
3850
4485
  declare const abs: (value: OperandInput$1) => FunctionNode;
3851
4486
  /**
3852
- * Helper: ACOS(x) - Returns the arccosine (inverse cosine)
4487
+ * Returns the arccosine (inverse cosine) of a number.
4488
+ * @param value - The numeric value.
4489
+ * @returns A FunctionNode representing the ACOS SQL function.
3853
4490
  */
3854
4491
  declare const acos: (value: OperandInput$1) => FunctionNode;
3855
4492
  /**
3856
- * Helper: ASIN(x) - Returns the arcsine (inverse sine)
4493
+ * Returns the arcsine (inverse sine) of a number.
4494
+ * @param value - The numeric value.
4495
+ * @returns A FunctionNode representing the ASIN SQL function.
3857
4496
  */
3858
4497
  declare const asin: (value: OperandInput$1) => FunctionNode;
3859
4498
  /**
3860
- * Helper: ATAN(x) - Returns the arctangent (inverse tangent)
4499
+ * Returns the arctangent (inverse tangent) of a number.
4500
+ * @param value - The numeric value.
4501
+ * @returns A FunctionNode representing the ATAN SQL function.
3861
4502
  */
3862
4503
  declare const atan: (value: OperandInput$1) => FunctionNode;
3863
4504
  /**
3864
- * Helper: ATAN2(y, x) - Returns the arctangent of the two arguments
4505
+ * Returns the arctangent of the two arguments.
4506
+ * @param y - The y-coordinate.
4507
+ * @param x - The x-coordinate.
4508
+ * @returns A FunctionNode representing the ATAN2 SQL function.
3865
4509
  */
3866
4510
  declare const atan2: (y: OperandInput$1, x: OperandInput$1) => FunctionNode;
3867
4511
  /**
3868
- * Helper: CEIL(x) / CEILING(x) - Returns the smallest integer >= x
4512
+ * Returns the smallest integer greater than or equal to a number.
4513
+ * @param value - The numeric value.
4514
+ * @returns A FunctionNode representing the CEIL SQL function.
3869
4515
  */
3870
4516
  declare const ceil: (value: OperandInput$1) => FunctionNode;
3871
4517
  /**
3872
- * Helper: CEILING(x) - Alias for CEIL
4518
+ * Alias for ceil. Returns the smallest integer greater than or equal to a number.
4519
+ * @param value - The numeric value.
4520
+ * @returns A FunctionNode representing the CEILING SQL function.
3873
4521
  */
3874
4522
  declare const ceiling: (value: OperandInput$1) => FunctionNode;
3875
4523
  /**
3876
- * Helper: COS(x) - Returns the cosine of a number (in radians)
4524
+ * Returns the cosine of a number (in radians).
4525
+ * @param value - The numeric value in radians.
4526
+ * @returns A FunctionNode representing the COS SQL function.
3877
4527
  */
3878
4528
  declare const cos: (value: OperandInput$1) => FunctionNode;
3879
4529
  /**
3880
- * Helper: COT(x) - Returns the cotangent of a number
4530
+ * Returns the cotangent of a number.
4531
+ * @param value - The numeric value.
4532
+ * @returns A FunctionNode representing the COT SQL function.
3881
4533
  */
3882
4534
  declare const cot: (value: OperandInput$1) => FunctionNode;
3883
4535
  /**
3884
- * Helper: DEGREES(x) - Converts radians to degrees
4536
+ * Converts radians to degrees.
4537
+ * @param value - The angle in radians.
4538
+ * @returns A FunctionNode representing the DEGREES SQL function.
3885
4539
  */
3886
4540
  declare const degrees: (value: OperandInput$1) => FunctionNode;
3887
4541
  /**
3888
- * Helper: EXP(x) - Returns e raised to the power of the argument
4542
+ * Returns e raised to the power of the argument.
4543
+ * @param value - The exponent.
4544
+ * @returns A FunctionNode representing the EXP SQL function.
3889
4545
  */
3890
4546
  declare const exp: (value: OperandInput$1) => FunctionNode;
3891
4547
  /**
3892
- * Helper: FLOOR(x) - Returns the largest integer <= x
4548
+ * Returns the largest integer less than or equal to a number.
4549
+ * @param value - The numeric value.
4550
+ * @returns A FunctionNode representing the FLOOR SQL function.
3893
4551
  */
3894
4552
  declare const floor: (value: OperandInput$1) => FunctionNode;
3895
4553
  /**
3896
- * Helper: LN(x) - Returns the natural logarithm (base e)
4554
+ * Returns the natural logarithm (base e) of a number.
4555
+ * @param value - The numeric value.
4556
+ * @returns A FunctionNode representing the LN SQL function.
3897
4557
  */
3898
4558
  declare const ln: (value: OperandInput$1) => FunctionNode;
3899
4559
  /**
3900
- * Helper: LOG(x) - Returns the base-10 logarithm
4560
+ * Returns the base-10 logarithm of a number.
4561
+ * @param value - The numeric value.
4562
+ * @returns A FunctionNode representing the LOG SQL function.
3901
4563
  */
3902
4564
  declare const log: (value: OperandInput$1) => FunctionNode;
3903
4565
  /**
3904
- * Helper: LOG10(x) - Returns the base-10 logarithm
4566
+ * Returns the base-10 logarithm of a number.
4567
+ * @param value - The numeric value.
4568
+ * @returns A FunctionNode representing the LOG10 SQL function.
3905
4569
  */
3906
4570
  declare const log10: (value: OperandInput$1) => FunctionNode;
3907
4571
  /**
3908
- * Helper: LOG(base, x) - Returns the logarithm of x for a specific base
4572
+ * Returns the logarithm of a number for a specific base.
4573
+ * @param base - The base of the logarithm.
4574
+ * @param value - The numeric value.
4575
+ * @returns A FunctionNode representing the LOG_BASE SQL function.
3909
4576
  */
3910
4577
  declare const logBase: (base: OperandInput$1, value: OperandInput$1) => FunctionNode;
3911
4578
  /**
3912
- * Helper: MOD(x, y) - Returns the remainder of x/y
4579
+ * Returns the remainder of dividing x by y.
4580
+ * @param x - The dividend.
4581
+ * @param y - The divisor.
4582
+ * @returns A FunctionNode representing the MOD SQL function.
3913
4583
  */
3914
4584
  declare const mod: (x: OperandInput$1, y: OperandInput$1) => FunctionNode;
3915
4585
  /**
3916
- * Helper: PI() - Returns the value of PI (approx. 3.14159...)
4586
+ * Returns the value of PI (approximately 3.14159...).
4587
+ * @returns A FunctionNode representing the PI SQL function.
3917
4588
  */
3918
4589
  declare const pi: () => FunctionNode;
3919
4590
  /**
3920
- * Helper: POWER(x, y) - Returns x raised to the power of y
4591
+ * Returns x raised to the power of y.
4592
+ * @param x - The base.
4593
+ * @param y - The exponent.
4594
+ * @returns A FunctionNode representing the POWER SQL function.
3921
4595
  */
3922
4596
  declare const power: (x: OperandInput$1, y: OperandInput$1) => FunctionNode;
3923
4597
  /**
3924
- * Helper: POW(x, y) - Alias for POWER
4598
+ * Alias for power. Returns x raised to the power of y.
4599
+ * @param x - The base.
4600
+ * @param y - The exponent.
4601
+ * @returns A FunctionNode representing the POW SQL function.
3925
4602
  */
3926
4603
  declare const pow: (x: OperandInput$1, y: OperandInput$1) => FunctionNode;
3927
4604
  /**
3928
- * Helper: RADIANS(x) - Converts degrees to radians
4605
+ * Converts degrees to radians.
4606
+ * @param value - The angle in degrees.
4607
+ * @returns A FunctionNode representing the RADIANS SQL function.
3929
4608
  */
3930
4609
  declare const radians: (value: OperandInput$1) => FunctionNode;
3931
4610
  /**
3932
- * Helper: RAND() / RANDOM() - Returns a random number
4611
+ * Returns a random number between 0 and 1.
4612
+ * @returns A FunctionNode representing the RANDOM SQL function.
3933
4613
  */
3934
4614
  declare const random: () => FunctionNode;
3935
4615
  /**
3936
- * Helper: RAND() - Alias for RANDOM (returns float 0-1)
4616
+ * Alias for random. Returns a random number between 0 and 1.
4617
+ * @returns A FunctionNode representing the RAND SQL function.
3937
4618
  */
3938
4619
  declare const rand: () => FunctionNode;
3939
4620
  /**
3940
- * Helper: ROUND(x[, decimals]) - Rounds a number to specified decimal places
4621
+ * Rounds a number to a specified number of decimal places.
4622
+ * @param value - The numeric value to round.
4623
+ * @param decimals - The number of decimal places (optional).
4624
+ * @returns A FunctionNode representing the ROUND SQL function.
3941
4625
  */
3942
4626
  declare const round: (value: OperandInput$1, decimals?: OperandInput$1) => FunctionNode;
3943
4627
  /**
3944
- * Helper: SIGN(x) - Returns the sign of a number (-1, 0, 1)
4628
+ * Returns the sign of a number (-1 for negative, 0 for zero, 1 for positive).
4629
+ * @param value - The numeric value.
4630
+ * @returns A FunctionNode representing the SIGN SQL function.
3945
4631
  */
3946
4632
  declare const sign: (value: OperandInput$1) => FunctionNode;
3947
4633
  /**
3948
- * Helper: SIN(x) - Returns the sine of a number (in radians)
4634
+ * Returns the sine of a number (in radians).
4635
+ * @param value - The numeric value in radians.
4636
+ * @returns A FunctionNode representing the SIN SQL function.
3949
4637
  */
3950
4638
  declare const sin: (value: OperandInput$1) => FunctionNode;
3951
4639
  /**
3952
- * Helper: SQRT(x) - Returns the square root of a number
4640
+ * Returns the square root of a number.
4641
+ * @param value - The numeric value.
4642
+ * @returns A FunctionNode representing the SQRT SQL function.
3953
4643
  */
3954
4644
  declare const sqrt: (value: OperandInput$1) => FunctionNode;
3955
4645
  /**
3956
- * Helper: TAN(x) - Returns the tangent of a number (in radians)
4646
+ * Returns the tangent of a number (in radians).
4647
+ * @param value - The numeric value in radians.
4648
+ * @returns A FunctionNode representing the TAN SQL function.
3957
4649
  */
3958
4650
  declare const tan: (value: OperandInput$1) => FunctionNode;
3959
4651
  /**
3960
- * Helper: TRUNC(x[, decimals]) / TRUNCATE(x, decimals) - Truncates a number without rounding
4652
+ * Truncates a number to a specified number of decimal places without rounding.
4653
+ * @param value - The numeric value to truncate.
4654
+ * @param decimals - The number of decimal places (optional).
4655
+ * @returns A FunctionNode representing the TRUNC SQL function.
3961
4656
  */
3962
4657
  declare const trunc: (value: OperandInput$1, decimals?: OperandInput$1) => FunctionNode;
3963
4658
  /**
3964
- * Helper: TRUNCATE(x, decimals) - Alias for TRUNC
4659
+ * Alias for trunc. Truncates a number to a specified number of decimal places without rounding.
4660
+ * @param value - The numeric value to truncate.
4661
+ * @param decimals - The number of decimal places.
4662
+ * @returns A FunctionNode representing the TRUNCATE SQL function.
3965
4663
  */
3966
4664
  declare const truncate: (value: OperandInput$1, decimals: OperandInput$1) => FunctionNode;
3967
4665
 
3968
4666
  type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
3969
4667
  /**
3970
- * Helper: NOW() - Returns the current local date and time
4668
+ * Returns the current local date and time.
4669
+ * @returns A FunctionNode representing the NOW() SQL function.
3971
4670
  */
3972
4671
  declare const now: () => FunctionNode;
3973
4672
  /**
3974
- * Helper: CURRENT_DATE - Returns only the current date (no time)
4673
+ * Returns the current date without time.
4674
+ * @returns A FunctionNode representing the CURRENT_DATE SQL function.
3975
4675
  */
3976
4676
  declare const currentDate: () => FunctionNode;
3977
4677
  /**
3978
- * Helper: CURRENT_TIME - Returns only the current time
4678
+ * Returns the current time without date.
4679
+ * @returns A FunctionNode representing the CURRENT_TIME SQL function.
3979
4680
  */
3980
4681
  declare const currentTime: () => FunctionNode;
3981
4682
  /**
3982
- * Helper: UTC_NOW() - Returns current UTC/GMT date and time
4683
+ * Returns the current UTC date and time.
4684
+ * @returns A FunctionNode representing the UTC_NOW() SQL function.
3983
4685
  */
3984
4686
  declare const utcNow: () => FunctionNode;
3985
4687
  /**
3986
- * Helper: EXTRACT(part FROM date) - Extracts a part (year, month, day, hour, etc.) from a date
3987
- * @param part - The date part to extract (e.g., 'YEAR', 'MONTH', 'DAY', 'HOUR', 'MINUTE', 'SECOND')
3988
- * @param date - The date/datetime value
4688
+ * Extracts a specified part from a date or datetime value.
4689
+ * @param part - The date part to extract (e.g., 'YEAR', 'MONTH', 'DAY', 'HOUR', 'MINUTE', 'SECOND').
4690
+ * @param date - The date or datetime value to extract from.
4691
+ * @returns A FunctionNode representing the EXTRACT SQL function.
3989
4692
  */
3990
4693
  declare const extract: (part: OperandInput, date: OperandInput) => FunctionNode;
3991
4694
  /**
3992
- * Helper: YEAR(date) - Extracts the year from a date
4695
+ * Extracts the year from a date or datetime value.
4696
+ * @param date - The date or datetime value.
4697
+ * @returns A FunctionNode representing the YEAR SQL function.
3993
4698
  */
3994
4699
  declare const year: (date: OperandInput) => FunctionNode;
3995
4700
  /**
3996
- * Helper: MONTH(date) - Extracts the month from a date
4701
+ * Extracts the month from a date or datetime value.
4702
+ * @param date - The date or datetime value.
4703
+ * @returns A FunctionNode representing the MONTH SQL function.
3997
4704
  */
3998
4705
  declare const month: (date: OperandInput) => FunctionNode;
3999
4706
  /**
4000
- * Helper: DAY(date) - Extracts the day from a date
4707
+ * Extracts the day of the month from a date or datetime value.
4708
+ * @param date - The date or datetime value.
4709
+ * @returns A FunctionNode representing the DAY SQL function.
4001
4710
  */
4002
4711
  declare const day: (date: OperandInput) => FunctionNode;
4003
4712
  /**
4004
- * Helper: DATE_ADD(date, interval, unit) - Adds a specific time interval to a date
4005
- * @param date - The date/datetime value
4006
- * @param interval - The number of units to add
4007
- * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND')
4713
+ * Adds a specified time interval to a date or datetime value.
4714
+ * @param date - The date or datetime value to add to.
4715
+ * @param interval - The number of units to add.
4716
+ * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND').
4717
+ * @returns A FunctionNode representing the DATE_ADD SQL function.
4008
4718
  */
4009
4719
  declare const dateAdd: (date: OperandInput, interval: OperandInput, unit: OperandInput) => FunctionNode;
4010
4720
  /**
4011
- * Helper: DATE_SUB(date, interval, unit) - Subtracts a specific time interval from a date
4012
- * @param date - The date/datetime value
4013
- * @param interval - The number of units to subtract
4014
- * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND')
4721
+ * Subtracts a specified time interval from a date or datetime value.
4722
+ * @param date - The date or datetime value to subtract from.
4723
+ * @param interval - The number of units to subtract.
4724
+ * @param unit - The unit type (e.g., 'DAY', 'MONTH', 'YEAR', 'HOUR', 'MINUTE', 'SECOND').
4725
+ * @returns A FunctionNode representing the DATE_SUB SQL function.
4015
4726
  */
4016
4727
  declare const dateSub: (date: OperandInput, interval: OperandInput, unit: OperandInput) => FunctionNode;
4017
4728
  /**
4018
- * Helper: DATE_DIFF(date1, date2) - Returns the difference between two dates in days
4019
- * @param date1 - The end date
4020
- * @param date2 - The start date
4729
+ * Returns the difference between two dates in days.
4730
+ * @param date1 - The end date.
4731
+ * @param date2 - The start date.
4732
+ * @returns A FunctionNode representing the DATE_DIFF SQL function.
4021
4733
  */
4022
4734
  declare const dateDiff: (date1: OperandInput, date2: OperandInput) => FunctionNode;
4023
4735
  /**
4024
- * Helper: DATE_FORMAT(date, format) - Converts a date to a formatted string
4025
- * @param date - The date/datetime value
4026
- * @param format - The format string (dialect-specific)
4736
+ * Converts a date or datetime value to a formatted string.
4737
+ * @param date - The date or datetime value to format.
4738
+ * @param format - The format string (dialect-specific).
4739
+ * @returns A FunctionNode representing the DATE_FORMAT SQL function.
4027
4740
  */
4028
4741
  declare const dateFormat: (date: OperandInput, format: OperandInput) => FunctionNode;
4029
4742
  /**
4030
- * Helper: UNIX_TIMESTAMP() - Returns the current Unix epoch (seconds since 1970)
4743
+ * Returns the current Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).
4744
+ * @returns A FunctionNode representing the UNIX_TIMESTAMP SQL function.
4031
4745
  */
4032
4746
  declare const unixTimestamp: () => FunctionNode;
4033
4747
  /**
4034
- * Helper: FROM_UNIXTIME(timestamp) - Converts Unix epoch seconds to a date
4035
- * @param timestamp - Unix timestamp in seconds
4748
+ * Converts a Unix timestamp (seconds since 1970-01-01 00:00:00 UTC) to a date.
4749
+ * @param timestamp - Unix timestamp in seconds.
4750
+ * @returns A FunctionNode representing the FROM_UNIXTIME SQL function.
4036
4751
  */
4037
4752
  declare const fromUnixTime: (timestamp: OperandInput) => FunctionNode;
4038
4753
  /**
4039
- * Helper: END_OF_MONTH(date) - Returns the last day of the month for a given date
4754
+ * Returns the last day of the month for a given date.
4755
+ * @param date - The date value.
4756
+ * @returns A FunctionNode representing the END_OF_MONTH SQL function.
4040
4757
  */
4041
4758
  declare const endOfMonth: (date: OperandInput) => FunctionNode;
4042
4759
  /**
4043
- * Helper: DAY_OF_WEEK(date) - Returns the index of the weekday
4760
+ * Returns the index of the weekday for a given date (1 = Sunday, 2 = Monday, etc.).
4761
+ * @param date - The date value.
4762
+ * @returns A FunctionNode representing the DAY_OF_WEEK SQL function.
4044
4763
  */
4045
4764
  declare const dayOfWeek: (date: OperandInput) => FunctionNode;
4046
4765
  /**
4047
- * Helper: WEEK_OF_YEAR(date) - Returns the week number of the year
4766
+ * Returns the week number of the year for a given date.
4767
+ * @param date - The date value.
4768
+ * @returns A FunctionNode representing the WEEK_OF_YEAR SQL function.
4048
4769
  */
4049
4770
  declare const weekOfYear: (date: OperandInput) => FunctionNode;
4050
4771
  /**
4051
- * Helper: DATE_TRUNC(part, date) - Resets date precision (e.g., first day of the month/year)
4052
- * @param part - The truncation precision (e.g., 'YEAR', 'MONTH', 'DAY')
4053
- * @param date - The date/datetime value
4772
+ * Truncates a date or datetime value to a specified precision (e.g., first day of the month/year).
4773
+ * @param part - The truncation precision (e.g., 'YEAR', 'MONTH', 'DAY').
4774
+ * @param date - The date or datetime value to truncate.
4775
+ * @returns A FunctionNode representing the DATE_TRUNC SQL function.
4054
4776
  */
4055
4777
  declare const dateTrunc: (part: OperandInput, date: OperandInput) => FunctionNode;
4056
4778
 
4057
4779
  /**
4058
- * Browser-compatible implementation of AsyncLocalStorage
4059
- * Provides a simple in-memory store for browser environments
4060
- * @typeParam T - Type of the stored data
4780
+ * Browser-compatible implementation of AsyncLocalStorage.
4781
+ * Provides a simple in-memory store for browser environments while maintaining
4782
+ * Node.js AsyncLocalStorage API compatibility.
4783
+ *
4784
+ * @template T Type of the data stored in the async context
4061
4785
  */
4062
4786
  declare class AsyncLocalStorage<T> {
4063
4787
  private store;
4064
4788
  /**
4065
- * Executes a callback with the specified store value
4066
- * @param store - Value to store during callback execution
4067
- * @param callback - Function to execute with the store value
4068
- * @returns Result of the callback function
4789
+ * Executes a callback function within a context containing the specified store value.
4790
+ * The store value is only available during the callback's execution and is automatically
4791
+ * cleared afterward.
4792
+ *
4793
+ * @param store - The context value to make available during callback execution
4794
+ * @param callback - Function to execute with the store value available
4795
+ * @returns Result of the callback function execution
4796
+ *
4797
+ * @example
4798
+ * ```
4799
+ * const als = new AsyncLocalStorage<number>();
4800
+ * als.run(42, () => {
4801
+ * console.log(als.getStore()); // Outputs: 42
4802
+ * });
4803
+ * ```
4069
4804
  */
4070
4805
  run<R>(store: T, callback: () => R): R;
4071
4806
  /**
4072
- * Gets the currently stored value
4073
- * @returns Current store value or undefined if none exists
4807
+ * Retrieves the current store value from the async context.
4808
+ * Returns undefined if called outside of a `run()` callback execution.
4809
+ *
4810
+ * @returns Current store value or undefined if no context exists
4811
+ *
4812
+ * @example
4813
+ * ```
4814
+ * const als = new AsyncLocalStorage<string>();
4815
+ * console.log(als.getStore()); // Outputs: undefined
4816
+ *
4817
+ * als.run('hello', () => {
4818
+ * console.log(als.getStore()); // Outputs: 'hello'
4819
+ * });
4820
+ * ```
4074
4821
  */
4075
4822
  getStore(): T | undefined;
4076
4823
  }
4077
4824
 
4825
+ /**
4826
+ * Hydrates query results according to a hydration plan
4827
+ * @param rows - Raw database rows
4828
+
4078
4829
  /**
4079
4830
  * Hydrates query results according to a hydration plan
4080
4831
  * @param rows - Raw database rows
4081
4832
  * @param plan - Hydration plan
4082
4833
  * @returns Hydrated result objects with nested relations
4083
4834
  */
4084
- declare const hydrateRows: (rows: Record<string, any>[], plan?: HydrationPlan) => Record<string, any>[];
4835
+ declare const hydrateRows: (rows: Record<string, unknown>[], plan?: HydrationPlan) => Record<string, unknown>[];
4085
4836
 
4086
- /**
4087
- * Generates TypeScript code from query AST nodes
4088
- */
4089
4837
  declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVisitor<string> {
4090
4838
  private namingStrategy;
4091
4839
  constructor(namingStrategy?: NamingStrategy);
@@ -4117,6 +4865,8 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
4117
4865
  * Prints an ordering term (operand/expression/alias) to TypeScript code.
4118
4866
  */
4119
4867
  private printOrderingTerm;
4868
+ private getSelectionKey;
4869
+ private isNamedSelection;
4120
4870
  visitBinaryExpression(binary: BinaryExpressionNode): string;
4121
4871
  visitLogicalExpression(logical: LogicalExpressionNode): string;
4122
4872
  visitNullExpression(nullExpr: NullExpressionNode): string;
@@ -4235,7 +4985,7 @@ declare class TypeScriptGenerator implements ExpressionVisitor<string>, OperandV
4235
4985
  * @param lazyRelations - Optional lazy relations
4236
4986
  * @returns The entity instance
4237
4987
  */
4238
- 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>;
4988
+ declare const createEntityProxy: <TTable extends TableDef, TLazy extends keyof RelationMap<TTable> = keyof RelationMap<TTable>>(ctx: EntityContext, table: TTable, row: Record<string, unknown>, lazyRelations?: TLazy[]) => EntityInstance<TTable>;
4239
4989
  /**
4240
4990
  * Creates an entity instance from a database row.
4241
4991
  * @template TTable - The table type
@@ -4246,12 +4996,12 @@ declare const createEntityProxy: <TTable extends TableDef, TLazy extends keyof R
4246
4996
  * @param lazyRelations - Optional lazy relations
4247
4997
  * @returns The entity instance
4248
4998
  */
4249
- 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;
4999
+ declare const createEntityFromRow: <TTable extends TableDef, TResult extends EntityInstance<TTable> = EntityInstance<TTable>>(ctx: EntityContext, table: TTable, row: Record<string, unknown>, lazyRelations?: (keyof RelationMap<TTable>)[]) => TResult;
4250
5000
 
4251
- type Rows$3 = Record<string, any>[];
5001
+ type Rows$3 = Record<string, unknown>[];
4252
5002
  declare const loadHasManyRelation: (ctx: EntityContext, rootTable: TableDef, _relationName: string, relation: HasManyRelation) => Promise<Map<string, Rows$3>>;
4253
- declare const loadHasOneRelation: (ctx: EntityContext, rootTable: TableDef, _relationName: string, relation: HasOneRelation) => Promise<Map<string, Record<string, any>>>;
4254
- declare const loadBelongsToRelation: (ctx: EntityContext, rootTable: TableDef, _relationName: string, relation: BelongsToRelation) => Promise<Map<string, Record<string, any>>>;
5003
+ declare const loadHasOneRelation: (ctx: EntityContext, rootTable: TableDef, _relationName: string, relation: HasOneRelation) => Promise<Map<string, Record<string, unknown>>>;
5004
+ declare const loadBelongsToRelation: (ctx: EntityContext, rootTable: TableDef, _relationName: string, relation: BelongsToRelation) => Promise<Map<string, Record<string, unknown>>>;
4255
5005
  declare const loadBelongsToManyRelation: (ctx: EntityContext, rootTable: TableDef, _relationName: string, relation: BelongsToManyRelation) => Promise<Map<string, Rows$3>>;
4256
5006
 
4257
5007
  /**
@@ -4266,14 +5016,18 @@ interface EntityMeta<TTable extends TableDef> {
4266
5016
  /** Relations that should be loaded lazily */
4267
5017
  lazyRelations: (keyof RelationMap<TTable>)[];
4268
5018
  /** Cache for relation promises */
4269
- relationCache: Map<string, Promise<any>>;
5019
+ relationCache: Map<string, Promise<unknown>>;
4270
5020
  /** Hydration data for relations */
4271
- relationHydration: Map<string, Map<string, any>>;
5021
+ relationHydration: Map<string, Map<string, unknown>>;
4272
5022
  /** Relation wrapper instances */
4273
5023
  relationWrappers: Map<string, unknown>;
4274
5024
  }
4275
5025
 
4276
- type Rows$2 = Record<string, any>[];
5026
+ type Rows$2 = Record<string, unknown>[];
5027
+ /**
5028
+ * Default implementation of HasManyCollection for managing one-to-many relationships.
5029
+ * @template TChild - The type of child entities in the collection
5030
+ */
4277
5031
  declare class DefaultHasManyCollection<TChild> implements HasManyCollection<TChild> {
4278
5032
  private readonly ctx;
4279
5033
  private readonly meta;
@@ -4288,19 +5042,59 @@ declare class DefaultHasManyCollection<TChild> implements HasManyCollection<TChi
4288
5042
  private items;
4289
5043
  private readonly added;
4290
5044
  private readonly removed;
4291
- constructor(ctx: EntityContext, meta: EntityMeta<any>, root: any, relationName: string, relation: HasManyRelation, rootTable: TableDef, loader: () => Promise<Map<string, Rows$2>>, createEntity: (row: Record<string, any>) => TChild, localKey: string);
5045
+ /**
5046
+ * Creates a new DefaultHasManyCollection instance.
5047
+ * @param ctx - The entity context
5048
+ * @param meta - The entity metadata
5049
+ * @param root - The root entity
5050
+ * @param relationName - The relation name
5051
+ * @param relation - The relation definition
5052
+ * @param rootTable - The root table definition
5053
+ * @param loader - The loader function for lazy loading
5054
+ * @param createEntity - Function to create entities from rows
5055
+ * @param localKey - The local key for the relation
5056
+ */
5057
+ constructor(ctx: EntityContext, meta: EntityMeta<TableDef>, root: unknown, relationName: string, relation: HasManyRelation, rootTable: TableDef, loader: () => Promise<Map<string, Rows$2>>, createEntity: (row: Record<string, unknown>) => TChild, localKey: string);
5058
+ /**
5059
+ * Loads the related entities if not already loaded.
5060
+ * @returns Promise resolving to the array of child entities
5061
+ */
4292
5062
  load(): Promise<TChild[]>;
5063
+ /**
5064
+ * Gets the current items in the collection.
5065
+ * @returns Array of child entities
5066
+ */
4293
5067
  getItems(): TChild[];
5068
+ /**
5069
+ * Adds a new child entity to the collection.
5070
+ * @param data - Partial data for the new entity
5071
+ * @returns The created entity
5072
+ */
4294
5073
  add(data: Partial<TChild>): TChild;
5074
+ /**
5075
+ * Attaches an existing entity to the collection.
5076
+ * @param entity - The entity to attach
5077
+ */
4295
5078
  attach(entity: TChild): void;
5079
+ /**
5080
+ * Removes an entity from the collection.
5081
+ * @param entity - The entity to remove
5082
+ */
4296
5083
  remove(entity: TChild): void;
5084
+ /**
5085
+ * Clears all entities from the collection.
5086
+ */
4297
5087
  clear(): void;
4298
5088
  private get relationKey();
4299
5089
  private hydrateFromCache;
5090
+ /**
5091
+ * Returns the items for JSON serialization.
5092
+ * @returns Array of child entities
5093
+ */
4300
5094
  toJSON(): TChild[];
4301
5095
  }
4302
5096
 
4303
- type Rows$1 = Record<string, any>;
5097
+ type Rows$1 = Record<string, unknown>;
4304
5098
  declare class DefaultBelongsToReference<TParent> implements BelongsToReference<TParent> {
4305
5099
  private readonly ctx;
4306
5100
  private readonly meta;
@@ -4313,7 +5107,7 @@ declare class DefaultBelongsToReference<TParent> implements BelongsToReference<T
4313
5107
  private readonly targetKey;
4314
5108
  private loaded;
4315
5109
  private current;
4316
- constructor(ctx: EntityContext, meta: EntityMeta<any>, root: any, relationName: string, relation: BelongsToRelation, rootTable: TableDef, loader: () => Promise<Map<string, Rows$1>>, createEntity: (row: Record<string, any>) => TParent, targetKey: string);
5110
+ 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);
4317
5111
  load(): Promise<TParent | null>;
4318
5112
  get(): TParent | null;
4319
5113
  set(data: Partial<TParent> | TParent | null): TParent | null;
@@ -4322,7 +5116,7 @@ declare class DefaultBelongsToReference<TParent> implements BelongsToReference<T
4322
5116
  toJSON(): TParent | null;
4323
5117
  }
4324
5118
 
4325
- type Rows = Record<string, any>[];
5119
+ type Rows = Record<string, unknown>[];
4326
5120
  declare class DefaultManyToManyCollection<TTarget> implements ManyToManyCollection<TTarget> {
4327
5121
  private readonly ctx;
4328
5122
  private readonly meta;
@@ -4335,7 +5129,7 @@ declare class DefaultManyToManyCollection<TTarget> implements ManyToManyCollecti
4335
5129
  private readonly localKey;
4336
5130
  private loaded;
4337
5131
  private items;
4338
- constructor(ctx: EntityContext, meta: EntityMeta<any>, root: any, relationName: string, relation: BelongsToManyRelation, rootTable: TableDef, loader: () => Promise<Map<string, Rows>>, createEntity: (row: Record<string, any>) => TTarget, localKey: string);
5132
+ 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);
4339
5133
  load(): Promise<TTarget[]>;
4340
5134
  getItems(): TTarget[];
4341
5135
  attach(target: TTarget | number | string): void;
@@ -4349,32 +5143,66 @@ declare class DefaultManyToManyCollection<TTarget> implements ManyToManyCollecti
4349
5143
  toJSON(): TTarget[];
4350
5144
  }
4351
5145
 
4352
- declare function executeHydrated<TTable extends TableDef>(session: OrmSession, qb: SelectQueryBuilder<any, TTable>): Promise<EntityInstance<TTable>[]>;
4353
- declare function executeHydratedWithContexts<TTable extends TableDef>(_execCtx: ExecutionContext, hydCtx: HydrationContext, qb: SelectQueryBuilder<any, TTable>): Promise<EntityInstance<TTable>[]>;
5146
+ /**
5147
+ * Executes a hydrated query using the ORM session.
5148
+ * @template TTable - The table type
5149
+ * @param session - The ORM session
5150
+ * @param qb - The select query builder
5151
+ * @returns Promise resolving to array of entity instances
5152
+ */
5153
+ declare function executeHydrated<TTable extends TableDef>(session: OrmSession, qb: SelectQueryBuilder<unknown, TTable>): Promise<EntityInstance<TTable>[]>;
5154
+ /**
5155
+ * Executes a hydrated query using execution and hydration contexts.
5156
+ * @template TTable - The table type
5157
+ * @param _execCtx - The execution context (unused)
5158
+ * @param hydCtx - The hydration context
5159
+ * @param qb - The select query builder
5160
+ * @returns Promise resolving to array of entity instances
5161
+ */
5162
+ declare function executeHydratedWithContexts<TTable extends TableDef>(_execCtx: ExecutionContext, hydCtx: HydrationContext, qb: SelectQueryBuilder<unknown, TTable>): Promise<EntityInstance<TTable>[]>;
4354
5163
 
5164
+ /**
5165
+ * Context object provided by standard decorators in newer TypeScript versions.
5166
+ */
4355
5167
  interface StandardDecoratorContext {
4356
5168
  kind: string;
4357
5169
  name?: string | symbol;
4358
5170
  metadata?: Record<PropertyKey, unknown>;
4359
- addInitializer?(initializer: (this: unknown) => void): void;
4360
5171
  static?: boolean;
4361
5172
  private?: boolean;
4362
5173
  }
5174
+ /**
5175
+ * Dual-mode property decorator that supports both legacy and standard decorator syntax.
5176
+ */
4363
5177
  interface DualModePropertyDecorator {
4364
5178
  (target: object, propertyKey: string | symbol): void;
4365
5179
  (value: unknown, context: StandardDecoratorContext): void;
4366
5180
  }
5181
+ /**
5182
+ * Dual-mode class decorator that supports both legacy and standard decorator syntax.
5183
+ */
4367
5184
  interface DualModeClassDecorator {
4368
5185
  <TFunction extends Function>(value: TFunction): void | TFunction;
4369
5186
  <TFunction extends Function>(value: TFunction, context: StandardDecoratorContext): void | TFunction;
4370
5187
  }
4371
5188
 
5189
+ /**
5190
+ * Options for defining an entity.
5191
+ */
4372
5192
  interface EntityOptions {
4373
5193
  tableName?: string;
4374
5194
  hooks?: TableHooks;
4375
5195
  }
5196
+ /**
5197
+ * Class decorator to mark a class as an entity and configure its table mapping.
5198
+ * @param options - Configuration options for the entity.
5199
+ * @returns A class decorator that registers the entity metadata.
5200
+ */
4376
5201
  declare function Entity(options?: EntityOptions): DualModeClassDecorator;
4377
5202
 
5203
+ /**
5204
+ * Options for defining a column in an entity.
5205
+ */
4378
5206
  interface ColumnOptions {
4379
5207
  type: ColumnType;
4380
5208
  args?: ColumnDef['args'];
@@ -4382,8 +5210,22 @@ interface ColumnOptions {
4382
5210
  primary?: boolean;
4383
5211
  tsType?: ColumnDef['tsType'];
4384
5212
  }
4385
- type ColumnInput = ColumnOptions | ColumnDef<any, any>;
5213
+ /**
5214
+ * Input type for column definitions, either as options object or direct ColumnDef.
5215
+ */
5216
+ type ColumnInput = ColumnOptions | ColumnDef;
5217
+ /**
5218
+ * Decorator to define a column on an entity property.
5219
+ * @param definition - The column definition or options.
5220
+ * @returns A property decorator that registers the column metadata.
5221
+ */
4386
5222
  declare function Column(definition: ColumnInput): DualModePropertyDecorator;
5223
+ /**
5224
+ * Decorator to define a primary key column on an entity property.
5225
+ * Sets the primary flag to true and delegates to Column decorator.
5226
+ * @param definition - The column definition or options.
5227
+ * @returns A property decorator that registers the primary key column metadata.
5228
+ */
4387
5229
  declare function PrimaryKey(definition: ColumnInput): DualModePropertyDecorator;
4388
5230
 
4389
5231
  interface BaseRelationOptions {
@@ -4391,15 +5233,27 @@ interface BaseRelationOptions {
4391
5233
  cascade?: CascadeMode;
4392
5234
  localKey?: string;
4393
5235
  }
5236
+ /**
5237
+ * Options for HasMany relation.
5238
+ */
4394
5239
  interface HasManyOptions extends BaseRelationOptions {
4395
5240
  foreignKey: string;
4396
5241
  }
5242
+ /**
5243
+ * Options for HasOne relation.
5244
+ */
4397
5245
  interface HasOneOptions extends BaseRelationOptions {
4398
5246
  foreignKey: string;
4399
5247
  }
5248
+ /**
5249
+ * Options for BelongsTo relation.
5250
+ */
4400
5251
  interface BelongsToOptions extends BaseRelationOptions {
4401
5252
  foreignKey: string;
4402
5253
  }
5254
+ /**
5255
+ * Options for BelongsToMany relation.
5256
+ */
4403
5257
  interface BelongsToManyOptions {
4404
5258
  target: EntityOrTableTargetResolver;
4405
5259
  pivotTable: EntityOrTableTargetResolver;
@@ -4411,14 +5265,56 @@ interface BelongsToManyOptions {
4411
5265
  defaultPivotColumns?: string[];
4412
5266
  cascade?: CascadeMode;
4413
5267
  }
5268
+ /**
5269
+ * Decorator to define a HasMany relation on an entity property.
5270
+ * @param options - The relation options.
5271
+ * @returns A property decorator that registers the relation metadata.
5272
+ */
4414
5273
  declare function HasMany(options: HasManyOptions): DualModePropertyDecorator;
5274
+ /**
5275
+ * Decorator to define a HasOne relation on an entity property.
5276
+ * @param options - The relation options.
5277
+ * @returns A property decorator that registers the relation metadata.
5278
+ */
4415
5279
  declare function HasOne(options: HasOneOptions): DualModePropertyDecorator;
5280
+ /**
5281
+ * Decorator to define a BelongsTo relation on an entity property.
5282
+ * @param options - The relation options.
5283
+ * @returns A property decorator that registers the relation metadata.
5284
+ */
4416
5285
  declare function BelongsTo(options: BelongsToOptions): DualModePropertyDecorator;
5286
+ /**
5287
+ * Decorator to define a BelongsToMany relation on an entity property.
5288
+ * @param options - The relation options.
5289
+ * @returns A property decorator that registers the relation metadata.
5290
+ */
4417
5291
  declare function BelongsToMany(options: BelongsToManyOptions): DualModePropertyDecorator;
4418
5292
 
5293
+ /**
5294
+ * Bootstraps all entities by building their table definitions and relations.
5295
+ * @returns An array of table definitions for all bootstrapped entities.
5296
+ */
4419
5297
  declare const bootstrapEntities: () => TableDef[];
4420
- declare const getTableDefFromEntity: <TTable extends TableDef = TableDef>(ctor: EntityConstructor<any>) => TTable | undefined;
4421
- declare const selectFromEntity: <TTable extends TableDef = TableDef>(ctor: EntityConstructor<any>) => SelectQueryBuilder<any, TTable>;
5298
+ /**
5299
+ * Gets the table definition for a given entity constructor.
5300
+ * Bootstraps entities if necessary.
5301
+ * @param ctor - The entity constructor.
5302
+ * @returns The table definition or undefined if not found.
5303
+ */
5304
+ declare const getTableDefFromEntity: <TTable extends TableDef = TableDef>(ctor: EntityConstructor) => TTable | undefined;
5305
+ /**
5306
+ * Creates a select query builder for the given entity.
5307
+ * @param ctor - The entity constructor.
5308
+ * @returns A select query builder for the entity.
5309
+ */
5310
+ declare const selectFromEntity: <TTable extends TableDef = TableDef>(ctor: EntityConstructor) => SelectQueryBuilder<unknown, TTable>;
5311
+ /**
5312
+ * Public API: opt-in ergonomic entity reference (decorator-level).
5313
+ *
5314
+ * Lazily bootstraps entity metadata (via getTableDefFromEntity) and returns a
5315
+ * `tableRef(...)`-style proxy so users can write `u.id` instead of `u.columns.id`.
5316
+ */
5317
+ declare const entityRef: <TTable extends TableDef = TableDef>(ctor: EntityConstructor) => TableRef$1<TTable>;
4422
5318
 
4423
5319
  type PoolOptions = {
4424
5320
  /** Maximum number of live resources (idle + leased). */
@@ -4480,7 +5376,7 @@ interface PostgresClientLike {
4480
5376
  declare function createPostgresExecutor(client: PostgresClientLike): DbExecutor;
4481
5377
 
4482
5378
  interface MysqlClientLike {
4483
- query(sql: string, params?: unknown[]): Promise<[any, any?]>;
5379
+ query(sql: string, params?: unknown[]): Promise<[unknown, unknown?]>;
4484
5380
  beginTransaction?(): Promise<void>;
4485
5381
  commit?(): Promise<void>;
4486
5382
  rollback?(): Promise<void>;
@@ -4563,4 +5459,4 @@ type PooledExecutorFactoryOptions<TConn> = {
4563
5459
  */
4564
5460
  declare function createPooledExecutorFactory<TConn>(opts: PooledExecutorFactoryOptions<TConn>): DbExecutorFactory;
4565
5461
 
4566
- 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 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$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, 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, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };
5462
+ 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 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$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, ceil, ceiling, char, charLength, clearExpressionDispatchers, clearOperandDispatchers, col, columnOperand, concat, concatWs, correlateBy, cos, cot, count, 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, 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, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };