uql-orm 0.42.1 → 0.43.0

package/dist/entity/metadata/definition.js

@@ -1,5 +1,5 @@
 import { SOFT_DELETE_FILTER } from '../../type/index.js';
-import { getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
+import { fieldOptionConflict, getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 // Held on `globalThis` via the global symbol registry so a single metadata map survives multiple
 // evaluations of this module (HMR, duplicated/federated bundles, ESM+CJS dual-loading). Version-suffixed
@@ -10,11 +10,15 @@ const metaKey = Symbol.for('uql-orm/entity/metadata/v1');
 const metas = holder[metaKey] ?? new Map();
 holder[metaKey] = metas;
 export function defineField(entity, key, opts = {}) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (!opts.type && !opts.references && !opts.virtual) {
         throw new TypeError(`'${entity.name}.${key}' needs a 'type'. Declare it - '@Field({ type: String })' - or point the field ` +
             "at another entity with 'references', which resolves the column type from its primary key.");
     }
+    const conflict = fieldOptionConflict(opts);
+    if (conflict) {
+        throw new TypeError(`'${entity.name}.${key}' ${conflict}.`);
+    }
     const fieldKey = key;
     // Flagged when the author gave `references` but no `type`, so schema generation knows to resolve the
     // column from the referenced primary key (picking up its `columnType`, length and chained keys)
@@ -32,7 +36,7 @@ export function defineRelation(entity, key, opts) {
     if (!opts.entity) {
         throw new TypeError(`'${entity.name}.${key}' needs an 'entity' getter, e.g. '@ManyToOne({ entity: () => Company })'.`);
     }
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     // Registration writes the authored shape into a map declared as resolved: `getMeta` runs
     // `fillRelations`, which settles `entity`, `references` and `mappedBy` or throws. Bridging the two
     // shapes here is what lets every consumer read `RelationMeta` without asserting.
@@ -41,7 +45,7 @@ export function defineRelation(entity, key, opts) {
     return meta;
 }
 export function defineHook(entity, methodName, event) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (!meta.hooks)
         meta.hooks = {};
     if (!meta.hooks[event])
@@ -54,7 +58,7 @@ export function defineHook(entity, methodName, event) {
  * lets the dialects render one shape instead of re-parsing it.
  */
 export function defineIndex(entity, index) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (!meta.indexes)
         meta.indexes = [];
     meta.indexes.push({
@@ -66,7 +70,7 @@ export function defineIndex(entity, index) {
     return meta;
 }
 export function defineFilter(entity, name, opts) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (name === SOFT_DELETE_FILTER) {
         throw TypeError(`'${entity.name}' filter name '${SOFT_DELETE_FILTER}' is reserved; it is auto-registered from @Field({ softDelete })`);
     }
@@ -112,7 +116,7 @@ export function defineEntity(entity, opts = {}) {
         throw new TypeError(`'${entity.name}' has a dotted name '${opts.name}'. Name the schema separately as ` +
             `{ schema: '${schema}', name: '${rest.join('.')}' }.`);
     }
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     // Covers `defineEntity(Decorated)` called on a class whose members carry decorators. `@Entity()`
     // drains `context.metadata` itself, because TypeScript only attaches `Symbol.metadata` to the class
     // after class decorators return; draining empties the bag, so whichever runs second is a no-op.
@@ -132,8 +136,9 @@ export function defineEntity(entity, opts = {}) {
     if (!hasKeys(meta.fields)) {
         throw TypeError(`'${entity.name}' must have fields`);
     }
-    meta.name = opts.name ?? entity.name;
-    meta.schema = opts.schema;
+    // A later call composes onto the entity, so saying nothing about the table retracts nothing.
+    meta.name = opts.name ?? meta.name ?? entity.name;
+    meta.schema = opts.schema ?? meta.schema;
     let proto = Object.getPrototypeOf(entity.prototype);
     while (proto.constructor !== Object) {
         const parent = proto.constructor;
@@ -211,12 +216,21 @@ export function getEntities() {
         return acc;
     }, []);
 }
+/**
+ * The metadata of `entity`, marked as changed. Every `define*` goes through this, and nothing outside
+ * this file writes to a meta, so it is the one place a derived cache can be told it has gone stale.
+ */
+function ensureWritableMeta(entity) {
+    const meta = ensureMeta(entity);
+    meta.revision++;
+    return meta;
+}
 function ensureMeta(entity) {
     let meta = metas.get(entity);
     if (meta) {
         return meta;
     }
-    meta = { entity, ids: [], fields: {}, relations: {} };
+    meta = { entity, ids: [], fields: {}, relations: {}, revision: 0 };
     metas.set(entity, meta);
     return meta;
 }
@@ -225,10 +239,13 @@ export function getMeta(entity) {
     if (!meta) {
         throw TypeError(`'${entity.name}' is not an entity`);
     }
-    if (meta.processed) {
+    if (meta.processedAt === meta.revision) {
         return meta;
     }
-    meta.processed = true;
+    // 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.
+    meta.processedAt = meta.revision;
     return fillRelations(meta);
 }
 function fillRelations(meta) {

package/dist/maria/mariaDialect.js

@@ -1,7 +1,7 @@
 import { jsonPath } from '../dialect/jsonSql.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import { isVectorFieldType } from '../dialect/vectorCast.js';
 import { getMeta } from '../entity/index.js';
+import { columnFamily } from '../util/field.util.js';
 import { MARIA_VECTOR_METRICS } from './mariaVectorMetrics.js';
 export class MariaDialect extends MysqlLikeSqlDialect {
     dialectName = 'mariadb';
@@ -76,6 +76,6 @@ export class MariaDialect extends MysqlLikeSqlDialect {
     }
     /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
     selectFieldExpr(escapedColumn, field) {
-        return isVectorFieldType(field.type) ? `VEC_ToText(${escapedColumn})` : escapedColumn;
+        return columnFamily(field.type) === 'vector' ? `VEC_ToText(${escapedColumn})` : escapedColumn;
     }
 }

package/dist/migrate/drift/driftDetector.js

@@ -4,7 +4,7 @@
  * Detects schema drift between expected schema (from entities) and
  * actual database schema.
  */
-import { canonicalToSql } from '../../schema/canonicalType.js';
+import { canonicalToSql, engineType } from '../../schema/canonicalType.js';
 import { diffSchemas } from '../../schema/schemaASTDiffer.js';
 function resolveOptions(options) {
     return {
@@ -24,11 +24,15 @@ function resolveOptions(options) {
  */
 export function detectDrift(expectedAST, actualAST, options = {}) {
     const opts = resolveOptions(options);
+    const { dialect } = opts;
     const diff = diffSchemas(expectedAST, actualAST, {
         compareIndexes: opts.checkIndexes,
         indexFacets: opts.indexFacets,
         compareRelationships: opts.checkForeignKeys,
         excludeTables: opts.excludeTables,
+        // Without a dialect there is no engine to compare through, and `formatType` below then reports no
+        // type drift at all.
+        ...(dialect && { normalizeType: engineType(dialect) }),
     });
     const drifts = [
         ...detectTableDrifts(diff),

package/dist/migrate/generator/mongoSchemaGenerator.d.ts

@@ -39,7 +39,7 @@ export declare class MongoSchemaGenerator extends AbstractDialect implements Sch
      */
     generateCreateIndex(tableName: string, index: IndexSchema): string;
     generateDropIndex(tableName: string, indexName: string): string;
-    getSqlType(fieldOptions: FieldOptions, fieldType?: unknown): string;
+    getSqlType(fieldOptions: FieldOptions): string;
     generateCreateTableFromNode(table: TableNode, _options?: {
         ifNotExists?: boolean;
     }): string[];

package/dist/migrate/generator/mongoSchemaGenerator.js

@@ -120,7 +120,7 @@ export class MongoSchemaGenerator extends AbstractDialect {
             name: indexName,
         });
     }
-    getSqlType(fieldOptions, fieldType) {
+    getSqlType(fieldOptions) {
         return '';
     }
     generateCreateTableFromNode(table, _options) {

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;
 /**

package/dist/schema/canonicalType.js

@@ -6,6 +6,7 @@
  * - Canonical types (dialect-agnostic)
  * - TypeScript types (for entity generation)
  */
+import { columnFamily } from '../util/field.util.js';
 /** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
 export function isVectorCategory(category) {
     return category === 'vector' || category === 'halfvec' || category === 'sparsevec';
@@ -108,66 +109,57 @@ const PG_TYPE_MAP = {
     halfvec: 'HALFVEC',
     sparsevec: 'SPARSEVEC',
 };
+const MYSQL_SCALAR_MAP = {
+    integer: 'INT',
+    float: 'FLOAT',
+    decimal: 'DECIMAL',
+    string: 'VARCHAR',
+    boolean: 'TINYINT(1)',
+    date: 'DATE',
+    time: 'TIME',
+    timestamp: 'DATETIME',
+    json: 'JSON',
+    uuid: 'CHAR(36)',
+    blob: 'BLOB',
+};
+const SQLITE_SCALAR_MAP = {
+    integer: 'INTEGER',
+    float: 'REAL',
+    decimal: 'REAL',
+    string: 'TEXT',
+    boolean: 'INTEGER',
+    date: 'TEXT',
+    time: 'TEXT',
+    timestamp: 'TEXT',
+    json: 'TEXT',
+    uuid: 'TEXT',
+    blob: 'BLOB',
+};
+/** MongoDB uses BSON types, not SQL types. These are placeholders for compatibility. */
+const MONGO_SCALAR_MAP = {
+    integer: 'int',
+    float: 'double',
+    decimal: 'decimal128',
+    string: 'string',
+    boolean: 'bool',
+    date: 'date',
+    time: 'string',
+    timestamp: 'timestamp',
+    json: 'object',
+    uuid: 'binData',
+    blob: 'binData',
+};
+/** Every engine's scalars, and the one spelling it gives all three vector widths. */
 const CANONICAL_TO_SQL = {
     postgres: PG_TYPE_MAP,
     // CockroachDB's VECTOR is native, no extension needed.
     cockroachdb: withVectorType(PG_SCALAR_MAP, 'VECTOR'),
-    mysql: withVectorType({
-        integer: 'INT',
-        float: 'FLOAT',
-        decimal: 'DECIMAL',
-        string: 'VARCHAR',
-        boolean: 'TINYINT(1)',
-        date: 'DATE',
-        time: 'TIME',
-        timestamp: 'DATETIME',
-        json: 'JSON',
-        uuid: 'CHAR(36)',
-        blob: 'BLOB',
-    }, 
     // MySQL does have a `VECTOR` type (26.7), but no distance function outside HeatWave and no vector
     // index, so JSON keeps the column queryable with the JSON operators and needs no conversion.
-    'JSON'),
-    sqlite: withVectorType({
-        integer: 'INTEGER',
-        float: 'REAL',
-        decimal: 'REAL',
-        string: 'TEXT',
-        boolean: 'INTEGER',
-        date: 'TEXT',
-        time: 'TEXT',
-        timestamp: 'TEXT',
-        json: 'TEXT',
-        uuid: 'TEXT',
-        blob: 'BLOB',
-    }, 'TEXT'),
-    mariadb: withVectorType({
-        integer: 'INT',
-        float: 'FLOAT',
-        decimal: 'DECIMAL',
-        string: 'VARCHAR',
-        boolean: 'TINYINT(1)',
-        date: 'DATE',
-        time: 'TIME',
-        timestamp: 'DATETIME',
-        json: 'JSON',
-        uuid: 'CHAR(36)',
-        blob: 'BLOB',
-    }, 'VECTOR'),
-    // MongoDB uses BSON types, not SQL types. These are placeholders for compatibility.
-    mongodb: withVectorType({
-        integer: 'int',
-        float: 'double',
-        decimal: 'decimal128',
-        string: 'string',
-        boolean: 'bool',
-        date: 'date',
-        time: 'string',
-        timestamp: 'timestamp',
-        json: 'object',
-        uuid: 'binData',
-        blob: 'binData',
-    }, 'array'),
+    mysql: withVectorType(MYSQL_SCALAR_MAP, 'JSON'),
+    mariadb: withVectorType(MYSQL_SCALAR_MAP, 'VECTOR'),
+    sqlite: withVectorType(SQLITE_SCALAR_MAP, 'TEXT'),
+    mongodb: withVectorType(MONGO_SCALAR_MAP, 'array'),
 };
 /**
  * Size variant modifiers for SQL types.
@@ -239,7 +231,7 @@ const CANONICAL_TO_TS = {
     timestamp: 'Date',
     json: 'unknown',
     uuid: 'string',
-    blob: 'Buffer',
+    blob: 'Uint8Array',
     vector: 'number[]',
     halfvec: 'number[]',
     sparsevec: 'number[]',
@@ -387,136 +379,94 @@ function formatDecimalSqlType(type, dialect, baseType) {
 export function canonicalToTypeScript(type) {
     return CANONICAL_TO_TS[type.category];
 }
+/**
+ * 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 function engineType(dialect) {
+    return (type) => sqlToCanonical(canonicalToSql(type, dialect));
+}
 /**
  * Convert UQL FieldOptions to a canonical type.
  */
-export function fieldOptionsToCanonical(options, tsType) {
-    // If explicit columnType is specified, use it
+export function fieldOptionsToCanonical(options) {
+    // An explicit column type is read exactly as an introspected one is: the SQL type, plus whatever
+    // bounds are stated beside it.
     if (options.columnType) {
-        const base = sqlToCanonical(options.columnType);
-        return {
-            ...base,
-            length: options.length ?? base.length,
-            precision: options.precision ?? base.precision,
-            scale: options.scale ?? base.scale,
-        };
-    }
-    // Infer from type (could be constructor or string)
-    const type = options.type || tsType;
-    if (type === String) {
-        return {
-            category: 'string',
-            length: options.length,
-        };
-    }
-    if (type === Number) {
-        if (options.precision || options.scale) {
-            return {
-                category: 'decimal',
-                precision: options.precision,
-                scale: options.scale,
-            };
-        }
-        // BIGINT for every `Number`, key or not: a 32-bit column is a migration waiting to happen, and
-        // the pools decode it back to a JS number at the wire (see `pgNumericTypes`).
-        return { category: 'integer', size: 'big' };
-    }
-    if (type === Boolean) {
-        return { category: 'boolean' };
-    }
-    if (type === Date) {
-        return { category: 'timestamp' };
-    }
-    if (type === BigInt) {
-        return { category: 'integer', size: 'big' };
+        return canonicalColumnType(options.columnType, options);
     }
+    // Infer from type, which is a SQL type string or one of the constructors.
+    const { type } = options;
     if (typeof type === 'string') {
         const canonical = sqlToCanonical(type);
         // Propagate explicit dimensions into CanonicalType.length for vector types
-        if (options.dimensions && isVectorCategory(canonical.category)) {
-            return { ...canonical, length: options.dimensions };
-        }
-        return canonical;
+        return options.dimensions && isVectorCategory(canonical.category)
+            ? { ...canonical, length: options.dimensions }
+            : canonical;
+    }
+    switch (columnFamily(type)) {
+        case 'numeric':
+            // BIGINT for every `Number` without a scale, key or not: a 32-bit column is a migration waiting
+            // to happen, and the pools decode it back to a JS number at the wire (see `pgNumericTypes`).
+            return type === Number && (options.precision || options.scale)
+                ? { category: 'decimal', precision: options.precision, scale: options.scale }
+                : { category: 'integer', size: 'big' };
+        case 'boolean':
+            return { category: 'boolean' };
+        case 'date':
+            return { category: 'timestamp' };
+        // `String`, and anything a reflected type left unrecognised.
+        default:
+            return { category: 'string', length: options.length };
     }
-    // Default to string
-    return { category: 'string', length: options.length };
 }
 /**
- * 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 function areTypesEqual(a, b) {
-    // Category must match
-    if (a.category !== b.category) {
-        return false;
-    }
-    // Size must match (if specified)
-    if (a.size !== b.size) {
-        return false;
-    }
-    // For strings, compare length (allowing for default 255)
-    if (a.category === 'string') {
-        const lengthA = a.length ?? 255;
-        const lengthB = b.length ?? 255;
-        if (lengthA !== lengthB) {
-            return false;
-        }
-    }
-    // For decimals, compare precision and scale (allowing for default 10, 2)
-    if (a.category === 'decimal') {
-        const pA = a.precision ?? 10;
-        const pB = b.precision ?? 10;
-        const sA = a.scale ?? 2;
-        const sB = b.scale ?? 2;
-        if (pA !== pB || sA !== sB) {
-            return false;
-        }
-    }
-    // For timestamps, compare timezone
-    if (a.category === 'timestamp') {
-        if (!!a.withTimezone !== !!b.withTimezone) {
-            return false;
-        }
-    }
-    // Unsigned must match
-    if (!!a.unsigned !== !!b.unsigned) {
-        return false;
-    }
-    return true;
+    return (a.category === b.category &&
+        a.size === b.size &&
+        a.length === b.length &&
+        a.precision === b.precision &&
+        a.scale === b.scale &&
+        !!a.withTimezone === !!b.withTimezone &&
+        !!a.unsigned === !!b.unsigned);
 }
 /**
- * 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 function isBreakingTypeChange(from, to) {
-    // Changing category is always potentially breaking
     if (from.category !== to.category) {
         return true;
     }
-    // Reducing size is breaking
-    const sizeOrder = ['tiny', 'small', 'medium', 'big'];
-    if (from.size && to.size) {
-        const fromIndex = sizeOrder.indexOf(from.size);
-        const toIndex = sizeOrder.indexOf(to.size);
-        if (toIndex < fromIndex) {
-            return true;
-        }
-    }
-    // Reducing string length is breaking
-    if (from.category === 'string' && from.length && to.length) {
-        if (to.length < from.length) {
-            return true;
-        }
-    }
-    // Reducing precision/scale is breaking
-    if (from.category === 'decimal') {
-        if (from.precision && to.precision && to.precision < from.precision) {
-            return true;
-        }
-        if (from.scale && to.scale && to.scale < from.scale) {
-            return true;
-        }
+    // Only where both state a size: an unsized member of a family is the engine's base type, wider than
+    // `tiny` and narrower than `big`, and which of those it is depends on a family this does not know.
+    if (from.size && to.size && SIZE_ORDER.indexOf(to.size) < SIZE_ORDER.indexOf(from.size)) {
+        return true;
     }
-    return false;
+    return (narrows(from.length, to.length) ||
+        narrows(from.precision, to.precision) ||
+        narrows(from.scale, to.scale) ||
+        // Either direction drops half the range: signed loses the top bit, unsigned the negatives.
+        !!from.unsigned !== !!to.unsigned ||
+        // An offset the column stops keeping cannot be recovered from what is left.
+        (!!from.withTimezone && !to.withTimezone));
+}
+const SIZE_ORDER = ['tiny', 'small', 'medium', 'big'];
+/** A bound narrowed, where an unstated one is unbounded. */
+function narrows(from, to) {
+    return to !== undefined && (from === undefined || to < from);
 }
 /**
  * Get the UQL ColumnType that best matches a canonical type.

package/dist/schema/schemaASTBuilder.js

@@ -65,7 +65,7 @@ function resolveColumnCanonicalType(field, seen = new Set()) {
             return resolveColumnCanonicalType(referencedIdField, seen);
         }
     }
-    return fieldOptionsToCanonical(field, field.type);
+    return fieldOptionsToCanonical(field);
 }
 /**
  * Add a table from entity metadata.

package/dist/schema/schemaASTDiffer.js

@@ -175,7 +175,8 @@ function diffColumn(tableName, source, target, opts) {
     // key column" rule these two replace used to hide.
     const generatedType = source.isAutoIncrement && target.isAutoIncrement;
     const impliedNotNull = source.isPrimaryKey && target.isPrimaryKey;
-    if (!generatedType && !areTypesEqual(opts.normalizeType(source.type), opts.normalizeType(target.type))) {
+    const typeChanged = !generatedType && !areTypesEqual(opts.normalizeType(source.type), opts.normalizeType(target.type));
+    if (typeChanged) {
         differences.push(`type: ${formatType(source.type)} → ${formatType(target.type)}`);
     }
     if (!impliedNotNull && source.nullable !== target.nullable) {
@@ -202,7 +203,10 @@ function diffColumn(tableName, source, target, opts) {
         type: 'alter',
         expected: source,
         actual: target,
-        isBreaking: isBreakingTypeChange(target.type, source.type),
+        // Only the type this diff actually reports: a column altered for its default carries no data loss,
+        // and a generated key's type - never compared above - reads as unsigned against an entity that
+        // cannot say so.
+        isBreaking: typeChanged && isBreakingTypeChange(target.type, source.type),
         description: differences.join(', '),
     };
 }