uql-orm 0.68.1 → 0.69.0

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.1",
+  "version": "0.69.0",
   "type": "module",
   "engines": {
     "node": ">=24"