uql-orm 0.68.0 → 0.69.0

package/dist/type/queryRaw.js

@@ -30,3 +30,21 @@ export class ColumnRef extends QueryRaw {
         this.key = key;
     }
 }
+/**
+ * A relation aggregate as SQL, read off a `computed` field's refs: `(user) => user.resources.count()`.
+ * It renders as the correlated subquery a `$count` reads, so a field holding one is read, filtered and
+ * sorted like any other.
+ *
+ * `V` is the value it reads and `Storable` whether a trigger could keep it, both carried in phantom
+ * fields so the aggregate a field declares decides the property's type and refuses `stored: true` on
+ * one no delta can maintain.
+ */
+export class RelationAggregate extends QueryRaw {
+    spec;
+    constructor(
+    /** What it reads, kept beside the SQL so a read decodes the value the way the target's field does. */
+    spec, value) {
+        super(value);
+        this.spec = spec;
+    }
+}

package/dist/type/queryWhere.d.ts

@@ -26,10 +26,10 @@ export type QueryTextSearchOptions<E> = {
  * entity's keys so each stays linked for rename. An object and nothing else, so a wrong value is
  * reported on its key: ids go through `{ id: 1 }` or the by-id methods.
  */
-export type QueryWhere<E, K extends keyof E = FieldKey<E> | RelationKey<E>> = QueryWhereRootOperator<E> & {
-    [P in K]?: P extends FieldKey<E> ? QueryWhereFieldValue<E[P]> : QueryWhere<RelationTarget<E[P]>> | QueryRelationSizeFilter;
+export type QueryWhere<E, Raw = QueryRaw, K extends keyof E = FieldKey<E> | RelationKey<E>> = QueryWhereRootOperator<E, Raw> & {
+    [P in K]?: P extends FieldKey<E> ? QueryWhereFieldValue<E[P], Raw> : QueryWhere<RelationTarget<E[P]>, Raw> | QueryRelationSizeFilter;
 } & ([JsonFieldPaths<E>] extends [never] ? unknown : {
-    [P in JsonFieldPaths<E>]?: QueryWhereFieldValue<JsonFieldPathValue<E, P>>;
+    [P in JsonFieldPaths<E>]?: QueryWhereFieldValue<JsonFieldPathValue<E, P>, Raw>;
 });
 /**
  * Filter a to-many relation by its row count.
@@ -39,24 +39,24 @@ export type QueryWhere<E, K extends keyof E = FieldKey<E> | RelationKey<E>> = Qu
 export type QueryRelationSizeFilter = {
     readonly $size: number | QuerySizeComparisonOps;
 };
-export type QueryWhereRootOperator<E> = {
+export type QueryWhereRootOperator<E, Raw = QueryRaw> = {
     /**
      * joins query clauses with a logical `AND`, returns records that match all the clauses.
      */
-    $and?: QueryWhereArray<E>;
+    $and?: QueryWhereArray<E, Raw>;
     /**
      * joins query clauses with a logical `OR`, returns records that match any of the clauses.
      */
-    $or?: QueryWhereArray<E>;
+    $or?: QueryWhereArray<E, Raw>;
     /**
      * joins query clauses with a logical `AND`, returns records that do not match all the clauses.
      * @see {@link QueryWhereFieldOperatorMap.$not} for per-field negation.
      */
-    $not?: QueryWhereArray<E>;
+    $not?: QueryWhereArray<E, Raw>;
     /**
      * joins query clauses with a logical `OR`, returns records that do not match any of the clauses.
      */
-    $nor?: QueryWhereArray<E>;
+    $nor?: QueryWhereArray<E, Raw>;
     /**
      * whether the specified fields match against a full-text search of the given string.
      */
@@ -64,11 +64,11 @@ export type QueryWhereRootOperator<E> = {
     /**
      * whether the record exists in the given sub-query.
      */
-    $exists?: QueryRaw;
+    $exists?: Raw;
     /**
      * whether the record does not exists in the given sub-query.
      */
-    $nexists?: QueryRaw;
+    $nexists?: Raw;
 };
 /**
  * Per-field negation operators. `Pick`'s constraint ties this back to
@@ -100,7 +100,7 @@ export type QuerySizeComparisonOps = {
 export type QueryVectorNear = QueryVectorQuery & {
     [K in QueryOrderedOp]?: NonNullable<QueryWhereFieldOperatorMap<number>[K]>;
 };
-export type QueryWhereFieldOperatorMap<T> = {
+export type QueryWhereFieldOperatorMap<T, Raw = QueryRaw> = {
     /**
      * whether a value is equal to the given value.
      */
@@ -113,7 +113,7 @@ export type QueryWhereFieldOperatorMap<T> = {
      * negates the given comparison for a single field.
      * @see {@link QueryWhereRootOperator.$not} for root-level clause negation.
      */
-    $not?: QueryWhereFieldValue<T>;
+    $not?: QueryWhereFieldValue<T, Raw>;
     /**
      * whether a value is less than the given value.
      */
@@ -202,7 +202,7 @@ export type QueryWhereFieldOperatorMap<T> = {
      * @example { addresses: { $elemMatch: { city: 'NYC', zip: '10001' } } }
      * @example { addresses: { $elemMatch: { city: { $like: 'New%' } } } }
      */
-    $elemMatch?: unknown extends T ? QueryWhereElemMatch<unknown> : NonNullable<T> extends readonly (infer U)[] ? QueryWhereElemMatch<U> : never;
+    $elemMatch?: unknown extends T ? QueryWhereElemMatch<unknown, Raw> : NonNullable<T> extends readonly (infer U)[] ? QueryWhereElemMatch<U, Raw> : never;
     /**
      * whether a vector is within a given distance of the query vector. `$sort` ranks by distance;
      * this filters by it, so "the closest ten" and "everything closer than 0.35" are separate asks.
@@ -216,10 +216,10 @@ export type QueryWhereFieldOperatorMap<T> = {
  * field comparison. An untyped element (`unknown`) accepts any keys but still requires the
  * object-of-conditions shape (a bare scalar is rejected).
  */
-export type QueryWhereElemMatch<U> = unknown extends U ? {
-    [key: string]: QueryWhereFieldValue<unknown> | undefined;
-} : NonNullable<U> extends Scalar ? QueryWhereFieldOperators<NonNullable<U>> : {
-    [K in keyof NonNullable<U>]?: QueryWhereFieldValue<NonNullable<U>[K]>;
+export type QueryWhereElemMatch<U, Raw = QueryRaw> = unknown extends U ? {
+    [key: string]: QueryWhereFieldValue<unknown, Raw> | undefined;
+} : NonNullable<U> extends Scalar ? QueryWhereFieldOperators<NonNullable<U>, Raw> : {
+    [K in keyof NonNullable<U>]?: QueryWhereFieldValue<NonNullable<U>[K], Raw>;
 };
 /**
  * Simple relational comparison operators. `Pick`'s constraint ties this back to
@@ -269,7 +269,7 @@ type QueryAllowedOp<T> = QueryCommonOp | ([NonNullable<T>] extends [QueryCompara
  * The operators a field of type `T` takes. `unknown`, and a column typed as every scalar at once (a
  * runtime-defined entity), take all of them, since nothing narrows what they hold.
  */
-export type QueryWhereFieldOperators<T> = unknown extends T ? QueryWhereFieldOperatorMap<T> : IsUntypedColumn<T> extends true ? QueryWhereFieldOperatorMap<T> : Pick<QueryWhereFieldOperatorMap<T>, QueryAllowedOp<T>>;
+export type QueryWhereFieldOperators<T, Raw = QueryRaw> = unknown extends T ? QueryWhereFieldOperatorMap<T, Raw> : IsUntypedColumn<T> extends true ? QueryWhereFieldOperatorMap<T, Raw> : Pick<QueryWhereFieldOperatorMap<T, Raw>, QueryAllowedOp<T>>;
 /**
  * Whether a column admits every scalar at once, which is what an entity keyed by an index signature
  * says about all of its columns. `Scalar` is the yardstick rather than a parameter: the question is
@@ -280,9 +280,9 @@ type IsUntypedColumn<T> = [Scalar] extends [NonNullable<T>] ? true : false;
  * A field's filter value: the value, `null` where it is optional, a list as an implicit `$in` (not on
  * an array field, where it would be ambiguous), or an operator map.
  */
-export type QueryWhereFieldValue<T> = T | (undefined extends T ? null : never) | (IsMany<T> extends true ? never : T[]) | QueryWhereFieldOperators<T> | QueryRaw;
+export type QueryWhereFieldValue<T, Raw = QueryRaw> = T | (undefined extends T ? null : never) | (IsMany<T> extends true ? never : T[]) | QueryWhereFieldOperators<T, Raw> | Raw;
 /**
  * query filter array - the value every {@link QueryGroupOp} takes.
  */
-export type QueryWhereArray<E> = (QueryWhere<E> | QueryRaw)[];
+export type QueryWhereArray<E, Raw = QueryRaw> = (QueryWhere<E, Raw> | Raw)[];
 export {};

package/dist/type/universalQuerier.d.ts

@@ -2,38 +2,38 @@ import type { EntityData, EntityId, FieldKey, RelationKey, UpdatePayload, Writte
 import type { QueryConflictPaths, QueryFilter, QueryFindResult, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpsertOneResult, QueryUpsertManyResult } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
-import type { QuerierCountedResult, QuerierResult, QuerierTransport } from './wire.js';
+import type { QuerierCountedResult, QuerierRaw, QuerierResult, QuerierTransport } from './wire.js';
 /**
  * The operations the server and the browser client declare alike, per transport `W`, options `O`,
  * and delete options `DO`, which on the client also carry the {@link QueryOptions} it cannot pass otherwise.
  */
 export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
     /** Find the record with the given primary key. */
-    findOneById<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, id: EntityId<E>, q?: QueryOneProjected<E, S, V, X, P, C>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C> | undefined>;
+    findOneById<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, id: EntityId<E>, q?: QueryOneProjected<E, S, V, X, P, C, QuerierRaw<W>>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C> | undefined>;
     /**
      * obtains the first record matching the given search parameters.
      * @param entity the target entity
      * @param q the criteria options
      * @return the record
      */
-    findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryOneProjected<E, S, V, X, P, C>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C> | undefined>;
+    findOne<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryOneProjected<E, S, V, X, P, C, QuerierRaw<W>>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C> | undefined>;
     /**
      * obtains the records matching the given search parameters.
      * @param entity the target entity
      * @param q the criteria options
      * @return the records
      */
-    findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C>[]>;
+    findMany<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C, QuerierRaw<W>>, opts?: O): QuerierResult<W, QueryFindResult<E, S, V, X, P, C>[]>;
     /** Find the records matching the query, and count every match past its page. */
-    findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C>, opts?: O): QuerierCountedResult<W, QueryFindResult<E, S, V, X, P, C>>;
+    findManyAndCount<E extends object, const S extends FieldKey<E> = never, const V = true, const X extends FieldKey<E> = never, const P extends RelationKey<E> = never, const C extends RelationKey<E> = never>(entity: Type<E>, q: QueryProjected<E, S, V, X, P, C, QuerierRaw<W>>, opts?: O): QuerierCountedResult<W, QueryFindResult<E, S, V, X, P, C>>;
     /** Count the records matching the filter, or those a page of them takes. */
-    count<E extends object>(entity: Type<E>, q?: QueryPage<E>, opts?: O): QuerierResult<W, number>;
+    count<E extends object>(entity: Type<E>, q?: QueryPage<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, number>;
     /** Whether any record matches: a count capped at one row, so the engine stops at the first match. */
-    exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: O): QuerierResult<W, boolean>;
+    exists<E extends object>(entity: Type<E>, q?: QueryFilter<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, boolean>;
     /** Update the record with the given primary key; resolves to the number of affected rows. */
-    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: O): QuerierResult<W, number>;
+    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, number>;
     /** Update the records matching the query; resolves to the number of affected rows. */
-    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: O): QuerierResult<W, number>;
+    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E, QuerierRaw<W>>, payload: UpdatePayload<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, number>;
     /**
      * delete or SoftDelete a record.
      * @param entity the entity to persist on
@@ -47,7 +47,7 @@ export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
      * @param q the criteria to look for the records
      * @return the number of affected records
      */
-    deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: DO): QuerierResult<W, number>;
+    deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E, QuerierRaw<W>>, opts?: DO): QuerierResult<W, number>;
 }
 /**
  * A `querier` allows to interact with the datasource to perform persistence operations on any entity.

package/dist/type/wire.d.ts

@@ -1,3 +1,4 @@
+import type { QueryRaw } from './queryRaw.js';
 /**
  * The envelope a wire response wraps its result in.
  */
@@ -16,6 +17,14 @@ export type RequestCountedSuccessResponse<E> = RequestSuccessResponse<E> & {
  * client one hands back the envelope its transport wrapped it in.
  */
 export type QuerierTransport = 'server' | 'client';
+/**
+ * The `raw` SQL a transport carries. A client's query and payload travel as JSON, which a `raw` fragment
+ * is not: it would arrive as `{}`, so the client's types refuse one rather than let it leave.
+ */
+export type QuerierRaw<W extends QuerierTransport> = {
+    server: QueryRaw;
+    client: never;
+}[W];
 /**
  * A querier method's result on a transport: `Promise<User[]>` on the server, the response envelope on
  * the client. A map indexed by the transport, which resolves away in hovers.

package/dist/util/dialect.util.js

@@ -2,8 +2,8 @@ import { getContext, UqlSecurityError } from '../context/context.js';
 import { soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
 import { VECTOR_INDEX_TYPES } from '../type/vector.js';
-import { isDatabaseWritten } from './field.util.js';
-import { entityName, getFieldKeys, getKeys, hasKeys, isOperatorObject, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
+import { getFieldKeys, isDatabaseWritten } from './field.util.js';
+import { entityName, getKeys, hasKeys, isOperatorObject, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
 /** The keys of `payload` a write persists as columns. */
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {

package/dist/util/field.util.d.ts

@@ -1,4 +1,4 @@
-import { type ColumnFamily, type EntityMeta, type FieldOptions } from '../type/index.js';
+import { type ColumnFamily, type EntityMeta, type FieldKey, type FieldOptions, type RelationAggregateSpec } from '../type/index.js';
 /** The family of a logical field type, or `undefined` where it names none. */
 export declare function columnFamily(type: unknown): ColumnFamily | undefined;
 /**
@@ -12,6 +12,12 @@ export declare function isIntegerColumn(field: Pick<FieldOptions, 'type' | 'colu
  * because an inlined field has no column to name, while a stored one is read like any other.
  */
 export declare function isInlinedExpression<F extends FieldOptions>(field: F): field is F & Required<Pick<F, 'computed'>>;
+/**
+ * The relation aggregate a field computes, where it computes one rather than writing SQL: what it
+ * reads, off which relation, narrowed and capped how. Every engine renders it from this - a correlated
+ * subquery on SQL, a lookup on MongoDB - so both read the same declaration rather than parsing SQL.
+ */
+export declare function aggregateOf(field: FieldOptions | undefined): RelationAggregateSpec | undefined;
 /**
  * Whether the database supplies this field's value, so no insert or update may write it: a stored
  * computed column *is* a real column, read like one, but writing to it is an error on every engine.
@@ -25,3 +31,11 @@ export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOption
  * states its width. The one answer the create statement and the diff both read.
  */
 export declare function isAutoIncrement(field: FieldOptions, isPrimaryKey: boolean): boolean;
+/**
+ * The fields a read answers with where it names none. A relation aggregate is left out unless it asks
+ * for `eager: true`: it reads the related rows, which is what a relation does, and a relation is loaded
+ * only when a query asks for it. Naming one in `$select` reads it, whatever the default.
+ */
+export declare function getFieldKeys<E>(fields: {
+    [K in FieldKey<E>]?: FieldOptions;
+}): FieldKey<E>[];

package/dist/util/field.util.js

@@ -1,4 +1,4 @@
-import { COLUMN_TYPES, } from '../type/index.js';
+import { COLUMN_TYPES, RelationAggregate, } from '../type/index.js';
 import { getKeys } from './object.util.js';
 // Constructors and type strings in one map: a logical type is either, and every caller asks the same
 // question of both.
@@ -41,6 +41,15 @@ export function isIntegerColumn(field) {
 export function isInlinedExpression(field) {
     return field.computed !== undefined && field.stored !== true;
 }
+/**
+ * The relation aggregate a field computes, where it computes one rather than writing SQL: what it
+ * reads, off which relation, narrowed and capped how. Every engine renders it from this - a correlated
+ * subquery on SQL, a lookup on MongoDB - so both read the same declaration rather than parsing SQL.
+ */
+export function aggregateOf(field) {
+    const computed = field?.computed;
+    return computed instanceof RelationAggregate ? computed.spec : undefined;
+}
 /**
  * Whether the database supplies this field's value, so no insert or update may write it: a stored
  * computed column *is* a real column, read like one, but writing to it is an error on every engine.
@@ -62,3 +71,11 @@ export function isAutoIncrement(field, isPrimaryKey) {
         return field.autoIncrement;
     return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert && !field.references;
 }
+/**
+ * The fields a read answers with where it names none. A relation aggregate is left out unless it asks
+ * for `eager: true`: it reads the related rows, which is what a relation does, and a relation is loaded
+ * only when a query asks for it. Naming one in `$select` reads it, whatever the default.
+ */
+export function getFieldKeys(fields) {
+    return getKeys(fields).filter((field) => fields[field].eager ?? !aggregateOf(fields[field]));
+}

package/dist/util/object.util.d.ts

@@ -1,4 +1,4 @@
-import type { EntityMeta, FieldKey, FieldOptions } from '../type/index.js';
+import type { EntityMeta } from '../type/index.js';
 export declare function throwPendingTransaction(): never;
 export declare function throwNoPendingTransaction(): never;
 export declare function clone<T>(value: T): T;
@@ -24,9 +24,6 @@ export declare function definedEntries<K extends string, V>(record: Partial<Reco
  * out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
  */
 export declare function entityName<E>(meta: EntityMeta<E>): string;
-export declare function getFieldKeys<E>(fields: {
-    [K in FieldKey<E>]?: FieldOptions;
-}): FieldKey<E>[];
 /**
  * Whether `value` addresses a row by itself rather than naming columns: every primitive, and the
  * object ids a driver deals in (`ObjectId`, `Date`, bytes). Only a plain object names columns, which

package/dist/util/object.util.js

@@ -59,9 +59,6 @@ export function definedEntries(record) {
 export function entityName(meta) {
     return meta.name ?? meta.entity.name;
 }
-export function getFieldKeys(fields) {
-    return getKeys(fields).filter((field) => fields[field].eager ?? true);
-}
 /**
  * Whether `value` addresses a row by itself rather than naming columns: every primitive, and the
  * object ids a driver deals in (`ObjectId`, `Date`, bytes). Only a plain object names columns, which

package/dist/util/raw.d.ts

@@ -1,4 +1,4 @@
-import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type RefMap, type Type } from '../type/index.js';
+import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type ComputedRefs, type RefMap, type Type } from '../type/index.js';
 /**
  * Raw SQL, where an interpolated value binds, a `refs` field renders its column, and a `raw` renders
  * in place: `raw`GREATEST(0, ${user.credits} - ${amount})``. A callback writes whatever it writes, so
@@ -16,7 +16,7 @@ export declare function refs<E>(entity: Type<E>): RefMap<E>;
  * The refs a definition's callbacks read: an index's, a check's, a computed field's. A member decorator
  * sees no class, so these name no entity and resolve against the one rendering them.
  */
-export declare function memberRefs<E>(): RefMap<E>;
+export declare function memberRefs<E>(): ComputedRefs<E>;
 /** SQL a definition writes, a callback's refs read off {@link memberRefs}. */
 export declare function entitySql<E>(sql: EntitySql<E>): QueryRaw;
 /** A definition's predicate, its callback resolved the way {@link entitySql} resolves one. */

package/dist/util/raw.js

@@ -1,5 +1,5 @@
 import { getMeta } from '../entity/metadata/definition.js';
-import { ColumnRef, QueryRaw, } from '../type/index.js';
+import { ColumnRef, QueryRaw, RelationAggregate, } from '../type/index.js';
 import { isInlinedExpression } from './field.util.js';
 export function raw(value, ...rest) {
     if (!isTemplateStrings(value)) {
@@ -27,7 +27,7 @@ export function raw(value, ...rest) {
 export function refs(entity) {
     return new Proxy({}, { get: (_, key) => columnRef(entity, String(key)) });
 }
-const MEMBER_REFS = new Proxy({}, { get: (_, key) => columnRef(undefined, String(key)) });
+const MEMBER_REFS = new Proxy({}, { get: (_, key) => memberRef(String(key)) });
 /**
  * The refs a definition's callbacks read: an index's, a check's, a computed field's. A member decorator
  * sees no class, so these name no entity and resolve against the one rendering them.
@@ -43,6 +43,33 @@ export function entitySql(sql) {
 export function entityWhere(where) {
     return typeof where === 'function' ? where(memberRefs()) : where;
 }
+/**
+ * One member as a definition reads it: a {@link ColumnRef} where it names a field, and the same object
+ * answering `count`, `sum`, `min`, `max` and `avg` where it names a to-many. One runtime object, since
+ * a member decorator sees no class and so cannot know which the key is; the types keep them apart.
+ */
+function memberRef(relation) {
+    const over = (op) => (pick, q) => relationAggregate({ relation, op, field: pick(memberRefs()).key, ...(q && { query: q }) });
+    return Object.assign(columnRef(undefined, relation), {
+        count: (q) => relationAggregate({ relation, op: '$count', ...(q && { query: q }) }),
+        sum: over('$sum'),
+        min: over('$min'),
+        max: over('$max'),
+        avg: over('$avg'),
+    });
+}
+/**
+ * A relation aggregate as SQL: the dialect writes the same correlated subquery a `$count` reads,
+ * correlated to whichever alias the clause naming the field is rendering under.
+ */
+function relationAggregate(spec) {
+    return new RelationAggregate(spec, (opts) => {
+        if (!opts.entity) {
+            throw new TypeError(`'${spec.relation}' was read off a definition's refs, so it renders only inside its entity's SQL`);
+        }
+        opts.dialect.appendRelationAggregate(opts.ctx, opts.entity, spec, opts.prefix);
+    });
+}
 /** One field as SQL, against its own entity or, read off a definition, the entity rendering it. */
 function columnRef(entity, key) {
     return new ColumnRef(key, (opts) => {

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -161,7 +161,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rogerpadilla/uql.git",
-    "directory": "packages/uql-orm"
+    "directory": "packages/orm"
   },
   "bugs": {
     "url": "https://github.com/rogerpadilla/uql/issues"