uql-orm 0.25.1 → 0.26.1

package/dist/migrate/drift/driftDetector.js

@@ -5,261 +5,252 @@
  * actual database schema.
  */
 import { canonicalToSql } from '../../schema/canonicalType.js';
-import { SchemaASTDiffer } from '../../schema/schemaASTDiffer.js';
+import { diffSchemas } from '../../schema/schemaASTDiffer.js';
+function resolveOptions(options) {
+    return {
+        checkTypes: options.checkTypes ?? true,
+        checkNullable: options.checkNullable ?? true,
+        checkIndexes: options.checkIndexes ?? true,
+        indexFacets: options.indexFacets ?? new Set(),
+        checkForeignKeys: options.checkForeignKeys ?? true,
+        checkDefaults: options.checkDefaults ?? false,
+        excludeTables: options.excludeTables ?? [],
+        dialect: options.dialect,
+    };
+}
+/**
+ * Compare an expected schema (from entities) with an actual one (from the database) and report every
+ * way they have drifted apart.
+ */
+export function detectDrift(expectedAST, actualAST, options = {}) {
+    const opts = resolveOptions(options);
+    const diff = diffSchemas(expectedAST, actualAST, {
+        compareIndexes: opts.checkIndexes,
+        indexFacets: opts.indexFacets,
+        compareRelationships: opts.checkForeignKeys,
+        excludeTables: opts.excludeTables,
+    });
+    const drifts = [
+        ...detectTableDrifts(diff),
+        ...detectColumnDrifts(diff, opts),
+        ...detectIndexDrifts(diff),
+        ...detectRelationshipDrifts(diff),
+    ];
+    return {
+        status: calculateStatus(drifts),
+        drifts,
+        summary: createSummary(drifts),
+        generatedAt: new Date(),
+    };
+}
 /**
- * Detects drift between expected and actual database schemas.
+ * Detect table-level drifts (missing/unexpected tables).
  */
-export class DriftDetector {
-    expectedAST;
-    actualAST;
-    options;
-    constructor(expectedAST, actualAST, options = {}) {
-        this.expectedAST = expectedAST;
-        this.actualAST = actualAST;
-        this.options = {
-            checkTypes: options.checkTypes ?? true,
-            checkNullable: options.checkNullable ?? true,
-            checkIndexes: options.checkIndexes ?? true,
-            checkForeignKeys: options.checkForeignKeys ?? true,
-            checkDefaults: options.checkDefaults ?? false,
-            excludeTables: options.excludeTables ?? [],
-            dialect: options.dialect,
-        };
+function detectTableDrifts(diff) {
+    const drifts = [];
+    for (const table of diff.tablesToCreate) {
+        drifts.push({
+            type: 'missing_table',
+            severity: 'critical',
+            table: table.name,
+            details: `Entity "${table.name}" exists but table not in database`,
+            suggestion: 'Run migrations to create table',
+        });
     }
-    /**
-     * Detect all schema drift.
-     */
-    detect() {
-        const differ = new SchemaASTDiffer();
-        const diff = differ.diff(this.expectedAST, this.actualAST, {
-            compareIndexes: this.options.checkIndexes,
-            compareRelationships: this.options.checkForeignKeys,
-            excludeTables: this.options.excludeTables,
+    for (const table of diff.tablesToDrop) {
+        drifts.push({
+            type: 'unexpected_table',
+            severity: 'warning',
+            table: table.name,
+            details: `Table "${table.name}" exists in database but no matching entity`,
+            suggestion: 'Create entity or drop table',
         });
-        const drifts = [
-            ...this.detectTableDrifts(diff),
-            ...this.detectColumnDrifts(diff),
-            ...this.detectIndexDrifts(diff),
-            ...this.detectRelationshipDrifts(diff),
-        ];
-        return {
-            status: this.calculateStatus(drifts),
-            drifts,
-            summary: this.createSummary(drifts),
-            generatedAt: new Date(),
-        };
     }
-    /**
-     * Detect table-level drifts (missing/unexpected tables).
-     */
-    detectTableDrifts(diff) {
-        const drifts = [];
-        for (const table of diff.tablesToCreate) {
+    return drifts;
+}
+/**
+ * Detect column-level drifts.
+ */
+function detectColumnDrifts(diff, opts) {
+    const drifts = [];
+    for (const colDiff of diff.columnDiffs) {
+        if (colDiff.type === 'add') {
             drifts.push({
-                type: 'missing_table',
+                type: 'missing_column',
                 severity: 'critical',
-                table: table.name,
-                details: `Entity "${table.name}" exists but table not in database`,
-                suggestion: 'Run migrations to create table',
+                table: colDiff.table,
+                column: colDiff.column,
+                details: `Column "${colDiff.column}" expected but not found in database`,
+                suggestion: 'Run migration to add column',
             });
         }
-        for (const table of diff.tablesToDrop) {
+        else if (colDiff.type === 'drop') {
             drifts.push({
-                type: 'unexpected_table',
+                type: 'unexpected_column',
                 severity: 'warning',
-                table: table.name,
-                details: `Table "${table.name}" exists in database but no matching entity`,
-                suggestion: 'Create entity or drop table',
+                table: colDiff.table,
+                column: colDiff.column,
+                details: `Column "${colDiff.column}" exists in database but not in entity`,
+                suggestion: 'Add to entity or create migration to drop',
             });
         }
-        return drifts;
-    }
-    /**
-     * Detect column-level drifts.
-     */
-    detectColumnDrifts(diff) {
-        const drifts = [];
-        for (const colDiff of diff.columnDiffs) {
-            if (colDiff.type === 'add') {
-                drifts.push({
-                    type: 'missing_column',
-                    severity: 'critical',
-                    table: colDiff.table,
-                    column: colDiff.column,
-                    details: `Column "${colDiff.column}" expected but not found in database`,
-                    suggestion: 'Run migration to add column',
-                });
-            }
-            else if (colDiff.type === 'drop') {
-                drifts.push({
-                    type: 'unexpected_column',
-                    severity: 'warning',
-                    table: colDiff.table,
-                    column: colDiff.column,
-                    details: `Column "${colDiff.column}" exists in database but not in entity`,
-                    suggestion: 'Add to entity or create migration to drop',
-                });
-            }
-            else if (colDiff.type === 'alter') {
-                this.addAlterColumnDrifts(colDiff, drifts);
-            }
+        else if (colDiff.type === 'alter') {
+            addAlterColumnDrifts(colDiff, drifts, opts);
         }
-        return drifts;
     }
-    /**
-     * Add drifts for column alterations (type/nullable mismatches).
-     */
-    addAlterColumnDrifts(colDiff, drifts) {
-        // Every check below compares the two sides, so there is nothing to report without both.
-        if (!colDiff.expected || !colDiff.actual) {
-            return;
-        }
-        if (this.options.checkTypes) {
-            const expectedType = this.formatType(colDiff.expected.type);
-            const actualType = this.formatType(colDiff.actual.type);
-            if (expectedType !== actualType) {
-                drifts.push({
-                    type: 'type_mismatch',
-                    severity: colDiff.isBreaking ? 'critical' : 'warning',
-                    table: colDiff.table,
-                    column: colDiff.column,
-                    expected: expectedType,
-                    actual: actualType,
-                    details: `Type mismatch for "${colDiff.column}": expected ${expectedType}, got ${actualType}`,
-                    suggestion: colDiff.isBreaking
-                        ? 'Data truncation risk! Create migration to fix.'
-                        : 'Create migration to align types',
-                });
-            }
+    return drifts;
+}
+/**
+ * Add drifts for column alterations (type/nullable mismatches).
+ */
+function addAlterColumnDrifts(colDiff, drifts, opts) {
+    // Every check below compares the two sides, so there is nothing to report without both.
+    if (!colDiff.expected || !colDiff.actual) {
+        return;
+    }
+    if (opts.checkTypes) {
+        const expectedType = formatType(colDiff.expected.type, opts.dialect);
+        const actualType = formatType(colDiff.actual.type, opts.dialect);
+        if (expectedType !== actualType) {
+            drifts.push({
+                type: 'type_mismatch',
+                severity: colDiff.isBreaking ? 'critical' : 'warning',
+                table: colDiff.table,
+                column: colDiff.column,
+                expected: expectedType,
+                actual: actualType,
+                details: `Type mismatch for "${colDiff.column}": expected ${expectedType}, got ${actualType}`,
+                suggestion: colDiff.isBreaking
+                    ? 'Data truncation risk! Create migration to fix.'
+                    : 'Create migration to align types',
+            });
         }
-        if (this.options.checkNullable && colDiff.expected.nullable !== colDiff.actual.nullable) {
+    }
+    if (opts.checkNullable && colDiff.expected.nullable !== colDiff.actual.nullable) {
+        drifts.push({
+            type: 'constraint_mismatch',
+            severity: 'warning',
+            table: colDiff.table,
+            column: colDiff.column,
+            expected: colDiff.expected.nullable ? 'NULLABLE' : 'NOT NULL',
+            actual: colDiff.actual.nullable ? 'NULLABLE' : 'NOT NULL',
+            details: `Nullable mismatch for "${colDiff.column}"`,
+            suggestion: 'Align nullable setting in entity or database',
+        });
+    }
+    if (opts.checkDefaults) {
+        const expected = String(colDiff.expected.defaultValue ?? 'NULL');
+        const actual = String(colDiff.actual.defaultValue ?? 'NULL');
+        if (expected !== actual) {
             drifts.push({
                 type: 'constraint_mismatch',
-                severity: 'warning',
+                severity: 'info',
                 table: colDiff.table,
                 column: colDiff.column,
-                expected: colDiff.expected.nullable ? 'NULLABLE' : 'NOT NULL',
-                actual: colDiff.actual.nullable ? 'NULLABLE' : 'NOT NULL',
-                details: `Nullable mismatch for "${colDiff.column}"`,
-                suggestion: 'Align nullable setting in entity or database',
+                expected,
+                actual,
+                details: `Default mismatch for "${colDiff.column}"`,
+                suggestion: 'Align the default in the entity or the database',
             });
         }
-        if (this.options.checkDefaults) {
-            const expected = String(colDiff.expected.defaultValue ?? 'NULL');
-            const actual = String(colDiff.actual.defaultValue ?? 'NULL');
-            if (expected !== actual) {
-                drifts.push({
-                    type: 'constraint_mismatch',
-                    severity: 'info',
-                    table: colDiff.table,
-                    column: colDiff.column,
-                    expected,
-                    actual,
-                    details: `Default mismatch for "${colDiff.column}"`,
-                    suggestion: 'Align the default in the entity or the database',
-                });
-            }
-        }
     }
-    /**
-     * Detect index drifts.
-     */
-    detectIndexDrifts(diff) {
-        const drifts = [];
-        for (const idxDiff of diff.indexDiffs) {
-            if (idxDiff.type === 'create') {
-                drifts.push({
-                    type: 'missing_index',
-                    severity: 'warning',
-                    table: idxDiff.table,
-                    index: idxDiff.name,
-                    details: `Index "${idxDiff.name}" expected but not found in database`,
-                    suggestion: 'Create index via migration',
-                });
-            }
-            else if (idxDiff.type === 'drop') {
-                drifts.push({
-                    type: 'unexpected_index',
-                    severity: 'info',
-                    table: idxDiff.table,
-                    index: idxDiff.name,
-                    details: `Index "${idxDiff.name}" exists in database but not defined in entity`,
-                    suggestion: 'Add @Field({ index }) or create migration to drop',
-                });
-            }
+}
+/**
+ * Detect index drifts.
+ */
+function detectIndexDrifts(diff) {
+    const drifts = [];
+    for (const idxDiff of diff.indexDiffs) {
+        if (idxDiff.type === 'create') {
+            drifts.push({
+                type: 'missing_index',
+                severity: 'warning',
+                table: idxDiff.table,
+                index: idxDiff.name,
+                details: `Index "${idxDiff.name}" expected but not found in database`,
+                suggestion: 'Create index via migration',
+            });
         }
-        return drifts;
-    }
-    /**
-     * Detect relationship/FK drifts.
-     */
-    detectRelationshipDrifts(diff) {
-        const drifts = [];
-        for (const relDiff of diff.relationshipDiffs) {
-            if (relDiff.type === 'create') {
-                drifts.push({
-                    type: 'missing_relationship',
-                    severity: 'warning',
-                    table: relDiff.fromTable,
-                    relationship: relDiff.name,
-                    details: `FK "${relDiff.name}" expected but not found in database`,
-                    suggestion: 'Add FK constraint or remove relation from entity',
-                });
-            }
-            else if (relDiff.type === 'drop') {
-                drifts.push({
-                    type: 'unexpected_relationship',
-                    severity: 'info',
-                    table: relDiff.fromTable,
-                    relationship: relDiff.name,
-                    details: `FK "${relDiff.name}" exists in database but not in entity`,
-                    suggestion: 'Add relation to entity or drop FK',
-                });
-            }
+        else if (idxDiff.type === 'drop') {
+            drifts.push({
+                type: 'unexpected_index',
+                severity: 'info',
+                table: idxDiff.table,
+                index: idxDiff.name,
+                details: `Index "${idxDiff.name}" exists in database but not defined in entity`,
+                suggestion: 'Add @Field({ index }) or create migration to drop',
+            });
+        }
+        else if (idxDiff.type === 'alter') {
+            // No `expected`/`actual` here: the CLI prints those by interpolation, where an `IndexNode`
+            // renders as `[object Object]`. What differs is already spelled out in `description`.
+            drifts.push({
+                type: 'index_mismatch',
+                severity: 'warning',
+                table: idxDiff.table,
+                index: idxDiff.name,
+                details: `Index "${idxDiff.name}" differs from the entity (${idxDiff.description})`,
+                suggestion: 'Drop and recreate the index via migration',
+            });
         }
-        return drifts;
-    }
-    /**
-     * Calculate overall status based on drifts.
-     */
-    calculateStatus(drifts) {
-        if (drifts.length === 0)
-            return 'in_sync';
-        const hasCritical = drifts.some((d) => d.severity === 'critical');
-        if (hasCritical)
-            return 'critical';
-        return 'drifted';
-    }
-    /**
-     * Create a summary of drifts by severity.
-     */
-    createSummary(drifts) {
-        return {
-            critical: drifts.filter((d) => d.severity === 'critical').length,
-            warning: drifts.filter((d) => d.severity === 'warning').length,
-            info: drifts.filter((d) => d.severity === 'info').length,
-        };
     }
-    /**
-     * Format type for display.
-     */
-    formatType(type) {
-        const dialect = this.options.dialect;
-        if (!type || !dialect)
-            return 'unknown';
-        return canonicalToSql(type, dialect);
+    return drifts;
+}
+/**
+ * Detect relationship/FK drifts.
+ */
+function detectRelationshipDrifts(diff) {
+    const drifts = [];
+    for (const relDiff of diff.relationshipDiffs) {
+        if (relDiff.type === 'create') {
+            drifts.push({
+                type: 'missing_relationship',
+                severity: 'warning',
+                table: relDiff.fromTable,
+                relationship: relDiff.name,
+                details: `FK "${relDiff.name}" expected but not found in database`,
+                suggestion: 'Add FK constraint or remove relation from entity',
+            });
+        }
+        else if (relDiff.type === 'drop') {
+            drifts.push({
+                type: 'unexpected_relationship',
+                severity: 'info',
+                table: relDiff.fromTable,
+                relationship: relDiff.name,
+                details: `FK "${relDiff.name}" exists in database but not in entity`,
+                suggestion: 'Add relation to entity or drop FK',
+            });
+        }
     }
+    return drifts;
+}
+/**
+ * Calculate overall status based on drifts.
+ */
+function calculateStatus(drifts) {
+    if (drifts.length === 0)
+        return 'in_sync';
+    const hasCritical = drifts.some((d) => d.severity === 'critical');
+    if (hasCritical)
+        return 'critical';
+    return 'drifted';
 }
 /**
- * Create a DriftDetector for comparing expected vs actual schemas.
+ * Create a summary of drifts by severity.
  */
-export function createDriftDetector(expectedAST, actualAST, options) {
-    return new DriftDetector(expectedAST, actualAST, options);
+function createSummary(drifts) {
+    return {
+        critical: drifts.filter((d) => d.severity === 'critical').length,
+        warning: drifts.filter((d) => d.severity === 'warning').length,
+        info: drifts.filter((d) => d.severity === 'info').length,
+    };
 }
 /**
- * Quick check for schema drift.
+ * Format type for display.
  */
-export function detectDrift(expectedAST, actualAST, options) {
-    const detector = new DriftDetector(expectedAST, actualAST, options);
-    return detector.detect();
+function formatType(type, dialect) {
+    if (!type || !dialect)
+        return 'unknown';
+    return canonicalToSql(type, dialect);
 }

package/dist/migrate/drift/index.d.ts

@@ -3,4 +3,4 @@
  *
  * Detects schema drift between expected and actual database schemas.
  */
-export { createDriftDetector, DriftDetector, type DriftDetectorOptions, detectDrift, } from './driftDetector.js';
+export { type DriftDetectorOptions, detectDrift, } from './driftDetector.js';

package/dist/migrate/drift/index.js

@@ -3,4 +3,4 @@
  *
  * Detects schema drift between expected and actual database schemas.
  */
-export { createDriftDetector, DriftDetector, detectDrift, } from './driftDetector.js';
+export { detectDrift, } from './driftDetector.js';

package/dist/migrate/generator/definitionToNode.d.ts

@@ -0,0 +1,9 @@
+import type { ColumnNode, TableNode } from '../../schema/types.js';
+import type { FullColumnDefinition, TableDefinition } from '../builder/types.js';
+/**
+ * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
+ * `createTable` and an entity reach `generateCreateTableFromNode` in the same shape. Free functions and
+ * not generator methods: nothing here consults the dialect.
+ */
+export declare function tableDefinitionToNode(def: TableDefinition): TableNode;
+export declare function fullColumnDefinitionToNode(col: FullColumnDefinition, tableName: string): ColumnNode;

package/dist/migrate/generator/definitionToNode.js

@@ -0,0 +1,79 @@
+/**
+ * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
+ * `createTable` and an entity reach `generateCreateTableFromNode` in the same shape. Free functions and
+ * not generator methods: nothing here consults the dialect.
+ */
+export function tableDefinitionToNode(def) {
+    const columns = new Map();
+    const pkNodes = [];
+    const table = {
+        name: def.name,
+        columns,
+        primaryKey: [], // placeholder
+        indexes: [],
+        schema: { tables: new Map(), relationships: [], indexes: [] },
+        incomingRelations: [],
+        outgoingRelations: [],
+        comment: def.comment,
+    };
+    for (const colDef of def.columns) {
+        const node = fullColumnDefinitionToNode(colDef, def.name);
+        node.table = table;
+        columns.set(node.name, node);
+        if (node.isPrimaryKey) {
+            pkNodes.push(node);
+        }
+    }
+    const finalPrimaryKey = def.primaryKey
+        ? def.primaryKey.map((name) => columns.get(name)).filter((c) => c !== undefined)
+        : pkNodes;
+    table.primaryKey = finalPrimaryKey;
+    for (const idxDef of def.indexes) {
+        table.indexes.push({ ...idxDef, table });
+    }
+    for (const fkDef of def.foreignKeys) {
+        const relNode = {
+            name: fkDef.name ?? `fk_${def.name}_${fkDef.columns.join('_')}`,
+            type: 'ManyToOne', // Builder default
+            from: {
+                table,
+                columns: fkDef.columns.map((name) => columns.get(name)).filter((c) => c !== undefined),
+            },
+            to: {
+                table: { name: fkDef.referencesTable },
+                columns: fkDef.referencesColumns.map((name) => ({ name })),
+            },
+            onDelete: fkDef.onDelete,
+            onUpdate: fkDef.onUpdate,
+        };
+        table.outgoingRelations.push(relNode);
+    }
+    return table;
+}
+export function fullColumnDefinitionToNode(col, tableName) {
+    return {
+        name: col.name,
+        type: col.type,
+        nullable: col.nullable,
+        defaultValue: col.defaultValue,
+        isPrimaryKey: col.primaryKey,
+        isAutoIncrement: col.autoIncrement,
+        isUnique: col.unique,
+        comment: col.comment,
+        table: { name: tableName },
+        referencedBy: [],
+        references: col.foreignKey
+            ? {
+                name: `fk_${tableName}_${col.name}`,
+                type: 'ManyToOne',
+                from: { table: { name: tableName }, columns: [] },
+                to: {
+                    table: { name: col.foreignKey.table },
+                    columns: col.foreignKey.columns.map((name) => ({ name })),
+                },
+                onDelete: col.foreignKey.onDelete,
+                onUpdate: col.foreignKey.onUpdate,
+            }
+            : undefined,
+    };
+}

package/dist/migrate/generator/indexNodeToSchema.js

@@ -1,4 +1,5 @@
 import { isVectorCategory } from '../../schema/canonicalType.js';
+import { indexColumns } from '../../schema/indexColumns.js';
 /**
  * An AST index as the generators and dialects want it. Spread rather than copied field by field:
  * rebuilding it by hand is how the partial-index `where` once vanished without a trace. The node-only
@@ -8,7 +9,8 @@ import { isVectorCategory } from '../../schema/canonicalType.js';
 export function indexNodeToSchema(index) {
     return {
         ...index,
-        columns: index.entries ?? index.columns.map((col) => ({ column: col.name })),
-        vectorType: index.columns.map((col) => col.type?.category).find(isVectorCategory),
+        vectorType: indexColumns(index)
+            .map((col) => col.type?.category)
+            .find(isVectorCategory),
     };
 }

package/dist/migrate/generator/mongoSchemaGenerator.js

@@ -42,7 +42,7 @@ export class MongoSchemaGenerator extends AbstractDialect {
                 const indexName = typeof field.index === 'string' ? field.index : `idx_${collectionName}_${columnName}`;
                 indexes.push({
                     name: indexName,
-                    columns: [{ column: columnName }],
+                    entries: [{ column: columnName }],
                     unique: !!field.unique,
                 });
             }
@@ -85,7 +85,7 @@ export class MongoSchemaGenerator extends AbstractDialect {
      */
     generateCreateIndex(tableName, index) {
         const key = {};
-        for (const entry of index.columns) {
+        for (const entry of index.entries) {
             if (entry.expression || entry.length !== undefined || entry.nulls || entry.opsClass) {
                 throw new TypeError(`mongodb does not support that index column option (index "${index.name}")`);
             }
@@ -146,7 +146,7 @@ export class MongoSchemaGenerator extends AbstractDialect {
                 if (!existingIndexes.has(indexName)) {
                     indexesToAdd.push({
                         name: indexName,
-                        columns: [{ column: columnName }],
+                        entries: [{ column: columnName }],
                         unique: !!field.unique,
                     });
                 }

package/dist/migrate/introspection/baseSqlIntrospector.d.ts

@@ -1,4 +1,5 @@
 import type { AbstractSqlDialect } from '../../dialect/index.js';
+import type { IndexFacet } from '../../schema/indexDifferences.js';
 import { SchemaAST } from '../../schema/schemaAST.js';
 import type { TableSchema } from '../../type/migration.js';
 /**
@@ -6,6 +7,8 @@ import type { TableSchema } from '../../type/migration.js';
  */
 export declare abstract class BaseSqlIntrospector {
     protected readonly dialect: AbstractSqlDialect;
+    /** Columns and uniqueness only; each introspector opts in to what its catalogue queries report. */
+    readonly indexFacets: ReadonlySet<IndexFacet>;
     constructor(dialect: AbstractSqlDialect);
     protected escapeId(identifier: string): string;
     /**