uql-orm 0.47.0 → 0.48.0

package/dist/querier/abstractQuerier.js

@@ -1,5 +1,5 @@
-import { assertSoleId, getMeta, idOf, soleIdOf } from '../entity/index.js';
-import { asSelectMap, augmentWhere, childrenOf, clone, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, joinedRowKey, LoggerWrapper, isBoundedPerParent, parentJoins, parentRowKey, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, runHooks, someKey, targetKeyColumns, withoutSoftDeleteFilter, } from '../util/index.js';
+import { assertSoleId, getMeta, idOf, namesKey, soleIdOf } from '../entity/index.js';
+import { asSelectMap, augmentWhere, childrenOf, clone, dataKeyed, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, keyColumns, LoggerWrapper, isBoundedPerParent, parentJoins, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
 import { fillRelationCounts, withIdForCounts } from './relationCount.js';
 /**
@@ -168,20 +168,14 @@ export class AbstractQuerier {
         return id;
     }
     async insertMany(entity, payload) {
-        await this.emitHook(entity, 'beforeInsert', payload);
-        const ids = await this.internalInsertMany(entity, payload);
-        await this.emitHook(entity, 'afterInsert', payload);
-        return ids;
+        return this.hooked(entity, 'Insert', payload, () => this.internalInsertMany(entity, payload));
     }
     async updateOneById(entity, id, payload, opts) {
         assertIdValue(entity, id);
         return this.updateMany(entity, { $where: id }, payload, opts);
     }
     async updateMany(entity, q, payload, opts) {
-        await this.emitHook(entity, 'beforeUpdate', [payload]);
-        const changes = await this.internalUpdateMany(entity, q, payload, opts);
-        await this.emitHook(entity, 'afterUpdate', [payload]);
-        return changes;
+        return this.hooked(entity, 'Update', [payload], () => this.internalUpdateMany(entity, q, payload, opts));
     }
     async restoreOneById(entity, id) {
         assertIdValue(entity, id);
@@ -197,6 +191,18 @@ export class AbstractQuerier {
             filters: { softDelete: false },
         });
     }
+    /**
+     * `beforeUpsert`/`afterUpsert` rather than the insert's or the update's pair: the database decides
+     * which branch each row takes as the statement runs, so neither of those could be fired honestly -
+     * but the upsert itself is a fact known before and after, and a row written with no hook at all
+     * was how an `@Id({ onInsert })` or an audit trail silently skipped this path.
+     */
+    async upsertOne(entity, conflictPaths, payload) {
+        return this.hooked(entity, 'Upsert', [payload], () => this.internalUpsertOne(entity, conflictPaths, payload));
+    }
+    async upsertMany(entity, conflictPaths, payload) {
+        return this.hooked(entity, 'Upsert', payload, () => this.internalUpsertMany(entity, conflictPaths, payload));
+    }
     async deleteOneById(entity, id, opts) {
         assertIdValue(entity, id);
         return this.deleteMany(entity, { $where: id }, opts);
@@ -240,38 +246,65 @@ export class AbstractQuerier {
         const [id] = await this.saveMany(entity, [payload]);
         return id;
     }
+    /**
+     * Insert or update, as the name has always promised - and now as one statement per kind rather
+     * than a guess.
+     *
+     * Whether a row names its key decides which statement it takes, never whether the row exists: an
+     * id the caller invented is not proof of anything, and a stale one used to issue an `UPDATE` that
+     * matched nothing and reported success. A named row upserts on its own key, so it is written
+     * either way and no read can go stale between deciding and writing. An unnamed one inserts, and
+     * the database assigns the key.
+     *
+     * A composite key is always supplied by the caller, so it always takes the upsert branch - which
+     * is why nothing here special-cases one, and why this is the method that stopped refusing them.
+     *
+     * The hooks follow the statement: a named row fires `beforeUpsert`/`afterUpsert`, never the
+     * update pair, because the database picks the branch as the statement runs.
+     */
     async saveMany(entity, payload) {
         const meta = getMeta(entity);
+        // Indexes, not rows: the result is reported in payload order so it can be zipped with what was
+        // passed, which concatenating the branches did not do.
         const toInsert = [];
-        const toUpdate = [];
-        const existingIds = [];
-        // Save reads an id as proof the row exists, and inserts the rest. A composite key is supplied by
-        // the caller on every row, insert included, so that proof does not exist for one: telling the two
-        // apart takes a read, which is `upsertMany`'s job and not this one's.
-        const idKey = soleIdOf(meta, 'saving a row');
-        for (const it of payload) {
-            const id = it[idKey];
-            if (!id) {
-                toInsert.push(it);
+        const toUpsert = [];
+        const ids = new Array(payload.length);
+        /** Whether the row carries anything its primary key does not - something to write. */
+        const writesMoreThanItsKey = (row) => someKey(row, (key) => !meta.ids.some((idKey) => idKey === key));
+        for (let index = 0; index < payload.length; index++) {
+            const it = payload[index];
+            if (!namesKey(meta, it)) {
+                toInsert.push(index);
             }
-            else if (!someKey(it, (key) => key !== idKey)) {
-                existingIds.push(id);
+            else if (writesMoreThanItsKey(it)) {
+                toUpsert.push(index);
             }
             else {
-                toUpdate.push(it);
+                // A row that names its key and carries nothing else is a *reference*, not a write - the
+                // shape a to-many uses to link rows it did not author. Upserting it would stamp `onUpdate`
+                // fields on a row the caller never asked to change, and create one that was meant to exist.
+                ids[index] = idOf(meta, it);
             }
         }
-        const [insertedIds, updatedIds] = await Promise.all([
-            toInsert.length ? this.insertMany(entity, toInsert) : [],
-            Promise.all(toUpdate.map(async (it) => {
-                const id = it[idKey];
-                const data = { ...it };
-                delete data[idKey];
-                await this.updateOneById(entity, id, data);
-                return id;
-            })),
-        ]);
-        return [...existingIds, ...insertedIds, ...updatedIds];
+        const write = async () => {
+            if (toInsert.length) {
+                const inserted = await this.insertMany(entity, toInsert.map((index) => payload[index]));
+                toInsert.forEach((index, position) => {
+                    ids[index] = inserted[position];
+                });
+            }
+            if (toUpsert.length) {
+                const conflictPaths = Object.fromEntries(meta.ids.map((key) => [key, true]));
+                await this.upsertMany(entity, conflictPaths, toUpsert.map((index) => payload[index]));
+                for (const index of toUpsert) {
+                    ids[index] = idOf(meta, payload[index]);
+                }
+            }
+        };
+        // Only a batch carrying both kinds is more than one statement; `transaction` is re-entrant, so
+        // this is free inside a caller's own.
+        await (toInsert.length && toUpsert.length ? this.transaction(write) : write());
+        return ids;
     }
     async fillToManyRelations(entity, payload, populate) {
         if (!payload.length) {
@@ -377,17 +410,19 @@ export class AbstractQuerier {
         return founds;
     }
     putChildrenInParents(parents, children, joins, relKey) {
-        const childrenByParentId = {};
+        const childrenByParentId = dataKeyed();
+        // Every joined column, so two children agreeing on one column of a composite key are not
+        // gathered under the same parent. Both column lists are read once, not once per row.
+        const joinedKeys = keyColumns(joins, 'joined');
+        const parentKeys = keyColumns(joins, 'parent');
         for (const child of children) {
-            // Every joined column, so two children agreeing on one column of a composite key are not
-            // gathered under the same parent.
-            (childrenByParentId[joinedRowKey(joins, child)] ??= []).push(child);
+            (childrenByParentId[rowKey(child, joinedKeys)] ??= []).push(child);
         }
         for (const parent of parents) {
             // `[]` rather than nothing for a parent with no children: a populated to-many is a list the
             // caller asked for, so it maps and counts without a guard, and its type can say so. An
             // unpopulated one stays absent, which is what tells the two apart.
-            parent[relKey] = (childrenByParentId[parentRowKey(joins, parent)] ?? []);
+            parent[relKey] = (childrenByParentId[rowKey(parent, parentKeys)] ?? []);
         }
     }
     async insertRelations(entity, payload) {
@@ -459,7 +494,7 @@ export class AbstractQuerier {
             case 'mm':
                 return this.saveToMany(relOpts, relEntity, ids, relPayload, isUpdate);
             case '11':
-                return this.saveOneToOne(relEntity, relOpts, ids, relPayload);
+                return this.saveOneToOne(relEntity, relOpts, ids, relPayload, isUpdate);
             case 'm1':
                 if (relPayload)
                     return this.saveManyToOne(entity, relEntity, relOpts, ids, relPayload);
@@ -498,11 +533,15 @@ export class AbstractQuerier {
             await this.saveMany(relEntity, ids.flatMap((id) => relPayload.map((it) => ({ ...it, [foreignField]: id }))));
         }
     }
-    async saveOneToOne(relEntity, relOpts, ids, relPayload) {
+    async saveOneToOne(relEntity, relOpts, ids, relPayload, isUpdate) {
         const foreignField = soleParentColumn(relOpts);
-        if (relPayload === null) {
+        // The same rule a to-many follows: the parent owns its child, so an update replaces it. Without
+        // this the old row stayed behind and a one-to-one `$populate` had two rows to choose from.
+        if (relPayload === null || isUpdate) {
             await this.deleteMany(relEntity, { $where: { [foreignField]: ids } });
-            return;
+            if (relPayload === null) {
+                return;
+            }
         }
         await this.saveMany(relEntity, ids.map((id) => ({ ...relPayload, [foreignField]: id })));
     }
@@ -561,6 +600,16 @@ export class AbstractQuerier {
      * Emit a lifecycle hook event for the given entity.
      * Fires global listeners first, then entity-level hooks.
      */
+    /**
+     * Runs `write` between the event's `before`/`after` pair. Every hooked write is this shape, and
+     * each one spelled out was a place the pair could drift - `upsert` had none at all for a release.
+     */
+    async hooked(entity, event, payloads, write) {
+        await this.emitHook(entity, `before${event}`, payloads);
+        const result = await write();
+        await this.emitHook(entity, `after${event}`, payloads);
+        return result;
+    }
     async emitHook(entity, event, payloads) {
         if (!this.hasHook(entity, event))
             return;

package/dist/querier/abstractQuerierPool.d.ts

@@ -43,8 +43,8 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     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<QueryUpdateResult>;
     upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<EntityId<E> | undefined>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(EntityId<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

@@ -123,8 +123,9 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     /** The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on. */
     private settleIds;
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
+    protected internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
+    protected internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
+    private runUpsert;
     protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     get hasOpenTransaction(): boolean;
     beginTransaction(opts?: TransactionOptions): Promise<void>;

package/dist/querier/abstractSqlQuerier.js

@@ -1,9 +1,74 @@
 import { COUNT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
 import { getMeta, idOf, soleIdOf } from '../entity/index.js';
-import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, getRelationRequestSummary, hasKeys, idOnlyQuery, isAutoIncrement, isPagedQuery, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, withoutSoftDeleteFilter, } from '../util/index.js';
+import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, insertShapeOf, getRelationRequestSummary, hasKeys, idOnlyQuery, isAutoIncrement, isPagedQuery, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { enrichError } from './queryError.js';
+/**
+ * Row indexes grouped by whether the caller supplied the key, payload order kept within each group.
+ * One group when the batch agrees on it, which is the single statement it has always been.
+ *
+ * Deliberately coarser than {@link groupByInsertShape}, and the two must not be merged: an insert's
+ * `VALUES` list takes the union of the batch's columns and fills the rest with `DEFAULT`, so the
+ * key's presence is the only thing that changes what the statement can report. Splitting an insert
+ * by full shape instead would turn a batch of optional fields into a statement per combination.
+ */
+function partitionBySuppliedId(payload, idKey) {
+    const supplied = [];
+    const generated = [];
+    for (let index = 0; index < payload.length; index++) {
+        (payload[index][idKey] === undefined ? generated : supplied).push(index);
+    }
+    return supplied.length && generated.length ? [supplied, generated] : [supplied.length ? supplied : generated];
+}
+/**
+ * Rows grouped by the columns they carry, payload order kept within each group - or `undefined` when
+ * they all carry the same ones, which is the batch as it stands and needs no grouping at all.
+ *
+ * Deliberately finer than {@link partitionBySuppliedId}: an upsert's `DO UPDATE SET` is one
+ * assignment list for the whole statement, so rows of different shapes cannot share one at all.
+ */
+function groupByInsertShape(meta, payload) {
+    const first = insertShapeOf(meta, payload[0]);
+    let index = 1;
+    while (index < payload.length && insertShapeOf(meta, payload[index]) === first) {
+        index++;
+    }
+    if (index === payload.length) {
+        return undefined;
+    }
+    const groups = new Map([[first, payload.slice(0, index)]]);
+    for (; index < payload.length; index++) {
+        const row = payload[index];
+        const shape = insertShapeOf(meta, row);
+        const group = groups.get(shape);
+        if (group) {
+            group.push(row);
+        }
+        else {
+            groups.set(shape, [row]);
+        }
+    }
+    return [...groups.values()];
+}
+/**
+ * How many rows one statement can carry within the dialect's bind budget. `DEFAULT` cells bind no
+ * parameter, so fields-per-record is a safe upper bound. Every multi-row write splits on this: D1
+ * allows 100 binds, which a couple of dozen rows reach.
+ */
+function bindBudgetChunkSize(meta, rows, maxBindValues) {
+    const fieldsPerRecord = getInsertFieldKeys(meta, rows).length || 1;
+    return Math.max(1, Math.floor(maxBindValues / fieldsPerRecord));
+}
+/** `rows` split into statement-sized slices, payload order kept. */
+function chunkByBindBudget(meta, rows, maxBindValues) {
+    const size = bindBudgetChunkSize(meta, rows, maxBindValues);
+    const chunks = [];
+    for (let start = 0; start < rows.length; start += size) {
+        chunks.push(rows.slice(start, start + size));
+    }
+    return chunks;
+}
 export class AbstractSqlQuerier extends AbstractQuerier {
     dialect;
     extra;
@@ -306,33 +371,39 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         const [idKey] = meta.ids;
         const sole = meta.ids.length === 1;
         const idField = sole ? meta.fields[idKey] : undefined;
-        // RETURNING-based IDs are exact per row. Header-derived IDs (LAST_INSERT_ID /
-        // lastInsertRowid arithmetic) are only sound when the primary key is database-generated
-        // and no record supplies an explicit ID (a mixed batch shifts the positional mapping and
-        // MySQL stops guaranteeing consecutive values); otherwise generated IDs stay `undefined`.
-        const idsReliable = sole &&
-            (this.dialect.insertIdSource === 'returning' ||
-                (!!idField && isAutoIncrement(idField, true) && payload.every((it) => it[idKey] === undefined)));
-        // Inferring multiple ids from the single header id (MySQL) assumes a known stride; a clustered
-        // server may set `auto_increment_increment` > 1, so probe it (once, cached) before inferring.
-        if (idsReliable && payload.length > 1 && this.dialect.insertIdSource === 'firstId') {
-            this.#insertIdIncrement ??= await this.loadInsertIdIncrement();
-        }
-        // `DEFAULT` cells bind no parameter, so fields-per-record is a safe upper bound per row.
-        const fieldsPerRecord = getInsertFieldKeys(meta, payload).length || 1;
-        const chunkSize = Math.max(1, Math.floor(this.dialect.maxBindValues / fieldsPerRecord));
-        const payloadIds = [];
-        for (let start = 0; start < payload.length; start += chunkSize) {
-            const chunk = payload.slice(start, start + chunkSize);
-            const ctx = this.dialect.createContext();
-            this.dialect.insert(ctx, entity, chunk);
-            const { ids = [] } = await this.run(ctx.sql, ctx.values);
-            chunk.forEach((it, index) => {
-                if (idsReliable) {
-                    it[idKey] ??= ids[index];
-                }
-                payloadIds.push(sole ? it[idKey] : undefined);
-            });
+        const generatedKey = !!idField && isAutoIncrement(idField, true);
+        const payloadIds = new Array(payload.length);
+        for (const group of partitionBySuppliedId(payload, idKey)) {
+            // Per group, not per batch: the two carry different columns - one names the key, one does not -
+            // so a budget taken over their union would under-fill the statement that is missing one.
+            const chunkSize = bindBudgetChunkSize(meta, group.map((index) => payload[index]), this.dialect.maxBindValues);
+            // RETURNING-based ids are exact per row. Header-derived ones (LAST_INSERT_ID / lastInsertRowid
+            // arithmetic) are only sound when the key is database-generated and every row *in this
+            // statement* left it to the database. That is a property of the statement, not of the batch:
+            // asking it of the whole batch meant one supplied id made every id `undefined`, which a
+            // cascade then wrote into a child as a null foreign key. Splitting on that one axis costs at
+            // most one extra statement and keeps each of them inferable.
+            const idsReliable = sole &&
+                (this.dialect.insertIdSource === 'returning' ||
+                    (generatedKey && group.every((index) => payload[index][idKey] === undefined)));
+            // Inferring multiple ids from the single header id (MySQL) assumes a known stride; a clustered
+            // server may set `auto_increment_increment` > 1, so probe it (once, cached) before inferring.
+            if (idsReliable && group.length > 1 && this.dialect.insertIdSource === 'firstId') {
+                this.#insertIdIncrement ??= await this.loadInsertIdIncrement();
+            }
+            for (let start = 0; start < group.length; start += chunkSize) {
+                const indexes = group.slice(start, start + chunkSize);
+                const ctx = this.dialect.createContext();
+                this.dialect.insert(ctx, entity, indexes.map((index) => payload[index]));
+                const { ids = [] } = await this.run(ctx.sql, ctx.values);
+                indexes.forEach((index, position) => {
+                    const it = payload[index];
+                    if (idsReliable) {
+                        it[idKey] ??= ids[position];
+                    }
+                    payloadIds[index] = sole ? it[idKey] : undefined;
+                });
+            }
         }
         await this.insertRelations(entity, payload);
         return payloadIds;
@@ -363,14 +434,44 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         const founds = await this.all(ctx.sql, ctx.values);
         return founds.map((found) => idOf(meta, found));
     }
-    async upsertOne(entity, conflictPaths, payload) {
-        return this.upsertMany(entity, conflictPaths, [payload]);
+    async internalUpsertOne(entity, conflictPaths, payload) {
+        return this.internalUpsertMany(entity, conflictPaths, [payload]);
     }
-    async upsertMany(entity, conflictPaths, payload) {
+    async internalUpsertMany(entity, conflictPaths, payload) {
         if (!payload?.length) {
             return { changes: 0 };
         }
         payload = clone(payload);
+        const meta = getMeta(entity);
+        // One statement per shape, each split again to stay inside the bind budget. Grouping first is
+        // what makes the budget arithmetic right: every row of a group carries the same columns, so the
+        // `DO UPDATE SET` resolves to non-binding `EXCLUDED` references rather than inlined values.
+        const groups = groupByInsertShape(meta, payload);
+        const statements = (groups ?? [payload]).flatMap((group) => chunkByBindBudget(meta, group, this.dialect.maxBindValues));
+        if (statements.length === 1) {
+            return this.runUpsert(entity, conflictPaths, payload);
+        }
+        // `ON CONFLICT DO UPDATE SET` carries one assignment list for the whole statement, so rows of
+        // different shapes cannot share one. Neither obvious single-statement form works: taking the
+        // union writes the omitting row's `DEFAULT` (null) over a column it never mentioned, and
+        // sampling one row drops every column that row happens to lack. One statement per shape is the
+        // only form that writes exactly what each row asked for. Transactional because it is now more
+        // than one statement; `transaction` is re-entrant, so this is free inside a caller's own.
+        return this.transaction(async () => {
+            let changes = 0;
+            const ids = [];
+            for (const statement of statements) {
+                const result = await this.runUpsert(entity, conflictPaths, statement);
+                changes += result.changes ?? 0;
+                if (result.ids) {
+                    ids.push(...result.ids);
+                }
+            }
+            // No `created`/`firstId`: both speak for a single statement, and there were several.
+            return ids.length ? { changes, ids } : { changes };
+        });
+    }
+    async runUpsert(entity, conflictPaths, payload) {
         const ctx = this.dialect.createContext();
         this.dialect.upsert(ctx, entity, conflictPaths, payload);
         const result = await this.run(ctx.sql, ctx.values);

package/dist/querier/relationCount.js

@@ -1,7 +1,7 @@
 import { COUNT_ALIAS } from '../dialect/aliases.js';
 import { getMeta, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
-import { asSelectMap, getKeys, joinedColumns, joinedRowKey, parentJoins, parentRowKey, parentsIn, targetKeyColumns, } from '../util/index.js';
+import { asSelectMap, dataKeyed, getKeys, joinedColumns, keyColumns, parentJoins, parentsIn, rowKey, targetKeyColumns, } from '../util/index.js';
 /**
  * A `$count` groups its tallies by the parent's id, so the id has to outlive the projection - the
  * same reason populating a relation keeps it. A whitelisting `$select` gains the key and an
@@ -50,7 +50,7 @@ export async function fillRelationCounts(querier, entity, payload, count) {
         return;
     }
     const meta = getMeta(entity);
-    // The tallies come back keyed by the columns *this relation* joins from, so its `joins` are kept
+    // The tallies come back keyed by the columns *this relation* joins from, so those columns are kept
     // beside them: reading the parent through `meta.ids` instead matches only where the two coincide,
     // which is a to-many and nothing else.
     const counted = new Map();
@@ -62,14 +62,19 @@ export async function fillRelationCounts(querier, entity, payload, count) {
         }
         const where = typeof value === 'object' ? value.$where : undefined;
         const joins = parentJoins(relOpts, meta.ids.length);
-        counted.set(relKey, { joins, byParent: await countPerParent(querier, relOpts, joins, payload, where) });
+        counted.set(relKey, {
+            parentKeys: keyColumns(joins, 'parent'),
+            byParent: await countPerParent(querier, relOpts, joins, payload, where),
+        });
     }
     for (const parent of payload) {
+        // A plain object, unlike the tallies below: this one is keyed by relation names the entity
+        // declares, not by data, and it is handed to the caller - who would meet a null prototype.
         const row = {};
-        for (const [relKey, { joins, byParent }] of counted) {
+        for (const [relKey, { parentKeys, byParent }] of counted) {
             // A parent the grouped result has no row for matched nothing, which is a zero rather than a
             // gap: `_count` names what the caller asked to count, so every key it asked for is present.
-            row[relKey] = byParent[parentRowKey(joins, parent)] ?? 0;
+            row[relKey] = byParent[rowKey(parent, parentKeys)] ?? 0;
         }
         parent[COUNT_RESULT_KEY] = row;
     }
@@ -105,11 +110,12 @@ async function groupedCount(querier, entity, joins, where) {
     const $agg = { [COUNT_ALIAS]: { $count: '*' } };
     const $group = joinedColumns(joins);
     const rows = await querier.aggregate(entity, { $group, $agg, $where: where });
-    const byParent = {};
+    const byParent = dataKeyed();
+    // Keyed by every joined column, which is how a tally finds the one parent whose whole key it
+    // matches - and how the rows an over-selecting `IN` brought back find no parent at all.
+    const joinedKeys = keyColumns(joins, 'joined');
     for (const row of rows) {
-        // Keyed by every joined column, which is how a tally finds the one parent whose whole key it
-        // matches - and how the rows an over-selecting `IN` brought back find no parent at all.
-        byParent[joinedRowKey(joins, row)] = Number(row[COUNT_ALIAS]);
+        byParent[rowKey(row, joinedKeys)] = Number(row[COUNT_ALIAS]);
     }
     return byParent;
 }

package/dist/type/entity.d.ts

@@ -570,7 +570,7 @@ export type RelationManyToManyOptions<E> = RelationOptionsThroughOwner<E> | Rela
 /**
  * Lifecycle hook event names.
  */
-export type HookEvent = 'beforeInsert' | 'afterInsert' | 'beforeUpdate' | 'afterUpdate' | 'beforeDelete' | 'afterDelete' | 'afterLoad';
+export type HookEvent = 'beforeInsert' | 'afterInsert' | 'beforeUpdate' | 'afterUpdate' | 'beforeUpsert' | 'afterUpsert' | 'beforeDelete' | 'afterDelete' | 'afterLoad';
 /**
  * A registered hook: the method name on the entity class to call.
  */

package/dist/type/queryRaw.d.ts

@@ -25,7 +25,7 @@ export type QueryRawFnOptions = {
 /**
  * A `raw` callback: write into `ctx`, or return a string or number to have it appended. Anything else
  * it returns is ignored, which is why the return type is `unknown` rather than `void | Scalar` - the
- * latter rejected `({ ctx }) => ctx.append(...)`, the form every virtual field is written in, because
+ * latter rejected `({ ctx }) => ctx.append(...)`, the form every computed field is written in, because
  * TypeScript's "returning a value where void is expected" allowance does not apply to a union.
  *
  * `Required`, and the parameter not optional, because the one place that calls it (`getRawValue`)

package/dist/type/queryWhere.d.ts

@@ -85,6 +85,16 @@ export type QueryWhereRootOperator<E> = {
  * {@link QueryWhereRootOperator} so a rename there breaks this union at compile time.
  */
 export type QueryNegateOp = keyof Pick<QueryWhereRootOperator<unknown>, '$not' | '$nor'>;
+/**
+ * The root operators that join their clauses instead of negating them, tied back to
+ * {@link QueryWhereRootOperator} on the same terms as {@link QueryNegateOp}.
+ */
+export type QueryJoinOp = keyof Pick<QueryWhereRootOperator<unknown>, '$and' | '$or'>;
+/**
+ * Every root operator whose value is a {@link QueryWhereArray} rather than a field condition: the
+ * two that join their clauses and the two that negate the join.
+ */
+export type QueryGroupOp = QueryJoinOp | QueryNegateOp;
 /**
  * Comparison operators accepted by `$size` for range queries: {@link QueryHavingOp} plus `$between`.
  * Strips `null` from picked operators since array size is always numeric.
@@ -320,7 +330,7 @@ type IsUntypedColumn<T> = [Scalar] extends [NonNullable<T>] ? true : false;
  */
 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.
+ * query filter array - the value every {@link QueryGroupOp} takes.
  */
 export type QueryWhereArray<E> = (QueryWhereMap<E> | QueryRaw)[];
 /**

package/dist/type/universalQuerier.d.ts

@@ -153,14 +153,14 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
      * @param payload the data to be persisted
      * @return the ID
      */
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<IdValue<E> | undefined>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<EntityId<E> | undefined>;
     /**
      * 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: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(EntityId<E> | undefined)[]>;
     /**
      * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
      * entity has no soft-delete field.

package/dist/util/dialect.util.d.ts

@@ -1,6 +1,13 @@
 import { type CascadeType, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryVectorSearch, type QueryWhere, type QueryWhereMap, type RelationKey } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E>, callbackKey: CallbackKey): FieldKey<E>[];
+/** Appends `record`'s not-yet-`seen` insertable keys (real, caller-written, defined value) to `keys`. */
+/**
+ * The insertable keys `record` itself carries, as a string, for grouping rows by the statement they
+ * can share. Only the row's own keys: the `onInsert` columns {@link getInsertFieldKeys} appends are a
+ * property of the entity, identical for every row, so they cannot tell two rows apart.
+ */
+export declare function insertShapeOf<E>(meta: EntityMeta<E>, record: EntityData<E>): string;
 /**
  * Resolves the columns of an INSERT statement: the union of the persistable fields provided by
  * any record (in first-seen order), plus every `onInsert` field. Records missing one of these

package/dist/util/dialect.util.js

@@ -16,6 +16,20 @@ function isInsertableField(meta, record, key) {
     return !!field && !isDatabaseWritten(field) && record[key] !== undefined;
 }
 /** Appends `record`'s not-yet-`seen` insertable keys (real, caller-written, defined value) to `keys`. */
+/**
+ * The insertable keys `record` itself carries, as a string, for grouping rows by the statement they
+ * can share. Only the row's own keys: the `onInsert` columns {@link getInsertFieldKeys} appends are a
+ * property of the entity, identical for every row, so they cannot tell two rows apart.
+ */
+export function insertShapeOf(meta, record) {
+    let shape = '';
+    for (const key of getKeys(record)) {
+        if (isInsertableField(meta, record, key)) {
+            shape += `${key},`;
+        }
+    }
+    return shape;
+}
 function addInsertFieldKeys(meta, record, seen, keys) {
     for (const key of getKeys(record)) {
         if (!seen.has(key) && isInsertableField(meta, record, key)) {

package/dist/util/fieldOption.util.d.ts

@@ -34,7 +34,7 @@ declare const FIELD_OPTION_FAMILY: {
     readonly comment: '*';
 };
 /**
- * The only options a `virtual` field reaches: it is skipped in DDL and dropped from every insert and
+ * The only options an inlined computed field reaches: it is skipped in DDL and dropped from every insert and
  * update, so the whole persistence half of the options above is dead on one. Stated as what survives
  * rather than on each option that dies, because it is one fact rather than nineteen - and because an
  * option added without a thought then lands on the safe side of it.

package/dist/util/fieldOption.util.js

@@ -34,7 +34,7 @@ const FIELD_OPTION_FAMILY = {
     comment: '*',
 };
 /**
- * The only options a `virtual` field reaches: it is skipped in DDL and dropped from every insert and
+ * The only options an inlined computed field reaches: it is skipped in DDL and dropped from every insert and
  * update, so the whole persistence half of the options above is dead on one. Stated as what survives
  * rather than on each option that dies, because it is one fact rather than nineteen - and because an
  * option added without a thought then lands on the safe side of it.