uql-orm 0.69.0 → 0.70.0

package/dist/dialect/abstractSqlDialect.js

@@ -3,10 +3,10 @@ import { COUNT_RESULT_KEY, parseQueryLock, QueryRaw, RAW_ALIAS, VECTOR_QUERY_KEY
 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, aggregateOf, raw, refs, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral } from '../util/sqlLiteral.js';
-import { AGGREGATE_PAGE_ALIAS, AGGREGATE_VALUE_ALIAS, 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. */
@@ -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.aggregateHydrateKind(meta, field) ?? this.hydrateKind(field);
+            const kind = this.fieldKind(meta, field);
             if (kind) {
                 decoded.push([key, kind]);
             }
@@ -1306,13 +1339,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /** 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)) {
-            // A grouped column is the field itself; an aggregate reads the one it aggregates, `'*'` for a tally.
-            const key = entry.kind === 'fn' ? entry.fieldRef : entry.alias;
-            const field = fields[key];
-            const kind = entry.kind === 'fn' ? this.aggregateKind(entry.op, field) : this.hydrateKind(field);
+            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]);
             }
@@ -1327,17 +1360,22 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      *
      * One rule for both readers: a relation aggregate a field declares, and an aggregate a query names.
      */
-    aggregateKind(op, field) {
-        return op === '$count' || op === '$avg' ? 'number' : this.hydrateKind(field);
+    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 relation aggregate a field declares decodes as: {@link aggregateKind} over the target's column. */
-    aggregateHydrateKind(meta, field) {
+    /** 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 undefined;
+            return this.hydrateKind(field);
         }
         const target = getMeta(relationOf(meta, spec.relation).entity());
-        return this.aggregateKind(spec.op, spec.field ? target.fields[spec.field] : undefined);
+        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) {
@@ -1395,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)) {
@@ -1584,7 +1620,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const meta = getMeta(entity);
         const rel = relationOf(meta, aggregate.relation);
         const parent = prefix || this.resolveTableAlias(meta);
-        if (!aggregate.query?.$limit && aggregate.query?.$skip === undefined) {
+        const { $limit, $skip } = aggregate.query ?? {};
+        if ($limit === undefined && $skip === undefined) {
             this.appendRelationSubquery(ctx, meta, aggregate.relation, rel, { prefix: parent }, aggregate);
             return;
         }
@@ -1616,14 +1653,15 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const joins = resolveQueryJoins(getMeta(entity), query, (path) => ctx.claimAlias(path));
         this.read(ctx, entity, query, { alias }, joins);
     }
-    /** One aggregate over an operand, `COALESCE`d where the aggregate answers `0` on no rows rather than null. */
+    /** A relation aggregate over an operand, reading `0` on a parent with no rows where its type says so. */
     aggregateCall(op, operand) {
-        if (op === '$count') {
-            return 'COUNT(*)';
-        }
-        const call = `${AbstractSqlDialect.AGGREGATE_FN[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

package/dist/dialect/aliases.d.ts

@@ -1,17 +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";
 /**
- * What an aggregate answers under: the column a capped page carries out for the aggregate wrapping it,
- * and the field a MongoDB `$group` or `$count` leaves its value in. One name, since both ends of each
- * are written and read here.
+ * 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,19 +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';
 /**
- * What an aggregate answers under: the column a capped page carries out for the aggregate wrapping it,
- * and the field a MongoDB `$group` or `$count` leaves its value in. One name, since both ends of each
- * are written and read here.
+ * 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 { AggregateValue, ComputedRefs, EntityAggregate, EntityGetter, Except, FieldOptions, FieldType, HasCompositeKey, IdValue, NamedIdKey, RejectKeys, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, RelationAggregate, 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,14 +51,14 @@ 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): AggregateDecorator<AggregateValue<O>, This>;
+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.
@@ -50,14 +72,6 @@ type AggregateOptions<E> = (Except<FieldOptions<never, E>, 'computed' | 'stored'
     }['agg'];
     readonly stored: true;
 });
-/**
- * {@link MemberDecorator} for a field an aggregate types, which the property has to hold *exactly*: a
- * decorator context takes a property narrower than its value, so nothing else would stop a `number`
- * from holding what `max()` reads, which is `number | null` on a parent with no rows.
- */
-type AggregateDecorator<V, O> = <P extends V | undefined>(value: undefined, context: ClassFieldDecoratorContext<O, P> & ([V] extends [P] ? unknown : {
-    readonly __propertyMustAdmit: V;
-})) => void;
 /**
  * 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/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 {};

package/dist/migrate/codegen/entityCodeGenerator.js

@@ -156,9 +156,11 @@ export class EntityCodeGenerator {
             const fieldOptions = this.buildFieldOptions(col, propertyName);
             lines.push(`  @Field(${fieldOptions})`);
         }
-        // Property
+        // Property. A generated column is the database's to write, so it is `readonly`: a write payload
+        // leaves those out, and one naming it would be dropped rather than persisted.
         const nullable = col.nullable ? '?' : '';
-        lines.push(`  ${propertyName}${nullable}: ${tsType};`);
+        const written = col.generatedAs === undefined ? '' : 'readonly ';
+        lines.push(`  ${written}${propertyName}${nullable}: ${tsType};`);
         return lines.join('\n');
     }
     /**

package/dist/migrate/migrator.d.ts

@@ -49,7 +49,8 @@ export declare class Migrator {
     /** Runs the list narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over the executed reversed. */
     private runInOrder;
     /**
-     * Run a single migration, within a transaction where the dialect has one for it
+     * Run a single migration, in a transaction where the dialect has one for it and the migration has not
+     * declared `transaction: false` - the opt-out a statement an engine refuses inside one needs.
      */
     runMigration(migration: Migration<Querier>, direction: 'up' | 'down'): Promise<MigrationResult>;
     /**

package/dist/migrate/migrator.js

@@ -112,14 +112,15 @@ export class Migrator {
         return results;
     }
     /**
-     * Run a single migration, within a transaction where the dialect has one for it
+     * Run a single migration, in a transaction where the dialect has one for it and the migration has not
+     * declared `transaction: false` - the opt-out a statement an engine refuses inside one needs.
      */
     async runMigration(migration, direction) {
         const startTime = Date.now();
         return this.target.withSession(async ({ querier, transaction }) => {
             try {
                 this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
-                await transaction(async () => {
+                const work = async () => {
                     if (direction === 'up') {
                         await migration.up(querier);
                         await this.storage.logWithQuerier(querier, migration.name);
@@ -128,7 +129,8 @@ export class Migrator {
                         await migration.down(querier);
                         await this.storage.unlogWithQuerier(querier, migration.name);
                     }
-                });
+                };
+                await (migration.transaction === false ? work() : transaction(work));
                 const duration = Date.now() - startTime;
                 this.logger.logMigration(`Migration ${migration.name} ${direction === 'up' ? 'applied' : 'reverted'} in ${duration}ms`);
                 return {