uql-orm 0.52.0 → 0.54.0

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,12 +1,13 @@
 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 { 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';
 /**
  * Rejects a nullish primary key before it reaches a statement. The by-id methods reduce to
- * `{ $where: id }`, and a nullish `$where` is *no filter*, so an unchecked one addresses the whole
- * table. An entity declares its id optional, which puts `undefined` inside `IdValue<E>`, and the
- * HTTP layer reaches these methods with parsed JSON regardless, so the guard belongs at runtime.
+ * `{ $where: { id } }`, and a key compared to `undefined` is *no filter*, so an unchecked one
+ * addresses the whole table. An entity declares its id optional, which puts `undefined` inside
+ * `IdValue<E>`, and the HTTP layer reaches these methods with parsed JSON regardless, so the guard
+ * belongs at runtime.
  *
  * Its callers are all `async` so this surfaces as a rejection on every one of them: a guard that
  * threw synchronously from some and rejected from others would escape a caller's `.catch()`.
@@ -16,7 +17,7 @@ function assertIdValue(entity, id) {
         throw new TypeError(`'${entity.name}' was addressed by id, but the id is ${String(id)}`);
     }
     if (isScalarId(id)) {
-        // One value names one column, which `buildQueryWhereAsMap` refuses on a composite.
+        // One value names one column, which `whereIds` refuses on a composite.
         return;
     }
     // Every key, or the `$where` names only some of the columns and addresses each row that agrees on
@@ -40,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;
     /**
@@ -119,7 +125,7 @@ export class AbstractQuerier {
     }
     async findOneById(entity, id, q = {}, opts) {
         assertIdValue(entity, id);
-        return this.findOne(entity, { ...q, $where: augmentWhere(getMeta(entity), q.$where, id) }, opts);
+        return this.findOne(entity, { ...q, $where: { ...q.$where, ...whereIds(getMeta(entity), id) } }, opts);
     }
     async findOne(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts);
@@ -181,34 +187,40 @@ 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) {
         assertIdValue(entity, id);
-        return this.updateMany(entity, { $where: id }, payload, opts);
+        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);
-        return this.restoreMany(entity, { $where: id });
+        return this.restoreMany(entity, { $where: whereIds(getMeta(entity), id) });
     }
     async restoreMany(entity, q) {
         const meta = getMeta(entity);
         if (!meta.softDelete) {
             throw new TypeError(`'${entity.name}' has not enabled 'softDelete'`);
         }
-        const $where = augmentWhere(meta, q.$where, { [meta.softDelete]: { $ne: null } });
+        const $where = { ...q.$where, [meta.softDelete]: { $ne: null } };
         return this.updateMany(entity, { ...q, $where }, { [meta.softDelete]: null }, {
             filters: { softDelete: false },
         });
@@ -220,21 +232,25 @@ 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) {
         assertIdValue(entity, id);
-        return this.deleteMany(entity, { $where: id }, opts);
+        return this.deleteMany(entity, { $where: whereIds(getMeta(entity), id) }, opts);
     }
     async deleteMany(entityOrQuery, qOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, qOrOpts, maybeOpts);
@@ -248,7 +264,8 @@ export class AbstractQuerier {
         let target = q;
         if (doomed) {
             const meta = getMeta(entity);
-            target = { $where: doomed.map((it) => idOf(meta, it)) };
+            const ids = doomed.map((it) => idOf(meta, it));
+            target = { $where: whereIds(meta, ids) };
         }
         await this.emitHook(entity, 'beforeDelete', doomed ?? []);
         const changes = await this.internalDeleteMany(entity, target, opts);
@@ -276,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);
@@ -318,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];
                 }
             }
         };
@@ -517,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) {
@@ -626,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;