uql-orm 0.29.0 → 0.30.0

package/dist/querier/abstractQuerier.js

@@ -1,6 +1,20 @@
 import { getMeta } from '../entity/index.js';
-import { asSelectMap, augmentWhere, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, LoggerWrapper, parseRelationAtKey, parseRelationQueryValue, runHooks, } from '../util/index.js';
+import { asSelectMap, augmentWhere, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, LoggerWrapper, parseRelationAtKey, parseRelationQueryValue, runHooks, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
+/**
+ * Rejects a nullish primary key before it reaches a statement. The by-id methods reduce to
+ * `{ $where: id }`, and a nullish `$where` is *no filter*, so an unchecked one addresses the whole
+ * table. An entity declares its id optional, which puts `undefined` inside `IdValue<E>`, and the
+ * HTTP layer reaches these methods with parsed JSON regardless, so the guard belongs at runtime.
+ *
+ * Its callers are all `async` so this surfaces as a rejection on every one of them: a guard that
+ * threw synchronously from some and rejected from others would escape a caller's `.catch()`.
+ */
+function assertIdValue(entity, id) {
+    if (id === undefined || id === null) {
+        throw new TypeError(`'${entity.name}' was addressed by id, but the id is ${String(id)}`);
+    }
+}
 /**
  * Base class for all database queriers.
  * It provides a standardized way to execute tasks serially to prevent race conditions on database connections.
@@ -65,6 +79,7 @@ export class AbstractQuerier {
         return [$entity, query, maybeQueryOrOpts];
     }
     async findOneById(entity, id, q = {}, opts) {
+        assertIdValue(entity, id);
         return this.findOne(entity, { ...q, $where: augmentWhere(getMeta(entity), q.$where, id) }, opts);
     }
     async findOne(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
@@ -115,7 +130,8 @@ export class AbstractQuerier {
         await this.emitHook(entity, 'afterInsert', payload);
         return ids;
     }
-    updateOneById(entity, id, payload, opts) {
+    async updateOneById(entity, id, payload, opts) {
+        assertIdValue(entity, id);
         return this.updateMany(entity, { $where: id }, payload, opts);
     }
     async updateMany(entity, q, payload, opts) {
@@ -124,7 +140,8 @@ export class AbstractQuerier {
         await this.emitHook(entity, 'afterUpdate', [payload]);
         return changes;
     }
-    restoreOneById(entity, id) {
+    async restoreOneById(entity, id) {
+        assertIdValue(entity, id);
         return this.restoreMany(entity, { $where: id });
     }
     async restoreMany(entity, q) {
@@ -137,16 +154,41 @@ export class AbstractQuerier {
             filters: { softDelete: false },
         });
     }
-    deleteOneById(entity, id, opts) {
+    async deleteOneById(entity, id, opts) {
+        assertIdValue(entity, id);
         return this.deleteMany(entity, { $where: id }, opts);
     }
     async deleteMany(entityOrQuery, qOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, qOrOpts, maybeOpts);
-        await this.emitHook(entity, 'beforeDelete', []);
-        const changes = await this.internalDeleteMany(entity, q, opts);
-        await this.emitHook(entity, 'afterDelete', []);
+        const doomed = await this.findDoomed(entity, q, opts);
+        if (doomed?.length === 0) {
+            return 0;
+        }
+        // Where a snapshot was taken, the statement names those rows rather than resolving `q` a second
+        // time. Two reads of one `$limit` with no total order are free to disagree, which would fire the
+        // hooks for one row and delete another; naming them also spares the second read.
+        const target = doomed ? { $where: doomed.map((it) => it[getMeta(entity).id]) } : q;
+        await this.emitHook(entity, 'beforeDelete', doomed ?? []);
+        const changes = await this.internalDeleteMany(entity, target, opts);
+        await this.emitHook(entity, 'afterDelete', doomed ?? []);
         return changes;
     }
+    /**
+     * The rows a delete is about to take, loaded only when a hook or listener is there to receive
+     * them: the round trip is pure overhead for the (common) delete nobody is watching, and
+     * `internalDeleteMany` has its own fast path that never reads the rows at all.
+     *
+     * `undefined` means nobody was watching, which is not the same as the empty array meaning nothing
+     * matched - the caller deletes by `q` for the first and skips the statement entirely for the second.
+     */
+    async findDoomed(entity, q, opts) {
+        if (!this.hasHook(entity, 'beforeDelete') && !this.hasHook(entity, 'afterDelete')) {
+            return undefined;
+        }
+        // A hard delete takes already-soft-deleted rows too, so reading them back has to see them.
+        const findOpts = opts?.hardDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts;
+        return this.internalFindMany(entity, q, findOpts);
+    }
     async saveOne(entity, payload) {
         const [id] = await this.saveMany(entity, [payload]);
         return id;
@@ -400,32 +442,26 @@ export class AbstractQuerier {
             throw err;
         }
     }
+    /** Whether anything at all - a global listener or the entity itself - handles `event`. */
+    hasHook(entity, event) {
+        return (this.extra?.listeners?.some((listener) => listener[event]) || (getMeta(entity).hooks?.[event]?.length ?? 0) > 0);
+    }
     /**
      * Emit a lifecycle hook event for the given entity.
      * Fires global listeners first, then entity-level hooks.
      */
     async emitHook(entity, event, payloads) {
-        const listeners = this.extra?.listeners;
-        const meta = getMeta(entity);
-        const registrations = meta.hooks?.[event];
-        // Fast bail-out: skip if no listeners and no entity hooks
-        if (!listeners?.length && !registrations?.length)
+        if (!this.hasHook(entity, event))
             return;
-        // Fire global listeners first
-        if (listeners?.length) {
-            for (const listener of listeners) {
-                const fn = listener[event];
-                if (fn) {
-                    const result = fn({ entity, querier: this, payloads, event });
-                    if (result instanceof Promise)
-                        await result;
-                }
+        for (const listener of this.extra?.listeners ?? []) {
+            const fn = listener[event];
+            if (fn) {
+                const result = fn({ entity, querier: this, payloads, event });
+                if (result instanceof Promise)
+                    await result;
             }
         }
-        // Fire entity-level hooks
-        if (registrations?.length) {
-            await runHooks(entity, event, payloads, { querier: this });
-        }
+        await runHooks(entity, event, payloads, { querier: this });
     }
     /**
      * Runs `task` after everything already queued on this querier, one at a time.

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { ExtraOptions, IdValue, PoolRunOptions, Querier, QuerierPool, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, IdValue, PoolRunOptions, Querier, QuerierPool, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -35,14 +35,14 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     findManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     count<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
-    insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     updateOneById<E extends object>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
-    saveOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E>>;
-    saveMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E>>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     deleteOneById<E extends object>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions): Promise<number>;
     deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     restoreOneById<E extends object>(entity: Type<E>, id: IdValue<E>): Promise<number>;

package/dist/querier/abstractSqlQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
-import type { ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import type { BuildUpdateResultPayload } from '../util/sql.util.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
@@ -64,10 +64,12 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     private hydrateFields;
     protected internalCount<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     protected internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
-    internalInsertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
+    /** The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on. */
+    private settleIds;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     get hasOpenTransaction(): boolean;
     beginTransaction(opts?: TransactionOptions): Promise<void>;

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;
@@ -219,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]);
     }
@@ -252,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);
@@ -261,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);

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';
 /**
@@ -25,51 +25,57 @@ export type TransactionOptions = {
     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.
      */

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 {};