uql-orm 0.63.0 → 0.65.0

package/dist/entity/metadata/definition.js

@@ -1,6 +1,6 @@
 import { SOFT_DELETE_FILTER } from '../../type/index.js';
 import { isInlinedExpression } from '../../util/field.util.js';
-import { entityName, entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, lowerFirst, memberRefs, normalizeIndexColumn, upperFirst, definedEntries, } from '../../util/index.js';
+import { entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, lowerFirst, memberRefs, normalizeIndexColumn, upperFirst, definedEntries, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 /**
  * A map held on `globalThis` through the global symbol registry, so a single one survives multiple
@@ -54,10 +54,11 @@ export function defineRelation(entity, key, opts) {
  * exist, and the registry holds data alone.
  */
 export function relationRegistration({ mappedBy, references, ...opts }) {
+    const joined = references?.(keyMap(), keyMap());
     return {
         ...opts,
         ...(mappedBy && { mappedBy: mappedBy(keyMap()) }),
-        ...(references && { references: [...references(keyMap(), keyMap())] }),
+        ...(joined && { references: typeof joined === 'string' ? joined : [...joined] }),
     };
 }
 /** Every entity's key map: a callback only reads one property off it, and that property is its own key. */
@@ -70,8 +71,8 @@ function addRelation(entity, key, registration) {
         throw new TypeError(`'${entity.name}.${key}' needs an 'entity' getter, e.g. '@ManyToOne({ entity: () => Company })'.`);
     }
     if (registration.through && registration.references) {
-        throw new TypeError(`'${entity.name}.${key}' joins through a junction, whose columns follow the convention; 'references' ` +
-            "pairs the declaring entity's columns with the target's instead.");
+        throw new TypeError(`'${entity.name}.${key}' joins through a junction, whose column referencing each side is the join; ` +
+            "'references' pairs the declaring entity's columns with the target's instead.");
     }
     const meta = ensureWritableMeta(entity);
     // Registration writes into a map declared as resolved: `getMeta` runs `fillRelations`, which settles
@@ -312,51 +313,62 @@ export function getMeta(entity) {
     if (meta.processedAt === meta.revision) {
         return meta;
     }
-    // Stamped before finalizing, not after: `fillInverseSide` reads the other side through `getMeta`,
-    // and with each side mapped by the other that recursion has to find this half-filled meta rather
-    // than run again. Finalizing twice is harmless anyway - every step of it skips what it settled.
+    // Stamped before finalizing: `fillInverseSide` reads the other side through `getMeta`, and with each
+    // side mapped by the other that recursion has to find this half-filled meta rather than run again.
+    // Unstamped when finalizing throws, so the next read reports the same mistake; running it again is
+    // harmless, since every step skips what it settled.
     meta.processedAt = meta.revision;
-    return fillRelations(meta);
+    try {
+        return fillRelations(meta);
+    }
+    catch (error) {
+        meta.processedAt = undefined;
+        throw error;
+    }
 }
 function fillRelations(meta) {
     for (const [relKey, relation] of definedEntries(meta.relations)) {
-        // The registered view: `references` may be unset until this settles it.
+        // The registered view: `references` may be unset, or the one column a to-one names, until this settles it.
         const relOpts = relation;
         const at = `'${meta.entity.name}.${relKey}'`;
-        if (relOpts.mappedBy) {
-            fillInverseSide(at, meta, relOpts, relOpts.mappedBy);
-        }
-        else if (!relOpts.references) {
-            fillOwningSide(at, meta, relKey, relOpts);
-        }
-        if (!relOpts.references?.length) {
+        const references = relOpts.mappedBy
+            ? fillInverseSide(at, meta, relOpts, relOpts.mappedBy)
+            : (pairedReferences(at, relOpts) ?? fillOwningSide(at, meta, relKey, relOpts));
+        if (!references.length) {
             throw new TypeError(`${at} has no columns to join on.`);
         }
-        // Hand-written `references` land here too: naming the columns says which they are, not that they exist.
-        if (relOpts.through) {
-            const junction = getMeta(relOpts.through());
-            for (const { local } of relOpts.references) {
-                if (junction.fields[local])
-                    continue;
-                throw new TypeError(`${at} joins through '${junction.entity.name}', which has no '${local}' field: a junction's ` +
-                    'columns are named after the entities it joins. Declare it.');
-            }
-        }
     }
-    fillForeignKeyRelations(meta);
+    // A column `references` names is a foreign key with or without a relation over it, and one cannot point
+    // at a composite key: refused on first read, as a relation that cannot join is, not at the schema build.
+    foreignKeysOf(meta);
     return meta;
 }
+/**
+ * The pairs a relation joins on, with the one column a to-one names paired with the target's primary key:
+ * on first read rather than at registration, which can run before the target has a key to pair with.
+ */
+function pairedReferences(at, relOpts) {
+    const { references } = relOpts;
+    if (typeof references !== 'string') {
+        return references;
+    }
+    const target = ensureMeta(relOpts.entity());
+    if (relOpts.mappedBy || isToManyRelation(relOpts) || target.ids.length > 1) {
+        throw new TypeError(`${at} names one column, '${references}', which only a to-one holding a foreign key to a one-column key ` +
+            'can: pair the columns, [{ local, foreign }].');
+    }
+    relOpts.references = [{ local: references, foreign: soleIdOf(target, 'a foreign key') }];
+    return relOpts.references;
+}
 function fillOwningSide(at, meta, relKey, relOpts) {
     const relMeta = ensureMeta(relOpts.entity());
     if (relOpts.through) {
         // Both columns live on the junction, whatever the cardinality: `deleteRelations` and every dialect
         // read them as junction columns. A composite key contributes one pair per column of it, which is
         // what makes the join address a whole key rather than part.
-        relOpts.references = [
-            ...meta.ids.map((key) => ({ local: junctionColumn(meta, key), foreign: key })),
-            ...relMeta.ids.map((key) => ({ local: junctionColumn(relMeta, key), foreign: key })),
-        ];
-        return;
+        const junction = getMeta(relOpts.through());
+        relOpts.references = [...junctionReferences(at, junction, meta), ...junctionReferences(at, junction, relMeta)];
+        return relOpts.references;
     }
     if (isToManyRelation(relOpts)) {
         throw new TypeError(`${at} is a to-many relation with no way to join: it needs 'mappedBy' (the field on the other side), ` +
@@ -366,16 +378,23 @@ function fillOwningSide(at, meta, relKey, relOpts) {
     // property, so both are spelled from the referenced *property* - a column name is what the naming
     // strategy makes of this afterwards.
     const sole = relMeta.ids.length === 1;
-    relOpts.references = relMeta.ids.map((key) => ({
+    const references = relMeta.ids.map((key) => ({
         local: sole ? `${relKey}Id` : `${relKey}${upperFirst(key)}`,
         foreign: key,
     }));
+    // A column the entity declares would be joined by its name alone, so renaming either one would leave
+    // the other behind, still compiling.
+    const fields = meta.fields;
+    if (references.some(({ local }) => fields[local])) {
+        const own = lowerFirst(meta.entity.name);
+        throw new TypeError(`${at} joins ${references.map(({ local }) => `'${local}'`).join(', ')} by name, which a rename does not ` +
+            `follow: link them with ${sole ? `'references: (${own}) => ${own}.${references[0].local}'` : "'references' pairs"}.`);
+    }
     // `typeFromReference` so schema generation resolves the referenced primary key's exact type
     // (columnType, length, chained keys) rather than trusting the fallback, as it does for an
     // explicit `@Field({ references })`.
-    const fields = meta.fields;
-    for (const { local, foreign } of relOpts.references) {
-        fields[local] ??= {
+    for (const { local, foreign } of references) {
+        fields[local] = {
             name: local,
             type: fieldOf(relMeta, foreign).type ?? Number,
             references: relOpts.entity,
@@ -383,12 +402,15 @@ function fillOwningSide(at, meta, relKey, relOpts) {
             typeFromReference: true,
         };
     }
+    relOpts.references = references;
+    return references;
 }
 function fillInverseSide(at, meta, relOpts, mappedBy) {
     const relEntity = relOpts.entity();
     const relMeta = getMeta(relEntity);
-    if (relOpts.references)
-        return;
+    const own = pairedReferences(at, relOpts);
+    if (own)
+        return own;
     if (relMeta.fields[mappedBy]) {
         if (meta.ids.length > 1) {
             throw new TypeError(`${at} is mapped by '${relEntity.name}.${mappedBy}', one column, but the primary key of ` +
@@ -397,7 +419,7 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
         }
         // `local` is this entity's own key, as in every other pair.
         relOpts.references = [{ local: meta.ids[0], foreign: mappedBy }];
-        return;
+        return relOpts.references;
     }
     // Authored view again: with each side mapped by the other, the target is still mid-resolution here and
     // its own `references` are unset, which is what the second throw reports.
@@ -405,7 +427,8 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
     if (!owner) {
         throw new TypeError(`${at} is mapped by '${mappedBy}', which is neither a field nor a relation of '${relEntity.name}'.`);
     }
-    if (!owner.references?.length) {
+    const ownerReferences = pairedReferences(`'${relEntity.name}.${mappedBy}'`, owner);
+    if (!ownerReferences?.length) {
         throw new TypeError(`${at} is mapped by '${relEntity.name}.${mappedBy}', an inverse side too, so neither owns the foreign key.`);
     }
     // Two different flips: a junction's pairs are the owner's group followed by ours, so the two groups
@@ -413,50 +436,55 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
     // plain foreign key is one pair per key whose ends swap.
     relOpts.references =
         relOpts.cardinality === 'm1' || relOpts.cardinality === 'mm'
-            ? [...owner.references.slice(relMeta.ids.length), ...owner.references.slice(0, relMeta.ids.length)]
-            : owner.references.map(({ local, foreign }) => ({ local: foreign, foreign: local }));
+            ? [...ownerReferences.slice(relMeta.ids.length), ...ownerReferences.slice(0, relMeta.ids.length)]
+            : ownerReferences.map(({ local, foreign }) => ({ local: foreign, foreign: local }));
     relOpts.through = owner.through;
+    return relOpts.references;
 }
 /**
- * A field carrying `references` is a foreign key, and a foreign key is a many-to-one whether or not
- * anyone declared the relation. Deriving it everywhere is what lets a junction be written as two plain
- * columns: it needs the relations for `$populate` and for its DDL constraints, and it used to get them
- * only because some *other* entity pointed `through` at it. Gaps only, so a declared relation keeps its
- * own cardinality and `cascade`.
+ * The foreign keys an entity holds: each owning to-one's columns, and each `@Field({ references })` no
+ * relation joins on, as the many-to-one it describes, once its target has registered a key. What the
+ * schema build constrains and a junction joins by.
  */
-function fillForeignKeyRelations(meta) {
-    const joined = new Set(definedEntries(meta.relations).flatMap(([, relation]) => relation.references.map(({ local }) => local)));
-    for (const [fieldKey, { references }] of definedEntries(meta.fields)) {
-        if (!references || joined.has(fieldKey))
-            continue;
-        const target = ensureMeta(references());
-        // Nothing to derive from an entity that has not registered its own fields yet.
+export function foreignKeysOf(meta) {
+    const owning = definedEntries(meta.relations)
+        .map(([, relation]) => relation)
+        .filter(({ cardinality, mappedBy }) => cardinality === 'm1' || (cardinality === '11' && !mappedBy));
+    const joined = new Set(owning.flatMap(({ references }) => references.map(({ local }) => local)));
+    const columns = definedEntries(meta.fields).flatMap(([key, field]) => {
+        if (!field.references || joined.has(key))
+            return [];
+        const target = ensureMeta(field.references());
         if (!target.ids.length)
-            continue;
+            return [];
         if (target.ids.length > 1) {
-            throw new TypeError(`'${meta.entity.name}.${fieldKey}' cannot reference '${target.entity.name}', whose primary key is composite ` +
+            throw new TypeError(`'${meta.entity.name}.${key}' cannot reference '${target.entity.name}', whose primary key is composite ` +
                 `(${target.ids.join(', ')}): a column points at one. Use ` +
                 `'@ManyToOne({ entity: () => ${target.entity.name} })', which declares one column per key.`);
         }
-        const [foreign] = target.ids;
-        // The relation takes the column's name minus the key it points at (`itemId` -> `item`); a column
-        // named anything else has no name to take, so it stays a plain foreign key.
-        const suffix = upperFirst(foreign);
-        if (!fieldKey.endsWith(suffix))
-            continue;
-        const relKey = fieldKey.slice(0, -suffix.length);
-        if (!relKey || meta.fields[relKey] || meta.relations[relKey])
-            continue;
-        meta.relations[relKey] = {
-            entity: references,
-            cardinality: 'm1',
-            references: [{ local: fieldKey, foreign }],
-        };
-    }
-}
-/** `<entityName><IdColumn>`, not the `<relationKey>Id` an owning to-one derives: a junction row has no relation key to borrow from. */
-function junctionColumn(meta, idKey) {
-    return lowerFirst(entityName(meta)) + upperFirst(fieldOf(meta, idKey).name ?? idKey);
+        return [{ entity: field.references, cardinality: 'm1', references: [{ local: key, foreign: target.ids[0] }] }];
+    });
+    return [...owning, ...columns];
+}
+/** Each key of `side`, paired with the one column of `junction` referencing it: a rename of either follows. */
+function junctionReferences(at, junction, side) {
+    const pairs = foreignKeysOf(junction).flatMap(({ entity, references }) => entity() === side.entity ? references : []);
+    return side.ids.map((key) => {
+        const [pair, ...others] = pairs.filter(({ foreign }) => foreign === key);
+        const referenced = `'${side.entity.name}.${key}'`;
+        if (!pair) {
+            const declare = side.ids.length > 1
+                ? `@ManyToOne({ entity: () => ${side.entity.name} })`
+                : `@Field({ references: () => ${side.entity.name} })`;
+            throw new TypeError(`${at} joins through '${junction.entity.name}', which has no column referencing ${referenced}: declare one, '${declare}'.`);
+        }
+        if (others.length) {
+            const columns = [pair, ...others].map(({ local }) => `'${local}'`).join(' and ');
+            throw new TypeError(`${at} joins through '${junction.entity.name}', where ${columns} each reference ${referenced}: a junction ` +
+                'needs exactly one column per key of each side.');
+        }
+        return { local: pair.local, foreign: key };
+    });
 }
 /** Every key the entity marks, in declaration order. More than one is a composite primary key. */
 function getIdKeys(meta) {
@@ -490,7 +518,12 @@ function extendMeta(target, source) {
         }
     }
     target.fields = { ...sourceFields, ...target.fields };
-    target.relations = { ...source.relations, ...target.relations };
+    // A copy of each relation per entity: resolving one writes the columns it joins on into it, and those
+    // columns are the resolving entity's, so one shared object left every later entity without them.
+    target.relations = {
+        ...Object.fromEntries(definedEntries(source.relations).map(([key, relation]) => [key, { ...relation }])),
+        ...target.relations,
+    };
     // Inherit user-defined filters from the parent (child overrides by name). The built-in soft-delete
     // filter + `meta.softDelete` are (re)derived from the merged fields in `defineEntity`.
     if (source.filters) {

package/dist/migrate/builder/expressions.js

@@ -99,21 +99,7 @@ function defaultLiteral(value, dialect) {
     if (typeof value === 'boolean') {
         return dialect.booleanLiteral === 'native' ? (value ? 'TRUE' : 'FALSE') : value ? '1' : '0';
     }
-    if (value instanceof Date) {
-        return dialect.escape(ddlTimestamp(value));
-    }
-    if (typeof value === 'object') {
-        return dialect.escape(JSON.stringify(value));
-    }
-    return dialect.escape(value);
-}
-/**
- * `YYYY-MM-DD HH:mm:ss.SSS` in UTC. Not `toISOString`, whose `T` and `Z` MySQL rejects outright
- * ("Invalid default value"), and not `escape`'s local-time form, which would make the DDL depend on
- * the machine that generated it.
- */
-function ddlTimestamp(date) {
-    return date.toISOString().replace('T', ' ').replace('Z', '');
+    return dialect.escape(typeof value === 'object' && !(value instanceof Date) ? JSON.stringify(value) : value);
 }
 function expressionSql(expression, dialect) {
     const { expressions } = DIALECT_DEFAULTS[dialect.dialectName];

package/dist/migrate/builder/migrationBuilder.d.ts

@@ -1,13 +1,6 @@
-/**
- * Migration Builder
- *
- * Provides type-safe migration operations with two modes:
- * - OperationRecorder: Record operations only (for code generation)
- * - MigrationBuilder: Execute DDL operations (for integration tests/runtime)
- */
 import type { ForeignKeyAction } from '../../schema/types.js';
 import type { IndexColumnInput, IndexOptions } from '../../type/index.js';
-import type { SqlQuerier } from '../../type/querier.js';
+import type { SchemaGenerator } from '../../type/migration.js';
 import type { AnyMigrationOperation, IAlterTableBuilder, IColumnBuilder, IColumnFactory, IMigrationBuilder, ITableBuilder } from './types.js';
 type ForeignKeyTarget = {
     table: string;
@@ -49,28 +42,13 @@ export declare class OperationRecorder implements IMigrationBuilder {
     getOperations(): AnyMigrationOperation[];
 }
 /**
- * Executes DDL operations via a SQL querier.
- * Use for integration tests and runtime schema management.
- *
- * @example
- * ```typescript
- * const builder = new MigrationBuilder(querier);
- *
- * await builder.createTable('users', (t) => {
- *   t.id();
- *   t.string('name');
- *   t.timestamps();
- * });
- * ```
+ * Records each operation, then runs the statements `generator` writes for it through `run`. Build one
+ * for a querier with `migrationBuilderFor`.
  */
 export declare class MigrationBuilder extends OperationRecorder {
-    private readonly querier;
-    private readonly sqlGenerator;
-    constructor(querier: SqlQuerier);
-    /** The recorder's sink, plus the statements the operation turns into. */
+    private readonly generator;
+    private readonly run;
+    constructor(generator: SchemaGenerator, run: (statement: string) => Promise<unknown>);
     protected record(operation: AnyMigrationOperation): Promise<void>;
-    private getCreateTableStatements;
-    private execute;
-    private operationToSql;
 }
 export {};

package/dist/migrate/builder/migrationBuilder.js

@@ -1,14 +1,5 @@
-/**
- * Migration Builder
- *
- * Provides type-safe migration operations with two modes:
- * - OperationRecorder: Record operations only (for code generation)
- * - MigrationBuilder: Execute DDL operations (for integration tests/runtime)
- */
 import { indexNameParts, normalizeIndexColumn } from '../../util/index.js';
 import { derivedIndexName } from '../../util/sql.util.js';
-import { createSchemaGenerator } from '../schemaGenerator.js';
-import { splitSqlStatements } from './splitSqlStatements.js';
 import { TableBuilder } from './tableBuilder.js';
 /**
  * One `createIndex` operation. Shared because the alter-table builder, the recorder and the
@@ -239,86 +230,21 @@ export class OperationRecorder {
     }
 }
 /**
- * Executes DDL operations via a SQL querier.
- * Use for integration tests and runtime schema management.
- *
- * @example
- * ```typescript
- * const builder = new MigrationBuilder(querier);
- *
- * await builder.createTable('users', (t) => {
- *   t.id();
- *   t.string('name');
- *   t.timestamps();
- * });
- * ```
+ * Records each operation, then runs the statements `generator` writes for it through `run`. Build one
+ * for a querier with `migrationBuilderFor`.
  */
 export class MigrationBuilder extends OperationRecorder {
-    querier;
-    sqlGenerator;
-    constructor(querier) {
+    generator;
+    run;
+    constructor(generator, run) {
         super();
-        this.querier = querier;
-        const generator = createSchemaGenerator(querier.dialect);
-        if (!generator) {
-            throw new TypeError(`Could not find a schema generator for dialect: ${querier.dialect.dialectName}`);
-        }
-        this.sqlGenerator = generator;
+        this.generator = generator;
+        this.run = run;
     }
-    /** The recorder's sink, plus the statements the operation turns into. */
     async record(operation) {
         await super.record(operation);
-        await this.execute(operation);
-    }
-    getCreateTableStatements(operation) {
-        return this.sqlGenerator.generateCreateTableFromDefinition(operation.table);
-    }
-    async execute(operation) {
-        if (operation.type === 'createTable') {
-            for (const statement of this.getCreateTableStatements(operation)) {
-                await this.querier.run(statement);
-            }
-            return;
-        }
-        const sql = this.operationToSql(operation);
-        if (sql) {
-            for (const statement of splitSqlStatements(sql)) {
-                await this.querier.run(statement);
-            }
-        }
-    }
-    operationToSql(operation) {
-        switch (operation.type) {
-            case 'createTable':
-                // One line per statement in preview; execute() runs each separately (#87).
-                return this.getCreateTableStatements(operation).join('\n');
-            case 'dropTable':
-                return this.sqlGenerator.generateDropTable(operation.tableName, {
-                    ifExists: operation.ifExists,
-                    cascade: operation.cascade,
-                });
-            case 'renameTable':
-                return this.sqlGenerator.generateRenameTableSql(operation.oldName, operation.newName);
-            case 'addColumn':
-                return this.sqlGenerator.generateAddColumnSql(operation.tableName, operation.column);
-            case 'dropColumn':
-                return this.sqlGenerator.generateDropColumnSql(operation.tableName, operation.columnName);
-            case 'renameColumn':
-                return this.sqlGenerator.generateRenameColumnSql(operation.tableName, operation.oldName, operation.newName);
-            case 'alterColumn':
-                return this.sqlGenerator.generateAlterColumnSql(operation.tableName, operation.columnName, operation.changes);
-            case 'createIndex':
-                return this.sqlGenerator.generateCreateIndexFromDefinition(operation.tableName, operation.index);
-            case 'dropIndex':
-                return this.sqlGenerator.generateDropIndex(operation.tableName, operation.indexName);
-            case 'addForeignKey':
-                return this.sqlGenerator.generateAddForeignKeySql(operation.tableName, operation.foreignKey);
-            case 'dropForeignKey':
-                return this.sqlGenerator.generateDropForeignKeySql(operation.tableName, operation.constraintName);
-            case 'raw':
-                return operation.sql;
-            default:
-                return undefined;
+        for (const statement of this.generator.generateOperation(operation)) {
+            await this.run(statement);
         }
     }
 }

package/dist/migrate/builder/types.d.ts

@@ -116,20 +116,10 @@ export interface TableDefinition {
     /** Table comment */
     comment?: string;
 }
-/**
- * Type of migration operation.
- */
-export type MigrationOperationType = 'createTable' | 'dropTable' | 'renameTable' | 'alterTable' | 'addColumn' | 'dropColumn' | 'alterColumn' | 'renameColumn' | 'createIndex' | 'dropIndex' | 'addForeignKey' | 'dropForeignKey' | 'raw';
-/**
- * Base migration operation.
- */
-export interface MigrationOperation {
-    type: MigrationOperationType;
-}
 /**
  * Create table operation.
  */
-export interface CreateTableOperation extends MigrationOperation {
+export interface CreateTableOperation {
     type: 'createTable';
     table: TableDefinition;
     ifNotExists?: boolean;
@@ -137,7 +127,7 @@ export interface CreateTableOperation extends MigrationOperation {
 /**
  * Drop table operation.
  */
-export interface DropTableOperation extends MigrationOperation {
+export interface DropTableOperation {
     type: 'dropTable';
     tableName: string;
     ifExists?: boolean;
@@ -146,7 +136,7 @@ export interface DropTableOperation extends MigrationOperation {
 /**
  * Rename table operation.
  */
-export interface RenameTableOperation extends MigrationOperation {
+export interface RenameTableOperation {
     type: 'renameTable';
     oldName: string;
     newName: string;
@@ -154,7 +144,7 @@ export interface RenameTableOperation extends MigrationOperation {
 /**
  * Add column operation.
  */
-export interface AddColumnOperation extends MigrationOperation {
+export interface AddColumnOperation {
     type: 'addColumn';
     tableName: string;
     column: FullColumnDefinition;
@@ -162,7 +152,7 @@ export interface AddColumnOperation extends MigrationOperation {
 /**
  * Drop column operation.
  */
-export interface DropColumnOperation extends MigrationOperation {
+export interface DropColumnOperation {
     type: 'dropColumn';
     tableName: string;
     columnName: string;
@@ -170,7 +160,7 @@ export interface DropColumnOperation extends MigrationOperation {
 /**
  * Alter column operation.
  */
-export interface AlterColumnOperation extends MigrationOperation {
+export interface AlterColumnOperation {
     type: 'alterColumn';
     tableName: string;
     columnName: string;
@@ -179,7 +169,7 @@ export interface AlterColumnOperation extends MigrationOperation {
 /**
  * Rename column operation.
  */
-export interface RenameColumnOperation extends MigrationOperation {
+export interface RenameColumnOperation {
     type: 'renameColumn';
     tableName: string;
     oldName: string;
@@ -188,7 +178,7 @@ export interface RenameColumnOperation extends MigrationOperation {
 /**
  * Create index operation.
  */
-export interface CreateIndexOperation extends MigrationOperation {
+export interface CreateIndexOperation {
     type: 'createIndex';
     tableName: string;
     index: IndexDefinition;
@@ -197,7 +187,7 @@ export interface CreateIndexOperation extends MigrationOperation {
 /**
  * Drop index operation.
  */
-export interface DropIndexOperation extends MigrationOperation {
+export interface DropIndexOperation {
     type: 'dropIndex';
     tableName: string;
     indexName: string;
@@ -206,7 +196,7 @@ export interface DropIndexOperation extends MigrationOperation {
 /**
  * Add foreign key operation.
  */
-export interface AddForeignKeyOperation extends MigrationOperation {
+export interface AddForeignKeyOperation {
     type: 'addForeignKey';
     tableName: string;
     foreignKey: ForeignKeySchema;
@@ -214,7 +204,7 @@ export interface AddForeignKeyOperation extends MigrationOperation {
 /**
  * Drop foreign key operation.
  */
-export interface DropForeignKeyOperation extends MigrationOperation {
+export interface DropForeignKeyOperation {
     type: 'dropForeignKey';
     tableName: string;
     constraintName: string;
@@ -222,7 +212,7 @@ export interface DropForeignKeyOperation extends MigrationOperation {
 /**
  * Raw SQL operation (escape hatch).
  */
-export interface RawSqlOperation extends MigrationOperation {
+export interface RawSqlOperation {
     type: 'raw';
     sql: string;
 }
@@ -387,7 +377,7 @@ export interface IAlterTableBuilder {
  * Interface for the main migration builder.
  */
 export interface IMigrationBuilder {
-    /** Create a new table */
+    /** Create a table as `callback` declares it; on MongoDB a collection, whose callback declares only indexes. */
     createTable(name: string, callback: (table: ITableBuilder) => void): Promise<void>;
     /** Drop a table */
     dropTable(name: string, options?: {
@@ -420,6 +410,6 @@ export interface IMigrationBuilder {
     }): Promise<void>;
     /** Drop a foreign key */
     dropForeignKey(tableName: string, constraintName: string): Promise<void>;
-    /** Execute raw SQL */
+    /** Execute raw SQL, the escape hatch for anything the builder does not model. */
     raw(sql: string): Promise<void>;
 }

package/dist/migrate/cli.d.ts

@@ -1,11 +1,6 @@
 #!/usr/bin/env node
-import type { ForeignKeyAction } from '../schema/types.js';
-import type { Config, MigratorDialect } from '../type/index.js';
+import type { Config } from '../type/index.js';
 import { Migrator } from './migrator.js';
-import { createSchemaGeneratorAsync } from './schemaGeneratorAsync.js';
-/** Sync helper for SQL dialects only; returns `undefined` for MongoDB - use {@link createSchemaGeneratorAsync}. */
-export declare function getSchemaGenerator(dialect: MigratorDialect, defaultForeignKeyAction?: ForeignKeyAction): import("./schemaGenerator.js").SqlSchemaGenerator | undefined;
-export { createSchemaGeneratorAsync };
 export declare function main(args?: string[]): Promise<void>;
 export declare function runUp(migrator: Migrator, args: string[]): Promise<void>;
 export declare function runDown(migrator: Migrator, args: string[]): Promise<void>;
@@ -19,5 +14,5 @@ export declare function runGenerateFromEntities(migrator: Migrator, args: string
  */
 export declare function runTypes(migrator: Migrator, args: string[]): void;
 export declare function runSync(migrator: Migrator, args: string[], config: Partial<Config>): Promise<void>;
-export declare function runGenerateFromDb(migrator: Migrator, args: string[], config: Partial<Config>): Promise<void>;
+export declare function runGenerateFromDb(migrator: Migrator, args: string[]): Promise<void>;
 export declare function runDriftCheck(migrator: Migrator, config: Partial<Config>): Promise<void>;