metal-orm 1.0.42 → 1.0.44

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

@@ -146,11 +146,20 @@ const operandTypes = new Set<OperandNode['type']>([
   'WindowFunction'
 ]);
 
-export const isOperandNode = (node: any): node is OperandNode => node && operandTypes.has(node.type);
-
-export const isFunctionNode = (node: any): node is FunctionNode => node?.type === 'Function';
-export const isCaseExpressionNode = (node: any): node is CaseExpressionNode => node?.type === 'CaseExpression';
-export const isWindowFunctionNode = (node: any): node is WindowFunctionNode => node?.type === 'WindowFunction';
+const hasTypeProperty = (value: unknown): value is { type?: string } =>
+  typeof value === 'object' && value !== null && 'type' in value;
+
+export const isOperandNode = (node: unknown): node is OperandNode => {
+  if (!hasTypeProperty(node)) return false;
+  return operandTypes.has(node.type as OperandNode['type']);
+};
+
+export const isFunctionNode = (node: unknown): node is FunctionNode =>
+  isOperandNode(node) && node.type === 'Function';
+export const isCaseExpressionNode = (node: unknown): node is CaseExpressionNode =>
+  isOperandNode(node) && node.type === 'CaseExpression';
+export const isWindowFunctionNode = (node: unknown): node is WindowFunctionNode =>
+  isOperandNode(node) && node.type === 'WindowFunction';
 export const isExpressionSelectionNode = (
   node: ColumnRef | FunctionNode | CaseExpressionNode | WindowFunctionNode
 ): node is FunctionNode | CaseExpressionNode | WindowFunctionNode =>

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

@@ -47,18 +47,52 @@ export interface OperandVisitor<R> {
   otherwise?(node: OperandNode): R;
 }
 
-type ExpressionDispatch = <R>(node: any, visitor: ExpressionVisitor<R>) => R;
-type OperandDispatch = <R>(node: any, visitor: OperandVisitor<R>) => 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,21 +100,29 @@ 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;
 
 const unsupportedExpression = (node: ExpressionNode): never => {
-  throw new Error(`Unsupported expression type "${(node as any)?.type ?? 'unknown'}"`);
+  throw new Error(`Unsupported expression type "${getNodeType(node) ?? 'unknown'}"`);
 };
 
 const unsupportedOperand = (node: OperandNode): never => {
-  throw new Error(`Unsupported operand type "${(node as any)?.type ?? 'unknown'}"`);
+  throw new Error(`Unsupported operand type "${getNodeType(node) ?? 'unknown'}"`);
 };
 /**
  * Dispatches an expression node to the visitor
@@ -88,8 +130,8 @@ const unsupportedOperand = (node: OperandNode): never => {
  * @param visitor - Visitor implementation
  */
 export const visitExpression = <R>(node: ExpressionNode, visitor: ExpressionVisitor<R>): R => {
-  const dynamic = expressionDispatchers.get((node as any)?.type);
-  if (dynamic) return dynamic(node as any, visitor);
+  const dynamic = expressionRegistry.get(node.type);
+  if (dynamic) return dynamic(node, visitor);
 
   switch (node.type) {
     case 'BinaryExpression':
@@ -126,8 +168,8 @@ 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 as any)?.type);
-  if (dynamic) return dynamic(node as any, visitor);
+  const dynamic = operandRegistry.get(node.type);
+  if (dynamic) return dynamic(node, visitor);
 
   switch (node.type) {
     case 'Column':

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

@@ -2,7 +2,7 @@ import { JoinNode } from './join.js';
 import { ExpressionNode } from './expression.js';
 import { JoinKind } from '../sql/sql.js';
 import { JoinMetadata } from './join-metadata.js';
-import { TableSourceNode, TableNode, FunctionTableNode } from './query.js';
+import { TableSourceNode, TableNode } from './query.js';
 
 /**
  * Creates a JoinNode ready for AST insertion.
@@ -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/ast/query.ts

@@ -1,12 +1,12 @@
 import {
+  AliasRefNode,
+  CaseExpressionNode,
   ColumnNode,
-  FunctionNode,
   ExpressionNode,
-  ScalarSubqueryNode,
-  CaseExpressionNode,
-  WindowFunctionNode,
+  FunctionNode,
   OperandNode,
-  AliasRefNode
+  ScalarSubqueryNode,
+  WindowFunctionNode
 } from './expression.js';
 import { JoinNode } from './join.js';
 import { OrderDirection } from '../sql/sql.js';
@@ -34,7 +34,7 @@ export interface FunctionTableNode {
   /** Optional schema for the function (some dialects) */
   schema?: string;
   /** Function arguments as operand nodes */
-  args?: any[]; // use any to avoid circular import here; caller should supply OperandNode
+  args?: OperandNode[];
   /** Optional alias for the function table */
   alias?: string;
   /** LATERAL flag */

package/src/core/ast/window-functions.ts

@@ -60,7 +60,11 @@ export const ntile = (n: number): WindowFunctionNode =>
  * @param defaultValue - Default value if no row exists
  * @returns Window function node for LAG
  */
-export const lag = (col: ColumnRef | ColumnNode, offset: number = 1, defaultValue?: any): WindowFunctionNode => {
+export const lag = (
+  col: ColumnRef | ColumnNode,
+  offset: number = 1,
+  defaultValue?: LiteralNode['value']
+): WindowFunctionNode => {
   const args: (ColumnNode | LiteralNode | JsonPathNode)[] = [
     columnOperand(col),
     { type: 'Literal', value: offset }
@@ -78,7 +82,11 @@ export const lag = (col: ColumnRef | ColumnNode, offset: number = 1, defaultValu
  * @param defaultValue - Default value if no row exists
  * @returns Window function node for LEAD
  */
-export const lead = (col: ColumnRef | ColumnNode, offset: number = 1, defaultValue?: any): WindowFunctionNode => {
+export const lead = (
+  col: ColumnRef | ColumnNode,
+  offset: number = 1,
+  defaultValue?: LiteralNode['value']
+): WindowFunctionNode => {
   const args: (ColumnNode | LiteralNode | JsonPathNode)[] = [
     columnOperand(col),
     { type: 'Literal', value: offset }

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

@@ -1,9 +1,10 @@
 import { SchemaDialect, DialectName } from '../schema-dialect.js';
-import { formatLiteral, quoteQualified, createLiteralFormatter, LiteralFormatter } from '../sql-writing.js';
+import { formatLiteral, quoteQualified, LiteralFormatter } from '../sql-writing.js';
 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,20 +31,30 @@ 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 {
+    void _column;
     return formatLiteral(this.literalFormatter, value);
   }
   renderReference(ref: ForeignKeyReference, _table: TableDef): string {
+    void _table;
     const parts = ['REFERENCES', quoteQualified(this, ref.table), `(${this.quoteIdentifier(ref.column)})`];
     if (ref.onDelete) parts.push('ON DELETE', ref.onDelete);
     if (ref.onUpdate) parts.push('ON UPDATE', ref.onUpdate);
-    if (ref.deferrable && this.name === 'postgres') parts.push('DEFERRABLE INITIALLY DEFERRED');
+    const suffix = this.renderReferenceSuffix(ref, _table);
+    if (suffix) parts.push(suffix);
     return parts.join(' ');
   }
+
+  protected renderReferenceSuffix(ref: ForeignKeyReference, _table: TableDef): string | undefined {
+    void ref;
+    void _table;
+    return undefined;
+  }
   renderTableOptions(_table: TableDef): string | undefined {
+    void _table;
     return undefined;
   }
   dropTableSql(table: DatabaseTable): string[] {
@@ -51,12 +67,29 @@ export abstract class BaseSchemaDialect implements SchemaDialect {
     return [`DROP INDEX ${this.quoteIdentifier(index)};`];
   }
   warnDropColumn(_table: DatabaseTable, _column: string): string | undefined {
+    void _table;
+    void _column;
     return undefined;
   }
-  alterColumnSql?(table: TableDef, column: ColumnDef, actualColumn: DatabaseColumn, diff: ColumnDiff): string[] {
+  alterColumnSql?(_table: TableDef, _column: ColumnDef, _actualColumn: DatabaseColumn, _diff: ColumnDiff): string[] {
+    void _table;
+    void _column;
+    void _actualColumn;
+    void _diff;
     return [];
   }
   warnAlterColumn?(_table: TableDef, _column: ColumnDef, _actual: DatabaseColumn, _diff: ColumnDiff): string | undefined {
+    void _table;
+    void _column;
+    void _actual;
+    void _diff;
     return undefined;
   }
+
+  preferInlinePkAutoincrement(_column: ColumnDef, _table: TableDef, _pk: string[]): boolean {
+    void _column;
+    void _table;
+    void _pk;
+    return false;
+  }
 }

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';
 
@@ -120,6 +121,7 @@ export class MSSqlSchemaDialect extends BaseSchemaDialect {
   }
 
   alterColumnSql(table: TableDef, column: ColumnDef, _actual: DatabaseColumn, diff: ColumnDiff): string[] {
+    void _actual;
     const stmts: string[] = [];
     if (diff.typeChanged || diff.nullabilityChanged) {
       const nullability = column.notNull ? 'NOT NULL' : 'NULL';
@@ -131,6 +133,9 @@ export class MSSqlSchemaDialect extends BaseSchemaDialect {
   }
 
   warnAlterColumn(_table: TableDef, _column: ColumnDef, _actual: DatabaseColumn, diff: ColumnDiff): string | undefined {
+    void _table;
+    void _column;
+    void _actual;
     if (diff.defaultChanged || diff.autoIncrementChanged) {
       return 'Altering defaults or identity on MSSQL is not automated (requires dropping/adding default or identity constraints manually).';
     }

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';
 
@@ -125,6 +126,8 @@ export class MySqlSchemaDialect extends BaseSchemaDialect {
   }
 
   alterColumnSql(table: TableDef, column: ColumnDef, _actual: DatabaseColumn, _diff: ColumnDiff): string[] {
+    void _actual;
+    void _diff;
     const rendered = renderColumnDefinition(table, column, this);
     return [`ALTER TABLE ${this.formatTableName(table)} MODIFY COLUMN ${rendered.sql};`];
   }

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

@@ -1,11 +1,12 @@
 import { BaseSchemaDialect } from './base-schema-dialect.js';
 import { deriveIndexName } from '../naming-strategy.js';
 import { renderIndexColumns, createLiteralFormatter } from '../sql-writing.js';
-import { ColumnDef } from '../../../schema/column.js';
+import { ColumnDef, ForeignKeyReference } from '../../../schema/column.js';
 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';
 
@@ -102,6 +103,14 @@ export class PostgresSchemaDialect extends BaseSchemaDialect {
     return true;
   }
 
+  protected renderReferenceSuffix(ref: ForeignKeyReference, _table: TableDef): string | undefined {
+    void _table;
+    if (ref.deferrable) {
+      return 'DEFERRABLE INITIALLY DEFERRED';
+    }
+    return undefined;
+  }
+
   dropColumnSql(table: DatabaseTable, column: string): string[] {
     return [`ALTER TABLE ${this.formatTableName(table)} DROP COLUMN ${this.quoteIdentifier(column)};`];
   }
@@ -114,6 +123,7 @@ export class PostgresSchemaDialect extends BaseSchemaDialect {
   }
 
   alterColumnSql(table: TableDef, column: ColumnDef, actualColumn: DatabaseColumn, diff: ColumnDiff): string[] {
+    void actualColumn;
     const stmts: string[] = [];
     const tableName = this.formatTableName(table);
     const colName = this.quoteIdentifier(column.name);
@@ -145,6 +155,9 @@ export class PostgresSchemaDialect extends BaseSchemaDialect {
   }
 
   warnAlterColumn(_table: TableDef, _column: ColumnDef, _actual: DatabaseColumn, diff: ColumnDiff): string | undefined {
+    void _table;
+    void _column;
+    void _actual;
     if (diff.autoIncrementChanged) {
       return 'Altering identity properties may fail if an existing sequence is attached; verify generated column state.';
     }

package/src/core/ddl/dialects/render-reference.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { BaseSchemaDialect } from './base-schema-dialect.js';
+import { PostgresSchemaDialect } from './postgres-schema-dialect.js';
+import { TableDef } from '../../../schema/table.js';
+import { ForeignKeyReference } from '../../../schema/column.js';
+import { createLiteralFormatter } from '../sql-writing.js';
+
+class DummySchemaDialect extends BaseSchemaDialect {
+    readonly name = 'sqlite';
+    private readonly formatter = createLiteralFormatter({
+        booleanTrue: '1',
+        booleanFalse: '0',
+    });
+
+    get literalFormatter() {
+        return this.formatter;
+    }
+
+    quoteIdentifier(id: string): string {
+        return `"${id}"`;
+    }
+
+    renderColumnType(): string {
+        return 'INTEGER';
+    }
+
+    renderAutoIncrement(): string | undefined {
+        return undefined;
+    }
+
+    renderIndex(): string {
+        return 'CREATE INDEX dummy;';
+    }
+}
+
+const table: TableDef = {
+    name: 'child',
+    columns: {},
+    relations: {},
+};
+
+const deferrableReference: ForeignKeyReference = {
+    table: 'parent',
+    column: 'id',
+    deferrable: true,
+    onDelete: 'CASCADE',
+    onUpdate: 'NO ACTION',
+};
+
+describe('renderReference deferrable handling', () => {
+    it('base dialect remains agnostic to deferrable flags', () => {
+        const dialect = new DummySchemaDialect();
+        const sql = dialect.renderReference(deferrableReference, table);
+        expect(sql).toContain('REFERENCES "parent"');
+        expect(sql).not.toContain('DEFERRABLE INITIALLY DEFERRED');
+    });
+
+    it('Postgres dialect renders the deferrable clause', () => {
+        const dialect = new PostgresSchemaDialect();
+        const sql = dialect.renderReference(deferrableReference, table);
+        expect(sql).toContain('DEFERRABLE INITIALLY DEFERRED');
+    });
+
+    it('Postgres dialect skips the clause when the flag is missing', () => {
+        const dialect = new PostgresSchemaDialect();
+        const sql = dialect.renderReference({ table: 'parent', column: 'id' }, table);
+        expect(sql).not.toContain('DEFERRABLE INITIALLY DEFERRED');
+    });
+});

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';
 
@@ -103,10 +104,13 @@ export class SQLiteSchemaDialect extends BaseSchemaDialect {
   }
 
   dropColumnSql(_table: DatabaseTable, _column: string): string[] {
+    void _table;
+    void _column;
     return [];
   }
 
   dropIndexSql(_table: DatabaseTable, index: string): string[] {
+    void _table;
     return [`DROP INDEX IF EXISTS ${this.quoteIdentifier(index)};`];
   }
 
@@ -116,10 +120,16 @@ export class SQLiteSchemaDialect extends BaseSchemaDialect {
   }
 
   alterColumnSql(_table: TableDef, _column: ColumnDef, _actual: DatabaseColumn, _diff: ColumnDiff): string[] {
+    void _table;
+    void _column;
+    void _actual;
+    void _diff;
     return [];
   }
 
   warnAlterColumn(table: TableDef, column: ColumnDef, _actual: DatabaseColumn, _diff: ColumnDiff): string | undefined {
+    void _actual;
+    void _diff;
     const key = table.schema ? `${table.schema}.${table.name}` : table.name;
     return `SQLite ALTER COLUMN is not supported; rebuild table ${key} to change column ${column.name}.`;
   }

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 };