uql-orm 0.25.1 → 0.26.0

package/dist/schema/index.js

@@ -21,6 +21,6 @@ export async function introspectSchema(introspector) {
 // SchemaAST class
 export { SchemaAST } from './schemaAST.js';
 // Builder
-export { SchemaASTBuilder } from './schemaASTBuilder.js';
+export { buildSchemaAST } from './schemaASTBuilder.js';
 // Differ
-export { diffSchemas, SchemaASTDiffer } from './schemaASTDiffer.js';
+export { diffSchemas } from './schemaASTDiffer.js';

package/dist/schema/indexColumns.d.ts

@@ -0,0 +1,10 @@
+import type { ColumnNode, IndexNode } from './types.js';
+/**
+ * The table columns an index resolves to, in order.
+ *
+ * Derived rather than stored: an index is defined by its entries, and a second field repeating them
+ * as columns is a second thing to keep in step. It went out of step - one introspector rebuilt the
+ * entries from the columns it had just built from the entries, and every fixture had to write both.
+ * An expression entry resolves to no column at all, which is why the two were never the same list.
+ */
+export declare function indexColumns(index: IndexNode): ColumnNode[];

package/dist/schema/indexColumns.js

@@ -0,0 +1,11 @@
+/**
+ * The table columns an index resolves to, in order.
+ *
+ * Derived rather than stored: an index is defined by its entries, and a second field repeating them
+ * as columns is a second thing to keep in step. It went out of step - one introspector rebuilt the
+ * entries from the columns it had just built from the entries, and every fixture had to write both.
+ * An expression entry resolves to no column at all, which is why the two were never the same list.
+ */
+export function indexColumns(index) {
+    return index.entries.flatMap((entry) => (entry.expression ? [] : (index.table.columns.get(entry.column) ?? [])));
+}

package/dist/schema/indexDifferences.d.ts

@@ -0,0 +1,22 @@
+import type { IndexNode } from './types.js';
+/**
+ * What an introspector can report about an index, and so all that diffing may compare. Anything it
+ * cannot report is skipped: the entity declares it, the database never mentions it, and no migration
+ * could ever make the two agree.
+ *
+ * Deliberately separate from the dialect's `IndexFeature`, which says what an engine can *emit* and
+ * rejects outright. The two look alike and are not: Postgres emits an expression index and reads one
+ * back, MySQL emits one it cannot describe afterwards.
+ */
+export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include';
+/**
+ * Everything an index differs by, named, or nothing when the two match.
+ *
+ * Only what both sides can state *structurally* is compared. SQL text is not: a database reprints an
+ * expression and a predicate from its parse tree, so `status IN ('a','b')` reads back as
+ * `status = ANY (ARRAY['a'::text, 'b'::text])`, `LIKE` as `~~`, and a date literal with its time zone
+ * spelled out. Folding that back needs a SQL parser, and every near-miss reports drift that no
+ * migration can settle. So a partial index's predicate is never compared, and an index over an
+ * expression has its entries left alone while the rest of it still compares.
+ */
+export declare function describeIndexDifferences(source: IndexNode, target: IndexNode, facets: ReadonlySet<IndexFacet>): string[];

package/dist/schema/indexDifferences.js

@@ -0,0 +1,49 @@
+/**
+ * Everything an index differs by, named, or nothing when the two match.
+ *
+ * Only what both sides can state *structurally* is compared. SQL text is not: a database reprints an
+ * expression and a predicate from its parse tree, so `status IN ('a','b')` reads back as
+ * `status = ANY (ARRAY['a'::text, 'b'::text])`, `LIKE` as `~~`, and a date literal with its time zone
+ * spelled out. Folding that back needs a SQL parser, and every near-miss reports drift that no
+ * migration can settle. So a partial index's predicate is never compared, and an index over an
+ * expression has its entries left alone while the rest of it still compares.
+ */
+export function describeIndexDifferences(source, target, facets) {
+    const differences = [];
+    const comparableEntries = ![...source.entries, ...target.entries].some((entry) => entry.expression);
+    if (comparableEntries) {
+        const [sourceColumns, targetColumns] = [source.entries, target.entries].map((entries) => entries.map((entry) => entrySignature(entry, facets)).join(', '));
+        if (sourceColumns !== targetColumns) {
+            differences.push(`columns: (${targetColumns}) → (${sourceColumns})`);
+        }
+    }
+    if ((source.unique ?? false) !== (target.unique ?? false)) {
+        differences.push(`unique: ${target.unique ?? false} → ${source.unique ?? false}`);
+    }
+    if (facets.has('accessMethod') && (source.type ?? 'btree') !== (target.type ?? 'btree')) {
+        differences.push(`type: ${target.type ?? 'btree'} → ${source.type ?? 'btree'}`);
+    }
+    if (facets.has('include')) {
+        // Order carries no meaning in an `INCLUDE` list, so it is compared as a set.
+        const [sourceInclude, targetInclude] = [source.include ?? [], target.include ?? []].map((columns) => [...columns].sort().join(', '));
+        if (sourceInclude !== targetInclude) {
+            differences.push(`include: (${targetInclude}) → (${sourceInclude})`);
+        }
+    }
+    return differences;
+}
+function entrySignature(entry, facets) {
+    const parts = [entry.column];
+    if (facets.has('order')) {
+        parts.push(entry.order ?? 'asc');
+    }
+    if (facets.has('nulls')) {
+        // Postgres states this on every entry, so an entity that omits it has asked for Postgres's own
+        // default: nulls sort opposite to the direction.
+        parts.push(`nulls ${entry.nulls ?? ((entry.order ?? 'asc') === 'desc' ? 'first' : 'last')}`);
+    }
+    if (facets.has('opsClass') && entry.opsClass) {
+        parts.push(entry.opsClass);
+    }
+    return parts.join(' ');
+}

package/dist/schema/schemaAST.js

@@ -400,13 +400,7 @@ export class SchemaAST {
             const table = clone.tables.get(idx.table.name);
             if (!table)
                 continue;
-            const columns = idx.columns.map((c) => table.columns.get(c.name)).filter((c) => c !== undefined);
-            const clonedIdx = {
-                ...idx,
-                table,
-                columns,
-            };
-            clone.addIndex(clonedIdx);
+            clone.addIndex({ ...idx, table });
         }
         return clone;
     }
@@ -442,7 +436,7 @@ export class SchemaAST {
                 })),
                 indexes: t.indexes.map((i) => ({
                     name: i.name,
-                    columns: i.columns.map((c) => c.name),
+                    columns: i.entries.map((entry) => entry.column),
                     unique: i.unique,
                 })),
             })),

package/dist/schema/schemaASTBuilder.d.ts

@@ -12,7 +12,7 @@ import type { ForeignKeyAction } from './types.js';
 /**
  * Options for building SchemaAST from entities.
  */
-export interface BuildFromEntitiesOptions {
+export interface BuildSchemaASTOptions {
     /** Custom table name resolver */
     resolveTableName?: (entity: Type<unknown>, meta: EntityMeta<unknown>) => string;
     /** Custom column name resolver */
@@ -23,62 +23,9 @@ export interface BuildFromEntitiesOptions {
     defaultForeignKeyAction?: ForeignKeyAction;
 }
 /**
- * Builds SchemaAST instances from various sources.
+ * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).
+ *
+ * Three passes, because each needs the one before it to have finished for *every* entity: a relation
+ * resolves against a table another entity declares, and an index against the columns of its own.
  */
-export declare class SchemaASTBuilder {
-    private readonly namingStrategy?;
-    private readonly defaultForeignKeyAction;
-    private ast;
-    constructor(namingStrategy?: NamingStrategy | undefined, defaultForeignKeyAction?: ForeignKeyAction);
-    /**
-     * Reset the builder for a new schema.
-     */
-    reset(): this;
-    /**
-     * Get the built AST.
-     */
-    getAST(): SchemaAST;
-    /**
-     * Build AST from entity classes (decorated with @Entity, @Field, etc.)
-     */
-    fromEntities(entities: readonly Type<unknown>[], options?: BuildFromEntitiesOptions): 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.
-     */
-    private resolveColumnCanonicalType;
-    /**
-     * Add a table from entity metadata.
-     */
-    private addTableFromEntity;
-    /**
-     * Add relationships from entity relation decorators.
-     */
-    private addRelationshipsFromEntity;
-    /**
-     * Add indexes from field options (`@Field({ index })`) and from `@Index([...])`, which have nothing
-     * in common beyond their target table.
-     */
-    private addIndexesFromEntity;
-    /**
-     * One `@Index([...])`. Its entries keep the authored form (expression, prefix length, order) with
-     * names resolved, so the generator renders exactly what was declared; `columns` is the resolvable
-     * subset, which is what diffing and introspection compare.
-     */
-    private addCompositeIndex;
-}
+export declare function buildSchemaAST(entities: readonly Type<unknown>[], options?: BuildSchemaASTOptions): SchemaAST;