uql-orm 0.28.2 → 0.30.0

package/dist/querier/abstractSqlQuerier.js

@@ -3,6 +3,14 @@ import { getMeta } from '../entity/index.js';
 import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, getRelationRequestSummary, isAutoIncrement, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { enrichError } from './queryError.js';
+/**
+ * Whether `q` picks a specific slice of the matching rows rather than all of them. A write that
+ * does has to settle those rows and name them: `ORDER BY`/`LIMIT` on an UPDATE or DELETE is MySQL's
+ * alone.
+ */
+function isPaged(q) {
+    return q.$sort !== undefined || q.$limit !== undefined || q.$skip !== undefined;
+}
 export class AbstractSqlQuerier extends AbstractQuerier {
     dialect;
     extra;
@@ -35,10 +43,15 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         return Number.isInteger(value) && value > 0 ? value : 1;
     }
     /**
-     * Hook for subclasses (e.g. pool queriers) to establish a connection.
-     * Called before every query but outside the timing window.
+     * Hook for subclasses (e.g. pool queriers) to establish a connection. Called before every query and
+     * before `BEGIN`, outside the timing window, which makes it the one place a released querier is
+     * caught for every SQL backend.
      */
-    async lazyConnect() { }
+    async lazyConnect() {
+        if (this.released) {
+            throw new TypeError('querier already released');
+        }
+    }
     async all(query, values) {
         return this.serialize(async () => {
             await this.lazyConnect();
@@ -214,12 +227,30 @@ export class AbstractSqlQuerier extends AbstractQuerier {
     }
     async internalUpdateMany(entity, q, payload, opts) {
         payload = clone(payload);
+        // Settled first for the reason `internalDeleteMany` settles: `ORDER BY`/`LIMIT` on an UPDATE is
+        // MySQL's alone, so a paged update has to name the rows it picked.
+        let target = q;
+        if (isPaged(q)) {
+            const ids = await this.settleIds(entity, q, opts);
+            if (!ids.length) {
+                return 0;
+            }
+            target = { $where: ids };
+        }
         const ctx = this.dialect.createContext();
-        this.dialect.update(ctx, entity, q, payload, opts);
+        this.dialect.update(ctx, entity, target, payload, opts);
         const { changes = 0 } = await this.run(ctx.sql, ctx.values);
-        await this.updateRelations(entity, q, payload, opts);
+        await this.updateRelations(entity, target, payload, opts);
         return changes;
     }
+    /** The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on. */
+    async settleIds(entity, q, opts) {
+        const meta = getMeta(entity);
+        const ctx = this.dialect.createContext();
+        this.dialect.find(ctx, entity, { ...q, $select: { [meta.id]: true } }, opts);
+        const founds = await this.all(ctx.sql, ctx.values);
+        return founds.map((it) => it[meta.id]);
+    }
     async upsertOne(entity, conflictPaths, payload) {
         return this.upsertMany(entity, conflictPaths, [payload]);
     }
@@ -247,8 +278,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         // parents' ids to find their children, and no engine but MySQL accepts `ORDER BY`/`LIMIT` on a
         // DELETE, so a paged delete has to name the rows it settled on. A plain predicate needs neither,
         // and there the round trip buys nothing: the statement can say what the caller already said.
-        const hasPagination = q.$sort !== undefined || q.$limit !== undefined || q.$skip !== undefined;
-        if (!hasPagination && !cascadesOnDelete(meta)) {
+        if (!isPaged(q) && !cascadesOnDelete(meta)) {
             const ctx = this.dialect.createContext();
             this.dialect.delete(ctx, entity, q, opts);
             const { changes = 0 } = await this.run(ctx.sql, ctx.values);
@@ -256,13 +286,10 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
         // A hard delete also targets already-soft-deleted rows, so drop the soft-delete filter when finding ids.
         const findOpts = opts?.hardDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts;
-        const findCtx = this.dialect.createContext();
-        this.dialect.find(findCtx, entity, { ...q, $select: { [meta.id]: true } }, findOpts);
-        const founds = await this.all(findCtx.sql, findCtx.values);
-        if (!founds.length) {
+        const ids = await this.settleIds(entity, q, findOpts);
+        if (!ids.length) {
             return 0;
         }
-        const ids = founds.map((it) => it[meta.id]);
         // Children first: they hold the foreign key, so deleting the parent ahead of them is rejected
         // outright by any schema that declares the constraint without `ON DELETE CASCADE`.
         await this.deleteRelations(entity, ids, opts);
@@ -281,12 +308,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             }
             await this.lazyConnect();
             for (const sql of this.dialect.getBeginTransactionStatements(opts?.isolationLevel)) {
-                try {
-                    await this.internalRun(sql);
-                }
-                catch (err) {
-                    throw enrichError(err, this.logger, sql);
-                }
+                await this.runTransactionCommand(sql);
             }
             this.hasPendingTransaction = true;
         });
@@ -296,27 +318,32 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             if (!this.hasPendingTransaction) {
                 throwNoPendingTransaction();
             }
-            try {
-                await this.internalRun(this.dialect.commitTransactionCommand);
-            }
-            catch (err) {
-                throw enrichError(err, this.logger, this.dialect.commitTransactionCommand);
-            }
-            this.hasPendingTransaction = false;
+            await this.endTransactionWith(this.dialect.commitTransactionCommand);
         });
     }
     async rollbackTransaction() {
         return this.serialize(async () => {
-            if (!this.hasPendingTransaction) {
-                throwNoPendingTransaction();
-            }
-            try {
-                await this.internalRun(this.dialect.rollbackTransactionCommand);
-            }
-            catch (err) {
-                throw enrichError(err, this.logger, this.dialect.rollbackTransactionCommand);
+            if (this.hasPendingTransaction) {
+                await this.endTransactionWith(this.dialect.rollbackTransactionCommand);
             }
-            this.hasPendingTransaction = false;
         });
     }
+    /**
+     * Only a statement that succeeded ends the transaction. A `COMMIT` that fails can leave it open
+     * (SQLite answers `SQLITE_BUSY` and keeps it), so the flag has to stay set for the `catch` in
+     * {@link AbstractQuerier.transaction} or {@link AbstractQuerier.release} to roll it back.
+     */
+    async endTransactionWith(command) {
+        await this.runTransactionCommand(command);
+        this.hasPendingTransaction = false;
+    }
+    /** Transaction statements skip `timed()`, so they attach their own query context to a failure. */
+    async runTransactionCommand(sql) {
+        try {
+            await this.internalRun(sql);
+        }
+        catch (err) {
+            throw enrichError(err, this.logger, sql);
+        }
+    }
 }

package/dist/querier/index.d.ts

@@ -2,6 +2,4 @@ export * from './abstractQuerier.js';
 export * from './abstractQuerierPool.js';
 export * from './abstractSqlQuerier.js';
 export * from './abstractSqlQuerierPool.js';
-export * from './querierContext.js';
 export * from './queryError.js';
-export * from './transactional.js';

package/dist/querier/index.js

@@ -2,6 +2,4 @@ export * from './abstractQuerier.js';
 export * from './abstractQuerierPool.js';
 export * from './abstractSqlQuerier.js';
 export * from './abstractSqlQuerierPool.js';
-export * from './querierContext.js';
 export * from './queryError.js';
-export * from './transactional.js';

package/dist/sqlite/abstractSqliteQuerier.d.ts

@@ -30,8 +30,7 @@ export type SqlitePreparedStatement = {
 export declare abstract class AbstractSqliteQuerier extends AbstractSqlQuerier {
     /**
      * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
-     * a querier returns nothing; it only asserts the unit of work was finished. Drivers owning a
-     * closable per-querier connection override this.
+     * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
      */
     internalRelease(): Promise<void>;
 }

package/dist/sqlite/abstractSqliteQuerier.js

@@ -1,5 +1,4 @@
 import { AbstractSqlQuerier } from '../querier/index.js';
-import { throwPendingTransaction } from '../util/index.js';
 /** Bound parameters reach a driver as `unknown[]` from the compiler; every driver types them narrowly. */
 export function toSqliteBindValues(values) {
     return (values || []);
@@ -7,14 +6,9 @@ export function toSqliteBindValues(values) {
 export class AbstractSqliteQuerier extends AbstractSqlQuerier {
     /**
      * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
-     * a querier returns nothing; it only asserts the unit of work was finished. Drivers owning a
-     * closable per-querier connection override this.
+     * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
      */
-    async internalRelease() {
-        if (this.hasOpenTransaction) {
-            throwPendingTransaction();
-        }
-    }
+    async internalRelease() { }
 }
 /**
  * Querier for the SQLite drivers that expose prepared statements: `better-sqlite3`, `bun:sqlite`

package/dist/sqlite/hranaQuerier.d.ts

@@ -48,6 +48,11 @@ export declare class HranaQuerier extends AbstractSqliteQuerier {
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
     get hasOpenTransaction(): boolean;
     beginTransaction(_opts?: TransactionOptions): Promise<void>;
+    /**
+     * Both drop the handle before the call, not after: one that outlived a failed commit or rollback left
+     * the querier unreleasable. The optional call in the rollback is also what makes it a no-op when
+     * there is nothing open.
+     */
     commitTransaction(): Promise<void>;
     rollbackTransaction(): Promise<void>;
     internalRelease(): Promise<void>;

package/dist/sqlite/hranaQuerier.js

@@ -41,22 +41,26 @@ export class HranaQuerier extends AbstractSqliteQuerier {
             this.tx = await this.client.transaction('write');
         });
     }
+    /**
+     * Both drop the handle before the call, not after: one that outlived a failed commit or rollback left
+     * the querier unreleasable. The optional call in the rollback is also what makes it a no-op when
+     * there is nothing open.
+     */
     async commitTransaction() {
         return this.serialize(async () => {
-            if (!this.tx) {
+            const tx = this.tx;
+            if (!tx) {
                 throwNoPendingTransaction();
             }
-            await this.tx.commit();
             this.tx = undefined;
+            await tx.commit();
         });
     }
     async rollbackTransaction() {
         return this.serialize(async () => {
-            if (!this.tx) {
-                throwNoPendingTransaction();
-            }
-            await this.tx.rollback();
+            const tx = this.tx;
             this.tx = undefined;
+            await tx?.rollback();
         });
     }
     async internalRelease() {

package/dist/type/entity.d.ts

@@ -16,16 +16,20 @@ export type Key<E> = keyof E & string;
  * Includes scalar fields, JSON fields, and scalar arrays (e.g. vector `number[]`).
  * The `-?` modifier strips optionality so the indexed access yields clean key unions
  * (without it, optional properties leak `undefined` into the union).
+ *
+ * The check is bracketed so `any` resolves once rather than matching both this and
+ * {@link RelationKey}: an unbracketed `any extends X` satisfies either branch.
  */
 export type FieldKey<E> = {
-    readonly [K in keyof E]-?: NonNullable<E[K]> extends Scalar | Scalar[] | Json ? K : never;
+    readonly [K in keyof E]-?: [NonNullable<E[K]>] extends [Scalar | Scalar[] | Json] ? K : never;
 }[Key<E>];
 /**
- * Infers the relation names of an entity
+ * Infers the relation names of an entity: whatever is left once its fields and its methods are
+ * taken out. Stated as the complement rather than as {@link FieldKey}'s test negated, so the two
+ * cannot drift; methods are subtracted because one is not a `Scalar` and would otherwise read as a
+ * relation.
  */
-export type RelationKey<E> = {
-    readonly [K in keyof E]-?: NonNullable<E[K]> extends Scalar | Scalar[] | Json ? never : K;
-}[Key<E>];
+export type RelationKey<E> = Exclude<Key<E>, FieldKey<E> | MethodKey<E>>;
 /**
  * Whether `T` carries the `Json` brand. Checks for the `__json` marker key explicitly:
  * a bare `extends Json<infer T>` is not discriminating in check position (primitives match it,
@@ -117,14 +121,29 @@ export type JsonUpdateOp<T = unknown> = {
  */
 type JsonUpdateOpFor<V, T = UnwrapJson<NonNullable<V>>> = [T] extends [never] ? never : T extends readonly unknown[] ? never : JsonUpdateOp<T>;
 /**
- * Accepted value for a single field in an update payload: the value itself, `QueryRaw` for a raw SQL
- * expression (e.g. `raw('NOW()')`), and - for JSON object fields - the JSON operators.
+ * Accepted value for a single field in an update payload: the value itself, `null` where the column
+ * is nullable, `QueryRaw` for a raw SQL expression (e.g. `raw('NOW()')`), and - for JSON object
+ * fields - the JSON operators.
+ *
+ * An optional property is a nullable column, and clearing one is what an update is for, so `null`
+ * belongs in the declared type rather than behind a cast.
  */
-type UpdateFieldValue<V> = V | QueryRaw | JsonUpdateOpFor<V>;
+type UpdateFieldValue<V> = V | (undefined extends V ? null : never) | QueryRaw | JsonUpdateOpFor<V>;
 /**
- * Payload type for update operations.
- * Widens each field to additionally accept `QueryRaw` or `JsonUpdateOp` (for JSON fields),
- * providing IDE autocomplete for `$set`/`$push`/`$pull` keys via `Json<infer T>`.
+ * An entity's fields and relations, each keeping its declared optionality: what the whole-record
+ * writes (`insertOne`, `saveOne`, `upsertOne`, and their `*Many`) persist.
+ *
+ * Not `E`: that *demands* back every method the class declares, so on an entity carrying a
+ * lifecycle hook - `@BeforeInsert() generateSlug()` - a plain `{ title: 'Hello' }` was rejected as
+ * "missing the following properties". Method-free entities were unaffected, which is why the other
+ * examples worked. No runtime filter can help; the call never gets that far. `Pick` because it
+ * stays indexable by `IdKey<E>`, which the write path needs.
+ */
+export type EntityData<E> = Pick<E, FieldKey<E> | RelationKey<E>>;
+/**
+ * Payload type for update operations: {@link EntityData} made partial, and widened per field to
+ * accept `QueryRaw` or `JsonUpdateOp` (for JSON fields), which gives IDE autocomplete for
+ * `$set`/`$push`/`$pull` keys via `Json<infer T>`.
  */
 export type UpdatePayload<E> = {
     [K in FieldKey<E>]?: UpdateFieldValue<E[K]>;
@@ -149,6 +168,10 @@ export type IdKey<E> = E extends {
 } ? 'uuid' & FieldKey<E> : FieldKey<E>;
 /**
  * Infers the value of the key identifier on an entity.
+ *
+ * Nullable, because an entity declares its id optional - nothing has assigned one before the
+ * insert. That puts `undefined` inside every by-id method's parameter, where it would mean "no
+ * filter"; `assertIdValue` is what rejects it.
  */
 export type IdValue<E> = E[IdKey<E>];
 /**

package/dist/type/querier.d.ts

@@ -4,7 +4,7 @@ import type { SqlDialectName } from './dialect.js';
 import type { HookEvent } from './entity.js';
 import type { LoggingOptions } from './logger.js';
 import type { NamingStrategy } from './namingStrategy.js';
-import type { Query, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
+import type { Query, QueryFilter, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
 import type { UniversalQuerier } from './universalQuerier.js';
 import type { Type } from './utility.js';
 /**
@@ -15,54 +15,67 @@ export type IsolationLevel = 'read uncommitted' | 'read committed' | 'repeatable
  * Options for starting a transaction.
  */
 export type TransactionOptions = {
+    /**
+     * Applies to this transaction only.
+     *
+     * @remarks MySQL and MariaDB set it as a statement of its own ahead of `START TRANSACTION`, so a
+     * `START TRANSACTION` that then fails leaves the level applied to whatever the pooled connection
+     * runs next. Set it per transaction that needs it rather than relying on what a connection carries.
+     */
     readonly isolationLevel?: IsolationLevel;
 };
 export type DialectName = SqlDialectName | 'mongodb';
+/**
+ * The read and delete methods below take the entity as an argument or as the query's `$entity` key.
+ * In each pair the `$entity` overload comes **first** on purpose: when no overload matches,
+ * TypeScript reports the error from the *last* one, so keeping the entity-argument form last is
+ * what makes a typo'd query key report as itself rather than as a missing `$entity`.
+ */
 export interface Querier extends UniversalQuerier {
     /**
      * Find one record. Supports both entity-as-argument and entity-as-field patterns.
      */
-    findOne<E extends object>(entity: Type<E>, q: QueryOne<E>, opts?: QueryOptions): Promise<E | undefined>;
     findOne<E extends object>(q: QueryOne<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<E | undefined>;
+    findOne<E extends object>(entity: Type<E>, q: QueryOne<E>, opts?: QueryOptions): Promise<E | undefined>;
     /**
      * Find many records. Supports both entity-as-argument and entity-as-field patterns.
      */
-    findMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
     findMany<E extends object>(q: Query<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<E[]>;
+    findMany<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<E[]>;
     /**
      * Stream records as an async iterable. Supports both patterns.
      * Does not fill relations or fire lifecycle hooks.
      */
-    findManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncIterable<E>;
     findManyStream<E extends object>(q: Query<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): AsyncIterable<E>;
+    findManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncIterable<E>;
     /**
      * Find many records and count. Supports both patterns.
      */
-    findManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     findManyAndCount<E extends object>(q: Query<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<[E[], number]>;
+    findManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     /**
      * Count records. Supports both patterns.
      */
-    count<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
-    count<E extends object>(q: QuerySearch<E> & {
+    count<E extends object>(q: QueryFilter<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
+    count<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Delete many records (soft-deletes when the entity has a soft-delete field, else removes them).
      * Supports both entity-as-argument and entity-as-field patterns.
      */
-    deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     deleteMany<E extends object>(q: QuerySearch<E> & {
         $entity: Type<E>;
     }, opts?: QueryOptions): Promise<number>;
+    deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     /**
      * whether this querier is in a transaction or not.
      */
@@ -80,11 +93,14 @@ export interface Querier extends UniversalQuerier {
      */
     commitTransaction(): Promise<void>;
     /**
-     * aborts the currently active transaction in this querier.
+     * aborts the currently active transaction, or does nothing when there is none, so it is safe from a
+     * `catch` / `finally` without checking {@link hasOpenTransaction} first. `commitTransaction` is strict
+     * instead: a caller who believes their work was committed has to hear that it was not.
      */
     rollbackTransaction(): Promise<void>;
     /**
-     * release the querier to the pool.
+     * rolls back any unfinished transaction and releases the querier to the pool. A pooled querier is
+     * finished afterwards: using it again throws rather than taking a second connection nothing owns.
      */
     release(): Promise<void>;
     /**

package/dist/type/query.d.ts

@@ -142,21 +142,29 @@ export type QueryPager = {
     $limit?: number;
 };
 /**
- * search options.
+ * Which rows a statement addresses. `count` takes exactly this: how many rows match is all a count
+ * can answer, so an ordering or a page on it is a clause it could only drop or choke on.
  */
-export type QuerySearch<E> = {
+export type QueryFilter<E> = {
     /**
      * filtering options.
      */
     $where?: QueryWhere<E>;
+};
+/**
+ * A filter plus the ordering and page `updateMany`/`deleteMany` take. Both settle the rows they
+ * picked before writing, so the page is portable rather than MySQL-only.
+ *
+ * `$sort` excludes vector search here for the reason `$lock` is declared on {@link Query} instead:
+ * a vector search ranks rows into a projected distance column, and only a SELECT has a projection
+ * list to hold one. Passing `QuerySortMap` its `Vector = false` is what keeps it off these.
+ */
+export type QuerySearch<E> = QueryFilter<E> & {
     /**
      * sorting options.
      */
-    $sort?: QuerySortMap<E>;
+    $sort?: QuerySortMap<E, false>;
 } & QueryPager;
-/**
- * criteria one options.
- */
 /**
  * query options.
  */
@@ -177,6 +185,11 @@ export type Query<E> = {
      * regardless, since subtracting them would leave the relation unfilled.
      */
     $exclude?: QueryExclude<E>;
+    /**
+     * sorting options, vector similarity search included: a SELECT is the one statement with a
+     * projection list to hold the distance such a search computes.
+     */
+    $sort?: QuerySortMap<E>;
     /**
      * whether to return only distinct rows.
      */
@@ -187,11 +200,11 @@ export type Query<E> = {
      * the rows, so it is rejected rather than emitted. Locks only the queried entity, never anything
      * reached through `$populate`. SQL only; MongoDB and the SQLite family reject it.
      *
-     * Deliberately declared here rather than on `QuerySearch`, which `count`/`update`/`delete` take:
-     * that placement is what keeps the clause off those statements at the type level.
+     * Declared here rather than on {@link QuerySearch}, which `update`/`delete` take: that placement
+     * is what keeps the clause off those statements at the type level.
      */
     $lock?: QueryLock;
-} & QuerySearch<E>;
+} & QueryFilter<E> & QueryPager;
 /**
  * options to get a single record.
  */

package/dist/type/queryAggregate.d.ts

@@ -1,5 +1,5 @@
 import type { FieldKey } from './entity.js';
-import type { QueryPager, QuerySortDirection, QuerySortMap } from './query.js';
+import type { QueryPager, QuerySortDirection } from './query.js';
 import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
 /**
  * Maps the offending keys to `never`, turning an excess key into a compile error; resolves to
@@ -10,6 +10,22 @@ import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
  * @internal
  */
 type Reject<K> = [K] extends [never] ? unknown : Record<K & string, never>;
+/**
+ * The columns `$group` actually names: keys whose value is literally `true`, not `keyof G`.
+ * Wherever `G` cannot be inferred - `$group` omitted, hoisted, or annotated - it *is* its own
+ * constraint, whose every value is `true | undefined`, and keying off values yields `never` there
+ * rather than every field of the entity.
+ * @internal
+ */
+type GroupedKeys<G> = {
+    [K in keyof G]: G[K] extends true ? K : never;
+}[keyof G];
+/**
+ * The keys `T` declares by name, or `never` when `T` is only an index signature - which is what an
+ * uninferred `$agg` is, and what would otherwise make every key look like a declared alias.
+ * @internal
+ */
+type NamedKeys<T> = string extends keyof T ? never : keyof T;
 declare const QUERY_AGGREGATE_OPS: readonly ['$count', '$sum', '$avg', '$min', '$max'];
 /**
  * Supported aggregate operations.
@@ -44,10 +60,29 @@ export declare function resolveAggregateOp(key: string): {
 };
 /** The argument of an aggregate function: a field, or `'*'` (only meaningful for `COUNT(*)`). */
 export type QueryAggregateArg<E> = FieldKey<E> | '*';
-/** Ops whose argument must be a plain field: every op except `$count` (which also accepts `'*'`). */
-type QueryAggregateFieldOp = Exclude<QueryAggregateOp, '$count'> | QueryAggregateDistinctOp;
-/** Every aggregate op mapped to its accepted argument: `$count` takes a field or `'*'`, the rest a field. */
-type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<QueryAggregateFieldOp, FieldKey<E>>;
+/**
+ * Fields `SUM`/`AVG` can total. Restricted to numeric columns because the result is declared
+ * `number`: totalling a text or date column is either an engine error or a coercion, and neither
+ * produces the value the signature promises.
+ */
+type NumericFieldKey<E> = {
+    readonly [K in FieldKey<E>]: [NonNullable<E[K]>] extends [number | bigint] ? K : never;
+}[FieldKey<E>];
+/** Every aggregate op, plain and DISTINCT-qualified. */
+type AggregateOp = QueryAggregateOp | QueryAggregateDistinctOp;
+/**
+ * Names a subset of {@link AggregateOp}. The constraint is the point, and why this is not `Extract`:
+ * renaming an op stops these literals satisfying it and breaks the subsets below at compile time,
+ * where `Extract` would quietly drop the renamed member and leave the subset wrong but valid.
+ */
+type OpsOf<K extends AggregateOp> = K;
+/** Ops that total a column, so their argument has to be numeric. */
+type TotallingOp = OpsOf<'$sum' | '$avg' | '$sumDistinct' | '$avgDistinct'>;
+/**
+ * Every aggregate op mapped to the argument it accepts: `$count` a field or `'*'` (`COUNT(*)`),
+ * the totalling ops a numeric field, `$min`/`$max`/`$countDistinct` any field.
+ */
+type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<TotallingOp, NumericFieldKey<E>> & Record<Exclude<AggregateOp, '$count' | TotallingOp>, FieldKey<E>>;
 /** Exactly one key of `T`: the chosen op with its value; every other op key is forbidden (`never`). */
 type ExactlyOne<T> = {
     [K in keyof T]: Readonly<Record<K, T[K]>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
@@ -64,17 +99,14 @@ type ExactlyOne<T> = {
  * @example { $avg: 'age' }            → AVG("age")
  */
 export type QueryAggregateFn<E> = ExactlyOne<QueryAggregateArgMap<E>>;
-/**
- * Aggregate ops whose grouped column always resolves to `number`, regardless of the aggregated
- * field's own type: the DISTINCT variants plus the base ops they map to (`$count`/`$sum`/`$avg`).
- */
-type QueryAggregateNumericOp = QueryAggregateDistinctOp | (typeof QUERY_AGGREGATE_DISTINCT_OP_BASE)[QueryAggregateDistinctOp];
-/** A single-key `{ [op]: unknown }` shape for each {@link QueryAggregateNumericOp}, matched to infer a `number` result. */
-type QueryAggregateNumericFn = {
-    [K in QueryAggregateNumericOp]: {
+/** A single-key `{ [op]: unknown }` shape for each op in `Ops`, matched to infer that op's result. */
+type FnWithOp<Ops extends string> = {
+    [K in Ops]: {
         readonly [P in K]: unknown;
     };
-}[QueryAggregateNumericOp];
+}[Ops];
+/** Ops that count rows. Alone among the ops they answer `0`, never NULL, over an empty group. */
+type CountingOp = OpsOf<'$count' | '$countDistinct'>;
 /**
  * Group-by columns: an object mapping entity field keys to `true`, exactly like {@link QuerySelect}.
  * Typed against the entity, so a typo'd column is a compile error. Compute aggregate columns with
@@ -105,18 +137,22 @@ export type QueryAggMap<E> = {
 /** The entity type of an aggregated field reference `F`, or `unknown` if it is not a known field. */
 type FieldValueType<E, F> = F extends keyof E ? E[F] : unknown;
 /**
- * Resolves a single computed column's type from its aggregate function: `$count`/`$sum`/`$avg` are
- * always `number`; `$min`/`$max` keep the aggregated field's own type.
+ * Resolves a single computed column's type from its aggregate function: `$count` is always
+ * `number`; `$sum`/`$avg` total to a `number` or to `null`; `$min`/`$max` keep the aggregated
+ * field's own type, likewise or `null`.
+ *
+ * Everything but `$count` is nullable: an aggregate over zero rows is NULL, and an ungrouped one
+ * still returns a row, so a `$where` matching nothing hands back a row of NULLs.
  *
  * `$sum`/`$avg` are exact to 2^53: Postgres widens a sum over BIGINT to NUMERIC, and decoding that
  * text to satisfy this `number` drops the digits past that bound. Use `raw()` for a wider total.
  * @internal
  */
-type QueryAggregateFnResult<E, Fn> = Fn extends QueryAggregateNumericFn ? number : Fn extends {
+type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number : Fn extends FnWithOp<TotallingOp> ? number | null : Fn extends {
     readonly $min: infer F;
-} ? FieldValueType<E, F> : Fn extends {
+} | {
     readonly $max: infer F;
-} ? FieldValueType<E, F> : unknown;
+} ? FieldValueType<E, F> | null : unknown;
 /**
  * Flattens an intersection into a single object literal for readable editor hovers.
  * @internal
@@ -127,9 +163,12 @@ type Simplify<T> = {
 /**
  * Infers the aggregated result row: grouped columns (`G`) keep their entity type; computed columns
  * (`A`) resolve from their aggregate function via {@link QueryAggregateFnResult}.
+ *
+ * Grouped columns come from {@link GroupedKeys}, not `keyof G`, so a `$group` the compiler could
+ * not read contributes none rather than all of them.
  */
 export type QueryAggregateResult<E, G, A> = Simplify<{
-    -readonly [K in keyof G & FieldKey<E>]: E[K];
+    -readonly [K in GroupedKeys<G> & FieldKey<E>]: E[K];
 } & {
     -readonly [K in keyof A]: QueryAggregateFnResult<E, A[K]>;
 }>;
@@ -171,8 +210,11 @@ export type QueryAggregate<E, G extends QueryGroupMap<E> = QueryGroupMap<E>, A e
     readonly $group?: G & Reject<Exclude<keyof G, FieldKey<E>>>;
     /**
      * Computed aggregate columns - `{ count: { $count: '*' }, avgAge: { $avg: 'age' } }`.
+     *
+     * An alias repeating a `$group` column is rejected: both would be emitted under that one name,
+     * leaving the driver to keep whichever it read last.
      */
-    readonly $agg?: A;
+    readonly $agg?: A & Reject<NamedKeys<A> & GroupedKeys<G>>;
     /**
      * Post-aggregation filtering, applied after grouping (SQL `HAVING`, MongoDB post-group `$match`).
      * Keyed by the result columns (grouped columns + computed aliases), and each value is typed to that
@@ -184,10 +226,11 @@ export type QueryAggregate<E, G extends QueryGroupMap<E> = QueryGroupMap<E>, A e
         readonly [K in keyof QueryAggregateResult<E, G, A>]?: QueryWhereFieldValue<QueryAggregateResult<E, G, A>[K]>;
     };
     /**
-     * Sort the aggregated results by a grouped column, a computed alias, or an entity field.
+     * Sort the aggregated results by a grouped column or a computed alias - an aggregate's rows are
+     * its groups, so any other entity field names a value the statement never produced.
      */
-    readonly $sort?: QuerySortMap<E> & {
-        readonly [K in (keyof G & string) | (keyof A & string)]?: QuerySortDirection;
+    readonly $sort?: {
+        readonly [K in keyof QueryAggregateResult<E, G, A>]?: QuerySortDirection;
     };
 } & QueryPager;
 export {};