uql-orm 0.25.0 → 0.26.0

package/dist/migrate/schemaGenerator.js

@@ -1,9 +1,10 @@
 import { AbstractSqlDialect } from '../dialect/index.js';
 import { getMeta } from '../entity/index.js';
 import { areTypesEqual, canonicalToSql, fieldOptionsToCanonical, isVectorCategory, sqlToCanonical, } from '../schema/canonicalType.js';
-import { SchemaASTBuilder } from '../schema/schemaASTBuilder.js';
+import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
 import { escapeSqlId, getKeys, isAutoIncrement } from '../util/index.js';
 import { formatDefaultValue } from './builder/expressions.js';
+import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
 /**
  * Unified SQL schema generator.
@@ -90,7 +91,7 @@ export class SqlSchemaGenerator {
      * resolves instead of being silently dropped.
      */
     orderedTables(entities, direction, only) {
-        const ast = new SchemaASTBuilder(this.dialect.namingStrategy).fromEntities(entities);
+        const ast = buildEntityAST(this, entities, this.defaultForeignKeyAction);
         const tables = direction === 'create' ? ast.getCreateOrder() : ast.getDropOrder();
         if (!only) {
             return tables;
@@ -331,7 +332,11 @@ export class SqlSchemaGenerator {
         for (const [name] of currentColumns) {
             columnsToDrop.push(name);
         }
-        if (columnsToAdd.length === 0 && columnsToAlter.length === 0 && columnsToDrop.length === 0) {
+        const indexesToAdd = this.missingIndexes(entity, currentTable);
+        if (columnsToAdd.length === 0 &&
+            columnsToAlter.length === 0 &&
+            columnsToDrop.length === 0 &&
+            indexesToAdd.length === 0) {
             return undefined;
         }
         return {
@@ -340,8 +345,32 @@ export class SqlSchemaGenerator {
             columnsToAdd: columnsToAdd.length > 0 ? columnsToAdd : undefined,
             columnsToAlter: columnsToAlter.length > 0 ? columnsToAlter : undefined,
             columnsToDrop: columnsToDrop.length > 0 ? columnsToDrop : undefined,
+            indexesToAdd: indexesToAdd.length > 0 ? indexesToAdd : undefined,
         };
     }
+    /**
+     * Indexes the entity declares that the table does not have, matched by name and built the same way
+     * `CREATE TABLE` builds them, so adding an `@Index` to an entity already in the database is picked
+     * up rather than waiting for the table to be created from scratch somewhere else.
+     *
+     * Only ever additive. An index the entity does not name is left alone: it may well have been
+     * created deliberately outside the ORM, and dropping it is a decision for a reviewed migration.
+     */
+    missingIndexes(entity, currentTable) {
+        const desired = buildEntityAST(this, [entity]).getTable(currentTable.name)?.indexes ?? [];
+        const present = new Set(currentTable.indexes.map((index) => index.name));
+        return desired
+            .filter((index) => !present.has(index.name) && !this.isInlineVectorIndex(index))
+            .map(indexNodeToSchema);
+    }
+    /**
+     * A vector index this dialect declares inside `CREATE TABLE` rather than as a statement of its own,
+     * which MariaDB is alone in doing. It has no `CREATE INDEX` form, so it can only ever be created
+     * with its table, never added to one.
+     */
+    isInlineVectorIndex(index) {
+        return this.features.inlineVectorIndex && index.type === 'vector';
+    }
     columnNodeToSchema(col) {
         return {
             name: col.name,
@@ -430,12 +459,11 @@ export class SqlSchemaGenerator {
     generateCreateTableFromNode(table, options = {}) {
         const columns = [];
         const constraints = [];
-        const isInlineVectorIdx = this.features.inlineVectorIndex;
-        const vectorIndexes = isInlineVectorIdx ? table.indexes.filter((idx) => idx.type === 'vector') : [];
-        const regularIndexes = isInlineVectorIdx ? table.indexes.filter((idx) => idx.type !== 'vector') : table.indexes;
+        const vectorIndexes = table.indexes.filter((index) => this.isInlineVectorIndex(index));
+        const regularIndexes = table.indexes.filter((index) => !this.isInlineVectorIndex(index));
         // MariaDB rejects a `VECTOR INDEX` whose column is nullable ("All parts of a VECTOR index must
         // be NOT NULL"), so being indexed decides it rather than the entity's own nullability.
-        const indexedVectorColumns = new Set(vectorIndexes.flatMap((idx) => idx.columns.map((col) => col.name)));
+        const indexedVectorColumns = new Set(vectorIndexes.flatMap((idx) => idx.entries.map((entry) => entry.column)));
         for (const col of table.columns.values()) {
             const colDef = this.generateColumnFromNode(indexedVectorColumns.has(col.name) ? { ...col, nullable: false } : col);
             columns.push(colDef);
@@ -503,7 +531,7 @@ export class SqlSchemaGenerator {
         return this.generateCreateIndex(index.table.name, indexNodeToSchema(index), options);
     }
     generateCreateTableFromDefinition(table, options = {}) {
-        const tableNode = this.tableDefinitionToNode(table);
+        const tableNode = tableDefinitionToNode(table);
         return this.generateCreateTableFromNode(tableNode, options);
     }
     generateRenameTableSql(oldName, newName) {
@@ -513,11 +541,11 @@ export class SqlSchemaGenerator {
         return `ALTER TABLE ${this.escapeId(oldName)} RENAME TO ${this.escapeId(newName)};`;
     }
     generateAddColumnSql(tableName, column) {
-        const colSql = this.generateColumnFromNode(this.fullColumnDefinitionToNode(column, tableName));
+        const colSql = this.generateColumnFromNode(fullColumnDefinitionToNode(column, tableName));
         return `ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${colSql};`;
     }
     generateAlterColumnSql(tableName, columnName, column) {
-        const node = this.fullColumnDefinitionToNode(column, tableName);
+        const node = fullColumnDefinitionToNode(column, tableName);
         return this.generateAlterColumnStatements(tableName, { ...this.columnNodeToSchema(node), name: columnName }, this.generateColumnFromNode(node)).join('\n');
     }
     generateDropColumnSql(tableName, columnName) {
@@ -542,88 +570,21 @@ export class SqlSchemaGenerator {
     generateDropForeignKeySql(tableName, constraintName) {
         return `ALTER TABLE ${this.escapeId(tableName)} ${this.dialect.dropForeignKeySyntax} ${this.escapeId(constraintName)};`;
     }
-    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 = this.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) {
-            const indexNode = {
-                ...idxDef,
-                table,
-                columns: idxDef.columns
-                    .map((entry) => (entry.expression ? undefined : columns.get(entry.column)))
-                    .filter((c) => c !== undefined),
-                entries: idxDef.columns,
-            };
-            table.indexes.push(indexNode);
-        }
-        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;
-    }
-    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,
-        };
-    }
+}
+/**
+ * The entities as an AST, named the way `generator` names things.
+ *
+ * Its resolvers rather than a naming strategy, because the two disagree: a strategy renames whatever
+ * it is handed, while a generator leaves an explicit `@Entity({ name })` alone. Build the AST the
+ * other way and the table is created under one name and compared under another, which reports every
+ * table of a project using a naming strategy as both missing and unexpected.
+ */
+export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
+    return buildSchemaAST(entities, {
+        resolveTableName: (entity, meta) => generator.resolveTableName(entity, meta),
+        resolveColumnName: (key, field) => generator.resolveColumnName(key, field),
+        defaultForeignKeyAction,
+    });
 }
 /**
  * Synchronous factory for SQL schema generators only.

package/dist/schema/index.d.ts

@@ -18,8 +18,8 @@ export { areTypesEqual, canonicalToColumnType, canonicalToSql, canonicalToTypeSc
  */
 export declare function introspectSchema(introspector: SchemaIntrospector): Promise<SchemaAST>;
 export { SchemaAST } from './schemaAST.js';
-export type { BuildFromEntitiesOptions } from './schemaASTBuilder.js';
-export { SchemaASTBuilder } from './schemaASTBuilder.js';
+export type { BuildSchemaASTOptions } from './schemaASTBuilder.js';
+export { buildSchemaAST } from './schemaASTBuilder.js';
 export type { DiffOptions } from './schemaASTDiffer.js';
-export { diffSchemas, SchemaASTDiffer } from './schemaASTDiffer.js';
+export { diffSchemas } from './schemaASTDiffer.js';
 export type { CanonicalType, ColumnDiff, ColumnNode, Drift, DriftReport, DriftSeverity, DriftStatus, DriftType, ForeignKeyAction, IndexDiff, IndexNode, IndexSource, IndexSyncStatus, IndexType, RelationshipDiff, RelationshipNode, RelationshipSource, RelationshipType, SchemaAST as ISchemaAST, SchemaDiffResult, SizeVariant, TableDiff, TableNode, TypeCategory, ValidationError, ValidationErrorType, } from './types.js';

package/dist/schema/index.js

@@ -21,6 +21,6 @@ export async function introspectSchema(introspector) {
 // SchemaAST class
 export { SchemaAST } from './schemaAST.js';
 // Builder
-export { SchemaASTBuilder } from './schemaASTBuilder.js';
+export { buildSchemaAST } from './schemaASTBuilder.js';
 // Differ
-export { diffSchemas, SchemaASTDiffer } from './schemaASTDiffer.js';
+export { diffSchemas } from './schemaASTDiffer.js';

package/dist/schema/indexColumns.d.ts

@@ -0,0 +1,10 @@
+import type { ColumnNode, IndexNode } from './types.js';
+/**
+ * The table columns an index resolves to, in order.
+ *
+ * Derived rather than stored: an index is defined by its entries, and a second field repeating them
+ * as columns is a second thing to keep in step. It went out of step - one introspector rebuilt the
+ * entries from the columns it had just built from the entries, and every fixture had to write both.
+ * An expression entry resolves to no column at all, which is why the two were never the same list.
+ */
+export declare function indexColumns(index: IndexNode): ColumnNode[];

package/dist/schema/indexColumns.js

@@ -0,0 +1,11 @@
+/**
+ * The table columns an index resolves to, in order.
+ *
+ * Derived rather than stored: an index is defined by its entries, and a second field repeating them
+ * as columns is a second thing to keep in step. It went out of step - one introspector rebuilt the
+ * entries from the columns it had just built from the entries, and every fixture had to write both.
+ * An expression entry resolves to no column at all, which is why the two were never the same list.
+ */
+export function indexColumns(index) {
+    return index.entries.flatMap((entry) => (entry.expression ? [] : (index.table.columns.get(entry.column) ?? [])));
+}

package/dist/schema/indexDifferences.d.ts

@@ -0,0 +1,22 @@
+import type { IndexNode } from './types.js';
+/**
+ * What an introspector can report about an index, and so all that diffing may compare. Anything it
+ * cannot report is skipped: the entity declares it, the database never mentions it, and no migration
+ * could ever make the two agree.
+ *
+ * Deliberately separate from the dialect's `IndexFeature`, which says what an engine can *emit* and
+ * rejects outright. The two look alike and are not: Postgres emits an expression index and reads one
+ * back, MySQL emits one it cannot describe afterwards.
+ */
+export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include';
+/**
+ * Everything an index differs by, named, or nothing when the two match.
+ *
+ * Only what both sides can state *structurally* is compared. SQL text is not: a database reprints an
+ * expression and a predicate from its parse tree, so `status IN ('a','b')` reads back as
+ * `status = ANY (ARRAY['a'::text, 'b'::text])`, `LIKE` as `~~`, and a date literal with its time zone
+ * spelled out. Folding that back needs a SQL parser, and every near-miss reports drift that no
+ * migration can settle. So a partial index's predicate is never compared, and an index over an
+ * expression has its entries left alone while the rest of it still compares.
+ */
+export declare function describeIndexDifferences(source: IndexNode, target: IndexNode, facets: ReadonlySet<IndexFacet>): string[];

package/dist/schema/indexDifferences.js

@@ -0,0 +1,49 @@
+/**
+ * Everything an index differs by, named, or nothing when the two match.
+ *
+ * Only what both sides can state *structurally* is compared. SQL text is not: a database reprints an
+ * expression and a predicate from its parse tree, so `status IN ('a','b')` reads back as
+ * `status = ANY (ARRAY['a'::text, 'b'::text])`, `LIKE` as `~~`, and a date literal with its time zone
+ * spelled out. Folding that back needs a SQL parser, and every near-miss reports drift that no
+ * migration can settle. So a partial index's predicate is never compared, and an index over an
+ * expression has its entries left alone while the rest of it still compares.
+ */
+export function describeIndexDifferences(source, target, facets) {
+    const differences = [];
+    const comparableEntries = ![...source.entries, ...target.entries].some((entry) => entry.expression);
+    if (comparableEntries) {
+        const [sourceColumns, targetColumns] = [source.entries, target.entries].map((entries) => entries.map((entry) => entrySignature(entry, facets)).join(', '));
+        if (sourceColumns !== targetColumns) {
+            differences.push(`columns: (${targetColumns}) → (${sourceColumns})`);
+        }
+    }
+    if ((source.unique ?? false) !== (target.unique ?? false)) {
+        differences.push(`unique: ${target.unique ?? false} → ${source.unique ?? false}`);
+    }
+    if (facets.has('accessMethod') && (source.type ?? 'btree') !== (target.type ?? 'btree')) {
+        differences.push(`type: ${target.type ?? 'btree'} → ${source.type ?? 'btree'}`);
+    }
+    if (facets.has('include')) {
+        // Order carries no meaning in an `INCLUDE` list, so it is compared as a set.
+        const [sourceInclude, targetInclude] = [source.include ?? [], target.include ?? []].map((columns) => [...columns].sort().join(', '));
+        if (sourceInclude !== targetInclude) {
+            differences.push(`include: (${targetInclude}) → (${sourceInclude})`);
+        }
+    }
+    return differences;
+}
+function entrySignature(entry, facets) {
+    const parts = [entry.column];
+    if (facets.has('order')) {
+        parts.push(entry.order ?? 'asc');
+    }
+    if (facets.has('nulls')) {
+        // Postgres states this on every entry, so an entity that omits it has asked for Postgres's own
+        // default: nulls sort opposite to the direction.
+        parts.push(`nulls ${entry.nulls ?? ((entry.order ?? 'asc') === 'desc' ? 'first' : 'last')}`);
+    }
+    if (facets.has('opsClass') && entry.opsClass) {
+        parts.push(entry.opsClass);
+    }
+    return parts.join(' ');
+}

package/dist/schema/schemaAST.js

@@ -400,13 +400,7 @@ export class SchemaAST {
             const table = clone.tables.get(idx.table.name);
             if (!table)
                 continue;
-            const columns = idx.columns.map((c) => table.columns.get(c.name)).filter((c) => c !== undefined);
-            const clonedIdx = {
-                ...idx,
-                table,
-                columns,
-            };
-            clone.addIndex(clonedIdx);
+            clone.addIndex({ ...idx, table });
         }
         return clone;
     }
@@ -442,7 +436,7 @@ export class SchemaAST {
                 })),
                 indexes: t.indexes.map((i) => ({
                     name: i.name,
-                    columns: i.columns.map((c) => c.name),
+                    columns: i.entries.map((entry) => entry.column),
                     unique: i.unique,
                 })),
             })),

package/dist/schema/schemaASTBuilder.d.ts

@@ -12,7 +12,7 @@ import type { ForeignKeyAction } from './types.js';
 /**
  * Options for building SchemaAST from entities.
  */
-export interface BuildFromEntitiesOptions {
+export interface BuildSchemaASTOptions {
     /** Custom table name resolver */
     resolveTableName?: (entity: Type<unknown>, meta: EntityMeta<unknown>) => string;
     /** Custom column name resolver */
@@ -23,62 +23,9 @@ export interface BuildFromEntitiesOptions {
     defaultForeignKeyAction?: ForeignKeyAction;
 }
 /**
- * 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 declare class SchemaASTBuilder {
-    private readonly namingStrategy?;
-    private readonly defaultForeignKeyAction;
-    private ast;
-    constructor(namingStrategy?: NamingStrategy | undefined, defaultForeignKeyAction?: ForeignKeyAction);
-    /**
-     * Reset the builder for a new schema.
-     */
-    reset(): this;
-    /**
-     * Get the built AST.
-     */
-    getAST(): SchemaAST;
-    /**
-     * Build AST from entity classes (decorated with @Entity, @Field, etc.)
-     */
-    fromEntities(entities: readonly Type<unknown>[], options?: BuildFromEntitiesOptions): SchemaAST;
-    /**
-     * 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.
-     */
-    private resolveColumnCanonicalType;
-    /**
-     * Add a table from entity metadata.
-     */
-    private addTableFromEntity;
-    /**
-     * Add relationships from entity relation decorators.
-     */
-    private addRelationshipsFromEntity;
-    /**
-     * Add indexes from field options (`@Field({ index })`) and from `@Index([...])`, which have nothing
-     * in common beyond their target table.
-     */
-    private addIndexesFromEntity;
-    /**
-     * 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.
-     */
-    private addCompositeIndex;
-}
+export declare function buildSchemaAST(entities: readonly Type<unknown>[], options?: BuildSchemaASTOptions): SchemaAST;