uql-orm 0.69.0 → 0.70.0

package/dist/type/universalQuerier.d.ts

@@ -1,4 +1,4 @@
-import type { EntityData, EntityId, FieldKey, RelationKey, UpdatePayload, WrittenId } from './entity.js';
+import type { EntityId, EntityWrite, FieldKey, RelationKey, UpdateWrite, WrittenId } from './entity.js';
 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';
@@ -31,9 +31,9 @@ export interface SharedQuerier<W extends QuerierTransport, O, DO = O> {
     /** 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, 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, QuerierRaw<W>>, opts?: O): QuerierResult<W, number>;
+    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<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, QuerierRaw<W>>, payload: UpdatePayload<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, number>;
+    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E, QuerierRaw<W>>, payload: UpdateWrite<E, QuerierRaw<W>>, opts?: O): QuerierResult<W, number>;
     /**
      * delete or SoftDelete a record.
      * @param entity the entity to persist on
@@ -59,31 +59,31 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      */
     findManyStream<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?: QueryOptions): AsyncIterable<QueryFindResult<E, S, V, X, P, C>>;
     /** Insert a record and resolve to its id. See {@link UniversalQuerier.insertMany}. */
-    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
     /**
      * Insert records in as few statements as the bind limit allows, resolving to their ids in payload order.
      * Ids are exact everywhere but MySQL, which infers them from its header and reports `undefined` rather
      * than a guess where it cannot: a batch naming some keys, or a key that is not `AUTO_INCREMENT`.
      */
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     /** Insert or update a record by its conflict paths; resolves to its id and whether it was created. */
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>): Promise<QueryUpsertOneResult<E>>;
     /** Insert or update records by their conflict paths; resolves to their ids in payload order. */
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>[]): Promise<QueryUpsertManyResult<E>>;
     /**
      * insert or update a record.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the ID
      */
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
     /**
      * Insert or update records.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the IDs
      */
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     /**
      * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
      * entity has no soft-delete field.

package/dist/util/dialect.util.d.ts

@@ -104,9 +104,11 @@ export declare function applyFilters<E>(meta: EntityMeta<E>, whereMap: QueryWher
 /**
  * Parsed entry from a `$group` map - either a raw group key or an aggregate function call.
  */
-export type ParsedGroupEntry = {
+export type ParsedGroupEntry<E = object> = {
     readonly kind: 'key';
     readonly alias: string;
+    /** The field it reads, behind the to-one relations leading to it: `['transaction', 'orderId']`. */
+    readonly path: readonly string[];
 } | {
     readonly kind: 'fn';
     readonly alias: string;
@@ -114,6 +116,8 @@ export type ParsedGroupEntry = {
     readonly fieldRef: string;
     /** `true` for a flat distinct op (`$countDistinct`, ...) -> `COUNT(DISTINCT field)`. */
     readonly distinct: boolean;
+    /** The rows it reads, where not all of the statement's. */
+    readonly where?: QueryWhere<E>;
 };
 /**
  * The `$size` of a relation condition, `{ comments: { $size: { $gte: 2 } } }`, or `undefined` where it
@@ -130,7 +134,7 @@ export declare function parseSortByCount(val: unknown): unknown;
  * Parse the `$group` (grouped columns) and `$select` (computed aggregates) maps into structured
  * entries consumable by any dialect. Grouped columns come first, then computed columns.
  */
-export declare function parseGroupMap<E>(group?: QueryGroupMap<E>, select?: QueryAggMap<E>): ParsedGroupEntry[];
+export declare function parseGroupMap<E>(group?: QueryGroupMap<E>, select?: QueryAggMap<E>): ParsedGroupEntry<E>[];
 /**
  * Whether `value` is a map of comparison operators rather than a value to compare against. Only a
  * plain object qualifies: `Date`, `QueryRaw`, `Uint8Array` and arrays are all `typeof 'object'`, and

package/dist/util/dialect.util.js

@@ -344,22 +344,36 @@ export function parseGroupMap(group, select) {
     const entries = [];
     const groupMap = group ?? {};
     for (const alias of getKeys(groupMap)) {
-        if (groupMap[alias]) {
-            entries.push({ kind: 'key', alias });
+        const ref = groupMap[alias];
+        if (ref) {
+            entries.push({ kind: 'key', alias, path: ref === true ? [alias] : groupRefPath(alias, ref) });
         }
     }
     if (!select) {
         return entries;
     }
     for (const alias of getKeys(select)) {
-        const fnEntry = select[alias];
-        const key = getKeys(fnEntry)[0];
+        const { $where: where } = select[alias];
+        const call = select[alias];
+        const key = getKeys(call).find((name) => name !== '$where');
+        if (key === undefined) {
+            throw new TypeError(`aggregate '${alias}' names no op, only a $where`);
+        }
         // Flat DISTINCT ops (`$countDistinct`, ...) normalize to their base op + a `distinct` flag.
         const { op, distinct } = resolveAggregateOp(key);
-        entries.push({ kind: 'fn', alias, op, fieldRef: aggregateFieldRef(alias, fnEntry[key]), distinct });
+        const fieldRef = aggregateFieldRef(alias, call[key]);
+        entries.push({ kind: 'fn', alias, op, fieldRef, distinct, ...(where && hasKeys(where) ? { where } : {}) });
     }
     return entries;
 }
+/** The path a group key's `{ transaction: { orderId: true } }` names, one key at each level. */
+function groupRefPath(alias, ref) {
+    const [key, ...rest] = isRecord(ref) ? getKeys(ref) : [];
+    if (!isRecord(ref) || key === undefined || rest.length) {
+        throw new TypeError(`$group '${alias}' names one field by the path to it: got ${JSON.stringify(ref)}`);
+    }
+    return ref[key] === true ? [key] : [key, ...groupRefPath(alias, ref[key])];
+}
 /** The column an aggregate reads: `'*'`, or the one field its `{ field: true }` names. */
 function aggregateFieldRef(alias, arg) {
     const [field, ...rest] = arg === '*' ? [arg] : namedKeys(arg);

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