uql-orm 0.42.1 → 0.44.0

package/dist/migrate/migrator.d.ts

@@ -1,4 +1,4 @@
-import type { DialectName, LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorOptions, MongoQuerier, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, Type } from '../type/index.js';
+import type { DialectName, LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorOptions, MongoQuerier, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SyncOptions, Type } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 import type { IMigrationBuilder } from './builder/types.js';
 /**
@@ -88,31 +88,45 @@ export declare class Migrator {
     private introspectClaimedSchemas;
     findEntityForTable(tableName: string): Promise<Type<unknown> | undefined>;
     /**
-     * Sync schema directly (for development only - not for production!)
-     */
-    sync(options?: {
-        force?: boolean;
-    }): Promise<void>;
-    /**
-     * Drops and recreates all tables (Development only!)
+     * Applies the entity schema to the database: every registered entity, or the one `entity` names.
+     *
+     * The whole surface is this and {@link planSync}, which answers the same question without running
+     * it - `force` and a single entity included, so `--dry-run` means the same thing whatever else was
+     * asked for.
      */
-    syncForce(): Promise<void>;
+    sync(options?: SyncOptions): Promise<void>;
     /**
-     * Safely synchronizes the schema by only adding missing tables and columns.
+     * Every table dropped and recreated.
+     *
+     * Both directions span the whole entity set rather than looping an entity at a time. A per-entity
+     * AST cannot resolve a cross-entity foreign key, so the old create loop silently produced a schema
+     * with no referential integrity; and the old drop loop went in reverse *declaration* order, which
+     * says nothing about the relation graph and is rejected as soon as the constraints are really there.
      */
-    autoSync(options?: {
-        safe?: boolean;
-        drop?: boolean;
-        logging?: boolean;
-    }): Promise<void>;
+    private forceStatements;
     /**
-     * The DDL {@link autoSync} would run, without running it. Separate so `--dry-run` shows the real
+     * Sync one entity, for a schema that grows while the process runs: a content type an admin just
+     * created is one table to add, where the whole set would read the catalogue to work that out.
+     *
+     * The new-table case costs one existence check and creates with `IF NOT EXISTS`, so instances racing
+     * the same admin save settle instead of colliding. An existing table still pays for introspection,
+     * since a column diff needs the columns.
+     */
+    /** The DDL for one entity: {@link planSync} narrowed to the table it names. */
+    private planEntity;
+    /** An alter diff as statements, narrowed to what the caller allows. */
+    private alterFromDiff;
+    /** The same for one entity against the table it already has, and nothing where the two agree. */
+    private alterFromEntity;
+    /** The configured entities, with `entity` among them however the migrator was built. */
+    private entitiesWith;
+    /** The introspector for a claimed schema, which is the connection's own where none is claimed. */
+    private introspectorFor;
+    /**
+     * The DDL {@link sync} would run, without running it. Separate so `--dry-run` shows the real
      * statements rather than a summary of a second, differently-computed diff.
      */
-    planSync(options?: {
-        safe?: boolean;
-        drop?: boolean;
-    }): Promise<string[]>;
+    planSync(options?: SyncOptions): Promise<string[]>;
     /**
      * New tables are emitted together, never one at a time: a single-entity AST has no other table for a
      * relation to resolve against, so every cross-entity foreign key was dropped and generated schemas

package/dist/migrate/migrator.js

@@ -305,7 +305,7 @@ export class Migrator {
         const claimed = new Set(this.entities.map((entity) => this.pool.dialect.resolveSchema(getMeta(entity))));
         const merged = new SchemaAST();
         for (const schema of claimed) {
-            const introspector = schema === undefined ? this.schemaIntrospector : this.createIntrospector(schema);
+            const introspector = this.introspectorFor(schema);
             if (!introspector) {
                 continue;
             }
@@ -330,52 +330,90 @@ export class Migrator {
         return undefined;
     }
     /**
-     * Sync schema directly (for development only - not for production!)
+     * Applies the entity schema to the database: every registered entity, or the one `entity` names.
+     *
+     * The whole surface is this and {@link planSync}, which answers the same question without running
+     * it - `force` and a single entity included, so `--dry-run` means the same thing whatever else was
+     * asked for.
      */
     async sync(options = {}) {
-        if (options.force) {
-            return this.syncForce();
+        const statements = await this.planSync(options);
+        if (statements.length) {
+            await this.executeSyncStatements(statements, options);
+        }
+        else if (options.logging) {
+            this.logger.logSchema('Schema is already in sync.');
         }
-        return this.autoSync({ safe: true });
     }
     /**
-     * Drops and recreates all tables (Development only!)
+     * Every table dropped and recreated.
+     *
+     * Both directions span the whole entity set rather than looping an entity at a time. A per-entity
+     * AST cannot resolve a cross-entity foreign key, so the old create loop silently produced a schema
+     * with no referential integrity; and the old drop loop went in reverse *declaration* order, which
+     * says nothing about the relation graph and is rejected as soon as the constraints are really there.
      */
-    async syncForce() {
-        await this.ensureSchemaGenerator();
-        // Both directions span the whole entity set rather than looping an entity at a time. A per-entity
-        // AST cannot resolve a cross-entity foreign key, so the old create loop silently produced a schema
-        // with no referential integrity; and the old drop loop went in reverse *declaration* order, which
-        // says nothing about the relation graph and is rejected as soon as the constraints are really there.
-        const statements = [
+    forceStatements() {
+        return [
             ...this.generator.generateDropSchema(this.entities, { ifExists: true, cascade: true }),
             ...this.generator.generateCreateSchema(this.entities),
         ];
-        await withSqlQuerierForMigrations(this.pool, 'Migrator', (querier) => querier.transaction(async () => {
-            for (const sql of statements) {
-                this.logger.logSchema(`Executing: ${sql}`);
-                await querier.run(sql);
-            }
-        }));
-        this.logger.logSchema('Schema sync (force) completed');
     }
     /**
-     * Safely synchronizes the schema by only adding missing tables and columns.
+     * Sync one entity, for a schema that grows while the process runs: a content type an admin just
+     * created is one table to add, where the whole set would read the catalogue to work that out.
+     *
+     * The new-table case costs one existence check and creates with `IF NOT EXISTS`, so instances racing
+     * the same admin save settle instead of colliding. An existing table still pays for introspection,
+     * since a column diff needs the columns.
      */
-    async autoSync(options = {}) {
-        const statements = await this.planSync(options);
-        if (statements.length === 0) {
-            if (options.logging)
-                this.logger.logSchema('Schema is already in sync.');
-            return;
+    /** The DDL for one entity: {@link planSync} narrowed to the table it names. */
+    async planEntity(entity, options) {
+        const meta = getMeta(entity);
+        // Before anything reads `this.generator`, whose own failure names neither the entity nor the
+        // dialect that has no support.
+        const introspector = this.introspectorFor(this.pool.dialect.resolveSchema(meta));
+        if (!introspector) {
+            throw new TypeError(`No introspector for '${meta.entity.name}' on '${this.dialectName}'`);
         }
-        await this.executeSyncStatements(statements, options);
+        const tableName = this.generator.resolveTableName(meta);
+        return (await introspector.tableExists(tableName))
+            ? this.alterFromEntity(entity, (await introspectSchema(introspector)).getTable(tableName), options)
+            : // Spanning the whole set, so a foreign key resolves against the tables it points at, and
+                // always including this entity: pinned to an explicit `entities` list, a sync of one outside
+                // it emitted nothing at all. `only` is what keeps the statements to this table.
+                this.generator.generateCreateSchema(this.entitiesWith(entity), { only: [tableName], ifNotExists: true });
+    }
+    /** An alter diff as statements, narrowed to what the caller allows. */
+    alterFromDiff(diff, options) {
+        return this.generator.generateAlterTable(this.filterDiff(diff, options));
+    }
+    /** The same for one entity against the table it already has, and nothing where the two agree. */
+    alterFromEntity(entity, table, options) {
+        const diff = this.generator.diffSchema(entity, table);
+        return diff?.type === 'alter' ? this.alterFromDiff(diff, options) : [];
+    }
+    /** The configured entities, with `entity` among them however the migrator was built. */
+    entitiesWith(entity) {
+        const entities = this.entities;
+        return entities.includes(entity) ? entities : [...entities, entity];
+    }
+    /** The introspector for a claimed schema, which is the connection's own where none is claimed. */
+    introspectorFor(schema) {
+        return schema === undefined ? this.schemaIntrospector : this.createIntrospector(schema);
     }
     /**
-     * The DDL {@link autoSync} would run, without running it. Separate so `--dry-run` shows the real
+     * The DDL {@link sync} would run, without running it. Separate so `--dry-run` shows the real
      * statements rather than a summary of a second, differently-computed diff.
      */
     async planSync(options = {}) {
+        await this.ensureSchemaGenerator();
+        if (options.force) {
+            return this.forceStatements();
+        }
+        if (options.entity) {
+            return this.planEntity(options.entity, options);
+        }
         const creating = [];
         const altering = [];
         for (const { diff, entity } of await this.pendingDiffs()) {
@@ -384,7 +422,7 @@ export class Migrator {
                     creating.push(diff.tableName);
             }
             else if (diff.type === 'alter') {
-                altering.push(...this.generator.generateAlterTable(this.filterDiff(diff, options)));
+                altering.push(...this.alterFromDiff(diff, options));
             }
         }
         return [...this.createSchema(creating), ...altering];
@@ -452,10 +490,15 @@ export class Migrator {
         return filteredDiff;
     }
     async executeSyncStatements(statements, options) {
-        // Mongo creates collections and indexes outside any transaction, so only the SQL path opens one.
-        await withQuerierForMigrations(this.pool, (querier) => this.dialectName === 'mongodb'
-            ? this.executeMongoSyncStatements(statements, options, querier)
-            : querier.transaction(() => this.executeSqlSyncStatements(statements, options, querier)));
+        // Mongo creates collections and indexes outside any transaction, so only the SQL path opens one -
+        // and asks for a SQL querier before it opens it, since `transaction` is what a Mongo one lacks and
+        // reaching for it first reports that instead of which querier the dialect needs.
+        if (this.dialectName === 'mongodb') {
+            await withQuerierForMigrations(this.pool, (querier) => this.executeMongoSyncStatements(statements, options, querier));
+        }
+        else {
+            await withSqlQuerierForMigrations(this.pool, 'Migrator', (querier) => querier.transaction(() => this.executeSqlSyncStatements(statements, options, querier)));
+        }
         if (options.logging)
             this.logger.logSchema('Schema synchronization completed');
     }

package/dist/migrate/schemaGenerator.d.ts

@@ -27,10 +27,6 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      * Primary key type for auto-increment integer IDs
      */
     protected get serialType(): string;
-    /**
-     * Convert FieldOptions to CanonicalType using the unified type system.
-     */
-    protected getCanonicalType(field: FieldOptions, fieldType?: unknown): CanonicalType;
     protected canonicalTypeToSql(type: CanonicalType): string;
     /**
      * Every `CREATE TABLE` for `entities`, then their foreign keys.
@@ -85,7 +81,7 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     /** ` DEFAULT <sql>`, or nothing where the column declares none. Empty rather than `DEFAULT NULL`
      * so an absent default stays absent - `defaultValue: null` is the way to ask for one. */
     private defaultClause;
-    getSqlType(field: FieldMeta, fieldType?: unknown, isSoleKey?: boolean): string;
+    getSqlType(field: FieldMeta): string;
     /**
      * Generate ALTER COLUMN statements (database-specific)
      */

package/dist/migrate/schemaGenerator.js

@@ -1,6 +1,6 @@
 import { AbstractSqlDialect } from '../dialect/index.js';
 import { getMeta, soleIdOf } from '../entity/index.js';
-import { areTypesEqual, canonicalToSql, fieldOptionsToCanonical, isVectorCategory, sqlToCanonical, } from '../schema/canonicalType.js';
+import { areTypesEqual, canonicalToSql, engineType, fieldOptionsToCanonical, isVectorCategory, } from '../schema/canonicalType.js';
 import { indexSignature } from '../schema/indexDifferences.js';
 import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
 import { diffTable } from '../schema/schemaASTDiffer.js';
@@ -52,12 +52,6 @@ export class SqlSchemaGenerator {
     get serialType() {
         return this.dialect.serialType;
     }
-    /**
-     * Convert FieldOptions to CanonicalType using the unified type system.
-     */
-    getCanonicalType(field, fieldType) {
-        return fieldOptionsToCanonical(field, fieldType);
-    }
     canonicalTypeToSql(type) {
         return canonicalToSql(type, this.dialect);
     }
@@ -275,18 +269,20 @@ export class SqlSchemaGenerator {
             ? ''
             : ` DEFAULT ${formatDefaultValue(column.defaultValue, this.dialect, column.type)}`;
     }
-    getSqlType(field, fieldType, isSoleKey = field.isId === true) {
-        // If field has a reference, inherit type from the target primary key
+    getSqlType(field) {
+        // A foreign key takes the type of the key it points at. A `referencedKey` the target does not
+        // have falls through to this column's own options, as the AST builder does with the same case.
         if (field.references) {
-            const refEntity = field.references();
-            const refMeta = getMeta(refEntity);
+            const refMeta = getMeta(field.references());
             const refIdField = refMeta.fields[field.referencedKey ?? soleIdOf(refMeta, 'a foreign key')];
-            return this.getSqlType({ ...refIdField, references: undefined, isId: undefined, autoIncrement: false }, refIdField.type);
+            if (refIdField) {
+                return this.getSqlType({ ...refIdField, references: undefined, isId: undefined, autoIncrement: false });
+            }
         }
         // Get canonical type and convert to SQL
-        const canonical = this.getCanonicalType(field, fieldType);
+        const canonical = fieldOptionsToCanonical(field);
         // Special case for serial primary keys
-        if (isAutoIncrement(field, isSoleKey)) {
+        if (isAutoIncrement(field, field.isId === true)) {
             return this.dialect.serialType;
         }
         return this.canonicalTypeToSql(canonical);
@@ -408,7 +404,7 @@ export class SqlSchemaGenerator {
     }
     diffOptions() {
         return {
-            normalizeType: (type) => sqlToCanonical(this.canonicalTypeToSql(type)),
+            normalizeType: engineType(this.dialect),
             defaultsEqual: (expected, actual) => this.isDefaultValueEqual(actual, expected),
         };
     }

package/dist/schema/canonicalType.d.ts

@@ -36,17 +36,32 @@ export declare function canonicalToSql(type: CanonicalType, dialect: AbstractDia
  * Convert a canonical type to a TypeScript type string.
  */
 export declare function canonicalToTypeScript(type: CanonicalType): string;
+/**
+ * A type as `dialect` would actually store it: rendered to that engine's SQL and read back.
+ *
+ * Several canonical types share one storage type per engine - a `boolean` is `TINYINT(1)` on MySQL and
+ * `INTEGER` on SQLite - and only the engine settles an unstated bound, since `VARCHAR` is 255 on MySQL
+ * and `TEXT` on Postgres. Both paths that diff a schema compare through this, so a migration and a
+ * drift report cannot disagree about what changed.
+ */
+export declare function engineType(dialect: AbstractDialect): (type: CanonicalType) => CanonicalType;
 /**
  * Convert UQL FieldOptions to a canonical type.
  */
-export declare function fieldOptionsToCanonical(options: FieldOptions, tsType?: unknown): CanonicalType;
+export declare function fieldOptionsToCanonical(options: FieldOptions): CanonicalType;
 /**
- * Compare two canonical types for equality.
- * Used for schema diffing.
+ * Compare two canonical types for equality. Used for schema diffing.
+ *
+ * Nothing here guesses an engine's own default for an unstated bound: `VARCHAR` is 255 on MySQL and
+ * `TEXT` on Postgres, and a comparison that assumed either was blind to that difference on the other.
+ * `DiffOptions.normalizeType` is what settles it, by putting both sides through the engine first.
  */
 export declare function areTypesEqual(a: CanonicalType, b: CanonicalType): boolean;
 /**
- * Check if changing from type A to type B could cause data loss.
+ * Whether changing a column from one type to the other can lose what it holds.
+ *
+ * An unstated bound is the engine's widest, so stating one for the first time narrows the column just
+ * as lowering one does: `TEXT` to `VARCHAR(50)` truncates, and `NUMERIC` to `NUMERIC(5,2)` rounds.
  */
 export declare function isBreakingTypeChange(from: CanonicalType, to: CanonicalType): boolean;
 /**