uql-orm 0.71.0 → 0.72.1

package/dist/migrate/ddl/indexDdl.js

@@ -50,6 +50,10 @@ export class IndexDdl {
             `ON ${this.dialect.escapeId(tableName)}${this.indexAccessMethod(index)} (${columns})` +
             `${this.indexInclude(index)}${this.indexTuning(index)}${this.indexPredicate(index)};`);
     }
+    /** What an index added to a table that has rows needs run after it to serve queries; nothing, mostly. */
+    settleStatements(_tableName, _index) {
+        return [];
+    }
     /**
      * Index features this dialect can express. Everything here is supported by at least one engine and
      * refused by at least one other, so an index asking for a missing one is rejected rather than

package/dist/migrate/ddl/mysqlIndexDdl.d.ts

@@ -6,6 +6,11 @@ export declare class MysqlLikeIndexDdl extends IndexDdl {
     protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
     protected readonly indexTypes: ReadonlySet<IndexType>;
     protected readonly indexTypeKeywords: ReadonlyMap<IndexType, string>;
+    /**
+     * InnoDB fills a fulltext index added beside another on a loaded table only once the table is optimized:
+     * until then MariaDB scores it 0 and MySQL can fail a `MATCH` over it (MySQL 26.7, MariaDB 12.3).
+     */
+    settleStatements(tableName: string, index: IndexSchema): string[];
     /** ` USING btree|hash` trails the columns: between the table and them, it is a syntax error here. */
     protected indexTuning(index: IndexSchema): string;
 }

package/dist/migrate/ddl/mysqlIndexDdl.js

@@ -11,6 +11,13 @@ export class MysqlLikeIndexDdl extends IndexDdl {
     indexFeatures = new Set(['expression', 'prefixLength']);
     indexTypes = new Set(['btree', 'hash', 'fulltext']);
     indexTypeKeywords = MYSQL_LIKE_INDEX_KEYWORDS;
+    /**
+     * InnoDB fills a fulltext index added beside another on a loaded table only once the table is optimized:
+     * until then MariaDB scores it 0 and MySQL can fail a `MATCH` over it (MySQL 26.7, MariaDB 12.3).
+     */
+    settleStatements(tableName, index) {
+        return index.type === 'fulltext' ? [`OPTIMIZE TABLE ${this.dialect.escapeId(tableName)};`] : [];
+    }
     /** ` USING btree|hash` trails the columns: between the table and them, it is a syntax error here. */
     indexTuning(index) {
         return index.type && !this.indexTypeKeywords.has(index.type) ? ` USING ${index.type}` : '';

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

@@ -5,6 +5,8 @@ export type MongoIndexOptions = {
     readonly unique: boolean;
     readonly name: string;
     readonly partialFilterExpression?: Readonly<Record<string, unknown>>;
+    /** A text index's weight per field, which `textScore` multiplies a match in it by. */
+    readonly weights?: Readonly<Record<string, number>>;
 };
 /** A field of an Atlas vector search index: the vector itself, or one its `filter` pre-filters on. */
 export type MongoVectorSearchField = {

package/dist/migrate/generator/mongoSchemaGenerator.js

@@ -3,6 +3,7 @@ import { MongoDialect } from '../../mongo/mongoDialect.js';
 import { QueryRaw, } from '../../type/index.js';
 import { indexDistance, unsupportedVectorMetric } from '../../type/vector.js';
 import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../../util/ddlExpression.util.js';
+import { fulltextWeights } from '../../util/dialect.util.js';
 import { assertIndexFeatures, assertIndexType } from '../ddl/indexDdl.js';
 import { assertIndexPredicate, refusedIndexPredicate } from '../indexPredicate.js';
 import { renderIndexDefinition } from './definitionToNode.js';
@@ -121,6 +122,7 @@ export class MongoSchemaGenerator extends MongoDialect {
         for (const entry of index.entries) {
             key[entry.column] = index.type === 'fulltext' ? 'text' : entry.order === 'desc' ? -1 : 1;
         }
+        const weights = fulltextWeights(index);
         return serializeMongoCommand({
             action: 'createIndex',
             collection: tableName,
@@ -130,6 +132,7 @@ export class MongoSchemaGenerator extends MongoDialect {
                 unique: index.unique,
                 name: index.name,
                 partialFilterExpression: index.where && JSON.parse(index.where),
+                weights: weights && Object.fromEntries(index.entries.map((entry, at) => [entry.column, weights[at]])),
             },
         });
     }

package/dist/migrate/introspection/mongoIntrospector.d.ts

@@ -7,7 +7,7 @@ import { type QuerierPool, type SchemaIntrospector, type TableSchema } from '../
  */
 export declare class MongoSchemaIntrospector implements SchemaIntrospector {
     private readonly pool;
-    /** `listIndexes` reports keys and uniqueness; a `partialFilterExpression` is no SQL predicate. */
+    /** `listIndexes` reports keys, uniqueness and text weights; a `partialFilterExpression` is no SQL predicate. */
     readonly indexFacets: ReadonlySet<IndexFacet>;
     constructor(pool: QuerierPool);
     introspect(tables?: readonly string[]): Promise<SchemaAST>;

package/dist/migrate/introspection/mongoIntrospector.js

@@ -8,8 +8,8 @@ const SEARCH_NOT_ENABLED = 31082;
  */
 export class MongoSchemaIntrospector {
     pool;
-    /** `listIndexes` reports keys and uniqueness; a `partialFilterExpression` is no SQL predicate. */
-    indexFacets = new Set();
+    /** `listIndexes` reports keys, uniqueness and text weights; a `partialFilterExpression` is no SQL predicate. */
+    indexFacets = new Set(['textWeights']);
     constructor(pool) {
         this.pool = pool;
     }
@@ -38,10 +38,12 @@ export class MongoSchemaIntrospector {
                 name: tableName,
                 columns: [],
                 indexes: [
-                    ...indexes.map((idx) => ({
-                        name: idx.name ?? Object.keys(idx.key).join('_'),
-                        entries: Object.keys(idx.key).map((column) => ({ column })),
-                        unique: !!idx.unique,
+                    ...indexes.map(({ name, key, unique, weights }) => ({
+                        name: name ?? Object.keys(key).join('_'),
+                        unique: !!unique,
+                        ...(weights
+                            ? { entries: Object.entries(weights).map(textIndexEntry), type: 'fulltext' }
+                            : { entries: Object.keys(key).map((column) => ({ column })) }),
                     })),
                     ...searchIndexes
                         .filter((idx) => idx.type === 'vectorSearch')
@@ -75,6 +77,10 @@ export class MongoSchemaIntrospector {
         });
     }
 }
+/** A text index field as an entity declares it: its weight stated only where it is not the default 1. */
+function textIndexEntry([column, weight]) {
+    return weight === 1 ? { column } : { column, weight };
+}
 /** A collection's Atlas search indexes, none where the server has no Atlas Search. */
 async function listSearchIndexes(collection) {
     try {

package/dist/migrate/schemaGenerator.d.ts

@@ -1,5 +1,6 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
+import { type BuildSchemaASTOptions } from '../schema/schemaASTBuilder.js';
 import { type DiffOptions } from '../schema/schemaASTDiffer.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
 import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, EntityWhereMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
@@ -65,6 +66,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     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.
@@ -175,4 +178,4 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
  * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
  * also rename an explicit `@Entity({ name })` and so compare each table under another name.
  */
-export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], defaultForeignKeyAction?: ForeignKeyAction): SchemaAST;
+export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], options?: Pick<BuildSchemaASTOptions, 'defaultForeignKeyAction' | 'textScoreIndexes'>): SchemaAST;

package/dist/migrate/schemaGenerator.js

@@ -74,7 +74,10 @@ export class SqlSchemaGenerator {
     }
     /** The entity side as an AST, carrying this generator's default referential action. */
     buildAST(entities) {
-        return buildEntityAST(this, entities, this.defaultForeignKeyAction);
+        return buildEntityAST(this, entities, {
+            defaultForeignKeyAction: this.defaultForeignKeyAction,
+            textScoreIndexes: this.dialect.features.textScoreIndexes,
+        });
     }
     /**
      * Every `CREATE TABLE` for `entities`, then their foreign keys, since a relation graph is routinely
@@ -115,7 +118,7 @@ export class SqlSchemaGenerator {
      * resolves instead of being silently dropped.
      */
     orderedTables(entities, direction, only) {
-        const ast = buildEntityAST(this, entities, this.defaultForeignKeyAction);
+        const ast = this.buildAST(entities);
         const tables = direction === 'create' ? ast.getCreateOrder() : ast.getDropOrder();
         if (!only) {
             return tables;
@@ -166,7 +169,7 @@ export class SqlSchemaGenerator {
         // Add indexes
         if (diff.indexesToAdd?.length) {
             for (const index of diff.indexesToAdd) {
-                statements.push(this.generateCreateIndex(diff.tableName, index));
+                statements.push(...this.addIndexStatements(diff.tableName, index));
             }
         }
         // Drop indexes
@@ -243,6 +246,10 @@ export class SqlSchemaGenerator {
     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.
@@ -338,7 +345,7 @@ export class SqlSchemaGenerator {
         }
         // Keyed by the qualified name this generator resolves, which is the key the AST stores the table
         // under.
-        const desired = (desiredAst ?? buildEntityAST(this, [entity], this.defaultForeignKeyAction)).getTable(tableName);
+        const desired = (desiredAst ?? this.buildAST([entity])).getTable(tableName);
         if (!desired) {
             return undefined;
         }
@@ -556,7 +563,7 @@ export class SqlSchemaGenerator {
             case 'alterColumn':
                 return this.generateAlterColumnSql(operation.tableName, operation.columnName, operation.changes);
             case 'createIndex':
-                return [this.generateCreateIndexFromDefinition(operation.tableName, operation.index)];
+                return this.addIndexStatements(operation.tableName, renderIndexDefinition(operation.index, (sql) => this.dialect.compileDdl(sql)));
             case 'dropIndex':
                 return [this.generateDropIndex(operation.tableName, operation.indexName)];
             case 'addForeignKey':
@@ -693,7 +700,7 @@ function foreignKeyOf(relation) {
  * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
  * also rename an explicit `@Entity({ name })` and so compare each table under another name.
  */
-export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
+export function buildEntityAST(generator, entities, options = {}) {
     return buildSchemaAST(entities, {
         // The alias, not `resolveTableName`: a node holds its schema separately, so that a name derived
         // from it stays a single identifier.
@@ -702,6 +709,6 @@ export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
         resolveColumnName: (key, field) => generator.resolveColumnName(key, field),
         compileDdl: (sql, entity) => generator.compileDdl(sql, entity),
         compileIndexPredicate: (where, entity, indexName) => generator.compileIndexPredicate(where, entity, indexName),
-        defaultForeignKeyAction,
+        ...options,
     });
 }

package/dist/mongo/mongoDialect.d.ts

@@ -1,6 +1,6 @@
 import { type Document, type Filter, type Sort, type UpdateFilter } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
-import type { DialectFeatures, EntityData, EntityMeta, Query, QueryAggMap, QueryAggregate, QueryExclude, QueryGroupMap, QueryOptions, QueryPager, QueryPopulate, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
+import type { DialectFeatures, EntityData, EntityMeta, Query, QueryAggMap, QueryAggregate, QueryExclude, QueryGroupMap, QueryOptions, QueryPager, QuerySelectValue, QuerySortMap, QueryVectorSearch, QueryWhere, Type } from '../type/index.js';
 import { type CallbackKey } from '../util/index.js';
 /** What a read pipeline contributes to {@link MongoDialect.readStages} beyond the query itself. */
 type MongoReadStages = {
@@ -122,7 +122,7 @@ export declare class MongoDialect extends AbstractDialect {
      * means a *populated* one, at every level of the path: a lookup adds a field to the result, so one
      * added for the sort alone would change what the caller gets back.
      */
-    sort<E extends Document>(entity: Type<E>, sort?: QuerySortMap<E>, populate?: QueryPopulate<E>): Sort;
+    sort<E extends Document>(entity: Type<E>, { $sort: sort, $populate: populate, $where: where }: Query<E>): Sort;
     /** Walks `$sort` against the metadata of the entity each level addresses, as the SQL dialects do. */
     private collectSort;
     /**
@@ -237,7 +237,7 @@ export declare class MongoDialect extends AbstractDialect {
      */
     getUpdateFilter<E extends Document>(persistable: Partial<E>): UpdateFilter<E> | Document[];
     /**
-     * A JSON update as one pipeline, since MongoDB refuses two operators on one path: each path composed as
+     * An update as one pipeline, since MongoDB refuses two operators on one path: each path composed as
      * `$pull`, `$set`, `$push`, then `$unset`, as SQL does, with values as `$literal` so `$x` stays data.
      */
     private getUpdatePipeline;

package/dist/mongo/mongoDialect.js

@@ -1,11 +1,13 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
-import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, sortCountField, } from '../dialect/aliases.js';
+import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, sortCountField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
 import { groupPathField, resolveGroupJoins, 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, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } 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, parseSortByCount, rankedTextSearch, someKey, targetKeyColumns, } from '../util/index.js';
+/** A scalar field's operator as the aggregation operator computing it. */
+const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
 /** Default {@link DialectFeatures} for MongoDB. */
 export const mongoDialectFeatures = {
     ifNotExists: false,
@@ -454,9 +456,13 @@ export class MongoDialect extends AbstractDialect {
      * means a *populated* one, at every level of the path: a lookup adds a field to the result, so one
      * added for the sort alone would change what the caller gets back.
      */
-    sort(entity, sort, populate) {
+    sort(entity, { $sort: sort, $populate: populate, $where: where }) {
         const meta = getMeta(entity);
         const normalized = {};
+        // Refused as the SQL dialects refuse it, before MongoDB answers a missing score with its own error.
+        if (sort?.$text) {
+            rankedTextSearch(where);
+        }
         // 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.
@@ -467,6 +473,13 @@ export class MongoDialect extends AbstractDialect {
     collectSort(meta, sort, joins, path, out) {
         for (const [key, value] of Object.entries(sort ?? {})) {
             const relation = meta.relations[key];
+            if (key === '$text') {
+                if (path) {
+                    throw new TypeError(`$sort by $text is only supported on the queried entity, not on relation '${path.slice(0, -1)}'`);
+                }
+                out[TEXT_SCORE_ALIAS] = { $meta: 'textScore' };
+                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
@@ -553,7 +566,7 @@ export class MongoDialect extends AbstractDialect {
         const relOpts = relationOf(meta, spec.relation);
         const query = spec.query ?? {};
         const tail = [
-            ...(query.$sort ? [{ $sort: this.sort(relOpts.entity(), query.$sort) }] : []),
+            ...(query.$sort ? [{ $sort: this.sort(relOpts.entity(), query) }] : []),
             ...this.pagerStages(query),
             spec.field
                 ? {
@@ -669,7 +682,7 @@ export class MongoDialect extends AbstractDialect {
         return [
             ...this.matchStages(entity, q.$where, opts, this.aggregateKeys(entity, q)),
             ...this.readStages(entity, q, {
-                sort: this.sort(entity, q.$sort, q.$populate),
+                sort: this.sort(entity, q),
                 pager: this.pagerStages(q),
             }),
         ];
@@ -912,8 +925,14 @@ export class MongoDialect extends AbstractDialect {
         const set = {};
         const push = {};
         const pull = {};
+        const arithmetic = {};
         const unset = new Set();
         for (const [key, value] of Object.entries(persistable)) {
+            if (isFieldUpdateOp(value)) {
+                const [op, operand] = fieldUpdateOf(value);
+                arithmetic[key] = { [MONGO_ARITHMETIC[op]]: [{ $ifNull: [`$${key}`, 0] }, { $literal: operand }] };
+                continue;
+            }
             if (!isJsonUpdateOp(value)) {
                 set[key] = value;
                 continue;
@@ -931,7 +950,7 @@ export class MongoDialect extends AbstractDialect {
                 pull[`${key}.${path}`] = v;
             }
         }
-        return { set, push, pull, unset };
+        return { set, push, pull, arithmetic, unset };
     }
     /**
      * Turn a persistable payload into a MongoDB update, mapping UQL's JSON operators onto their native
@@ -940,12 +959,12 @@ export class MongoDialect extends AbstractDialect {
      */
     getUpdateFilter(persistable) {
         const groups = this.groupUpdateOperators(persistable);
-        const { set, push, pull, unset } = groups;
+        const { set, push, pull, arithmetic, unset } = groups;
         const exprKeys = [...Object.keys(pull), ...Object.keys(set), ...Object.keys(push)];
-        // Native `$pull` fails on a value that is no array, and MongoDB rejects two operators targeting one
-        // path in a single update document: either forces the pipeline form.
+        // Native `$pull` fails on a value that is no array, native `$inc`/`$mul` on a `null`, and MongoDB
+        // rejects two operators targeting one path in a single update document: each forces the pipeline form.
         const allPaths = [...exprKeys, ...unset];
-        if (hasKeys(pull) || new Set(allPaths).size < allPaths.length) {
+        if (hasKeys(pull) || hasKeys(arithmetic) || new Set(allPaths).size < allPaths.length) {
             return this.getUpdatePipeline(groups, new Set(exprKeys));
         }
         return {
@@ -955,11 +974,11 @@ export class MongoDialect extends AbstractDialect {
         };
     }
     /**
-     * A JSON update as one pipeline, since MongoDB refuses two operators on one path: each path composed as
+     * An update as one pipeline, since MongoDB refuses two operators on one path: each path composed as
      * `$pull`, `$set`, `$push`, then `$unset`, as SQL does, with values as `$literal` so `$x` stays data.
      */
-    getUpdatePipeline({ set, push, pull, unset }, exprPaths) {
-        const assignments = {};
+    getUpdatePipeline({ set, push, pull, arithmetic, unset }, exprPaths) {
+        const assignments = { ...arithmetic };
         for (const path of exprPaths) {
             let expr = { $ifNull: [`$${path}`, []] };
             if (path in pull) {

package/dist/mongo/mongodbQuerier.js

@@ -93,7 +93,7 @@ export class MongodbQuerier extends AbstractQuerier {
         if (hasKeys(select)) {
             cursor.project(select);
         }
-        const sort = this.dialect.sort(entity, q.$sort, q.$populate);
+        const sort = this.dialect.sort(entity, q);
         if (hasKeys(sort)) {
             cursor.sort(sort);
         }
@@ -119,7 +119,7 @@ export class MongodbQuerier extends AbstractQuerier {
             ...(scoreAlias ? [{ $addFields: { [scoreAlias]: { $meta: 'vectorSearchScore' } } }] : []),
             // `$vectorSearch` has already applied `$limit`, so the pager is its own.
             ...this.dialect.readStages(entity, q, {
-                sort: this.dialect.sort(entity, vectorSort.regularSort, q.$populate),
+                sort: this.dialect.sort(entity, { ...q, $sort: vectorSort.regularSort }),
                 project: scoreAlias ? { [scoreAlias]: 1 } : undefined,
             }),
         ];
@@ -189,7 +189,6 @@ export class MongodbQuerier extends AbstractQuerier {
         return this.timed('internalUpdateMany', undefined, async () => {
             const persistable = this.dialect.getPersistable(getMeta(entity), payload, 'onUpdate');
             const filter = this.dialect.where(entity, qm.$where, opts);
-            // Maps JSON operators ($set/$unset/$push/$pull) onto their native MongoDB equivalents.
             const update = this.dialect.getUpdateFilter(persistable);
             const { matchedCount } = await this.execute((session) => this.collection(entity).updateMany(filter, update, { session }));
             return matchedCount;

package/dist/mssql/mssqlDialect.js

@@ -34,6 +34,7 @@ const MSSQL_FEATURES = {
     rowLocks: true,
     rowLockWithWindow: true,
     rowLockOf: true,
+    textScoreIndexes: false,
     orderedUpsertReturning: false,
     orderedJsonAggregates: true,
     narrowVectorTypes: false,

package/dist/schema/indexDifferences.d.ts

@@ -2,8 +2,9 @@ import type { IndexNode } from './types.js';
 /**
  * What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits.
  * `vector` is whether it is a vector index at all, for an engine with one vector index whatever type declared it.
+ * `textWeights` is a text index's weights, kept by an engine that lists its fields in no declared order.
  */
-export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector';
+export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'textWeights';
 /**
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
  * over an expression, whose text the engine reprints, falls back to its name.

package/dist/schema/indexDifferences.js

@@ -35,7 +35,7 @@ export function describeIndexDifferences(source, target, facets) {
     const differences = [];
     const comparableEntries = ![...source.entries, ...target.entries].some((entry) => entry.expression || entry.jsonPath || entry.jsonArray);
     if (comparableEntries) {
-        const [sourceColumns, targetColumns] = [source.entries, target.entries].map((entries) => entries.map((entry) => entrySignature(entry, facets)).join(', '));
+        const [sourceColumns, targetColumns] = [source, target].map((index) => textFieldOrder(index, facets, index.entries.map((entry) => entrySignature(entry, facets))).join(', '));
         if (sourceColumns !== targetColumns) {
             differences.push(`columns: (${targetColumns}) -> (${sourceColumns})`);
         }
@@ -59,6 +59,10 @@ export function describeIndexDifferences(source, target, facets) {
     }
     return differences;
 }
+/** A text index's fields as a set where the engine keeps its weights: MongoDB lists them alphabetically. */
+function textFieldOrder(index, facets, entries) {
+    return facets.has('textWeights') && index.type === 'fulltext' ? entries.toSorted() : entries;
+}
 function entrySignature(entry, facets) {
     const parts = [entry.column];
     if (facets.has('order')) {
@@ -72,5 +76,8 @@ function entrySignature(entry, facets) {
     if (facets.has('opsClass') && entry.opsClass) {
         parts.push(entry.opsClass);
     }
+    if (facets.has('textWeights') && (entry.weight ?? 1) !== 1) {
+        parts.push(`weight ${entry.weight}`);
+    }
     return parts.join(' ');
 }

package/dist/schema/schemaASTBuilder.d.ts

@@ -24,6 +24,8 @@ export interface BuildSchemaASTOptions {
     compileDdl?: (sql: EntityWhereMeta<object>, entity: Type<object>) => string;
     /** A partial index's predicate as the engine writes it, `compileDdl` where none is given. `buildEntityAST` supplies it. */
     compileIndexPredicate?: (where: EntityWhereMeta<object>, entity: Type<object>, indexName: string) => string;
+    /** Whether a weighted fulltext index declares one of its own for each heavier column, as MySQL scores through one. */
+    textScoreIndexes?: boolean;
 }
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).

package/dist/schema/schemaASTBuilder.js

@@ -1,5 +1,6 @@
 import { fieldOf, foreignKeysOf, getMeta, soleIdOf } from '../entity/metadata/definition.js';
 import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../util/ddlExpression.util.js';
+import { fulltextWeights, textWeightSteps } from '../util/dialect.util.js';
 import { isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
 import { isAutoIncrement } from '../util/field.util.js';
@@ -26,6 +27,7 @@ export function buildSchemaAST(entities, options = {}) {
         defaultForeignKeyAction: options.defaultForeignKeyAction ?? DEFAULT_FOREIGN_KEY_ACTION,
         compileDdl,
         compileIndexPredicate: options.compileIndexPredicate ?? compileDdl,
+        textScoreIndexes: options.textScoreIndexes ?? false,
     };
     for (const pass of [addTableFromEntity, addRelationshipsFromEntity, addIndexesFromEntity]) {
         for (const entity of entities) {
@@ -213,4 +215,25 @@ function addCompositeIndex(ctx, table, meta, idxMeta) {
         lists: idxMeta.lists,
         config: idxMeta.config,
     });
+    if (ctx.textScoreIndexes) {
+        addTextScoreIndexes(ctx, table, idxMeta.type, resolved);
+    }
+}
+/** A fulltext index of its own for each column heavier than the index's lightest, which its score reads. */
+function addTextScoreIndexes(ctx, table, type, entries) {
+    const weights = fulltextWeights({ type, entries });
+    if (!weights)
+        return;
+    const { extra } = textWeightSteps(weights);
+    entries.forEach((entry, at) => {
+        if (extra[at] && typeof entry.column === 'string') {
+            ctx.ast.addIndex({
+                name: derivedIndexName(table.name, [entry.column, 'score']),
+                table,
+                entries: [{ column: entry.column }],
+                unique: false,
+                type: 'fulltext',
+            });
+        }
+    });
 }

package/dist/sqlite/sqliteDialect.d.ts

@@ -67,6 +67,8 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      * FTS5 virtual table (UQL does not create those; declare it outside your entities).
      */
     protected appendTextSearch<E>(ctx: QueryContext, entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    /** FTS5's `BM25` of the match, lower for a better one, so negated to rank as every other engine does. */
+    protected appendTextScore<E>(ctx: QueryContext, meta: EntityMeta<E>): void;
     protected jsonLength(slot: JsonSlot): string;
     /** `JSON_EACH` walks the array at the path itself, each element's `fullkey` naming it from the column. */
     protected jsonElemFrom(slot: JsonSlot, alias: string): string;

package/dist/sqlite/sqliteDialect.js

@@ -27,6 +27,7 @@ export const SQLITE_FEATURES = {
     rowLocks: false,
     rowLockWithWindow: true,
     rowLockOf: true,
+    textScoreIndexes: false,
     orderedUpsertReturning: true,
     orderedJsonAggregates: true,
     narrowVectorTypes: false,
@@ -163,6 +164,10 @@ export class SqliteDialect extends AbstractSqlDialect {
         ctx.append(`${this.escapedTableName(meta)} MATCH {${columns.join(' ')}} : `);
         ctx.addValue(search.$value);
     }
+    /** FTS5's `BM25` of the match, lower for a better one, so negated to rank as every other engine does. */
+    appendTextScore(ctx, meta) {
+        ctx.append(`-BM25(${this.escapedTableName(meta)})`);
+    }
     jsonLength(slot) {
         return `JSON_ARRAY_LENGTH(${jsonArraySlotArgs(slot, this.jsonIsArray(slot))})`;
     }

package/dist/type/dialect.d.ts

@@ -142,6 +142,11 @@ export interface SqlDialectFeatures extends DialectFeatures {
     readonly rowLockWithWindow: boolean;
     /** Whether a lock can be narrowed to one table of a join, `FOR UPDATE OF`, which MariaDB lacks. */
     readonly rowLockOf: boolean;
+    /**
+     * Whether a fulltext index's heavier column needs a fulltext index of its own to be scored by, as
+     * MySQL's `MATCH` does, which reads only an index over exactly its columns.
+     */
+    readonly textScoreIndexes: boolean;
     /** Whether a multi-row upsert's `RETURNING` lists its rows in payload order; where not, the ids are read back. */
     readonly orderedUpsertReturning: boolean;
     /** Whether a JSON aggregate takes an `ORDER BY` of its own; where not, a relation's rows keep their derived table's order. */

package/dist/type/entity.d.ts

@@ -2,7 +2,7 @@ import type { EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js
 import type { FilterOptions, RelationQuery } from './query.js';
 import type { ColumnRef, QueryRaw, RelationAggregate } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
-import type { Except, IsMany, Json, Scalar, Type, Unpacked, Writable } from './utility.js';
+import type { Except, ExactlyOne, IsEqual, IsMany, Json, Scalar, Type, Unpacked, Writable } from './utility.js';
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
 export declare const idKey: unique symbol;
@@ -20,19 +20,13 @@ export type Key<E> = keyof E & string;
 export type FieldKey<E> = {
     readonly [K in keyof E]-?: [NonNullable<E[K]>] extends [Scalar | readonly Scalar[] | Json | readonly Json[]] ? K : never;
 }[Key<E>];
-/**
- * Whether `A` and `B` are the same type, `readonly` included - which no conditional sees, since
- * assignability ignores the modifier. Two identical generic signatures compare equal only when their
- * deferred bodies do.
- */
-type IfEquals<A, B, Yes, No> = (<T>() => T extends A ? 1 : 2) extends <T>() => (T extends B ? 1 : 2) ? Yes : No;
 /**
  * The fields a caller writes: every one the class does not declare `readonly`. A field the database
  * writes - a relation aggregate, a stored generated column, a trigger-kept stamp - is `readonly`, and
  * its value never reaches the database, so a write payload leaves it out rather than dropping it.
  */
 export type WritableKey<E> = {
-    readonly [K in FieldKey<E>]-?: IfEquals<Pick<E, K>, Writable<Pick<E, K>>, K, never>;
+    readonly [K in FieldKey<E>]-?: IsEqual<Pick<E, K>, Writable<Pick<E, K>>> extends true ? K : never;
 }[FieldKey<E>];
 /** A whole-record write as a caller supplies one: {@link EntityData} without the fields it cannot write. */
 export type EntityWrite<E> = EntityData<E, WritableKey<E>>;
@@ -110,8 +104,17 @@ export type JsonUpdateOp<T = unknown> = {
  * operators would address keys it does not have (engines disagree on what that does).
  */
 type JsonUpdateOpFor<V, T = UnwrapJson<NonNullable<V>>> = [T] extends [never] ? never : IsMany<T> extends true ? never : JsonUpdateOp<T>;
-/** What an update takes beyond the value: `null` to clear an optional member, `raw` SQL, and JSON operators. */
-type UpdateExtra<V, Raw> = (undefined extends V ? null : never) | Raw | JsonUpdateOpFor<V>;
+/**
+ * A scalar field's update operator, as {@link JsonUpdateOp} is a JSON field's, computed in the statement:
+ * `$inc` adds, `$mul` multiplies, a NULL counting as 0 on every engine. One per field, since their order
+ * would change the result. A `bigint` steps by a `bigint`, exactly.
+ * @example `{ stock: { $inc: -1 } }`
+ */
+export type FieldUpdateOp<T extends number | bigint = number | bigint> = ExactlyOne<Record<'$inc' | '$mul', T>>;
+/** The {@link FieldUpdateOp} a field takes: `never` on one it has no operator for, which is any but a number. */
+type FieldUpdateOpFor<V> = [NonNullable<V>] extends [number] ? FieldUpdateOp<number> : [NonNullable<V>] extends [bigint] ? FieldUpdateOp<bigint> : never;
+/** What an update takes beyond the value: `null` to clear an optional member, `raw` SQL, and update operators. */
+type UpdateExtra<V, Raw> = (undefined extends V ? null : never) | Raw | JsonUpdateOpFor<V> | FieldUpdateOpFor<V>;
 /**
  * What a whole-record write persists: the fields and relations with their declared optionality, a
  * related row's alike, and no methods. Two mapped types, since asking each key costs a conditional.
@@ -560,6 +563,11 @@ export type IndexColumnModifiers = {
     readonly nulls?: 'first' | 'last';
     /** Operator class, e.g. `jsonb_path_ops` for a smaller GIN index. Postgres only. */
     readonly opsClass?: string;
+    /**
+     * How many times a match in this column of a fulltext index counts in `$sort: { $text }`, 1 by default:
+     * a whole number from 1 to 99999, the range MongoDB weighs by.
+     */
+    readonly weight?: number;
     /** Index a path inside a JSON column. See {@link IndexJsonPath}. */
     readonly jsonPath?: IndexJsonPath;
     /** Index every element of a JSON array. See {@link IndexJsonArray}. */

package/dist/type/query.d.ts

@@ -130,15 +130,22 @@ export type QuerySortByCount = {
     $count: QuerySortDirection;
 };
 /**
- * A sort by fields, JSON paths, a to-one relation's fields, a to-many's `$count`, or a vector distance,
- * which `Vector` confines to the queried entity. One mapped type over the key sets: an intersection is
- * checked once per member, which made this the costliest type to check.
+ * Ordering by relevance to the `$text` at the root of `$where`: most relevant first, the one order every
+ * engine ranks by (MongoDB's `textScore` sorts no other way).
+ */
+export type QuerySortByText = {
+    $text?: -1 | 'desc';
+};
+/**
+ * A sort by fields, JSON paths, a to-one relation's fields, a to-many's `$count`, or a vector distance or
+ * `$text` relevance, which `Vector` confines to the queried entity. One mapped type over the key sets: an
+ * intersection is checked once per member, which made this the costliest type to check.
  */
 export type QuerySortMap<E, Vector extends boolean = true, K extends keyof E = FieldKey<E> | RelationKey<E>> = {
     [P in K]?: P extends RelationKey<E> ? IsMany<E[P]> extends true ? QuerySortByCount : QuerySortMap<RelationTarget<E[P]>, false> : Vector extends true ? NonNullable<E[P]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection;
 } & ([JsonFieldPaths<E>] extends [never] ? unknown : {
     [P in JsonFieldPaths<E>]?: QuerySortDirection;
-});
+}) & (Vector extends true ? QuerySortByText : unknown);
 /**
  * pager options.
  */