uql-orm 0.68.0 → 0.69.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,9 +1,9 @@
 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, COUNT_ALIAS, COUNTED_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';
@@ -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,
                     });
@@ -1296,7 +1296,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.aggregateHydrateKind(meta, field) ?? this.hydrateKind(field);
             if (kind) {
                 decoded.push([key, kind]);
             }
@@ -1304,28 +1304,41 @@ 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 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.
+            // 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 kind = this.hydrateKind(fields[key]);
+            const field = fields[key];
+            const kind = entry.kind === 'fn' ? this.aggregateKind(entry.op, field) : this.hydrateKind(field);
             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, field) {
+        return op === '$count' || op === '$avg' ? 'number' : this.hydrateKind(field);
+    }
+    /** What a relation aggregate a field declares decodes as: {@link aggregateKind} over the target's column. */
+    aggregateHydrateKind(meta, field) {
+        const spec = aggregateOf(field);
+        if (!spec) {
+            return undefined;
+        }
+        const target = getMeta(relationOf(meta, spec.relation).entity());
+        return this.aggregateKind(spec.op, spec.field ? 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;
@@ -1519,14 +1532,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 +1556,74 @@ 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);
+        if (!aggregate.query?.$limit && aggregate.query?.$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);
+    }
+    /** One aggregate over an operand, `COALESCE`d where the aggregate answers `0` on no rows rather than null. */
+    aggregateCall(op, operand) {
+        if (op === '$count') {
+            return 'COUNT(*)';
+        }
+        const call = `${AbstractSqlDialect.AGGREGATE_FN[op]}(${operand})`;
+        return op === '$sum' ? `COALESCE(${call}, 0)` : call;
+    }
     /**
      * 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 +1649,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 +1748,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

@@ -4,6 +4,14 @@ export declare const COUNT_ALIAS = "_uql_count";
 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 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.
+ */
+export declare const AGGREGATE_VALUE_ALIAS = "_uql_value";
 /** 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

@@ -6,6 +6,14 @@ export const COUNT_ALIAS = '_uql_count';
 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 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.
+ */
+export const AGGREGATE_VALUE_ALIAS = '_uql_value';
 /** 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/entity/decorator/members.d.ts

@@ -1,4 +1,4 @@
-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 } 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;
@@ -30,6 +30,34 @@ export declare function Field<This, O extends FieldOptions<DeclaredValue<O>, Thi
 } | {
     references: EntityGetter;
 }) & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined, 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>;
+/**
+ * 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;
+});
+/**
+ * {@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/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/http/query.d.ts

@@ -1,11 +1,19 @@
-import type { Query } from '../type/index.js';
+import type { WireQuery } from '../type/index.js';
 /**
  * Parse raw query-string entries (with JSON-stringified values) into a UQL query object.
  * Symmetric counterpart of {@link stringifyQuery}. Only {@link ALLOWED_QUERY_KEYS} are honored.
  */
-export declare function parseQueryParams(params?: Record<string, unknown>): Query<unknown>;
+export declare function parseQueryParams(params?: Record<string, unknown>): WireQuery<unknown>;
 /**
  * Serialize a UQL query object into a percent-encoded query string where object values
  * are JSON-stringified. Symmetric counterpart of {@link parseQueryParams}.
  */
 export declare function stringifyQuery(query?: Record<string, unknown>): string;
+/**
+ * What leaves the browser, as JSON, refusing what JSON keeps nothing of rather than letting the server
+ * build a statement around the remains. A `raw` fragment renders SQL against a dialect the client does not
+ * have and arrives as `{}`; binary arrives as an object keyed by index. A `Date` is not among them - it
+ * serializes to ISO 8601, which is what a date column reads. This is what a cast, or a JavaScript caller,
+ * hits where the client's types already refuse a fragment.
+ */
+export declare function wireJson(value: unknown): string;

package/dist/http/query.js

@@ -1,5 +1,8 @@
 // the clause lists themselves, not the barrel: this module is in the browser bundle's graph
 import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUERY_ROOT_NUMBER_CLAUSES, QUERY_ROOT_OBJECT_CLAUSES, } from '../type/query.js';
+// the brand alone, not the class: importing `QueryRaw` for an `instanceof` kept it, and `ColumnRef`
+// with it, in the browser bundle, which is on a size budget
+import { RAW_VALUE } from '../type/queryRaw.js';
 // the specific util module, not the barrel, so the browser bundle does not pull in entity metadata
 import { getKeys, isWhereMap } from '../util/object.util.js';
 /**
@@ -82,8 +85,30 @@ export function stringifyQuery(query) {
         if (value === undefined) {
             continue;
         }
-        params.append(key, typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value));
+        params.append(key, typeof value === 'object' && value !== null ? wireJson(value) : String(value));
     }
     const qs = params.toString();
     return qs ? `?${qs}` : '';
 }
+/**
+ * What leaves the browser, as JSON, refusing what JSON keeps nothing of rather than letting the server
+ * build a statement around the remains. A `raw` fragment renders SQL against a dialect the client does not
+ * have and arrives as `{}`; binary arrives as an object keyed by index. A `Date` is not among them - it
+ * serializes to ISO 8601, which is what a date column reads. This is what a cast, or a JavaScript caller,
+ * hits where the client's types already refuse a fragment.
+ */
+export function wireJson(value) {
+    return JSON.stringify(value, (_key, held) => {
+        if (typeof held !== 'object' || held === null) {
+            return held;
+        }
+        if (RAW_VALUE in held) {
+            throw new TypeError('raw SQL cannot travel over HTTP: what leaves the browser is JSON');
+        }
+        // A blob is a field value, so no type parameter reaches it: this is the only place it is caught.
+        if (held instanceof ArrayBuffer || ArrayBuffer.isView(held)) {
+            throw new TypeError('binary cannot travel over HTTP: what leaves the browser is JSON');
+        }
+        return held;
+    });
+}

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