uql-orm 0.68.1 → 0.70.0

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,60 @@ 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'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.
+ */
+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]>;
+}[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 +140,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 +152,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 +172,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/queryRaw.d.ts

@@ -1,4 +1,4 @@
-import type { QueryContext, SqlQueryDialect } from './dialect.js';
+import type { QueryContext, RelationAggregateSpec, SqlQueryDialect } from './dialect.js';
 import type { Type } from './utility.js';
 /** What a `raw` callback receives. See {@link QueryRawFn}. */
 export type QueryRawRenderOptions = {
@@ -44,3 +44,21 @@ export declare class ColumnRef<K extends string = string> extends QueryRaw {
     readonly key: K;
     constructor(key: K, value: QueryRawFn);
 }
+/**
+ * A relation aggregate as SQL, read off a `computed` field's refs: `(user) => user.resources.count()`.
+ * It renders as the correlated subquery a `$count` reads, so a field holding one is read, filtered and
+ * sorted like any other.
+ *
+ * `V` is the value it reads and `Storable` whether a trigger could keep it, both carried in phantom
+ * fields so the aggregate a field declares decides the property's type and refuses `stored: true` on
+ * one no delta can maintain.
+ */
+export declare class RelationAggregate<V = unknown, Storable extends boolean = boolean> extends QueryRaw {
+    /** What it reads, kept beside the SQL so a read decodes the value the way the target's field does. */
+    readonly spec: RelationAggregateSpec;
+    private readonly __value;
+    private readonly __storable;
+    constructor(
+    /** What it reads, kept beside the SQL so a read decodes the value the way the target's field does. */
+    spec: RelationAggregateSpec, value: QueryRawFn);
+}

package/dist/type/queryRaw.js

@@ -30,3 +30,21 @@ export class ColumnRef extends QueryRaw {
         this.key = key;
     }
 }
+/**
+ * A relation aggregate as SQL, read off a `computed` field's refs: `(user) => user.resources.count()`.
+ * It renders as the correlated subquery a `$count` reads, so a field holding one is read, filtered and
+ * sorted like any other.
+ *
+ * `V` is the value it reads and `Storable` whether a trigger could keep it, both carried in phantom
+ * fields so the aggregate a field declares decides the property's type and refuses `stored: true` on
+ * one no delta can maintain.
+ */
+export class RelationAggregate extends QueryRaw {
+    spec;
+    constructor(
+    /** What it reads, kept beside the SQL so a read decodes the value the way the target's field does. */
+    spec, value) {
+        super(value);
+        this.spec = spec;
+    }
+}

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/util/dialect.util.d.ts

@@ -104,9 +104,11 @@ 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;
@@ -114,6 +116,8 @@ export type ParsedGroupEntry = {
     readonly fieldRef: string;
     /** `true` for a flat distinct op (`$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 +134,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

package/dist/util/dialect.util.js

@@ -2,8 +2,8 @@ import { getContext, UqlSecurityError } from '../context/context.js';
 import { soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
 import { VECTOR_INDEX_TYPES } from '../type/vector.js';
-import { isDatabaseWritten } from './field.util.js';
-import { entityName, getFieldKeys, getKeys, hasKeys, isOperatorObject, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
+import { getFieldKeys, isDatabaseWritten } from './field.util.js';
+import { entityName, getKeys, hasKeys, isOperatorObject, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
 /** The keys of `payload` a write persists as columns. */
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
@@ -344,22 +344,36 @@ export function parseGroupMap(group, select) {
     const entries = [];
     const groupMap = group ?? {};
     for (const alias of getKeys(groupMap)) {
-        if (groupMap[alias]) {
-            entries.push({ kind: 'key', alias });
+        const ref = groupMap[alias];
+        if (ref) {
+            entries.push({ kind: 'key', alias, path: ref === true ? [alias] : groupRefPath(alias, ref) });
         }
     }
     if (!select) {
         return entries;
     }
     for (const alias of getKeys(select)) {
-        const fnEntry = select[alias];
-        const key = getKeys(fnEntry)[0];
+        const { $where: where } = select[alias];
+        const call = select[alias];
+        const key = getKeys(call).find((name) => name !== '$where');
+        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.
         const { op, distinct } = resolveAggregateOp(key);
-        entries.push({ kind: 'fn', alias, op, fieldRef: aggregateFieldRef(alias, fnEntry[key]), distinct });
+        const fieldRef = aggregateFieldRef(alias, call[key]);
+        entries.push({ kind: 'fn', alias, op, fieldRef, distinct, ...(where && hasKeys(where) ? { where } : {}) });
     }
     return entries;
 }
+/** The path a group key's `{ transaction: { orderId: true } }` names, one key at each level. */
+function groupRefPath(alias, ref) {
+    const [key, ...rest] = isRecord(ref) ? getKeys(ref) : [];
+    if (!isRecord(ref) || key === undefined || rest.length) {
+        throw new TypeError(`$group '${alias}' names one field by the path to it: got ${JSON.stringify(ref)}`);
+    }
+    return ref[key] === true ? [key] : [key, ...groupRefPath(alias, ref[key])];
+}
 /** The column an aggregate reads: `'*'`, or the one field its `{ field: true }` names. */
 function aggregateFieldRef(alias, arg) {
     const [field, ...rest] = arg === '*' ? [arg] : namedKeys(arg);

package/dist/util/field.util.d.ts

@@ -1,4 +1,4 @@
-import { type ColumnFamily, type EntityMeta, type FieldOptions } from '../type/index.js';
+import { type ColumnFamily, type EntityMeta, type FieldKey, type FieldOptions, type RelationAggregateSpec } from '../type/index.js';
 /** The family of a logical field type, or `undefined` where it names none. */
 export declare function columnFamily(type: unknown): ColumnFamily | undefined;
 /**
@@ -12,6 +12,12 @@ export declare function isIntegerColumn(field: Pick<FieldOptions, 'type' | 'colu
  * because an inlined field has no column to name, while a stored one is read like any other.
  */
 export declare function isInlinedExpression<F extends FieldOptions>(field: F): field is F & Required<Pick<F, 'computed'>>;
+/**
+ * The relation aggregate a field computes, where it computes one rather than writing SQL: what it
+ * reads, off which relation, narrowed and capped how. Every engine renders it from this - a correlated
+ * subquery on SQL, a lookup on MongoDB - so both read the same declaration rather than parsing SQL.
+ */
+export declare function aggregateOf(field: FieldOptions | undefined): RelationAggregateSpec | undefined;
 /**
  * Whether the database supplies this field's value, so no insert or update may write it: a stored
  * computed column *is* a real column, read like one, but writing to it is an error on every engine.
@@ -25,3 +31,11 @@ export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOption
  * states its width. The one answer the create statement and the diff both read.
  */
 export declare function isAutoIncrement(field: FieldOptions, isPrimaryKey: boolean): boolean;
+/**
+ * The fields a read answers with where it names none. A relation aggregate is left out unless it asks
+ * for `eager: true`: it reads the related rows, which is what a relation does, and a relation is loaded
+ * only when a query asks for it. Naming one in `$select` reads it, whatever the default.
+ */
+export declare function getFieldKeys<E>(fields: {
+    [K in FieldKey<E>]?: FieldOptions;
+}): FieldKey<E>[];

package/dist/util/field.util.js

@@ -1,4 +1,4 @@
-import { COLUMN_TYPES, } from '../type/index.js';
+import { COLUMN_TYPES, RelationAggregate, } from '../type/index.js';
 import { getKeys } from './object.util.js';
 // Constructors and type strings in one map: a logical type is either, and every caller asks the same
 // question of both.
@@ -41,6 +41,15 @@ export function isIntegerColumn(field) {
 export function isInlinedExpression(field) {
     return field.computed !== undefined && field.stored !== true;
 }
+/**
+ * The relation aggregate a field computes, where it computes one rather than writing SQL: what it
+ * reads, off which relation, narrowed and capped how. Every engine renders it from this - a correlated
+ * subquery on SQL, a lookup on MongoDB - so both read the same declaration rather than parsing SQL.
+ */
+export function aggregateOf(field) {
+    const computed = field?.computed;
+    return computed instanceof RelationAggregate ? computed.spec : undefined;
+}
 /**
  * Whether the database supplies this field's value, so no insert or update may write it: a stored
  * computed column *is* a real column, read like one, but writing to it is an error on every engine.
@@ -62,3 +71,11 @@ export function isAutoIncrement(field, isPrimaryKey) {
         return field.autoIncrement;
     return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert && !field.references;
 }
+/**
+ * The fields a read answers with where it names none. A relation aggregate is left out unless it asks
+ * for `eager: true`: it reads the related rows, which is what a relation does, and a relation is loaded
+ * only when a query asks for it. Naming one in `$select` reads it, whatever the default.
+ */
+export function getFieldKeys(fields) {
+    return getKeys(fields).filter((field) => fields[field].eager ?? !aggregateOf(fields[field]));
+}

package/dist/util/object.util.d.ts

@@ -1,4 +1,4 @@
-import type { EntityMeta, FieldKey, FieldOptions } from '../type/index.js';
+import type { EntityMeta } from '../type/index.js';
 export declare function throwPendingTransaction(): never;
 export declare function throwNoPendingTransaction(): never;
 export declare function clone<T>(value: T): T;
@@ -24,9 +24,6 @@ export declare function definedEntries<K extends string, V>(record: Partial<Reco
  * out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
  */
 export declare function entityName<E>(meta: EntityMeta<E>): string;
-export declare function getFieldKeys<E>(fields: {
-    [K in FieldKey<E>]?: FieldOptions;
-}): FieldKey<E>[];
 /**
  * Whether `value` addresses a row by itself rather than naming columns: every primitive, and the
  * object ids a driver deals in (`ObjectId`, `Date`, bytes). Only a plain object names columns, which

package/dist/util/object.util.js

@@ -59,9 +59,6 @@ export function definedEntries(record) {
 export function entityName(meta) {
     return meta.name ?? meta.entity.name;
 }
-export function getFieldKeys(fields) {
-    return getKeys(fields).filter((field) => fields[field].eager ?? true);
-}
 /**
  * Whether `value` addresses a row by itself rather than naming columns: every primitive, and the
  * object ids a driver deals in (`ObjectId`, `Date`, bytes). Only a plain object names columns, which

package/dist/util/raw.d.ts

@@ -1,4 +1,4 @@
-import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type RefMap, type Type } from '../type/index.js';
+import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type ComputedRefs, type RefMap, type Type } from '../type/index.js';
 /**
  * Raw SQL, where an interpolated value binds, a `refs` field renders its column, and a `raw` renders
  * in place: `raw`GREATEST(0, ${user.credits} - ${amount})``. A callback writes whatever it writes, so
@@ -16,7 +16,7 @@ export declare function refs<E>(entity: Type<E>): RefMap<E>;
  * The refs a definition's callbacks read: an index's, a check's, a computed field's. A member decorator
  * sees no class, so these name no entity and resolve against the one rendering them.
  */
-export declare function memberRefs<E>(): RefMap<E>;
+export declare function memberRefs<E>(): ComputedRefs<E>;
 /** SQL a definition writes, a callback's refs read off {@link memberRefs}. */
 export declare function entitySql<E>(sql: EntitySql<E>): QueryRaw;
 /** A definition's predicate, its callback resolved the way {@link entitySql} resolves one. */

package/dist/util/raw.js

@@ -1,5 +1,5 @@
 import { getMeta } from '../entity/metadata/definition.js';
-import { ColumnRef, QueryRaw, } from '../type/index.js';
+import { ColumnRef, QueryRaw, RelationAggregate, } from '../type/index.js';
 import { isInlinedExpression } from './field.util.js';
 export function raw(value, ...rest) {
     if (!isTemplateStrings(value)) {
@@ -27,7 +27,7 @@ export function raw(value, ...rest) {
 export function refs(entity) {
     return new Proxy({}, { get: (_, key) => columnRef(entity, String(key)) });
 }
-const MEMBER_REFS = new Proxy({}, { get: (_, key) => columnRef(undefined, String(key)) });
+const MEMBER_REFS = new Proxy({}, { get: (_, key) => memberRef(String(key)) });
 /**
  * The refs a definition's callbacks read: an index's, a check's, a computed field's. A member decorator
  * sees no class, so these name no entity and resolve against the one rendering them.
@@ -43,6 +43,33 @@ export function entitySql(sql) {
 export function entityWhere(where) {
     return typeof where === 'function' ? where(memberRefs()) : where;
 }
+/**
+ * One member as a definition reads it: a {@link ColumnRef} where it names a field, and the same object
+ * answering `count`, `sum`, `min`, `max` and `avg` where it names a to-many. One runtime object, since
+ * a member decorator sees no class and so cannot know which the key is; the types keep them apart.
+ */
+function memberRef(relation) {
+    const over = (op) => (pick, q) => relationAggregate({ relation, op, field: pick(memberRefs()).key, ...(q && { query: q }) });
+    return Object.assign(columnRef(undefined, relation), {
+        count: (q) => relationAggregate({ relation, op: '$count', ...(q && { query: q }) }),
+        sum: over('$sum'),
+        min: over('$min'),
+        max: over('$max'),
+        avg: over('$avg'),
+    });
+}
+/**
+ * A relation aggregate as SQL: the dialect writes the same correlated subquery a `$count` reads,
+ * correlated to whichever alias the clause naming the field is rendering under.
+ */
+function relationAggregate(spec) {
+    return new RelationAggregate(spec, (opts) => {
+        if (!opts.entity) {
+            throw new TypeError(`'${spec.relation}' was read off a definition's refs, so it renders only inside its entity's SQL`);
+        }
+        opts.dialect.appendRelationAggregate(opts.ctx, opts.entity, spec, opts.prefix);
+    });
+}
 /** One field as SQL, against its own entity or, read off a definition, the entity rendering it. */
 function columnRef(entity, key) {
     return new ColumnRef(key, (opts) => {

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.68.1",
+  "version": "0.70.0",
   "type": "module",
   "engines": {
     "node": ">=24"