uql-orm 0.47.1 → 0.48.0

package/dist/mongo/mongodbQuerier.js

@@ -81,7 +81,11 @@ export class MongodbQuerier extends AbstractQuerier {
      */
     async internalFindManyPerParent(entity, q, { joins, parents }) {
         const queries = parents.map((parent) => queryChildrenOf(q, joins, parent));
-        // A vector sort needs a pipeline of its own shape, which only `internalFindMany` builds.
+        // A vector sort is not a degraded fallback here, it is the only expressible form: `$vectorSearch`
+        // has to be the first stage of a pipeline, so it cannot be one of N `$unionWith` branches. Read a
+        // parent at a time it stays correct, because `buildVectorSearchStage` passes the query's `$where`
+        // - which carries this parent's key - into the search as its filter, so each parent gets its own
+        // nearest rather than a share of the collection's.
         if (this.dialect.extractVectorSort(q.$sort)) {
             return this.readEachInTurn(entity, queries);
         }
@@ -264,7 +268,7 @@ export class MongodbQuerier extends AbstractQuerier {
             const meta = getMeta(entity);
             const persistables = this.dialect.getPersistables(meta, payloads, 'onInsert');
             const { insertedIds } = await this.execute((session) => this.collection(entity).insertMany(persistables, { session }));
-            const ids = Object.values(insertedIds);
+            const ids = Object.values(insertedIds).map((id) => this.dialect.fromWireId(id));
             const idKey = soleIdOf(meta, 'insert');
             for (const [index, it] of payloads.entries()) {
                 it[idKey] = ids[index];
@@ -282,7 +286,7 @@ export class MongodbQuerier extends AbstractQuerier {
             // relation condition has nowhere to go, and MongoDB takes no page on a write, so a paged one
             // has to name the rows it picked rather than touching every match.
             const where = this.dialect.constrainsRelations(entity, qm.$where) || isPagedQuery(qm)
-                ? { _id: { $in: await this.settleIds(entity, qm, opts) } }
+                ? { _id: { $in: this.dialect.toWireId(await this.settleIds(entity, qm, opts)) } }
                 : this.dialect.where(entity, qm.$where, opts);
             // Maps JSON operators ($set/$unset/$push/$pull) onto their native MongoDB equivalents.
             const update = this.dialect.getUpdateFilter(persistable);
@@ -293,6 +297,21 @@ export class MongodbQuerier extends AbstractQuerier {
             return matchedCount;
         });
     }
+    /**
+     * `_id` is immutable, so a key the payload names can only be written on the insert branch of an
+     * upsert; in `$set` it would refuse every matched document. Everything else updates either way.
+     */
+    upsertUpdate(persistable) {
+        const { _id, ...rest } = persistable;
+        const update = {};
+        if (hasKeys(rest)) {
+            update['$set'] = rest;
+        }
+        if (_id !== undefined) {
+            update['$setOnInsert'] = { _id };
+        }
+        return update;
+    }
     buildConflictFilter(entity, conflictPaths, item) {
         const where = getKeys(conflictPaths).reduce((acc, key) => {
             acc[key] = item[key];
@@ -300,26 +319,26 @@ export class MongodbQuerier extends AbstractQuerier {
         }, {});
         return this.dialect.where(entity, where);
     }
-    async upsertOne(entity, conflictPaths, payload) {
+    async internalUpsertOne(entity, conflictPaths, payload) {
         return this.timed('upsertOne', undefined, async () => {
             payload = clone(payload);
             const meta = getMeta(entity);
             const persistable = this.dialect.getPersistable(meta, payload, 'onInsert');
             const filter = this.buildConflictFilter(entity, conflictPaths, payload);
-            const update = { $set: persistable };
+            const update = this.upsertUpdate(persistable);
             const res = await this.execute((session) => this.collection(entity).findOneAndUpdate(filter, update, {
                 upsert: true,
                 returnDocument: 'after',
                 includeResultMetadata: true,
                 session,
             }));
-            const firstId = res?.value?._id;
+            const firstId = this.dialect.fromWireId(res?.value?._id);
             // `updatedExisting` is false when a new document was inserted (upserted).
             const created = res?.lastErrorObject?.['updatedExisting'] === false;
             return { firstId, changes: firstId ? 1 : 0, created };
         });
     }
-    async upsertMany(entity, conflictPaths, payload) {
+    async internalUpsertMany(entity, conflictPaths, payload) {
         return this.timed('upsertMany', undefined, async () => {
             if (!payload?.length) {
                 return { changes: 0 };
@@ -329,7 +348,7 @@ export class MongodbQuerier extends AbstractQuerier {
             const operations = payload.map((item) => {
                 const persistable = this.dialect.getPersistable(meta, item, 'onInsert');
                 const filter = this.buildConflictFilter(entity, conflictPaths, item);
-                const update = { $set: persistable };
+                const update = this.upsertUpdate(persistable);
                 return {
                     updateOne: {
                         filter,
@@ -344,7 +363,7 @@ export class MongodbQuerier extends AbstractQuerier {
             // updated document's `_id` isn't in the response, so it's simply not represented here - same
             // "exact where knowable, absent otherwise" convention `RETURNING`-based SQL dialects use for
             // rows that hit `DO NOTHING`.
-            const ids = Object.values(res.upsertedIds);
+            const ids = Object.values(res.upsertedIds).map((id) => this.dialect.fromWireId(id));
             return { changes, ids, firstId: ids[0] };
         });
     }
@@ -366,13 +385,13 @@ export class MongodbQuerier extends AbstractQuerier {
                 // Stamp the mapped column: reads filter on it, so a `@Field({ name })` mismatch here would
                 // report a successful delete and leave the row visible.
                 const softDeleteColumn = this.dialect.resolveColumnName(meta.softDelete, field);
-                const updateResult = await this.execute((session) => this.collection(entity).updateMany({ _id: { $in: ids } }, { $set: { [softDeleteColumn]: getSoftDeleteValue(field) } }, {
+                const updateResult = await this.execute((session) => this.collection(entity).updateMany({ _id: { $in: this.dialect.toWireId(ids) } }, { $set: { [softDeleteColumn]: getSoftDeleteValue(field) } }, {
                     session,
                 }));
                 changes = updateResult.matchedCount;
             }
             else {
-                const deleteResult = await this.execute((session) => this.collection(entity).deleteMany({ _id: { $in: ids } }, { session }));
+                const deleteResult = await this.execute((session) => this.collection(entity).deleteMany({ _id: { $in: this.dialect.toWireId(ids) } }, { session }));
                 changes = deleteResult.deletedCount;
             }
             await this.deleteRelations(entity, ids, opts);

package/dist/querier/abstractQuerier.d.ts

@@ -119,8 +119,16 @@ export declare abstract class AbstractQuerier implements Querier {
     protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;
     restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
-    abstract upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
-    abstract upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
+    /**
+     * `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.
+     */
+    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 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>;
     /**
      * Delete records matching the query. Soft-deletes when the entity has a soft-delete field (unless
@@ -140,8 +148,24 @@ export declare abstract class AbstractQuerier implements Querier {
      */
     private findDoomed;
     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<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>;
+    /**
+     * 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.
+     */
+    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(EntityId<E> | undefined)[]>;
     protected fillToManyRelations<E>(entity: Type<E>, payload: E[], populate?: QueryPopulate<E>): Promise<void>;
     private fillToManyThroughRelation;
     private fillToManyOneToMany;
@@ -196,6 +220,11 @@ export declare abstract class AbstractQuerier implements Querier {
      * 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.
+     */
+    private hooked;
     private emitHook;
     /**
      * Runs `task` after everything already queued on this querier, one at a time.

package/dist/querier/abstractQuerier.js

@@ -1,4 +1,4 @@
-import { assertSoleId, getMeta, idOf, soleIdOf } from '../entity/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) {
@@ -461,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);
@@ -500,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 })));
     }
@@ -563,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/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/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.