uql-orm 0.73.1 → 0.74.1

package/dist/dialect/vectorSqlDialect.js

@@ -1,5 +1,5 @@
-import { DEFAULT_VECTOR_DISTANCE, unsupportedVectorMetric } from '../type/vector.js';
-import { findVectorIndex, findVectorSort, vectorCandidates } from '../util/dialect.util.js';
+import { unsupportedVectorMetric } from '../type/vector.js';
+import { findVectorIndex, findVectorSort, vectorCandidates, vectorDistanceOf } from '../util/dialect.util.js';
 import { AbstractDialect } from './abstractDialect.js';
 import { encodeFloat32s } from './vectorCast.js';
 /**
@@ -44,15 +44,10 @@ export class VectorSqlDialect extends AbstractDialect {
     hasVectorIndex() {
         return [...this.vectorMetrics.values()].some((metric) => metric.index);
     }
-    /**
-     * What a distance expression reads, for a `$sort` and a `$near` alike. The metric falls back to the
-     * field's, then its index's, which serves no other, then cosine.
-     */
+    /** What a distance expression reads, for a `$sort` and a `$near` alike. */
     resolveVectorDistance(meta, key, search) {
         const field = meta.fields[key];
-        const colName = this.resolveColumnName(key, field);
-        const distance = search.$distance ?? field?.distance ?? findVectorIndex(meta, key)?.distance ?? DEFAULT_VECTOR_DISTANCE;
-        return { colName, distance, field };
+        return { colName: this.resolveColumnName(key, field), distance: vectorDistanceOf(meta, key, search), field };
     }
     /**
      * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
@@ -70,9 +65,10 @@ export class VectorSqlDialect extends AbstractDialect {
     }
     /**
      * The distance expression, in whichever of the two shapes this dialect spells it. One method for
-     * both, so the metric lookup and its refusal exist once rather than per shape.
+     * both, so the metric lookup and its refusal exist once rather than per shape. The column is read
+     * under `prefix`, the alias in scope, since a joined table may have a column of the same name.
      */
-    appendVectorDistance(ctx, meta, key, search) {
+    appendVectorDistance(ctx, meta, key, search, prefix) {
         if (this.vectorMetrics.size === 0) {
             throw new TypeError(`${this.dialectName} does not support vector similarity search. Use raw() for vector queries.`);
         }
@@ -81,14 +77,15 @@ export class VectorSqlDialect extends AbstractDialect {
         if (!metric) {
             throw unsupportedVectorMetric(this.dialectName, distance);
         }
+        const column = this.escapeId(prefix, true, true) + this.escapeId(colName);
         if ('fn' in metric) {
             const leading = metric.metricArg === undefined ? '' : `'${metric.metricArg}', `;
-            ctx.append(`${metric.fn}(${leading}${this.escapeId(colName)}, `);
+            ctx.append(`${metric.fn}(${leading}${column}, `);
             this.appendVectorValue(ctx, search.$vector, field);
             ctx.append(')');
             return;
         }
-        ctx.append(`${this.escapeId(colName)} ${metric.op} `);
+        ctx.append(`${column} ${metric.op} `);
         this.appendVectorValue(ctx, search.$vector, field);
     }
 }

package/dist/migrate/drift/driftDetector.js

@@ -199,7 +199,7 @@ function detectIndexDrifts(diff) {
                 table: idxDiff.table,
                 index: idxDiff.name,
                 details: `Index "${idxDiff.name}" exists in database but not defined in entity`,
-                suggestion: 'Add @Field({ index }) or create migration to drop',
+                suggestion: 'Declare it, or drop it via migration: generate:entities drops one uql named',
             });
         }
         else {
@@ -211,7 +211,7 @@ function detectIndexDrifts(diff) {
                 table: idxDiff.table,
                 index: idxDiff.name,
                 details: `Index "${idxDiff.name}" differs from the entity (${idxDiff.description})`,
-                suggestion: 'Drop and recreate the index via migration',
+                suggestion: 'Recreate it via migration, which generate:entities writes',
             });
         }
     }

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

@@ -33,6 +33,7 @@ export declare class MongoSchemaGenerator extends MongoDialect implements Schema
     generateDropTable(tableName: string): string;
     generateAlterTable(diff: SchemaDiff): string[];
     generateAlterTableDown(diff: SchemaDiff): string[];
+    private dropIndexCommand;
     /** An index as MongoDB's key spec (`-1` descending, `'text'` full-text), refusing the SQL-only options. */
     generateCreateIndex(tableName: string, index: IndexSchema): string;
     /** An Atlas vector search index: its vector field first, then each field a `$vectorSearch` pre-filters on. */

package/dist/migrate/generator/mongoSchemaGenerator.js

@@ -1,6 +1,7 @@
 import { getMeta } from '../../entity/index.js';
 import { MongoDialect } from '../../mongo/mongoDialect.js';
 import { textLanguage } from '../../mongo/textLanguage.js';
+import { indexChanges } from '../../schema/indexDifferences.js';
 import { QueryRaw, } from '../../type/index.js';
 import { indexDistance, unsupportedVectorMetric } from '../../type/vector.js';
 import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../../util/ddlExpression.util.js';
@@ -8,6 +9,7 @@ import { fulltextConfig, fulltextWeights } from '../../util/dialect.util.js';
 import { assertIndexFeatures, assertIndexType } from '../ddl/indexDdl.js';
 import { assertIndexPredicate, refusedIndexPredicate } from '../indexPredicate.js';
 import { renderIndexDefinition } from './definitionToNode.js';
+import { indexNodeToSchema } from './indexNodeToSchema.js';
 import { serializeMongoCommand } from './mongoCommand.js';
 /** The index types a key spec can say, a plain key or `'text'`, and Atlas's vector search index. */
 const MONGO_INDEX_TYPES = new Set(['btree', 'fulltext', 'vectorSearch']);
@@ -105,12 +107,21 @@ export class MongoSchemaGenerator extends MongoDialect {
         return serializeMongoCommand({ action: 'dropCollection', name: tableName });
     }
     generateAlterTable(diff) {
-        return (diff.indexesToAdd ?? []).map((index) => this.generateCreateIndex(diff.tableName, index));
+        return [
+            ...(diff.indexesToDrop ?? []).map((index) => this.dropIndexCommand(diff.tableName, index)),
+            ...(diff.indexesToAdd ?? []).map((index) => this.generateCreateIndex(diff.tableName, index)),
+        ];
     }
     generateAlterTableDown(diff) {
-        return (diff.indexesToAdd ?? []).map((index) => index.type === 'vectorSearch'
-            ? serializeMongoCommand({ action: 'dropSearchIndex', collection: diff.tableName, name: index.name })
-            : this.generateDropIndex(diff.tableName, index.name));
+        return [
+            ...(diff.indexesToAdd ?? []).map((index) => this.dropIndexCommand(diff.tableName, index)),
+            ...(diff.indexesToDrop ?? []).map((index) => this.generateCreateIndex(diff.tableName, index)),
+        ];
+    }
+    dropIndexCommand(tableName, index) {
+        return index.type === 'vectorSearch'
+            ? serializeMongoCommand({ action: 'dropSearchIndex', collection: tableName, name: index.name })
+            : this.generateDropIndex(tableName, index.name);
     }
     /** An index as MongoDB's key spec (`-1` descending, `'text'` full-text), refusing the SQL-only options. */
     generateCreateIndex(tableName, index) {
@@ -200,15 +211,16 @@ export class MongoSchemaGenerator extends MongoDialect {
         if (!currentTable) {
             return { tableName: collectionName, type: 'create' };
         }
-        const existingIndexes = new Set(currentTable.indexes.map((i) => i.name));
-        const indexesToAdd = this.indexesOf(meta, collectionName).filter((index) => !existingIndexes.has(index.name));
-        if (indexesToAdd.length === 0) {
+        // By name: MongoDB lists a text index's fields alphabetically, so a shape would not match its own.
+        const { toAdd, toDrop } = indexChanges(collectionName, this.indexesOf(meta, collectionName), currentTable.indexes, (index) => index.name);
+        if (!toAdd.length && !toDrop.length) {
             return undefined;
         }
         return {
             tableName: collectionName,
             type: 'alter',
-            indexesToAdd,
+            indexesToAdd: toAdd.length ? toAdd : undefined,
+            indexesToDrop: toDrop.length ? toDrop.map(indexNodeToSchema) : undefined,
         };
     }
 }

package/dist/migrate/migrator.js

@@ -189,15 +189,16 @@ export class Migrator {
             this.logger.logInfo('No schema changes detected.');
             return '';
         }
+        // Diff by diff in reverse, each rolled back in the order its generator wrote it.
         const down = [
-            ...created.map((tableName) => generator.generateDropTable(tableName, { ifExists: true })),
-            ...altered.flatMap((diff) => generator.generateAlterTableDown(diff)),
+            ...altered.toReversed().flatMap((diff) => generator.generateAlterTableDown(diff)),
+            ...created.toReversed().map((tableName) => generator.generateDropTable(tableName, { ifExists: true })),
         ];
         const { emit } = this.target.source;
         const filePath = await this.writeMigration(name, {
             docExtraLines: ['Generated from entity definitions'],
             upInner: emit(up),
-            downInner: emit(down.reverse()),
+            downInner: emit(down),
         });
         this.logger.logInfo(`Created migration from entities: ${filePath}`);
         return filePath;
@@ -345,7 +346,13 @@ export class Migrator {
                 this.logger.logSkippedMigration(`[AutoSync] Skipped altering ${filteredDiff.foreignKeysToAlter.length} foreign keys in table '${diff.tableName}': ${filteredDiff.foreignKeysToAlter.map((fk) => fk.to.name).join(', ')} (safe mode active). Use a migration or { safe: false } to apply.`);
                 delete filteredDiff.foreignKeysToAlter;
             }
-            delete filteredDiff.indexesToDrop;
+            if (filteredDiff.indexesToDrop?.length) {
+                // An index recreated under its old name is a drop and an add, held back together.
+                const dropped = new Set(filteredDiff.indexesToDrop.map((index) => index.name));
+                this.logger.logSkippedMigration(`[AutoSync] Skipped dropping ${dropped.size} indexes in table '${diff.tableName}': ${[...dropped].join(', ')} (safe mode active). Use a migration or { safe: false } to apply.`);
+                filteredDiff.indexesToAdd = filteredDiff.indexesToAdd?.filter((index) => !dropped.has(index.name));
+                delete filteredDiff.indexesToDrop;
+            }
             delete filteredDiff.foreignKeysToDrop;
         }
         if (!options.drop && filteredDiff.columnsToDrop?.length) {

package/dist/migrate/schemaGenerator.d.ts

@@ -62,12 +62,16 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     private addForeignKeyStatements;
     /** `DROP CONSTRAINT` for each of `constraintNames`, the mirror of {@link addForeignKeyStatements}. */
     private dropForeignKeyStatements;
+    /** The `ALTER COLUMN` restating each of `columns`. */
+    private alterColumnStatements;
+    /** An index added to a table that may already have rows: its `CREATE`, then what the engine needs after. */
+    private addIndexStatements;
+    /** `DROP INDEX` for each of `indexes`, the mirror of {@link addIndexStatements}. */
+    private dropIndexStatements;
     generateAlterTableDown(diff: SchemaDiff): string[];
     generateCreateIndex(tableName: string, index: IndexSchema, options?: {
         ifNotExists?: boolean;
     }): string;
-    /** An index added to a table that may already have rows: its `CREATE`, then what the engine needs after. */
-    private addIndexStatements;
     /**
      * `schema` is the table's, because that is where its indexes live. MySQL takes it from the table
      * operand instead, which is already qualified.
@@ -106,13 +110,6 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      * drift detection runs, with types normalized as the engine stores them.
      */
     diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
-    /**
-     * Indexes the entity declares that the table does not already have, in any shape.
-     *
-     * Additive only: an index the entity does not name may well have been created deliberately outside
-     * the ORM, and dropping it is a decision for a reviewed migration.
-     */
-    private missingIndexes;
     protected diffOptions(): DiffOptions;
     /** Spread, not copied field by field, so a field the node gains cannot go missing here. */
     private columnNodeToSchema;

package/dist/migrate/schemaGenerator.js

@@ -1,6 +1,6 @@
 import { getMeta } from '../entity/index.js';
 import { canonicalToSql, engineType, isVectorCategory } from '../schema/canonicalType.js';
-import { indexSignature } from '../schema/indexDifferences.js';
+import { indexChanges } from '../schema/indexDifferences.js';
 import { buildSchemaAST, resolveColumnCanonicalType } from '../schema/schemaASTBuilder.js';
 import { diffRelationshipNodes, diffTable } from '../schema/schemaASTDiffer.js';
 import { isAutoIncrement, qualifyName } from '../util/index.js';
@@ -144,40 +144,19 @@ export class SqlSchemaGenerator {
             ...(diff.foreignKeysToDrop ?? []),
             ...(diff.foreignKeysToAlter ?? []).map((it) => constraintNameOf(diff.tableName, it.from)),
         ]));
-        // Add new columns
-        if (diff.columnsToAdd?.length) {
-            for (const column of diff.columnsToAdd) {
-                this.assertColumnAddable(diff.tableName, column);
-                statements.push(this.tableDdl.addColumn(diff.tableName, this.generateColumnDefinitionFromSchema(column)));
-                statements.push(...this.generateColumnCommentStatement(diff.tableName, column, diff.schema));
-            }
-        }
-        // Alter existing columns
-        if (diff.columnsToAlter?.length) {
-            for (const { to } of diff.columnsToAlter) {
-                const colDef = this.generateColumnDefinitionFromSchema(to);
-                const colStatements = this.generateAlterColumnStatements(diff.tableName, to, colDef);
-                statements.push(...colStatements);
-            }
-        }
-        // Drop columns
-        if (diff.columnsToDrop?.length) {
-            for (const columnName of diff.columnsToDrop) {
-                statements.push(...this.tableDdl.dropColumn(diff.tableName, columnName));
-            }
-        }
-        // Add indexes
-        if (diff.indexesToAdd?.length) {
-            for (const index of diff.indexesToAdd) {
-                statements.push(...this.addIndexStatements(diff.tableName, index));
-            }
-        }
-        // Drop indexes
-        if (diff.indexesToDrop?.length) {
-            for (const indexName of diff.indexesToDrop) {
-                statements.push(this.generateDropIndex(diff.tableName, indexName, diff.schema));
-            }
-        }
+        // Before the adds, which may reuse a dropped index's name, and before the columns: some engines
+        // drop an index along with its column, which would leave nothing here to name.
+        statements.push(...this.dropIndexStatements(diff.tableName, diff.indexesToDrop, diff.schema));
+        for (const column of diff.columnsToAdd ?? []) {
+            this.assertColumnAddable(diff.tableName, column);
+            statements.push(this.tableDdl.addColumn(diff.tableName, this.generateColumnDefinitionFromSchema(column)));
+            statements.push(...this.generateColumnCommentStatement(diff.tableName, column, diff.schema));
+        }
+        statements.push(...this.alterColumnStatements(diff.tableName, (diff.columnsToAlter ?? []).map((it) => it.to)));
+        for (const columnName of diff.columnsToDrop ?? []) {
+            statements.push(...this.tableDdl.dropColumn(diff.tableName, columnName));
+        }
+        statements.push(...this.addIndexStatements(diff.tableName, diff.indexesToAdd));
         // Last, so every column it names exists by now.
         if (diff.primaryKey?.to.length) {
             statements.push(this.generateAddPrimaryKeySql(diff.tableName, diff.primaryKey.to));
@@ -198,6 +177,21 @@ export class SqlSchemaGenerator {
     dropForeignKeyStatements(tableName, constraintNames) {
         return constraintNames.map((name) => this.generateDropForeignKeySql(tableName, name));
     }
+    /** The `ALTER COLUMN` restating each of `columns`. */
+    alterColumnStatements(tableName, columns) {
+        return columns.flatMap((column) => this.generateAlterColumnStatements(tableName, column, this.generateColumnDefinitionFromSchema(column)));
+    }
+    /** An index added to a table that may already have rows: its `CREATE`, then what the engine needs after. */
+    addIndexStatements(tableName, indexes = []) {
+        return indexes.flatMap((index) => [
+            this.generateCreateIndex(tableName, index),
+            ...this.indexDdl.settleStatements(tableName, index),
+        ]);
+    }
+    /** `DROP INDEX` for each of `indexes`, the mirror of {@link addIndexStatements}. */
+    dropIndexStatements(tableName, indexes = [], schema) {
+        return indexes.map((index) => this.generateDropIndex(tableName, index.name, schema));
+    }
     generateAlterTableDown(diff) {
         const statements = [];
         // Constraints first, mirroring the up direction: the up added them last, so the down drops them
@@ -212,44 +206,26 @@ export class SqlSchemaGenerator {
         if (diff.primaryKey?.to.length) {
             statements.push(this.generateDropPrimaryKeySql(diff.tableName, derivedPrimaryKeyName(diff.tableName, diff.primaryKey.to)));
         }
-        // Reverse column additions by dropping them
-        if (diff.columnsToAdd?.length) {
-            for (const column of diff.columnsToAdd) {
-                statements.push(...this.tableDdl.dropColumn(diff.tableName, column.name));
-            }
-        }
-        // Reverse column alterations by restoring original schema
-        if (diff.columnsToAlter?.length) {
-            for (const { from } of diff.columnsToAlter) {
-                const colDef = this.generateColumnDefinitionFromSchema(from);
-                const colStatements = this.generateAlterColumnStatements(diff.tableName, from, colDef);
-                statements.push(...colStatements);
-            }
-        }
-        // Reverse index additions by dropping them
-        if (diff.indexesToAdd?.length) {
-            for (const index of diff.indexesToAdd) {
-                statements.push(this.generateDropIndex(diff.tableName, index.name, diff.schema));
-            }
+        for (const column of diff.columnsToAdd ?? []) {
+            statements.push(...this.tableDdl.dropColumn(diff.tableName, column.name));
         }
+        statements.push(...this.alterColumnStatements(diff.tableName, (diff.columnsToAlter ?? []).map((it) => it.from)));
+        statements.push(...this.dropIndexStatements(diff.tableName, diff.indexesToAdd, diff.schema));
+        statements.push(...this.addIndexStatements(diff.tableName, diff.indexesToDrop));
         if (diff.primaryKey?.from.length) {
             statements.push(this.generateAddPrimaryKeySql(diff.tableName, diff.primaryKey.from, diff.primaryKey.fromName));
         }
         // The constraint the up replaced, back under the name the database had for it. A foreign key the
         // up *dropped* is not restored: only its name survived the diff, never what it pointed at.
         statements.push(...this.addForeignKeyStatements(diff.tableName, (diff.foreignKeysToAlter ?? []).map((it) => it.from)));
-        if (diff.columnsToDrop?.length || diff.indexesToDrop?.length || diff.foreignKeysToDrop?.length) {
-            statements.push(`-- TODO: Manual reversal needed for dropped columns/indexes/foreign keys`);
+        if (diff.columnsToDrop?.length || diff.foreignKeysToDrop?.length) {
+            statements.push(`-- TODO: Manual reversal needed for dropped columns/foreign keys`);
         }
         return statements;
     }
     generateCreateIndex(tableName, index, options = {}) {
         return this.indexDdl.getCreateIndexStatement(tableName, index, options);
     }
-    /** An index added to a table that may already have rows: its `CREATE`, then what the engine needs after. */
-    addIndexStatements(tableName, index) {
-        return [this.generateCreateIndex(tableName, index), ...this.indexDdl.settleStatements(tableName, index)];
-    }
     /**
      * `schema` is the table's, because that is where its indexes live. MySQL takes it from the table
      * operand instead, which is already qualified.
@@ -351,10 +327,12 @@ export class SqlSchemaGenerator {
         }
         // Indexes are matched here rather than by the differ, which pairs them by name so that a changed
         // one reads as one index that altered. A migration needs the opposite: an index already in the
-        // table, under whatever name, must not be created again, and one whose shape differs is a
-        // separate index rather than a change - no engine alters an index's columns or uniqueness.
+        // table, under whatever name, must not be created again, and one whose shape differs is dropped
+        // and created anew - no engine alters an index's columns or uniqueness.
         const tableDiff = diffTable(desired, currentTable, { ...this.diffOptions(), compareIndexes: false });
-        const indexesToAdd = this.missingIndexes(desired, currentTable);
+        const indexes = indexChanges(currentTable.name, desired.indexes, currentTable.indexes);
+        const indexesToAdd = indexes.toAdd.map(indexNodeToSchema);
+        const indexesToDrop = indexes.toDrop.map(indexNodeToSchema);
         const columnDiffs = tableDiff?.columnDiffs ?? [];
         const columnsToAdd = columnDiffs.flatMap((it) => (it.type === 'add' ? [this.columnNodeToSchema(it.expected)] : []));
         const columnsToDrop = columnDiffs.flatMap((it) => (it.type === 'drop' ? [it.column] : []));
@@ -387,6 +365,7 @@ export class SqlSchemaGenerator {
             !columnsToAlter.length &&
             !columnsToDrop.length &&
             !indexesToAdd.length &&
+            !indexesToDrop.length &&
             !foreignKeysToAdd.length &&
             !foreignKeysToDrop.length &&
             !foreignKeysToAlter.length &&
@@ -402,21 +381,12 @@ export class SqlSchemaGenerator {
             columnsToAlter: columnsToAlter.length ? columnsToAlter : undefined,
             columnsToDrop: columnsToDrop.length ? columnsToDrop : undefined,
             indexesToAdd: indexesToAdd.length ? indexesToAdd : undefined,
+            indexesToDrop: indexesToDrop.length ? indexesToDrop : undefined,
             foreignKeysToAdd: foreignKeysToAdd.length ? foreignKeysToAdd : undefined,
             foreignKeysToDrop: foreignKeysToDrop.length ? foreignKeysToDrop : undefined,
             foreignKeysToAlter: foreignKeysToAlter.length ? foreignKeysToAlter : undefined,
         };
     }
-    /**
-     * Indexes the entity declares that the table does not already have, in any shape.
-     *
-     * Additive only: an index the entity does not name may well have been created deliberately outside
-     * the ORM, and dropping it is a decision for a reviewed migration.
-     */
-    missingIndexes(desired, currentTable) {
-        const present = new Set(currentTable.indexes.map(indexSignature));
-        return desired.indexes.filter((index) => !present.has(indexSignature(index))).map(indexNodeToSchema);
-    }
     diffOptions() {
         return {
             normalizeType: engineType(this.dialect),
@@ -563,7 +533,9 @@ export class SqlSchemaGenerator {
             case 'alterColumn':
                 return this.generateAlterColumnSql(operation.tableName, operation.columnName, operation.changes);
             case 'createIndex':
-                return this.addIndexStatements(operation.tableName, renderIndexDefinition(operation.index, (sql) => this.dialect.compileDdl(sql)));
+                return this.addIndexStatements(operation.tableName, [
+                    renderIndexDefinition(operation.index, (sql) => this.dialect.compileDdl(sql)),
+                ]);
             case 'dropIndex':
                 return [this.generateDropIndex(operation.tableName, operation.indexName)];
             case 'addForeignKey':

package/dist/mongo/mongoDialect.d.ts

@@ -130,11 +130,11 @@ export declare class MongoDialect extends AbstractDialect {
     /** Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. */
     private collectSort;
     /**
-     * The stages a `$sort` by a relation's size needs: one correlated `$lookup` tallying the relation
-     * per parent, and the `$set` that lifts the tally onto the document as the field the `$sort` then
-     * orders by. A parent with no related row gets no lookup result at all, which is a zero.
+     * The stages a `$sort` by a relation's aggregate needs - its size, or its row nearest a vector: one
+     * correlated `$lookup` reading it per parent, and the `$set` that lifts it onto the document as the
+     * field the `$sort` then orders by. A parent with no related row reads a zero tally and no distance.
      */
-    sortCountStages<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined): {
+    sortAggregateStages<E extends Document>(entity: Type<E>, sort: QuerySortMap<E> | undefined): {
         readonly stages: MongoAggregationPipelineEntry<Document>[];
         readonly fields: string[];
     };

package/dist/mongo/mongoDialect.js

@@ -1,13 +1,14 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
-import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, sortCountField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
-import { aggregateColumnField, groupPathField, resolveGroupJoins, resolveQueryJoins, resolveSortableJoin, } from '../dialect/queryJoins.js';
+import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, sortAggregateField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
+import { aggregateColumnField, groupPathField, resolveGroupJoins, relationSortTerms, resolveQueryJoins, resolveSortableJoin, } from '../dialect/queryJoins.js';
 import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/query.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { aggregateOf, asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, rankedTextSearch, someKey, targetKeyColumns, textSortOf, } from '../util/index.js';
+import { aggregateOf, asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, rankedTextSearch, someKey, targetKeyColumns, textSortOf, vectorDistanceOf, } from '../util/index.js';
 import { decodeBigIntsExcept } from '../util/wideNumber.js';
 import { textLanguage } from './textLanguage.js';
+import { vectorDistanceExpr } from './vectorDistance.js';
 /** A scalar field's operator as the aggregation operator computing it. */
 const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
 /** Default {@link DialectFeatures} for MongoDB. */
@@ -461,7 +462,8 @@ export class MongoDialect extends AbstractDialect {
      */
     sort(entity, { $sort: sort, $populate: populate, $where: where }) {
         const meta = getMeta(entity);
-        const normalized = {};
+        const nearest = {};
+        const columns = {};
         // Refused as the SQL dialects refuse it, before MongoDB answers a missing score with its own error.
         if (sort?.$text) {
             rankedTextSearch(where);
@@ -469,11 +471,13 @@ export class MongoDialect extends AbstractDialect {
         // The same join set the lookups are built from, so what an ordering may address and what the
         // pipeline actually produces cannot drift apart - `$sort` contributes its own to-one joins here
         // exactly as it does on the SQL dialects.
-        this.collectSort(meta, sort, resolveQueryJoins(meta, { $populate: populate, $sort: sort }), '', normalized);
-        return normalized;
+        const joins = resolveQueryJoins(meta, { $populate: populate, $sort: sort });
+        this.collectSort(meta, sort, joins, '', nearest, columns);
+        // A vector distance is the primary ordering wherever it appears, as on the SQL dialects.
+        return { ...nearest, ...columns };
     }
     /** Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. */
-    collectSort(meta, sort, joins, path, out) {
+    collectSort(meta, sort, joins, path, nearest, out) {
         for (const [key, value] of Object.entries(sort ?? {})) {
             const relation = meta.relations[key];
             if (key === '$text') {
@@ -485,12 +489,11 @@ export class MongoDialect extends AbstractDialect {
                 continue;
             }
             if (!relation) {
-                // The queried entity's own vector search is lifted out before this walk, so one reaching it
-                // sits under a relation, which a `$lookup` brings in one row at a time - there is nothing to
-                // rank. `sortDirection` would read the operator object as "ascending" and order by the raw
-                // vector column instead, which is the SQL dialects' rejection turned into a silent answer.
+                // The queried entity's first vector search is lifted out into `$vectorSearch` before this walk,
+                // so one reaching it is a second. `sortDirection` would read the operator object as "ascending"
+                // and order by the raw vector column instead, a silent answer where the caller asked for a rank.
                 if (isVectorSearch(value)) {
-                    throw new TypeError(`$vector sort is only supported on the queried entity, not on relation '${path.slice(0, -1)}'`);
+                    throw new TypeError(`cannot $sort by a second vector '${key}' on MongoDB: $vectorSearch ranks by one`);
                 }
                 out[path + this.pathOf(meta, key)] = sortDirection(value);
                 continue;
@@ -499,39 +502,38 @@ export class MongoDialect extends AbstractDialect {
             // one: ordering by a relation nothing looked up reads a field that is not there, which MongoDB
             // ranks as all-equal rather than rejecting. The SQL dialects can add the join themselves.
             const relPath = `${path}${key}`;
-            const countDirection = parseSortByCount(value);
-            if (countDirection !== undefined) {
-                // The tally rides on a field {@link sortCountStages} adds, which only the queried entity's
+            const { aggregates, rest } = relationSortTerms(key, relPath, value);
+            for (const { spec, direction } of aggregates) {
+                // The value rides on a field {@link sortAggregateStages} adds, which only the queried entity's
                 // own pipeline has: a nested one is built inside its parent's `$lookup`, where there is no
                 // parent document left to hang it off.
                 if (path) {
-                    throw new TypeError(`$sort by '${relPath}.$count' is only supported on the queried entity`);
+                    throw new TypeError(`$sort by '${relPath}.${spec.field ?? '$count'}' is only supported on the queried entity`);
+                }
+                if (spec.search) {
+                    nearest[sortAggregateField(spec)] = 1;
+                }
+                else {
+                    out[sortAggregateField(spec)] = sortDirection(direction);
                 }
-                out[sortCountField(key)] = sortDirection(countDirection);
+            }
+            if (rest === undefined) {
                 continue;
             }
-            const { join, sort: relationSort } = resolveSortableJoin(relation, relPath, value, joins, `cannot $sort by relation '${relPath}' on MongoDB unless it is populated: only $populate adds its fields to the document`);
-            this.collectSort(join.meta, relationSort, joins, `${relPath}.`, out);
+            const { join, sort: relationSort } = resolveSortableJoin(relation, relPath, rest, joins, `cannot $sort by relation '${relPath}' on MongoDB unless it is populated: only $populate adds its fields to the document`);
+            this.collectSort(join.meta, relationSort, joins, `${relPath}.`, nearest, out);
         }
     }
     /**
-     * The stages a `$sort` by a relation's size needs: one correlated `$lookup` tallying the relation
-     * per parent, and the `$set` that lifts the tally onto the document as the field the `$sort` then
-     * orders by. A parent with no related row gets no lookup result at all, which is a zero.
+     * The stages a `$sort` by a relation's aggregate needs - its size, or its row nearest a vector: one
+     * correlated `$lookup` reading it per parent, and the `$set` that lifts it onto the document as the
+     * field the `$sort` then orders by. A parent with no related row reads a zero tally and no distance.
      */
-    sortCountStages(entity, sort) {
+    sortAggregateStages(entity, sort) {
         const meta = getMeta(entity);
-        const stages = [];
-        const fields = [];
-        for (const [key, value] of Object.entries(sort ?? {})) {
-            const relOpts = meta.relations[key];
-            if (!relOpts || parseSortByCount(value) === undefined) {
-                continue;
-            }
-            const temp = sortCountField(key);
-            stages.push(...this.aggregateStages(meta, { relation: key, op: '$count' }, `${REL_TEMP_PREFIX}${temp}`, temp));
-            fields.push(temp);
-        }
+        const specs = Object.entries(sort ?? {}).flatMap(([key, value]) => meta.relations[key] ? relationSortTerms(key, key, value).aggregates.map(({ spec }) => spec) : []);
+        const fields = specs.map(sortAggregateField);
+        const stages = specs.flatMap((spec, index) => this.aggregateStages(meta, spec, `${REL_TEMP_PREFIX}${fields[index]}`, fields[index]));
         return { stages, fields };
     }
     /** Whether a read answers with a relation aggregate, which only the pipeline can build. */
@@ -568,15 +570,24 @@ export class MongoDialect extends AbstractDialect {
      */
     aggregateStages(meta, spec, temp, field) {
         const relOpts = relationOf(meta, spec.relation);
+        const relMeta = getMeta(relOpts.entity());
         const page = spec.page ?? {};
+        // A many-to-many's lookup runs over its junction's rows, each carrying its target: read as that
+        // target, so the page's order and the aggregate reach the target's own fields.
+        const targets = relOpts.through ? [{ $replaceRoot: { newRoot: { $arrayElemAt: [`$${REL_NESTED_KEY}`, 0] } } }] : [];
         const tail = [
+            ...targets,
             ...(page.$sort ? [{ $sort: this.sort(relOpts.entity(), page) }] : []),
             ...this.pagerStages(page),
             spec.field
                 ? {
                     $group: {
                         _id: null,
-                        [AGGREGATE_VALUE_ALIAS]: { [spec.op]: `$${this.columnOf(getMeta(relOpts.entity()), spec.field)}` },
+                        [AGGREGATE_VALUE_ALIAS]: {
+                            [spec.op]: spec.search
+                                ? vectorDistanceExpr(this.columnOf(relMeta, spec.field), spec.search.$vector, vectorDistanceOf(relMeta, spec.field, spec.search))
+                                : `$${this.columnOf(relMeta, spec.field)}`,
+                        },
                     },
                 }
                 : { $count: AGGREGATE_VALUE_ALIAS },
@@ -708,10 +719,10 @@ export class MongoDialect extends AbstractDialect {
     readStages(entity, q, extra = {}) {
         const meta = getMeta(entity);
         const joins = resolveQueryJoins(meta, q);
-        // The tally an ordering by a relation's size reads, and the field it parks it on: both belong
+        // The value an ordering by a relation's aggregate reads, and the field it parks it on: both belong
         // with the lookups, since the `$sort` right after them is what they exist for.
-        const counted = this.sortCountStages(entity, q.$sort);
-        const lookups = [...this.lookupStages(meta, joins), ...counted.stages];
+        const aggregated = this.sortAggregateStages(entity, q.$sort);
+        const lookups = [...this.lookupStages(meta, joins), ...aggregated.stages];
         // Each to-many and each `$count`, which neither drop nor reorder a row, so they read the page alone.
         const related = this.relationReadStages(entity, q);
         const sort = hasKeys(extra.sort) ? [{ $sort: extra.sort }] : [];
@@ -732,13 +743,13 @@ export class MongoDialect extends AbstractDialect {
         // which is the one way this differs from a SQL join. Taken back out once the `$sort` that needed
         // it has run, so ordering by an unpopulated relation costs the same nothing it does there.
         const sortOnly = [...joins.values()].filter((join) => !join.projected).map((join) => join.path);
-        const dropped = [...sortOnly, ...counted.fields];
+        const dropped = [...sortOnly, ...aggregated.fields];
         const unset = dropped.length ? [{ $unset: dropped }] : [];
         // The grouping collapses rows onto the columns it projects, which leaves nothing for an ordering
         // that reads a lookup those columns do not carry. Refused rather than answered all-equal, and in
         // the same terms the SQL dialects refuse `SELECT DISTINCT` ordered by an unselected column.
-        if (q.$distinct && counted.fields.length) {
-            throw new TypeError(`cannot $sort by a relation's $count with $distinct: the grouping keeps only the columns it projects`);
+        if (q.$distinct && aggregated.fields.length) {
+            throw new TypeError(`cannot $sort by a relation's aggregate with $distinct: the grouping keeps only the columns it projects`);
         }
         if (q.$distinct && sortOnly.length) {
             throw new TypeError(`cannot $sort by relation '${sortOnly[0]}' with $distinct unless '${sortOnly[0]}' is populated: the grouping keeps only the columns it projects`);

package/dist/mongo/vectorDistance.d.ts

@@ -0,0 +1,8 @@
+import type { Document } from 'mongodb';
+import type { VectorDistance } from '../type/index.js';
+/**
+ * A document's distance from `vector` as an aggregation expression, computed exactly as the SQL engines
+ * compute theirs: Atlas ranks only through its own index, which no related document reaches. `null` where
+ * the field holds no vector, or a cosine has a zero-length side, and `$min` skips a `null`.
+ */
+export declare function vectorDistanceExpr(column: string, vector: readonly number[], metric: VectorDistance): Document;