uql-orm 0.68.1 → 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

@@ -1,6 +1,6 @@
 import type { EntityMeta, UpdatePayload } from './entity.js';
-import type { Query, QueryConflictPaths, QueryOptions, QueryPage, QuerySearch } from './query.js';
-import type { QueryAggMap, QueryAggregate, QueryGroupMap } from './queryAggregate.js';
+import type { Query, QueryConflictPaths, QueryOptions, QueryPage, QuerySearch, RelationQuery } from './query.js';
+import type { QueryAggMap, QueryAggregate, QueryAggregateOp, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
 /**
  * comparison options.
@@ -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 {
@@ -208,7 +214,34 @@ export interface SqlQueryDialect {
      * Default: '?' for MySQL/MariaDB/SQLite, '$n' for PostgreSQL.
      */
     placeholder(index: number): string;
+    /**
+     * A relation aggregate as a correlated subquery, correlated to the row under `prefix`: what a field
+     * declaring `computed: (user) => user.resources.count()` renders as, wherever a clause names it.
+     */
+    appendRelationAggregate<E>(ctx: QueryContext, entity: Type<E>, aggregate: RelationAggregateSpec, prefix: string): void;
 }
+/**
+ * The aggregates a relation reads, spelled as the query language spells them, so a `computed` field, an
+ * aggregate query and MongoDB's own `$group` all name one the same way. `$count` and `$sum` are the two
+ * a row change turns into a delta.
+ */
+export type RelationAggregateOp = QueryAggregateOp;
+/** What a relation aggregate reads: how many rows, or one of the target's columns. */
+export type RelationAggregateProjection = {
+    readonly op: '$count';
+    readonly field?: never;
+} | {
+    readonly op: Exclude<RelationAggregateOp, '$count'>;
+    readonly field: string;
+};
+/** A relation aggregate as a `computed` field holds it: what it reads, off which relation, filtered how. */
+export type RelationAggregateSpec = RelationAggregateProjection & {
+    readonly relation: string;
+    /** Which of the related rows it reads, and the page it caps them to, as the field declared them. */
+    readonly query?: RelationSubqueryQuery;
+};
+/** The rows a relation subquery reads: which ones, in what order, and the page capping them. */
+export type RelationSubqueryQuery = Pick<RelationQuery, '$where' | '$sort' | '$limit' | '$skip'>;
 /**
  * Supported SQL dialect identifiers.
  */

package/dist/type/entity.d.ts

@@ -1,8 +1,8 @@
 import type { EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js';
-import type { FilterOptions } from './query.js';
-import type { ColumnRef, QueryRaw } from './queryRaw.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,8 +20,35 @@ 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>>;
+/**
+ * To-one relations only: a parent holds many rows of a to-many, so there is no single value to order it
+ * by, and joining one in would duplicate the parent instead. Order those inside `$populate`.
+ */
+export type ToOneRelationKey<E> = {
+    [K in RelationKey<E>]: IsMany<E[K]> extends true ? never : K;
+}[RelationKey<E>];
+/** The relation names a parent holds many rows of: what a populated query fills, and what an aggregate reads. */
+export type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
 /** Whether `T` carries the `Json` brand, read off its marker key: a primitive matches `Json<infer P>` too. */
 type IsJson<T> = '__json' extends keyof T ? true : false;
 /** The payload `P` of a branded `Json<P>`, or `never` for any other type. */
@@ -201,8 +228,11 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
     /**
      * An expression the database computes, never written: spliced into each read, or with `stored` a
      * generated column, `computed: (user) => raw`${user.first} || ' ' || ${user.last}``.
+     *
+     * A relation aggregate is the other form, `computed: (user) => user.resources.count()`, read as the
+     * subquery a `$count` reads. Both resolve to SQL at registration, so everything downstream sees one.
      */
-    readonly computed?: EntitySql<E>;
+    readonly computed?: ComputedSql<E>;
     /** Whether {@link FieldOptions.computed} is a generated column rather than spliced into each read; no query changes either way. */
     readonly stored?: boolean;
     readonly updatable?: boolean;
@@ -255,10 +285,36 @@ 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>;
+} & 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`.
+ */
+type AggregateOptionsFor<V, E> = Except<FieldOptions<NonNullable<V>, E>, 'computed' | 'stored' | 'type'> & ({
+    readonly computed: AggregateReading<E, V, boolean>;
+    readonly stored?: false;
+} | {
+    readonly computed: AggregateReading<E, V, true>;
+    readonly stored: true;
 });
+/** An aggregate reading what the property holds, bivariant the way {@link EntitySql} is. */
+type AggregateReading<E, V, S extends boolean> = {
+    agg(refs: ComputedRefs<E>): RelationAggregate<null extends V ? NonNullable<V> | null : NonNullable<V>, S>;
+}['agg'];
 /** The entity a relation points at: `Company` for `company?: Company` and `companies?: Company[]` alike. */
 export type RelationTarget<V> = Extract<Unpacked<V>, object>;
 /**
@@ -360,6 +416,66 @@ export type RefMap<E, F extends keyof E = FieldKey<E>> = {
 export type EntitySql<E> = QueryRaw | {
     sql(refs: RefMap<E>): QueryRaw;
 }['sql'];
+/** The fields of `C` a `sum` or an `avg` can add up. */
+type NumericKey<C> = {
+    readonly [K in FieldKey<C>]-?: [NonNullable<C[K]>] extends [number | bigint] ? K : never;
+}[FieldKey<C>];
+/** One field of `C`, read off its refs: `(item) => item.amount`. */
+type PickRef<C, K extends keyof C> = (refs: RefMap<C>) => ColumnRef<K & string>;
+/**
+ * A relation as a `computed` field reads it, its aggregates typed against the related entity. `count`
+ * and `sum` are the two a row change turns into a delta, so they alone may be `stored`; the rest read
+ * as a subquery and are `null` where the relation holds no row.
+ */
+export type RelationRef<C> = {
+    count(q?: AggregateFilter<C>): RelationAggregate<number, true>;
+    count(q: AggregatePage<C>): RelationAggregate<number, false>;
+    sum<K extends NumericKey<C>>(pick: PickRef<C, K>, q?: AggregateFilter<C>): RelationAggregate<NonNullable<C[K]>, true>;
+    sum<K extends NumericKey<C>>(pick: PickRef<C, K>, q: AggregateTopRows<C>): RelationAggregate<NonNullable<C[K]>, false>;
+    min<K extends FieldKey<C>>(pick: PickRef<C, K>, q?: AggregateRows<C>): RelationAggregate<NonNullable<C[K]> | null, false>;
+    max<K extends FieldKey<C>>(pick: PickRef<C, K>, q?: AggregateRows<C>): RelationAggregate<NonNullable<C[K]> | null, false>;
+    avg<K extends NumericKey<C>>(pick: PickRef<C, K>, q?: AggregateRows<C>): RelationAggregate<number | null, false>;
+};
+/**
+ * What an aggregate reads of the related rows. The predicate is an {@link EntityPredicate} rather than a
+ * full `$where` so that `stored: true` changes no call site: a trigger sees one row, and can evaluate
+ * nothing that traverses a relation or opens a subquery.
+ */
+export type AggregateFilter<C> = {
+    readonly $where?: EntityPredicate<C>;
+};
+/**
+ * A tally capped to a page of the related rows, as `count` itself takes one. It needs no `$sort` and
+ * accepts none: an order picks *which* rows a page holds, never how many.
+ */
+export type AggregatePage<C> = AggregateFilter<C> & Pick<RelationQuery<C>, '$limit' | '$skip'>;
+/**
+ * The rows a value aggregate reads where it reads only some of them - "the five largest" - which only
+ * an order defines, so `$sort` and `$limit` come together. Keyed off the relation read they are, so
+ * the page an aggregate takes and the page a `$populate` takes cannot drift apart.
+ */
+export type AggregateTopRows<C> = AggregateFilter<C> & Required<Pick<RelationQuery<C>, '$sort' | '$limit'>> & Pick<RelationQuery<C>, '$skip'>;
+/** Either of those, for the aggregates that are never `stored` and so need no second signature. */
+export type AggregateRows<C> = AggregateFilter<C> | AggregateTopRows<C>;
+/** What a `computed` callback reads: the entity's fields as columns, its to-many relations as aggregates. */
+export type ComputedRefs<E, F extends keyof E = FieldKey<E>, R extends keyof E = ToManyRelationKey<E>> = RefMap<E, F> & {
+    readonly [K in R]-?: RelationRef<RelationTarget<E[K]>>;
+};
+/** A relation aggregate a definition writes, bivariant the way {@link EntitySql} is. */
+export type EntityAggregate<E> = {
+    agg(refs: ComputedRefs<E>): RelationAggregate;
+}['agg'];
+/**
+ * SQL a `computed` field writes. One callback shape for every arm, aggregate or not: overload
+ * resolution picks a contextual parameter type per arm only while they agree on one.
+ */
+export type ComputedSql<E> = QueryRaw | {
+    sql(refs: ComputedRefs<E>): QueryRaw;
+}['sql'];
+/** The value a field's options declare it holds, where an aggregate is what declares it. */
+export type AggregateValue<O> = O extends {
+    readonly computed: (...args: never[]) => RelationAggregate<infer V>;
+} ? V : never;
 /** A predicate DDL can hold: the entity's own fields, without a relation, `$text` or a sub-query. */
 export type EntityPredicate<E> = QueryWhere<E> & {
     readonly [K in RelationKey<E>]?: never;

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

@@ -1,4 +1,4 @@
-import type { FieldKey, JsonFieldPaths, RelationKey, RelationTarget, WrittenId } from './entity.js';
+import type { FieldKey, JsonFieldPaths, RelationKey, RelationTarget, ToManyRelationKey, WrittenId } from './entity.js';
 import type { QueryLock } from './queryLock.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
@@ -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.
      */
@@ -116,15 +122,6 @@ export type QuerySortDirection = -1 | 1 | 'asc' | 'desc';
  * Accepted value for a field in `$sort` - either a direction or a vector similarity search.
  */
 export type QuerySortValue = QuerySortDirection | QueryVectorSearch;
-/**
- * To-one relations only: a parent holds many rows of a to-many, so there is no single value to order
- * it by, and joining one in would duplicate the parent instead. Order those inside `$populate`.
- */
-type ToOneRelationKey<E> = {
-    [K in RelationKey<E>]: IsMany<E[K]> extends true ? never : K;
-}[RelationKey<E>];
-/** The relation names a parent holds many rows of, which a populated query fills with a list. */
-type ToManyRelationKey<E> = Exclude<RelationKey<E>, ToOneRelationKey<E>>;
 /**
  * Ordering parents by how many rows a to-many relation holds - "the ten users with the most posts".
  * The tally is computed per parent as a correlated count, never by loading the rows.