uql-orm 0.42.1 → 0.44.0

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.d.ts

@@ -5,10 +5,11 @@
  * - Entity metadata (decorator-based entities)
  * - Database introspection results (TableSchema[])
  */
-import type { EntityMeta, FieldOptions, Type } from '../type/index.js';
+import type { EntityGetter } from '../type/entity.js';
+import type { EntityMeta, FieldMeta, FieldOptions, Type } from '../type/index.js';
 import type { NamingStrategy } from '../type/namingStrategy.js';
 import { SchemaAST } from './schemaAST.js';
-import { type ForeignKeyAction } from './types.js';
+import { type CanonicalType, type ForeignKeyAction } from './types.js';
 /**
  * Options for building SchemaAST from entities.
  */
@@ -31,3 +32,23 @@ export interface BuildSchemaASTOptions {
  * resolves against a table another entity declares, and an index against the columns of its own.
  */
 export declare function buildSchemaAST(entities: readonly Type<unknown>[], 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.
+ */
+export declare function resolveColumnCanonicalType(field: FieldMeta, seen?: Set<EntityGetter>): CanonicalType;

package/dist/schema/schemaASTBuilder.js

@@ -53,7 +53,7 @@ export function buildSchemaAST(entities, options = {}) {
  * reflection also produces constructor values like `String`/`Number`.
  * `columnType` remains the unambiguous, always-respected explicit override.
  */
-function resolveColumnCanonicalType(field, seen = new Set()) {
+export function resolveColumnCanonicalType(field, seen = new Set()) {
     const hasExplicitType = !!field.columnType || !field.typeFromReference;
     if (!hasExplicitType && field.references && !seen.has(field.references)) {
         seen.add(field.references);
@@ -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(', '),
     };
 }

package/dist/type/entity.d.ts

@@ -49,6 +49,8 @@ export type RelationKey<E> = Exclude<Key<E>, FieldKey<E> | MethodKey<E>>;
  * inferring junk like `T = string`), while the marker key only exists on branded types.
  */
 type IsJson<T> = '__json' extends keyof T ? true : false;
+/** Whether `T` is what a JSON column holds: the branded payload, or an array of them. */
+type IsJsonColumn<T> = IsJson<T> extends true ? true : IsJson<NonNullable<Unpacked<T>>>;
 /** The payload `P` of a branded `Json<P>`, or `never` for any non-JSON type. */
 type UnwrapJson<T> = IsJson<T> extends true ? (T extends Json<infer P> ? P : never) : never;
 /**
@@ -276,7 +278,7 @@ export type FieldType = StringConstructor | NumberConstructor | BooleanConstruct
  * Both `Json<T>` and `Json<T>[]` have to be recognised, and the array check has to precede the scalar
  * arms so a `number[]` vector is not read as a `number`.
  */
-export type TypeFor<V, T = NonNullable<V>> = IsJson<T> extends true ? JsonColumnType : IsJson<NonNullable<Unpacked<T>>> extends true ? JsonColumnType : T extends readonly number[] ? VectorColumnType : T extends string ? StringConstructor | StringColumnType : T extends number ? NumberConstructor | NumericColumnType : T extends bigint ? BigIntConstructor | NumericColumnType : T extends boolean ? BooleanConstructor | BooleanColumnType : T extends Date ? DateConstructor | DateColumnType : T extends Uint8Array ? BlobColumnType : FieldType;
+export type TypeFor<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? JsonColumnType : T extends readonly number[] ? VectorColumnType : T extends string ? StringConstructor | StringColumnType : T extends number ? NumberConstructor | NumericColumnType : T extends bigint ? BigIntConstructor | NumericColumnType : T extends boolean ? BooleanConstructor | BooleanColumnType : T extends Date ? DateConstructor | DateColumnType : T extends Uint8Array ? BlobColumnType : FieldType;
 /**
  * A field as the registry holds it: what the user authored, plus what registration worked out.
  *
@@ -384,11 +386,9 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
      */
     readonly unique?: boolean;
     /**
-     * The column's DDL default, rendered into `CREATE TABLE` by `formatDefaultValue` - not `V`, unlike
-     * the generators above. A JSONB column defaults with the SQL literal it stores, `defaultValue: '{}'`,
-     * which is a string whatever the field's TypeScript type is.
+     * The column's DDL default, rendered into `CREATE TABLE` by `formatDefaultValue`.
      */
-    readonly defaultValue?: Scalar | Record<string, unknown>;
+    readonly defaultValue?: DdlDefault<V>;
     /**
      * Whether the column is auto-incrementing (for integer IDs).
      */
@@ -403,6 +403,17 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
     readonly comment?: string;
 };
 export type OnFieldCallback<V = TsTypeOf<FieldType>> = V | QueryRaw | (() => V | QueryRaw);
+/**
+ * What a column may default to: the value it holds, except on a JSON column, which defaults with the
+ * SQL literal it stores (`defaultValue: '{}'`) whatever the property's TypeScript type is. Opening
+ * that exception to every field is what let `@Field({ type: Number, defaultValue: 'hello' })` compile.
+ *
+ * The erased shape - `FieldOptions` with no field in mind - admits every column's default at once, or
+ * no `FieldOptions<V>` would be assignable to the one the registry and the dialects read.
+ */
+type DdlDefault<V, T = NonNullable<V>> = IsJsonColumn<T> extends true ? JsonDdlDefault : [TsTypeOf<FieldType>] extends [T] ? JsonDdlDefault | T : T;
+/** What a JSON column, and the field-less `FieldOptions`, may default to. */
+type JsonDdlDefault = Scalar | Record<string, unknown>;
 /**
  * The TypeScript types a field may be declared as, given the `type` it registers: the inverse of
  * {@link TypeFor}.
@@ -730,7 +741,10 @@ export type EntityIndexMeta = {
 } & VectorIndexOptions & IndexTypeOptions;
 export type EntityMeta<E> = {
     readonly entity: Type<E>;
+    /** The table, which is the class's own name where the entity named none - see {@link derivedName}. */
     name?: string;
+    /** Whether {@link name} came from the class rather than from the author, so a naming strategy applies. */
+    derivedName?: boolean;
     /** Set only when the entity named one; unset defers to the pool where it is used. See `AbstractDialect.resolveSchema`. */
     schema?: string;
     /**
@@ -760,7 +774,13 @@ export type EntityMeta<E> = {
     checks?: CheckSchema[];
     /** Lifecycle hooks registered via @BeforeInsert, @AfterUpdate, etc. */
     hooks?: Partial<Record<HookEvent, HookRegistration[]>>;
-    processed?: boolean;
+    /**
+     * Bumped by every `define*` call, so anything derived from this metadata can tell that it changed.
+     * A content type registered at runtime keeps adding to an entity that has already been read.
+     */
+    revision: number;
+    /** The revision `getMeta` last finalized, which is what makes finalizing idempotent and re-entrant. */
+    processedAt?: number;
 };
 /**
  * Configurable options for an entity (`@Entity()` / `defineEntity`).
@@ -777,6 +797,16 @@ export type CheckOptions = {
     readonly name?: string;
     readonly expression: QueryRaw;
 };
+/**
+ * An entity's members as the registry takes them, keyed by plain strings - what a decorator bag, an
+ * {@link EntityOptions} and a decorator bag both reduce to before anything is registered: a member
+ * decorator has no class to key against, so by then the keys are plain strings either way.
+ */
+export type EntityMembers = {
+    readonly fields?: Readonly<Record<string, FieldOptions | undefined>>;
+    readonly relations?: Readonly<Record<string, RelationOptions | undefined>>;
+    readonly hooks?: Readonly<Partial<Record<HookEvent, readonly string[]>>>;
+};
 export type EntityOptions<E = unknown> = {
     readonly name?: string;
     /**

package/dist/type/migration.d.ts

@@ -206,6 +206,19 @@ export interface SchemaDiff {
     readonly foreignKeysToAdd?: ForeignKeySchema[];
     readonly foreignKeysToDrop?: string[];
 }
+/**
+ * What every sync entry point takes: `safe` keeps it additive, `drop` lets it remove a column, and
+ * `logging` reports each statement. A plan ignores `logging`, having nothing to run.
+ */
+export interface SyncOptions {
+    readonly safe?: boolean;
+    readonly drop?: boolean;
+    readonly logging?: boolean;
+    /** One entity instead of every registered one, for a schema that grows while the process runs. */
+    readonly entity?: Type<unknown>;
+    /** Drop every table and recreate it. Development only: it is the one option that loses data. */
+    readonly force?: boolean;
+}
 export interface CreateSchemaOptions {
     readonly ifNotExists?: boolean;
     /**
@@ -262,7 +275,7 @@ export interface SchemaGenerator {
     /**
      * Get the SQL type for a field based on its options
      */
-    getSqlType(fieldOptions: FieldOptions, fieldType?: unknown): string;
+    getSqlType(fieldOptions: FieldOptions): string;
     /**
      * Compare an entity with a database table node and return the differences.
      */

package/dist/type/query.d.ts

@@ -394,12 +394,8 @@ type CountedRelations<C extends PropertyKey> = [C] extends [never] ? unknown : {
     };
 };
 /** @internal */
-type QueryProjectedRow<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = [S | X] extends [never] ? E : IsUniform<V> extends true ? [PopulatedToMany<E, P>] extends [never] ? {
-    [K in keyof E as K extends ProjectedKeys<E, S, V, X, P, C> ? K : never]: E[K];
-} : // A populated to-many is always a list, empty where the parent has no children, so it maps
-{
-    [K in keyof E as K extends Exclude<ProjectedKeys<E, S, V, X, P, C>, PopulatedToMany<E, P>> ? K : never]: E[K];
-} & {
+type QueryProjectedRow<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = [S | X] extends [never] ? E : IsUniform<V> extends true ? [PopulatedToMany<E, P>] extends [never] ? Pick<E, ProjectedKeys<E, S, V, X, P, C> & keyof E> : // A populated to-many is always a list, empty where the parent has no children, so it maps
+Pick<E, Exclude<ProjectedKeys<E, S, V, X, P, C>, PopulatedToMany<E, P>> & keyof E> & {
     [K in PopulatedToMany<E, P>]-?: NonNullable<E[K]>;
 } : E;
 /** The to-many relations a query populated, which come back as lists rather than as optional ones. */

package/dist/type/queryWhere.d.ts

@@ -296,10 +296,20 @@ type QueryCommonOp = Exclude<keyof QueryWhereFieldOperatorMap<unknown>, QueryStr
 type QueryAllowedOp<T> = QueryCommonOp | ([NonNullable<T>] extends [QueryComparableScalar] ? QueryOrderedOp : never) | ([NonNullable<T>] extends [string] ? QueryStringOp : never) | ([NonNullable<T>] extends [readonly number[] | Uint8Array] ? QueryVectorOp : never) | (IsMany<T> extends true ? QueryArrayOp : never);
 /**
  * Operators applicable to a field of type `T`: string operators require string fields, ordering
- * operators comparable fields, array operators array fields. `unknown` stays fully permissive
- * (untyped JSON dot-paths, erased dialect shapes).
+ * operators comparable fields, array operators array fields.
+ *
+ * Two shapes stay fully permissive, because neither says anything to check against: `unknown`
+ * (untyped JSON dot-paths, erased dialect shapes), and a field typed as every scalar at once - the
+ * column of a content type defined at runtime. Narrowing to what they share would leave a dynamic
+ * row with equality alone, since no operator applies to a boolean and a blob both.
+ */
+export type QueryWhereFieldOperators<T> = unknown extends T ? QueryWhereFieldOperatorMap<T> : IsUntypedColumn<T> extends true ? QueryWhereFieldOperatorMap<T> : Pick<QueryWhereFieldOperatorMap<T>, QueryAllowedOp<T>>;
+/**
+ * Whether a column admits every scalar at once, which is what an entity keyed by an index signature
+ * says about all of its columns. `Scalar` is the yardstick rather than a parameter: the question is
+ * whether `T` is at least that wide, and nothing narrower than the whole union answers it.
  */
-export type QueryWhereFieldOperators<T> = unknown extends T ? QueryWhereFieldOperatorMap<T> : Pick<QueryWhereFieldOperatorMap<T>, QueryAllowedOp<T>>;
+type IsUntypedColumn<T> = [Scalar] extends [NonNullable<T>] ? true : false;
 /**
  * Value for a field comparison. A bare array is an implicit `$in` for scalar fields only:
  * on array-typed fields (e.g. a vector `number[]`) an array of arrays is ambiguous, so

package/dist/util/field.util.d.ts

@@ -1,16 +1,27 @@
 import type { EntityMeta, FieldOptions } from '../type/index.js';
 /**
- * Checks if a field type is numeric (Number, BigInt, or explicit numeric logical types)
+ * The kind of column a field lands on, which is what decides whether an option means anything on it:
+ * `length` is a string's, `precision` a number's, `dimensions` a vector's. Named in the words an
+ * error reports it in, so there is no second table of labels to keep in step.
  */
-export declare function isNumericType(type: unknown): boolean;
+export type ColumnFamily = 'string' | 'numeric' | 'boolean' | 'date' | 'json' | 'blob' | 'vector';
 /**
- * Checks if a field type is boolean (Boolean, or an explicit boolean logical type)
+ * The runtime half of the column-type unions in `type/entity.ts`, which TypeScript erases. Each list
+ * is checked against its own union, so a type cannot be filed under the wrong family, and
+ * {@link UnplacedColumnType} refuses to compile if a new one is filed under none. Nothing here
+ * restates the unions: the compile-time side of the same question reads them directly.
  */
-export declare function isBooleanType(type: unknown): boolean;
-/**
- * Checks if a field type is JSON
- */
-export declare function isJsonType(type: unknown): boolean;
+export declare const COLUMN_TYPES_BY_FAMILY: {
+    readonly numeric: readonly ["int", "integer", "tinyint", "smallint", "bigint", "float", "float4", "float8", "double", "double precision", "decimal", "numeric", "real", "serial", "smallserial", "bigserial"];
+    readonly string: readonly ["char", "varchar", "text", "uuid"];
+    readonly date: readonly ["date", "time", "datetime", "timestamp", "timestamptz"];
+    readonly json: readonly ["json", "jsonb"];
+    readonly blob: readonly ["blob", "bytea"];
+    readonly boolean: readonly ["bool", "boolean"];
+    readonly vector: readonly ["vector", "halfvec", "sparsevec"];
+};
+/** The family of a logical field type, or `undefined` where it names none. */
+export declare function columnFamily(type: unknown): ColumnFamily | undefined;
 /**
  * Whether the field is the entity's *whole* primary key - the only kind a serial can stand in for,
  * and the only one that may state `PRIMARY KEY` in its own column definition.