uql-orm 0.53.0 → 0.54.0

package/dist/mssql/mssqlDialect.js

@@ -64,6 +64,8 @@ export class MsSqlDialect extends MergeSqlDialect {
     maxBindValues = 2100;
     /** `OUTPUT` has no trailing form: it sits between the column list and `VALUES`. */
     returningPosition = 'after-target';
+    /** Microsoft documents no row order for a `MERGE ... OUTPUT`. */
+    upsertReturningOrdered = false;
     insertIdSource = 'returning';
     /** Holds the update key lock across the insert; without it two concurrent upserts of one key race. */
     mergeTargetHint = ' WITH (HOLDLOCK)';

package/dist/querier/abstractQuerier.d.ts

@@ -1,5 +1,6 @@
-import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
+import type { EntityData, EntityId, ExtraOptions, FieldKey, IdValue, Querier, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryPopulate, QueryProjected, QuerySearch, QueryStreamProjected, PrimaryKey, QueryUpdateResult, QueryUpsertOneResult, QueryUpsertManyResult, RawRow, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
 import { LoggerWrapper, type ParentJoin, type ParentPartition } from '../util/index.js';
+/** Base class for all database queriers. */
 export declare abstract class AbstractQuerier implements Querier {
     readonly extra?: ExtraOptions | undefined;
     /**
@@ -109,11 +110,12 @@ export declare abstract class AbstractQuerier implements Querier {
     abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
     /**
-     * A composite key is named here rather than by the statement: no column holds it, so no database
-     * reports one, but the caller wrote every column of it and the payload still carries them.
+     * 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)[]>;
-    protected abstract internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<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>;
     updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
     protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
@@ -150,20 +152,9 @@ export declare abstract class AbstractQuerier implements Querier {
     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>;
     /**
-     * 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.
+     * 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)[]>;
     protected fillToManyRelations<E>(entity: Type<E>, payload: E[], populate?: QueryPopulate<E>): Promise<void>;
@@ -217,14 +208,18 @@ export declare abstract class AbstractQuerier implements Querier {
     /** Whether anything at all - a global listener or the entity itself - handles `event`. */
     private hasHook;
     /**
-     * Emit a lifecycle hook event for the given entity.
-     * Fires global listeners first, then entity-level hooks.
+     * The ids of `rows`, read back by the columns an upsert matched them on, for a statement that could
+     * not report them in payload order. A row that no read row matches, or that two do, keeps
+     * `undefined`: a missing id is honest where a guessed one is not.
      */
+    protected idsByConflict<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, rows: EntityData<E>[]): Promise<(PrimaryKey | undefined)[]>;
     /**
-     * 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.
+     * Runs `write` between the event's `before`/`after` pair. The before hooks get the caller's rows, so
+     * what they assign is written; `write` and the after hooks get a copy, which by then carries what
+     * the write filled in - a generated key, an `onInsert` value - without it landing on the caller's.
      */
     private hooked;
+    /** Fires the global listeners first, then the entity's own hooks. */
     private emitHook;
     /**
      * Runs `task` after everything already queued on this querier, one at a time.

package/dist/querier/abstractQuerier.js

@@ -1,5 +1,5 @@
 import { assertSoleId, getMeta, idOf, namesKey, soleIdOf } from '../entity/index.js';
-import { asSelectMap, childrenOf, clone, dataKeyed, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, keyColumns, LoggerWrapper, isBoundedPerParent, parentJoins, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, childrenOf, clone, dataKeyed, fillOnFields, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isScalarId, joinedColumns, keyColumns, LoggerWrapper, isBoundedPerParent, parentJoins, queryChildrenOfAll, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
 import { fillRelationCounts, withIdForCounts } from './relationCount.js';
 /**
@@ -41,22 +41,27 @@ function soleParentColumn(relOpts) {
     return parentJoins(relOpts, 1)[0].joined;
 }
 /**
- * Base class for all database queriers.
- * It provides a standardized way to execute tasks serially to prevent race conditions on database connections.
+ * 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.
  */
+function writtenIds(meta, rows) {
+    return rows.map((row) => (namesKey(meta, row) ? idOf(meta, row) : undefined));
+}
 /**
- * The ids an upsert reports, payload-aligned so the result zips with the rows that were passed.
- *
- * A composite is named from the payload, as an insert's is: no column holds that key, so no
- * statement reports one. A sole key takes what the statement reported when it spoke for every row,
- * and otherwise falls back to the key the caller supplied - a `firstId` dialect reports nothing for
- * a batch, which is not the same as those rows having no id.
+ * Writes the key an upsert reported onto each row that named none - only the key, since an `onInsert`
+ * value was never written to a row the upsert updated. A report aligns with the rows only when it
+ * speaks for every one: a `firstId` dialect reports nothing for a batch.
  */
-function upsertIds(meta, payload, reported) {
-    return meta.ids.length === 1 && reported?.length === payload.length
-        ? reported
-        : payload.map((it) => (namesKey(meta, it) ? idOf(meta, it) : undefined));
+function adoptReportedIds(meta, rows, reported) {
+    if (meta.ids.length !== 1 || reported?.length !== rows.length) {
+        return;
+    }
+    const [idKey] = meta.ids;
+    for (let index = 0; index < rows.length; index++) {
+        rows[index][idKey] ??= reported[index];
+    }
 }
+/** Base class for all database queriers. */
 export class AbstractQuerier {
     extra;
     /**
@@ -182,15 +187,18 @@ export class AbstractQuerier {
         return id;
     }
     /**
-     * A composite key is named here rather than by the statement: no column holds it, so no database
-     * reports one, but the caller wrote every column of it and the payload still carries them.
+     * The `onInsert` values are filled here, before the write, so the after hooks and the ids read the
+     * same rows the statement wrote.
      */
     async insertMany(entity, payload) {
+        if (!payload?.length) {
+            return [];
+        }
         const meta = getMeta(entity);
-        return this.hooked(entity, 'Insert', payload, async () => {
-            const reported = await this.internalInsertMany(entity, payload);
-            // Neither branch can be shown to be `WrittenId` for an unresolved `E`; `idOf` narrows likewise.
-            return meta.ids.length === 1 ? reported : payload.map((it) => idOf(meta, it));
+        return this.hooked(entity, 'Insert', payload, async (rows) => {
+            fillOnFields(meta, rows, 'onInsert');
+            await this.internalInsertMany(entity, rows);
+            return writtenIds(meta, rows);
         });
     }
     async updateOneById(entity, id, payload, opts) {
@@ -198,7 +206,10 @@ export class AbstractQuerier {
         return this.updateMany(entity, { $where: whereIds(getMeta(entity), id) }, payload, opts);
     }
     async updateMany(entity, q, payload, opts) {
-        return this.hooked(entity, 'Update', [payload], () => this.internalUpdateMany(entity, q, payload, opts));
+        return this.hooked(entity, 'Update', [payload], ([row]) => {
+            fillOnFields(getMeta(entity), [row], 'onUpdate');
+            return this.internalUpdateMany(entity, q, row, opts);
+        });
     }
     async restoreOneById(entity, id) {
         assertIdValue(entity, id);
@@ -221,16 +232,20 @@ export class AbstractQuerier {
      * was how an `@Id({ onInsert })` or an audit trail silently skipped this path.
      */
     async upsertOne(entity, conflictPaths, payload) {
-        return this.hooked(entity, 'Upsert', [payload], async () => {
-            const { ids, changes, created } = await this.internalUpsertOne(entity, conflictPaths, payload);
-            const [id] = upsertIds(getMeta(entity), [payload], ids);
+        const meta = getMeta(entity);
+        return this.hooked(entity, 'Upsert', [payload], async (rows) => {
+            const { ids, changes, created } = await this.internalUpsertOne(entity, conflictPaths, rows[0]);
+            adoptReportedIds(meta, rows, ids);
+            const [id] = writtenIds(meta, rows);
             return { id, changes, created };
         });
     }
     async upsertMany(entity, conflictPaths, payload) {
-        return this.hooked(entity, 'Upsert', payload, async () => {
-            const { ids, changes } = await this.internalUpsertMany(entity, conflictPaths, payload);
-            return { ids: upsertIds(getMeta(entity), payload, ids), changes };
+        const meta = getMeta(entity);
+        return this.hooked(entity, 'Upsert', payload, async (rows) => {
+            const { ids, changes } = await this.internalUpsertMany(entity, conflictPaths, rows);
+            adoptReportedIds(meta, rows, ids);
+            return { ids: writtenIds(meta, rows), changes };
         });
     }
     async deleteOneById(entity, id, opts) {
@@ -278,20 +293,9 @@ export class AbstractQuerier {
         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.
+     * 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.
      */
     async saveMany(entity, payload) {
         const meta = getMeta(entity);
@@ -320,15 +324,15 @@ export class AbstractQuerier {
         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];
-                });
+                for (let position = 0; position < toInsert.length; position++) {
+                    ids[toInsert[position]] = 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]);
+                const { ids: upserted } = await this.upsertMany(entity, conflictPaths, toUpsert.map((index) => payload[index]));
+                for (let position = 0; position < toUpsert.length; position++) {
+                    ids[toUpsert[position]] = upserted[position];
                 }
             }
         };
@@ -519,16 +523,15 @@ export class AbstractQuerier {
         // unless this has run - and this method is `protected`, so a caller can arrive without them.
         assertSoleId(meta, 'saving a relation');
         const relEntity = relOpts.entity();
-        const relPayload = relValue;
         switch (relOpts.cardinality) {
             case '1m':
             case 'mm':
-                return this.saveToMany(relOpts, relEntity, ids, relPayload, isUpdate);
+                return this.saveToMany(relOpts, relEntity, ids, relValue, isUpdate);
             case '11':
-                return this.saveOneToOne(relEntity, relOpts, ids, relPayload, isUpdate);
+                return this.saveOneToOne(relEntity, relOpts, ids, relValue, isUpdate);
             case 'm1':
-                if (relPayload)
-                    return this.saveManyToOne(entity, relEntity, relOpts, ids, relPayload);
+                if (relValue)
+                    return this.saveManyToOne(entity, relEntity, relOpts, ids, relValue);
         }
     }
     async saveToMany(relOpts, relEntity, ids, relPayload, isUpdate) {
@@ -628,19 +631,39 @@ export class AbstractQuerier {
         return (this.extra?.listeners?.some((listener) => listener[event]) || (getMeta(entity).hooks?.[event]?.length ?? 0) > 0);
     }
     /**
-     * Emit a lifecycle hook event for the given entity.
-     * Fires global listeners first, then entity-level hooks.
+     * The ids of `rows`, read back by the columns an upsert matched them on, for a statement that could
+     * not report them in payload order. A row that no read row matches, or that two do, keeps
+     * `undefined`: a missing id is honest where a guessed one is not.
      */
+    async idsByConflict(entity, conflictPaths, rows) {
+        const meta = getMeta(entity);
+        const [idKey] = meta.ids;
+        const keys = getKeys(conflictPaths);
+        const q = {
+            $select: Object.fromEntries([idKey, ...keys].map((key) => [key, true])),
+            $where: { $or: rows.map((row) => Object.fromEntries(keys.map((key) => [key, row[key]]))) },
+        };
+        const found = await this.internalFindMany(entity, q, { filters: withoutSoftDeleteFilter(undefined) });
+        const byConflict = new Map();
+        for (const row of found) {
+            const key = rowKey(row, keys);
+            byConflict.set(key, byConflict.has(key) ? undefined : row[idKey]);
+        }
+        return rows.map((row) => byConflict.get(rowKey(row, keys)));
+    }
     /**
-     * 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.
+     * Runs `write` between the event's `before`/`after` pair. The before hooks get the caller's rows, so
+     * what they assign is written; `write` and the after hooks get a copy, which by then carries what
+     * 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 result = await write();
-        await this.emitHook(entity, `after${event}`, payloads);
+        const rows = clone(payloads);
+        const result = await write(rows);
+        await this.emitHook(entity, `after${event}`, rows);
         return result;
     }
+    /** Fires the global listeners first, then the entity's own hooks. */
     async emitHook(entity, event, payloads) {
         if (!this.hasHook(entity, event))
             return;

package/dist/querier/abstractSqlQuerier.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractSqlDialect } from '../dialect/index.js';
-import type { EntityData, ExtraOptions, IdValue, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
+import type { EntityData, ExtraOptions, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, SqlQuerier, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
 import { type ParentPartition } from '../util/index.js';
 import type { BuildUpdateResultPayload } from '../util/sql.util.js';
 import { AbstractQuerier } from './abstractQuerier.js';
@@ -71,6 +71,13 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * query, so neither can reach here.
      */
     protected internalFindManyPerParent<E extends object>(entity: Type<E>, q: Query<E>, partition: ParentPartition): Promise<E[]>;
+    /**
+     * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
+     * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
+     * before the deduplication and so overstates the page, and `$lock` on an engine that refuses the
+     * pair outright. Both then cost a second statement; only the counting differs.
+     */
+    private countedSeparately;
     /**
      * One statement for both: the page carries its own unpaged total in an extra column. An empty page
      * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past
@@ -82,13 +89,6 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
      * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
      */
-    /**
-     * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
-     * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
-     * before the deduplication and so overstates the page, and `$lock` on an engine that refuses the
-     * pair outright. Both then cost a second statement; only the counting differs.
-     */
-    private countedSeparately;
     protected internalFindManyAndCount<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): Promise<[E[], number]>;
     private selectRows;
     private hydrateRows;
@@ -119,7 +119,7 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     protected internalCount<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<number>;
     estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
     protected 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>[]>;
-    internalInsertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(IdValue<E> | undefined)[]>;
+    internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
     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;

package/dist/querier/abstractSqlQuerier.js

@@ -1,6 +1,6 @@
 import { COUNT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
-import { getMeta, idOf, soleIdOf } from '../entity/index.js';
+import { getMeta, idOf, namesKey } from '../entity/index.js';
 import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, insertShapeOf, getRelationRequestSummary, hasKeys, idOnlyQuery, isAutoIncrement, isPagedQuery, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { enrichError } from './queryError.js';
@@ -22,50 +22,36 @@ function partitionBySuppliedId(payload, idKey) {
     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.
+ * Row indexes grouped by the columns their rows carry, payload order kept within each group.
  *
  * 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 groups = new Map();
+    for (let index = 0; index < payload.length; index++) {
+        const shape = insertShapeOf(meta, payload[index]);
         const group = groups.get(shape);
         if (group) {
-            group.push(row);
+            group.push(index);
         }
         else {
-            groups.set(shape, [row]);
+            groups.set(shape, [index]);
         }
     }
     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.
+ * A group's row indexes split into statements within the dialect's bind budget, payload order kept.
+ * `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);
+function chunkByBindBudget(meta, payload, group, maxBindValues) {
+    const fieldsPerRecord = getInsertFieldKeys(meta, group.map((index) => payload[index])).length;
+    const size = Math.max(1, Math.floor(maxBindValues / (fieldsPerRecord || 1)));
     const chunks = [];
-    for (let start = 0; start < rows.length; start += size) {
-        chunks.push(rows.slice(start, start + size));
+    for (let start = 0; start < group.length; start += size) {
+        chunks.push(group.slice(start, start + size));
     }
     return chunks;
 }
@@ -186,17 +172,6 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         this.dialect.findPerParent(ctx, entity, q, partition);
         return this.hydrateRows(entity, q, await this.all(ctx.sql, ctx.values));
     }
-    /**
-     * One statement for both: the page carries its own unpaged total in an extra column. An empty page
-     * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past
-     * the end, or a filter nothing matched.
-     *
-     * A `$required` relation needs no special case: the window counts what the INNER JOIN left, which
-     * is exactly the total a caller of a filtered read is asking for. A `$lock` is the one clause an
-     * engine may refuse to have in the same statement, which {@link AbstractSqlDialect.supportsWindowWithRowLock}
-     * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
-     * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
-     */
     /**
      * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
      * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
@@ -212,6 +187,17 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
         return undefined;
     }
+    /**
+     * One statement for both: the page carries its own unpaged total in an extra column. An empty page
+     * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past
+     * the end, or a filter nothing matched.
+     *
+     * A `$required` relation needs no special case: the window counts what the INNER JOIN left, which
+     * is exactly the total a caller of a filtered read is asking for. A `$lock` is the one clause an
+     * engine may refuse to have in the same statement, which {@link AbstractSqlDialect.supportsWindowWithRowLock}
+     * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
+     * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
+     */
     async internalFindManyAndCount(entity, q, opts) {
         const separately = this.countedSeparately(entity, q, opts);
         if (separately) {
@@ -359,24 +345,15 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
         return res;
     }
-    async internalInsertMany(entity, payload) {
-        if (!payload?.length) {
-            return [];
-        }
-        payload = clone(payload);
+    async internalInsertMany(entity, rows) {
         const meta = getMeta(entity);
-        // What comes back is one column's value, so a composite reports nothing here and `insertMany`
-        // names those rows from the payload instead. `sole` is what keeps every id path off a key that
-        // is several columns.
+        // What comes back is one column's value, so nothing is read back for a composite: its rows
+        // already carry every column of it. `sole` is what keeps every id path off such a key.
         const [idKey] = meta.ids;
         const sole = meta.ids.length === 1;
         const idField = sole ? meta.fields[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);
+        for (const group of partitionBySuppliedId(rows, idKey)) {
             // 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:
@@ -385,28 +362,26 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             // 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)));
+                    (generatedKey && group.every((index) => rows[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);
+            // 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.
+            for (const indexes of chunkByBindBudget(meta, rows, group, this.dialect.maxBindValues)) {
                 const ctx = this.dialect.createContext();
-                this.dialect.insert(ctx, entity, indexes.map((index) => payload[index]));
+                this.dialect.insert(ctx, entity, indexes.map((index) => rows[index]));
                 const { ids = [] } = await this.run(ctx.sql, ctx.values);
-                indexes.forEach((index, position) => {
-                    const it = payload[index];
-                    if (idsReliable) {
-                        it[idKey] ??= ids[position];
+                if (idsReliable) {
+                    for (let position = 0; position < indexes.length; position++) {
+                        rows[indexes[position]][idKey] ??= ids[position];
                     }
-                    payloadIds[index] = sole ? it[idKey] : undefined;
-                });
+                }
             }
         }
-        await this.insertRelations(entity, payload);
-        return payloadIds;
+        await this.insertRelations(entity, rows);
     }
     async internalUpdateMany(entity, q, payload, opts) {
         payload = clone(payload);
@@ -446,8 +421,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         // 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));
+        const statements = groupByInsertShape(meta, payload).flatMap((group) => chunkByBindBudget(meta, payload, group, this.dialect.maxBindValues));
         if (statements.length === 1) {
             return this.runUpsert(entity, conflictPaths, payload);
         }
@@ -459,31 +433,41 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         // 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);
+            // Placed by index, since grouping by shape reorders the rows. A statement reporting fewer ids
+            // than it wrote places none.
+            const ids = new Array(payload.length);
+            for (const indexes of statements) {
+                const { changes: written = 0, ids: reported } = await this.runUpsert(entity, conflictPaths, indexes.map((index) => payload[index]));
+                changes += written;
+                if (reported?.length === indexes.length) {
+                    for (let position = 0; position < indexes.length; position++) {
+                        ids[indexes[position]] = reported[position];
+                    }
                 }
             }
-            // No `created`/`firstId`: both speak for a single statement, and there were several.
-            return ids.length ? { changes, ids } : { changes };
+            // No `created`: it speaks for a single statement, and there were several.
+            return { changes, ids };
         });
     }
     async runUpsert(entity, conflictPaths, payload) {
+        const meta = getMeta(entity);
+        // Asked first: the statement fills an `onInsert` key into these rows whether it inserts them or not.
+        const unnamed = meta.ids.length === 1 && payload.some((row) => !namesKey(meta, row));
         const ctx = this.dialect.createContext();
         this.dialect.upsert(ctx, entity, conflictPaths, payload);
         const result = await this.run(ctx.sql, ctx.values);
-        // On a `firstId` dialect (MySQL: no `RETURNING`), a multi-row upsert's `affectedRows` is a
-        // per-row weighted sum (1=insert, 2=update, 0=no-op), not a row count, so `buildUpdateResult`'s
-        // header-derived `ids`/`firstId`/`created` can't be trusted the moment more than one row is
-        // involved (verified: a 1-insert-1-update batch reports `changes: 3`, which would otherwise
-        // infer 3 sequential ids for only 2 real rows). A single-row batch (`upsertOne`) is unambiguous.
-        if (this.dialect.insertIdSource !== 'returning' && payload.length > 1) {
-            return { changes: result.changes };
-        }
-        return result;
+        const ordered = payload.length === 1 || (this.dialect.insertIdSource === 'returning' && this.dialect.upsertReturningOrdered);
+        if (ordered && result.ids?.length === payload.length) {
+            return result;
+        }
+        // The statement's ids name its rows only in order and for every one. A MySQL batch reports a
+        // weighted count (1=insert, 2=update) instead, CockroachDB and SQL Server answer out of order, and
+        // `DO NOTHING` skips rows, so there the ids are read back by the conflict columns.
+        const { changes } = result;
+        const created = payload.length === 1 ? result.created : undefined;
+        return unnamed
+            ? { changes, created, ids: await this.idsByConflict(entity, conflictPaths, payload) }
+            : { changes, created };
     }
     async internalDeleteMany(entity, q, opts) {
         const meta = getMeta(entity);