uql-orm 0.70.0 → 0.72.0

package/dist/turso/tursoLocalDialect.js

@@ -1,7 +1,7 @@
 import { TursoDialect } from './tursoDialect.js';
 /**
  * SQLite Dialect specialization for the embedded Turso engine, the Rust engine alone: it adds a
- * dot-product distance to libSQL's cosine and L2, and caps no function call.
+ * dot-product distance to libSQL's cosine and L2, caps no function call, and has no vector index.
  */
 export class TursoLocalDialect extends TursoDialect {
     vectorMetrics = new Map([

package/dist/turso/tursoLocalQuerierPool.d.ts

@@ -1,15 +1,14 @@
 import type { connect } from '@tursodatabase/database';
-import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
-import { type SqliteDatabase, SqliteQuerier } from '../sqlite/sqliteQuerier.js';
+import { AbstractLocalSqliteQuerierPool } from '../sqlite/localSqliteQuerierPool.js';
+import type { SqliteDatabase } from '../sqlite/sqliteQuerier.js';
 import type { ExtraOptions } from '../type/index.js';
 import { TursoLocalDialect } from './tursoLocalDialect.js';
 /** The engine's own options: `readonly`, `timeout`, `encryption`, `experimental` and the rest. */
 export type TursoLocalOptions = NonNullable<Parameters<typeof connect>[1]>;
 /** A pool for the embedded Turso engine, on `uql-orm/turso/local` so its native binaries stay out of edge bundles. */
-export declare class TursoLocalQuerierPool extends AbstractSharedHandleQuerierPool<SqliteDatabase, SqliteQuerier, TursoLocalDialect> {
+export declare class TursoLocalQuerierPool extends AbstractLocalSqliteQuerierPool<SqliteDatabase, TursoLocalDialect> {
     readonly filename: string;
     readonly opts?: TursoLocalOptions | undefined;
     constructor(filename?: string, opts?: TursoLocalOptions | undefined, extra?: ExtraOptions);
-    protected openDb(): Promise<SqliteDatabase>;
-    protected buildQuerier(db: SqliteDatabase): SqliteQuerier;
+    protected createDb(): Promise<SqliteDatabase>;
 }

package/dist/turso/tursoLocalQuerierPool.js

@@ -1,10 +1,8 @@
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
-import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
-import { applySqlitePragmas } from '../sqlite/sqlitePragmas.js';
-import { SqliteQuerier } from '../sqlite/sqliteQuerier.js';
+import { AbstractLocalSqliteQuerierPool } from '../sqlite/localSqliteQuerierPool.js';
 import { TursoLocalDialect } from './tursoLocalDialect.js';
 /** A pool for the embedded Turso engine, on `uql-orm/turso/local` so its native binaries stay out of edge bundles. */
-export class TursoLocalQuerierPool extends AbstractSharedHandleQuerierPool {
+export class TursoLocalQuerierPool extends AbstractLocalSqliteQuerierPool {
     filename;
     opts;
     constructor(filename = ':memory:', opts, extra) {
@@ -12,15 +10,10 @@ export class TursoLocalQuerierPool extends AbstractSharedHandleQuerierPool {
         this.filename = filename;
         this.opts = opts;
     }
-    async openDb() {
+    async createDb() {
         const { connect } = await import('@tursodatabase/database');
         const db = await connect(this.filename, this.opts);
-        // Integers as `bigint`, which the querier decodes exactly past 2^53.
         db.defaultSafeIntegers(true);
-        await applySqlitePragmas(db);
         return db;
     }
-    buildQuerier(db) {
-        return new SqliteQuerier(db, this.dialect, this.extra);
-    }
 }

package/dist/type/dialect.d.ts

@@ -107,6 +107,11 @@ export interface DialectFeatures {
     readonly vectorIndexRequiresNotNull: boolean;
     /** Whether the dialect requires/allows (n) length constraints on vector types. */
     readonly vectorSupportsLength: boolean;
+    /**
+     * Whether a vector binds as its packed little-endian float32 bytes, which a blob column holds and the
+     * SQLite family and MariaDB read, rather than as `[1,2,3]` text they would reparse per row.
+     */
+    readonly vectorBytes: boolean;
     /** Whether the dialect natively supports the TIMESTAMPTZ alias/type. */
     readonly supportsTimestamptz: boolean;
     /**

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.
@@ -504,15 +507,26 @@ export type HookRegistration = {
     readonly methodName: string;
 };
 /**
- * An index type with the metric it needs: a vector index has to name one, since engines default to
- * a different one than the queries use, and any other index names none.
+ * An index type with what it needs: a vector index has to name its metric, since engines default to a
+ * different one than the queries use; an Atlas `vectorSearch` index may, else takes its field's, else
+ * cosine; a `fulltext` one may name the text-search `config` it parses with; and any other index neither.
  */
 export type IndexTypeOptions = {
     type: VectorIndexType;
     distance: VectorDistance;
+    config?: never;
+} | {
+    type: 'vectorSearch';
+    distance?: VectorDistance;
+    config?: never;
+} | {
+    type: 'fulltext';
+    distance?: never;
+    config?: string;
 } | {
-    type?: Exclude<IndexType, VectorIndexType>;
+    type?: Exclude<IndexType, VectorIndexType | 'vectorSearch' | 'fulltext'>;
     distance?: never;
+    config?: never;
 };
 /** One index entry as the migration builder takes it: a column name, `raw`, or an object when it needs more. */
 export type IndexColumnInput = string | QueryRaw | EntityIndexColumn;

package/dist/type/migration.d.ts

@@ -1,9 +1,8 @@
-import type { VectorCast } from '../dialect/vectorCast.js';
 import type { AnyMigrationOperation } from '../migrate/builder/types.js';
 import type { IndexFacet } from '../schema/indexDifferences.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import type { ColumnNode, ForeignKeyAction, IndexType, TableNode } from '../schema/types.js';
-import type { EntityMeta, EntityWhereMeta, FieldOptions, IndexColumnSchema, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
+import type { EntityMeta, EntityWhereMeta, FieldOptions, IndexColumnSchema, IndexedVectorField, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
 /**
  * Defines a migration using a simple object literal. `Q` is `MongoQuerier` for a MongoDB migration.
  */
@@ -133,7 +132,12 @@ export interface TableSchema {
 /**
  * Represents an index in a database table
  */
-export interface IndexSchema extends VectorIndexOptions {
+export interface IndexSchema extends VectorIndexOptions, IndexedVectorField {
+    /**
+     * A `fulltext` index's text-search configuration, which `$text` parses with on the Postgres family
+     * (`'english'`); `'simple'` where unstated. Other engines take their language from elsewhere.
+     */
+    readonly config?: string;
     readonly name: string;
     /**
      * What the index is over, in order. Named `entries` and not `columns` because an entry need not be
@@ -149,12 +153,6 @@ export interface IndexSchema extends VectorIndexOptions {
     readonly where?: string;
     /** Non-key columns stored in the index (Postgres-wire `INCLUDE`). */
     readonly include?: readonly string[];
-    /**
-     * The indexed column's vector type, which pgvector's operator-class names are built from
-     * (`halfvec_cosine_ops`). Absent for a non-vector index, and for an index whose column types are
-     * unknown, where `vector` is assumed.
-     */
-    readonly vectorType?: VectorCast;
 }
 /**
  * A foreign key constraint, wherever one is described: read back by introspection, planned into a

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.
  */

package/dist/type/queryAggregate.d.ts

@@ -2,7 +2,7 @@ import type { FieldKey, RelationKey, RelationTarget } from './entity.js';
 import type { QueryPager, QuerySelect, QuerySortDirection } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
-import type { IsMany, RejectKeys } from './utility.js';
+import type { ExactlyOne, IsMany, RejectKeys } from './utility.js';
 /** The columns `$group` names by a literal `true`, so an uninferred `$group`, its own constraint, names none. */
 type GroupedKeys<G> = {
     [K in keyof G]: G[K] extends true ? K : never;
@@ -37,13 +37,6 @@ export declare function resolveAggregateOp(key: string): {
     op: QueryAggregateOp;
     distinct: boolean;
 };
-/**
- * Exactly one key of `T` with its value; every other key is forbidden (`never`). `Pick`, not `Record`,
- * so the chosen key stays linked to `T`'s own property and renames follow it through.
- */
-type ExactlyOne<T> = {
-    [K in keyof T]: Readonly<Pick<T, K>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
-}[keyof T];
 /**
  * One field named as a key - `{ amount: true }` - the way a statement names every field, so an editor
  * rename reaches it where a string never would. `F` narrows which fields qualify.
@@ -122,16 +115,12 @@ type QueryGroupSchema<E, G> = Readonly<QuerySelect<E, FieldKey<E>, true>> & {
     readonly [K in Exclude<NamedKeys<G>, FieldKey<E>>]: QueryGroupRef<E>;
 } & RejectKeys<Exclude<GroupedKeys<G>, FieldKey<E>>>;
 /**
- * The value a path reads: the field's own type, or through a relation, `null` where the row points nowhere.
- * `any` answers `unknown`: TypeScript checks a deferred type by instantiating it with `any`, which would
- * walk every relation of the entity on every aggregate call, quadrupling what one costs to check.
+ * The value a path reads: the field at its end as its column holds it, `null` only where that does, since
+ * the path joins the rows it reads. `any` answers `unknown`: TypeScript checks a deferred type by
+ * instantiating it with `any`, which would walk every relation of the entity on every aggregate call.
  */
 type GroupRefValue<E, Ref> = 0 extends 1 & Ref ? unknown : {
-    [K in keyof Ref & keyof E]: Ref[K] extends true ? E[K] : NonNullable<GroupRefLeaf<RelationTarget<E[K]>, Ref[K]>> | null;
-}[keyof Ref & keyof E];
-/** The field at the end of a path, whose type {@link GroupRefValue} widens with `null`; `any` as it does. */
-type GroupRefLeaf<E, Ref> = 0 extends 1 & Ref ? unknown : {
-    [K in keyof Ref & keyof E]: Ref[K] extends true ? E[K] : GroupRefLeaf<RelationTarget<E[K]>, Ref[K]>;
+    [K in keyof Ref & keyof E]: Ref[K] extends true ? Exclude<E[K], undefined> : GroupRefValue<RelationTarget<E[K]>, Ref[K]>;
 }[keyof Ref & keyof E];
 /** Computed columns by the alias each is read back under: `{ count: { $count: '*' }, avgAge: { $avg: { age: true } } }`. */
 export type QueryAggMap<E> = {

package/dist/type/utility.d.ts

@@ -30,6 +30,12 @@ export type ExpandScalar<T> = T extends Date ? Date | string : T;
 export interface RawRow {
     [key: string]: unknown;
 }
+/**
+ * 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.
+ */
+export type IsEqual<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => (T extends B ? 1 : 2) ? true : false;
 export type Writable<T> = {
     -readonly [K in keyof T]: T[K];
 };
@@ -46,6 +52,13 @@ export type Except<T, K extends keyof T> = {
  * excess-property check on one.
  */
 export type RejectKeys<K> = [K] extends [never] ? unknown : Record<K & string, never>;
+/**
+ * Exactly one key of `T` with its value; every other key is forbidden (`never`). `Pick`, not `Record`,
+ * so the chosen key stays linked to `T`'s own property and renames follow it through.
+ */
+export type ExactlyOne<T> = {
+    [K in keyof T]: Readonly<Pick<T, K>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
+}[keyof T];
 export type Unpacked<T> = T extends readonly (infer U)[] ? U : T extends (...args: unknown[]) => infer U ? U : T extends Promise<infer U> ? U : T;
 /**
  * Whether the value a property holds is many rather than one: a to-many relation, a scalar array, a

package/dist/type/vector.d.ts

@@ -1,3 +1,4 @@
+import type { VectorCast } from '../dialect/vectorCast.js';
 import type { IndexType } from '../schema/types.js';
 /**
  * A vector search's metric: `cosine` (the default), `l2`, `inner` product or `l1`. No hamming: every
@@ -55,6 +56,22 @@ export type VectorIndexOptions = {
     /** IVFFlat: number of inverted lists. */
     lists?: number;
 };
+/** The metric a search or an index measures by where nothing names one: every engine with vectors has it. */
+export declare const DEFAULT_VECTOR_DISTANCE: VectorDistance;
+/** The metric an index is built for: its own, else {@link DEFAULT_VECTOR_DISTANCE}. */
+export declare function indexDistance(index: {
+    readonly distance?: VectorDistance;
+}): VectorDistance;
+/**
+ * What a vector index's DDL reads off the field it indexes, never declared on the index itself, so the
+ * two cannot disagree. Absent for a non-vector index, and for one whose field is unknown.
+ */
+export type IndexedVectorField = {
+    /** The field's vector type, which pgvector's operator classes are named after (`halfvec_cosine_ops`); `vector` where absent. */
+    readonly vectorType?: VectorCast;
+    /** The field's dimensions, which an Atlas vector search index states. */
+    readonly dimensions?: number;
+};
 /**
  * Index types whose emitted DDL depends on the distance metric. The runtime list is the source, so
  * the type and every dialect's "do I have this one?" answer cannot drift from each other.

package/dist/type/vector.js

@@ -5,6 +5,12 @@ export function unsupportedVectorMetric(dialectName, distance, indexName) {
     const where = indexName === undefined ? '' : ` (index "${indexName}")`;
     return new TypeError(`${dialectName} does not support vector distance metric: ${distance}${where}`);
 }
+/** The metric a search or an index measures by where nothing names one: every engine with vectors has it. */
+export const DEFAULT_VECTOR_DISTANCE = 'cosine';
+/** The metric an index is built for: its own, else {@link DEFAULT_VECTOR_DISTANCE}. */
+export function indexDistance(index) {
+    return index.distance ?? DEFAULT_VECTOR_DISTANCE;
+}
 /**
  * Index types whose emitted DDL depends on the distance metric. The runtime list is the source, so
  * the type and every dialect's "do I have this one?" answer cannot drift from each other.

package/dist/util/ddlExpression.util.d.ts

@@ -10,3 +10,5 @@ export declare function declaredIndexes<E>(meta: EntityMeta<E>): EntityIndexMeta
 export declare function renderIndexColumn(entry: EntityIndexColumn, render: (sql: QueryRaw) => string): IndexColumnSchema;
 /** What an unnamed index's name is built from: each entry's column, or `expr<n>` for an expression, which has none. */
 export declare function indexNameParts(entries: readonly EntityIndexColumn[]): string[];
+/** The name an index is created and read by: its own, else one derived from its table and its entries' columns. */
+export declare function declaredIndexName(name: string | undefined, table: string, entries: readonly EntityIndexColumn[]): string;

package/dist/util/ddlExpression.util.js

@@ -1,5 +1,6 @@
 import { ColumnRef, QueryRaw, } from '../type/index.js';
 import { definedEntries } from './object.util.js';
+import { derivedIndexName } from './sql.util.js';
 /**
  * Reduces an authored index entry to the form metadata keeps, so a column, an expression and an options
  * object reach the schema as one: a column read off the refs as its key, any other `raw` as it is.
@@ -30,3 +31,7 @@ export function renderIndexColumn(entry, render) {
 export function indexNameParts(entries) {
     return entries.map((entry, at) => (typeof entry.column === 'string' ? entry.column : `expr${at}`));
 }
+/** The name an index is created and read by: its own, else one derived from its table and its entries' columns. */
+export function declaredIndexName(name, table, entries) {
+    return name ?? derivedIndexName(table, indexNameParts(entries));
+}

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

@@ -1,4 +1,4 @@
-import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, 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 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>[];
@@ -71,6 +71,10 @@ export declare function findVectorSort<E>(sort: QuerySortMap<E> | undefined): {
     key: string;
     search: QueryVectorSearch;
 } | undefined;
+/** `$candidates`, checked: it can be spelled into a statement, and `/http` input is untyped. */
+export declare function vectorCandidates(q: {
+    readonly $candidates?: number;
+}): number | undefined;
 /**
  * The vector index declared on `key`, if any. Answers both "is there an ANN index to tune here" and
  * "which kind", which decide the name Atlas is queried by and the setting Postgres is tuned with.
@@ -83,6 +87,10 @@ export declare function findVectorIndex<E>(meta: EntityMeta<E>, key: string): En
 export declare function hasVectorNear(where: unknown): boolean;
 /** Type guard: checks whether an update payload value is a JSON operator object. */
 export declare function isJsonUpdateOp(value: unknown): value is JsonUpdateOp;
+/** Type guard: checks whether an update payload value is a scalar field's operator. */
+export declare function isFieldUpdateOp(value: unknown): value is FieldUpdateOp;
+/** The one operator a scalar field's update carries, and its operand. */
+export declare function fieldUpdateOf(value: FieldUpdateOp): [keyof FieldUpdateOp, number | bigint];
 /**
  * The `$where` naming rows by key: a bare value names the one key column (refused on a composite), a
  * composite's key map is a `$where` already, and a list is an `IN` of bare values or an OR of maps.
@@ -114,7 +122,7 @@ export type ParsedGroupEntry<E = object> = {
     readonly alias: string;
     readonly op: QueryAggregateOp;
     readonly fieldRef: string;
-    /** `true` for a flat distinct op (`$countDistinct`, ...) -> `COUNT(DISTINCT field)`. */
+    /** `true` for `$countDistinct`: `COUNT(DISTINCT field)`. */
     readonly distinct: boolean;
     /** The rows it reads, where not all of the statement's. */
     readonly where?: QueryWhere<E>;
@@ -159,6 +167,17 @@ export declare function assertNonNegativeInteger(value: number, clause: string):
 export declare function throwUnknownAggregateColumn(key: string, clause: string): never;
 /** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
 export declare function assertAggregateColumns(clauseMap: object, emitted: ReadonlySet<string>, clause: string): void;
+/** The text-search config a fulltext index builds with, which a search it serves has to parse with too. */
+export declare function fulltextConfig(index: {
+    readonly config?: string;
+}): string;
+/** 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;
+/**
+ * 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.
+ */
+export declare function rankedTextSearch<E>(where: QueryWhere<E> | undefined): QueryTextSearchOptions<E>;
 /**
  * The fields a `$text` searches: those it names, or else the columns of the entity's fulltext index,
  * the declaration MySQL's `MATCH` has to name exactly and a MongoDB text index already is. Refused

package/dist/util/dialect.util.js

@@ -188,6 +188,14 @@ export function findVectorSort(sort) {
     }
     return undefined;
 }
+/** `$candidates`, checked: it can be spelled into a statement, and `/http` input is untyped. */
+export function vectorCandidates(q) {
+    const candidates = q.$candidates;
+    if (candidates !== undefined && (!Number.isInteger(candidates) || candidates < 1)) {
+        throw new TypeError(`$candidates must be a positive integer, got ${JSON.stringify(candidates)}`);
+    }
+    return candidates;
+}
 /**
  * Every index type that means "vector" to some engine: pgvector's two, the generic one MariaDB and
  * CockroachDB share, and Atlas's. Wider than {@link VECTOR_INDEX_TYPES}, which is the set whose DDL
@@ -228,6 +236,16 @@ const JSON_UPDATE_OPS = [
 export function isJsonUpdateOp(value) {
     return isRecord(value) && someKey(value, (key) => JSON_UPDATE_OPS.includes(key));
 }
+/** `satisfies` ties this to {@link FieldUpdateOp}, so renaming an operator breaks it at compile time. */
+const FIELD_UPDATE_OPS = ['$inc', '$mul'];
+/** Type guard: checks whether an update payload value is a scalar field's operator. */
+export function isFieldUpdateOp(value) {
+    return isRecord(value) && someKey(value, (key) => FIELD_UPDATE_OPS.includes(key));
+}
+/** The one operator a scalar field's update carries, and its operand. */
+export function fieldUpdateOf(value) {
+    return value.$inc === undefined ? ['$mul', value.$mul] : ['$inc', value.$inc];
+}
 /**
  * The `$where` naming rows by key: a bare value names the one key column (refused on a composite), a
  * composite's key map is a `$where` already, and a list is an `IN` of bare values or an OR of maps.
@@ -359,10 +377,10 @@ export function parseGroupMap(group, select) {
         if (key === undefined) {
             throw new TypeError(`aggregate '${alias}' names no op, only a $where`);
         }
-        // Flat DISTINCT ops (`$countDistinct`, ...) normalize to their base op + a `distinct` flag.
+        // `$countDistinct` normalizes to `$count` plus a `distinct` flag.
         const { op, distinct } = resolveAggregateOp(key);
         const fieldRef = aggregateFieldRef(alias, call[key]);
-        entries.push({ kind: 'fn', alias, op, fieldRef, distinct, ...(where && hasKeys(where) ? { where } : {}) });
+        entries.push({ kind: 'fn', alias, op, fieldRef, distinct, ...(hasKeys(where) ? { where } : {}) });
     }
     return entries;
 }
@@ -432,6 +450,28 @@ export function assertAggregateColumns(clauseMap, emitted, clause) {
         }
     }
 }
+/** The text-search config a fulltext index builds with where it states none: language-neutral, no stemming. */
+const DEFAULT_TEXT_CONFIG = 'simple';
+/** The text-search config a fulltext index builds with, which a search it serves has to parse with too. */
+export function fulltextConfig(index) {
+    return index.config ?? DEFAULT_TEXT_CONFIG;
+}
+/** 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]));
+}
+/**
+ * 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.
+ */
+export function rankedTextSearch(where) {
+    if (!where?.$text) {
+        throw new TypeError('$sort by $text ranks by the $text at the root of $where, which this query has none of');
+    }
+    return where.$text;
+}
 /**
  * The fields a `$text` searches: those it names, or else the columns of the entity's fulltext index,
  * the declaration MySQL's `MATCH` has to name exactly and a MongoDB text index already is. Refused

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.70.0",
+  "version": "0.72.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -52,11 +52,12 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "scripts": {
-    "prepack": "bun run build && bun run verify-dist.ts && cp ../../README.md .",
-    "postpack": "rm README.md && npm pkg delete gitHead",
+    "prepack": "bun run build && bun run verify-dist.ts && cp ../../README.md . && cp -R ../../skills .",
+    "postpack": "rm -r README.md skills && npm pkg delete gitHead",
     "compile.browser": "bun build src/browser/index.ts --minify --sourcemap=linked --format=esm --target=browser --outdir=dist/browser --entry-naming 'uql-browser.min.[ext]'",
     "build": "bun run clean && tsc -b tsconfig.build.json && bun run compile.browser && bun run verify-dist.ts",
     "start": "tsc --watch",