uql-orm 0.66.0 → 0.67.0

package/dist/schema/schemaAST.js

@@ -1,16 +1,6 @@
-/**
- * SchemaAST Class
- *
- * The main class for working with schema graphs.
- * Provides graph operations like navigation, validation, and topological sorting.
- */
 import { qualifyName } from '../util/sql.util.js';
-import { createOrder, dropOrder, findCycles } from './dependencyGraph.js';
-/**
- * A table node with its collections empty, ready to be filled. Six places build one, and the fields
- * that are pure boilerplate are exactly the ones a new field gets forgotten in: {@link TableNode.schema}
- * was added and `SchemaAST.clone` kept rebuilding nodes without it.
- */
+import { createOrder, dropOrder } from './dependencyGraph.js';
+/** A table node with its collections empty, ready to be filled. */
 export function createTableNode(name, schema, comment) {
     return {
         name,
@@ -24,264 +14,40 @@ export function createTableNode(name, schema, comment) {
         outgoingRelations: [],
     };
 }
-/**
- * Schema AST - A graph representation of a database schema.
- *
- * Enables:
- * - Graph navigation (dependencies, dependents)
- * - Circular dependency detection
- * - Topological sorting for correct DDL order
- * - Smart relation inference
- * - Schema validation
- */
+/** A database schema as a graph: tables, the foreign keys between them, and their indexes. */
 export class SchemaAST {
     tables = new Map();
     relationships = [];
     indexes = [];
-    /**
-     * Get a table by the name it is keyed under: schema-qualified where it has one, so two tables of
-     * the same name in different schemas stay distinct. Build the key with `qualifyName`.
-     */
+    /** A table by the key it is stored under: schema-qualified where it has one (see `qualifyName`). */
     getTable(name) {
         return this.tables.get(name);
     }
-    /**
-     * Add a table to the schema.
-     */
     addTable(table) {
         this.tables.set(qualifyName(table.name, table.schema), table);
     }
-    /**
-     * Remove a table from the schema.
-     */
-    removeTable(name) {
-        const table = this.tables.get(name);
-        if (!table)
-            return false;
-        // Remove all relationships involving this table
-        for (let i = this.relationships.length - 1; i >= 0; i--) {
-            const rel = this.relationships[i];
-            if (rel.from.table === table || rel.to.table === table) {
-                this.relationships.splice(i, 1);
-            }
-        }
-        // Remove all indexes for this table
-        for (let i = this.indexes.length - 1; i >= 0; i--) {
-            if (this.indexes[i].table === table) {
-                this.indexes.splice(i, 1);
-            }
-        }
-        return this.tables.delete(name);
-    }
-    /**
-     * Get all table nodes.
-     */
     getTables() {
-        return Array.from(this.tables.values());
-    }
-    /**
-     * Get all table names.
-     */
-    getTableNames() {
-        return Array.from(this.tables.keys());
-    }
-    /**
-     * Get all tables that depend on this table (have FKs pointing to it).
-     * These are tables that reference this table's primary key.
-     */
-    getDependentTables(table) {
-        return table.incomingRelations.map((r) => r.from.table);
-    }
-    /**
-     * Get all tables this table depends on (has FKs to).
-     * These are tables that this table references.
-     */
-    getDependencies(table) {
-        return table.outgoingRelations.map((r) => r.to.table);
-    }
-    /**
-     * Get the relationship between two tables (if any).
-     */
-    getRelationship(from, to) {
-        return this.relationships.find((r) => r.from.table === from && r.to.table === to);
-    }
-    /**
-     * Get all relationships for a table.
-     */
-    getTableRelationships(table) {
-        return this.relationships.filter((r) => r.from.table === table || r.to.table === table);
-    }
-    /**
-     * Get the column that a foreign key column references.
-     */
-    getReferencedColumn(fkColumn) {
-        return fkColumn.references?.to.columns[0];
-    }
-    /**
-     * Detect circular foreign key dependencies.
-     * Returns arrays of tables that form cycles.
-     */
-    detectCircularDependencies() {
-        return findCycles(this.tables.values(), (table) => this.getDependencies(table));
+        return [...this.tables.values()];
     }
-    /**
-     * Check if there are any circular dependencies.
-     */
-    hasCircularDependencies() {
-        return this.detectCircularDependencies().length > 0;
-    }
-    /**
-     * Get tables in correct order for CREATE (dependencies first).
-     * Tables with no dependencies come first, then tables that depend on them, etc.
-     */
+    /** Tables in `CREATE` order, each after the tables it references. */
     getCreateOrder() {
-        return createOrder(this.tables.values(), (table) => this.getDependencies(table));
+        return createOrder(this.tables.values(), referencedTables);
     }
-    /**
-     * Get tables in correct order for DROP (dependents first).
-     * Tables that depend on others come first, then the tables they depend on.
-     */
+    /** Tables in `DROP` order, each before the tables it references. */
     getDropOrder() {
-        return dropOrder(this.tables.values(), (table) => this.getDependencies(table));
-    }
-    /**
-     * Validate schema integrity.
-     * Checks for:
-     * - Missing FK targets
-     * - Circular dependencies
-     * - Orphan columns
-     * - Duplicate indexes
-     */
-    validate() {
-        const errors = [];
-        // Check all FK targets exist
-        for (const rel of this.relationships) {
-            if (!this.tables.has(rel.to.table.name)) {
-                errors.push({
-                    type: 'missing_fk_target',
-                    message: `FK target table "${rel.to.table.name}" does not exist`,
-                    relationship: rel,
-                });
-            }
-        }
-        // Check for circular dependencies
-        const cycles = this.detectCircularDependencies();
-        for (const cycle of cycles) {
-            errors.push({
-                type: 'circular_dependency',
-                message: `Circular FK: ${cycle.map((t) => t.name).join(' -> ')}`,
-                tables: cycle,
-            });
-        }
-        // Check for duplicate index names within same table
-        for (const table of this.tables.values()) {
-            const indexNames = new Set();
-            for (const index of table.indexes) {
-                if (indexNames.has(index.name)) {
-                    errors.push({
-                        type: 'duplicate_index',
-                        message: `Duplicate index name "${index.name}" in table "${table.name}"`,
-                        table,
-                    });
-                }
-                indexNames.add(index.name);
-            }
-        }
-        return errors;
+        return dropOrder(this.tables.values(), referencedTables);
     }
-    /**
-     * Check if the schema is valid (no validation errors).
-     */
-    isValid() {
-        return this.validate().length === 0;
-    }
-    /**
-     * Check if a table looks like a junction table (ManyToMany through).
-     * Junction tables typically have:
-     * - Exactly 2 foreign keys
-     * - Few other columns (id, maybe timestamps)
-     * - Primary key might be composite of the FKs
-     */
-    isJunctionTable(table) {
-        const fkCount = table.outgoingRelations.length;
-        const columnCount = table.columns.size;
-        // Must have exactly 2 FKs
-        if (fkCount !== 2) {
-            return false;
-        }
-        // Should have few columns (typically: id + 2 FKs + maybe timestamps)
-        if (columnCount > 6) {
-            return false;
-        }
-        // Check if name suggests a junction (contains both related table names)
-        const relatedTables = table.outgoingRelations.map((r) => r.to.table.name.toLowerCase());
-        const tableName = table.name.toLowerCase();
-        // Common patterns: user_roles, post_tags, etc.
-        const containsBothNames = relatedTables.every((name) => tableName.includes(name.replace(/s$/, '')) || tableName.includes(name));
-        return containsBothNames || columnCount <= 5;
-    }
-    /**
-     * Infer relation type from schema structure.
-     */
-    inferRelationType(rel) {
-        const fromCol = rel.from.columns[0];
-        // Check if source is junction table -> ManyToMany
-        if (this.isJunctionTable(rel.from.table)) {
-            return 'ManyToMany';
-        }
-        // Unique FK -> OneToOne
-        if (fromCol?.isUnique) {
-            return 'OneToOne';
-        }
-        // Default: ManyToOne (many rows can reference same target)
-        return 'ManyToOne';
-    }
-    /**
-     * Get the inverse relation type.
-     */
-    getInverseRelationType(type) {
-        switch (type) {
-            case 'OneToOne':
-                return 'OneToOne';
-            case 'OneToMany':
-                return 'ManyToOne';
-            case 'ManyToOne':
-                return 'OneToMany';
-            case 'ManyToMany':
-                return 'ManyToMany';
-        }
-    }
-    /**
-     * Add an index to the schema.
-     */
     addIndex(index) {
         this.indexes.push(index);
         if (!index.table.indexes.includes(index)) {
             index.table.indexes.push(index);
         }
     }
-    /**
-     * Get all indexes for a table.
-     */
-    getTableIndexes(tableName) {
-        const table = this.tables.get(tableName);
-        return table?.indexes ?? [];
-    }
-    /**
-     * Find an index by name.
-     */
-    getIndex(name) {
-        return this.indexes.find((i) => i.name === name);
-    }
-    /**
-     * Add a relationship to the schema.
-     */
+    /** Adds a foreign key, linking it from both tables and both column sets. */
     addRelationship(rel) {
         this.relationships.push(rel);
-        // Update table links
         rel.from.table.outgoingRelations.push(rel);
         rel.to.table.incomingRelations.push(rel);
-        // Update column links
         for (const col of rel.from.columns) {
             col.references = rel;
         }
@@ -289,125 +55,7 @@ export class SchemaAST {
             col.referencedBy.push(rel);
         }
     }
-    /**
-     * Remove a relationship from the schema.
-     */
-    removeRelationship(name) {
-        const index = this.relationships.findIndex((r) => r.name === name);
-        if (index === -1)
-            return false;
-        const rel = this.relationships[index];
-        // Remove from table links
-        const fromIdx = rel.from.table.outgoingRelations.indexOf(rel);
-        if (fromIdx !== -1)
-            rel.from.table.outgoingRelations.splice(fromIdx, 1);
-        const toIdx = rel.to.table.incomingRelations.indexOf(rel);
-        if (toIdx !== -1)
-            rel.to.table.incomingRelations.splice(toIdx, 1);
-        // Remove from column links
-        for (const col of rel.from.columns) {
-            if (col.references === rel) {
-                col.references = undefined;
-            }
-        }
-        for (const col of rel.to.columns) {
-            const refIdx = col.referencedBy.indexOf(rel);
-            if (refIdx !== -1)
-                col.referencedBy.splice(refIdx, 1);
-        }
-        this.relationships.splice(index, 1);
-        return true;
-    }
-    /**
-     * Create a deep clone of this schema.
-     */
-    clone() {
-        const clone = new SchemaAST();
-        // First pass: tables and columns. The table is built before its columns so each clone can link
-        // back to it on creation - `columns` and `primaryKey` are readonly properties holding mutable
-        // containers, so they are filled in afterwards without reassigning anything.
-        for (const [name, table] of this.tables) {
-            const clonedTable = createTableNode(table.name, table.schema, table.comment);
-            for (const [colName, col] of table.columns) {
-                clonedTable.columns.set(colName, { ...col, table: clonedTable, referencedBy: [], references: undefined });
-            }
-            clonedTable.primaryKey.push(...table.primaryKey.flatMap((pk) => clonedTable.columns.get(pk.name) ?? []));
-            clone.tables.set(name, clonedTable);
-        }
-        // Second pass: clone relationships
-        for (const rel of this.relationships) {
-            const fromTable = clone.tables.get(rel.from.table.name);
-            const toTable = clone.tables.get(rel.to.table.name);
-            if (!fromTable || !toTable)
-                continue;
-            const fromColumns = rel.from.columns
-                .map((c) => fromTable.columns.get(c.name))
-                .filter((c) => c !== undefined);
-            const toColumns = rel.to.columns
-                .map((c) => toTable.columns.get(c.name))
-                .filter((c) => c !== undefined);
-            const clonedRel = {
-                ...rel,
-                from: {
-                    table: fromTable,
-                    columns: fromColumns,
-                },
-                to: {
-                    table: toTable,
-                    columns: toColumns,
-                },
-                through: rel.through ? clone.tables.get(rel.through.name) : undefined,
-            };
-            clone.addRelationship(clonedRel);
-        }
-        // Third pass: clone indexes
-        for (const idx of this.indexes) {
-            const table = clone.tables.get(idx.table.name);
-            if (!table)
-                continue;
-            clone.addIndex({ ...idx, table });
-        }
-        return clone;
-    }
-    /**
-     * Get statistics about the schema.
-     */
-    getStats() {
-        let columnCount = 0;
-        for (const table of this.tables.values()) {
-            columnCount += table.columns.size;
-        }
-        return {
-            tableCount: this.tables.size,
-            columnCount,
-            relationshipCount: this.relationships.length,
-            indexCount: this.indexes.length,
-        };
-    }
-    /**
-     * The schema as a plain object, for serialization and debugging. The graph links are what is left
-     * out - they are cycles, and nothing else is: listing the fields to keep instead dropped every
-     * option a column had gained since, `defaultValue` and `enum` included.
-     */
-    toJSON() {
-        return {
-            tables: Array.from(this.tables.values()).map((t) => ({
-                name: t.name,
-                columns: Array.from(t.columns.values()).map(({ table: _table, referencedBy: _referencedBy, references: _references, ...column }) => column),
-                indexes: t.indexes.map((i) => ({
-                    name: i.name,
-                    columns: i.entries.map((entry) => entry.column),
-                    unique: i.unique,
-                })),
-            })),
-            relationships: this.relationships.map((r) => ({
-                name: r.name,
-                type: r.type,
-                from: `${r.from.table.name}.${r.from.columns.map((c) => c.name).join(',')}`,
-                to: `${r.to.table.name}.${r.to.columns.map((c) => c.name).join(',')}`,
-                onDelete: r.onDelete,
-                onUpdate: r.onUpdate,
-            })),
-        };
-    }
+}
+function referencedTables(table) {
+    return table.outgoingRelations.map((rel) => rel.to.table);
 }

package/dist/schema/schemaASTBuilder.d.ts

@@ -1,10 +1,3 @@
-/**
- * SchemaAST Builder
- *
- * Constructs a SchemaAST from:
- * - Entity metadata (decorator-based entities)
- * - Database introspection results (TableSchema[])
- */
 import type { EntityGetter } from '../type/entity.js';
 import type { EntityMeta, EntityWhereMeta, FieldMeta, FieldOptions, Type } from '../type/index.js';
 import type { NamingStrategy } from '../type/namingStrategy.js';
@@ -40,22 +33,7 @@ export interface BuildSchemaASTOptions {
  */
 export declare function buildSchemaAST(entities: readonly Type<object>[], options?: BuildSchemaASTOptions): 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.
+ * A field's canonical type, taken from the referenced key where the field gave `references` and no
+ * `type` (`typeFromReference`), so a foreign key matches the key it points at; `columnType` always wins.
  */
 export declare function resolveColumnCanonicalType(field: FieldMeta, seen?: Set<EntityGetter>): CanonicalType;

package/dist/schema/schemaASTBuilder.js

@@ -1,10 +1,3 @@
-/**
- * SchemaAST Builder
- *
- * Constructs a SchemaAST from:
- * - Entity metadata (decorator-based entities)
- * - Database introspection results (TableSchema[])
- */
 import { fieldOf, foreignKeysOf, getMeta, soleIdOf } from '../entity/metadata/definition.js';
 import { declaredIndexes, indexNameParts, renderIndexColumn } from '../util/ddlExpression.util.js';
 import { isInlinedExpression } from '../util/field.util.js';
@@ -46,23 +39,8 @@ function refuseDdl() {
     throw new TypeError('building the schema of an entity that declares SQL (a check, a stored computed column, an index expression or predicate) needs a dialect to render it: pass `compileDdl`, as `buildEntityAST` does');
 }
 /**
- * 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.
+ * A field's canonical type, taken from the referenced key where the field gave `references` and no
+ * `type` (`typeFromReference`), so a foreign key matches the key it points at; `columnType` always wins.
  */
 export function resolveColumnCanonicalType(field, seen = new Set()) {
     const hasExplicitType = !!field.columnType || !field.typeFromReference;
@@ -156,8 +134,6 @@ function addRelationshipsFromEntity(ctx, meta) {
             // references, onDelete })` work with no relation declared at all.
             onDelete: foreignKey.onDelete ?? meta.fields[foreignKey.references[0].local]?.onDelete ?? ctx.defaultForeignKeyAction,
             onUpdate: foreignKey.onUpdate ?? ctx.defaultForeignKeyAction,
-            confidence: 1.0,
-            inferredFrom: 'entity_decorator',
         });
     }
 }
@@ -190,8 +166,6 @@ function addForeignKeyIndexes(ctx, meta, table) {
             table,
             entries: columns.map((column) => ({ column })),
             unique: false,
-            source: 'entity',
-            syncStatus: 'entity_only',
         });
     }
 }
@@ -237,7 +211,5 @@ function addCompositeIndex(ctx, table, meta, idxMeta) {
         m: idxMeta.m,
         efConstruction: idxMeta.efConstruction,
         lists: idxMeta.lists,
-        source: 'entity',
-        syncStatus: 'entity_only',
     });
 }

package/dist/schema/schemaASTDiffer.d.ts

@@ -1,12 +1,3 @@
-/**
- * SchemaAST Differ
- *
- * Compares two SchemaAST instances and produces a detailed diff.
- * Used for:
- * - Migration generation (entity vs database)
- * - Drift detection (expected vs actual)
- * - Schema synchronization
- */
 import { type IndexFacet } from './indexDifferences.js';
 import type { SchemaAST } from './schemaAST.js';
 import type { CanonicalType } from './types.js';
@@ -26,52 +17,21 @@ export interface DiffOptions {
     /** Tables to exclude from comparison */
     excludeTables?: string[];
     /**
-     * A type as the engine would actually store it, for the caller that has a dialect.
-     *
-     * Several canonical types share one storage type per engine - a `boolean` is `TINYINT(1)` on MySQL
-     * and `INTEGER` on SQLite - so comparing them canonically reports an alteration on every sync for
-     * those columns. Passing both sides through the engine first is what settles that, and it is the
-     * only thing here a dialect is needed for, so it arrives as a function rather than as a dependency.
+     * A type as the engine stores it, since several canonical types share one storage type (a boolean is
+     * `TINYINT(1)` on MySQL): the one thing a dialect is needed for, passed as a function.
      */
     normalizeType?: (type: CanonicalType) => CanonicalType;
-    /**
-     * Whether two defaults are the same value, for the caller that has a dialect.
-     *
-     * A database reprints a default from its parse tree, so `'active'` comes back as
-     * `'active'::character varying` on Postgres and a symbolic `now()` matches no spelling of
-     * `CURRENT_TIMESTAMP`. Undoing that needs the dialect that wrote it, so it arrives as a function.
-     */
+    /** Whether two defaults are one value, as the dialect that reprinted them can tell: `'a'::character varying` is `'a'`. */
     defaultsEqual?: (expected: unknown, actual: unknown) => boolean;
 }
-/**
- * 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
- */
+/** The differences between the expected schema (the entities) and the actual one (the database). */
 export declare function diffSchemas(source: SchemaAST, target: SchemaAST, options?: DiffOptions): SchemaDiffResult;
-/**
- * Compare two tables and return the differences.
- *
- * Exported because it is also how a migration is planned: the generator diffs one entity's table
- * against the one the database reported, then projects the result into a `SchemaDiff`. One
- * comparison serves both, so drift and migrations can no longer disagree about what has changed.
- */
+/** The differences between two tables, shared by migrations and drift detection so they cannot disagree. */
 export declare function diffTable(source: TableNode, target: TableNode, options?: DiffOptions): (TableDiff & {
     readonly columnDiffs: ColumnDiff[];
     readonly indexDiffs: IndexDiff[];
 }) | undefined;
-/**
- * Compare two lists of relationships.
- *
- * Lists rather than whole schemas, because a migration diffs one table: its two sides are that
- * table's `outgoingRelations`, where `diffSchemas` passes the schema's every relationship.
- *
- * Matched by columns, never by name - the engine named every constraint that already exists, so
- * pairing on names would report every hand-named one as a drop and an add.
- */
+/** The differences between two lists of foreign keys, matched by their columns and never by the name the engine gave them. */
 export declare function diffRelationshipNodes(source: readonly RelationshipNode[], target: readonly RelationshipNode[], opts?: DiffOptions): RelationshipDiff[];
 /** A relationship's `ON DELETE` and `ON UPDATE`, an unstated one read as the action the database applies. */
 export declare function referentialActions(rel: RelationshipNode): {