uql-orm 0.25.1 → 0.26.0

package/dist/schema/schemaASTDiffer.js

@@ -8,423 +8,259 @@
  * - Schema synchronization
  */
 import { areTypesEqual, isBreakingTypeChange } from './canonicalType.js';
+import { describeIndexDifferences } from './indexDifferences.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
  * Default diff options.
  */
 const DEFAULT_OPTIONS = {
     compareIndexes: true,
+    indexFacets: new Set(),
     compareRelationships: true,
     ignoreCase: false,
     excludeTables: [],
 };
+function nameNormalizer(opts) {
+    return opts.ignoreCase ? (name) => name.toLowerCase() : (name) => name;
+}
 /**
- * Compares two SchemaAST instances and produces a detailed diff.
+ * The only three ways two keyed collections can differ, which is the shape of every comparison here:
+ * tables, columns, indexes and relationships all key by name and then split the same way.
  */
-export class SchemaASTDiffer {
-    /**
-     * Compare two schemas and return the differences.
-     *
-     * @param source - The "expected" or "desired" schema (e.g., from entities)
-     * @param target - The "actual" or "current" schema (e.g., from database)
-     * @param options - Diff options
-     * @returns Detailed diff result
-     */
-    diff(source, target, options = {}) {
-        const opts = { ...DEFAULT_OPTIONS, ...options };
-        const normalizeName = opts.ignoreCase ? (n) => n.toLowerCase() : (n) => n;
-        const tablesToCreate = [];
-        const tablesToDrop = [];
-        const tablesToAlter = [];
-        const columnDiffs = [];
-        const indexDiffs = [];
-        const relationshipDiffs = [];
-        // Build lookup maps
-        const sourceTableMap = new Map();
-        const targetTableMap = new Map();
-        for (const table of source.tables.values()) {
-            if (!opts.excludeTables.includes(table.name)) {
-                sourceTableMap.set(normalizeName(table.name), table);
-            }
-        }
-        for (const table of target.tables.values()) {
-            if (!opts.excludeTables.includes(table.name)) {
-                targetTableMap.set(normalizeName(table.name), table);
-            }
-        }
-        // Find tables to create (in source but not target)
-        for (const [name, sourceTable] of sourceTableMap) {
-            if (!targetTableMap.has(name)) {
-                tablesToCreate.push(sourceTable);
-            }
-        }
-        // Find tables to drop (in target but not source)
-        for (const [name, targetTable] of targetTableMap) {
-            if (!sourceTableMap.has(name)) {
-                tablesToDrop.push(targetTable);
-            }
-        }
-        // Find tables that need alteration
-        for (const [name, sourceTable] of sourceTableMap) {
-            const targetTable = targetTableMap.get(name);
-            if (!targetTable)
-                continue;
-            const tableDiff = this.diffTable(sourceTable, targetTable, opts);
-            if (tableDiff) {
-                tablesToAlter.push(tableDiff);
-                // Collect column diffs
-                if (tableDiff.columnDiffs) {
-                    columnDiffs.push(...tableDiff.columnDiffs);
-                }
-                // Collect index diffs
-                if (tableDiff.indexDiffs) {
-                    indexDiffs.push(...tableDiff.indexDiffs);
-                }
-            }
-        }
-        // Compare relationships (global view, not just per-table)
-        if (opts.compareRelationships) {
-            const relDiffs = this.diffRelationships(source, target, opts);
-            relationshipDiffs.push(...relDiffs);
-        }
-        // Determine if there are any differences
-        const hasDifferences = tablesToCreate.length > 0 ||
-            tablesToDrop.length > 0 ||
-            tablesToAlter.length > 0 ||
-            relationshipDiffs.length > 0 ||
-            indexDiffs.length > 0;
-        // Determine if any changes are breaking
-        const hasBreakingChanges = tablesToDrop.length > 0 || columnDiffs.some((d) => d.isBreaking);
-        return {
-            tablesToCreate,
-            tablesToDrop,
-            tablesToAlter,
-            columnDiffs,
-            indexDiffs,
-            relationshipDiffs,
-            hasDifferences,
-            hasBreakingChanges,
-        };
-    }
-    /**
-     * Compare two tables and return the differences.
-     */
-    diffTable(source, target, opts) {
-        const normalizeName = opts.ignoreCase ? (n) => n.toLowerCase() : (n) => n;
-        const columnDiffs = this.diffTableColumns(source, target, normalizeName);
-        const indexDiffs = opts.compareIndexes ? this.diffTableIndexes(source, target, normalizeName) : [];
-        // If no differences, return undefined
-        if (columnDiffs.length === 0 && indexDiffs.length === 0) {
-            return undefined;
-        }
-        return {
-            name: source.name,
-            type: 'alter',
-            columnDiffs,
-            indexDiffs,
-        };
+function matchByKey(source, target, key) {
+    const sourceByKey = new Map([...source].map((item) => [key(item), item]));
+    const targetByKey = new Map([...target].map((item) => [key(item), item]));
+    return {
+        created: [...sourceByKey].filter(([at]) => !targetByKey.has(at)).map(([, item]) => item),
+        dropped: [...targetByKey].filter(([at]) => !sourceByKey.has(at)).map(([, item]) => item),
+        matched: [...sourceByKey].flatMap(([at, item]) => {
+            const counterpart = targetByKey.get(at);
+            return counterpart ? [[item, counterpart]] : [];
+        }),
+    };
+}
+/** How a relationship diff names the pair it is about, whichever way it differs. */
+function relationEnds(relation) {
+    return { name: relation.name, fromTable: relation.from.table.name, toTable: relation.to.table.name };
+}
+/**
+ * Compare two schemas and return the differences.
+ *
+ * @param source - The "expected" or "desired" schema (e.g., from entities)
+ * @param target - The "actual" or "current" schema (e.g., from database)
+ * @param options - Diff options
+ * @returns Detailed diff result
+ */
+export function diffSchemas(source, target, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const normalizeName = nameNormalizer(opts);
+    const included = (tables) => [...tables].filter((table) => !opts.excludeTables.includes(table.name));
+    const { created: tablesToCreate, dropped: tablesToDrop, matched, } = matchByKey(included(source.tables.values()), included(target.tables.values()), (table) => normalizeName(table.name));
+    const tablesToAlter = matched
+        .map(([sourceTable, targetTable]) => diffTable(sourceTable, targetTable, opts))
+        .filter((tableDiff) => tableDiff !== undefined);
+    const columnDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.columnDiffs ?? []);
+    const indexDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.indexDiffs ?? []);
+    // Relationships span tables, so they are compared over the whole schema rather than per table.
+    const relationshipDiffs = opts.compareRelationships ? diffRelationships(source, target, opts) : [];
+    const hasDifferences = tablesToCreate.length > 0 ||
+        tablesToDrop.length > 0 ||
+        tablesToAlter.length > 0 ||
+        relationshipDiffs.length > 0 ||
+        indexDiffs.length > 0;
+    const hasBreakingChanges = tablesToDrop.length > 0 || columnDiffs.some((d) => d.isBreaking);
+    return {
+        tablesToCreate,
+        tablesToDrop,
+        tablesToAlter,
+        columnDiffs,
+        indexDiffs,
+        relationshipDiffs,
+        hasDifferences,
+        hasBreakingChanges,
+    };
+}
+/**
+ * Compare two tables and return the differences.
+ */
+function diffTable(source, target, opts) {
+    const columnDiffs = diffTableColumns(source, target, opts);
+    const indexDiffs = opts.compareIndexes ? diffTableIndexes(source, target, opts) : [];
+    if (columnDiffs.length === 0 && indexDiffs.length === 0) {
+        return undefined;
     }
-    /**
-     * Compare columns between two tables.
-     */
-    diffTableColumns(source, target, normalizeName) {
-        const columnDiffs = [];
-        // Build column maps
-        const sourceColMap = new Map();
-        const targetColMap = new Map();
-        for (const col of source.columns.values()) {
-            sourceColMap.set(normalizeName(col.name), col);
-        }
-        for (const col of target.columns.values()) {
-            targetColMap.set(normalizeName(col.name), col);
-        }
-        // Columns to add (in source but not target)
-        for (const [name, sourceCol] of sourceColMap) {
-            if (!targetColMap.has(name)) {
-                columnDiffs.push({
-                    table: source.name,
-                    column: sourceCol.name,
-                    type: 'add',
-                    expected: sourceCol,
-                    description: `Add column "${sourceCol.name}"`,
-                });
-            }
-        }
-        // Columns to drop (in target but not source)
-        for (const [name, targetCol] of targetColMap) {
-            if (!sourceColMap.has(name)) {
-                columnDiffs.push({
-                    table: target.name,
-                    column: targetCol.name,
-                    type: 'drop',
-                    actual: targetCol,
-                    isBreaking: true,
-                    description: `Drop column "${targetCol.name}"`,
-                });
-            }
-        }
-        // Columns that might need alteration
-        for (const [name, sourceCol] of sourceColMap) {
-            const targetCol = targetColMap.get(name);
-            if (!targetCol)
-                continue;
-            const colDiff = this.diffColumn(source.name, sourceCol, targetCol);
-            if (colDiff) {
-                columnDiffs.push(colDiff);
-            }
-        }
-        return columnDiffs;
+    return { name: source.name, type: 'alter', columnDiffs, indexDiffs };
+}
+/**
+ * Compare columns between two tables.
+ */
+function diffTableColumns(source, target, opts) {
+    const normalizeName = nameNormalizer(opts);
+    const { created, dropped, matched } = matchByKey(source.columns.values(), target.columns.values(), (column) => normalizeName(column.name));
+    return [
+        ...created.map((column) => ({
+            table: source.name,
+            column: column.name,
+            type: 'add',
+            expected: column,
+            description: `Add column "${column.name}"`,
+        })),
+        ...dropped.map((column) => ({
+            table: target.name,
+            column: column.name,
+            type: 'drop',
+            actual: column,
+            isBreaking: true,
+            description: `Drop column "${column.name}"`,
+        })),
+        ...matched
+            .map(([sourceColumn, targetColumn]) => diffColumn(source.name, sourceColumn, targetColumn))
+            .filter((diff) => diff !== undefined),
+    ];
+}
+/**
+ * Compare indexes between two tables.
+ */
+function diffTableIndexes(source, target, opts) {
+    const normalizeName = nameNormalizer(opts);
+    const { created, dropped, matched } = matchByKey(source.indexes, target.indexes, (index) => normalizeName(index.name));
+    return [
+        ...created.map((index) => ({ name: index.name, table: source.name, type: 'create', expected: index })),
+        ...dropped.map((index) => ({ name: index.name, table: target.name, type: 'drop', actual: index })),
+        ...matched
+            .map(([sourceIndex, targetIndex]) => diffIndex(source.name, sourceIndex, targetIndex, opts.indexFacets))
+            .filter((diff) => diff !== undefined),
+    ];
+}
+/**
+ * Compare two columns and return the difference.
+ */
+function diffColumn(tableName, source, target) {
+    const differences = [];
+    // Compare types
+    if (!areTypesEqual(source.type, target.type)) {
+        differences.push(`type: ${formatType(source.type)} → ${formatType(target.type)}`);
     }
-    /**
-     * Compare indexes between two tables.
-     */
-    diffTableIndexes(source, target, normalizeName) {
-        const indexDiffs = [];
-        const sourceIndexMap = new Map();
-        const targetIndexMap = new Map();
-        for (const idx of source.indexes) {
-            sourceIndexMap.set(normalizeName(idx.name), idx);
-        }
-        for (const idx of target.indexes) {
-            targetIndexMap.set(normalizeName(idx.name), idx);
-        }
-        // Indexes to create
-        for (const [, sourceIdx] of sourceIndexMap) {
-            const normalizedName = normalizeName(sourceIdx.name);
-            if (!targetIndexMap.has(normalizedName)) {
-                indexDiffs.push({
-                    name: sourceIdx.name,
-                    table: source.name,
-                    type: 'create',
-                    expected: sourceIdx,
-                });
-            }
-        }
-        // Indexes to drop
-        for (const [, targetIdx] of targetIndexMap) {
-            const normalizedName = normalizeName(targetIdx.name);
-            if (!sourceIndexMap.has(normalizedName)) {
-                indexDiffs.push({
-                    name: targetIdx.name,
-                    table: target.name,
-                    type: 'drop',
-                    actual: targetIdx,
-                });
-            }
-        }
-        // Indexes that might differ
-        for (const [name, sourceIdx] of sourceIndexMap) {
-            const targetIdx = targetIndexMap.get(name);
-            if (!targetIdx)
-                continue;
-            const idxDiff = this.diffIndex(source.name, sourceIdx, targetIdx);
-            if (idxDiff) {
-                indexDiffs.push(idxDiff);
-            }
-        }
-        return indexDiffs;
+    // Compare nullability
+    if (source.nullable !== target.nullable) {
+        differences.push(`nullable: ${target.nullable} → ${source.nullable}`);
     }
-    /**
-     * Compare two columns and return the difference.
-     */
-    diffColumn(tableName, source, target) {
-        const differences = [];
-        // Compare types
-        if (!areTypesEqual(source.type, target.type)) {
-            differences.push(`type: ${this.formatType(source.type)} → ${this.formatType(target.type)}`);
-        }
-        // Compare nullability
-        if (source.nullable !== target.nullable) {
-            differences.push(`nullable: ${target.nullable} → ${source.nullable}`);
-        }
-        // Compare unique constraint
-        if (source.isUnique !== target.isUnique) {
-            differences.push(`unique: ${target.isUnique} → ${source.isUnique}`);
-        }
-        // Compare auto-increment
-        if (source.isAutoIncrement !== target.isAutoIncrement) {
-            differences.push(`autoIncrement: ${target.isAutoIncrement} → ${source.isAutoIncrement}`);
-        }
-        // Compare default values (if both defined)
-        if (this.normalizeDefault(source.defaultValue) !== this.normalizeDefault(target.defaultValue)) {
-            differences.push(`default: ${target.defaultValue ?? 'NULL'} → ${source.defaultValue ?? 'NULL'}`);
-        }
-        if (differences.length === 0) {
-            return undefined;
-        }
-        return {
-            table: tableName,
-            column: source.name,
-            type: 'alter',
-            expected: source,
-            actual: target,
-            isBreaking: isBreakingTypeChange(target.type, source.type),
-            description: differences.join(', '),
-        };
+    // Compare unique constraint
+    if (source.isUnique !== target.isUnique) {
+        differences.push(`unique: ${target.isUnique} → ${source.isUnique}`);
     }
-    /**
-     * Compare two indexes and return the difference.
-     */
-    diffIndex(tableName, source, target) {
-        // Compare columns
-        const sourceColNames = source.columns.map((c) => c.name).join(',');
-        const targetColNames = target.columns.map((c) => c.name).join(',');
-        if (sourceColNames !== targetColNames) {
-            return {
-                name: source.name,
-                table: tableName,
-                type: 'alter',
-                expected: source,
-                actual: target,
-            };
-        }
-        // Compare uniqueness
-        if (source.unique !== target.unique) {
-            return {
-                name: source.name,
-                table: tableName,
-                type: 'alter',
-                expected: source,
-                actual: target,
-            };
-        }
-        // Compare index type
-        if (source.type !== target.type) {
-            return {
-                name: source.name,
-                table: tableName,
-                type: 'alter',
-                expected: source,
-                actual: target,
-            };
-        }
-        return undefined;
+    // Compare auto-increment
+    if (source.isAutoIncrement !== target.isAutoIncrement) {
+        differences.push(`autoIncrement: ${target.isAutoIncrement} → ${source.isAutoIncrement}`);
     }
-    /**
-     * Compare relationships at the schema level.
-     */
-    diffRelationships(source, target, opts) {
-        const diffs = [];
-        const normalizeName = opts.ignoreCase ? (n) => n.toLowerCase() : (n) => n;
-        // Build relationship maps by a normalized key
-        const sourceRelMap = new Map();
-        const targetRelMap = new Map();
-        for (const rel of source.relationships) {
-            const key = this.getRelationshipKey(rel, normalizeName);
-            sourceRelMap.set(key, rel);
-        }
-        for (const rel of target.relationships) {
-            const key = this.getRelationshipKey(rel, normalizeName);
-            targetRelMap.set(key, rel);
-        }
-        // Relationships to create
-        for (const [key, sourceRel] of sourceRelMap) {
-            if (!targetRelMap.has(key)) {
-                diffs.push({
-                    name: sourceRel.name,
-                    fromTable: sourceRel.from.table.name,
-                    toTable: sourceRel.to.table.name,
-                    type: 'create',
-                    expected: sourceRel,
-                });
-            }
-        }
-        // Relationships to drop
-        for (const [key, targetRel] of targetRelMap) {
-            if (!sourceRelMap.has(key)) {
-                diffs.push({
-                    name: targetRel.name,
-                    fromTable: targetRel.from.table.name,
-                    toTable: targetRel.to.table.name,
-                    type: 'drop',
-                    actual: targetRel,
-                });
-            }
-        }
-        // Relationships that differ
-        for (const [key, sourceRel] of sourceRelMap) {
-            const targetRel = targetRelMap.get(key);
-            if (!targetRel)
-                continue;
-            const relDiff = this.diffRelationship(sourceRel, targetRel);
-            if (relDiff) {
-                diffs.push(relDiff);
-            }
-        }
-        return diffs;
+    // Compare default values (if both defined)
+    if (normalizeDefault(source.defaultValue) !== normalizeDefault(target.defaultValue)) {
+        differences.push(`default: ${target.defaultValue ?? 'NULL'} → ${source.defaultValue ?? 'NULL'}`);
     }
-    /**
-     * Compare two relationships.
-     */
-    diffRelationship(source, target) {
-        // Compare on delete/update actions (normalizing defaults)
-        const sDelete = source.onDelete ?? DEFAULT_FOREIGN_KEY_ACTION;
-        const tDelete = target.onDelete ?? DEFAULT_FOREIGN_KEY_ACTION;
-        const sUpdate = source.onUpdate ?? DEFAULT_FOREIGN_KEY_ACTION;
-        const tUpdate = target.onUpdate ?? DEFAULT_FOREIGN_KEY_ACTION;
-        if (sDelete !== tDelete || sUpdate !== tUpdate) {
-            return {
-                name: source.name,
-                fromTable: source.from.table.name,
-                toTable: source.to.table.name,
-                type: 'alter',
-                expected: source,
-                actual: target,
-            };
-        }
+    if (differences.length === 0) {
         return undefined;
     }
-    /**
-     * Generate a unique key for a relationship based on its structure.
-     */
-    getRelationshipKey(rel, normalizeName) {
-        const fromCols = rel.from.columns
-            .map((c) => c.name)
-            .sort()
-            .join(',');
-        const toCols = rel.to.columns
-            .map((c) => c.name)
-            .sort()
-            .join(',');
-        return `${normalizeName(rel.from.table.name)}.${fromCols}->${normalizeName(rel.to.table.name)}.${toCols}`;
+    return {
+        table: tableName,
+        column: source.name,
+        type: 'alter',
+        expected: source,
+        actual: target,
+        isBreaking: isBreakingTypeChange(target.type, source.type),
+        description: differences.join(', '),
+    };
+}
+/**
+ * Compare two indexes and return the difference.
+ */
+function diffIndex(tableName, source, target, facets) {
+    const differences = describeIndexDifferences(source, target, facets);
+    if (differences.length === 0) {
+        return undefined;
     }
-    /**
-     * Format a canonical type for display.
-     */
-    formatType(type) {
-        let result = type.category;
-        if (type.size)
-            result += `(${type.size})`;
-        if (type.length)
-            result += `(${type.length})`;
-        if (type.precision) {
-            result += type.scale !== undefined ? `(${type.precision},${type.scale})` : `(${type.precision})`;
-        }
-        if (type.unsigned)
-            result += ' unsigned';
-        return result;
+    return {
+        name: source.name,
+        table: tableName,
+        type: 'alter',
+        expected: source,
+        actual: target,
+        description: differences.join(', '),
+    };
+}
+/**
+ * Compare relationships at the schema level.
+ */
+function diffRelationships(source, target, opts) {
+    const normalizeName = nameNormalizer(opts);
+    const { created, dropped, matched } = matchByKey(source.relationships, target.relationships, (relation) => getRelationshipKey(relation, normalizeName));
+    return [
+        ...created.map((relation) => ({
+            ...relationEnds(relation),
+            type: 'create',
+            expected: relation,
+        })),
+        ...dropped.map((relation) => ({ ...relationEnds(relation), type: 'drop', actual: relation })),
+        ...matched
+            .map(([sourceRelation, targetRelation]) => diffRelationship(sourceRelation, targetRelation))
+            .filter((diff) => diff !== undefined),
+    ];
+}
+/**
+ * Compare two relationships.
+ */
+function diffRelationship(source, target) {
+    // Compare on delete/update actions (normalizing defaults)
+    const sDelete = source.onDelete ?? DEFAULT_FOREIGN_KEY_ACTION;
+    const tDelete = target.onDelete ?? DEFAULT_FOREIGN_KEY_ACTION;
+    const sUpdate = source.onUpdate ?? DEFAULT_FOREIGN_KEY_ACTION;
+    const tUpdate = target.onUpdate ?? DEFAULT_FOREIGN_KEY_ACTION;
+    if (sDelete !== tDelete || sUpdate !== tUpdate) {
+        return { ...relationEnds(source), type: 'alter', expected: source, actual: target };
     }
-    /**
-     * Normalize default values for comparison.
-     */
-    normalizeDefault(value) {
-        if (value === undefined || value === null)
-            return '';
-        if (typeof value === 'string') {
-            // Normalize function calls
-            const upper = value.toUpperCase();
-            if (upper.includes('NOW()') || upper.includes('CURRENT_TIMESTAMP')) {
-                return 'CURRENT_TIMESTAMP';
-            }
-        }
-        return String(value);
+    return undefined;
+}
+/**
+ * Generate a unique key for a relationship based on its structure.
+ */
+function getRelationshipKey(rel, normalizeName) {
+    const fromCols = rel.from.columns
+        .map((c) => c.name)
+        .sort()
+        .join(',');
+    const toCols = rel.to.columns
+        .map((c) => c.name)
+        .sort()
+        .join(',');
+    return `${normalizeName(rel.from.table.name)}.${fromCols}->${normalizeName(rel.to.table.name)}.${toCols}`;
+}
+/**
+ * Format a canonical type for display.
+ */
+function formatType(type) {
+    let result = type.category;
+    if (type.size)
+        result += `(${type.size})`;
+    if (type.length)
+        result += `(${type.length})`;
+    if (type.precision) {
+        result += type.scale !== undefined ? `(${type.precision},${type.scale})` : `(${type.precision})`;
     }
+    if (type.unsigned)
+        result += ' unsigned';
+    return result;
 }
 /**
- * Create a differ and run a comparison.
- * Convenience function for one-off comparisons.
+ * Normalize default values for comparison.
  */
-export function diffSchemas(source, target, options) {
-    const differ = new SchemaASTDiffer();
-    return differ.diff(source, target, options);
+function normalizeDefault(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'string') {
+        // Normalize function calls
+        const upper = value.toUpperCase();
+        if (upper.includes('NOW()') || upper.includes('CURRENT_TIMESTAMP')) {
+            return 'CURRENT_TIMESTAMP';
+        }
+    }
+    return String(value);
 }