uql-orm 0.72.1 → 0.72.2

package/dist/dialect/pgLikeSqlDialect.js

@@ -129,15 +129,15 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
      * index over these fields, which the planner serves it from. `WEBSEARCH_TO_TSQUERY` takes free-form
      * input (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `TO_TSQUERY`.
      */
-    appendTextSearch(ctx, _entity, meta, search) {
-        const { document, query } = this.textSearchParts(meta, search);
+    appendTextSearch(ctx, meta, search, prefix) {
+        const { document, query } = this.textSearchParts(meta, search, prefix);
         ctx.append(`${document} @@ ${query}`);
         ctx.addValue(search.$value);
         ctx.append(')');
     }
     /** `TS_RANK` of the document over `keys` against the same search the match reads. */
-    appendTextScore(ctx, meta, search, keys) {
-        const { document, query } = this.textSearchParts(meta, search, keys);
+    appendTextScore(ctx, meta, search, keys, prefix) {
+        const { document, query } = this.textSearchParts(meta, search, prefix, keys);
         ctx.append(`TS_RANK(${document}, ${query}`);
         ctx.addValue(search.$value);
         ctx.append('))');
@@ -146,13 +146,12 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
      * The document over `keys` and the search itself, open for its value, under the `$config` asked for,
      * else that of the fulltext index over every field searched, which is what serves the match.
      */
-    textSearchParts(meta, search, keys) {
+    textSearchParts(meta, search, prefix, keys) {
         const fields = textSearchFields(meta, search);
         const index = fulltextIndexOver(meta, fields);
         const config = search.$config ?? (index && fulltextConfig(index));
-        const columns = (keys ?? fields).map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
         return {
-            document: this.textSearchTarget(columns, config),
+            document: this.textSearchTarget(this.textColumns(meta, keys ?? fields, prefix), config),
             query: `${this.textQueryFn}(${this.textConfigArg(config)}`,
         };
     }

package/dist/dialect/queryJoins.d.ts

@@ -1,4 +1,5 @@
-import type { EntityMeta, Query, QueryGroupMap, QuerySortMap, QueryWhere, RelationMeta, RelationQuery, Type } from '../type/index.js';
+import type { EntityMeta, FieldMeta, Query, QueryGroupMap, QuerySortMap, QueryWhere, RelationMeta, RelationQuery, Type } from '../type/index.js';
+import { type ParsedGroupEntry } from '../util/index.js';
 /**
  * One relation a statement joins, keyed by the alias its columns are addressed by (`tax`,
  * `tax.category`). `projected` tells a `$populate` join, whose columns are selected, from one only
@@ -56,6 +57,15 @@ export declare function groupPathField(joins: QueryJoins, path: readonly string[
     readonly key: string;
     readonly join: QueryJoin | undefined;
 };
+/**
+ * The field an aggregate's column reads as, and the join it reads it through, none for the entity's own:
+ * a group key's, or the one a `$sum`, `$min` or `$max` aggregates. None at all for `$count` and `$avg`,
+ * which the engine widens to a number whatever they read.
+ */
+export declare function aggregateColumnField<E>(meta: EntityMeta<E>, joins: QueryJoins, entry: ParsedGroupEntry<E>): {
+    readonly field: FieldMeta | undefined;
+    readonly join?: QueryJoin;
+} | undefined;
 /**
  * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
  * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or

package/dist/dialect/queryJoins.js

@@ -53,6 +53,20 @@ export function groupPathField(joins, path) {
     }
     return { key, join };
 }
+/**
+ * The field an aggregate's column reads as, and the join it reads it through, none for the entity's own:
+ * a group key's, or the one a `$sum`, `$min` or `$max` aggregates. None at all for `$count` and `$avg`,
+ * which the engine widens to a number whatever they read.
+ */
+export function aggregateColumnField(meta, joins, entry) {
+    if (entry.kind === 'fn') {
+        return entry.op === '$count' || entry.op === '$avg'
+            ? undefined
+            : { field: meta.fields[entry.fieldRef] };
+    }
+    const { key, join } = groupPathField(joins, entry.path);
+    return join ? { field: join.meta.fields[key], join } : { field: meta.fields[key] };
+}
 /**
  * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
  * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or

package/dist/dialect/vectorSqlDialect.d.ts

@@ -51,11 +51,6 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      * rather than naming a type the engine does not define.
      */
     supportedVectorType(cast: VectorCast): VectorCast;
-    /**
-     * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to
-     * `appendVectorDistance` so each dialect's distance syntax is written once.
-     */
-    protected appendVectorProjection<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
     /**
      * 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.

package/dist/dialect/vectorSqlDialect.js

@@ -1,6 +1,5 @@
 import { DEFAULT_VECTOR_DISTANCE, unsupportedVectorMetric } from '../type/vector.js';
 import { findVectorIndex, findVectorSort, vectorCandidates } from '../util/dialect.util.js';
-import { entityName } from '../util/object.util.js';
 import { AbstractDialect } from './abstractDialect.js';
 import { encodeFloat32s } from './vectorCast.js';
 /**
@@ -69,20 +68,6 @@ export class VectorSqlDialect extends AbstractDialect {
     supportedVectorType(cast) {
         return this.features.narrowVectorTypes ? cast : 'vector';
     }
-    /**
-     * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to
-     * `appendVectorDistance` so each dialect's distance syntax is written once.
-     */
-    appendVectorProjection(ctx, meta, key, search) {
-        const alias = search.$project;
-        // `$project` names a new column, so it cannot be one the entity already has: both come back
-        // under that name and the driver keeps whichever it read last. Checked here rather than in the
-        // type because TypeScript cannot say "any string except these".
-        if (meta.fields[alias]) {
-            throw new TypeError(`$project '${alias}' collides with a field of '${entityName(meta)}'`);
-        }
-        this.appendVectorDistance(ctx, meta, key, search);
-    }
     /**
      * 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.

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

@@ -7,6 +7,8 @@ export type MongoIndexOptions = {
     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>>;
+    /** The language a text index stems and drops stop words in, a search's own `$language` aside. */
+    readonly default_language?: string;
 };
 /** 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

@@ -1,9 +1,9 @@
 import { getMeta } from '../../entity/index.js';
-import { MongoDialect } from '../../mongo/mongoDialect.js';
+import { MongoDialect, textLanguage } 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 { 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';
@@ -133,6 +133,7 @@ export class MongoSchemaGenerator extends MongoDialect {
                 name: index.name,
                 partialFilterExpression: index.where && JSON.parse(index.where),
                 weights: weights && Object.fromEntries(index.entries.map((entry, at) => [entry.column, weights[at]])),
+                default_language: index.type === 'fulltext' ? textLanguage(fulltextConfig(index)) : undefined,
             },
         });
     }

package/dist/migrate/introspection/mongoIntrospector.js

@@ -1,3 +1,4 @@
+import { textConfigOf } from '../../mongo/mongoDialect.js';
 import { createTableNode, SchemaAST } from '../../schema/schemaAST.js';
 import { isMongoQuerier, } from '../../type/index.js';
 /** What a server without Atlas Search answers a search index command with. */
@@ -9,7 +10,7 @@ const SEARCH_NOT_ENABLED = 31082;
 export class MongoSchemaIntrospector {
     pool;
     /** `listIndexes` reports keys, uniqueness and text weights; a `partialFilterExpression` is no SQL predicate. */
-    indexFacets = new Set(['textWeights']);
+    indexFacets = new Set(['textIndex']);
     constructor(pool) {
         this.pool = pool;
     }
@@ -38,11 +39,15 @@ export class MongoSchemaIntrospector {
                 name: tableName,
                 columns: [],
                 indexes: [
-                    ...indexes.map(({ name, key, unique, weights }) => ({
+                    ...indexes.map(({ name, key, unique, weights, default_language }) => ({
                         name: name ?? Object.keys(key).join('_'),
                         unique: !!unique,
                         ...(weights
-                            ? { entries: Object.entries(weights).map(textIndexEntry), type: 'fulltext' }
+                            ? {
+                                entries: Object.entries(weights).map(textIndexEntry),
+                                type: 'fulltext',
+                                config: default_language && textConfigOf(default_language),
+                            }
                             : { entries: Object.keys(key).map((column) => ({ column })) }),
                     })),
                     ...searchIndexes

package/dist/mongo/mongoDialect.d.ts

@@ -7,14 +7,25 @@ type MongoReadStages = {
     /** Ordering, which runs after the lookups when it reads one of their fields. */
     readonly sort?: Sort;
     readonly pager?: MongoAggregationPipelineEntry<Document>[];
-    /** Keys merged into the query's projection, when it has one: a vector search's score. */
-    readonly project?: Record<string, 1>;
+    /** A score the read answers as a field, a vector search's or a text search's; a temporary one leaves again. */
+    readonly score?: {
+        readonly field: string;
+        readonly meta: 'vectorSearchScore' | 'textScore';
+        readonly temporary?: boolean;
+    };
 };
 /** Accumulator threaded through `$where` rendering: the relation lookups it needs, and their temp fields. */
 type RelationLookups = {
     readonly stages: MongoAggregationPipelineEntry<Document>[];
     readonly temps: string[];
 };
+/**
+ * A text-search config as MongoDB names the language: the same word for each language both know, and
+ * `'none'` for the no-stemming parser Postgres calls `'simple'`. {@link textConfigOf} reads one back.
+ */
+export declare function textLanguage(config: string): string;
+/** A MongoDB language as the text-search config it is, the inverse of {@link textLanguage}. */
+export declare function textConfigOf(language: string): string;
 /** Default {@link DialectFeatures} for MongoDB. */
 export declare const mongoDialectFeatures: DialectFeatures;
 export declare class MongoDialect extends AbstractDialect {
@@ -220,6 +231,8 @@ export declare class MongoDialect extends AbstractDialect {
     normalizeIds<E extends Document>(meta: EntityMeta<E>, docs: Document[]): E[];
     /** `doc` is the wire shape - `_id`, stored names, `ObjectId`s - and what comes back is the code's. */
     normalizeId<E extends Document>(meta: EntityMeta<E>, doc: Document | undefined): E | undefined;
+    /** An aggregate's rows with each 64-bit integer decoded as a document's is: a `bigint` only where the column reads a `BigInt` field. */
+    normalizeAggregateRows<E extends Document, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>, R extends Document>(entity: Type<E>, q: QueryAggregate<E, G, A>, rows: R[]): R[];
     /**
      * A key as MongoDB stores it: a 24-hex string as an `ObjectId`, so a write matches the filter looking for
      * it, and anything else as given. Only 24-hex, not any 12-byte string. Arrays convert element-wise.

package/dist/mongo/mongoDialect.js

@@ -1,13 +1,25 @@
 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 { groupPathField, resolveGroupJoins, resolveQueryJoins, resolveSortableJoin, } from '../dialect/queryJoins.js';
+import { aggregateColumnField, 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, 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';
+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 { decodeBigIntsExcept } from '../util/wideNumber.js';
 /** A scalar field's operator as the aggregation operator computing it. */
 const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
+/**
+ * A text-search config as MongoDB names the language: the same word for each language both know, and
+ * `'none'` for the no-stemming parser Postgres calls `'simple'`. {@link textConfigOf} reads one back.
+ */
+export function textLanguage(config) {
+    return config === 'simple' ? 'none' : config;
+}
+/** A MongoDB language as the text-search config it is, the inverse of {@link textLanguage}. */
+export function textConfigOf(language) {
+    return language === 'none' ? 'simple' : language;
+}
 /** Default {@link DialectFeatures} for MongoDB. */
 export const mongoDialectFeatures = {
     ifNotExists: false,
@@ -99,7 +111,8 @@ export class MongoDialect extends AbstractDialect {
             else if (key === '$text') {
                 // MongoDB's text index declares which fields it covers, so `$fields` cannot narrow the search
                 // the way it does elsewhere - the same shape as `$distance` being index-defined here.
-                filter['$text'] = { $search: val.$value };
+                const { $value, $config } = val;
+                filter['$text'] = { $search: $value, ...($config && { $language: textLanguage($config) }) };
             }
             else if (meta.relations[key]) {
                 this.assertNoRaw(val);
@@ -477,7 +490,8 @@ export class MongoDialect extends AbstractDialect {
                 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' };
+                const { order, project } = textSortOf(sort);
+                out[project ?? TEXT_SCORE_ALIAS] = sortDirection(order);
                 continue;
             }
             if (!relation) {
@@ -679,11 +693,14 @@ export class MongoDialect extends AbstractDialect {
         return this.columnOf(meta, key.slice(0, dot)) + key.slice(dot);
     }
     aggregationPipeline(entity, q, opts) {
+        // Sorted as a field, which goes either way where a `$meta` sort only descends.
+        const text = textSortOf(q.$sort);
         return [
             ...this.matchStages(entity, q.$where, opts, this.aggregateKeys(entity, q)),
             ...this.readStages(entity, q, {
                 sort: this.sort(entity, q),
                 pager: this.pagerStages(q),
+                score: text && { field: text.project ?? TEXT_SCORE_ALIAS, meta: 'textScore', temporary: !text.project },
             }),
         ];
     }
@@ -709,10 +726,17 @@ export class MongoDialect extends AbstractDialect {
         const related = this.relationReadStages(entity, q);
         const sort = hasKeys(extra.sort) ? [{ $sort: extra.sort }] : [];
         const pager = extra.pager ?? [];
-        // Merged into the query's own projection rather than standing in for one: a query that asked
-        // for no columns wants the whole document, not just the field this adds to it.
+        // The score becomes a real field before anything reads it, so the lookups, the sort and the projection
+        // that follow treat it like any other; merged into the query's own projection rather than standing in
+        // for one, since a query that asked for no columns wants the whole document as well.
+        const { score } = extra;
+        if (score && !score.temporary) {
+            this.assertProjectable(meta, score.field);
+        }
+        const scored = score ? [{ $addFields: { [score.field]: { $meta: score.meta } } }] : [];
+        const unscored = score?.temporary ? [{ $unset: [score.field] }] : [];
         const projection = this.pipelineProjection(entity, q);
-        const projected = projection ? { ...projection, ...extra.project } : undefined;
+        const projected = projection && score ? { ...projection, [score.field]: 1 } : projection;
         const project = projected ? [{ $project: projected }] : [];
         // A `$lookup` the ordering asked for puts a field on the document the caller never requested,
         // which is the one way this differs from a SQL join. Taken back out once the `$sort` that needed
@@ -734,7 +758,7 @@ export class MongoDialect extends AbstractDialect {
         // ordering and the page have to run after it to address the set the caller actually receives.
         const dedup = q.$distinct ? this.distinctStages(projected) : [];
         if (dedup.length) {
-            return [...lookups, ...related, ...project, ...dedup, ...sort, ...pager];
+            return [...scored, ...lookups, ...related, ...project, ...dedup, ...sort, ...pager, ...unscored];
         }
         // A `$required` relation drops parents when it unwinds, and an ordering may read a field only a
         // lookup produces: either one puts the lookups first, as an INNER JOIN does. Otherwise paging
@@ -742,10 +766,12 @@ export class MongoDialect extends AbstractDialect {
         const lookupsFirst = this.sortsRelations(entity, q.$sort) ||
             lookups.some((stage) => stage.$unwind?.preserveNullAndEmptyArrays === false);
         return [
+            ...scored,
             ...(lookupsFirst ? [...lookups, ...sort, ...pager] : [...sort, ...pager, ...lookups]),
             ...related,
             ...unset,
             ...project,
+            ...unscored,
         ];
     }
     /**
@@ -894,6 +920,9 @@ export class MongoDialect extends AbstractDialect {
                 res[key] = this.fromWireId(res[key]);
             }
         }
+        // A 64-bit integer, which the pool reads as a `bigint`: kept for a `BigInt` field, and elsewhere the
+        // number it is where exact and its exact text past 2^53, as every SQL driver decodes one.
+        decodeBigIntsExcept(res, (key) => meta.fields[key]?.type === BigInt);
         const relKeys = getKeys(meta.relations).filter((key) => res[key]);
         for (const relKey of relKeys) {
             const relMeta = getMeta(relationOf(meta, relKey).entity());
@@ -903,6 +932,18 @@ export class MongoDialect extends AbstractDialect {
         }
         return res;
     }
+    /** An aggregate's rows with each 64-bit integer decoded as a document's is: a `bigint` only where the column reads a `BigInt` field. */
+    normalizeAggregateRows(entity, q, rows) {
+        const meta = getMeta(entity);
+        const { joins } = resolveGroupJoins(meta, q);
+        const exact = new Set(parseGroupMap(q.$group, q.$select)
+            .filter((entry) => aggregateColumnField(meta, joins, entry)?.field?.type === BigInt)
+            .map((entry) => entry.alias));
+        for (const row of rows) {
+            decodeBigIntsExcept(row, (key) => exact.has(key));
+        }
+        return rows;
+    }
     /**
      * A key as MongoDB stores it: a 24-hex string as an `ObjectId`, so a write matches the filter looking for
      * it, and anything else as given. Only 24-hex, not any 12-byte string. Arrays convert element-wise.

package/dist/mongo/mongodbQuerier.js

@@ -2,7 +2,7 @@ import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
 import { hasRequiredJoin } from '../dialect/queryJoins.js';
 import { fieldOf, getMeta, namesKey, soleIdOf } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
-import { clone, getKeys, getSoftDeleteValue, hasKeys, populatesRelations, throwNoPendingTransaction, throwPendingTransaction, vectorCandidates, withoutSoftDeleteFilter, } from '../util/index.js';
+import { clone, getKeys, getSoftDeleteValue, hasKeys, populatesRelations, textSortOf, throwNoPendingTransaction, throwPendingTransaction, vectorCandidates, withoutSoftDeleteFilter, } from '../util/index.js';
 /**
  * `$limit: 0` asks for no rows, the way it does on every SQL dialect - but MongoDB reads `limit(0)`
  * as *unlimited*, so a read that passed it straight to the driver came back with the whole
@@ -77,7 +77,8 @@ export class MongodbQuerier extends AbstractQuerier {
             populatesRelations(getMeta(entity), q.$populate) ||
             this.dialect.constrainsRelations(entity, q.$where) ||
             this.dialect.sortsRelations(entity, q.$sort) ||
-            this.dialect.readsAggregates(entity, q));
+            this.dialect.readsAggregates(entity, q) ||
+            textSortOf(q.$sort) !== undefined);
     }
     buildScalarProjection(entity, q) {
         return this.dialect.select(entity, q.$select, q.$exclude);
@@ -114,20 +115,18 @@ export class MongodbQuerier extends AbstractQuerier {
         const scoreAlias = vectorSort.vectorSearch.$project;
         return [
             this.dialect.buildVectorSearchStage(entity, vectorSort.vectorKey, vectorSort.vectorSearch, q.$where, q.$limit ?? 10, opts, vectorCandidates(q)),
-            // The score becomes a real field before anything reads it, so the lookups and the projection
-            // that follow treat it like any other - and a query with no projection keeps its own columns.
-            ...(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, { ...q, $sort: vectorSort.regularSort }),
-                project: scoreAlias ? { [scoreAlias]: 1 } : undefined,
+                score: scoreAlias ? { field: scoreAlias, meta: 'vectorSearchScore' } : undefined,
             }),
         ];
     }
     async internalAggregate(entity, q, opts) {
         return this.timed('internalAggregate', undefined, async () => {
             const pipeline = this.dialect.buildAggregateStages(entity, q, opts);
-            return this.execute((session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
+            const rows = await this.execute((session) => this.collection(entity).aggregate(pipeline, { session }).toArray());
+            return this.dialect.normalizeAggregateRows(entity, q, rows);
         });
     }
     /**

package/dist/mongo/mongodbQuerierPool.js

@@ -7,7 +7,10 @@ export class MongodbQuerierPool extends AbstractQuerierPool {
     client;
     constructor(uri, opts, extra) {
         super(new MongoDialect(dialectOptionsFrom(extra)), extra);
-        this.client = new MongoClient(uri, opts);
+        // A 64-bit integer read as the exact `bigint` it is, where the driver would round it past 2^53 or
+        // hand back its own `Long`; each read then decodes it the way every SQL driver does. First, as the
+        // MySQL pool's `supportBigNumbers` is, so an explicit choice of the caller's wins.
+        this.client = new MongoClient(uri, { useBigInt64: true, ...opts });
     }
     async getQuerier() {
         const conn = await this.client.connect();

package/dist/schema/indexDifferences.d.ts

@@ -2,9 +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.
+ * `textIndex` is a text index's weights and language, kept by an engine that lists its fields in no declared order.
  */
-export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'textWeights';
+export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'textIndex';
 /**
  * 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

@@ -1,4 +1,5 @@
 import { isVectorIndexType } from '../type/vector.js';
+import { fulltextConfig } from '../util/dialect.util.js';
 /**
  * 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.
@@ -40,6 +41,12 @@ export function describeIndexDifferences(source, target, facets) {
             differences.push(`columns: (${targetColumns}) -> (${sourceColumns})`);
         }
     }
+    if (facets.has('textIndex') && source.type === 'fulltext' && target.type === 'fulltext') {
+        const [expected, actual] = [fulltextConfig(source), fulltextConfig(target)];
+        if (expected !== actual) {
+            differences.push(`config: ${actual} -> ${expected}`);
+        }
+    }
     if (source.unique !== target.unique) {
         differences.push(`unique: ${target.unique} -> ${source.unique}`);
     }
@@ -61,7 +68,7 @@ export function describeIndexDifferences(source, target, facets) {
 }
 /** 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;
+    return facets.has('textIndex') && index.type === 'fulltext' ? entries.toSorted() : entries;
 }
 function entrySignature(entry, facets) {
     const parts = [entry.column];
@@ -76,7 +83,7 @@ function entrySignature(entry, facets) {
     if (facets.has('opsClass') && entry.opsClass) {
         parts.push(entry.opsClass);
     }
-    if (facets.has('textWeights') && (entry.weight ?? 1) !== 1) {
+    if (facets.has('textIndex') && (entry.weight ?? 1) !== 1) {
         parts.push(`weight ${entry.weight}`);
     }
     return parts.join(' ');

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,6 +1,6 @@
 import { AbstractSqlDialect, type DerivedRelation, type HydrateKind, type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
-import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryPager, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type Type, type VectorDistance, type VectorMetric } from '../type/index.js';
+import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryPager, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type VectorDistance, type VectorMetric } from '../type/index.js';
 /** What SQLite and the engines derived from it have. */
 export declare const SQLITE_FEATURES: SqlDialectFeatures;
 export declare class SqliteDialect extends AbstractSqlDialect {
@@ -63,10 +63,10 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
     protected hydrateKind(field: FieldOptions | undefined): HydrateKind | undefined;
     /**
-     * FTS5 matches the table itself rather than its columns, so this only works when the table *is* an
-     * FTS5 virtual table (UQL does not create those; declare it outside your entities).
+     * FTS5 matches the table itself, so this works only where the table *is* an FTS5 virtual table (UQL does
+     * not create those; declare it outside your entities). The whole query is bound, column filter and all.
      */
-    protected appendTextSearch<E>(ctx: QueryContext, entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    protected appendTextSearch<E>(ctx: QueryContext, 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;

package/dist/sqlite/sqliteDialect.js

@@ -6,6 +6,15 @@ import { indexDistance, isVectorIndexType } from '../type/vector.js';
 import { declaredIndexName } from '../util/ddlExpression.util.js';
 import { findVectorIndex, findVectorSort, textSearchFields, vectorCandidates } from '../util/dialect.util.js';
 import { columnFamily, isIntegerColumn } from '../util/field.util.js';
+/**
+ * An FTS5 query over `columns` for what a person typed: each word a quoted string, which FTS5 reads as a
+ * term to match and never as syntax, and every one required, as the other engines read plain words.
+ */
+function ftsQuery(columns, value) {
+    const quote = (text) => `"${text.replaceAll('"', '""')}"`;
+    const words = value.split(/\s+/).filter(Boolean);
+    return `{${columns.map(quote).join(' ')}} : (${words.map(quote).join(' ') || '""'})`;
+}
 /** What SQLite and the engines derived from it have. */
 export const SQLITE_FEATURES = {
     ifNotExists: true,
@@ -156,13 +165,13 @@ export class SqliteDialect extends AbstractSqlDialect {
         return columnFamily(field?.type) === 'date' ? undefined : super.hydrateKind(field);
     }
     /**
-     * FTS5 matches the table itself rather than its columns, so this only works when the table *is* an
-     * FTS5 virtual table (UQL does not create those; declare it outside your entities).
+     * FTS5 matches the table itself, so this works only where the table *is* an FTS5 virtual table (UQL does
+     * not create those; declare it outside your entities). The whole query is bound, column filter and all.
      */
-    appendTextSearch(ctx, entity, meta, search) {
-        const columns = textSearchFields(meta, search).map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
-        ctx.append(`${this.escapedTableName(meta)} MATCH {${columns.join(' ')}} : `);
-        ctx.addValue(search.$value);
+    appendTextSearch(ctx, meta, search) {
+        const columns = textSearchFields(meta, search).map((key) => this.resolveColumnName(key, meta.fields[key]));
+        ctx.append(`${this.escapedTableName(meta)} MATCH `);
+        ctx.addValue(ftsQuery(columns, 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) {

package/dist/type/query.d.ts

@@ -130,12 +130,20 @@ export type QuerySortByCount = {
     $count: QuerySortDirection;
 };
 /**
- * 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).
+ * Ordering by relevance to the `$text` at the root of `$where`, in either direction as any key sorts. The
+ * object form also answers it under the name `$project` gives it, most relevant first unless `$order` says.
  */
 export type QuerySortByText = {
-    $text?: -1 | 'desc';
+    $text?: QuerySortDirection | {
+        readonly $project: string;
+        readonly $order?: QuerySortDirection;
+    };
 };
+/**
+ * A row with the relevance a `$sort: { $text: { $project } }` names, which is not inferred:
+ * `(await querier.findMany(Post, q)) as WithScore<Post, 'score'>[]`.
+ */
+export type WithScore<E, K extends string> = E & Record<K, number>;
 /**
  * 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

package/dist/type/queryWhere.d.ts

@@ -16,8 +16,9 @@ export type QueryTextSearchOptions<E> = {
      */
     $fields?: QuerySelect<E>;
     /**
-     * Postgres text-search configuration (e.g. `'english'`), applied to both the document and the
-     * query. Defaults to the server's `default_text_search_config`. Ignored by other dialects.
+     * The language the search is parsed in (e.g. `'english'`, or `'simple'` for no stemming), else that of
+     * the fulltext index over its fields: the Postgres family's text-search config, MongoDB's `$language`.
+     * MySQL and SQLite parse by their index alone.
      */
     $config?: string;
 };

package/dist/util/dialect.util.d.ts

@@ -1,5 +1,5 @@
 import type { IndexType } from '../schema/types.js';
-import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload } from '../type/index.js';
+import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 /** The keys of `payload` a write persists as columns. */
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
@@ -192,6 +192,11 @@ export declare function textWeightSteps(weights: readonly number[]): {
 };
 /** The fulltext index over exactly `fields`, in order, which a search of them is served by. */
 export declare function fulltextIndexOver<E>(meta: EntityMeta<E>, fields: readonly string[]): EntityIndexMeta<E> | undefined;
+/** How a `$sort` orders by `$text`: its direction, and the name it answers the relevance under, if any. */
+export declare function textSortOf<E>(sort: QuerySortMap<E> | undefined): {
+    readonly order: QuerySortDirection;
+    readonly project?: string;
+} | undefined;
 /**
  * The search a `$sort` by `$text` ranks by: the one at the root of the same query's `$where`. A nested or
  * negated one has no score to order by, and MongoDB scores only the one `$text` it allows.

package/dist/util/dialect.util.js

@@ -491,6 +491,14 @@ export function fulltextIndexOver(meta, fields) {
         index.columns.length === fields.length &&
         index.columns.every((entry, at) => entry.column === fields[at]));
 }
+/** How a `$sort` orders by `$text`: its direction, and the name it answers the relevance under, if any. */
+export function textSortOf(sort) {
+    const text = sort?.$text;
+    if (text === undefined) {
+        return undefined;
+    }
+    return isRecord(text) ? { order: text.$order ?? 'desc', project: text.$project } : { order: text };
+}
 /**
  * The search a `$sort` by `$text` ranks by: the one at the root of the same query's `$where`. A nested or
  * negated one has no score to order by, and MongoDB scores only the one `$text` it allows.

package/dist/util/wideNumber.d.ts

@@ -7,8 +7,10 @@ import type { RawRow } from '../type/index.js';
  */
 export declare function decodeWideNumber(value: string | bigint): number | string;
 /**
- * {@link decodeWideNumber} over every `bigint` cell of a row, for the drivers that hand a BIGINT back
- * as one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In place: the row is the driver's fresh
- * object, and a copy per row cost more than the decode it carried.
+ * {@link decodeWideNumber} over every `bigint` cell of a row, for the drivers that hand a BIGINT back as
+ * one (`bun:sql`, `mariadb`, and every SQLite driver but D1). In place: the row is the driver's fresh
+ * object, and a copy per row cost more than the decode it carried. One argument, so it maps rows as is.
  */
 export declare function decodeBigInts(row: RawRow): RawRow;
+/** {@link decodeBigInts}, keeping the cells `exact` names: what MongoDB reads a `BigInt` field into. */
+export declare function decodeBigIntsExcept(row: RawRow, exact: (key: string) => boolean): RawRow;