uql-orm 0.80.0 → 0.81.0

package/dist/schema/schemaASTDiffer.d.ts

@@ -1,4 +1,3 @@
-import { type IndexFacet } from './indexDifferences.js';
 import type { SchemaAST } from './schemaAST.js';
 import type { CanonicalType } from './types.js';
 import type { ColumnDiff, ForeignKeyAction, IndexDiff, RelationshipDiff, RelationshipNode, SchemaDiffResult, TableDiff, TableNode } from './types.js';
@@ -8,8 +7,6 @@ import type { ColumnDiff, ForeignKeyAction, IndexDiff, RelationshipDiff, Relatio
 export interface DiffOptions {
     /** Compare indexes */
     compareIndexes?: boolean;
-    /** What the target side can report about an index, normally an introspector's `indexFacets`. Anything left out is not compared. */
-    indexFacets?: ReadonlySet<IndexFacet>;
     /** Compare foreign keys/relationships */
     compareRelationships?: boolean;
     /** Ignore case differences in names */
@@ -38,3 +35,5 @@ export declare function referentialActions(rel: RelationshipNode): {
     readonly onDelete: ForeignKeyAction;
     readonly onUpdate: ForeignKeyAction;
 };
+/** Two defaults compared as written, where no dialect reprints them: `now()` and `CURRENT_TIMESTAMP` are one. */
+export declare function defaultsEqualAsWritten(expected: unknown, actual: unknown): boolean;

package/dist/schema/schemaASTDiffer.js

@@ -1,37 +1,21 @@
 import { areTypesEqual, isBreakingTypeChange } from './canonicalType.js';
-import { describeIndexDifferences, indexNameStem } from './indexDifferences.js';
+import { describeIndexDifferences, pairIndexes } from './indexDifferences.js';
+import { matchByKey } from './matchByKey.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
  * Default diff options.
  */
 const DEFAULT_OPTIONS = {
     compareIndexes: true,
-    indexFacets: new Set(),
     compareRelationships: true,
     normalizeType: (type) => type,
-    defaultsEqual: (expected, actual) => normalizeDefault(expected) === normalizeDefault(actual),
+    defaultsEqual: defaultsEqualAsWritten,
     ignoreCase: false,
     excludeTables: [],
 };
 function nameNormalizer(opts) {
     return opts.ignoreCase ? (name) => name.toLowerCase() : (name) => name;
 }
-/**
- * The only three ways two keyed collections can differ, which is the shape of every comparison here:
- * tables, columns, indexes and relationships all key by name and then split the same way.
- */
-function matchByKey(source, target, key) {
-    const sourceByKey = new Map([...source].map((item) => [key(item), item]));
-    const targetByKey = new Map([...target].map((item) => [key(item), item]));
-    return {
-        created: [...sourceByKey].filter(([at]) => !targetByKey.has(at)).map(([, item]) => item),
-        dropped: [...targetByKey].filter(([at]) => !sourceByKey.has(at)).map(([, item]) => item),
-        matched: [...sourceByKey].flatMap(([at, item]) => {
-            const counterpart = targetByKey.get(at);
-            return counterpart ? [[item, counterpart]] : [];
-        }),
-    };
-}
 /** How a relationship diff names the pair it is about, whichever way it differs. */
 function relationEnds(relation) {
     return { name: relation.name, fromTable: relation.from.table.name, toTable: relation.to.table.name };
@@ -86,12 +70,12 @@ export function diffTable(source, target, options = {}) {
 }
 /** The two keys where they hold different columns, compared in order and never by the name the engine gave them. */
 function diffPrimaryKey(source, target) {
-    const expected = source.primaryKey.map((column) => column.name);
-    const actual = target.primaryKey.map((column) => column.name);
+    const expected = source.primaryKey?.columns ?? [];
+    const actual = target.primaryKey?.columns ?? [];
     if (expected.length === actual.length && expected.every((column, i) => column === actual[i])) {
         return undefined;
     }
-    return { table: source.name, expected, actual, actualName: target.primaryKeyName };
+    return { table: source.name, expected: source.primaryKey, actual: target.primaryKey };
 }
 /**
  * Compare columns between two tables.
@@ -120,17 +104,14 @@ function diffTableColumns(source, target, opts) {
             .filter((diff) => diff !== undefined),
     ];
 }
-/**
- * Compare indexes between two tables.
- */
+/** Compare indexes between two tables, paired by {@link pairIndexes}, in what the target's reader reports. */
 function diffTableIndexes(source, target, opts) {
-    const normalizeName = nameNormalizer(opts);
-    const { created, dropped, matched } = matchByKey(source.indexes, target.indexes, (index) => normalizeName(indexNameStem(index.name)));
+    const { created, dropped, matched } = pairIndexes(source.indexes, target.indexes, nameNormalizer(opts));
     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 })),
         ...matched
-            .map(([sourceIndex, targetIndex]) => diffIndex(source.name, sourceIndex, targetIndex, opts.indexFacets))
+            .map(([sourceIndex, targetIndex]) => diffIndex(source.name, sourceIndex, targetIndex, target.indexFacets))
             .filter((diff) => diff !== undefined),
     ];
 }
@@ -158,12 +139,9 @@ function diffColumn(tableName, source, target, opts) {
     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}`);
-    }
     // Not compared, since no statement this generator emits could settle a difference: `isAutoIncrement`,
-    // `enum` (a check the database reprints), `generatedAs`, and `comment`.
+    // `enum` (a check the database reprints), `generatedAs`, and `comment`. Nor `isUnique`: a unique
+    // column is a unique index, compared with the indexes.
     // Compare default values (if both defined)
     if (!opts.defaultsEqual(source.defaultValue, target.defaultValue)) {
         differences.push(`default: ${target.defaultValue ?? 'NULL'} -> ${source.defaultValue ?? 'NULL'}`);
@@ -262,9 +240,10 @@ function formatType(type) {
         result += ' unsigned';
     return result;
 }
-/**
- * Normalize default values for comparison.
- */
+/** Two defaults compared as written, where no dialect reprints them: `now()` and `CURRENT_TIMESTAMP` are one. */
+export function defaultsEqualAsWritten(expected, actual) {
+    return normalizeDefault(expected) === normalizeDefault(actual);
+}
 function normalizeDefault(value) {
     if (value === undefined || value === null)
         return '';

package/dist/schema/types.d.ts

@@ -1,4 +1,5 @@
-import type { IndexSchema } from '../type/migration.js';
+import type { IndexSchema, PrimaryKeySchema } from '../type/migration.js';
+import type { IndexFacet } from './indexDifferences.js';
 /**
  * Type categories universal across SQL dialects.
  * These represent logical/semantic types, not specific SQL types.
@@ -109,18 +110,17 @@ export interface TableNode {
     readonly schema?: string;
     /** Map of column name to column node */
     readonly columns: Map<string, ColumnNode>;
-    /** 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;
+    /** The table's key, named where the database reported a name; none on a table without one. */
+    primaryKey?: PrimaryKeySchema;
     /** Indexes on this table */
     readonly indexes: IndexNode[];
-    /** `CHECK` constraints on this table. Optional: a node can be built without ever naming one. */
-    readonly checks?: CheckSchema[];
+    /**
+     * What the introspector that read this table reports about an index, and so all an index diff against
+     * it may compare. None on a table built from entities.
+     */
+    readonly indexFacets: ReadonlySet<IndexFacet>;
+    /** `CHECK` constraints on this table. */
+    readonly checks: CheckSchema[];
     /** Optional table comment */
     readonly comment?: string;
     /** Relationships pointing TO this table (other tables referencing this one) */
@@ -214,10 +214,9 @@ export interface TableDiff {
  */
 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;
+    readonly expected?: PrimaryKeySchema;
+    /** Named as the database reported it, which is the only name a `DROP` can use. */
+    readonly actual?: PrimaryKeySchema;
 }
 /**
  * Difference between two index definitions.

package/dist/type/migration.d.ts

@@ -118,14 +118,7 @@ export interface ColumnSchema extends Omit<ColumnNode, 'type' | 'table' | 'refer
 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 primaryKey?: PrimaryKeySchema;
     readonly indexes?: IndexSchema[];
     readonly foreignKeys?: ForeignKeySchema[];
 }
@@ -176,8 +169,26 @@ export interface ForeignKeySchema {
     readonly onUpdate?: ForeignKeyAction;
 }
 /**
- * Represents a difference between current and desired schema
+ * One object's change: added (`to` alone), dropped (`from` alone), or altered (both), each whole so the
+ * change is undone by swapping its ends. No engine alters an index, a key or a foreign key in place, so
+ * an alter of one is its drop and its add, which safe mode holds back together.
  */
+export interface Change<T> {
+    readonly from?: T;
+    readonly to?: T;
+}
+/** A primary key, whichever side it is read from: the entities, the database, or a diff between them. */
+export interface PrimaryKeySchema {
+    /** Its columns **in order**, which is what a composite is: `(a, b)` is not `(b, a)`. */
+    readonly columns: readonly string[];
+    /**
+     * What the engine calls its 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
+     * reported will do: a derived one would name a constraint that is not there.
+     */
+    readonly name?: string;
+}
+/** A table's differences from what its entity declares, or the table to create or drop. */
 export interface SchemaDiff {
     /** Qualified where the table has a schema, since it is also the key the table is found under. */
     readonly tableName: string;
@@ -187,36 +198,10 @@ export interface SchemaDiff {
      */
     readonly schema?: string;
     readonly type: 'create' | 'alter' | 'drop';
-    /**
-     * The table's key against the entity's, where their columns differ; `fromName` is the name the
-     * database reported, which is what a `DROP` needs.
-     */
-    readonly primaryKey?: {
-        readonly from: string[];
-        readonly to: string[];
-        readonly fromName?: string;
-    };
-    readonly columnsToAdd?: ColumnSchema[];
-    readonly columnsToAlter?: {
-        from: ColumnSchema;
-        to: ColumnSchema;
-    }[];
-    readonly columnsToDrop?: string[];
-    readonly indexesToAdd?: IndexSchema[];
-    /** Whole rather than by name, so the rollback can create each again. */
-    readonly indexesToDrop?: IndexSchema[];
-    readonly foreignKeysToAdd?: ForeignKeySchema[];
-    /** Dropped under the name the *database* reported, which is the only name a `DROP` can use. */
-    readonly foreignKeysToDrop?: string[];
-    /**
-     * A constraint whose referential actions changed. Its own field rather than a pair of entries in
-     * the two above, because no engine alters an action in place: it is a drop and an add that have to
-     * travel together, and safe mode has to hold back both or neither.
-     */
-    readonly foreignKeysToAlter?: {
-        readonly from: ForeignKeySchema;
-        readonly to: ForeignKeySchema;
-    }[];
+    readonly primaryKey?: Change<PrimaryKeySchema>;
+    readonly columns?: readonly Change<ColumnSchema>[];
+    readonly indexes?: readonly Change<IndexSchema>[];
+    readonly foreignKeys?: readonly Change<ForeignKeySchema>[];
 }
 /**
  * What every sync entry point takes: `safe` keeps it additive, `drop` lets it remove a column, and
@@ -254,6 +239,8 @@ export type InstalledTriggers = ReadonlyMap<string, readonly string[]>;
  * Interface for generating DDL statements from entity metadata
  */
 export interface SchemaGenerator {
+    /** Whether a column's stored default is the one the entity declares, as the engine reprints it. Absent where columns are not compared. */
+    readonly defaultsEqual?: (expected: unknown, actual: unknown) => boolean;
     /** The whole schema for `entities`, tables then the foreign keys between them, which need every entity at once. */
     generateCreateSchema(entities: readonly Type<object>[], options?: CreateSchemaOptions): string[];
     /**
@@ -273,14 +260,8 @@ export interface SchemaGenerator {
     generateTriggersDown(entity: Type<object>, installed?: InstalledTriggers): string[];
     /** A `DROP` for each trigger uql owns among `names` on `entity`'s table, whatever the entity declares. */
     generateTriggerDrops(entity: Type<object>, names: readonly string[]): string[];
-    /**
-     * Generate ALTER TABLE statements based on schema diff
-     */
+    /** The statements taking a table through `diff`; its rollback is the diff reversed, see `reverseDiff`. */
     generateAlterTable(diff: SchemaDiff): string[];
-    /**
-     * Generate rollback (down) statements for ALTER TABLE based on schema diff
-     */
-    generateAlterTableDown(diff: SchemaDiff): string[];
     /**
      * Generate CREATE INDEX statement
      */
@@ -333,11 +314,12 @@ export interface SchemaGenerator {
  */
 export interface SchemaIntrospector {
     /**
-     * Every trigger uql installed in this schema, by table and then by name, each with the statements that
-     * recreate it as it stands. The names say which to drop once an entity no longer declares them; the
-     * statements are what a rollback puts back, read off the engine rather than recorded anywhere by uql.
+     * Every trigger uql installed on `table`, by name, each with the statements that recreate it as it
+     * stands. The names say which to drop once an entity no longer declares them; the statements are what
+     * a rollback puts back, read off the engine rather than recorded anywhere by uql. One table's alone,
+     * so reading it never meets a trigger another writer is dropping from some other table.
      */
-    ownedTriggers(): Promise<Map<string, InstalledTriggers>>;
+    ownedTriggers(table: string): Promise<InstalledTriggers>;
     /**
      * What this introspector can read back about an index, and so all that diffing may compare.
      * Comparing a feature it cannot read reports the same drift forever: the entity side declares it,

package/dist/util/ddlExpression.util.d.ts

@@ -4,7 +4,11 @@ import { type EntityIndexColumn, type EntityIndexMeta, type EntityMeta, type Ind
  * object reach the schema as one: a column read off the refs as its key, any other `raw` as it is.
  */
 export declare function normalizeIndexColumn(entry: IndexColumnInput): EntityIndexColumn;
-/** Every index an entity declares: each `@Field({ index })` as the one-column `@Index` it is, then its `@Index`es. */
+/**
+ * Every index an entity declares: each `@Field({ index })` or `@Field({ unique })` as the one-column
+ * `@Index` it is, then its `@Index`es. A unique column is a unique index, the one spelling of uniqueness
+ * every engine can add and drop.
+ */
 export declare function declaredIndexes<E>(meta: EntityMeta<E>): EntityIndexMeta<E>[];
 /** An index entry as the schema holds it, its expression rendered to text by `render`. */
 export declare function renderIndexColumn(entry: EntityIndexColumn, render: (sql: QueryRaw) => string): IndexColumnSchema;

package/dist/util/ddlExpression.util.js

@@ -9,9 +9,13 @@ export function normalizeIndexColumn(entry) {
     const { column, ...modifiers } = typeof entry === 'string' || entry instanceof QueryRaw ? { column: entry } : entry;
     return { ...modifiers, column: column instanceof ColumnRef ? column.key : column };
 }
-/** Every index an entity declares: each `@Field({ index })` as the one-column `@Index` it is, then its `@Index`es. */
+/**
+ * Every index an entity declares: each `@Field({ index })` or `@Field({ unique })` as the one-column
+ * `@Index` it is, then its `@Index`es. A unique column is a unique index, the one spelling of uniqueness
+ * every engine can add and drop.
+ */
 export function declaredIndexes(meta) {
-    const fieldIndexes = definedEntries(meta.fields).flatMap(([key, field]) => field.index
+    const fieldIndexes = definedEntries(meta.fields).flatMap(([key, field]) => field.index || field.unique
         ? [
             {
                 columns: [{ column: key }],

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.80.0",
+  "version": "0.81.0",
   "type": "module",
   "engines": {
     "node": ">=24"