uql-orm 0.25.0 → 0.26.0

package/dist/schema/schemaASTBuilder.js

@@ -10,256 +10,231 @@ import { fieldOptionsToCanonical } from './canonicalType.js';
 import { SchemaAST } from './schemaAST.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
- * Builds SchemaAST instances from various sources.
+ * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).
+ *
+ * Three passes, because each needs the one before it to have finished for *every* entity: a relation
+ * resolves against a table another entity declares, and an index against the columns of its own.
  */
-export class SchemaASTBuilder {
-    namingStrategy;
-    defaultForeignKeyAction;
-    ast;
-    constructor(namingStrategy, defaultForeignKeyAction = DEFAULT_FOREIGN_KEY_ACTION) {
-        this.namingStrategy = namingStrategy;
-        this.defaultForeignKeyAction = defaultForeignKeyAction;
-        this.ast = new SchemaAST();
-    }
-    /**
-     * Reset the builder for a new schema.
-     */
-    reset() {
-        this.ast = new SchemaAST();
-        return this;
-    }
-    /**
-     * Get the built AST.
-     */
-    getAST() {
-        return this.ast;
-    }
-    /**
-     * Build AST from entity classes (decorated with @Entity, @Field, etc.)
-     */
-    fromEntities(entities, options = {}) {
-        this.reset();
-        const namingStrategy = options.namingStrategy ?? this.namingStrategy;
-        const resolveTableName = options.resolveTableName ?? ((e, m) => namingStrategy?.tableName(m.name ?? e.name) ?? m.name ?? e.name);
-        const resolveColumnName = options.resolveColumnName ?? ((k, f) => namingStrategy?.columnName(f.name ?? k) ?? f.name ?? k);
-        // First pass: create all tables and columns
-        for (const entity of entities) {
-            const meta = getMeta(entity);
-            this.addTableFromEntity(entity, meta, resolveTableName, resolveColumnName);
-        }
-        // Second pass: create relationships from relation decorators
-        for (const entity of entities) {
-            const meta = getMeta(entity);
-            this.addRelationshipsFromEntity(entity, meta, resolveTableName, resolveColumnName, options);
-        }
-        // Third pass: create indexes from field options
+export function buildSchemaAST(entities, options = {}) {
+    const { namingStrategy } = options;
+    const ctx = {
+        ast: new SchemaAST(),
+        resolveTableName: options.resolveTableName ?? ((e, m) => namingStrategy?.tableName(m.name ?? e.name) ?? m.name ?? e.name),
+        resolveColumnName: options.resolveColumnName ?? ((k, f) => namingStrategy?.columnName(f.name ?? k) ?? f.name ?? k),
+        defaultForeignKeyAction: options.defaultForeignKeyAction ?? DEFAULT_FOREIGN_KEY_ACTION,
+    };
+    for (const pass of [addTableFromEntity, addRelationshipsFromEntity, addIndexesFromEntity]) {
         for (const entity of entities) {
-            const meta = getMeta(entity);
-            this.addIndexesFromEntity(entity, meta, resolveTableName, resolveColumnName);
+            pass(ctx, entity, getMeta(entity));
         }
-        return this.ast;
     }
-    /**
-     * Resolve the canonical type for a field, inheriting from the referenced
-     * entity's primary key when the field is a foreign-key reference
-     * (`@Field({ references: () => SomeEntity })`) with no explicit type of its
-     * own.
-     *
-     * Without this, a field like `creatorId?: UUID` (a bare TypeScript alias for
-     * `string`, erased at runtime) falls back to the generic string inference in
-     * {@link fieldOptionsToCanonical} and gets typed as TEXT/VARCHAR - producing a
-     * foreign key column whose type doesn't match the UUID primary key it
-     * references, which Postgres (and most databases) reject outright.
-     *
-     * `field.typeFromReference` (set by `defineField`, see entity/metadata/definition.ts)
-     * is what distinguishes "no type was given" from "the decorator explicitly set
-     * a type" - including explicit constructor overrides like `type: BigInt`, which
-     * a value-based check (e.g. `typeof field.type === 'string'`) would miss since
-     * reflection also produces constructor values like `String`/`Number`.
-     * `columnType` remains the unambiguous, always-respected explicit override.
-     */
-    resolveColumnCanonicalType(field, seen = new Set()) {
-        const hasExplicitType = !!field.columnType || !field.typeFromReference;
-        if (!hasExplicitType && field.references && !seen.has(field.references)) {
-            seen.add(field.references);
-            const referencedMeta = getMeta(field.references());
-            const referencedIdField = referencedMeta.fields[referencedMeta.id];
-            if (referencedIdField) {
-                return this.resolveColumnCanonicalType(referencedIdField, seen);
-            }
+    return ctx.ast;
+}
+/**
+ * Resolve the canonical type for a field, inheriting from the referenced
+ * entity's primary key when the field is a foreign-key reference
+ * (`@Field({ references: () => SomeEntity })`) with no explicit type of its
+ * own.
+ *
+ * Without this, a field like `creatorId?: UUID` (a bare TypeScript alias for
+ * `string`, erased at runtime) falls back to the generic string inference in
+ * {@link fieldOptionsToCanonical} and gets typed as TEXT/VARCHAR - producing a
+ * foreign key column whose type doesn't match the UUID primary key it
+ * references, which Postgres (and most databases) reject outright.
+ *
+ * `field.typeFromReference` (set by `defineField`, see entity/metadata/definition.ts)
+ * is what distinguishes "no type was given" from "the decorator explicitly set
+ * a type" - including explicit constructor overrides like `type: BigInt`, which
+ * a value-based check (e.g. `typeof field.type === 'string'`) would miss since
+ * reflection also produces constructor values like `String`/`Number`.
+ * `columnType` remains the unambiguous, always-respected explicit override.
+ */
+function resolveColumnCanonicalType(field, seen = new Set()) {
+    const hasExplicitType = !!field.columnType || !field.typeFromReference;
+    if (!hasExplicitType && field.references && !seen.has(field.references)) {
+        seen.add(field.references);
+        const referencedMeta = getMeta(field.references());
+        const referencedIdField = referencedMeta.fields[referencedMeta.id];
+        if (referencedIdField) {
+            return resolveColumnCanonicalType(referencedIdField, seen);
         }
-        return fieldOptionsToCanonical(field, field.type);
     }
-    /**
-     * Add a table from entity metadata.
-     */
-    addTableFromEntity(entity, meta, resolveTableName, resolveColumnName) {
-        const tableName = resolveTableName(entity, meta);
-        const columns = new Map();
-        const primaryKey = [];
-        // Create placeholder table (will be fully initialized below)
-        const table = {
-            name: tableName,
-            columns,
-            primaryKey,
-            indexes: [],
-            schema: this.ast,
-            incomingRelations: [],
-            outgoingRelations: [],
+    return fieldOptionsToCanonical(field, field.type);
+}
+/**
+ * Add a table from entity metadata.
+ */
+function addTableFromEntity(ctx, entity, meta) {
+    const tableName = ctx.resolveTableName(entity, meta);
+    const columns = new Map();
+    const primaryKey = [];
+    // Create placeholder table (will be fully initialized below)
+    const table = {
+        name: tableName,
+        columns,
+        primaryKey,
+        indexes: [],
+        schema: ctx.ast,
+        incomingRelations: [],
+        outgoingRelations: [],
+    };
+    // Add columns from fields
+    const fields = meta.fields;
+    for (const key of Object.keys(fields)) {
+        const field = fields[key];
+        if (!field)
+            continue;
+        // Skip virtual fields
+        if (field.virtual)
+            continue;
+        const columnName = ctx.resolveColumnName(key, field);
+        const type = resolveColumnCanonicalType(field);
+        const isPrimaryKey = key === meta.id;
+        const column = {
+            name: columnName,
+            type,
+            // A primary key is NOT NULL in every engine, whatever the entity's property says: `id?: number`
+            // is optional because the database assigns it, not because the column accepts a null.
+            nullable: isPrimaryKey ? false : (field.nullable ?? true),
+            defaultValue: field.defaultValue,
+            isPrimaryKey,
+            isAutoIncrement: field.autoIncrement ?? (isPrimaryKey && type.category === 'integer'),
+            isUnique: field.unique ?? false,
+            comment: field.comment,
+            table,
+            referencedBy: [],
+            references: undefined,
         };
-        // Add columns from fields
-        const fields = meta.fields;
-        for (const key of Object.keys(fields)) {
-            const field = fields[key];
-            if (!field)
-                continue;
-            // Skip virtual fields
-            if (field.virtual)
-                continue;
-            const columnName = resolveColumnName(key, field);
-            const type = this.resolveColumnCanonicalType(field);
-            const column = {
-                name: columnName,
-                type,
-                nullable: field.nullable ?? true,
-                defaultValue: field.defaultValue,
-                isPrimaryKey: key === meta.id,
-                isAutoIncrement: field.autoIncrement ?? (key === meta.id && type.category === 'integer'),
-                isUnique: field.unique ?? false,
-                comment: field.comment,
-                table,
-                referencedBy: [],
-                references: undefined,
-            };
-            columns.set(columnName, column);
-            if (key === meta.id) {
-                primaryKey.push(column);
-            }
+        columns.set(columnName, column);
+        if (key === meta.id) {
+            primaryKey.push(column);
         }
-        this.ast.addTable(table);
     }
-    /**
-     * Add relationships from entity relation decorators.
-     */
-    addRelationshipsFromEntity(entity, meta, resolveTableName, resolveColumnName, options) {
-        const tableName = resolveTableName(entity, meta);
-        const table = this.ast.getTable(tableName);
-        if (!table)
-            return;
-        const relations = meta.relations;
-        for (const key of Object.keys(relations)) {
-            const relation = relations[key];
-            if (!relation)
+    ctx.ast.addTable(table);
+}
+/**
+ * Add relationships from entity relation decorators.
+ */
+function addRelationshipsFromEntity(ctx, entity, meta) {
+    const tableName = ctx.resolveTableName(entity, meta);
+    const table = ctx.ast.getTable(tableName);
+    if (!table)
+        return;
+    const relations = meta.relations;
+    for (const key of Object.keys(relations)) {
+        const relation = relations[key];
+        if (!relation)
+            continue;
+        const relatedEntity = relation.entity();
+        const relatedMeta = getMeta(relatedEntity);
+        const relatedTableName = ctx.resolveTableName(relatedEntity, relatedMeta);
+        const relatedTable = ctx.ast.getTable(relatedTableName);
+        if (!relatedTable)
+            continue;
+        // Only the owning side gets the FK. `mappedBy` marks the inverse side of a one-to-one, whose
+        // `references` describe how to join back (its own primary key against the owner's FK column) -
+        // reading those as a foreign key emitted a reversed constraint (`User(id) REFERENCES
+        // user_profile(creatorId)`), which SQLite rejects outright as a foreign key mismatch.
+        const ownsForeignKey = relation.cardinality === 'm1' || (relation.cardinality === '11' && !relation.mappedBy);
+        if (ownsForeignKey) {
+            const localPropName = relation.references[0].local;
+            const foreignPropName = relation.references[0].foreign;
+            const localField = meta.fields[localPropName];
+            if (!localField)
                 continue;
-            const relatedEntity = relation.entity();
-            const relatedMeta = getMeta(relatedEntity);
-            const relatedTableName = resolveTableName(relatedEntity, relatedMeta);
-            const relatedTable = this.ast.getTable(relatedTableName);
-            if (!relatedTable)
+            const localColName = ctx.resolveColumnName(localPropName, localField);
+            const foreignField = relatedMeta.fields[foreignPropName];
+            if (!foreignField)
                 continue;
-            // Only the owning side gets the FK. `mappedBy` marks the inverse side of a one-to-one, whose
-            // `references` describe how to join back (its own primary key against the owner's FK column) -
-            // reading those as a foreign key emitted a reversed constraint (`User(id) REFERENCES
-            // user_profile(creatorId)`), which SQLite rejects outright as a foreign key mismatch.
-            const ownsForeignKey = relation.cardinality === 'm1' || (relation.cardinality === '11' && !relation.mappedBy);
-            if (ownsForeignKey) {
-                const localPropName = relation.references[0].local;
-                const foreignPropName = relation.references[0].foreign;
-                const localField = meta.fields[localPropName];
-                if (!localField)
-                    continue;
-                const localColName = resolveColumnName(localPropName, localField);
-                const foreignField = relatedMeta.fields[foreignPropName];
-                if (!foreignField)
-                    continue;
-                const foreignColName = resolveColumnName(foreignPropName, foreignField);
-                const localColumn = table.columns.get(localColName);
-                const foreignColumn = relatedTable.columns.get(foreignColName);
-                if (localColumn && foreignColumn) {
-                    const relNode = {
-                        name: `fk_${tableName}_${localColName}`,
-                        type: relation.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
-                        from: { table, columns: [localColumn] },
-                        to: { table: relatedTable, columns: [foreignColumn] },
-                        // The relation's own action wins over the global default, so one relation can cascade in the
-                        // database while the rest stay on `NO ACTION`.
-                        onDelete: relation.onDelete ?? options.defaultForeignKeyAction ?? this.defaultForeignKeyAction,
-                        onUpdate: relation.onUpdate ?? options.defaultForeignKeyAction ?? this.defaultForeignKeyAction,
-                        confidence: 1.0,
-                        inferredFrom: 'entity_decorator',
-                    };
-                    this.ast.addRelationship(relNode);
-                }
+            const foreignColName = ctx.resolveColumnName(foreignPropName, foreignField);
+            const localColumn = table.columns.get(localColName);
+            const foreignColumn = relatedTable.columns.get(foreignColName);
+            if (localColumn && foreignColumn) {
+                const relNode = {
+                    name: `fk_${tableName}_${localColName}`,
+                    type: relation.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
+                    from: { table, columns: [localColumn] },
+                    to: { table: relatedTable, columns: [foreignColumn] },
+                    // Falls back to the FK column's own `onDelete`, which is what makes a bare `@Field({
+                    // references, onDelete })` work with no relation declared at all.
+                    onDelete: relation.onDelete ?? localField.onDelete ?? ctx.defaultForeignKeyAction,
+                    onUpdate: relation.onUpdate ?? ctx.defaultForeignKeyAction,
+                    confidence: 1.0,
+                    inferredFrom: 'entity_decorator',
+                };
+                ctx.ast.addRelationship(relNode);
             }
         }
     }
-    /**
-     * Add indexes from field options (`@Field({ index })`) and from `@Index([...])`, which have nothing
-     * in common beyond their target table.
-     */
-    addIndexesFromEntity(entity, meta, resolveTableName, resolveColumnName) {
-        const tableName = resolveTableName(entity, meta);
-        const table = this.ast.getTable(tableName);
-        if (!table)
-            return;
-        for (const key of Object.keys(meta.fields)) {
-            const field = meta.fields[key];
-            if (!field?.index)
-                continue;
-            const column = table.columns.get(resolveColumnName(key, field));
-            if (!column)
-                continue;
-            this.ast.addIndex({
-                name: typeof field.index === 'string' ? field.index : `idx_${tableName}_${column.name}`,
-                table,
-                columns: [column],
-                unique: field.unique ?? false,
-                source: 'entity',
-                syncStatus: 'entity_only',
-            });
-        }
-        for (const idxMeta of meta.indexes ?? []) {
-            this.addCompositeIndex(table, meta, idxMeta, resolveColumnName);
-        }
-    }
-    /**
-     * One `@Index([...])`. Its entries keep the authored form (expression, prefix length, order) with
-     * names resolved, so the generator renders exactly what was declared; `columns` is the resolvable
-     * subset, which is what diffing and introspection compare.
-     */
-    addCompositeIndex(table, meta, idxMeta, resolveColumnName) {
-        // An entry survives if it is an expression (nothing to resolve) or names a column that exists;
-        // an index left with none is dropped, the same as one naming only unknown columns always was.
-        const entries = idxMeta.columns
-            .map((entry) => {
-            if (entry.expression)
-                return entry;
-            const field = meta.fields[entry.column];
-            const column = field && resolveColumnName(entry.column, field);
-            return column && table.columns.has(column) ? { ...entry, column } : undefined;
-        })
-            .filter((entry) => entry !== undefined);
-        if (!entries.length)
-            return;
-        const columns = entries
-            .map((entry) => (entry.expression ? undefined : table.columns.get(entry.column)))
-            .filter((column) => column !== undefined);
-        const named = columns.length ? columns.map((column) => column.name) : entries.map((_, at) => `expr${at}`);
-        this.ast.addIndex({
-            name: idxMeta.name ?? `idx_${table.name}_${named.join('_')}`,
+}
+/**
+ * Add indexes from field options (`@Field({ index })`) and from `@Index([...])`, which have nothing
+ * in common beyond their target table.
+ */
+function addIndexesFromEntity(ctx, entity, meta) {
+    const tableName = ctx.resolveTableName(entity, meta);
+    const table = ctx.ast.getTable(tableName);
+    if (!table)
+        return;
+    for (const key of Object.keys(meta.fields)) {
+        const field = meta.fields[key];
+        if (!field?.index)
+            continue;
+        const column = table.columns.get(ctx.resolveColumnName(key, field));
+        if (!column)
+            continue;
+        ctx.ast.addIndex({
+            name: typeof field.index === 'string' ? field.index : `idx_${tableName}_${column.name}`,
             table,
-            columns,
-            entries,
-            include: idxMeta.include,
-            unique: idxMeta.unique ?? false,
-            type: idxMeta.type,
-            where: idxMeta.where,
-            distance: idxMeta.distance,
-            m: idxMeta.m,
-            efConstruction: idxMeta.efConstruction,
-            lists: idxMeta.lists,
+            entries: [{ column: column.name }],
+            unique: field.unique ?? false,
             source: 'entity',
             syncStatus: 'entity_only',
         });
     }
+    for (const idxMeta of meta.indexes ?? []) {
+        addCompositeIndex(ctx, table, meta, idxMeta);
+    }
+}
+/**
+ * One `@Index([...])`. Its entries keep the authored form (expression, prefix length, order) with
+ * names resolved, so the generator renders exactly what was declared; `columns` is the resolvable
+ * subset, which is what diffing and introspection compare.
+ */
+/** An `include` column is named like any other, so a naming strategy has to reach it too. */
+function resolveIncludeColumn(ctx, meta, column) {
+    const field = meta.fields[column];
+    return field ? ctx.resolveColumnName(column, field) : column;
+}
+function addCompositeIndex(ctx, table, meta, idxMeta) {
+    // An entry survives if it is an expression (nothing to resolve) or names a column that exists;
+    // an index left with none is dropped, the same as one naming only unknown columns always was.
+    const entries = idxMeta.columns
+        .map((entry) => {
+        if (entry.expression)
+            return entry;
+        const field = meta.fields[entry.column];
+        const column = field && ctx.resolveColumnName(entry.column, field);
+        return column && table.columns.has(column) ? { ...entry, column } : undefined;
+    })
+        .filter((entry) => entry !== undefined);
+    if (!entries.length)
+        return;
+    // An index over expressions alone has no column names to build a default name from.
+    const named = entries.map((entry, at) => (entry.expression ? `expr${at}` : entry.column));
+    ctx.ast.addIndex({
+        name: idxMeta.name ?? `idx_${table.name}_${named.join('_')}`,
+        table,
+        entries,
+        include: idxMeta.include?.map((column) => resolveIncludeColumn(ctx, meta, column)),
+        unique: idxMeta.unique ?? false,
+        type: idxMeta.type,
+        where: idxMeta.where,
+        distance: idxMeta.distance,
+        m: idxMeta.m,
+        efConstruction: idxMeta.efConstruction,
+        lists: idxMeta.lists,
+        source: 'entity',
+        syncStatus: 'entity_only',
+    });
 }

package/dist/schema/schemaASTDiffer.d.ts

@@ -7,6 +7,7 @@
  * - Drift detection (expected vs actual)
  * - Schema synchronization
  */
+import { type IndexFacet } from './indexDifferences.js';
 import type { SchemaAST } from './schemaAST.js';
 import type { SchemaDiffResult } from './types.js';
 /**
@@ -15,6 +16,8 @@ import type { SchemaDiffResult } from './types.js';
 export interface DiffOptions {
     /** Compare indexes */
     compareIndexes?: boolean;
+    /** What the target side can report about an index, normally an introspector's `indexFacets`. Anything left out is not compared. */
+    indexFacets?: ReadonlySet<IndexFacet>;
     /** Compare foreign keys/relationships */
     compareRelationships?: boolean;
     /** Ignore case differences in names */
@@ -23,61 +26,11 @@ export interface DiffOptions {
     excludeTables?: string[];
 }
 /**
- * Compares two SchemaAST instances and produces a detailed diff.
- */
-export declare 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: SchemaAST, target: SchemaAST, options?: DiffOptions): SchemaDiffResult;
-    /**
-     * Compare two tables and return the differences.
-     */
-    private diffTable;
-    /**
-     * Compare columns between two tables.
-     */
-    private diffTableColumns;
-    /**
-     * Compare indexes between two tables.
-     */
-    private diffTableIndexes;
-    /**
-     * Compare two columns and return the difference.
-     */
-    private diffColumn;
-    /**
-     * Compare two indexes and return the difference.
-     */
-    private diffIndex;
-    /**
-     * Compare relationships at the schema level.
-     */
-    private diffRelationships;
-    /**
-     * Compare two relationships.
-     */
-    private diffRelationship;
-    /**
-     * Generate a unique key for a relationship based on its structure.
-     */
-    private getRelationshipKey;
-    /**
-     * Format a canonical type for display.
-     */
-    private formatType;
-    /**
-     * Normalize default values for comparison.
-     */
-    private normalizeDefault;
-}
-/**
- * Create a differ and run a comparison.
- * Convenience function for one-off comparisons.
+ * 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 declare function diffSchemas(source: SchemaAST, target: SchemaAST, options?: DiffOptions): SchemaDiffResult;