uql-orm 0.68.0 → 0.69.0

package/dist/mongo/mongoDialect.js

@@ -1,10 +1,10 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
-import { COUNT_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, sortCountField } from '../dialect/aliases.js';
+import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, sortCountField } from '../dialect/aliases.js';
 import { resolveQueryJoins, resolveSortableJoin } from '../dialect/queryJoins.js';
 import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/query.js';
-import { QueryRaw } from '../type/queryRaw.js';
+import { QueryRaw, RelationAggregate } from '../type/queryRaw.js';
 import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
 /** Default {@link DialectFeatures} for MongoDB. */
 export const mongoDialectFeatures = {
@@ -165,7 +165,7 @@ export class MongoDialect extends AbstractDialect {
     appendRelationLookup(filter, meta, relKey, val, lookups) {
         const temp = `${REL_TEMP_PREFIX}${lookups.temps.length}`;
         const sizeVal = parseRelationSize(val);
-        const tail = sizeVal === undefined ? [{ $limit: 1 }] : [{ $count: COUNT_ALIAS }];
+        const tail = sizeVal === undefined ? [{ $limit: 1 }] : [{ $count: AGGREGATE_VALUE_ALIAS }];
         const where = (sizeVal === undefined ? val : {});
         lookups.temps.push(temp);
         lookups.stages.push(this.relationLookup(meta, meta.relations[relKey], where, temp, tail));
@@ -423,6 +423,20 @@ export class MongoDialect extends AbstractDialect {
         const selectMap = asSelectMap(select);
         // Projected by column, not by field key; `normalizeId` maps them back on the way out.
         const projection = normalizeScalarFieldSelection(meta, selectMap, exclude).reduce((acc, key) => {
+            // Swept in with the rest of the entity's fields, a computed one is skipped; asked for by name
+            // it is refused, since the document holds nothing to project under it.
+            const field = meta.fields[key];
+            if (field?.computed) {
+                // An aggregate is on the document by the time this projects, under the field's own name; SQL
+                // is refused where it was asked for by name, and skipped where it was swept in with the rest.
+                if (aggregateOf(field)) {
+                    acc[key] = 1;
+                }
+                else if (selectMap && key in selectMap) {
+                    assertReadable(meta, key);
+                }
+                return acc;
+            }
             acc[this.columnOf(meta, key)] = 1;
             return acc;
         }, {});
@@ -498,18 +512,81 @@ export class MongoDialect extends AbstractDialect {
                 continue;
             }
             const temp = sortCountField(key);
-            stages.push(this.tallyLookup(meta, relOpts, {}, temp), { $addFields: { [temp]: this.tally(temp) } });
+            stages.push(...this.aggregateStages(meta, { relation: key, op: '$count' }, `${REL_TEMP_PREFIX}${temp}`, temp));
             fields.push(temp);
         }
         return { stages, fields };
     }
-    /** The correlated lookup counting a relation's rows, which `where` narrows, into `temp`. */
-    tallyLookup(meta, relOpts, where, temp) {
-        return this.relationLookup(meta, relOpts, where, temp, [{ $count: COUNT_ALIAS }]);
+    /** Whether a read answers with a relation aggregate, which only the pipeline can build. */
+    readsAggregates(entity, q) {
+        return this.aggregateKeys(entity, q).length > 0;
+    }
+    /**
+     * The relation aggregates one query reads: the ones its projection carries, plus any its `$where` or
+     * `$sort` names, which a read materializes whether or not it answers with them.
+     */
+    aggregateKeys(entity, q) {
+        const meta = getMeta(entity);
+        const projected = normalizeScalarFieldSelection(meta, asSelectMap(q.$select), q.$exclude);
+        const named = [...Object.keys(q.$where ?? {}), ...Object.keys(q.$sort ?? {})];
+        return [...new Set([...projected, ...named])].flatMap((key) => {
+            const spec = aggregateOf(meta.fields[key]);
+            return spec ? [[key, spec]] : [];
+        });
+    }
+    /**
+     * The stages a relation aggregate a query names needs: the correlated lookup that reads the related
+     * rows - narrowed, ordered and capped as the field declared - ending in the tally or total it wants,
+     * and the `$addFields` that puts the value on the document under the field's own name.
+     *
+     * The same spec the SQL dialects render as a correlated subquery: a relation aggregate is data, so a
+     * document engine builds it out of stages rather than being refused a language it does not speak.
+     */
+    aggregateFieldStages(meta, aggregates) {
+        const stages = [];
+        const temps = [];
+        for (const [key, spec] of aggregates) {
+            const temp = `${REL_TEMP_PREFIX}${key}`;
+            stages.push(...this.aggregateStages(meta, spec, temp, key));
+            temps.push(temp);
+        }
+        return { stages, temps };
+    }
+    /**
+     * One relation aggregate on the document under `field`: the correlated lookup that reads the related
+     * rows - narrowed, ordered and capped as the spec says - ending in the tally or total it wants, and
+     * the `$addFields` reading that back, `0` or `null` where the lookup matched nothing.
+     *
+     * Every aggregate MongoDB answers is built here: a `$count` a query asks for, an ordering by one, and
+     * a field a `computed` declares, which is the same spec the SQL dialects render as one subquery.
+     */
+    aggregateStages(meta, spec, temp, field) {
+        const relOpts = relationOf(meta, spec.relation);
+        const query = spec.query ?? {};
+        const tail = [
+            ...(query.$sort ? [{ $sort: this.sort(relOpts.entity(), query.$sort) }] : []),
+            ...this.pagerStages(query),
+            spec.field
+                ? {
+                    $group: {
+                        _id: null,
+                        [AGGREGATE_VALUE_ALIAS]: { [spec.op]: `$${this.columnOf(getMeta(relOpts.entity()), spec.field)}` },
+                    },
+                }
+                : { $count: AGGREGATE_VALUE_ALIAS },
+        ];
+        return [
+            this.relationLookup(meta, relOpts, query.$where ?? {}, temp, tail),
+            { $addFields: { [field]: this.tally(temp, spec.op) } },
+        ];
     }
-    /** The tally a lookup left in `temp`, which holds no row at all where nothing matched: a zero. */
-    tally(temp) {
-        return { $ifNull: [{ $arrayElemAt: [`$${temp}.${COUNT_ALIAS}`, 0] }, 0] };
+    /**
+     * The value a lookup left in `temp`, which holds no row at all where nothing matched: `0` for the
+     * aggregates that count something, and `null` for the ones with no value to report.
+     */
+    tally(temp, op = '$count') {
+        const empty = op === '$count' || op === '$sum' ? 0 : null;
+        return { $ifNull: [{ $arrayElemAt: [`$${temp}.${AGGREGATE_VALUE_ALIAS}`, 0] }, empty] };
     }
     /**
      * The lookups reading each to-many a query populates, and the tally of each `$count`, onto the fields
@@ -523,12 +600,11 @@ export class MongoDialect extends AbstractDialect {
         for (const relKey of getRelationRequestSummary(meta, q.$populate).toManyKeys) {
             stages.push(...this.toManyLookup(meta, relKey, parseRelationAtKey(relKey, q.$populate).query, temps));
         }
-        for (const { relKey, relation, where } of countedRelations(meta, q.$count)) {
+        for (const { relKey, where } of countedRelations(meta, q.$count)) {
             const temp = `${REL_TEMP_PREFIX}count_${relKey}`;
             temps.push(temp);
-            stages.push(this.tallyLookup(meta, relation, where, temp), {
-                $addFields: { [`${COUNT_RESULT_KEY}.${relKey}`]: this.tally(temp) },
-            });
+            const spec = { relation: relKey, op: '$count', query: { $where: where } };
+            stages.push(...this.aggregateStages(meta, spec, temp, `${COUNT_RESULT_KEY}.${relKey}`));
         }
         return temps.length ? [...stages, { $unset: temps }] : stages;
     }
@@ -595,6 +671,7 @@ export class MongoDialect extends AbstractDialect {
     pathOf(meta, key) {
         const dot = key.indexOf('.');
         if (dot < 0) {
+            assertReadable(meta, key);
             return this.columnOf(meta, key);
         }
         return this.columnOf(meta, key.slice(0, dot)) + key.slice(dot);
@@ -602,8 +679,12 @@ export class MongoDialect extends AbstractDialect {
     aggregationPipeline(entity, q, opts) {
         // Lookups that a relation condition needs come first, then the match that reads them, then the
         // temporary fields are dropped so they never reach the caller.
+        // Every relation aggregate the query reads comes first: a `$match`, a `$sort` and the projection all
+        // name it as a field of the document, which is what these stages make true.
+        const aggregates = this.aggregateFieldStages(getMeta(entity), this.aggregateKeys(entity, q));
         const { stages, filter, unset } = this.whereWithRelations(entity, q.$where, opts);
         return [
+            ...aggregates.stages,
             ...stages,
             ...(hasKeys(filter) ? [{ $match: filter }] : []),
             ...(unset.length ? [{ $unset: unset }] : []),
@@ -611,6 +692,7 @@ export class MongoDialect extends AbstractDialect {
                 sort: this.sort(entity, q.$sort, q.$populate),
                 pager: this.pagerStages(q),
             }),
+            ...(aggregates.temps.length ? [{ $unset: aggregates.temps }] : []),
         ];
     }
     /** The `$skip`/`$limit` stages of a page, each checked: `/http` hands a page over untyped. */
@@ -1113,3 +1195,18 @@ export class MongoDialect extends AbstractDialect {
 function sortDirection(value) {
     return value === 'desc' || value === -1 ? -1 : 1;
 }
+/** The relation aggregate a field computes, where it computes one rather than writing SQL. */
+function aggregateOf(field) {
+    return field?.computed instanceof RelationAggregate ? field.computed.spec : undefined;
+}
+/**
+ * A `computed` field writing SQL is refused wherever a query names it, since no document engine
+ * evaluates SQL and answering with the property name would hand back `undefined` for every row. One
+ * computing a relation aggregate is read: `aggregateFieldStages` builds it.
+ */
+function assertReadable(meta, key) {
+    const field = meta.fields[key];
+    if (field?.computed && !aggregateOf(field)) {
+        throw new TypeError(`cannot read '${meta.entity.name}.${key}' on MongoDB: a 'computed' field writing SQL is not something a document engine evaluates`);
+    }
+}

package/dist/mongo/mongodbQuerier.d.ts

@@ -18,8 +18,8 @@ export declare class MongodbQuerier extends AbstractQuerier {
      */
     private readCursor;
     /**
-     * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter
-     * or order by a relation, and the grouping `$distinct` is.
+     * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter or
+     * order by a relation, one to build a relation aggregate, and the grouping `$distinct` is.
      */
     private readsThroughPipeline;
     private buildScalarProjection;

package/dist/mongo/mongodbQuerier.js

@@ -68,15 +68,16 @@ export class MongodbQuerier extends AbstractQuerier {
             : this.buildFindCursor(entity, q, opts);
     }
     /**
-     * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter
-     * or order by a relation, and the grouping `$distinct` is.
+     * Whether a read needs stages a `find` cursor cannot express: a lookup to populate, count, filter or
+     * order by a relation, one to build a relation aggregate, and the grouping `$distinct` is.
      */
     readsThroughPipeline(entity, q) {
         return (!!q.$distinct ||
             hasKeys(q.$count) ||
             populatesRelations(getMeta(entity), q.$populate) ||
             this.dialect.constrainsRelations(entity, q.$where) ||
-            this.dialect.sortsRelations(entity, q.$sort));
+            this.dialect.sortsRelations(entity, q.$sort) ||
+            this.dialect.readsAggregates(entity, q));
     }
     buildScalarProjection(entity, q) {
         return this.dialect.select(entity, q.$select, q.$exclude);

package/dist/type/dialect.d.ts

@@ -1,6 +1,6 @@
 import type { EntityMeta, UpdatePayload } from './entity.js';
-import type { Query, QueryConflictPaths, QueryOptions, QueryPage, QuerySearch } from './query.js';
-import type { QueryAggMap, QueryAggregate, QueryGroupMap } from './queryAggregate.js';
+import type { Query, QueryConflictPaths, QueryOptions, QueryPage, QuerySearch, RelationQuery } from './query.js';
+import type { QueryAggMap, QueryAggregate, QueryAggregateOp, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
 /**
  * comparison options.
@@ -208,7 +208,34 @@ export interface SqlQueryDialect {
      * Default: '?' for MySQL/MariaDB/SQLite, '$n' for PostgreSQL.
      */
     placeholder(index: number): string;
+    /**
+     * A relation aggregate as a correlated subquery, correlated to the row under `prefix`: what a field
+     * declaring `computed: (user) => user.resources.count()` renders as, wherever a clause names it.
+     */
+    appendRelationAggregate<E>(ctx: QueryContext, entity: Type<E>, aggregate: RelationAggregateSpec, prefix: string): void;
 }
+/**
+ * The aggregates a relation reads, spelled as the query language spells them, so a `computed` field, an
+ * aggregate query and MongoDB's own `$group` all name one the same way. `$count` and `$sum` are the two
+ * a row change turns into a delta.
+ */
+export type RelationAggregateOp = QueryAggregateOp;
+/** What a relation aggregate reads: how many rows, or one of the target's columns. */
+export type RelationAggregateProjection = {
+    readonly op: '$count';
+    readonly field?: never;
+} | {
+    readonly op: Exclude<RelationAggregateOp, '$count'>;
+    readonly field: string;
+};
+/** A relation aggregate as a `computed` field holds it: what it reads, off which relation, filtered how. */
+export type RelationAggregateSpec = RelationAggregateProjection & {
+    readonly relation: string;
+    /** Which of the related rows it reads, and the page it caps them to, as the field declared them. */
+    readonly query?: RelationSubqueryQuery;
+};
+/** The rows a relation subquery reads: which ones, in what order, and the page capping them. */
+export type RelationSubqueryQuery = Pick<RelationQuery, '$where' | '$sort' | '$limit' | '$skip'>;
 /**
  * Supported SQL dialect identifiers.
  */

package/dist/type/entity.d.ts

@@ -1,6 +1,6 @@
 import type { EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js';
-import type { FilterOptions } from './query.js';
-import type { ColumnRef, QueryRaw } from './queryRaw.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 { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
@@ -22,6 +22,15 @@ export type FieldKey<E> = {
 }[Key<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>>;
+/**
+ * To-one relations only: a parent holds many rows of a to-many, so there is no single value to order it
+ * by, and joining one in would duplicate the parent instead. Order those inside `$populate`.
+ */
+export type ToOneRelationKey<E> = {
+    [K in RelationKey<E>]: IsMany<E[K]> extends true ? never : K;
+}[RelationKey<E>];
+/** The relation names a parent holds many rows of: what a populated query fills, and what an aggregate reads. */
+export type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
 /** Whether `T` carries the `Json` brand, read off its marker key: a primitive matches `Json<infer P>` too. */
 type IsJson<T> = '__json' extends keyof T ? true : false;
 /** The payload `P` of a branded `Json<P>`, or `never` for any other type. */
@@ -84,7 +93,7 @@ export type JsonUpdateOp<T = unknown> = {
  */
 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> = (undefined extends V ? null : never) | QueryRaw | JsonUpdateOpFor<V>;
+type UpdateExtra<V, Raw> = (undefined extends V ? null : never) | Raw | JsonUpdateOpFor<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.
@@ -97,10 +106,10 @@ export type EntityData<E, F extends keyof E = FieldKey<E>, R extends keyof E = R
 /** A relation's value as its rows' {@link EntityData}. */
 type RelationData<V> = V extends readonly (infer T)[] ? EntityData<T>[] : V extends object ? EntityData<V> : never;
 /** {@link EntityData} made partial, each member also taking its {@link UpdateExtra}. */
-export type UpdatePayload<E, F extends keyof E = FieldKey<E>, R extends keyof E = RelationKey<E>> = {
-    [P in F]?: E[P] | UpdateExtra<E[P]>;
+export type UpdatePayload<E, Raw = QueryRaw, F extends keyof E = FieldKey<E>, R extends keyof E = RelationKey<E>> = {
+    [P in F]?: E[P] | UpdateExtra<E[P], Raw>;
 } & {
-    [P in R]?: E[P] | RelationData<E[P]> | UpdateExtra<E[P]>;
+    [P in R]?: E[P] | RelationData<E[P]> | UpdateExtra<E[P], Raw>;
 };
 /** The key's name where the entity states it, by the `idKey` brand or a conventional name; `never` otherwise. */
 export type NamedIdKey<E> = E extends {
@@ -201,8 +210,11 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
     /**
      * An expression the database computes, never written: spliced into each read, or with `stored` a
      * generated column, `computed: (user) => raw`${user.first} || ' ' || ${user.last}``.
+     *
+     * A relation aggregate is the other form, `computed: (user) => user.resources.count()`, read as the
+     * subquery a `$count` reads. Both resolve to SQL at registration, so everything downstream sees one.
      */
-    readonly computed?: EntitySql<E>;
+    readonly computed?: ComputedSql<E>;
     /** Whether {@link FieldOptions.computed} is a generated column rather than spliced into each read; no query changes either way. */
     readonly stored?: boolean;
     readonly updatable?: boolean;
@@ -258,7 +270,22 @@ export type FieldOptionsFor<V, E = unknown> = (FieldOptions<NonNullable<V>, E> &
 }) | (FieldOptions<NonNullable<V>, E> & {
     readonly references: EntityGetter;
     readonly type?: TypeFor<V>;
+}) | AggregateOptionsFor<V, E>;
+/**
+ * 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`.
+ */
+type AggregateOptionsFor<V, E> = Except<FieldOptions<NonNullable<V>, E>, 'computed' | 'stored' | 'type'> & ({
+    readonly computed: AggregateReading<E, V, boolean>;
+    readonly stored?: false;
+} | {
+    readonly computed: AggregateReading<E, V, true>;
+    readonly stored: true;
 });
+/** An aggregate reading what the property holds, bivariant the way {@link EntitySql} is. */
+type AggregateReading<E, V, S extends boolean> = {
+    agg(refs: ComputedRefs<E>): RelationAggregate<null extends V ? NonNullable<V> | null : NonNullable<V>, S>;
+}['agg'];
 /** The entity a relation points at: `Company` for `company?: Company` and `companies?: Company[]` alike. */
 export type RelationTarget<V> = Extract<Unpacked<V>, object>;
 /**
@@ -360,6 +387,66 @@ export type RefMap<E, F extends keyof E = FieldKey<E>> = {
 export type EntitySql<E> = QueryRaw | {
     sql(refs: RefMap<E>): QueryRaw;
 }['sql'];
+/** The fields of `C` a `sum` or an `avg` can add up. */
+type NumericKey<C> = {
+    readonly [K in FieldKey<C>]-?: [NonNullable<C[K]>] extends [number | bigint] ? K : never;
+}[FieldKey<C>];
+/** One field of `C`, read off its refs: `(item) => item.amount`. */
+type PickRef<C, K extends keyof C> = (refs: RefMap<C>) => ColumnRef<K & string>;
+/**
+ * A relation as a `computed` field reads it, its aggregates typed against the related entity. `count`
+ * and `sum` are the two a row change turns into a delta, so they alone may be `stored`; the rest read
+ * as a subquery and are `null` where the relation holds no row.
+ */
+export type RelationRef<C> = {
+    count(q?: AggregateFilter<C>): RelationAggregate<number, true>;
+    count(q: AggregatePage<C>): RelationAggregate<number, false>;
+    sum<K extends NumericKey<C>>(pick: PickRef<C, K>, q?: AggregateFilter<C>): RelationAggregate<NonNullable<C[K]>, true>;
+    sum<K extends NumericKey<C>>(pick: PickRef<C, K>, q: AggregateTopRows<C>): RelationAggregate<NonNullable<C[K]>, false>;
+    min<K extends FieldKey<C>>(pick: PickRef<C, K>, q?: AggregateRows<C>): RelationAggregate<NonNullable<C[K]> | null, false>;
+    max<K extends FieldKey<C>>(pick: PickRef<C, K>, q?: AggregateRows<C>): RelationAggregate<NonNullable<C[K]> | null, false>;
+    avg<K extends NumericKey<C>>(pick: PickRef<C, K>, q?: AggregateRows<C>): RelationAggregate<number | null, false>;
+};
+/**
+ * What an aggregate reads of the related rows. The predicate is an {@link EntityPredicate} rather than a
+ * full `$where` so that `stored: true` changes no call site: a trigger sees one row, and can evaluate
+ * nothing that traverses a relation or opens a subquery.
+ */
+export type AggregateFilter<C> = {
+    readonly $where?: EntityPredicate<C>;
+};
+/**
+ * A tally capped to a page of the related rows, as `count` itself takes one. It needs no `$sort` and
+ * accepts none: an order picks *which* rows a page holds, never how many.
+ */
+export type AggregatePage<C> = AggregateFilter<C> & Pick<RelationQuery<C>, '$limit' | '$skip'>;
+/**
+ * The rows a value aggregate reads where it reads only some of them - "the five largest" - which only
+ * an order defines, so `$sort` and `$limit` come together. Keyed off the relation read they are, so
+ * the page an aggregate takes and the page a `$populate` takes cannot drift apart.
+ */
+export type AggregateTopRows<C> = AggregateFilter<C> & Required<Pick<RelationQuery<C>, '$sort' | '$limit'>> & Pick<RelationQuery<C>, '$skip'>;
+/** Either of those, for the aggregates that are never `stored` and so need no second signature. */
+export type AggregateRows<C> = AggregateFilter<C> | AggregateTopRows<C>;
+/** What a `computed` callback reads: the entity's fields as columns, its to-many relations as aggregates. */
+export type ComputedRefs<E, F extends keyof E = FieldKey<E>, R extends keyof E = ToManyRelationKey<E>> = RefMap<E, F> & {
+    readonly [K in R]-?: RelationRef<RelationTarget<E[K]>>;
+};
+/** A relation aggregate a definition writes, bivariant the way {@link EntitySql} is. */
+export type EntityAggregate<E> = {
+    agg(refs: ComputedRefs<E>): RelationAggregate;
+}['agg'];
+/**
+ * SQL a `computed` field writes. One callback shape for every arm, aggregate or not: overload
+ * resolution picks a contextual parameter type per arm only while they agree on one.
+ */
+export type ComputedSql<E> = QueryRaw | {
+    sql(refs: ComputedRefs<E>): QueryRaw;
+}['sql'];
+/** The value a field's options declare it holds, where an aggregate is what declares it. */
+export type AggregateValue<O> = O extends {
+    readonly computed: (...args: never[]) => RelationAggregate<infer V>;
+} ? V : never;
 /** A predicate DDL can hold: the entity's own fields, without a relation, `$text` or a sub-query. */
 export type EntityPredicate<E> = QueryWhere<E> & {
     readonly [K in RelationKey<E>]?: never;

package/dist/type/query.d.ts

@@ -1,4 +1,4 @@
-import type { FieldKey, JsonFieldPaths, RelationKey, RelationTarget, WrittenId } from './entity.js';
+import type { FieldKey, JsonFieldPaths, RelationKey, RelationTarget, ToManyRelationKey, WrittenId } from './entity.js';
 import type { QueryLock } from './queryLock.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
@@ -37,7 +37,7 @@ export type QuerySelect<E, F extends keyof E = FieldKey<E>, V = BooleanLike> = {
  * Accepted `$select` value: a field map, or raw SQL projections built with `raw()`
  * (e.g. ``[raw`*`, raw`LOG10(points)`.as('score')]``). The raw form is SQL-only.
  */
-export type QuerySelectValue<E> = QuerySelect<E> | readonly QueryRaw[];
+export type QuerySelectValue<E, Raw = QueryRaw> = QuerySelect<E> | readonly Raw[];
 /**
  * Fields to exclude from the query result - `{ name: true }` blacklists fields.
  * Mutually exclusive with positive field selections in `$select`.
@@ -46,8 +46,8 @@ export type QueryExclude<E> = QuerySelect<E>;
 /**
  * relation population map.
  */
-export type QueryPopulate<E, R extends keyof E = RelationKey<E>> = {
-    [K in R]?: BooleanLike | QueryPopulateRelationOptions<E[K]>;
+export type QueryPopulate<E, Raw = QueryRaw, R extends keyof E = RelationKey<E>> = {
+    [K in R]?: BooleanLike | QueryPopulateRelationOptions<E[K], Raw>;
 };
 /**
  * The key a read carries its relation tallies under. One spelling for the type and the runtime that
@@ -59,8 +59,8 @@ export declare const COUNT_RESULT_KEY = "_count";
  * which ones count: a correlated count in the read's own statement, so no related row is loaded. Comes
  * back under `_count`, which keeps it clear of a relation of the same name `$populate` filled.
  */
-export type QueryCount<E, R extends keyof E = ToManyRelationKey<E>> = {
-    [K in R]?: BooleanLike | QueryFilter<RelationTarget<E[K]>>;
+export type QueryCount<E, Raw = QueryRaw, R extends keyof E = ToManyRelationKey<E>> = {
+    [K in R]?: BooleanLike | QueryFilter<RelationTarget<E[K]>, Raw>;
 };
 /**
  * query conflict paths - subset of field keys used to detect upsert conflicts.
@@ -69,7 +69,7 @@ export type QueryConflictPaths<E> = QuerySelect<E, FieldKey<E>, true>;
 /**
  * Options to populate a relation declared as `V`, by its cardinality.
  */
-export type QueryPopulateRelationOptions<V> = IsMany<V> extends true ? RelationQuery<RelationTarget<V>> : QueryUnique<RelationTarget<V>> & {
+export type QueryPopulateRelationOptions<V, Raw = QueryRaw> = IsMany<V> extends true ? RelationQuery<RelationTarget<V>, Raw> : QueryUnique<RelationTarget<V>, Raw> & {
     $required?: boolean;
 };
 /**
@@ -116,15 +116,6 @@ export type QuerySortDirection = -1 | 1 | 'asc' | 'desc';
  * Accepted value for a field in `$sort` - either a direction or a vector similarity search.
  */
 export type QuerySortValue = QuerySortDirection | QueryVectorSearch;
-/**
- * To-one relations only: a parent holds many rows of a to-many, so there is no single value to order
- * it by, and joining one in would duplicate the parent instead. Order those inside `$populate`.
- */
-type ToOneRelationKey<E> = {
-    [K in RelationKey<E>]: IsMany<E[K]> extends true ? never : K;
-}[RelationKey<E>];
-/** The relation names a parent holds many rows of, which a populated query fills with a list. */
-type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
 /**
  * Ordering parents by how many rows a to-many relation holds - "the ten users with the most posts".
  * The tally is computed per parent as a correlated count, never by loading the rows.
@@ -158,24 +149,24 @@ export type QueryPager = {
 /**
  * Which rows a statement addresses.
  */
-export type QueryFilter<E> = {
+export type QueryFilter<E, Raw = QueryRaw> = {
     /**
      * filtering options.
      */
-    $where?: QueryWhere<E>;
+    $where?: QueryWhere<E, Raw>;
 };
 /**
  * A filter plus the page `count` takes. No `$sort`: ordering picks *which* rows a page holds, never
  * how many, so a count that accepted one would promise an influence it cannot have.
  */
-export type QueryPage<E> = QueryFilter<E> & QueryPager;
+export type QueryPage<E, Raw = QueryRaw> = QueryFilter<E, Raw> & QueryPager;
 /**
  * A filter plus the ordering and page `updateMany`/`deleteMany` take. Both settle the
  * rows they address with a SELECT first, so the page is portable rather than MySQL-only, and a
  * vector `$sort` is as valid here as on a read: it ranks the settle query's rows, which has the
  * projection list to hold the distance. `$lock` stays off these, declared on {@link Query} instead.
  */
-export type QuerySearch<E> = QueryPage<E> & {
+export type QuerySearch<E, Raw = QueryRaw> = QueryPage<E, Raw> & {
     /**
      * sorting options.
      */
@@ -184,21 +175,21 @@ export type QuerySearch<E> = QueryPage<E> & {
 /**
  * query options.
  */
-export type Query<E> = {
+export type Query<E, Raw = QueryRaw> = {
     /**
      * field selection - `{ name: true }` whitelists fields, or raw SQL projections
      * (``[raw`LOG10(points)`.as('score')]``, SQL dialects only - MongoDB rejects the raw-array form).
      * Mutually exclusive with `$exclude`.
      */
-    $select?: QuerySelectValue<E>;
+    $select?: QuerySelectValue<E, Raw>;
     /**
      * relation population options.
      */
-    $populate?: QueryPopulate<E>;
+    $populate?: QueryPopulate<E, Raw>;
     /**
      * how many rows each named relation holds, under `_count` on every row. See {@link QueryCount}.
      */
-    $count?: QueryCount<E>;
+    $count?: QueryCount<E, Raw>;
     /**
      * field exclusion - `{ name: true }` blacklists fields. Mutually exclusive with positive `$select`.
      * Keys a relation is assembled from (a joined row's primary key, a to-many's foreign key) are kept
@@ -227,7 +218,7 @@ export type Query<E> = {
     /**
      * filtering options.
      */
-    $where?: QueryWhere<E>;
+    $where?: QueryWhere<E, Raw>;
     /**
      * Index from where start the search
      */
@@ -237,6 +228,11 @@ export type Query<E> = {
      */
     $limit?: number;
 };
+/**
+ * A {@link Query} as it travels as JSON, which a `raw` SQL fragment cannot: what the browser client takes,
+ * and what an RPC contract (tRPC, oRPC, TanStack Start) declares as its input.
+ */
+export type WireQuery<E> = Query<E, never>;
 /**
  * `Query`'s clauses grouped by the shape of their value, for the wire parser and the relation query
  * check alike; `satisfies` keeps them in step with `Query`.
@@ -262,36 +258,36 @@ type RelationClause = (typeof QUERY_OBJECT_CLAUSES | typeof QUERY_NUMBER_CLAUSES
  * A populated relation's own query: the clause groups its runtime check accepts, so the two cannot
  * drift, and a clause added to {@link Query} stays off it until it joins one of them.
  */
-export type RelationQuery<E = object> = Pick<Query<E>, RelationClause> & {
+export type RelationQuery<E = object, Raw = QueryRaw> = Pick<Query<E, Raw>, RelationClause> & {
     $required?: boolean;
 };
 /**
  * options to get a single record.
  */
-export type QueryOne<E> = Except<Query<E>, '$limit'>;
+export type QueryOne<E, Raw = QueryRaw> = Except<Query<E, Raw>, '$limit'>;
 /**
  * options to get an unique record.
  */
-export type QueryUnique<E> = Pick<QueryOne<E>, '$select' | '$exclude' | '$populate' | '$where'>;
+export type QueryUnique<E, Raw = QueryRaw> = Pick<QueryOne<E, Raw>, '$select' | '$exclude' | '$populate' | '$where'>;
 /**
  * The clauses that shape a row, captured as key sets rather than maps: a naked type parameter skips
  * excess-property checks, while a key set fails its own constraint on a typo.
  * @internal
  */
-type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>> = {
-    $select?: QuerySelect<E, S, V> | readonly QueryRaw[];
+type QueryProjection<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E>, Raw = QueryRaw> = {
+    $select?: QuerySelect<E, S, V> | readonly Raw[];
     $exclude?: QuerySelect<E, X, V>;
-    $populate?: QueryPopulate<E, P>;
-    $count?: QueryCount<E, C & ToManyRelationKey<E>>;
+    $populate?: QueryPopulate<E, Raw, P>;
+    $count?: QueryCount<E, Raw, C & ToManyRelationKey<E>>;
 };
 /**
  * A {@link Query} whose projection is captured, so {@link QueryFindResult} can shape the row.
  */
-export type QueryProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never> = Query<E> & QueryProjection<E, S, V, X, P, C>;
+export type QueryProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never, Raw = QueryRaw> = Query<E, Raw> & QueryProjection<E, S, V, X, P, C, Raw>;
 /**
  * A {@link QueryOne} whose projection is captured, so {@link QueryFindResult} can shape the row.
  */
-export type QueryOneProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never> = QueryOne<E> & QueryProjection<E, S, V, X, P, C>;
+export type QueryOneProjected<E, S extends FieldKey<E>, V, X extends FieldKey<E>, P extends RelationKey<E>, C extends RelationKey<E> = never, Raw = QueryRaw> = QueryOne<E, Raw> & QueryProjection<E, S, V, X, P, C, Raw>;
 /**
  * The keys a query comes back with, as the runtime projects them: a positive `$select`'s, or every
  * field minus what `$select` or `$exclude` subtracts, plus the populated relations.

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);
+}