uql-orm 0.29.0 → 0.31.0

package/dist/turso/tursoLocalQuerierPool.d.ts

@@ -1,7 +1,7 @@
-import { AbstractSqlQuerierPool } from '../querier/index.js';
+import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
 import type { ExtraOptions } from '../type/index.js';
 import { TursoDialect } from './tursoDialect.js';
-import { TursoLocalQuerier } from './tursoLocalQuerier.js';
+import { type TursoDatabase, TursoLocalQuerier } from './tursoLocalQuerier.js';
 /** Subset of `DatabaseOpts` from `@tursodatabase/database`, declared locally to avoid the coupling. */
 export type TursoLocalOptions = {
     readonly?: boolean;
@@ -17,16 +17,10 @@ export type TursoLocalOptions = {
  * package ships native binaries that do not resolve on edge runtimes. Separating them guarantees a
  * bundle targeting Workers never reaches the native import.
  */
-export declare class TursoLocalQuerierPool extends AbstractSqlQuerierPool<TursoLocalQuerier, TursoDialect> {
+export declare class TursoLocalQuerierPool extends AbstractSharedHandleQuerierPool<TursoDatabase, TursoLocalQuerier, TursoDialect> {
     readonly filename: string;
     readonly opts?: TursoLocalOptions | undefined;
-    private db?;
     constructor(filename?: string, opts?: TursoLocalOptions | undefined, extra?: ExtraOptions);
-    /**
-     * The database handle is shared (single connection), but each acquisition gets its own querier
-     * so transaction state stays per unit of work.
-     */
-    getQuerier(): Promise<TursoLocalQuerier>;
-    private openDb;
-    end(): Promise<void>;
+    protected openDb(): Promise<TursoDatabase>;
+    protected buildQuerier(db: TursoDatabase): TursoLocalQuerier;
 }

package/dist/turso/tursoLocalQuerierPool.js

@@ -1,4 +1,4 @@
-import { AbstractSqlQuerierPool } from '../querier/index.js';
+import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
 import { TursoDialect } from './tursoDialect.js';
 import { TursoLocalQuerier } from './tursoLocalQuerier.js';
 /**
@@ -8,23 +8,14 @@ import { TursoLocalQuerier } from './tursoLocalQuerier.js';
  * package ships native binaries that do not resolve on edge runtimes. Separating them guarantees a
  * bundle targeting Workers never reaches the native import.
  */
-export class TursoLocalQuerierPool extends AbstractSqlQuerierPool {
+export class TursoLocalQuerierPool extends AbstractSharedHandleQuerierPool {
     filename;
     opts;
-    db;
     constructor(filename = ':memory:', opts, extra) {
         super(new TursoDialect({ namingStrategy: extra?.namingStrategy }), extra);
         this.filename = filename;
         this.opts = opts;
     }
-    /**
-     * The database handle is shared (single connection), but each acquisition gets its own querier
-     * so transaction state stays per unit of work.
-     */
-    async getQuerier() {
-        this.db ??= await this.openDb();
-        return new TursoLocalQuerier(this.db, this.dialect, this.extra);
-    }
     async openDb() {
         const { connect } = await import('@tursodatabase/database');
         // Annotated rather than cast, so the structural contract is checked against the real driver.
@@ -33,8 +24,7 @@ export class TursoLocalQuerierPool extends AbstractSqlQuerierPool {
         await db.pragma('foreign_keys = ON');
         return db;
     }
-    async end() {
-        await this.db?.close();
-        this.db = undefined;
+    buildQuerier(db) {
+        return new TursoLocalQuerier(db, this.dialect, this.extra);
     }
 }

package/dist/type/entity.d.ts

@@ -1,7 +1,7 @@
 import type { ForeignKeyAction, IndexType } from '../schema/types.js';
 import type { FilterOptions } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
-import type { Except, Json, Scalar, Type, Unpacked } from './utility.js';
+import type { Except, IsMany, Json, Scalar, Type, Unpacked } from './utility.js';
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /**
  * Allow to customize the name of the property that identifies an entity
@@ -16,16 +16,22 @@ 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. It reads
+ * `readonly Scalar[]`, which every mutable one satisfies too, so declaring a vector or a scalar
+ * array `readonly` does not push the field over into {@link RelationKey}.
  */
 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 | readonly 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,
@@ -75,7 +81,7 @@ export type JsonFieldPathValue<E, P extends string> = P extends `${infer F}.${in
  * Used by `$push` and `$pull` to provide type-safe element targets.
  */
 export type JsonArrayFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends readonly unknown[] ? K & string : never]?: Unpacked<NonNullable<T[K]>>;
+    [K in keyof T as IsMany<T[K]> extends true ? K & string : never]?: Unpacked<NonNullable<T[K]>>;
 };
 /**
  * Operator shape accepted by JSON/JSONB fields in update payloads: `$set`/`$unset` target object
@@ -115,16 +121,31 @@ export type JsonUpdateOp<T = unknown> = {
  *   `JSON_SET(arr, '$.k', v)` is a no-op on MySQL and SQLite. Replace the whole value instead.
  *   `Json<unknown>` stays permissive, since `unknown` is not an array.
  */
-type JsonUpdateOpFor<V, T = UnwrapJson<NonNullable<V>>> = [T] extends [never] ? never : T extends readonly unknown[] ? never : JsonUpdateOp<T>;
+type JsonUpdateOpFor<V, T = UnwrapJson<NonNullable<V>>> = [T] extends [never] ? never : IsMany<T> extends true ? 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 +170,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>];
 /**
@@ -346,8 +371,8 @@ export type RelationTarget<V> = NonNullable<Unpacked<NonNullable<V>>>;
  */
 export type RelationOptionsFor<V> = Omit<RelationOptions<RelationTarget<V>>, 'entity' | 'cardinality'> & {
     readonly entity: EntityGetter<RelationTarget<V>>;
-    readonly cardinality: NonNullable<V> extends readonly unknown[] ? '1m' | 'mm' : '11' | 'm1';
-} & (NonNullable<V> extends readonly unknown[] ? RelationJoin<RelationTarget<V>> : unknown);
+    readonly cardinality: IsMany<V> extends true ? '1m' | 'mm' : '11' | 'm1';
+} & (IsMany<V> extends true ? RelationJoin<RelationTarget<V>> : unknown);
 /**
  * The method names of an entity, so hook registrations name a method that exists.
  */

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

@@ -1,8 +1,8 @@
-import type { FieldKey, JsonFieldPaths, RelationKey } from './entity.js';
+import type { FieldKey, JsonFieldPaths, RelationKey, RelationTarget } from './entity.js';
 import type { QueryLock } from './queryLock.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
-import type { BooleanLike, Except, PrimaryKey, Unpacked } from './utility.js';
+import type { BooleanLike, Except, IsMany, PrimaryKey } from './utility.js';
 import type { QueryVectorSearch } from './vector.js';
 export type QueryOptions = {
     /**
@@ -64,9 +64,9 @@ export type QueryConflictPaths<E> = {
     [K in FieldKey<E>]?: true;
 };
 /**
- * options to populate a relation.
+ * Options to populate a relation declared as `V`, by its cardinality.
  */
-export type QueryPopulateRelationOptions<E> = (E extends unknown[] ? Except<Query<Unpacked<E>>, '$lock'> : QueryUnique<Unpacked<E>>) & {
+export type QueryPopulateRelationOptions<V> = (IsMany<V> extends true ? Except<Query<RelationTarget<V>>, '$lock'> : QueryUnique<RelationTarget<V>>) & {
     $required?: boolean;
 };
 /**
@@ -126,7 +126,7 @@ export type QuerySortMap<E, Vector extends boolean = true> = {
 } & {
     [P in JsonFieldPaths<E>]?: QuerySortDirection;
 } & {
-    [K in RelationKey<E> as NonNullable<E[K]> extends readonly unknown[] ? never : K]?: QuerySortMap<NonNullable<E[K]>, false>;
+    [K in RelationKey<E> as IsMany<E[K]> extends true ? never : K]?: QuerySortMap<RelationTarget<E[K]>, false>;
 };
 /**
  * pager options.
@@ -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 {};

package/dist/type/queryWhere.d.ts

@@ -1,6 +1,6 @@
-import type { FieldKey, IdValue, JsonFieldPaths, JsonFieldPathValue, RelationKey } from './entity.js';
+import type { FieldKey, IdValue, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
 import type { QueryRaw } from './queryRaw.js';
-import type { ExpandScalar, QueryComparableScalar, Scalar, Unpacked } from './utility.js';
+import type { ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
 /**
  * options for full-text-search operator.
  */
@@ -35,7 +35,7 @@ export type QueryWhereFieldMap<E> = {
 export type QueryWhereMap<E> = QueryWhereFieldMap<E> & QueryWhereRootOperator<E> & {
     [P in JsonFieldPaths<E>]?: QueryWhereFieldValue<JsonFieldPathValue<E, P>>;
 } & {
-    [K in RelationKey<E>]?: QueryWhereMap<Unpacked<NonNullable<E[K]>>> | QueryRelationSizeFilter;
+    [K in RelationKey<E>]?: QueryWhereMap<RelationTarget<E[K]>> | QueryRelationSizeFilter;
 };
 /**
  * Filter a to-many relation by its row count.
@@ -246,7 +246,7 @@ type QueryCommonOp = Exclude<keyof QueryWhereFieldOperatorMap<unknown>, QueryStr
  * Operator keys applicable to a field of type `T`. Brackets prevent union distribution so an
  * optional field (`string | undefined`) or a literal union (`'a' | 'b'`) gates as one type.
  */
-type QueryAllowedOp<T> = QueryCommonOp | ([NonNullable<T>] extends [QueryComparableScalar] ? QueryOrderedOp : never) | ([NonNullable<T>] extends [string] ? QueryStringOp : never) | ([NonNullable<T>] extends [readonly unknown[]] ? QueryArrayOp : never);
+type QueryAllowedOp<T> = QueryCommonOp | ([NonNullable<T>] extends [QueryComparableScalar] ? QueryOrderedOp : never) | ([NonNullable<T>] extends [string] ? QueryStringOp : never) | (IsMany<T> extends true ? QueryArrayOp : never);
 /**
  * Operators applicable to a field of type `T`: string operators require string fields, ordering
  * operators comparable fields, array operators array fields. `unknown` stays fully permissive
@@ -257,8 +257,11 @@ export type QueryWhereFieldOperators<T> = unknown extends T ? QueryWhereFieldOpe
  * Value for a field comparison. A bare array is an implicit `$in` for scalar fields only:
  * on array-typed fields (e.g. a vector `number[]`) an array of arrays is ambiguous, so
  * membership there requires an explicit operator.
+ *
+ * `null` is accepted on a nullable field (an optional property is a nullable column), matching what
+ * `$eq: null` already took.
  */
-export type QueryWhereFieldValue<T> = T | ([NonNullable<T>] extends [readonly unknown[]] ? never : T[]) | QueryWhereFieldOperators<T> | QueryRaw;
+export type QueryWhereFieldValue<T> = T | (undefined extends T ? null : never) | (IsMany<T> extends true ? never : T[]) | QueryWhereFieldOperators<T> | QueryRaw;
 /**
  * query filter array - used for `$and`, `$or`, `$not`, `$nor` operators.
  */

package/dist/type/universalQuerier.d.ts

@@ -1,5 +1,5 @@
-import type { IdValue, UpdatePayload } from './entity.js';
-import type { Query, QueryConflictPaths, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
+import type { EntityData, IdValue, UpdatePayload } from './entity.js';
+import type { Query, QueryConflictPaths, QueryFilter, QueryOne, QueryOptions, QuerySearch, QueryUpdateResult } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateResult, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
 /**
@@ -46,22 +46,24 @@ export interface UniversalQuerier {
      */
     findManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     /**
-     * counts the number of records matching the given search parameters.
+     * counts the number of records matching the given filter.
      * @param entity the target entity
-     * @param q the search options
+     * @param q the filter
      * @return the count
      */
-    count<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
+    count<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
     /**
      * Insert a single record and return its ID (provided, `onInsert`-generated, or
      * database-generated - see {@link UniversalQuerier.insertMany} for the exact semantics).
-     * Returns `undefined` when the ID cannot be determined (e.g. MySQL/SQLite non-auto-increment
-     * keys in batches without explicit IDs).
+     * Returns `undefined` only where the database cannot report one: MySQL, whose `LAST_INSERT_ID()`
+     * speaks for `AUTO_INCREMENT` columns alone and is left *stale* rather than cleared otherwise, so
+     * a non-auto-increment key the caller did not supply has no id to give and a header read would
+     * hand back an earlier row's. Every other backend uses `RETURNING` and is exact, SQLite included.
      * @param entity the entity to persist on
      * @param payload the data to be persisted
      * @return the ID
      */
-    insertOne<E extends object>(entity: Type<E>, payload: E): Promise<IdValue<E> | undefined>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
     /**
      * Insert multiple records in a single statement (auto-chunked when the batch exceeds the
      * dialect's bind-parameter limit) and return their IDs in payload order.
@@ -75,7 +77,7 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return the IDs
      */
-    insertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     /**
      * updates a record partially.
      * @param entity the entity to persist on
@@ -99,7 +101,7 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return operation metadata; see {@link QueryUpdateResult}
      */
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E): Promise<QueryUpdateResult>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     /**
      * Insert or update many records based on the conflict paths.
      * @param entity the entity to persist on
@@ -107,21 +109,21 @@ export interface UniversalQuerier {
      * @param payload the data to be persisted
      * @return operation metadata; see {@link QueryUpdateResult}
      */
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[]): Promise<QueryUpdateResult>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     /**
      * 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: E): Promise<IdValue<E>>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E>>;
     /**
      * 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: E[]): Promise<IdValue<E>[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<IdValue<E>[]>;
     /**
      * delete or SoftDelete a record.
      * @param entity the entity to persist on

package/dist/type/utility.d.ts

@@ -58,3 +58,10 @@ export type Except<T, K extends keyof T> = {
     [P in keyof T as P extends K ? never : P]: T[P];
 };
 export type Unpacked<T> = T extends readonly (infer U)[] ? U : T extends (...args: unknown[]) => infer U ? U : T extends Promise<infer U> ? U : T;
+/**
+ * Whether the value a property holds is many rather than one: a to-many relation, a scalar array, a
+ * vector. Every array test in the type layer goes through this, because writing one by hand gets some
+ * part of it wrong in ways nothing reports. `isMany.test-d.ts` has one case per part, and says what
+ * each is load-bearing for.
+ */
+export type IsMany<V> = [NonNullable<V>] extends [readonly unknown[]] ? true : false;