uql-orm 0.69.0 → 0.71.0

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;
     /**
@@ -122,6 +127,12 @@ export interface DialectFeatures {
      * answer, not the driver's: node-`pg` streams on its own and keeps doing so.
      */
     readonly serverSideCursors: boolean;
+    /**
+     * Whether an `UPDATE` or `DELETE` can read a relation in its filter. False on MongoDB, whose filter
+     * hosts no lookup, and on Turso's engine, which cannot resolve the written table inside a subquery:
+     * such a write reads the ids of the rows it names first.
+     */
+    readonly correlatedWrites: boolean;
 }
 /** What a SQL engine can do beyond {@link DialectFeatures}, read where a statement is built. */
 export interface SqlDialectFeatures extends DialectFeatures {

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 } from './utility.js';
+import type { Except, 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,6 +20,24 @@ 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>;
+}[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>>;
+/** A partial write as a caller supplies one: {@link UpdatePayload} without them. */
+export type UpdateWrite<E, Raw = QueryRaw> = UpdatePayload<E, Raw, WritableKey<E>>;
 /** The relation names of an entity: every key but its fields and its methods, so the two sets cannot drift. */
 export type RelationKey<E> = Exclude<Key<E>, FieldKey<E> | MethodKey<E>>;
 /**
@@ -267,10 +285,21 @@ export type TsTypeOf<T> = T extends StringConstructor ? string : T extends Numbe
  */
 export type FieldOptionsFor<V, E = unknown> = (FieldOptions<NonNullable<V>, E> & {
     readonly type: TypeFor<V>;
+    readonly isId: true;
 }) | (FieldOptions<NonNullable<V>, E> & {
+    readonly type: TypeFor<V>;
+} & DeclaresNotNull<V>) | (FieldOptions<NonNullable<V>, E> & {
     readonly references: EntityGetter;
     readonly type?: TypeFor<V>;
-}) | AggregateOptionsFor<V, E>;
+} & DeclaresNotNull<V>) | AggregateOptionsFor<V, E>;
+/**
+ * A column holds `null` unless `nullable: false` says otherwise, and a read hydrates one, so a property
+ * that does not admit it says so here. The decorators state the same rule the other way round, against
+ * the property they are applied to; a key needs neither, being NOT NULL on every engine.
+ */
+type DeclaresNotNull<V> = null extends V ? unknown : {
+    readonly nullable: false;
+};
 /**
  * A field a relation aggregate computes: the aggregate types it, so it declares no `type`, and only the
  * two a row change turns into a delta - `count` and `sum` - may be `stored`.
@@ -475,15 +504,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,14 +1,20 @@
-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.
  */
 export interface MigrationDefinition<Q extends Querier = SqlQuerier> {
     readonly name?: string;
+    /**
+     * `false` runs this migration outside a transaction, for a statement an engine refuses inside one -
+     * `CREATE INDEX CONCURRENTLY` on Postgres, the index a busy table needs. The cost is the rollback: a
+     * failure part-way leaves the statements before it applied and the migration unlogged. MongoDB
+     * creates collections outside any transaction already, so it changes nothing there.
+     */
+    readonly transaction?: boolean;
     up(querier: Q): Promise<void>;
     down(querier: Q): Promise<void>;
 }
@@ -126,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
@@ -142,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

@@ -16,6 +16,12 @@ export type QueryOptions = {
      * already-deleted rows are removed too. No effect on entities without a soft-delete field.
      */
     hardDelete?: boolean;
+    /**
+     * `updateMany`/`deleteMany` only: address every row of the table on purpose. Without it a bulk write
+     * that names none - no `$where` and no `$limit` - is refused, since a forgotten filter and the whole
+     * table look alike. The entity's own filters never count as naming one.
+     */
+    unfiltered?: boolean;
     /**
      * prefix the query with this.
      */

package/dist/type/queryAggregate.d.ts

@@ -1,7 +1,8 @@
-import type { FieldKey } from './entity.js';
+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 { RejectKeys } from './utility.js';
+import type { 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;
@@ -23,22 +24,14 @@ export type QueryAggregateOp = (typeof QUERY_AGGREGATE_OPS)[number];
  */
 export declare function isQueryAggregateOp(op: string): op is QueryAggregateOp;
 /**
- * DISTINCT-qualified aggregate ops, each mapped to the base op it applies to a field's distinct
- * values: `$countDistinct` -> `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
- * (not a nested `{ $distinct }` argument) so the op is self-documenting and greppable. `$min`/`$max`
- * are omitted: DISTINCT is a no-op for them.
+ * `$countDistinct` -> `COUNT(DISTINCT col)`. Flat (not a nested `{ $distinct }` argument) so the op is
+ * self-documenting and greppable. The other ops have no DISTINCT variant: `$sum`/`$avg` over deduplicated
+ * values is rarely what totalling or averaging means, and DISTINCT is a no-op for `$min`/`$max`.
  */
-declare const QUERY_AGGREGATE_DISTINCT_OP_BASE: {
-    readonly $countDistinct: '$count';
-    readonly $sumDistinct: '$sum';
-    readonly $avgDistinct: '$avg';
-};
-/** DISTINCT-qualified aggregate operators (the keys of {@link QUERY_AGGREGATE_DISTINCT_OP_BASE}). */
-export type QueryAggregateDistinctOp = keyof typeof QUERY_AGGREGATE_DISTINCT_OP_BASE;
+export type QueryAggregateDistinctOp = '$countDistinct';
 /**
- * Resolve an aggregate op key into its base op and whether it is DISTINCT-qualified. A flat distinct
- * op resolves to its base op with `distinct: true`; a plain op to `distinct: false`. Throws otherwise
- * (`$min`/`$max` have no distinct variant).
+ * Resolve an aggregate op key into its base op and whether it is DISTINCT-qualified: `$countDistinct`
+ * resolves to `$count` with `distinct: true`, a plain op to itself with `distinct: false`. Throws otherwise.
  */
 export declare function resolveAggregateOp(key: string): {
     op: QueryAggregateOp;
@@ -59,9 +52,8 @@ export type QueryFieldRef<E, F extends keyof E = FieldKey<E>> = ExactlyOne<Requi
 /** The argument of an aggregate function: a field, or `'*'` (only meaningful for `COUNT(*)`). */
 export type QueryAggregateArg<E> = QueryFieldRef<E> | '*';
 /**
- * Fields `SUM`/`AVG` can total. Restricted to numeric columns because the result is declared
- * `number`: totalling a text or date column is either an engine error or a coercion, and neither
- * produces the value the signature promises.
+ * Fields `SUM`/`AVG` can total. Restricted to numeric columns because totalling a text or date one is
+ * either an engine error or a coercion, and neither produces the value the signature promises.
  */
 type NumericFieldKey<E> = {
     readonly [K in FieldKey<E>]: [NonNullable<E[K]>] extends [number | bigint] ? K : never;
@@ -74,8 +66,12 @@ type AggregateOp = QueryAggregateOp | QueryAggregateDistinctOp;
  * where `Extract` would quietly drop the renamed member and leave the subset wrong but valid.
  */
 type OpsOf<K extends AggregateOp> = K;
+/** Ops that add a column up, which keeps the column's own type: a `bigint` column totals to a `bigint`. */
+type SummingOp = OpsOf<'$sum'>;
+/** Ops that mean a column, which the engine floats, so the result is a `number` however wide the column. */
+type AveragingOp = OpsOf<'$avg'>;
 /** Ops that total a column, so their argument has to be numeric. */
-type TotallingOp = OpsOf<'$sum' | '$avg' | '$sumDistinct' | '$avgDistinct'>;
+type TotallingOp = SummingOp | AveragingOp;
 /**
  * Every aggregate op mapped to the argument it accepts: `$count` a field or `'*'` (`COUNT(*)`),
  * the totalling ops a numeric field, `$min`/`$max`/`$countDistinct` any field.
@@ -83,19 +79,56 @@ type TotallingOp = OpsOf<'$sum' | '$avg' | '$sumDistinct' | '$avgDistinct'>;
 type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<TotallingOp, QueryFieldRef<E, NumericFieldKey<E>>> & Record<Exclude<AggregateOp, '$count' | TotallingOp>, QueryFieldRef<E>>;
 /**
  * An aggregate over one field, exactly one op per entry: `{ $sum: { amount: true } }` is `SUM("amount")`,
- * `{ $countDistinct: { id: true } }` is `COUNT(DISTINCT "id")`, and only `$count` takes `'*'`.
+ * `{ $countDistinct: { id: true } }` is `COUNT(DISTINCT "id")`, and only `$count` takes `'*'`. Its own
+ * `$where` narrows the rows it reads to those matching, over the entity's own fields.
  */
-export type QueryAggregateFn<E> = ExactlyOne<QueryAggregateArgMap<E>>;
-/** A single-key `{ [op]: unknown }` shape for each op in `Ops`, matched to infer that op's result. */
-type FnWithOp<Ops extends string> = {
+export type QueryAggregateFn<E> = ExactlyOne<QueryAggregateArgMap<E>> & {
+    readonly $where?: QueryAggregateWhere<E>;
+};
+/** What an aggregate's own `$where` reads: the entity's fields, since a relation there is a subquery inside it. */
+type QueryAggregateWhere<E> = QueryWhere<E, QueryRaw, FieldKey<E>>;
+/** An aggregate's `$where` naming a key it does not have, refused: a captured `$select` skips the excess-property check. */
+type AggregateWhereKeys<E, Fn> = Fn extends {
+    readonly $where: infer W;
+} ? {
+    readonly $where: RejectKeys<Exclude<keyof W, keyof QueryAggregateWhere<E>>>;
+} : unknown;
+/** A single-key `{ [op]: Arg }` shape for each op in `Ops`, matched to infer that op's result or its argument. */
+type FnWithOp<Ops extends string, Arg = unknown> = {
     [K in Ops]: {
-        readonly [P in K]: unknown;
+        readonly [P in K]: Arg;
     };
 }[Ops];
 /** Ops that count rows. Alone among the ops they answer `0`, never NULL, over an empty group. */
 type CountingOp = OpsOf<'$count' | '$countDistinct'>;
-/** The columns to group by, `{ status: true }`, typed against the entity like `$select`. */
-export type QueryGroupMap<E> = Readonly<QuerySelect<E, FieldKey<E>, true>>;
+/** Ops that read back as the column they aggregate, rather than widening or floating it. */
+type ColumnTypedOp = SummingOp | OpsOf<'$min' | '$max'>;
+/**
+ * A field a group key reads, by the path to it: `{ orderId: true }`, or through a to-one relation,
+ * `{ transaction: { orderId: true } }`. A to-many is `never`, since joining one multiplies the rows.
+ */
+export type QueryGroupRef<E, K extends keyof E = FieldKey<E> | RelationKey<E>> = ExactlyOne<Required<{
+    [P in K]: P extends RelationKey<E> ? IsMany<E[P]> extends true ? never : QueryGroupRef<RelationTarget<E[P]>> : true;
+}>>;
+/** The columns to group by: a field switched on, `{ status: true }`, or an alias for a field a path reads. */
+export type QueryGroupMap<E> = {
+    readonly [key: string]: true | QueryGroupRef<E>;
+};
+/**
+ * A captured `$group` against its schema: a field key takes `true` and keeps its link, any other key is an
+ * alias for a path. A key switched on that is no field is refused by name, which the intersection alone lets by.
+ */
+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 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 ? 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> = {
     readonly [alias: string]: QueryAggregateFn<E>;
@@ -103,14 +136,11 @@ export type QueryAggMap<E> = {
 /** The entity type of an aggregated field reference `F`, or `unknown` if it is not a known field. */
 type FieldValueType<E, F> = F extends keyof E ? E[F] : unknown;
 /**
- * A computed column's type: a count is a `number`; every other aggregate is `null` over no rows, a
- * total a `number` (exact to 2^53, `raw` beyond) and `$min`/`$max` the field's own type.
+ * A computed column's type: a count is a `number`; every other aggregate is `null` over no rows, a mean
+ * a `number` whatever it read, and a total, a `$min` or a `$max` the column's own type - so a `bigint`
+ * column totals to a `bigint`, which is what the driver decodes rather than rounding through a float.
  */
-type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number : Fn extends FnWithOp<TotallingOp> ? number | null : Fn extends {
-    readonly $min: infer F;
-} | {
-    readonly $max: infer F;
-} ? FieldValueType<E, keyof F> | null : unknown;
+type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number : Fn extends FnWithOp<AveragingOp> ? number | null : Fn extends FnWithOp<ColumnTypedOp, infer F> ? FieldValueType<E, keyof F> | null : unknown;
 /**
  * Flattens an intersection into a single object literal for readable editor hovers.
  * @internal
@@ -118,8 +148,10 @@ type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number :
 type Simplify<T> = {
     [K in keyof T]: T[K];
 } & {};
-/** An aggregate's row: each grouped column with its entity type, each computed one with its aggregate's. */
+/** An aggregate's row: each grouped column with its entity type, each alias with its path's, each computed one with its aggregate's. */
 export type QueryAggregateResult<E, G, A> = Simplify<Pick<E, GroupedKeys<G> & FieldKey<E>> & {
+    -readonly [K in Exclude<NamedKeys<G>, FieldKey<E>>]: GroupRefValue<E, G[K]>;
+} & {
     -readonly [K in keyof A]: QueryAggregateFnResult<E, A[K]>;
 }>;
 /** A `HAVING` as the dialects read it, erased; {@link QueryAggregate.$having} is where it is typed. `{ count: { $gt: 5 } }` */
@@ -136,19 +168,18 @@ export type QueryAggregate<E, G extends QueryGroupMap<E> = QueryGroupMap<E>, A e
      */
     readonly $where?: QueryWhere<E>;
     /**
-     * Columns to group by - `{ status: true }`, typed against the entity like `$select`. A computed
-     * aggregate wrongly placed here (it belongs in `$select`) is rejected via {@link RejectKeys}, since
-     * `$group` is captured as a generic and a bare generic skips excess-property checking. The captured
-     * map meets its schema, {@link QueryGroupMap}, so each key keeps its link to the entity property.
+     * Columns to group by: `{ status: true }`, or an alias for a to-one relation's field by the path to
+     * it, `{ orderId: { transaction: { orderId: true } } }`. The captured map meets its schema, so a field
+     * key keeps its link to the entity property, and a typo matches neither form.
      */
-    readonly $group?: G & QueryGroupMap<E> & RejectKeys<Exclude<keyof G, FieldKey<E>>>;
+    readonly $group?: G & QueryGroupSchema<E, G>;
     /**
      * The computed columns by alias, the captured map meeting its schema so field keys stay linked. An alias
      * repeating a `$group` column is refused, since both would come back under one name.
      */
     readonly $select?: A & {
-        readonly [K in keyof A]: QueryAggregateFn<E>;
-    } & RejectKeys<NamedKeys<A> & GroupedKeys<G>>;
+        readonly [K in keyof A]: QueryAggregateFn<E> & AggregateWhereKeys<E, A[K]>;
+    } & RejectKeys<NamedKeys<A> & NamedKeys<G>>;
     /** Filtering after grouping, by a result column, each value typed as that column is. */
     readonly $having?: {
         readonly [K in keyof QueryAggregateResult<E, G, A>]?: QueryWhereFieldValue<QueryAggregateResult<E, G, A>[K]>;

package/dist/type/queryAggregate.js

@@ -7,29 +7,12 @@ export function isQueryAggregateOp(op) {
     return QUERY_AGGREGATE_OPS.includes(op);
 }
 /**
- * DISTINCT-qualified aggregate ops, each mapped to the base op it applies to a field's distinct
- * values: `$countDistinct` -> `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
- * (not a nested `{ $distinct }` argument) so the op is self-documenting and greppable. `$min`/`$max`
- * are omitted: DISTINCT is a no-op for them.
- */
-const QUERY_AGGREGATE_DISTINCT_OP_BASE = {
-    $countDistinct: '$count',
-    $sumDistinct: '$sum',
-    $avgDistinct: '$avg',
-};
-/** Whether `key` is a DISTINCT-qualified aggregate operator (narrows for a cast-free base lookup). */
-function isQueryAggregateDistinctOp(key) {
-    // `Object.hasOwn`, not `key in`: the latter matches inherited members like `toString`.
-    return Object.hasOwn(QUERY_AGGREGATE_DISTINCT_OP_BASE, key);
-}
-/**
- * Resolve an aggregate op key into its base op and whether it is DISTINCT-qualified. A flat distinct
- * op resolves to its base op with `distinct: true`; a plain op to `distinct: false`. Throws otherwise
- * (`$min`/`$max` have no distinct variant).
+ * Resolve an aggregate op key into its base op and whether it is DISTINCT-qualified: `$countDistinct`
+ * resolves to `$count` with `distinct: true`, a plain op to itself with `distinct: false`. Throws otherwise.
  */
 export function resolveAggregateOp(key) {
-    if (isQueryAggregateDistinctOp(key)) {
-        return { op: QUERY_AGGREGATE_DISTINCT_OP_BASE[key], distinct: true };
+    if (key === '$countDistinct') {
+        return { op: '$count', distinct: true };
     }
     if (isQueryAggregateOp(key)) {
         return { op: key, distinct: false };

package/dist/type/universalQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, EntityId, FieldKey, RelationKey, UpdatePayload, WrittenId } from './entity.js';
+import type { EntityId, EntityWrite, FieldKey, RelationKey, UpdateWrite, WrittenId } from './entity.js';
 import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpsertOneResult, QueryUpsertManyResult } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
@@ -31,9 +31,9 @@ export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
     /** Whether any record matches: a count capped at one row, so the engine stops at the first match. */
     exists<E extends object>(entity: Type<E>, q?: QueryFilter<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, boolean>;
     /** Update the record with the given primary key; resolves to the number of affected rows. */
-    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, number>;
+    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, number>;
     /** Update the records matching the query; resolves to the number of affected rows. */
-    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E, QuerierRaw<W>>, payload: UpdatePayload<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, number>;
+    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E, QuerierRaw<W>>, payload: UpdateWrite<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, number>;
     /**
      * delete or SoftDelete a record.
      * @param entity the entity to persist on
@@ -59,31 +59,31 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      */
     findManyStream<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
     /** Insert a record and resolve to its id. See {@link UniversalQuerier.insertMany}. */
-    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
     /**
      * Insert records in as few statements as the bind limit allows, resolving to their ids in payload order.
      * Ids are exact everywhere but MySQL, which infers them from its header and reports `undefined` rather
      * than a guess where it cannot: a batch naming some keys, or a key that is not `AUTO_INCREMENT`.
      */
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     /** Insert or update a record by its conflict paths; resolves to its id and whether it was created. */
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>): Promise<QueryUpsertOneResult<E>>;
     /** Insert or update records by their conflict paths; resolves to their ids in payload order. */
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>[]): Promise<QueryUpsertManyResult<E>>;
     /**
      * insert or update a record.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the ID
      */
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
     /**
      * Insert or update records.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
      */
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     /**
      * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
      * entity has no soft-delete field.

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

@@ -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.
@@ -104,16 +108,20 @@ export declare function applyFilters<E>(meta: EntityMeta<E>, whereMap: QueryWher
 /**
  * Parsed entry from a `$group` map - either a raw group key or an aggregate function call.
  */
-export type ParsedGroupEntry = {
+export type ParsedGroupEntry<E = object> = {
     readonly kind: 'key';
     readonly alias: string;
+    /** The field it reads, behind the to-one relations leading to it: `['transaction', 'orderId']`. */
+    readonly path: readonly string[];
 } | {
     readonly kind: 'fn';
     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>;
 };
 /**
  * The `$size` of a relation condition, `{ comments: { $size: { $gte: 2 } } }`, or `undefined` where it
@@ -130,7 +138,7 @@ export declare function parseSortByCount(val: unknown): unknown;
  * Parse the `$group` (grouped columns) and `$select` (computed aggregates) maps into structured
  * entries consumable by any dialect. Grouped columns come first, then computed columns.
  */
-export declare function parseGroupMap<E>(group?: QueryGroupMap<E>, select?: QueryAggMap<E>): ParsedGroupEntry[];
+export declare function parseGroupMap<E>(group?: QueryGroupMap<E>, select?: QueryAggMap<E>): ParsedGroupEntry<E>[];
 /**
  * Whether `value` is a map of comparison operators rather than a value to compare against. Only a
  * plain object qualifies: `Date`, `QueryRaw`, `Uint8Array` and arrays are all `typeof 'object'`, and
@@ -155,6 +163,12 @@ 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 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