uql-orm 0.68.1 → 0.70.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,12 +1,12 @@
 import { fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, VECTOR_QUERY_KEYS, } from '../type/index.js';
 import { isInlinedExpression } from '../util/field.util.js';
-import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, columnFamily, countedRelations, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, populatesRelations, raw, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, assertNonNegativeInteger, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, idOnlyQuery, columnFamily, countedRelations, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorKey, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, populatesRelations, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
-import { COUNT_ALIAS, COUNTED_ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn } from './aliases.js';
+import { AGGREGATE_PAGE_ALIAS, AGGREGATE_VALUE_ALIAS, ROWS_ALIAS, JSON_ELEM_ALIAS, JSON_PULL_ALIAS, relationSortColumn, } from './aliases.js';
 import { holdsOperator, isJsonScalar, jsonCompareMode, jsonElemExists, jsonPath, } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
-import { NO_JOINS, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
+import { groupPathField, NO_JOINS, resolveGroupJoins, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
 import { resolveVectorCast } from './vectorCast.js';
 import { VectorSqlDialect } from './vectorSqlDialect.js';
 /** The key a term answers under in a populated relation's row, which a raw expression has only once aliased. */
@@ -795,7 +795,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                     }
                     columns.push({
                         key: keyPath,
-                        expr: this.buildFragment(ctx, (fragmentCtx) => this.appendRelationSubquery(fragmentCtx, meta, key, relation, { prefix }, 'COUNT(*)', {})),
+                        expr: this.buildFragment(ctx, (fragmentCtx) => this.appendRelationSubquery(fragmentCtx, meta, key, relation, { prefix }, { op: '$count' })),
                         direction: this.resolveSortDirection(countDirection),
                         output: false,
                     });
@@ -916,7 +916,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     count(ctx, entity, q, opts) {
         const { $where, $skip, $limit } = q;
         if ($skip === undefined && $limit === undefined) {
-            this.select(ctx, entity, { $select: [raw `COUNT(*)`.as(COUNT_ALIAS)] });
+            this.select(ctx, entity, { $select: [raw `COUNT(*)`.as(AGGREGATE_VALUE_ALIAS)] });
             this.search(ctx, entity, { $where }, opts);
             return;
         }
@@ -936,9 +936,9 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** `SELECT COUNT(*)` over the rows `rows` appends, as a derived table. */
     countRows(ctx, rows) {
-        ctx.append(`SELECT COUNT(*) ${this.escapeId(COUNT_ALIAS, true)} FROM (`);
+        ctx.append(`SELECT COUNT(*) ${this.escapeId(AGGREGATE_VALUE_ALIAS, true)} FROM (`);
         rows();
-        ctx.append(`) ${this.escapeId(COUNTED_ROWS_ALIAS, true)}`);
+        ctx.append(`) ${this.escapeId(ROWS_ALIAS, true)}`);
     }
     /**
      * The statistic the engine already keeps, as a `count` column. Overridden by the dialects that
@@ -958,35 +958,40 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     };
     aggregate(ctx, entity, q, opts = {}) {
         const meta = getMeta(entity);
-        const tableName = this.escapedTableName(meta);
+        const entries = parseGroupMap(q.$group, q.$select);
+        if (!entries.length) {
+            throw new TypeError('aggregate requires at least one $group column or $select function');
+        }
+        const table = this.tableRef(meta, this.readOptions(ctx, meta).alias);
+        const joins = resolveGroupJoins(meta, q.$group, (path) => ctx.claimAlias(path));
+        const prefix = joins.size ? table.alias : undefined;
+        const reads = entries.map((entry) => ({ entry, value: this.aggregateValue(ctx, entity, entry, joins, prefix) }));
+        // Only bare columns are read inline: SQL Server refuses a subquery inside an aggregate or a
+        // `GROUP BY`, and a filter's bound values would repeat in `HAVING`. A derived table answers by alias.
+        const derived = reads.some(({ value }) => !value.bare);
+        const named = (sql, alias) => sql === this.escapeId(alias) ? sql : `${sql} ${this.escapeId(alias)}`;
         const groupKeys = [];
         const selectParts = [];
         // Every column the statement emits, mapped to the SQL that references it. `$having` and `$sort`
         // may name these and nothing else, so one map answers both "is this legal?" and "what do I
         // emit for it?".
         const emittedColumns = {};
-        for (const entry of parseGroupMap(q.$group, q.$select)) {
+        for (const { entry, value } of reads) {
+            const column = derived ? this.escapeId(entry.alias) : value.sql;
+            const expr = entry.kind === 'key' ? column : this.aggregateFn(entry.op, value.sql === '*' ? '*' : column, entry.distinct);
             if (entry.kind === 'key') {
-                const field = meta.fields[entry.alias];
-                const columnName = this.resolveColumnName(entry.alias, field);
-                const escaped = this.escapeId(columnName);
-                groupKeys.push(escaped);
-                emittedColumns[entry.alias] = escaped;
-                selectParts.push(columnName !== entry.alias ? `${escaped} ${this.escapeId(entry.alias)}` : escaped);
-            }
-            else {
-                const sqlFn = AbstractSqlDialect.AGGREGATE_FN[entry.op];
-                const sqlArg = entry.fieldRef === '*' ? '*' : this.escapeId(this.columnOf(meta, entry.fieldRef));
-                const expr = `${sqlFn}(${entry.distinct ? 'DISTINCT ' : ''}${sqlArg})`;
-                emittedColumns[entry.alias] = expr;
-                selectParts.push(`${expr} ${this.escapeId(entry.alias)}`);
+                groupKeys.push(expr);
             }
+            emittedColumns[entry.alias] = expr;
+            selectParts.push(named(expr, entry.alias));
         }
-        if (!selectParts.length) {
-            throw new TypeError('aggregate requires at least one $group column or $select function');
+        const columns = reads.flatMap(({ entry, value }) => (value.sql === '*' ? [] : [named(value.sql, entry.alias)]));
+        ctx.append(`SELECT ${selectParts.join(', ')} FROM ${derived ? `(SELECT ${columns.join(', ')} FROM ` : ''}${table.ref}`);
+        this.selectRelationJoins(ctx, meta, table.alias, joins);
+        this.where(ctx, entity, q.$where, { ...opts, prefix });
+        if (derived) {
+            ctx.append(`) ${this.escapeId(ROWS_ALIAS, true)}`);
         }
-        ctx.append(`SELECT ${selectParts.join(', ')} FROM ${tableName}`);
-        this.where(ctx, entity, q.$where, opts);
         if (groupKeys.length) {
             ctx.append(` GROUP BY ${groupKeys.join(', ')}`);
         }
@@ -996,6 +1001,34 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const sorted = this.aggregateSort(ctx, q.$sort, emittedColumns);
         this.pager(ctx, q, sorted);
     }
+    /**
+     * What one entry reads: a grouped field, through the join its path passes, or an aggregate's argument,
+     * narrowed by its own `$where` to `CASE WHEN … THEN … END`. Bare where it is a column or `'*'`.
+     */
+    aggregateValue(ctx, entity, entry, joins, prefix) {
+        if (entry.kind === 'key') {
+            const { key, join } = groupPathField(joins, entry.path);
+            return join
+                ? this.aggregateOperand(ctx, join.entity, key, join.alias)
+                : this.aggregateOperand(ctx, entity, key, prefix);
+        }
+        const arg = entry.fieldRef === '*' ? undefined : this.aggregateOperand(ctx, entity, entry.fieldRef, prefix);
+        const { where } = entry;
+        const condition = where &&
+            this.buildFragment(ctx, (fragment) => this.renderWhere(fragment, entity, where, { clause: false, prefix }));
+        if (!condition) {
+            return arg ?? { sql: '*', bare: true };
+        }
+        return { sql: `CASE WHEN ${condition} THEN ${arg?.sql ?? '1'} END`, bare: false };
+    }
+    /** A field as an aggregate reads it: its column, or the expression an inlined one stands for. */
+    aggregateOperand(ctx, entity, key, prefix) {
+        const field = getMeta(entity).fields[key];
+        return {
+            sql: this.resolveOperandField(ctx, entity, key, { prefix }),
+            bare: field === undefined || !isInlinedExpression(field),
+        };
+    }
     /**
      * ORDER BY for aggregate queries - handles both entity-field and alias references. A grouped
      * statement has no joins to address, so a relation key is rejected rather than emitted as an alias
@@ -1296,7 +1329,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         const decoded = [];
         for (const [key, field] of Object.entries(meta.fields)) {
-            const kind = this.hydrateKind(field);
+            const kind = this.fieldKind(meta, field);
             if (kind) {
                 decoded.push([key, kind]);
             }
@@ -1304,28 +1337,46 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         this.hydratable.set(entity, [meta.revision, decoded]);
         return decoded;
     }
-    /**
-     * The same for an aggregate's row, per query: a count or total is a number however the engine widened
-     * it, and `$min`/`$max` or a grouped column decodes as its field does.
-     */
+    /** The same for an aggregate's row, per query: each alias decodes by {@link aggregateKind}. */
     hydratableAggregates(entity, q) {
-        const { fields } = getMeta(entity);
+        const meta = getMeta(entity);
+        const joins = resolveGroupJoins(meta, q.$group);
         const decoded = [];
         for (const entry of parseGroupMap(q.$group, q.$select)) {
-            if (entry.kind === 'fn' && entry.op !== '$min' && entry.op !== '$max') {
-                decoded.push([entry.alias, 'number']);
-                continue;
-            }
-            // `$min`/`$max` read the field they aggregate; a `$group` column is that field. Only `$count`
-            // takes `'*'`, and it went down the numeric path above, so there is always a field to look up.
-            const key = entry.kind === 'fn' ? entry.fieldRef : entry.alias;
-            const kind = this.hydrateKind(fields[key]);
+            const kind = entry.kind === 'fn'
+                ? this.aggregateKind(entry.op, this.fieldKind(meta, meta.fields[entry.fieldRef]))
+                : this.groupedKind(meta, joins, entry.path);
             if (kind) {
                 decoded.push([entry.alias, kind]);
             }
         }
         return decoded;
     }
+    /**
+     * What an aggregate's value decodes as, which the engine widens beyond the column it read: a tally
+     * (`COUNT` to Postgres's `bigint`) and a mean (`AVG` to `numeric`) are numbers whatever they counted,
+     * and the rest read as the column they aggregate - so a `SUM` over a wide integer stays exact rather
+     * than rounding through a float, which is what every driver's BIGINT decoding promises.
+     *
+     * One rule for both readers: a relation aggregate a field declares, and an aggregate a query names.
+     */
+    aggregateKind(op, fieldKind) {
+        return op === '$count' || op === '$avg' ? 'number' : fieldKind;
+    }
+    /** What a grouped path decodes as: the kind of the field it reaches, through its join or on the entity. */
+    groupedKind(meta, joins, path) {
+        const { key, join } = groupPathField(joins, path);
+        return join ? this.fieldKind(join.meta, join.meta.fields[key]) : this.fieldKind(meta, meta.fields[key]);
+    }
+    /** What a field decodes as: its column's kind, or a relation aggregate's {@link aggregateKind} over the target's column. */
+    fieldKind(meta, field) {
+        const spec = aggregateOf(field);
+        if (!spec) {
+            return this.hydrateKind(field);
+        }
+        const target = getMeta(relationOf(meta, spec.relation).entity());
+        return this.aggregateKind(spec.op, spec.field ? this.fieldKind(target, target.fields[spec.field]) : undefined);
+    }
     /** What one column decodes as, the inverse of {@link persistKind}. `BigInt` first, since it shares the numeric family. */
     hydrateKind(field) {
         const type = field?.type;
@@ -1382,8 +1433,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * `$pull` reads the column and every later one its expression once, so no value binds twice.
      */
     formatJsonUpdate(ctx, escapedCol, value, field) {
-        // Centralizes the one narrowing cast: the payload's keys are typed against the entity's JSON
-        // payload, which the dialects do not need - they only build SQL from keys and values.
         const { $pull, $set, $push, $unset } = value;
         let expr = escapedCol;
         if (hasKeys($pull)) {
@@ -1519,14 +1568,18 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * invisible here just as it is to a joined `$populate`. The caller's filter bypass is deliberately
      * not propagated (`withDeleted()` does not reach into relations), matching `selectRelationJoins`.
      */
-    appendRelationSubquery(ctx, meta, relKey, rel, opts, projection, val) {
+    appendRelationSubquery(ctx, meta, relKey, rel, opts, read) {
         const relatedEntity = rel.entity();
         const relatedMeta = getMeta(relatedEntity);
         const parent = opts.prefix ?? this.resolveTableAlias(meta);
         // Resolved before any SQL is emitted: it also decides whether the junction form reaches the target.
-        const targetWhere = this.scopedWhere(relatedMeta, val);
-        ctx.append(`(SELECT ${projection} FROM `);
+        const targetWhere = this.scopedWhere(relatedMeta, read.query?.$where ?? {});
         if (rel.through) {
+            // The rows here are the junction's own, so a column of the far side is read as a page instead.
+            if (read.field) {
+                throw new TypeError(`cannot read ${read.op}('${read.field}') over the many-to-many '${relKey}' without a page: its rows are the junction's, so name a '$sort' and a '$limit' to read the target's own`);
+            }
+            ctx.append(`(SELECT ${read.op === 'exists' ? '1' : 'COUNT(*)'} FROM `);
             const junction = this.junctionRows(ctx, meta, rel, rel.through(), parent);
             ctx.append(junction.from);
             if (hasKeys(targetWhere)) {
@@ -1539,13 +1592,76 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             }
         }
         else {
+            // The alias is claimed before the SELECT is written, since an aggregate names a column of it.
             const related = this.tableRef(relatedMeta, ctx.claimAlias(relKey, parent));
+            ctx.append(`(SELECT ${this.aggregateProjection(read, related.alias, relatedMeta)} FROM `);
             ctx.append(related.ref);
             ctx.append(` WHERE ${this.correlation(meta, rel, parent, related.alias, relatedMeta)}`);
             this.renderWhere(ctx, relatedEntity, targetWhere, { prefix: related.alias, clause: 'AND' });
         }
         ctx.append(')');
     }
+    /**
+     * What a relation subquery selects: the literals a relation operator reads, or an aggregate over one
+     * of the target's columns. `count` and `sum` answer `0` on a parent with no rows, which is what makes
+     * them the two a trigger could keep; the rest answer `NULL`, and the field's type says so.
+     */
+    aggregateProjection(projection, alias, relatedMeta) {
+        if (projection.op === 'exists') {
+            return '1';
+        }
+        return this.aggregateCall(projection.op, projection.field ? this.escapedColumn(alias, relatedMeta, projection.field) : '');
+    }
+    /**
+     * A relation aggregate as the correlated subquery a `computed` field reads, the same one `$count`
+     * emits: `(user) => user.resources.count()` renders here, wherever the field is named.
+     */
+    appendRelationAggregate(ctx, entity, aggregate, prefix) {
+        const meta = getMeta(entity);
+        const rel = relationOf(meta, aggregate.relation);
+        const parent = prefix || this.resolveTableAlias(meta);
+        const { $limit, $skip } = aggregate.query ?? {};
+        if ($limit === undefined && $skip === undefined) {
+            this.appendRelationSubquery(ctx, meta, aggregate.relation, rel, { prefix: parent }, aggregate);
+            return;
+        }
+        // Capped: the rows it reads are a page of the relation, so they are read first - ordered, since an
+        // order is what picks them - and the aggregate runs over that page.
+        const pageAlias = this.escapeId(AGGREGATE_PAGE_ALIAS);
+        const value = this.escapeId(AGGREGATE_VALUE_ALIAS);
+        ctx.append(`(SELECT ${this.aggregateCall(aggregate.op, `${pageAlias}.${value}`)} FROM (`);
+        this.appendRelationPage(ctx, meta, rel, aggregate, parent);
+        ctx.append(`) ${pageAlias})`);
+    }
+    /**
+     * The page a capped aggregate reads: an ordinary read of the related entity under its own alias,
+     * narrowed to the parent's rows, carrying out the one column the aggregate runs over. Its `$sort`,
+     * `$limit` and `$skip` are the relation's own, and its filters apply as they do to any read.
+     */
+    appendRelationPage(ctx, meta, rel, aggregate, parent) {
+        const entity = rel.entity();
+        const alias = ctx.claimAlias(aggregate.relation, parent);
+        const correlation = raw(({ ctx: pageCtx }) => this.appendCorrelation(pageCtx, meta, rel, parent, alias));
+        const { $where, ...page } = aggregate.query ?? {};
+        // `1` where nothing is aggregated: a tally counts the rows the page holds, whatever they carry.
+        const read = aggregate.field ? refs(entity)[aggregate.field] : raw `1`;
+        const query = {
+            ...page,
+            $select: [read.as(AGGREGATE_VALUE_ALIAS)],
+            $where: { ...$where, $and: [...($where?.$and ?? []), correlation] },
+        };
+        const joins = resolveQueryJoins(getMeta(entity), query, (path) => ctx.claimAlias(path));
+        this.read(ctx, entity, query, { alias }, joins);
+    }
+    /** A relation aggregate over an operand, reading `0` on a parent with no rows where its type says so. */
+    aggregateCall(op, operand) {
+        const call = this.aggregateFn(op, op === '$count' ? '*' : operand);
+        return op === '$sum' ? `COALESCE(${call}, 0)` : call;
+    }
+    /** One aggregate function call, the one spelling every statement that aggregates writes. */
+    aggregateFn(op, operand, distinct) {
+        return `${AbstractSqlDialect.AGGREGATE_FN[op]}(${distinct ? 'DISTINCT ' : ''}${operand})`;
+    }
     /**
      * One equality per key of the parent, anded: a composite correlates on every column, and matching on
      * part of one would find the rows of a different parent. `parentJoins` keeps the two ends the right
@@ -1571,7 +1687,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     /** Each relation a read's `$count` tallies, as a correlated count of its select list. */
     selectRelationCounts(ctx, meta, count, parent) {
         return countedRelations(meta, count).map(({ relKey, relation, where }) => {
-            const sql = this.buildFragment(ctx, (fragmentCtx) => this.appendRelationSubquery(fragmentCtx, meta, relKey, relation, { prefix: parent }, 'COUNT(*)', where));
+            const sql = this.buildFragment(ctx, (fragmentCtx) => this.appendRelationSubquery(fragmentCtx, meta, relKey, relation, { prefix: parent }, { op: '$count', query: { $where: where } }));
             return { sql, key: `${COUNT_RESULT_KEY}.${relKey}` };
         });
     }
@@ -1670,11 +1786,11 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     /** Filter by relation: a parent matches when {@link appendRelationSubquery} finds one target row. */
     compareRelation(ctx, entity, relKey, val, rel, opts) {
         ctx.append('EXISTS ');
-        this.appendRelationSubquery(ctx, getMeta(entity), relKey, rel, opts, '1', val);
+        this.appendRelationSubquery(ctx, getMeta(entity), relKey, rel, opts, { op: 'exists', query: { $where: val } });
     }
     /** Filter by relation size: the same subquery, counting instead of testing for existence. */
     compareRelationSize(ctx, entity, relKey, sizeVal, rel, opts) {
-        const count = (fragmentCtx) => this.appendRelationSubquery(fragmentCtx, getMeta(entity), relKey, rel, opts, 'COUNT(*)', {});
+        const count = (fragmentCtx) => this.appendRelationSubquery(fragmentCtx, getMeta(entity), relKey, rel, opts, { op: '$count' });
         ctx.append(this.sizeCondition(ctx, count, sizeVal));
     }
     /**

package/dist/dialect/aliases.d.ts

@@ -1,9 +1,20 @@
-/** The column every internally-built count answers in: `COUNT(*)`, a grouped tally, a `$count` stage. */
-export declare const COUNT_ALIAS = "_uql_count";
 /** The column a paged read carries its own unpaged total in, from `COUNT(*) OVER ()`. */
 export declare const TOTAL_ALIAS = "_uql_total";
-/** The derived table a count wraps the rows it counts in: a page, or a `$distinct` set. MySQL requires the alias. */
-export declare const COUNTED_ROWS_ALIAS = "_uql_rows";
+/**
+ * The derived table a statement wraps the rows it counts or aggregates in: a page, a `$distinct` set, or
+ * rows computing an inlined field an aggregate names. MySQL requires the alias.
+ */
+export declare const ROWS_ALIAS = "_uql_rows";
+/** The derived table a capped relation aggregate reads: the page is taken first, then aggregated over. */
+export declare const AGGREGATE_PAGE_ALIAS = "_uql_page";
+/**
+ * The one value a statement that aggregates answers under: a `COUNT(*)` or an estimate, the column a
+ * capped page carries out for the aggregate wrapping it, and the field a MongoDB `$group` or `$count`
+ * leaves its result in. One name, since both ends of each are written and read here.
+ */
+export declare const AGGREGATE_VALUE_ALIAS = "_uql_value";
+/** Beside each MongoDB `$sum`, how many values it read: `$sum` answers 0 over none, where SQL answers null. */
+export declare const SUM_COUNT_ALIAS = "_uql_count";
 /** The row a Postgres relation aggregates whole: a LATERAL projection of the columns it answers under. */
 export declare const RELATION_ROW_ALIAS = "_uql_row";
 /** The alias an exploded JSON array element is read through, `_uql_elem_2` and on where one nests in another. */

package/dist/dialect/aliases.js

@@ -1,11 +1,22 @@
 // Every identifier UQL invents, `_uql`-prefixed to stay off a user's own, collected in one place:
 // the ends writing and reading one sit in different modules, and a drift between them fails silently.
-/** The column every internally-built count answers in: `COUNT(*)`, a grouped tally, a `$count` stage. */
-export const COUNT_ALIAS = '_uql_count';
 /** The column a paged read carries its own unpaged total in, from `COUNT(*) OVER ()`. */
 export const TOTAL_ALIAS = '_uql_total';
-/** The derived table a count wraps the rows it counts in: a page, or a `$distinct` set. MySQL requires the alias. */
-export const COUNTED_ROWS_ALIAS = '_uql_rows';
+/**
+ * The derived table a statement wraps the rows it counts or aggregates in: a page, a `$distinct` set, or
+ * rows computing an inlined field an aggregate names. MySQL requires the alias.
+ */
+export const ROWS_ALIAS = '_uql_rows';
+/** The derived table a capped relation aggregate reads: the page is taken first, then aggregated over. */
+export const AGGREGATE_PAGE_ALIAS = '_uql_page';
+/**
+ * The one value a statement that aggregates answers under: a `COUNT(*)` or an estimate, the column a
+ * capped page carries out for the aggregate wrapping it, and the field a MongoDB `$group` or `$count`
+ * leaves its result in. One name, since both ends of each are written and read here.
+ */
+export const AGGREGATE_VALUE_ALIAS = '_uql_value';
+/** Beside each MongoDB `$sum`, how many values it read: `$sum` answers 0 over none, where SQL answers null. */
+export const SUM_COUNT_ALIAS = '_uql_count';
 /** The row a Postgres relation aggregates whole: a LATERAL projection of the columns it answers under. */
 export const RELATION_ROW_ALIAS = '_uql_row';
 /** The alias an exploded JSON array element is read through, `_uql_elem_2` and on where one nests in another. */

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -2,7 +2,7 @@ import { getMeta } from '../entity/index.js';
 import { textSearchFields } from '../util/index.js';
 import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect, } from './abstractSqlDialect.js';
-import { COUNT_ALIAS } from './aliases.js';
+import { AGGREGATE_VALUE_ALIAS } from './aliases.js';
 import { BYTES_PREFIX } from './hydrateColumn.js';
 import { jsonSetCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.js';
 import { aggregatesRelations } from './queryJoins.js';
@@ -27,6 +27,7 @@ export const MYSQL_FEATURES = {
     stringSizing: 'varchar',
     supportsUnsigned: true,
     serverSideCursors: false,
+    correlatedWrites: true,
     rowLocks: true,
     rowLockWithWindow: true,
     rowLockOf: true,
@@ -49,7 +50,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     estimatedCount(ctx, entity) {
         const meta = getMeta(entity);
         const schema = this.resolveSchema(meta);
-        ctx.append(`SELECT TABLE_ROWS ${this.escapeId(COUNT_ALIAS, true)} FROM information_schema.TABLES WHERE TABLE_SCHEMA = `);
+        ctx.append(`SELECT TABLE_ROWS ${this.escapeId(AGGREGATE_VALUE_ALIAS, true)} FROM information_schema.TABLES WHERE TABLE_SCHEMA = `);
         if (schema) {
             ctx.addValue(schema);
         }

package/dist/dialect/pgLikeSqlDialect.js

@@ -29,6 +29,7 @@ export const PG_FEATURES = {
     stringSizing: 'bounded-text',
     supportsUnsigned: false,
     serverSideCursors: true,
+    correlatedWrites: true,
     rowLocks: true,
     rowLockWithWindow: false,
     rowLockOf: true,

package/dist/dialect/queryJoins.d.ts

@@ -1,4 +1,4 @@
-import type { EntityMeta, Query, QuerySortMap, RelationMeta, RelationQuery, Type } from '../type/index.js';
+import type { EntityMeta, Query, QueryGroupMap, QuerySortMap, RelationMeta, RelationQuery, Type } from '../type/index.js';
 /**
  * One relation a statement joins, keyed by the alias its columns are addressed by (`tax`,
  * `tax.category`). `projected` tells a `$populate` join, whose columns are selected, from one only
@@ -39,6 +39,13 @@ export type QuerySortOptions = {
  * columns, the `ORDER BY` and the lock agree. `claimAlias` names each join's table, parents first.
  */
 export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>, claimAlias?: (path: string) => string): QueryJoins;
+/** What an aggregate joins: each to-one relation a `$group` path passes through. */
+export declare function resolveGroupJoins<E>(meta: EntityMeta<E>, group: QueryGroupMap<E> | undefined, claimAlias?: (path: string) => string): QueryJoins;
+/** The field a grouped `path` reads, and the join it reads it through: none for the entity's own. */
+export declare function groupPathField(joins: QueryJoins, path: readonly string[]): {
+    readonly key: string;
+    readonly join: QueryJoin | undefined;
+};
 /**
  * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
  * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or

package/dist/dialect/queryJoins.js

@@ -1,5 +1,5 @@
 import { getMeta, relationOf } from '../entity/index.js';
-import { getKeys, getRelationRequestSummary, isToManyRelation, parseRelationAtKey } from '../util/index.js';
+import { getKeys, getRelationRequestSummary, isRecord, isToManyRelation, parseRelationAtKey } from '../util/index.js';
 export const NO_JOINS = new Map();
 /**
  * What the statement joins, from `$populate` and from a `$sort` by a to-one relation's field, so the
@@ -11,9 +11,31 @@ export function resolveQueryJoins(meta, q, claimAlias = (path) => path) {
     }
     const joins = new Map();
     addPopulateJoins(joins, claimAlias, meta, q.$populate);
-    addSortJoins(joins, claimAlias, meta, q.$sort);
+    addPathJoins(joins, claimAlias, meta, q.$sort);
     return joins;
 }
+/** What an aggregate joins: each to-one relation a `$group` path passes through. */
+export function resolveGroupJoins(meta, group, claimAlias = (path) => path) {
+    const joins = new Map();
+    for (const ref of Object.values(group ?? {})) {
+        if (isRecord(ref)) {
+            addPathJoins(joins, claimAlias, meta, ref);
+        }
+    }
+    return joins;
+}
+/** The field a grouped `path` reads, and the join it reads it through: none for the entity's own. */
+export function groupPathField(joins, path) {
+    const key = path[path.length - 1];
+    if (path.length === 1) {
+        return { key, join: undefined };
+    }
+    const join = joins.get(path.slice(0, -1).join('.'));
+    if (!join) {
+        throw new TypeError(`cannot $group by '${path.join('.')}': only a to-one relation's field groups, since a to-many multiplies the rows it joins`);
+    }
+    return { key, join };
+}
 /**
  * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
  * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or
@@ -71,21 +93,22 @@ function addPopulateJoins(joins, claimAlias, meta, populate, parent) {
         addPopulateJoins(joins, claimAlias, join.meta, query.$populate, join);
     }
 }
-function addSortJoins(joins, claimAlias, meta, sort, parent) {
-    if (!sort) {
+/** The to-one relations a nested map of fields passes through, a `$sort` or a `$group` path, as joins adding no columns. */
+function addPathJoins(joins, claimAlias, meta, map, parent) {
+    if (!map) {
         return;
     }
-    for (const key of getKeys(sort)) {
+    for (const key of getKeys(map)) {
         const relation = meta.relations[key];
-        const value = sort[key];
+        const value = map[key];
         // A to-many, or a value that is not a map of the relation's own fields, cannot be joined and is
-        // reported where the `ORDER BY` is rendered - the one place that knows how to name it.
+        // reported where the statement names it - the one place that knows how to.
         if (!relation || isToManyRelation(relation) || !isSortMap(value)) {
             continue;
         }
         const join = addJoin(joins, claimAlias, parent, key, relation, {}, false, false);
-        // `E` stated: inferred from a `QuerySortMap<object>`, it lands on the nested relation's target.
-        addSortJoins(joins, claimAlias, join.meta, value, join);
+        // `E` stated: inferred from the nested map, it lands on the nested relation's target.
+        addPathJoins(joins, claimAlias, join.meta, value, join);
     }
 }
 /** The join a sort may address at `path` with the relation's own sort map, or why it may not; `unjoinable` is the dialect's remedy. */
@@ -102,7 +125,7 @@ export function resolveSortableJoin(relation, path, value, joins, unjoinable) {
     }
     return { join, sort: value };
 }
-/** A nested `$sort` map, as opposed to a direction or a vector search. */
+/** A nested map of fields, as opposed to a `$sort` direction or vector search, or a `$group` field's `true`. */
 function isSortMap(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value) && !('$vector' in value);
 }

package/dist/entity/decorator/members.d.ts

@@ -1,7 +1,19 @@
-import type { EntityGetter, FieldOptions, FieldType, HasCompositeKey, IdValue, NamedIdKey, RejectKeys, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
+import type { AggregateValue, ComputedRefs, EntityAggregate, EntityGetter, Except, FieldOptions, FieldType, HasCompositeKey, IdValue, NamedIdKey, RejectKeys, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, RelationAggregate, TsTypeOf, Writable } from '../../type/index.js';
 import type { RejectIncompatible } from '../../util/index.js';
 /** A member decorator that also constrains the property it may be applied to, on a class `O`. */
 type MemberDecorator<V, O = unknown> = (value: undefined, context: ClassFieldDecoratorContext<O, V>) => void;
+/**
+ * A {@link MemberDecorator} whose property has to admit `M` as well as hold `V`. A decorator context is
+ * covariant in its value, so on its own it takes a property narrower than the field reads: a `string`
+ * where a nullable column reads `string | null`, a `number` where `max()` reads `number | null`.
+ *
+ * `M` is what each arm insists on rather than the whole of `V`, because a column type that names a
+ * family - `jsonb`, whose document the property shapes, or `numeric`, either number kind - is meant to
+ * be narrowed. A column insists on its `null`; an aggregate, whose value is exact, insists on all of it.
+ */
+type AdmittingDecorator<V, M, O> = <P extends V | undefined>(value: undefined, context: ClassFieldDecoratorContext<O, P> & ([Writable<M>] extends [Writable<P>] ? unknown : {
+    readonly __propertyMustAdmit: M;
+})) => void;
 /**
  * The property type a set of field options describes: the declared `type`, narrowed by `enum` to the
  * values that type admits (so `enum: [2]` stays off a `String`), or else the referenced key's own type,
@@ -16,6 +28,16 @@ type DeclaredValue<O> = O extends {
 } ? HasCompositeKey<E> extends true ? {
     readonly __compositeKeyNeedsAColumnPerKey: true;
 } : IdValue<E> : never;
+/**
+ * The `null` a column reads back: every one holds it unless `nullable: false` says otherwise, so the
+ * property admits it too. A key holds none, whether `@Id` or `@Field({ isId: true })` declares it, since
+ * it is NOT NULL on every engine.
+ */
+type NullOf<O> = O extends {
+    readonly nullable: false;
+} | {
+    readonly isId: true;
+} ? never : null;
 /** The enum's members, or a named complaint where they widened for lack of `as const`, which would check nothing. */
 type EnumValue<Members, Declared> = Declared extends Members ? {
     readonly __enumNeedsAsConst: true;
@@ -29,7 +51,27 @@ export declare function Field<This, O extends FieldOptions<DeclaredValue<O>, Thi
     type: FieldType;
 } | {
     references: EntityGetter;
-}) & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined, This>;
+}) & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O>>(opts: O): AdmittingDecorator<DeclaredValue<O> | NullOf<O>, NullOf<O>, This>;
+/**
+ * Declares a field a relation aggregate computes, `@Field({ computed: (user) => user.resources.count() })`.
+ * The aggregate says what the field holds, so it takes no `type`, and only `count` and `sum` - the two a
+ * row change turns into a delta - may be `stored`.
+ * @example `@Field({ computed: (user) => user.resources.count() }) readonly resourceCount?: number;`
+ */
+export declare function Field<This, O extends AggregateOptions<This> & RejectKeys<Exclude<keyof O, keyof FieldOptions>>>(opts: O): AdmittingDecorator<AggregateValue<O>, AggregateValue<O>, This>;
+/**
+ * A field the aggregate itself types: `stored: true` only where a trigger could keep it, and every other
+ * option as a column takes it.
+ */
+type AggregateOptions<E> = (Except<FieldOptions<never, E>, 'computed' | 'stored' | 'type'> & {
+    readonly computed: EntityAggregate<E>;
+    readonly stored?: false;
+}) | (Except<FieldOptions<never, E>, 'computed' | 'stored' | 'type'> & {
+    readonly computed: {
+        agg(refs: ComputedRefs<E>): RelationAggregate<unknown, true>;
+    }['agg'];
+    readonly stored: true;
+});
 /**
  * A key the type level cannot name, reported on each `@Id` that leaves it unnamed. Where no `idKey`
  * brand and no conventional name applies, `IdKey` falls back to every field, and `IdValue`,

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.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldMeta, FieldOptions, FilterName, FilterOptions, HookEvent, IdKey, RelationKey, RelationMeta, RelationOptions, RelationRegistration, Type, WrittenId } from '../../type/index.js';
+import type { EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldMeta, FieldOptions, FilterName, FilterOptions, HookEvent, IdKey, RelationKey, RelationMeta, RelationOptions, RelationRegistration, Type, WrittenId } from '../../type/index.js';
 export declare function defineField<E>(entity: Type<E>, key: string, opts?: FieldOptions): EntityMeta<E>;
 export declare function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E>;
 /** `T` is the relation's target, independent of the owner `E`. */
@@ -39,10 +39,14 @@ export declare function soleIdOf<E>(meta: EntityMeta<E>, what: string): IdKey<E>
 export declare function fieldOf<E>(meta: EntityMeta<E>, key: string): FieldMeta;
 /** The relation `key` names, for a caller that took `key` from the metadata itself. */
 export declare function relationOf<E>(meta: EntityMeta<E>, key: RelationKey<E>): RelationMeta;
+/** A row of `E` as far as reading its key goes: a record or a write, whatever its values. */
+type KeyedRow<E> = {
+    readonly [K in keyof E]?: unknown;
+};
 /** Whether the row names every column of its primary key, `0` and `''` included. */
-export declare function namesKey<E>(meta: EntityMeta<E>, row: EntityData<E>): boolean;
+export declare function namesKey<E>(meta: EntityMeta<E>, row: KeyedRow<E>): boolean;
 /** A row's primary key: its value, or a map of every column on a composite, checked at run time. */
-export declare function idOf<E>(meta: EntityMeta<E>, row: EntityData<E>): WrittenId<E>;
+export declare function idOf<E>(meta: EntityMeta<E>, row: KeyedRow<E>): WrittenId<E>;
 /**
  * Forgets an entity, and reports whether there was one - for a registry that grows at runtime, where a
  * deleted content type would otherwise keep its metadata for the life of the process. Nothing rewrites
@@ -58,3 +62,4 @@ export declare function getMeta<E>(entity: Type<E>): EntityMeta<E>;
  * schema build constrains and a junction joins by, settling the relations holding them first.
  */
 export declare function foreignKeysOf<E>(meta: EntityMeta<E>): RelationMeta[];
+export {};