metal-orm 1.0.43 → 1.0.45

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

@@ -50,15 +50,49 @@ export interface OperandVisitor<R> {
 type ExpressionDispatch = <R>(node: ExpressionNode, visitor: ExpressionVisitor<R>) => R;
 type OperandDispatch = <R>(node: OperandNode, visitor: OperandVisitor<R>) => R;
 
-const expressionDispatchers = new Map<string, ExpressionDispatch>();
-const operandDispatchers = new Map<string, OperandDispatch>();
+/**
+ * Registry class for managing dispatchers in an immutable way
+ */
+class DispatcherRegistry<T> {
+  private readonly dispatchers: ReadonlyMap<string, T>;
+
+  constructor(dispatchers: Map<string, T> = new Map()) {
+    this.dispatchers = dispatchers;
+  }
+
+  /**
+   * Registers a new dispatcher and returns a new registry instance
+   */
+  register(type: string, dispatcher: T): DispatcherRegistry<T> {
+    const newMap = new Map(this.dispatchers);
+    newMap.set(type, dispatcher);
+    return new DispatcherRegistry(newMap);
+  }
+
+  /**
+   * Gets a dispatcher for the given type
+   */
+  get(type: string): T | undefined {
+    return this.dispatchers.get(type);
+  }
+
+  /**
+   * Returns a new empty registry
+   */
+  clear(): DispatcherRegistry<T> {
+    return new DispatcherRegistry();
+  }
+}
+
+let expressionRegistry = new DispatcherRegistry<ExpressionDispatch>();
+let operandRegistry = new DispatcherRegistry<OperandDispatch>();
 
 /**
  * Registers a dispatcher for a custom expression node type.
  * Allows new node kinds without modifying the core switch.
  */
 export const registerExpressionDispatcher = (type: string, dispatcher: ExpressionDispatch): void => {
-  expressionDispatchers.set(type, dispatcher);
+  expressionRegistry = expressionRegistry.register(type, dispatcher);
 };
 
 /**
@@ -66,14 +100,19 @@ export const registerExpressionDispatcher = (type: string, dispatcher: Expressio
  * Allows new node kinds without modifying the core switch.
  */
 export const registerOperandDispatcher = (type: string, dispatcher: OperandDispatch): void => {
-  operandDispatchers.set(type, dispatcher);
+  operandRegistry = operandRegistry.register(type, dispatcher);
 };
 
 /**
  * Clears all registered dispatchers. Primarily for tests.
  */
-export const clearExpressionDispatchers = (): void => expressionDispatchers.clear();
-export const clearOperandDispatchers = (): void => operandDispatchers.clear();
+export const clearExpressionDispatchers = (): void => {
+  expressionRegistry = expressionRegistry.clear();
+};
+
+export const clearOperandDispatchers = (): void => {
+  operandRegistry = operandRegistry.clear();
+};
 
 const getNodeType = (node: { type?: string } | null | undefined): string | undefined =>
   typeof node === 'object' && node !== null && typeof node.type === 'string' ? node.type : undefined;
@@ -91,7 +130,7 @@ const unsupportedOperand = (node: OperandNode): never => {
  * @param visitor - Visitor implementation
  */
 export const visitExpression = <R>(node: ExpressionNode, visitor: ExpressionVisitor<R>): R => {
-  const dynamic = expressionDispatchers.get(node.type);
+  const dynamic = expressionRegistry.get(node.type);
   if (dynamic) return dynamic(node, visitor);
 
   switch (node.type) {
@@ -129,7 +168,7 @@ export const visitExpression = <R>(node: ExpressionNode, visitor: ExpressionVisi
  * @param visitor - Visitor implementation
  */
 export const visitOperand = <R>(node: OperandNode, visitor: OperandVisitor<R>): R => {
-  const dynamic = operandDispatchers.get(node.type);
+  const dynamic = operandRegistry.get(node.type);
   if (dynamic) return dynamic(node, visitor);
 
   switch (node.type) {

package/src/core/ast/helpers.ts

@@ -0,0 +1,23 @@
+import { ColumnNode, LiteralNode } from './expression.js';
+
+/**
+ * Creates a column node for use in expressions
+ * @param table - Table name
+ * @param name - Column name
+ * @returns ColumnNode with the specified table and name
+ */
+export const createColumn = (table: string, name: string): ColumnNode => ({
+    type: 'Column',
+    table,
+    name
+});
+
+/**
+ * Creates a literal value node for use in expressions
+ * @param val - Literal value (string or number)
+ * @returns LiteralNode with the specified value
+ */
+export const createLiteral = (val: string | number): LiteralNode => ({
+    type: 'Literal',
+    value: val
+});

package/src/core/ast/join-node.ts

@@ -17,8 +17,24 @@ export const createJoinNode = (
   type: 'Join',
   kind,
   table: typeof tableName === 'string'
-    ? ({ type: 'Table', name: tableName } as TableNode)
+    ? (parseQualifiedTableRef(tableName) as TableNode)
     : (tableName as TableSourceNode),
   condition,
   meta: relationName ? ({ relationName } as JoinMetadata) : undefined
 });
+
+/**
+ * Parses a simple qualified reference like `schema.table` into a structured TableNode.
+ *
+ * Notes:
+ * - We intentionally only support a single dot here.
+ * - For multi-part qualification (server/db/schema/table), callers should pass a TableNode.
+ */
+const parseQualifiedTableRef = (ref: string): TableNode => {
+  const parts = ref.split('.');
+  if (parts.length === 2) {
+    const [schema, name] = parts;
+    return { type: 'Table', schema, name };
+  }
+  return { type: 'Table', name: ref };
+};

package/src/core/ddl/dialects/base-schema-dialect.ts

@@ -4,6 +4,7 @@ import { ColumnDef, ForeignKeyReference } from '../../../schema/column.js';
 import { IndexDef, TableDef } from '../../../schema/table.js';
 import { DatabaseTable, DatabaseColumn, ColumnDiff } from '../schema-types.js';
 
+/** A table-like object with name and optional schema. */
 type TableLike = { name: string; schema?: string };
 
 /**
@@ -11,10 +12,15 @@ type TableLike = { name: string; schema?: string };
  * Concrete dialects only override the small surface area instead of reimplementing everything.
  */
 export abstract class BaseSchemaDialect implements SchemaDialect {
+  /** The name of the dialect. */
   abstract readonly name: DialectName;
+  /** Quotes an identifier for use in SQL. */
   abstract quoteIdentifier(id: string): string;
+  /** Renders the column type for SQL. */
   abstract renderColumnType(column: ColumnDef): string;
+  /** Renders the auto-increment clause for SQL. */
   abstract renderAutoIncrement(column: ColumnDef, table: TableDef): string | undefined;
+  /** Renders an index for SQL. */
   abstract renderIndex(table: TableDef, index: IndexDef): string;
   supportsPartialIndexes(): boolean {
     return false;
@@ -25,7 +31,7 @@ export abstract class BaseSchemaDialect implements SchemaDialect {
     }
     return this.quoteIdentifier(table.name);
   }
-  // Each dialect should provide its own formatter
+  /** The literal formatter for the dialect. */
   abstract get literalFormatter(): LiteralFormatter;
 
   renderDefault(value: unknown, _column: ColumnDef): string {

package/src/core/ddl/dialects/index.ts

@@ -1,3 +1,4 @@
+/** Re-exports for schema dialects. */
 export { BaseSchemaDialect } from './base-schema-dialect.js';
 export { PostgresSchemaDialect } from './postgres-schema-dialect.js';
 export { MySqlSchemaDialect } from './mysql-schema-dialect.js';

package/src/core/ddl/dialects/mssql-schema-dialect.ts

@@ -6,6 +6,7 @@ import { IndexDef, TableDef } from '../../../schema/table.js';
 import { ColumnDiff, DatabaseColumn, DatabaseTable } from '../schema-types.js';
 import { DialectName } from '../schema-dialect.js';
 
+/** MSSQL schema dialect implementation. */
 export class MSSqlSchemaDialect extends BaseSchemaDialect {
   name: DialectName = 'mssql';
 

package/src/core/ddl/dialects/mysql-schema-dialect.ts

@@ -7,6 +7,7 @@ import { ColumnDiff, DatabaseColumn, DatabaseTable } from '../schema-types.js';
 import { renderColumnDefinition } from '../schema-generator.js';
 import { DialectName } from '../schema-dialect.js';
 
+/** MySQL schema dialect implementation. */
 export class MySqlSchemaDialect extends BaseSchemaDialect {
   name: DialectName = 'mysql';
 

package/src/core/ddl/dialects/postgres-schema-dialect.ts

@@ -6,6 +6,7 @@ import { IndexDef, TableDef } from '../../../schema/table.js';
 import { ColumnDiff, DatabaseColumn, DatabaseTable } from '../schema-types.js';
 import { DialectName } from '../schema-dialect.js';
 
+/** PostgreSQL schema dialect implementation. */
 export class PostgresSchemaDialect extends BaseSchemaDialect {
   readonly name: DialectName = 'postgres';
 

package/src/core/ddl/dialects/sqlite-schema-dialect.ts

@@ -6,6 +6,7 @@ import { IndexDef, TableDef } from '../../../schema/table.js';
 import { ColumnDiff, DatabaseColumn, DatabaseTable } from '../schema-types.js';
 import { DialectName } from '../schema-dialect.js';
 
+/** SQLite schema dialect implementation. */
 export class SQLiteSchemaDialect extends BaseSchemaDialect {
   name: DialectName = 'sqlite';
 

package/src/core/ddl/introspect/catalogs/index.ts

@@ -1 +1,2 @@
+/** Re-exports for PostgreSQL catalog definitions. */
 export * from './postgres.js';

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

@@ -1,6 +1,7 @@
 import { defineTable } from '../../../../schema/table.js';
 import { col } from '../../../../schema/column.js';
 
+/** Table definition for information_schema.columns, providing metadata about table columns. */
 export const PgInformationSchemaColumns = defineTable(
   'columns',
   {
@@ -134,6 +135,7 @@ export const PgReferentialConstraints = defineTable(
   { schema: 'information_schema' }
 );
 
+/** Default export containing commonly used PostgreSQL catalog table definitions. */
 export default {
   PgInformationSchemaColumns,
   PgClass,

package/src/core/ddl/introspect/context.ts

@@ -1,8 +1,14 @@
 import type { Dialect } from '../../dialect/abstract.js';
 import type { DbExecutor } from '../../execution/db-executor.js';
 
+/**
+ * Context for schema introspection operations.
+ * Provides the necessary components to perform database schema introspection.
+ */
 export interface IntrospectContext {
+  /** The database dialect used for introspection. */
   dialect: Dialect;
+  /** The database executor for running introspection queries. */
   executor: DbExecutor;
 }
 

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

@@ -13,10 +13,23 @@ const fn = (name: string, args: OperandInput[]): FunctionNode => ({
   args: args.map(toOperand)
 });
 
+/**
+ * Creates a pg_get_expr function call AST node.
+ * @param expr - The expression.
+ * @param relid - The relation ID.
+ * @returns The function node.
+ */
 export const pgGetExpr = (expr: OperandInput, relid: OperandInput): FunctionNode =>
   fn('pg_get_expr', [expr, relid]);
 
+/**
+ * Creates a format_type function call AST node.
+ * @param typeOid - The type OID.
+ * @param typmod - The type modifier.
+ * @returns The function node.
+ */
 export const formatType = (typeOid: OperandInput, typmod: OperandInput): FunctionNode =>
   fn('format_type', [typeOid, typmod]);
 
+/** Default export with PostgreSQL-specific function helpers. */
 export default { pgGetExpr, formatType };

package/src/core/ddl/introspect/mssql.ts

@@ -3,6 +3,7 @@ import { queryRows, shouldIncludeTable } from './utils.js';
 import { DatabaseSchema, DatabaseTable, DatabaseIndex, DatabaseColumn } from '../schema-types.js';
 import { DbExecutor } from '../../execution/db-executor.js';
 
+/** Row type for MSSQL column information. */
 type MssqlColumnRow = {
   table_schema: string;
   table_name: string;
@@ -13,6 +14,7 @@ type MssqlColumnRow = {
   column_default: string | null;
 };
 
+/** Row type for MSSQL primary key information. */
 type MssqlPrimaryKeyRow = {
   table_schema: string;
   table_name: string;
@@ -20,6 +22,7 @@ type MssqlPrimaryKeyRow = {
   key_ordinal: number;
 };
 
+/** Row type for MSSQL index information. */
 type MssqlIndexRow = {
   table_schema: string;
   table_name: string;
@@ -29,6 +32,7 @@ type MssqlIndexRow = {
   filter_definition: string | null;
 };
 
+/** Row type for MSSQL index column information. */
 type MssqlIndexColumnRow = {
   table_schema: string;
   table_name: string;
@@ -37,7 +41,14 @@ type MssqlIndexColumnRow = {
   key_ordinal: number;
 };
 
+/** MSSQL schema introspector implementation. */
 export const mssqlIntrospector: SchemaIntrospector = {
+  /**
+   * Introspects the MSSQL database schema.
+   * @param ctx - The introspection context containing the database executor.
+   * @param options - Options for introspection, such as schema filter.
+   * @returns A promise that resolves to the introspected database schema.
+   */
   async introspect(ctx: { executor: DbExecutor }, options: IntrospectOptions): Promise<DatabaseSchema> {
     const schema = options.schema;
     const filterSchema = schema ? 'sch.name = @p1' : '1=1';

package/src/core/ddl/introspect/mysql.ts

@@ -3,6 +3,7 @@ import { queryRows, shouldIncludeTable } from './utils.js';
 import { DatabaseSchema, DatabaseTable, DatabaseIndex, DatabaseColumn } from '../schema-types.js';
 import { DbExecutor } from '../../execution/db-executor.js';
 
+/** Row type for MySQL column information. */
 type MysqlColumnRow = {
   table_schema: string;
   table_name: string;
@@ -27,6 +28,7 @@ type MysqlIndexRow = {
   cols: string | null;
 };
 
+/** MySQL schema introspector. */
 export const mysqlIntrospector: SchemaIntrospector = {
   async introspect(ctx: { executor: DbExecutor }, options: IntrospectOptions): Promise<DatabaseSchema> {
     const schema = options.schema;

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

@@ -13,6 +13,7 @@ import type { ColumnNode, ExpressionNode } from '../../ast/expression-nodes.js';
 import { fnTable } from '../../ast/builders.js';
 import { runSelect, runSelectNode } from './run-select.js';
 
+/** Row type for PostgreSQL column introspection from information_schema.columns. */
 type ColumnIntrospectRow = {
   table_schema: string;
   table_name: string;
@@ -23,6 +24,7 @@ type ColumnIntrospectRow = {
   ordinal_position: number | null;
 };
 
+/** Row type for PostgreSQL primary key introspection from key_column_usage and table_constraints. */
 type PrimaryKeyIntrospectRow = {
   table_schema: string;
   table_name: string;
@@ -31,6 +33,7 @@ type PrimaryKeyIntrospectRow = {
   constraint_name: string;
 };
 
+/** Row type for PostgreSQL foreign key introspection from various constraint tables. */
 type ForeignKeyIntrospectRow = {
   table_schema: string;
   table_name: string;
@@ -41,6 +44,7 @@ type ForeignKeyIntrospectRow = {
   foreign_column_name: string;
 };
 
+/** Represents a foreign key reference entry with optional referential actions. */
 type ForeignKeyEntry = {
   table: string;
   column: string;
@@ -48,6 +52,7 @@ type ForeignKeyEntry = {
   onUpdate?: ReferentialAction;
 };
 
+/** Row type for PostgreSQL index query results from pg_catalog tables. */
 type IndexQueryRow = {
   table_schema: string;
   table_name: string;
@@ -58,6 +63,7 @@ type IndexQueryRow = {
   ord: number | null;
 };
 
+/** Grouped index information used for aggregating index columns. */
 type IndexGroup = {
   table_schema: string;
   table_name: string;
@@ -67,7 +73,15 @@ type IndexGroup = {
   cols: { ord: number; att: string | null }[];
 };
 
+/** PostgreSQL schema introspector. */
 export const postgresIntrospector: SchemaIntrospector = {
+  /**
+   * Introspects the PostgreSQL database schema by querying information_schema and pg_catalog.
+   * Builds tables with columns, primary keys, foreign keys, and indexes.
+   * @param ctx - The introspection context with database executor.
+   * @param options - Options for schema selection and table filtering.
+   * @returns A promise resolving to the complete database schema.
+   */
   async introspect(ctx: IntrospectContext, options: IntrospectOptions): Promise<DatabaseSchema> {
     const schema = options.schema || 'public';
     const tables: DatabaseTable[] = [];

package/src/core/ddl/introspect/registry.ts

@@ -5,8 +5,12 @@ import { mysqlIntrospector } from './mysql.js';
 import { sqliteIntrospector } from './sqlite.js';
 import { mssqlIntrospector } from './mssql.js';
 
+/** Registry mapping dialect names to their corresponding schema introspectors. */
 const registry = new Map<DialectName, SchemaIntrospector>();
 
+/**
+ * Registers the built-in schema introspectors for all supported database dialects.
+ */
 const registerBuiltInIntrospectors = () => {
   registry.set('postgres', postgresIntrospector);
   registry.set('mysql', mysqlIntrospector);
@@ -16,10 +20,20 @@ const registerBuiltInIntrospectors = () => {
 
 registerBuiltInIntrospectors();
 
+/**
+ * Registers a schema introspector for a dialect.
+ * @param dialect - The dialect name.
+ * @param introspector - The schema introspector.
+ */
 export const registerSchemaIntrospector = (dialect: DialectName, introspector: SchemaIntrospector): void => {
   registry.set(dialect, introspector);
 };
 
+/**
+ * Gets the schema introspector for a dialect.
+ * @param dialect - The dialect name.
+ * @returns The schema introspector or undefined if not found.
+ */
 export const getSchemaIntrospector = (dialect: DialectName): SchemaIntrospector | undefined => {
   return registry.get(dialect);
 };

package/src/core/ddl/introspect/run-select.ts

@@ -3,8 +3,15 @@ import type { SelectQueryNode } from '../../ast/query.js';
 
 import { toRows } from './utils.js';
 
+/** A source that can provide a select query AST. */
 type SelectQuerySource = { getAST(): SelectQueryNode };
 
+/**
+ * Runs a select query from a query builder and returns the results.
+ * @param qb - The query builder.
+ * @param ctx - The introspection context.
+ * @returns The query results.
+ */
 export async function runSelect<T = Record<string, unknown>>(
   qb: SelectQuerySource,
   ctx: IntrospectContext
@@ -19,6 +26,12 @@ export async function runSelect<T = Record<string, unknown>>(
 
 export default runSelect;
 
+/**
+ * Runs a select query from an AST node and returns the results.
+ * @param ast - The select query AST.
+ * @param ctx - The introspection context.
+ * @returns The query results.
+ */
 export async function runSelectNode<T = Record<string, unknown>>(ast: SelectQueryNode, ctx: IntrospectContext): Promise<T[]> {
   const compiled = ctx.dialect.compileSelect(ast);
   const results = await ctx.executor.executeSql(compiled.sql, compiled.params);

package/src/core/ddl/introspect/sqlite.ts

@@ -4,10 +4,12 @@ import { DatabaseSchema, DatabaseTable, DatabaseIndex } from '../schema-types.js
 import { ReferentialAction } from '../../../schema/column.js';
 import { DbExecutor } from '../../execution/db-executor.js';
 
+/** Row type for SQLite table list from sqlite_master. */
 type SqliteTableRow = {
   name: string;
 };
 
+/** Row type for SQLite table column information from PRAGMA table_info. */
 type SqliteTableInfoRow = {
   name: string;
   type: string;
@@ -16,6 +18,7 @@ type SqliteTableInfoRow = {
   pk: number;
 };
 
+/** Row type for SQLite foreign key information from PRAGMA foreign_key_list. */
 type SqliteForeignKeyRow = {
   table: string;
   from: string;
@@ -24,15 +27,22 @@ type SqliteForeignKeyRow = {
   on_update: string | null;
 };
 
+/** Row type for SQLite index list from PRAGMA index_list. */
 type SqliteIndexListRow = {
   name: string;
   unique: number;
 };
 
+/** Row type for SQLite index column information from PRAGMA index_info. */
 type SqliteIndexInfoRow = {
   name: string;
 };
 
+/**
+ * Converts a SQLite referential action string to a ReferentialAction enum value.
+ * @param value - The string value from SQLite pragma (e.g., 'CASCADE', 'SET NULL').
+ * @returns The corresponding ReferentialAction enum value, or undefined if the value is invalid or null.
+ */
 const toReferentialAction = (value: string | null | undefined): ReferentialAction | undefined => {
   if (!value) return undefined;
   const normalized = value.toUpperCase();
@@ -48,9 +58,21 @@ const toReferentialAction = (value: string | null | undefined): ReferentialActio
   return undefined;
 };
 
+/**
+ * Escapes single quotes in a string for safe inclusion in SQL queries.
+ * @param name - The string to escape.
+ * @returns The escaped string with single quotes doubled.
+ */
 const escapeSingleQuotes = (name: string) => name.replace(/'/g, "''");
 
+/** SQLite schema introspector. */
 export const sqliteIntrospector: SchemaIntrospector = {
+  /**
+   * Introspects the SQLite database schema by querying sqlite_master and various PRAGMAs.
+   * @param ctx - The database execution context containing the DbExecutor.
+   * @param options - Options controlling which tables and schemas to include.
+   * @returns A promise that resolves to the introspected DatabaseSchema.
+   */
   async introspect(ctx: { executor: DbExecutor }, options: IntrospectOptions): Promise<DatabaseSchema> {
     const tables: DatabaseTable[] = [];
     const tableRows = (await queryRows(

package/src/core/ddl/introspect/utils.ts

@@ -1,6 +1,11 @@
 import { DbExecutor, QueryResult } from '../../execution/db-executor.js';
 import { IntrospectOptions } from './types.js';
 
+/**
+ * Converts a query result to an array of row objects.
+ * @param result - The query result.
+ * @returns The array of rows.
+ */
 export const toRows = (result: QueryResult | undefined): Record<string, unknown>[] => {
   if (!result) return [];
   return result.values.map(row =>
@@ -11,6 +16,13 @@ export const toRows = (result: QueryResult | undefined): Record<string, unknown>
   );
 };
 
+/**
+ * Executes a SQL query and returns the rows.
+ * @param executor - The database executor.
+ * @param sql - The SQL query.
+ * @param params - The query parameters.
+ * @returns The array of rows.
+ */
 export const queryRows = async (
   executor: DbExecutor,
   sql: string,
@@ -20,6 +32,12 @@ export const queryRows = async (
   return toRows(first);
 };
 
+/**
+ * Checks if a table should be included in introspection based on options.
+ * @param name - The table name.
+ * @param options - The introspection options.
+ * @returns True if the table should be included.
+ */
 export const shouldIncludeTable = (name: string, options: IntrospectOptions): boolean => {
   if (options.includeTables && !options.includeTables.includes(name)) return false;
   if (options.excludeTables && options.excludeTables.includes(name)) return false;

package/src/core/ddl/naming-strategy.ts

@@ -1,5 +1,11 @@
 import type { TableDef, IndexDef } from '../../schema/table.js';
 
+/**
+ * Derives the name for an index based on the table and index definition.
+ * @param table - The table definition.
+ * @param index - The index definition.
+ * @returns The derived index name.
+ */
 export const deriveIndexName = (table: TableDef, index: IndexDef): string => {
   const base = (index.columns ?? [])
     .map(col => (typeof col === 'string' ? col : col.column))

package/src/core/ddl/schema-dialect.ts

@@ -2,6 +2,7 @@ import type { TableDef, IndexDef } from '../../schema/table.js';
 import type { ColumnDef, ForeignKeyReference } from '../../schema/column.js';
 import type { DatabaseTable, DatabaseColumn, ColumnDiff } from './schema-types.js';
 
+/** The name of a database dialect. */
 export type DialectName =
   | 'postgres'
   | 'mysql'
@@ -9,34 +10,46 @@ export type DialectName =
   | 'mssql'
   | (string & {});
 
+/** Interface for schema dialect implementations that handle database-specific DDL operations. */
 export interface SchemaDialect {
+  /** The name of the dialect. */
   readonly name: DialectName;
 
-  // Minimal quoting surface; reusable for helpers
+  /** Quotes an identifier for use in SQL. */
   quoteIdentifier(id: string): string;
 
-  // Table naming
+  /** Formats the table name for SQL. */
   formatTableName(table: TableDef | DatabaseTable): string;
 
-  // Column rendering
+  /** Renders the column type for SQL. */
   renderColumnType(column: ColumnDef): string;
+  /** Renders the default value for SQL. */
   renderDefault(value: unknown, column: ColumnDef): string;
+  /** Renders the auto-increment clause for SQL. */
   renderAutoIncrement(column: ColumnDef, table: TableDef): string | undefined;
 
-  // Constraints & indexes
+  /** Renders a foreign key reference for SQL. */
   renderReference(ref: ForeignKeyReference, table: TableDef): string;
+  /** Renders an index for SQL. */
   renderIndex(table: TableDef, index: IndexDef): string;
+  /** Renders table options for SQL. */
   renderTableOptions(table: TableDef): string | undefined;
 
-  // Capability flags
+  /** Checks if the dialect supports partial indexes. */
   supportsPartialIndexes(): boolean;
+  /** Checks if the dialect prefers inline primary key auto-increment. */
   preferInlinePkAutoincrement(column: ColumnDef, table: TableDef, pk: string[]): boolean;
 
-  // DDL operations
+  /** Generates SQL to drop a column. */
   dropColumnSql?(table: DatabaseTable, column: string): string[];
+  /** Generates SQL to drop an index. */
   dropIndexSql?(table: DatabaseTable, index: string): string[];
+  /** Generates SQL to drop a table. */
   dropTableSql?(table: DatabaseTable): string[];
+  /** Returns a warning message for dropping a column. */
   warnDropColumn?(table: DatabaseTable, column: string): string | undefined;
+  /** Generates SQL to alter a column. */
   alterColumnSql?(table: TableDef, column: ColumnDef, actualColumn: DatabaseColumn, diff: ColumnDiff): string[];
+  /** Returns a warning message for altering a column. */
   warnAlterColumn?(table: TableDef, column: ColumnDef, actualColumn: DatabaseColumn, diff: ColumnDiff): string | undefined;
 }