uql-orm 0.42.0 → 0.43.0

package/dist/schema/schemaASTDiffer.js

@@ -8,7 +8,7 @@
  * - Schema synchronization
  */
 import { areTypesEqual, isBreakingTypeChange } from './canonicalType.js';
-import { describeIndexDifferences } from './indexDifferences.js';
+import { describeIndexDifferences, indexNameStem } from './indexDifferences.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
  * Default diff options.
@@ -17,6 +17,8 @@ const DEFAULT_OPTIONS = {
     compareIndexes: true,
     indexFacets: new Set(),
     compareRelationships: true,
+    normalizeType: (type) => type,
+    defaultsEqual: (expected, actual) => normalizeDefault(expected) === normalizeDefault(actual),
     ignoreCase: false,
     excludeTables: [],
 };
@@ -61,20 +63,25 @@ export function diffSchemas(source, target, options = {}) {
         .filter((tableDiff) => tableDiff !== undefined);
     const columnDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.columnDiffs ?? []);
     const indexDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.indexDiffs ?? []);
+    const primaryKeyDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.primaryKeyDiff ?? []);
     // Relationships span tables, so they are compared over the whole schema rather than per table.
     const relationshipDiffs = opts.compareRelationships ? diffRelationships(source, target, opts) : [];
     const hasDifferences = tablesToCreate.length > 0 ||
         tablesToDrop.length > 0 ||
         tablesToAlter.length > 0 ||
         relationshipDiffs.length > 0 ||
-        indexDiffs.length > 0;
-    const hasBreakingChanges = tablesToDrop.length > 0 || columnDiffs.some((d) => d.isBreaking);
+        indexDiffs.length > 0 ||
+        primaryKeyDiffs.length > 0;
+    // Rewriting a key drops a constraint and rebuilds an index over the whole table, and fails outright
+    // where its new columns are null on rows that already exist. Breaking by any measure.
+    const hasBreakingChanges = tablesToDrop.length > 0 || primaryKeyDiffs.length > 0 || columnDiffs.some((d) => d.isBreaking);
     return {
         tablesToCreate,
         tablesToDrop,
         tablesToAlter,
         columnDiffs,
         indexDiffs,
+        primaryKeyDiffs,
         relationshipDiffs,
         hasDifferences,
         hasBreakingChanges,
@@ -82,14 +89,35 @@ export function diffSchemas(source, target, options = {}) {
 }
 /**
  * Compare two tables and return the differences.
+ *
+ * Exported because it is also how a migration is planned: the generator diffs one entity's table
+ * against the one the database reported, then projects the result into a `SchemaDiff`. One
+ * comparison serves both, so drift and migrations can no longer disagree about what has changed.
  */
-function diffTable(source, target, opts) {
+export function diffTable(source, target, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
     const columnDiffs = diffTableColumns(source, target, opts);
     const indexDiffs = opts.compareIndexes ? diffTableIndexes(source, target, opts) : [];
-    if (columnDiffs.length === 0 && indexDiffs.length === 0) {
+    const primaryKeyDiff = diffPrimaryKey(source, target);
+    if (columnDiffs.length === 0 && indexDiffs.length === 0 && !primaryKeyDiff) {
         return undefined;
     }
-    return { name: source.name, type: 'alter', columnDiffs, indexDiffs };
+    return { name: source.name, type: 'alter', columnDiffs, indexDiffs, primaryKeyDiff };
+}
+/**
+ * The two keys, where they hold different columns.
+ *
+ * Compared by columns and in order. Not by name: the engine named the constraint on every table that
+ * already exists, so matching on one would report every table as drifted the moment the convention
+ * that derives names changes.
+ */
+function diffPrimaryKey(source, target) {
+    const expected = source.primaryKey.map((column) => column.name);
+    const actual = target.primaryKey.map((column) => column.name);
+    if (expected.length === actual.length && expected.every((column, i) => column === actual[i])) {
+        return undefined;
+    }
+    return { table: source.name, expected, actual, actualName: target.primaryKeyName };
 }
 /**
  * Compare columns between two tables.
@@ -114,7 +142,7 @@ function diffTableColumns(source, target, opts) {
             description: `Drop column "${column.name}"`,
         })),
         ...matched
-            .map(([sourceColumn, targetColumn]) => diffColumn(source.name, sourceColumn, targetColumn))
+            .map(([sourceColumn, targetColumn]) => diffColumn(source.name, sourceColumn, targetColumn, opts))
             .filter((diff) => diff !== undefined),
     ];
 }
@@ -123,7 +151,7 @@ function diffTableColumns(source, target, opts) {
  */
 function diffTableIndexes(source, target, opts) {
     const normalizeName = nameNormalizer(opts);
-    const { created, dropped, matched } = matchByKey(source.indexes, target.indexes, (index) => normalizeName(index.name));
+    const { created, dropped, matched } = matchByKey(source.indexes, target.indexes, (index) => normalizeName(indexNameStem(index.name)));
     return [
         ...created.map((index) => ({ name: index.name, table: source.name, type: 'create', expected: index })),
         ...dropped.map((index) => ({ name: index.name, table: target.name, type: 'drop', actual: index })),
@@ -135,26 +163,35 @@ function diffTableIndexes(source, target, opts) {
 /**
  * Compare two columns and return the difference.
  */
-function diffColumn(tableName, source, target) {
+function diffColumn(tableName, source, target, opts) {
     const differences = [];
-    // Compare types
-    if (!areTypesEqual(source.type, target.type)) {
+    // Two things a key column implies rather than states, and catalogues report inconsistently: its
+    // type, which is the dialect's serial spelling rather than one the entity chose and does not round
+    // trip (`BIGINT UNSIGNED AUTO_INCREMENT` reads back as `BIGINT(20) UNSIGNED`), and its nullability,
+    // which is NOT NULL in every engine whatever is reported - SQLite's `PRAGMA table_info` says
+    // `notnull: 0` for the `INTEGER PRIMARY KEY` that is the table's own rowid. Comparing either asked
+    // to rewrite the column on every sync, and on SQLite, which cannot alter one at all, failed
+    // outright. Everything else about a key column is still compared, which the blanket "never alter a
+    // key column" rule these two replace used to hide.
+    const generatedType = source.isAutoIncrement && target.isAutoIncrement;
+    const impliedNotNull = source.isPrimaryKey && target.isPrimaryKey;
+    const typeChanged = !generatedType && !areTypesEqual(opts.normalizeType(source.type), opts.normalizeType(target.type));
+    if (typeChanged) {
         differences.push(`type: ${formatType(source.type)} → ${formatType(target.type)}`);
     }
-    // Compare nullability
-    if (source.nullable !== target.nullable) {
+    if (!impliedNotNull && source.nullable !== target.nullable) {
         differences.push(`nullable: ${target.nullable} → ${source.nullable}`);
     }
     // Compare unique constraint
     if (source.isUnique !== target.isUnique) {
         differences.push(`unique: ${target.isUnique} → ${source.isUnique}`);
     }
-    // Compare auto-increment
-    if (source.isAutoIncrement !== target.isAutoIncrement) {
-        differences.push(`autoIncrement: ${target.isAutoIncrement} → ${source.isAutoIncrement}`);
-    }
+    // Auto-increment is deliberately not compared. No engine turns a column into an identity, or out of
+    // one, without rewriting the table, and there is no DDL here that does it - so a difference could
+    // only ever be reported, never settled, and the statements emitted for it (a bare `ALTER COLUMN
+    // TYPE`) do not change it. The same rule `describeIndexDifferences` follows for what it cannot read.
     // Compare default values (if both defined)
-    if (normalizeDefault(source.defaultValue) !== normalizeDefault(target.defaultValue)) {
+    if (!opts.defaultsEqual(source.defaultValue, target.defaultValue)) {
         differences.push(`default: ${target.defaultValue ?? 'NULL'} → ${source.defaultValue ?? 'NULL'}`);
     }
     if (differences.length === 0) {
@@ -166,7 +203,10 @@ function diffColumn(tableName, source, target) {
         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/schema/types.d.ts

@@ -122,7 +122,7 @@ export interface ColumnNode {
 export interface TableNode {
     /**
      * The table's own name, never qualified. Everything derived from a table reads this: an index or
-     * constraint name is a single identifier, and `idx_sales.Order_total` is a syntax error.
+     * constraint name is a single identifier, and `sales.Order_total_idx` is a syntax error.
      */
     readonly name: string;
     /**
@@ -133,8 +133,14 @@ export interface TableNode {
     readonly schema?: string;
     /** Map of column name to column node */
     readonly columns: Map<string, ColumnNode>;
-    /** Primary key columns (supports composite keys) */
+    /** Primary key columns, in key order (supports composite keys) */
     readonly primaryKey: ColumnNode[];
+    /**
+     * What the constraint is called, where a name is known: read back from the database on an
+     * introspected table, absent on one built from entities, where nothing has named it yet. A `DROP`
+     * is the only thing that needs it - see {@link TableSchema.primaryKeyName}.
+     */
+    primaryKeyName?: string;
     /** Indexes on this table */
     readonly indexes: IndexNode[];
     /** `CHECK` constraints on this table. Optional: a node can be built without ever naming one. */
@@ -151,7 +157,7 @@ export interface TableNode {
  * Represents a foreign key relationship between tables.
  */
 export interface RelationshipNode {
-    /** Constraint name (e.g., fk_posts_author_id) */
+    /** Constraint name (e.g., posts_author_id_fk) */
     readonly name: string;
     /** Type of relationship */
     readonly type: RelationshipType;
@@ -202,13 +208,28 @@ export interface SchemaAST {
 }
 /**
  * Difference between two column definitions.
+ *
+ * A union rather than one shape with two optional sides, so which node is present follows from the
+ * kind of difference: an added column has only the `expected` one, a dropped column only the
+ * `actual` one, and an altered column both. Stated as optionals, every reader had to assert its way
+ * past a `undefined` the kind had already ruled out.
  */
-export interface ColumnDiff {
+export type ColumnDiff = ColumnDiffBase & ({
+    readonly type: 'add';
+    readonly expected: ColumnNode;
+    readonly actual?: undefined;
+} | {
+    readonly type: 'drop';
+    readonly expected?: undefined;
+    readonly actual: ColumnNode;
+} | {
+    readonly type: 'alter';
+    readonly expected: ColumnNode;
+    readonly actual: ColumnNode;
+});
+interface ColumnDiffBase {
     readonly table: string;
     readonly column: string;
-    readonly type: 'add' | 'drop' | 'alter';
-    readonly expected?: ColumnNode;
-    readonly actual?: ColumnNode;
     /** Whether this change could cause data loss */
     readonly isBreaking?: boolean;
     readonly description?: string;
@@ -221,6 +242,21 @@ export interface TableDiff {
     readonly type: 'create' | 'drop' | 'alter';
     readonly columnDiffs?: ColumnDiff[];
     readonly indexDiffs?: IndexDiff[];
+    /** Set only where the two keys hold different columns. See {@link PrimaryKeyDiff}. */
+    readonly primaryKeyDiff?: PrimaryKeyDiff;
+}
+/**
+ * Two primary keys that hold different columns.
+ *
+ * By columns and in order, never by name: `(a, b)` is a different key from `(b, a)`, while the same
+ * key called `Member_pkey` on one side and `Member__userId_pk` on the other is one key, not two.
+ */
+export interface PrimaryKeyDiff {
+    readonly table: string;
+    readonly expected: string[];
+    readonly actual: string[];
+    /** What the *actual* side calls its constraint, which is the only name a `DROP` can use. */
+    readonly actualName?: string;
 }
 /**
  * Difference between two index definitions.
@@ -258,6 +294,8 @@ export interface SchemaDiffResult {
     readonly columnDiffs: ColumnDiff[];
     /** All index diffs */
     readonly indexDiffs: IndexDiff[];
+    /** Every table whose primary key holds different columns than the entity declares. */
+    readonly primaryKeyDiffs: PrimaryKeyDiff[];
     /** All relationship/FK diffs */
     readonly relationshipDiffs: RelationshipDiff[];
     /** Whether there are any differences */
@@ -321,3 +359,4 @@ export interface DriftReport {
         readonly info: number;
     };
 }
+export {};

package/dist/sqlite/sqliteDialect.d.ts

@@ -5,7 +5,8 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     protected readonly featureDefaults: DialectFeatures;
     readonly dialectName = "sqlite";
     readonly escapeIdChar = "`";
-    readonly serialPrimaryKey = "INTEGER PRIMARY KEY AUTOINCREMENT";
+    readonly serialType = "INTEGER PRIMARY KEY AUTOINCREMENT";
+    readonly serialDeclaresPrimaryKey = true;
     readonly tableOptions = "";
     readonly beginTransactionCommand = "BEGIN TRANSACTION";
     readonly commitTransactionCommand = "COMMIT";

package/dist/sqlite/sqliteDialect.js

@@ -13,6 +13,7 @@ export class SqliteDialect extends AbstractSqlDialect {
         dropTableCascade: false,
         renameColumn: true,
         foreignKeyAlter: false, // SQLite does not support adding FKs to existing tables
+        primaryKeyAlter: false, // nor changing a key: the only route is rebuilding the table
         columnComment: false, // SQLite does not support column comments
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
@@ -21,7 +22,9 @@ export class SqliteDialect extends AbstractSqlDialect {
     };
     dialectName = 'sqlite';
     escapeIdChar = '`';
-    serialPrimaryKey = 'INTEGER PRIMARY KEY AUTOINCREMENT';
+    serialType = 'INTEGER PRIMARY KEY AUTOINCREMENT';
+    // `AUTOINCREMENT` is only legal in that exact phrase, so the key cannot be lifted to table level.
+    serialDeclaresPrimaryKey = true;
     tableOptions = '';
     beginTransactionCommand = 'BEGIN TRANSACTION';
     commitTransactionCommand = 'COMMIT';

package/dist/type/dialect.d.ts

@@ -91,6 +91,12 @@ export interface EngineFeatures {
     readonly dropTableCascade: boolean;
     readonly renameColumn: boolean;
     readonly foreignKeyAlter: boolean;
+    /**
+     * Whether a table's primary key can be changed on an existing table. False on SQLite, whose only
+     * route is rebuilding the table - so a migration that would change one is refused by name rather
+     * than emitting DDL the engine rejects.
+     */
+    readonly primaryKeyAlter: boolean;
     /** Whether the dialect supports inline COMMENT on columns (MySQL/MariaDB). */
     readonly columnComment: boolean;
     /**

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}.
@@ -760,7 +771,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`).

package/dist/type/migration.d.ts

@@ -123,7 +123,14 @@ export interface ColumnSchema {
 export interface TableSchema {
     readonly name: string;
     readonly columns: ColumnSchema[];
+    /** The key's columns **in order**, which is what a composite is: `(a, b)` is not `(b, a)`. */
     readonly primaryKey?: string[];
+    /**
+     * What the engine calls the key's constraint, where it names one at all - Postgres's `Member_pkey`,
+     * MySQL's literal `PRIMARY`, nothing on SQLite. Only a `DROP` needs it, and only the name the
+     * database actually reported will do: a derived one would name a constraint that is not there.
+     */
+    readonly primaryKeyName?: string;
     readonly indexes?: IndexSchema[];
     readonly foreignKeys?: ForeignKeySchema[];
 }
@@ -176,6 +183,18 @@ export interface SchemaDiff {
      */
     readonly schema?: string;
     readonly type: 'create' | 'alter' | 'drop';
+    /**
+     * The key the table has against the key the entity declares, set only when they differ.
+     *
+     * Compared by columns, never by name: the engine named the existing one, so requiring a derived
+     * name to match would rewrite the primary key of every table on the first migration after
+     * upgrading. `fromName` is what the database reported, and the only name a `DROP` can use.
+     */
+    readonly primaryKey?: {
+        readonly from: string[];
+        readonly to: string[];
+        readonly fromName?: string;
+    };
     readonly columnsToAdd?: ColumnSchema[];
     readonly columnsToAlter?: {
         from: ColumnSchema;
@@ -243,7 +262,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/util/field.util.d.ts

@@ -1,16 +1,37 @@
-import type { FieldOptions } from '../type/index.js';
+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;
+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;
 /**
- * Checks if a field type is JSON
+ * 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.
+ *
+ * One column of a composite is a value the caller supplies, and the table states the key over every
+ * column at once. Asked in one place because the two schema paths - the AST that builds a
+ * `CREATE TABLE` and the diff that builds an `ALTER` - have to answer it the same way, and each
+ * answering for itself is what put a serial `PRIMARY KEY` on both columns of a composite.
  */
-export declare function isJsonType(type: unknown): boolean;
+export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOptions): boolean;
 /**
  * Checks if a field should be treated as auto-incrementing.
  */

package/dist/util/field.util.js

@@ -1,56 +1,65 @@
-const NUMERIC_COLUMN_TYPES = {
-    int: true,
-    integer: true,
-    tinyint: true,
-    smallint: true,
-    bigint: true,
-    float: true,
-    float4: true,
-    float8: true,
-    double: true,
-    'double precision': true,
-    decimal: true,
-    numeric: true,
-    real: true,
-    serial: true,
-    smallserial: true,
-    bigserial: true,
-};
-const JSON_COLUMN_TYPES = {
-    json: true,
-    jsonb: true,
-};
+import { getKeys } from './object.util.js';
 /**
- * Checks if a field type is numeric (Number, BigInt, or explicit numeric logical types)
+ * 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 function isNumericType(type) {
-    if (type === Number || type === BigInt)
-        return true;
-    if (typeof type === 'string') {
-        return type.toLowerCase() in NUMERIC_COLUMN_TYPES;
+export const COLUMN_TYPES_BY_FAMILY = {
+    numeric: [
+        'int',
+        'integer',
+        'tinyint',
+        'smallint',
+        'bigint',
+        'float',
+        'float4',
+        'float8',
+        'double',
+        'double precision',
+        'decimal',
+        'numeric',
+        'real',
+        'serial',
+        'smallserial',
+        'bigserial',
+    ],
+    string: ['char', 'varchar', 'text', 'uuid'],
+    date: ['date', 'time', 'datetime', 'timestamp', 'timestamptz'],
+    json: ['json', 'jsonb'],
+    blob: ['blob', 'bytea'],
+    boolean: ['bool', 'boolean'],
+    vector: ['vector', 'halfvec', 'sparsevec'],
+};
+// Constructors and type strings in one map: a logical type is either, and every caller asks the same
+// question of both.
+const FAMILY_OF = new Map([
+    [String, 'string'],
+    [Number, 'numeric'],
+    [BigInt, 'numeric'],
+    [Boolean, 'boolean'],
+    [Date, 'date'],
+]);
+for (const family of getKeys(COLUMN_TYPES_BY_FAMILY)) {
+    for (const columnType of COLUMN_TYPES_BY_FAMILY[family]) {
+        FAMILY_OF.set(columnType, family);
     }
-    return false;
 }
-/**
- * Checks if a field type is boolean (Boolean, or an explicit boolean logical type)
- */
-export function isBooleanType(type) {
-    if (type === Boolean)
-        return true;
-    if (typeof type === 'string') {
-        const lowered = type.toLowerCase();
-        return lowered === 'bool' || lowered === 'boolean';
-    }
-    return false;
+/** The family of a logical field type, or `undefined` where it names none. */
+export function columnFamily(type) {
+    return FAMILY_OF.get(typeof type === 'string' ? type.toLowerCase() : type);
 }
 /**
- * Checks if a field type is JSON
+ * 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.
+ *
+ * One column of a composite is a value the caller supplies, and the table states the key over every
+ * column at once. Asked in one place because the two schema paths - the AST that builds a
+ * `CREATE TABLE` and the diff that builds an `ALTER` - have to answer it the same way, and each
+ * answering for itself is what put a serial `PRIMARY KEY` on both columns of a composite.
  */
-export function isJsonType(type) {
-    if (typeof type === 'string') {
-        return type.toLowerCase() in JSON_COLUMN_TYPES;
-    }
-    return false;
+export function isSoleIdField(meta, field) {
+    return field.isId === true && meta.ids.length === 1;
 }
 /**
  * Checks if a field should be treated as auto-incrementing.
@@ -63,6 +72,5 @@ export function isAutoIncrement(field, isPrimaryKey) {
     const colType = field.columnType?.toLowerCase();
     if (colType === 'serial' || colType === 'smallserial' || colType === 'bigserial')
         return true;
-    const isNumeric = isNumericType(field.type);
-    return isPrimaryKey && isNumeric && !field.onInsert && !field.columnType;
+    return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert && !field.columnType;
 }