metal-orm 1.0.43 → 1.0.44

package/src/orm/relations/has-many.ts

@@ -20,12 +20,28 @@ const hideInternal = (obj: object, keys: string[]): void => {
   }
 };
 
+/**
+ * Default implementation of HasManyCollection for managing one-to-many relationships.
+ * @template TChild - The type of child entities in the collection
+ */
 export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChild> {
   private loaded = false;
   private items: TChild[] = [];
   private readonly added = new Set<TChild>();
   private readonly removed = new Set<TChild>();
 
+  /**
+   * Creates a new DefaultHasManyCollection instance.
+   * @param ctx - The entity context
+   * @param meta - The entity metadata
+   * @param root - The root entity
+   * @param relationName - The relation name
+   * @param relation - The relation definition
+   * @param rootTable - The root table definition
+   * @param loader - The loader function for lazy loading
+   * @param createEntity - Function to create entities from rows
+   * @param localKey - The local key for the relation
+   */
   constructor(
     private readonly ctx: EntityContext,
     private readonly meta: EntityMeta<TableDef>,
@@ -41,6 +57,10 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     this.hydrateFromCache();
   }
 
+  /**
+   * Loads the related entities if not already loaded.
+   * @returns Promise resolving to the array of child entities
+   */
   async load(): Promise<TChild[]> {
     if (this.loaded) return this.items;
     const map = await this.loader();
@@ -51,10 +71,19 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     return this.items;
   }
 
+  /**
+   * Gets the current items in the collection.
+   * @returns Array of child entities
+   */
   getItems(): TChild[] {
     return this.items;
   }
 
+  /**
+   * Adds a new child entity to the collection.
+   * @param data - Partial data for the new entity
+   * @returns The created entity
+   */
   add(data: Partial<TChild>): TChild {
     const keyValue = (this.root as Record<string, unknown>)[this.localKey];
     const childRow: Record<string, unknown> = {
@@ -75,6 +104,10 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     return entity;
   }
 
+  /**
+   * Attaches an existing entity to the collection.
+   * @param entity - The entity to attach
+   */
   attach(entity: TChild): void {
     const keyValue = this.root[this.localKey];
     (entity as Record<string, unknown>)[this.relation.foreignKey] = keyValue;
@@ -90,6 +123,10 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     );
   }
 
+  /**
+   * Removes an entity from the collection.
+   * @param entity - The entity to remove
+   */
   remove(entity: TChild): void {
     this.items = this.items.filter(item => item !== entity);
     this.removed.add(entity);
@@ -103,6 +140,9 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     );
   }
 
+  /**
+   * Clears all entities from the collection.
+   */
   clear(): void {
     for (const entity of [...this.items]) {
       this.remove(entity);
@@ -122,6 +162,10 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     this.loaded = true;
   }
 
+  /**
+   * Returns the items for JSON serialization.
+   * @returns Array of child entities
+   */
   toJSON(): TChild[] {
     return this.items;
   }

package/src/query/index.ts

@@ -0,0 +1,74 @@
+import { TableDef } from '../schema/table.js';
+import { SelectQueryBuilder } from '../query-builder/select.js';
+import { InsertQueryBuilder } from '../query-builder/insert.js';
+import { UpdateQueryBuilder } from '../query-builder/update.js';
+import { DeleteQueryBuilder } from '../query-builder/delete.js';
+import { QueryTarget, resolveTable } from './target.js';
+
+/**
+ * Creates a SELECT query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to query from
+ * @returns A new SelectQueryBuilder instance for building SELECT queries
+ *
+ * @example
+ * ```typescript
+ * const query = selectFrom(UserTable).select('id', 'name');
+ * ```
+ */
+export const selectFrom = <TTable extends TableDef>(target: QueryTarget<TTable>): SelectQueryBuilder<unknown, TTable> => {
+    const table = resolveTable(target);
+    return new SelectQueryBuilder(table);
+};
+
+/**
+ * Creates an INSERT query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to insert into
+ * @returns A new InsertQueryBuilder instance for building INSERT queries
+ *
+ * @example
+ * ```typescript
+ * const query = insertInto(UserTable).values({ name: 'John', email: 'john@example.com' });
+ * ```
+ */
+export const insertInto = <TTable extends TableDef>(target: QueryTarget<TTable>): InsertQueryBuilder<unknown> => {
+    const table = resolveTable(target);
+    return new InsertQueryBuilder(table);
+};
+
+/**
+ * Creates an UPDATE query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to update
+ * @returns A new UpdateQueryBuilder instance for building UPDATE queries
+ *
+ * @example
+ * ```typescript
+ * const query = update(UserTable).set({ name: 'Jane' }).where(eq(UserTable.id, 1));
+ * ```
+ */
+export const update = <TTable extends TableDef>(target: QueryTarget<TTable>): UpdateQueryBuilder<unknown> => {
+    const table = resolveTable(target);
+    return new UpdateQueryBuilder(table);
+};
+
+/**
+ * Creates a DELETE query builder for the specified table or entity.
+ *
+ * @template TTable - The table definition type
+ * @param target - The table definition or entity constructor to delete from
+ * @returns A new DeleteQueryBuilder instance for building DELETE queries
+ *
+ * @example
+ * ```typescript
+ * const query = deleteFrom(UserTable).where(eq(UserTable.id, 1));
+ * ```
+ */
+export const deleteFrom = <TTable extends TableDef>(target: QueryTarget<TTable>): DeleteQueryBuilder<unknown> => {
+    const table = resolveTable(target);
+    return new DeleteQueryBuilder(table);
+};

package/src/query/target.ts

@@ -0,0 +1,46 @@
+import { TableDef } from '../schema/table.js';
+import { isTableDef } from '../schema/table-guards.js';
+import { EntityConstructor } from '../orm/entity-metadata.js';
+import { getTableDefFromEntity } from '../decorators/bootstrap.js';
+
+/**
+ * Represents a target for query operations, which can be either a table definition
+ * or an entity constructor. This type allows flexible targeting of database tables
+ * through either direct table definitions or entity classes decorated with ORM metadata.
+ *
+ * @template TTable - The table definition type, defaults to TableDef
+ */
+export type QueryTarget<TTable extends TableDef = TableDef> = TTable | EntityConstructor;
+
+const resolveEntityTarget = <TTable extends TableDef>(ctor: EntityConstructor): TTable => {
+    const table = getTableDefFromEntity(ctor);
+    if (!table) {
+        throw new Error(`Entity '${ctor.name}' is not registered with decorators`);
+    }
+    return table as TTable;
+};
+
+/**
+ * Resolves a QueryTarget to its corresponding table definition.
+ *
+ * If the target is already a TableDef, it returns it directly.
+ * If the target is an EntityConstructor, it retrieves the associated table definition
+ * from the entity's metadata.
+ *
+ * @template TTable - The table definition type
+ * @param target - The query target to resolve
+ * @returns The resolved table definition
+ * @throws Error if the entity constructor is not registered with decorators
+ *
+ * @example
+ * ```typescript
+ * const table = resolveTable(UserTable); // Returns UserTable directly
+ * const table2 = resolveTable(UserEntity); // Returns table def from UserEntity metadata
+ * ```
+ */
+export const resolveTable = <TTable extends TableDef>(target: QueryTarget<TTable>): TTable => {
+    if (isTableDef(target)) {
+        return target as TTable;
+    }
+    return resolveEntityTarget(target as EntityConstructor);
+};

package/src/query-builder/delete-query-state.ts

@@ -14,6 +14,11 @@ export class DeleteQueryState {
   public readonly table: TableDef;
   public readonly ast: DeleteQueryNode;
 
+  /**
+   * Creates a new DeleteQueryState instance
+   * @param table - The table definition for the DELETE query
+   * @param ast - Optional initial AST node, defaults to a basic DELETE query
+   */
   constructor(table: TableDef, ast?: DeleteQueryNode) {
     this.table = table;
     this.ast = ast ?? {
@@ -27,6 +32,11 @@ export class DeleteQueryState {
     return new DeleteQueryState(this.table, nextAst);
   }
 
+  /**
+   * Adds a WHERE clause to the DELETE query
+   * @param expr - The expression to use as the WHERE condition
+   * @returns A new DeleteQueryState with the WHERE clause added
+   */
   withWhere(expr: ExpressionNode): DeleteQueryState {
     return this.clone({
       ...this.ast,
@@ -34,6 +44,11 @@ export class DeleteQueryState {
     });
   }
 
+  /**
+   * Adds a RETURNING clause to the DELETE query
+   * @param columns - The columns to return after deletion
+   * @returns A new DeleteQueryState with the RETURNING clause added
+   */
   withReturning(columns: ColumnNode[]): DeleteQueryState {
     return this.clone({
       ...this.ast,
@@ -41,6 +56,11 @@ export class DeleteQueryState {
     });
   }
 
+  /**
+   * Adds a USING clause to the DELETE query
+   * @param source - The table source to use in the USING clause
+   * @returns A new DeleteQueryState with the USING clause added
+   */
   withUsing(source: TableSourceNode): DeleteQueryState {
     return this.clone({
       ...this.ast,
@@ -48,6 +68,11 @@ export class DeleteQueryState {
     });
   }
 
+  /**
+   * Adds a JOIN clause to the DELETE query
+   * @param join - The join node to add
+   * @returns A new DeleteQueryState with the JOIN clause added
+   */
   withJoin(join: JoinNode): DeleteQueryState {
     return this.clone({
       ...this.ast,
@@ -55,6 +80,11 @@ export class DeleteQueryState {
     });
   }
 
+  /**
+   * Sets an alias for the table in the DELETE query
+   * @param alias - The alias to assign to the table
+   * @returns A new DeleteQueryState with the table alias set
+   */
   withTableAlias(alias: string): DeleteQueryState {
     return this.clone({
       ...this.ast,

package/src/query-builder/delete.ts

@@ -2,12 +2,14 @@ import { TableDef } from '../schema/table.js';
 import { ColumnDef } from '../schema/column.js';
 import { ColumnNode, ExpressionNode } from '../core/ast/expression.js';
 import { JOIN_KINDS, JoinKind } from '../core/sql/sql.js';
-import { CompiledQuery, DeleteCompiler, Dialect } from '../core/dialect/abstract.js';
+import { CompiledQuery, Dialect } from '../core/dialect/abstract.js';
 import { DialectKey, resolveDialectInput } from '../core/dialect/dialect-factory.js';
 import { TableSourceNode, DeleteQueryNode } from '../core/ast/query.js';
 import { DeleteQueryState } from './delete-query-state.js';
 import { createJoinNode } from '../core/ast/join-node.js';
 import { buildColumnNode } from '../core/ast/builders.js';
+import { OrmSession } from '../orm/orm-session.js';
+import { QueryResult } from '../core/execution/db-executor.js';
 
 type DeleteDialectInput = Dialect | DialectKey;
 
@@ -18,6 +20,11 @@ export class DeleteQueryBuilder<T> {
   private readonly table: TableDef;
   private readonly state: DeleteQueryState;
 
+  /**
+   * Creates a new DeleteQueryBuilder instance
+   * @param table - The table definition for the DELETE query
+   * @param state - Optional initial query state, defaults to a new DeleteQueryState
+   */
   constructor(table: TableDef, state?: DeleteQueryState) {
     this.table = table;
     this.state = state ?? new DeleteQueryState(table);
@@ -27,18 +34,41 @@ export class DeleteQueryBuilder<T> {
     return new DeleteQueryBuilder(this.table, state);
   }
 
+  /**
+   * Adds a WHERE clause to the DELETE query
+   * @param expr - The expression to use as the WHERE condition
+   * @returns A new DeleteQueryBuilder with the WHERE clause added
+   */
   where(expr: ExpressionNode): DeleteQueryBuilder<T> {
     return this.clone(this.state.withWhere(expr));
   }
 
+  /**
+   * Sets an alias for the table in the DELETE query
+   * @param alias - The alias to assign to the table
+   * @returns A new DeleteQueryBuilder with the table alias set
+   */
   as(alias: string): DeleteQueryBuilder<T> {
     return this.clone(this.state.withTableAlias(alias));
   }
 
+  /**
+   * Adds a USING clause to the DELETE query
+   * @param source - The table source to use in the USING clause
+   * @returns A new DeleteQueryBuilder with the USING clause added
+   */
   using(source: TableDef | TableSourceNode): DeleteQueryBuilder<T> {
     return this.clone(this.state.withUsing(this.resolveTableSource(source)));
   }
 
+  /**
+   * Adds a JOIN clause to the DELETE query
+   * @param table - The table to join with
+   * @param condition - The join condition expression
+   * @param kind - The type of join (defaults to INNER)
+   * @param relationName - Optional name for the relation
+   * @returns A new DeleteQueryBuilder with the JOIN clause added
+   */
   join(
     table: TableDef | TableSourceNode | string,
     condition: ExpressionNode,
@@ -50,6 +80,11 @@ export class DeleteQueryBuilder<T> {
     return this.clone(this.state.withJoin(joinNode));
   }
 
+  /**
+   * Adds a RETURNING clause to the DELETE query
+   * @param columns - The columns to return after deletion
+   * @returns A new DeleteQueryBuilder with the RETURNING clause added
+   */
   returning(...columns: (ColumnDef | ColumnNode)[]): DeleteQueryBuilder<T> {
     if (!columns.length) return this;
     const nodes = columns.map(column => buildColumnNode(this.table, column));
@@ -68,29 +103,39 @@ export class DeleteQueryBuilder<T> {
     return this.resolveTableSource(table);
   }
 
-  // Existing compiler-based compile stays, but we add a new overload.
-
-  // 1) Keep the old behavior (used internally / tests, if any):
-  compile(compiler: DeleteCompiler): CompiledQuery;
-  // 2) New ergonomic overload:
-  compile(dialect: DeleteDialectInput): CompiledQuery;
-
-  compile(arg: DeleteCompiler | DeleteDialectInput): CompiledQuery {
-    const candidate = arg as { compileDelete?: (ast: DeleteQueryNode) => CompiledQuery };
-    if (typeof candidate.compileDelete === 'function') {
-      // DeleteCompiler path – old behavior
-      return candidate.compileDelete(this.state.ast);
-    }
+  /**
+   * Compiles the DELETE query for the specified dialect
+   * @param dialect - The SQL dialect to compile for
+   * @returns The compiled query with SQL and parameters
+   */
+  compile(dialect: DeleteDialectInput): CompiledQuery {
+    const resolved = resolveDialectInput(dialect);
+    return resolved.compileDelete(this.state.ast);
+  }
 
-    // Dialect | string path – new behavior
-    const dialect = resolveDialectInput(arg as DeleteDialectInput);
-    return dialect.compileDelete(this.state.ast);
+  /**
+   * Returns the SQL string for the DELETE query
+   * @param dialect - The SQL dialect to generate SQL for
+   * @returns The SQL string representation of the query
+   */
+  toSql(dialect: DeleteDialectInput): string {
+    return this.compile(dialect).sql;
   }
 
-  toSql(arg: DeleteCompiler | DeleteDialectInput): string {
-    return this.compile(arg as DeleteCompiler).sql;
+  /**
+   * Executes the DELETE query using the provided session
+   * @param session - The ORM session to execute the query with
+   * @returns A promise that resolves to the query results
+   */
+  async execute(session: OrmSession): Promise<QueryResult[]> {
+    const compiled = this.compile(session.dialect);
+    return session.executor.executeSql(compiled.sql, compiled.params);
   }
 
+  /**
+   * Returns the Abstract Syntax Tree (AST) representation of the query
+   * @returns The AST node for the DELETE query
+   */
   getAST(): DeleteQueryNode {
     return this.state.ast;
   }

package/src/query-builder/hydration-manager.ts

@@ -113,6 +113,11 @@ export class HydrationManager {
     return hasPagination && this.hasMultiplyingRelations(plan);
   }
 
+  /**
+   * Checks if the hydration plan contains relations that multiply rows
+   * @param plan - Hydration plan to check
+   * @returns True if plan has HasMany or BelongsToMany relations
+   */
   private hasMultiplyingRelations(plan: HydrationPlan): boolean {
     return plan.relations.some(
       rel => rel.type === RelationKinds.HasMany || rel.type === RelationKinds.BelongsToMany
@@ -203,6 +208,12 @@ export class HydrationManager {
     };
   }
 
+  /**
+   * Generates a unique CTE name by appending a suffix if needed
+   * @param existing - Existing CTE nodes
+   * @param baseName - Base name for the CTE
+   * @returns Unique CTE name
+   */
   private nextCteName(existing: CommonTableExpressionNode[] | undefined, baseName: string): string {
     const names = new Set((existing ?? []).map(cte => cte.name));
     let candidate = baseName;
@@ -216,6 +227,11 @@ export class HydrationManager {
     return candidate;
   }
 
+  /**
+   * Extracts projection names from column nodes
+   * @param columns - Projection nodes
+   * @returns Array of names or undefined if any column lacks name/alias
+   */
   private getProjectionNames(columns: ProjectionNode[]): string[] | undefined {
     const names: string[] = [];
     for (const col of columns) {
@@ -227,6 +243,11 @@ export class HydrationManager {
     return names;
   }
 
+  /**
+   * Builds a map of column keys to their aliases from projection nodes
+   * @param columns - Projection nodes
+   * @returns Map of 'table.name' to alias
+   */
   private buildProjectionAliasMap(columns: ProjectionNode[]): Map<string, string> {
     const map = new Map<string, string>();
     for (const col of columns) {
@@ -238,6 +259,15 @@ export class HydrationManager {
     return map;
   }
 
+  /**
+   * Maps order by nodes to use base CTE alias
+   * @param orderBy - Original order by nodes
+   * @param plan - Hydration plan
+   * @param projectionAliases - Map of column aliases
+   * @param baseAlias - Base CTE alias
+   * @param availableColumns - Set of available column names
+   * @returns Mapped order by nodes, null if cannot map
+   */
   private mapOrderBy(
     orderBy: OrderByNode[] | undefined,
     plan: HydrationPlan,
@@ -261,6 +291,15 @@ export class HydrationManager {
     return mapped;
   }
 
+  /**
+   * Maps a single ordering term to use base CTE alias
+   * @param term - Ordering term to map
+   * @param plan - Hydration plan
+   * @param projectionAliases - Map of column aliases
+   * @param baseAlias - Base CTE alias
+   * @param availableColumns - Set of available column names
+   * @returns Mapped term or null if cannot map
+   */
   private mapOrderingTerm(
     term: OrderByNode['term'],
     plan: HydrationPlan,
@@ -285,6 +324,13 @@ export class HydrationManager {
     return null;
   }
 
+  /**
+   * Builds column nodes for paging CTE
+   * @param primaryKey - Primary key name
+   * @param orderBy - Order by nodes
+   * @param tableAlias - Table alias for columns
+   * @returns Array of column nodes for paging
+   */
   private buildPagingColumns(primaryKey: string, orderBy: OrderByNode[] | undefined, tableAlias: string): ColumnNode[] {
     const columns: ColumnNode[] = [{ type: 'Column', table: tableAlias, name: primaryKey, alias: primaryKey }];
 

package/src/query-builder/insert-query-state.ts

@@ -20,6 +20,11 @@ export class InsertQueryState {
   public readonly table: TableDef;
   public readonly ast: InsertQueryNode;
 
+  /**
+   * Creates a new InsertQueryState instance
+   * @param table - The table definition for the INSERT query
+   * @param ast - Optional initial AST node, defaults to a basic INSERT query
+   */
   constructor(table: TableDef, ast?: InsertQueryNode) {
     this.table = table;
     this.ast = ast ?? {
@@ -55,6 +60,13 @@ export class InsertQueryState {
     return buildColumnNodes(this.table, names);
   }
 
+  /**
+   * Adds VALUES clause to the INSERT query
+   * @param rows - Array of row objects to insert
+   * @returns A new InsertQueryState with the VALUES clause added
+   * @throws Error if mixing VALUES with SELECT source
+   * @throws Error if invalid values are provided
+   */
   withValues(rows: Record<string, unknown>[]): InsertQueryState {
     if (!rows.length) return this;
 
@@ -88,6 +100,11 @@ export class InsertQueryState {
     });
   }
 
+  /**
+   * Sets the columns for the INSERT query
+   * @param columns - Column nodes to insert into
+   * @returns A new InsertQueryState with the specified columns
+   */
   withColumns(columns: ColumnNode[]): InsertQueryState {
     if (!columns.length) return this;
     return this.clone({
@@ -96,6 +113,14 @@ export class InsertQueryState {
     });
   }
 
+  /**
+   * Adds SELECT source to the INSERT query
+   * @param query - The SELECT query to use as source
+   * @param columns - Target columns for the INSERT
+   * @returns A new InsertQueryState with the SELECT source
+   * @throws Error if mixing SELECT with VALUES source
+   * @throws Error if no destination columns specified
+   */
   withSelect(query: SelectQueryNode, columns: ColumnNode[]): InsertQueryState {
     const targetColumns =
       columns.length
@@ -122,6 +147,11 @@ export class InsertQueryState {
     });
   }
 
+  /**
+   * Adds a RETURNING clause to the INSERT query
+   * @param columns - Columns to return after insertion
+   * @returns A new InsertQueryState with the RETURNING clause added
+   */
   withReturning(columns: ColumnNode[]): InsertQueryState {
     return this.clone({
       ...this.ast,

package/src/query-builder/insert.ts

@@ -17,6 +17,11 @@ export class InsertQueryBuilder<T> {
   private readonly table: TableDef;
   private readonly state: InsertQueryState;
 
+  /**
+   * Creates a new InsertQueryBuilder instance
+   * @param table - The table definition for the INSERT query
+   * @param state - Optional initial query state, defaults to a new InsertQueryState
+   */
   constructor(table: TableDef, state?: InsertQueryState) {
     this.table = table;
     this.state = state ?? new InsertQueryState(table);
@@ -26,17 +31,34 @@ export class InsertQueryBuilder<T> {
     return new InsertQueryBuilder(this.table, state);
   }
 
+  /**
+   * Adds VALUES to the INSERT query
+   * @param rowOrRows - Single row object or array of row objects to insert
+   * @returns A new InsertQueryBuilder with the VALUES clause added
+   */
   values(rowOrRows: Record<string, unknown> | Record<string, unknown>[]): InsertQueryBuilder<T> {
     const rows = Array.isArray(rowOrRows) ? rowOrRows : [rowOrRows];
     if (!rows.length) return this;
     return this.clone(this.state.withValues(rows));
   }
 
+  /**
+   * Specifies the columns for the INSERT query
+   * @param columns - Column definitions or nodes to insert into
+   * @returns A new InsertQueryBuilder with the specified columns
+   */
   columns(...columns: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T> {
     if (!columns.length) return this;
     return this.clone(this.state.withColumns(this.resolveColumnNodes(columns)));
   }
 
+  /**
+   * Sets the source of the INSERT query to a SELECT query
+   * @template TSource - The source table type
+   * @param query - The SELECT query or query builder to use as source
+   * @param columns - Optional target columns for the INSERT
+   * @returns A new InsertQueryBuilder with the SELECT source
+   */
   fromSelect<TSource extends TableDef>(
     query: SelectQueryNode | SelectQueryBuilder<unknown, TSource>,
     columns: (ColumnDef | ColumnNode)[] = []
@@ -46,6 +68,11 @@ export class InsertQueryBuilder<T> {
     return this.clone(this.state.withSelect(ast, nodes));
   }
 
+  /**
+   * Adds a RETURNING clause to the INSERT query
+   * @param columns - Columns to return after insertion
+   * @returns A new InsertQueryBuilder with the RETURNING clause added
+   */
   returning(...columns: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T> {
     if (!columns.length) return this;
     const nodes = columns.map(column => buildColumnNode(this.table, column));
@@ -68,9 +95,17 @@ export class InsertQueryBuilder<T> {
 
   // Existing compiler-based compile stays, but we add a new overload.
 
-  // 1) Keep the old behavior (used internally / tests, if any):
+  /**
+   * Compiles the INSERT query
+   * @param compiler - The INSERT compiler to use
+   * @returns The compiled query with SQL and parameters
+   */
   compile(compiler: InsertCompiler): CompiledQuery;
-  // 2) New ergonomic overload:
+  /**
+   * Compiles the INSERT query for the specified dialect
+   * @param dialect - The SQL dialect to compile for
+   * @returns The compiled query with SQL and parameters
+   */
   compile(dialect: InsertDialectInput): CompiledQuery;
 
   compile(arg: InsertCompiler | InsertDialectInput): CompiledQuery {
@@ -85,10 +120,19 @@ export class InsertQueryBuilder<T> {
     return dialect.compileInsert(this.state.ast);
   }
 
+  /**
+   * Returns the SQL string for the INSERT query
+   * @param arg - The compiler or dialect to generate SQL for
+   * @returns The SQL string representation of the query
+   */
   toSql(arg: InsertCompiler | InsertDialectInput): string {
     return this.compile(arg as InsertCompiler).sql;
   }
 
+  /**
+   * Returns the Abstract Syntax Tree (AST) representation of the query
+   * @returns The AST node for the INSERT query
+   */
   getAST(): InsertQueryNode {
     return this.state.ast;
   }