uql-orm 0.68.1 → 0.69.0

package/dist/entity/decorator/members.js

@@ -1,10 +1,5 @@
 import { relationRegistration } from '../metadata/definition.js';
 import { memberRegistrations } from './bag.js';
-/**
- * Declares a persisted field, its `type` checked against the property's.
- * @example `@Field({ type: String }) name?: string;`
- * @example `@Field({ references: () => User }) userId?: string;`
- */
 export function Field(opts) {
     return (_value, context) => {
         memberRegistrations(context.metadata).fields[String(context.name)] = opts;

package/dist/entity/metadata/definition.js

@@ -1,4 +1,4 @@
-import { SOFT_DELETE_FILTER } from '../../type/index.js';
+import { RelationAggregate, SOFT_DELETE_FILTER } from '../../type/index.js';
 import { isInlinedExpression } from '../../util/field.util.js';
 import { entitySql, entityWhere, fieldOptionConflict, getKeys, hasKeys, isToManyRelation, memberRefs, normalizeIndexColumn, definedEntries, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
@@ -17,6 +17,14 @@ function globalMap(key) {
 const metas = globalMap('uql-orm/entity/metadata/v1');
 export function defineField(entity, key, opts = {}) {
     const meta = ensureWritableMeta(entity);
+    const { computed, ...rest } = opts;
+    const sql = computed === undefined ? undefined : entitySql(computed);
+    // A relation aggregate reads as a correlated subquery, which no engine accepts in a generated column:
+    // keeping one on the row takes the triggers a write fires, which are not built yet.
+    if (opts.stored && sql instanceof RelationAggregate) {
+        throw new TypeError(`'${entity.name}.${key}' cannot be 'stored': a relation aggregate reads as a subquery, which no ` +
+            "engine keeps in a generated column. Drop 'stored' to have it read on each query.");
+    }
     // A stored computed column is a real column and still needs a type; only an inlined one is exempt,
     // its expression being spliced in rather than declared.
     if (!opts.type && !opts.references && !isInlinedExpression(opts)) {
@@ -31,13 +39,12 @@ export function defineField(entity, key, opts = {}) {
     // Flagged when the author gave `references` but no `type`, so schema generation knows to resolve the
     // column from the referenced primary key (picking up its `columnType`, length and chained keys)
     // instead of treating whatever ends up in `type` as deliberate.
-    const { computed, ...rest } = opts;
     const resolved = rest.type ? rest : { ...rest, typeFromReference: true };
     meta.fields[fieldKey] = {
         ...meta.fields[fieldKey],
         name: key,
         ...resolved,
-        ...(computed && { computed: entitySql(computed) }),
+        ...(sql && { computed: sql }),
     };
     return meta;
 }

package/dist/migrate/introspection/postgresIntrospector.d.ts

@@ -14,6 +14,12 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
     protected getTableNamesQuery(): string;
     protected tableExistsQuery(): string;
     protected parseTableExistsResult([row]: RawRow[]): boolean;
+    /**
+     * The comment reads through `to_regclass` rather than a `::regclass` cast: a name resolves against
+     * the live catalogue while `information_schema` answers from this statement's snapshot, so a table
+     * another connection has just dropped is still listed here and the cast would raise on it. Whole
+     * database scans meet that table every time something else is migrating.
+     */
     protected getColumnsQuery(_tableName: string): string;
     /**
      * `attname` where the entry is a column, `pg_get_indexdef` for that one position where it is an

package/dist/migrate/introspection/postgresIntrospector.js

@@ -37,6 +37,12 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     parseTableExistsResult([row]) {
         return row['exists'] === true;
     }
+    /**
+     * The comment reads through `to_regclass` rather than a `::regclass` cast: a name resolves against
+     * the live catalogue while `information_schema` answers from this statement's snapshot, so a table
+     * another connection has just dropped is still listed here and the cast would raise on it. Whole
+     * database scans meet that table every time something else is migrating.
+     */
     getColumnsQuery(_tableName) {
         return /*sql*/ `
       SELECT
@@ -68,7 +74,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
           HAVING COUNT(*) = 1 AND MIN(kcu.column_name) = c.column_name
         ) AS is_unique,
         pg_catalog.col_description(
-          (quote_ident(c.table_schema) || '.' || quote_ident(c.table_name))::regclass,
+          to_regclass(quote_ident(c.table_schema) || '.' || quote_ident(c.table_name)),
           c.ordinal_position
         ) AS column_comment
       FROM information_schema.columns c

package/dist/mongo/mongoDialect.d.ts

@@ -139,9 +139,35 @@ export declare class MongoDialect extends AbstractDialect {
         readonly stages: MongoAggregationPipelineEntry<Document>[];
         readonly fields: string[];
     };
-    /** The correlated lookup counting a relation's rows, which `where` narrows, into `temp`. */
-    private tallyLookup;
-    /** The tally a lookup left in `temp`, which holds no row at all where nothing matched: a zero. */
+    /** Whether a read answers with a relation aggregate, which only the pipeline can build. */
+    readsAggregates<E extends Document>(entity: Type<E>, q: Query<E>): boolean;
+    /**
+     * 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.
+     */
+    private aggregateKeys;
+    /**
+     * 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.
+     */
+    private aggregateFieldStages;
+    /**
+     * 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.
+     */
+    private aggregateStages;
+    /**
+     * 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.
+     */
     private tally;
     /**
      * The lookups reading each to-many a query populates, and the tally of each `$count`, onto the fields

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. */
@@ -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';
@@ -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.

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/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) => {

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>[];