uql-orm 0.69.0 → 0.70.0

package/dist/querier/abstractQuerier.d.ts

@@ -1,4 +1,5 @@
-import type { EntityData, EntityId, ExtraOptions, FieldKey, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
+import type { AbstractDialect } from '../dialect/abstractDialect.js';
+import type { EntityData, EntityId, EntityWrite, ExtraOptions, FieldKey, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, UpdateWrite, WrittenId } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 /** Base class for all database queriers. */
 export declare abstract class AbstractQuerier implements Querier {
@@ -15,6 +16,7 @@ export declare abstract class AbstractQuerier implements Querier {
      */
     protected released: boolean;
     protected readonly logger: LoggerWrapper;
+    abstract readonly dialect: AbstractDialect;
     constructor(extra?: ExtraOptions | undefined);
     protected validateProjectionQuery<E extends object>(entity: Type<E>, q: Query<E>): void;
     private validateProjectionQueryRecursive;
@@ -73,21 +75,24 @@ export declare abstract class AbstractQuerier implements Querier {
     protected abstract 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>[]>;
     /** Abstract outright: nothing is shared to do around it. See {@link UniversalQuerier.estimatedCount}. */
     abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
-    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
     /**
      * The `onInsert` values are filled here, before the write, so the after hooks and the ids read the
      * same rows the statement wrote.
      */
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     /** Writes `rows`, and onto each one the key the database generated for it, where it can tell. */
     protected abstract internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
-    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
+    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
     /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
-    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
+    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
     /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
     private updateColumns;
-    /** Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or delete. */
-    protected settlesWrite<E extends object>(_entity: Type<E>, q: QuerySearch<E>): boolean;
+    /**
+     * Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or
+     * delete, and one without {@link DialectFeatures.correlatedWrites} cannot read a relation in its filter.
+     */
+    protected settlesWrite<E extends object>(entity: Type<E>, q: QuerySearch<E>): boolean;
     /** The ids `q` matches, in its own order and page. */
     protected settleIds<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<EntityId<E>[]>;
     /** Runs one UPDATE over `q`, which names its rows by id wherever {@link updateMany} settled them. */
@@ -95,8 +100,8 @@ export declare abstract class AbstractQuerier implements Querier {
     restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;
     restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
     /** Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither the insert's nor the update's pair fits. */
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>): Promise<QueryUpsertOneResult<E>>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>[]): Promise<QueryUpsertManyResult<E>>;
     protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
@@ -107,13 +112,13 @@ export declare abstract class AbstractQuerier implements Querier {
     }, opts?: QueryOptions): Promise<number>;
     /** Runs one DELETE (or soft-delete stamp) over `q`, which names its rows by id wherever {@link deleteMany} settled them. */
     protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
     /**
      * Whether a row names its key decides its statement, never whether the row exists: a named row
      * upserts on that key, so a stale id is written rather than silently missed, and an unnamed one
      * inserts. A composite is always named. The hooks follow the statement: a named row fires the upsert pair.
      */
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     /** Writes each inserted row's relations, one set of statements per relation whatever the number of rows. */
     protected insertRelations<E extends object>(entity: Type<E>, rows: E[]): Promise<void>;
     /** `EntityId` because a settled composite row is an object, which {@link childrenOf} reads each foreign key column out of. */

package/dist/querier/abstractQuerier.js

@@ -1,5 +1,5 @@
 import { assertSoleId, getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
-import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isPagedQuery, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
+import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isPagedQuery, hasKeys, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
 /**
  * Refuses a nullish id, which would reduce to no filter at all, and a composite id missing a column,
@@ -27,6 +27,17 @@ function assertIdValue(entity, id) {
 function soleParentColumn(relOpts) {
     return parentJoins(relOpts, 1)[0].joined;
 }
+/**
+ * A bulk write names the rows it changes: a `$where`, or a `$limit` capping how many it reaches. The
+ * caller's own clauses are what count - a filter the entity adds, soft delete's, would otherwise make
+ * every table look narrowed, which is the case this exists to catch.
+ */
+function assertNamesRows(entity, method, q, opts) {
+    if (opts?.unfiltered || hasKeys(q?.$where) || q?.$limit !== undefined) {
+        return;
+    }
+    throw new TypeError(`'${method}' over '${entity.name}' names no rows, so it would address every one: pass '{ unfiltered: true }' to mean it`);
+}
 /**
  * The id each written row is named by, in payload order. Read off the rows as written, so a key the
  * database generated or the ORM filled is there, and a composite is named by every column of it.
@@ -183,6 +194,7 @@ export class AbstractQuerier {
     }
     /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
     async updateMany(entity, q, payload, opts) {
+        assertNamesRows(entity, 'updateMany', q, opts);
         const meta = getMeta(entity);
         return this.hooked(entity, 'Update', [payload], async ([row]) => {
             fillOnFields(meta, [row], 'onUpdate');
@@ -206,9 +218,13 @@ export class AbstractQuerier {
         const writes = filterFieldKeys(getMeta(entity), row, 'onUpdate').length > 0;
         return writes ? this.internalUpdateMany(entity, q, row, opts) : unwritten;
     }
-    /** Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or delete. */
-    settlesWrite(_entity, q) {
-        return isPagedQuery(q);
+    /**
+     * Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or
+     * delete, and one without {@link DialectFeatures.correlatedWrites} cannot read a relation in its filter.
+     */
+    settlesWrite(entity, q) {
+        const { dialect } = this;
+        return isPagedQuery(q) || (!dialect.features.correlatedWrites && dialect.constrainsRelations(entity, q.$where));
     }
     /** The ids `q` matches, in its own order and page. */
     async settleIds(entity, q, opts) {
@@ -254,6 +270,7 @@ export class AbstractQuerier {
     }
     async deleteMany(entityOrQuery, qOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, qOrOpts, maybeOpts);
+        assertNamesRows(entity, 'deleteMany', q, opts);
         const meta = getMeta(entity);
         const cascades = cascadesOnDelete(meta);
         const watched = this.hasHook(entity, 'beforeDelete') || this.hasHook(entity, 'afterDelete');
@@ -350,8 +367,7 @@ export class AbstractQuerier {
             const relOpts = relationOf(meta, relKey);
             const relEntity = relOpts.entity();
             const target = relOpts.through ? relOpts.through() : relEntity;
-            const where = childrenOf(parentJoins(relOpts, meta.ids.length), ids);
-            await this.deleteMany(target, { $where: where }, opts);
+            await this.deleteMany(target, { $where: childrenOf(parentJoins(relOpts, meta.ids.length), ids) }, opts);
         }
     }
     /**
@@ -480,8 +496,12 @@ export class AbstractQuerier {
      * the write filled in - a generated key, an `onInsert` value - without it landing on the caller's.
      */
     async hooked(entity, event, payloads, write) {
-        await this.emitHook(entity, `before${event}`, payloads);
-        const rows = clone(payloads);
+        // The one place a caller's write becomes the row the rest of the library handles. They are the
+        // same object: a write is the entity's data without the keys the database fills, which
+        // TypeScript cannot relate across an entity it has not resolved.
+        const asRows = payloads;
+        await this.emitHook(entity, `before${event}`, asRows);
+        const rows = clone(asRows);
         const result = await write(rows);
         await this.emitHook(entity, `after${event}`, rows);
         return result;

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { EntityData, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
+import type { EntityWrite, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdateWrite, WrittenId } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -37,14 +37,14 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<boolean>;
     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>[]>;
     estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
-    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
-    updateOneById<E extends object>(entity: Type<E>, id: EntityId<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: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
+    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>): Promise<QueryUpsertOneResult<E>>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>[]): Promise<QueryUpsertManyResult<E>>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<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: EntityId<E>): Promise<number>;

package/dist/querier/abstractSqlQuerier.d.ts

@@ -80,7 +80,7 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      */
     private hydrateFields;
     /**
-     * Runs a statement whose one row carries a {@link COUNT_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
+     * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
      * a caller supplying their own `types` replaces the decoding the pools do at the wire; `?? 0` because
      * a catalog that does not know the table answers with no row, which is nothing counted.
      */

package/dist/querier/abstractSqlQuerier.js

@@ -1,4 +1,4 @@
-import { COUNT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
+import { AGGREGATE_VALUE_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
 import { getMeta, namesKey } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
@@ -290,13 +290,13 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
     }
     /**
-     * Runs a statement whose one row carries a {@link COUNT_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
+     * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
      * a caller supplying their own `types` replaces the decoding the pools do at the wire; `?? 0` because
      * a catalog that does not know the table answers with no row, which is nothing counted.
      */
     async runCount(build) {
         const [row] = await this.query(build);
-        return Number(row?.[COUNT_ALIAS] ?? 0);
+        return Number(row?.[AGGREGATE_VALUE_ALIAS] ?? 0);
     }
     async internalCount(entity, q, opts) {
         return this.runCount((ctx) => this.dialect.count(ctx, entity, q, opts));

package/dist/sqlite/sqliteDialect.js

@@ -19,6 +19,7 @@ export const SQLITE_FEATURES = {
     stringSizing: 'text',
     supportsUnsigned: false,
     serverSideCursors: false,
+    correlatedWrites: true,
     rowLocks: false,
     rowLockWithWindow: true,
     rowLockOf: true,

package/dist/turso/tursoDialect.d.ts

@@ -5,6 +5,6 @@ import type { SqlDialectFeatures } from '../type/index.js';
  * `ORDER BY` inside an aggregate, which its Rust engine lacks. Imports no driver.
  */
 export declare class TursoDialect extends LibsqlDialect {
-    /** The Rust engine takes no `ORDER BY` inside an aggregate. */
+    /** The Rust engine takes no `ORDER BY` inside an aggregate, nor a subquery reading the table a write changes. */
     readonly features: SqlDialectFeatures;
 }

package/dist/turso/tursoDialect.js

@@ -5,6 +5,10 @@ import { SQLITE_FEATURES } from '../sqlite/sqliteDialect.js';
  * `ORDER BY` inside an aggregate, which its Rust engine lacks. Imports no driver.
  */
 export class TursoDialect extends LibsqlDialect {
-    /** The Rust engine takes no `ORDER BY` inside an aggregate. */
-    features = { ...SQLITE_FEATURES, orderedJsonAggregates: false };
+    /** The Rust engine takes no `ORDER BY` inside an aggregate, nor a subquery reading the table a write changes. */
+    features = {
+        ...SQLITE_FEATURES,
+        orderedJsonAggregates: false,
+        correlatedWrites: false,
+    };
 }

package/dist/type/dialect.d.ts

@@ -122,6 +122,12 @@ export interface DialectFeatures {
      * answer, not the driver's: node-`pg` streams on its own and keeps doing so.
      */
     readonly serverSideCursors: boolean;
+    /**
+     * Whether an `UPDATE` or `DELETE` can read a relation in its filter. False on MongoDB, whose filter
+     * hosts no lookup, and on Turso's engine, which cannot resolve the written table inside a subquery:
+     * such a write reads the ids of the rows it names first.
+     */
+    readonly correlatedWrites: boolean;
 }
 /** What a SQL engine can do beyond {@link DialectFeatures}, read where a statement is built. */
 export interface SqlDialectFeatures extends DialectFeatures {

package/dist/type/entity.d.ts

@@ -2,7 +2,7 @@ import type { EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js
 import type { FilterOptions, RelationQuery } from './query.js';
 import type { ColumnRef, QueryRaw, RelationAggregate } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
-import type { Except, IsMany, Json, Scalar, Type, Unpacked } from './utility.js';
+import type { Except, IsMany, Json, Scalar, Type, Unpacked, Writable } from './utility.js';
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
 export declare const idKey: unique symbol;
@@ -20,6 +20,24 @@ export type Key<E> = keyof E & string;
 export type FieldKey<E> = {
     readonly [K in keyof E]-?: [NonNullable<E[K]>] extends [Scalar | readonly Scalar[] | Json | readonly Json[]] ? K : never;
 }[Key<E>];
+/**
+ * Whether `A` and `B` are the same type, `readonly` included - which no conditional sees, since
+ * assignability ignores the modifier. Two identical generic signatures compare equal only when their
+ * deferred bodies do.
+ */
+type IfEquals<A, B, Yes, No> = (<T>() => T extends A ? 1 : 2) extends <T>() => (T extends B ? 1 : 2) ? Yes : No;
+/**
+ * The fields a caller writes: every one the class does not declare `readonly`. A field the database
+ * writes - a relation aggregate, a stored generated column, a trigger-kept stamp - is `readonly`, and
+ * its value never reaches the database, so a write payload leaves it out rather than dropping it.
+ */
+export type WritableKey<E> = {
+    readonly [K in FieldKey<E>]-?: IfEquals<Pick<E, K>, Writable<Pick<E, K>>, K, never>;
+}[FieldKey<E>];
+/** A whole-record write as a caller supplies one: {@link EntityData} without the fields it cannot write. */
+export type EntityWrite<E> = EntityData<E, WritableKey<E>>;
+/** A partial write as a caller supplies one: {@link UpdatePayload} without them. */
+export type UpdateWrite<E, Raw = QueryRaw> = UpdatePayload<E, Raw, WritableKey<E>>;
 /** The relation names of an entity: every key but its fields and its methods, so the two sets cannot drift. */
 export type RelationKey<E> = Exclude<Key<E>, FieldKey<E> | MethodKey<E>>;
 /**
@@ -267,10 +285,21 @@ export type TsTypeOf<T> = T extends StringConstructor ? string : T extends Numbe
  */
 export type FieldOptionsFor<V, E = unknown> = (FieldOptions<NonNullable<V>, E> & {
     readonly type: TypeFor<V>;
+    readonly isId: true;
 }) | (FieldOptions<NonNullable<V>, E> & {
+    readonly type: TypeFor<V>;
+} & DeclaresNotNull<V>) | (FieldOptions<NonNullable<V>, E> & {
     readonly references: EntityGetter;
     readonly type?: TypeFor<V>;
-}) | AggregateOptionsFor<V, E>;
+} & DeclaresNotNull<V>) | AggregateOptionsFor<V, E>;
+/**
+ * A column holds `null` unless `nullable: false` says otherwise, and a read hydrates one, so a property
+ * that does not admit it says so here. The decorators state the same rule the other way round, against
+ * the property they are applied to; a key needs neither, being NOT NULL on every engine.
+ */
+type DeclaresNotNull<V> = null extends V ? unknown : {
+    readonly nullable: false;
+};
 /**
  * A field a relation aggregate computes: the aggregate types it, so it declares no `type`, and only the
  * two a row change turns into a delta - `count` and `sum` - may be `stored`.

package/dist/type/migration.d.ts

@@ -9,6 +9,13 @@ import type { EntityMeta, EntityWhereMeta, FieldOptions, IndexColumnSchema, Logg
  */
 export interface MigrationDefinition<Q extends Querier = SqlQuerier> {
     readonly name?: string;
+    /**
+     * `false` runs this migration outside a transaction, for a statement an engine refuses inside one -
+     * `CREATE INDEX CONCURRENTLY` on Postgres, the index a busy table needs. The cost is the rollback: a
+     * failure part-way leaves the statements before it applied and the migration unlogged. MongoDB
+     * creates collections outside any transaction already, so it changes nothing there.
+     */
+    readonly transaction?: boolean;
     up(querier: Q): Promise<void>;
     down(querier: Q): Promise<void>;
 }

package/dist/type/query.d.ts

@@ -16,6 +16,12 @@ export type QueryOptions = {
      * already-deleted rows are removed too. No effect on entities without a soft-delete field.
      */
     hardDelete?: boolean;
+    /**
+     * `updateMany`/`deleteMany` only: address every row of the table on purpose. Without it a bulk write
+     * that names none - no `$where` and no `$limit` - is refused, since a forgotten filter and the whole
+     * table look alike. The entity's own filters never count as naming one.
+     */
+    unfiltered?: boolean;
     /**
      * prefix the query with this.
      */

package/dist/type/queryAggregate.d.ts

@@ -1,7 +1,8 @@
-import type { FieldKey } from './entity.js';
+import type { FieldKey, RelationKey, RelationTarget } from './entity.js';
 import type { QueryPager, QuerySelect, QuerySortDirection } from './query.js';
+import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
-import type { RejectKeys } from './utility.js';
+import type { IsMany, RejectKeys } from './utility.js';
 /** The columns `$group` names by a literal `true`, so an uninferred `$group`, its own constraint, names none. */
 type GroupedKeys<G> = {
     [K in keyof G]: G[K] extends true ? K : never;
@@ -23,22 +24,14 @@ export type QueryAggregateOp = (typeof QUERY_AGGREGATE_OPS)[number];
  */
 export declare function isQueryAggregateOp(op: string): op is QueryAggregateOp;
 /**
- * DISTINCT-qualified aggregate ops, each mapped to the base op it applies to a field's distinct
- * values: `$countDistinct` -> `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
- * (not a nested `{ $distinct }` argument) so the op is self-documenting and greppable. `$min`/`$max`
- * are omitted: DISTINCT is a no-op for them.
+ * `$countDistinct` -> `COUNT(DISTINCT col)`. Flat (not a nested `{ $distinct }` argument) so the op is
+ * self-documenting and greppable. The other ops have no DISTINCT variant: `$sum`/`$avg` over deduplicated
+ * values is rarely what totalling or averaging means, and DISTINCT is a no-op for `$min`/`$max`.
  */
-declare const QUERY_AGGREGATE_DISTINCT_OP_BASE: {
-    readonly $countDistinct: '$count';
-    readonly $sumDistinct: '$sum';
-    readonly $avgDistinct: '$avg';
-};
-/** DISTINCT-qualified aggregate operators (the keys of {@link QUERY_AGGREGATE_DISTINCT_OP_BASE}). */
-export type QueryAggregateDistinctOp = keyof typeof QUERY_AGGREGATE_DISTINCT_OP_BASE;
+export type QueryAggregateDistinctOp = '$countDistinct';
 /**
- * Resolve an aggregate op key into its base op and whether it is DISTINCT-qualified. A flat distinct
- * op resolves to its base op with `distinct: true`; a plain op to `distinct: false`. Throws otherwise
- * (`$min`/`$max` have no distinct variant).
+ * Resolve an aggregate op key into its base op and whether it is DISTINCT-qualified: `$countDistinct`
+ * resolves to `$count` with `distinct: true`, a plain op to itself with `distinct: false`. Throws otherwise.
  */
 export declare function resolveAggregateOp(key: string): {
     op: QueryAggregateOp;
@@ -59,9 +52,8 @@ export type QueryFieldRef<E, F extends keyof E = FieldKey<E>> = ExactlyOne<Requi
 /** The argument of an aggregate function: a field, or `'*'` (only meaningful for `COUNT(*)`). */
 export type QueryAggregateArg<E> = QueryFieldRef<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.
+ * Fields `SUM`/`AVG` can total. Restricted to numeric columns because totalling a text or date one 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;
@@ -74,8 +66,12 @@ type AggregateOp = QueryAggregateOp | QueryAggregateDistinctOp;
  * where `Extract` would quietly drop the renamed member and leave the subset wrong but valid.
  */
 type OpsOf<K extends AggregateOp> = K;
+/** Ops that add a column up, which keeps the column's own type: a `bigint` column totals to a `bigint`. */
+type SummingOp = OpsOf<'$sum'>;
+/** Ops that mean a column, which the engine floats, so the result is a `number` however wide the column. */
+type AveragingOp = OpsOf<'$avg'>;
 /** Ops that total a column, so their argument has to be numeric. */
-type TotallingOp = OpsOf<'$sum' | '$avg' | '$sumDistinct' | '$avgDistinct'>;
+type TotallingOp = SummingOp | AveragingOp;
 /**
  * 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.
@@ -83,19 +79,60 @@ type TotallingOp = OpsOf<'$sum' | '$avg' | '$sumDistinct' | '$avgDistinct'>;
 type QueryAggregateArgMap<E> = Record<'$count', QueryAggregateArg<E>> & Record<TotallingOp, QueryFieldRef<E, NumericFieldKey<E>>> & Record<Exclude<AggregateOp, '$count' | TotallingOp>, QueryFieldRef<E>>;
 /**
  * An aggregate over one field, exactly one op per entry: `{ $sum: { amount: true } }` is `SUM("amount")`,
- * `{ $countDistinct: { id: true } }` is `COUNT(DISTINCT "id")`, and only `$count` takes `'*'`.
+ * `{ $countDistinct: { id: true } }` is `COUNT(DISTINCT "id")`, and only `$count` takes `'*'`. Its own
+ * `$where` narrows the rows it reads to those matching, over the entity's own fields.
  */
-export type QueryAggregateFn<E> = ExactlyOne<QueryAggregateArgMap<E>>;
-/** A single-key `{ [op]: unknown }` shape for each op in `Ops`, matched to infer that op's result. */
-type FnWithOp<Ops extends string> = {
+export type QueryAggregateFn<E> = ExactlyOne<QueryAggregateArgMap<E>> & {
+    readonly $where?: QueryAggregateWhere<E>;
+};
+/** What an aggregate's own `$where` reads: the entity's fields, since a relation there is a subquery inside it. */
+type QueryAggregateWhere<E> = QueryWhere<E, QueryRaw, FieldKey<E>>;
+/** An aggregate's `$where` naming a key it does not have, refused: a captured `$select` skips the excess-property check. */
+type AggregateWhereKeys<E, Fn> = Fn extends {
+    readonly $where: infer W;
+} ? {
+    readonly $where: RejectKeys<Exclude<keyof W, keyof QueryAggregateWhere<E>>>;
+} : unknown;
+/** A single-key `{ [op]: Arg }` shape for each op in `Ops`, matched to infer that op's result or its argument. */
+type FnWithOp<Ops extends string, Arg = unknown> = {
     [K in Ops]: {
-        readonly [P in K]: unknown;
+        readonly [P in K]: Arg;
     };
 }[Ops];
 /** Ops that count rows. Alone among the ops they answer `0`, never NULL, over an empty group. */
 type CountingOp = OpsOf<'$count' | '$countDistinct'>;
-/** The columns to group by, `{ status: true }`, typed against the entity like `$select`. */
-export type QueryGroupMap<E> = Readonly<QuerySelect<E, FieldKey<E>, true>>;
+/** Ops that read back as the column they aggregate, rather than widening or floating it. */
+type ColumnTypedOp = SummingOp | OpsOf<'$min' | '$max'>;
+/**
+ * A field a group key reads, by the path to it: `{ orderId: true }`, or through a to-one relation,
+ * `{ transaction: { orderId: true } }`. A to-many is `never`, since joining one multiplies the rows.
+ */
+export type QueryGroupRef<E, K extends keyof E = FieldKey<E> | RelationKey<E>> = ExactlyOne<Required<{
+    [P in K]: P extends RelationKey<E> ? IsMany<E[P]> extends true ? never : QueryGroupRef<RelationTarget<E[P]>> : true;
+}>>;
+/** The columns to group by: a field switched on, `{ status: true }`, or an alias for a field a path reads. */
+export type QueryGroupMap<E> = {
+    readonly [key: string]: true | QueryGroupRef<E>;
+};
+/**
+ * A captured `$group` against its schema: a field key takes `true` and keeps its link, any other key is an
+ * alias for a path. A key switched on that is no field is refused by name, which the intersection alone lets by.
+ */
+type QueryGroupSchema<E, G> = Readonly<QuerySelect<E, FieldKey<E>, true>> & {
+    readonly [K in Exclude<NamedKeys<G>, FieldKey<E>>]: QueryGroupRef<E>;
+} & RejectKeys<Exclude<GroupedKeys<G>, FieldKey<E>>>;
+/**
+ * The value a path reads: the field's own type, or through a relation, `null` where the row points nowhere.
+ * `any` answers `unknown`: TypeScript checks a deferred type by instantiating it with `any`, which would
+ * walk every relation of the entity on every aggregate call, quadrupling what one costs to check.
+ */
+type GroupRefValue<E, Ref> = 0 extends 1 & Ref ? unknown : {
+    [K in keyof Ref & keyof E]: Ref[K] extends true ? E[K] : NonNullable<GroupRefLeaf<RelationTarget<E[K]>, Ref[K]>> | null;
+}[keyof Ref & keyof E];
+/** The field at the end of a path, whose type {@link GroupRefValue} widens with `null`; `any` as it does. */
+type GroupRefLeaf<E, Ref> = 0 extends 1 & Ref ? unknown : {
+    [K in keyof Ref & keyof E]: Ref[K] extends true ? E[K] : GroupRefLeaf<RelationTarget<E[K]>, Ref[K]>;
+}[keyof Ref & keyof E];
 /** Computed columns by the alias each is read back under: `{ count: { $count: '*' }, avgAge: { $avg: { age: true } } }`. */
 export type QueryAggMap<E> = {
     readonly [alias: string]: QueryAggregateFn<E>;
@@ -103,14 +140,11 @@ 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;
 /**
- * A computed column's type: a count is a `number`; every other aggregate is `null` over no rows, a
- * total a `number` (exact to 2^53, `raw` beyond) and `$min`/`$max` the field's own type.
+ * A computed column's type: a count is a `number`; every other aggregate is `null` over no rows, a mean
+ * a `number` whatever it read, and a total, a `$min` or a `$max` the column's own type - so a `bigint`
+ * column totals to a `bigint`, which is what the driver decodes rather than rounding through a float.
  */
-type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number : Fn extends FnWithOp<TotallingOp> ? number | null : Fn extends {
-    readonly $min: infer F;
-} | {
-    readonly $max: infer F;
-} ? FieldValueType<E, keyof F> | null : unknown;
+type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number : Fn extends FnWithOp<AveragingOp> ? number | null : Fn extends FnWithOp<ColumnTypedOp, infer F> ? FieldValueType<E, keyof F> | null : unknown;
 /**
  * Flattens an intersection into a single object literal for readable editor hovers.
  * @internal
@@ -118,8 +152,10 @@ type QueryAggregateFnResult<E, Fn> = Fn extends FnWithOp<CountingOp> ? number :
 type Simplify<T> = {
     [K in keyof T]: T[K];
 } & {};
-/** An aggregate's row: each grouped column with its entity type, each computed one with its aggregate's. */
+/** An aggregate's row: each grouped column with its entity type, each alias with its path's, each computed one with its aggregate's. */
 export type QueryAggregateResult<E, G, A> = Simplify<Pick<E, GroupedKeys<G> & FieldKey<E>> & {
+    -readonly [K in Exclude<NamedKeys<G>, FieldKey<E>>]: GroupRefValue<E, G[K]>;
+} & {
     -readonly [K in keyof A]: QueryAggregateFnResult<E, A[K]>;
 }>;
 /** A `HAVING` as the dialects read it, erased; {@link QueryAggregate.$having} is where it is typed. `{ count: { $gt: 5 } }` */
@@ -136,19 +172,18 @@ export type QueryAggregate<E, G extends QueryGroupMap<E> = QueryGroupMap<E>, A e
      */
     readonly $where?: QueryWhere<E>;
     /**
-     * Columns to group by - `{ status: true }`, typed against the entity like `$select`. A computed
-     * aggregate wrongly placed here (it belongs in `$select`) is rejected via {@link RejectKeys}, since
-     * `$group` is captured as a generic and a bare generic skips excess-property checking. The captured
-     * map meets its schema, {@link QueryGroupMap}, so each key keeps its link to the entity property.
+     * Columns to group by: `{ status: true }`, or an alias for a to-one relation's field by the path to
+     * it, `{ orderId: { transaction: { orderId: true } } }`. The captured map meets its schema, so a field
+     * key keeps its link to the entity property, and a typo matches neither form.
      */
-    readonly $group?: G & QueryGroupMap<E> & RejectKeys<Exclude<keyof G, FieldKey<E>>>;
+    readonly $group?: G & QueryGroupSchema<E, G>;
     /**
      * The computed columns by alias, the captured map meeting its schema so field keys stay linked. An alias
      * repeating a `$group` column is refused, since both would come back under one name.
      */
     readonly $select?: A & {
-        readonly [K in keyof A]: QueryAggregateFn<E>;
-    } & RejectKeys<NamedKeys<A> & GroupedKeys<G>>;
+        readonly [K in keyof A]: QueryAggregateFn<E> & AggregateWhereKeys<E, A[K]>;
+    } & RejectKeys<NamedKeys<A> & NamedKeys<G>>;
     /** Filtering after grouping, by a result column, each value typed as that column is. */
     readonly $having?: {
         readonly [K in keyof QueryAggregateResult<E, G, A>]?: QueryWhereFieldValue<QueryAggregateResult<E, G, A>[K]>;

package/dist/type/queryAggregate.js

@@ -7,29 +7,12 @@ export function isQueryAggregateOp(op) {
     return QUERY_AGGREGATE_OPS.includes(op);
 }
 /**
- * DISTINCT-qualified aggregate ops, each mapped to the base op it applies to a field's distinct
- * values: `$countDistinct` -> `COUNT(DISTINCT col)`, and likewise `$sumDistinct`/`$avgDistinct`. Flat
- * (not a nested `{ $distinct }` argument) so the op is self-documenting and greppable. `$min`/`$max`
- * are omitted: DISTINCT is a no-op for them.
- */
-const QUERY_AGGREGATE_DISTINCT_OP_BASE = {
-    $countDistinct: '$count',
-    $sumDistinct: '$sum',
-    $avgDistinct: '$avg',
-};
-/** Whether `key` is a DISTINCT-qualified aggregate operator (narrows for a cast-free base lookup). */
-function isQueryAggregateDistinctOp(key) {
-    // `Object.hasOwn`, not `key in`: the latter matches inherited members like `toString`.
-    return Object.hasOwn(QUERY_AGGREGATE_DISTINCT_OP_BASE, key);
-}
-/**
- * Resolve an aggregate op key into its base op and whether it is DISTINCT-qualified. A flat distinct
- * op resolves to its base op with `distinct: true`; a plain op to `distinct: false`. Throws otherwise
- * (`$min`/`$max` have no distinct variant).
+ * Resolve an aggregate op key into its base op and whether it is DISTINCT-qualified: `$countDistinct`
+ * resolves to `$count` with `distinct: true`, a plain op to itself with `distinct: false`. Throws otherwise.
  */
 export function resolveAggregateOp(key) {
-    if (isQueryAggregateDistinctOp(key)) {
-        return { op: QUERY_AGGREGATE_DISTINCT_OP_BASE[key], distinct: true };
+    if (key === '$countDistinct') {
+        return { op: '$count', distinct: true };
     }
     if (isQueryAggregateOp(key)) {
         return { op: key, distinct: false };