uql-orm 0.72.0 → 0.72.2

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/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.
+ * `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';
+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.
@@ -35,11 +36,17 @@ 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})`);
         }
     }
+    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}`);
     }
@@ -59,6 +66,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('textIndex') && index.type === 'fulltext' ? entries.toSorted() : entries;
+}
 function entrySignature(entry, facets) {
     const parts = [entry.column];
     if (facets.has('order')) {
@@ -72,5 +83,8 @@ function entrySignature(entry, facets) {
     if (facets.has('opsClass') && entry.opsClass) {
         parts.push(entry.opsClass);
     }
+    if (facets.has('textIndex') && (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

@@ -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,12 +63,12 @@ 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 appendTextRank<E>(ctx: QueryContext, meta: EntityMeta<E>): void;
+    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

@@ -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,
@@ -27,6 +36,7 @@ export const SQLITE_FEATURES = {
     rowLocks: false,
     rowLockWithWindow: true,
     rowLockOf: true,
+    textScoreIndexes: false,
     orderedUpsertReturning: true,
     orderedJsonAggregates: true,
     narrowVectorTypes: false,
@@ -155,16 +165,16 @@ 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. */
-    appendTextRank(ctx, meta) {
+    appendTextScore(ctx, meta) {
         ctx.append(`-BM25(${this.escapedTableName(meta)})`);
     }
     jsonLength(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

@@ -563,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,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,4 +1,5 @@
-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 { 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 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>[];
@@ -171,8 +172,31 @@ export declare function assertAggregateColumns(clauseMap: object, emitted: Reado
 export declare function fulltextConfig(index: {
     readonly config?: string;
 }): string;
+/**
+ * Each column's weight in a fulltext index, 1 where it states none, or none at all where they are alike.
+ * Checked wherever it is read, so the migration, the search and its rank refuse the same declaration.
+ */
+export declare function fulltextWeights(index: {
+    readonly type?: IndexType;
+    readonly entries: readonly {
+        readonly weight?: number;
+    }[];
+}): readonly number[] | undefined;
+/**
+ * A weighted fulltext index's lightest weight, and what each column weighs beyond it: the score over every
+ * column counts the lightest, and a column weighing more adds its own score times the rest.
+ */
+export declare function textWeightSteps(weights: readonly number[]): {
+    lightest: number;
+    extra: 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

@@ -456,12 +456,49 @@ const DEFAULT_TEXT_CONFIG = 'simple';
 export function fulltextConfig(index) {
     return index.config ?? DEFAULT_TEXT_CONFIG;
 }
+/** The largest weight MongoDB's text index takes, which truncates a fraction to the whole number below. */
+const MAX_TEXT_WEIGHT = 99_999;
+/**
+ * Each column's weight in a fulltext index, 1 where it states none, or none at all where they are alike.
+ * Checked wherever it is read, so the migration, the search and its rank refuse the same declaration.
+ */
+export function fulltextWeights(index) {
+    if (!index.entries.some((entry) => entry.weight !== undefined)) {
+        return undefined;
+    }
+    if (index.type !== 'fulltext') {
+        throw new TypeError(`a column weight ranks a fulltext index, and this one is ${index.type ?? 'btree'}`);
+    }
+    const weights = index.entries.map(({ weight = 1 }) => {
+        if (!Number.isInteger(weight) || weight < 1 || weight > MAX_TEXT_WEIGHT) {
+            throw new TypeError(`a column weight is a whole number from 1 to ${MAX_TEXT_WEIGHT}, not ${weight}`);
+        }
+        return weight;
+    });
+    return new Set(weights).size > 1 ? weights : undefined;
+}
+/**
+ * A weighted fulltext index's lightest weight, and what each column weighs beyond it: the score over every
+ * column counts the lightest, and a column weighing more adds its own score times the rest.
+ */
+export function textWeightSteps(weights) {
+    const lightest = Math.min(...weights);
+    return { lightest, extra: weights.map((weight) => weight - lightest) };
+}
 /** The fulltext index over exactly `fields`, in order, which a search of them is served by. */
 export function fulltextIndexOver(meta, fields) {
     return meta.indexes?.find((index) => index.type === 'fulltext' &&
         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;

package/dist/util/wideNumber.js

@@ -9,14 +9,18 @@ export function decodeWideNumber(value) {
     return Math.abs(decoded) <= Number.MAX_SAFE_INTEGER ? decoded : String(value);
 }
 /**
- * {@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 function decodeBigInts(row) {
+    return decodeBigIntsExcept(row, () => false);
+}
+/** {@link decodeBigInts}, keeping the cells `exact` names: what MongoDB reads a `BigInt` field into. */
+export function decodeBigIntsExcept(row, exact) {
     for (const key in row) {
         const value = row[key];
-        if (typeof value === 'bigint') {
+        if (typeof value === 'bigint' && !exact(key)) {
             row[key] = decodeWideNumber(value);
         }
     }

package/package.json

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