uql-orm 0.114.2 → 0.114.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -165,6 +165,6 @@ Release notes live in [CHANGELOG.md](https://github.com/rogerpadilla/uql/blob/ma
165
165
 
166
166
  ---
167
167
 
168
- ## Enjoy UQL? ⭐
168
+ ## Enjoy UQL! ⭐
169
169
 
170
170
  [![Star it on GitHub](https://img.shields.io/badge/Star_on_GitHub-3282b5?style=flat&logo=github)](https://github.com/rogerpadilla/uql)
@@ -1,7 +1,6 @@
1
1
  import type { ClientSession, Document, MongoClient } from 'mongodb';
2
- import type { UpsertedId } from '../querier/abstractQuerier.js';
3
2
  import { AbstractQuerier } from '../querier/index.js';
4
- import type { EntityData, ExtraOptions, Query, QueryAggregate, QueryUpsert, QueryPage, StatementOptions, QuerySearch, RawRow, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
3
+ import type { EntityData, ExtraOptions, WrittenId, Query, QueryAggregate, QueryUpsert, QueryPage, StatementOptions, QuerySearch, RawRow, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
5
4
  import type { MongoDialect } from './mongoDialect.js';
6
5
  import type { MongoQuerier } from './mongoQuerier.js';
7
6
  export declare class MongodbQuerier extends AbstractQuerier implements MongoQuerier {
@@ -48,7 +47,7 @@ export declare class MongodbQuerier extends AbstractQuerier implements MongoQuer
48
47
  * Updating a found document `apart`, it writes only an inserted one.
49
48
  */
50
49
  private upsertUpdate;
51
- protected internalUpsertMany<E extends Document>(entity: Type<E>, q: QueryUpsert<E>, payload: E[]): Promise<(UpsertedId<E> | undefined)[]>;
50
+ protected internalUpsertMany<E extends Document>(entity: Type<E>, q: QueryUpsert<E>, payload: E[]): Promise<(WrittenId<E> | undefined)[]>;
52
51
  protected internalDeleteMany<E extends Document>(entity: Type<E>, qm: QuerySearch<E>, opts?: StatementOptions): Promise<number>;
53
52
  get hasOpenTransaction(): boolean;
54
53
  /** Every read and write goes through here, which makes it where a released querier is caught. */
@@ -1,8 +1,8 @@
1
1
  import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
2
2
  import { hasRequiredJoin } from '../dialect/queryJoins.js';
3
- import { getMeta, namesEvery, soleIdOf } from '../entity/index.js';
3
+ import { getMeta, soleIdOf } from '../entity/index.js';
4
4
  import { AbstractQuerier } from '../querier/index.js';
5
- import { clone, deletionOf, foundRowWhere, foundRowAssigned, getKeys, hasKeys, hasTriggers, upsertKeepsOwnKey, withDeleted, } from '../util/index.js';
5
+ import { clone, deletionOf, foundRowWhere, foundRowAssigned, hasKeys, hasTriggers, withDeleted, } from '../util/index.js';
6
6
  import { UqlUsageError } from '../util/uqlError.js';
7
7
  /**
8
8
  * `$limit: 0` asks for no rows, the way it does on every SQL dialect - but MongoDB reads `limit(0)`
@@ -183,33 +183,25 @@ export class MongodbQuerier extends AbstractQuerier {
183
183
  }
184
184
  async internalUpsertMany(entity, q, payload) {
185
185
  refuseTriggers(entity);
186
- if (!payload.length) {
187
- return [];
188
- }
189
186
  // A found document is updated apart from the insert when the upsert has an update of its own, as `$setOnInsert`
190
187
  // and `$inc` on one field conflict in one operation, or a `$where`. The two batches are not atomic on their own:
191
188
  // a transaction the caller opens makes them so.
192
189
  const apart = q.$update !== undefined || q.$where !== undefined;
193
190
  const meta = getMeta(entity);
194
191
  const { $conflict } = q;
195
- const kept = payload.map((row) => upsertKeepsOwnKey(meta, $conflict, row));
196
- // A row naming no conflict key conflicts with none, so it inserts, as `ON CONFLICT` inserts it; a soft-deleted
197
- // document conflicts as any other does, its unique key holding across both.
198
- const keys = getKeys($conflict);
199
- const upserts = payload.map((row) => !namesEvery(row, keys)
200
- ? { insertOne: { document: this.dialect.getPersistable(meta, clone(row), 'onInsert') } }
201
- : {
202
- updateOne: {
203
- filter: this.dialect.where(entity, foundRowWhere({ $conflict }, row), withDeleted()),
204
- update: this.upsertUpdate(meta, row, apart),
205
- upsert: true,
206
- },
207
- });
192
+ // A soft-deleted document conflicts as any other does, its unique key holding across both.
193
+ const upserts = payload.map((row) => ({
194
+ updateOne: {
195
+ filter: this.dialect.where(entity, foundRowWhere({ $conflict }, row), withDeleted()),
196
+ update: this.upsertUpdate(meta, row, apart),
197
+ upsert: true,
198
+ },
199
+ }));
208
200
  const res = await this.execute('upsertMany', (session) => this.collection(entity).bulkWrite(upserts, { session }));
209
- // `upsertedIds` and `insertedIds` name only the documents inserted, keyed by operation index, so each lands on
210
- // its own row; an updated document's `_id` is read back by the conflict fields instead.
201
+ // `upsertedIds` names only the documents inserted, keyed by operation index, so each lands on its own row; an
202
+ // updated document's `_id` is read back by the conflict fields instead.
211
203
  const reported = payload.map((_, index) => {
212
- const id = res.upsertedIds[index] ?? res.insertedIds[index];
204
+ const id = res.upsertedIds[index];
213
205
  return id === undefined ? undefined : this.dialect.fromWireId(id);
214
206
  });
215
207
  const updates = apart
@@ -223,7 +215,7 @@ export class MongodbQuerier extends AbstractQuerier {
223
215
  if (updates.length) {
224
216
  await this.execute('upsertMany', (session) => this.collection(entity).bulkWrite(updates, { session }));
225
217
  }
226
- return this.withUnreportedIds(entity, $conflict, payload, reported, kept);
218
+ return reported;
227
219
  }
228
220
  async internalDeleteMany(entity, qm, opts = {}) {
229
221
  refuseTriggers(entity);
@@ -1,9 +1,7 @@
1
1
  import type { AbstractDialect } from '../dialect/abstractDialect.js';
2
- import type { BooleanLike, CursorPage, Captured, EntityData, EntityId, EntityWrite, EntityMeta, ExtraOptions, FieldKey, Querier, Query, QueryAggregate, QueryAggregateResult, QueryConflictKeys, QueryUpsert, QueryFilter, QueryFindResult, QueryKeyset, QueryOne, QueryOptions, StatementOptions, QueryPage, QuerySearch, SavepointCommand, TransactionOptions, Type, UpdatePayload, UpdateWrite, WriteResults, WriteOptions, PrimaryKey, WrittenId, RawRow, ReportedWrite } from '../type/index.js';
2
+ import type { BooleanLike, CursorPage, Captured, EntityData, EntityId, EntityWrite, EntityMeta, ExtraOptions, FieldKey, Querier, Query, QueryAggregate, QueryAggregateResult, QueryUpsert, QueryFilter, QueryFindResult, QueryKeyset, QueryOne, QueryOptions, StatementOptions, QueryPage, QuerySearch, SavepointCommand, TransactionOptions, Type, UpdatePayload, UpdateWrite, WriteResults, WriteOptions, WrittenId, RawRow, ReportedWrite } from '../type/index.js';
3
3
  import { LoggerWrapper } from '../util/index.js';
4
4
  import { type TransactionScope } from './transaction.js';
5
- /** What an upsert reports of a row: the value a driver answers for a lone key, or the key the read back names. */
6
- export type UpsertedId<E> = PrimaryKey | WrittenId<E>;
7
5
  /** Each write as one statement reporting the rows it wrote with the fields `keys` names. */
8
6
  export type ReportingWrites = {
9
7
  update<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts: StatementOptions, keys: readonly FieldKey<E>[]): Promise<E[]>;
@@ -117,18 +115,22 @@ export declare abstract class AbstractQuerier implements Querier {
117
115
  protected abstract internalAggregate<E extends object>(entity: Type<E>, q: QueryAggregate<E>, opts?: QueryOptions): Promise<RawRow[]>;
118
116
  /** Abstract outright: nothing is shared to do around it. See {@link UniversalQuerier.estimatedCount}. */
119
117
  abstract estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
120
- insertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted']>;
121
- insertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted'][]>;
118
+ insertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
119
+ insertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
122
120
  /**
123
121
  * What an insert reports: the ids, or the rows `returning` asks for, off the insert's own statement where
124
122
  * {@link reportingWrites} can, else read back.
125
123
  */
126
124
  private insertWritten;
125
+ /** Inserts `rows` as {@link insertRows} does, reporting each with the fields `keys` names off its own statement. */
126
+ private insertReturning;
127
127
  /**
128
128
  * The ids of the rows inserted, in payload order. The `onInsert` values are filled before the write, so
129
129
  * the after hooks and the ids read the same rows the statement wrote.
130
130
  */
131
131
  private insertIds;
132
+ /** Inserts `rows` as {@link insertRows} does, answering the key each got. */
133
+ private insertedIds;
132
134
  /** `insert` of `payload` between the insert hooks, {@link atomically} where it writes relations too. */
133
135
  private inserting;
134
136
  /**
@@ -221,19 +223,35 @@ export declare abstract class AbstractQuerier implements Querier {
221
223
  restoreMany<E extends object>(entity: Type<E>, q: QuerySearch<E>): Promise<number>;
222
224
  upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(q: QueryUpsert<E> & {
223
225
  $entity: Type<E>;
224
- }, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['upserted']>;
225
- upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['upserted']>;
226
+ }, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
227
+ upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
226
228
  upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(q: QueryUpsert<E> & {
227
229
  $entity: Type<E>;
228
- }, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['upserted'][]>;
229
- upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['upserted'][]>;
230
- /** Upserts `rows`, reading first where {@link upsertsByReading} says so, and answers the id each row got. */
230
+ }, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
231
+ upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
232
+ /** Upserts `rows`, each naming every conflict key, reading first where {@link upsertsByReading} says so: the id each got. */
231
233
  private upsertIds;
232
234
  /**
233
- * An upsert of one statement reporting each row as it stands after it: off its `RETURNING` where it wrote the row,
234
- * else, where its `$where` or an empty `$update` kept it, read by the conflict keys.
235
+ * The id of each of `rows` the engine's upsert reports, or {@link withKept} reads back. A row matched on its own key
236
+ * names it, so needs neither.
237
+ */
238
+ private reportedOrKeptIds;
239
+ /**
240
+ * `written`, an upsert's report of each of `rows`, with each row it reported none of, kept by its `$where` or an
241
+ * empty `$update`, read back by its conflict keys selecting `select`: `undefined` where no row matches.
242
+ */
243
+ private withKept;
244
+ /**
245
+ * An upsert of one statement, of rows each naming every conflict key, reporting each row as it stands after it: off
246
+ * its `RETURNING` where it wrote the row, else, where its `$where` or an empty `$update` kept it, read by the
247
+ * conflict keys.
235
248
  */
236
249
  private upsertReturning;
250
+ /**
251
+ * Writes each of `rows` through the writer `branch` names for it, the writers in their order, answering each row's
252
+ * result in `rows` order; {@link atomically} where more than one branch but those `idle` names, which write nothing.
253
+ */
254
+ private writeEach;
237
255
  /**
238
256
  * Refuses a row an upsert wrote or kept that no row matches by its conflict key, as read back: the engine stores
239
257
  * the key otherwise than the row spells it, a uuid in other letters, and a row left out would misalign the rest.
@@ -247,10 +265,10 @@ export declare abstract class AbstractQuerier implements Querier {
247
265
  */
248
266
  private readThenUpsert;
249
267
  /**
250
- * Upserts `payload` as `q` names its rows, answering each row's key in payload order, `undefined` for one the
251
- * engine did not report.
268
+ * Upserts `payload`, at least one row, each naming every conflict key, as `q` names its rows, answering each row's
269
+ * key in payload order, `undefined` for one the engine did not report, which a found row it kept may be.
252
270
  */
253
- protected abstract internalUpsertMany<E extends object>(entity: Type<E>, q: QueryUpsert<E>, payload: E[]): Promise<(UpsertedId<E> | undefined)[]>;
271
+ protected abstract internalUpsertMany<E extends object>(entity: Type<E>, q: QueryUpsert<E>, payload: E[]): Promise<(WrittenId<E> | undefined)[]>;
254
272
  deleteOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions & WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['affected']>;
255
273
  /** Delete records matching the query, the entity passed first or as `$entity`; soft-deletes unless `opts.hardDelete`. */
256
274
  deleteMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(q: QuerySearch<E> & {
@@ -269,8 +287,8 @@ export declare abstract class AbstractQuerier implements Querier {
269
287
  private deleteRows;
270
288
  /** Runs one DELETE (or soft-delete stamp) over `q`, which names its rows by id wherever {@link deleteMany} settled them. */
271
289
  protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: StatementOptions): Promise<number>;
272
- saveOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted']>;
273
- saveMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted'][]>;
290
+ saveOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
291
+ saveMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
274
292
  /**
275
293
  * Whether a row names its key decides its statement, never whether the row exists: a named row
276
294
  * upserts on that key, so a stale id is written rather than silently missed, and an unnamed one
@@ -354,19 +372,12 @@ export declare abstract class AbstractQuerier implements Querier {
354
372
  * listens.
355
373
  */
356
374
  private emitLoaded;
357
- /** The ids of `rows`, read by the columns an upsert matches them on, as {@link rowsByConflict} reads them. */
358
- private idsByConflict;
359
375
  /**
360
- * The row each of `rows` matches on the columns an upsert matches on, with `select`, soft-deleted rows included
361
- * since a unique key holds across both, held as {@link readForWrite} holds its rows. One no row matches, or two do,
362
- * reads none, since a missing row is honest where a guessed one is not; a null key never conflicts, so is not read.
376
+ * The row each of `rows` matches on the columns an upsert matches on, each naming every one, with `select`,
377
+ * soft-deleted rows included since a unique key holds across both, held as {@link readForWrite} holds its rows. One
378
+ * no row matches, or two do, reads none, since a missing row is honest where a guessed one is not.
363
379
  */
364
380
  private rowsByConflict;
365
- /**
366
- * `ids` completed where an upsert reported no id for a row whose key it does not keep (`kept`, asked before the
367
- * write fills one in): read back by the conflict columns.
368
- */
369
- protected withUnreportedIds<E extends object>(entity: Type<E>, conflictKeys: QueryConflictKeys<E>, payload: EntityData<E>[], ids: (UpsertedId<E> | undefined)[], kept: readonly boolean[]): Promise<(UpsertedId<E> | undefined)[]>;
370
381
  /** Reads of the rows matching one of `rows` on `keys`, as many per statement as a key list takes, selecting `select`. */
371
382
  private keyedReads;
372
383
  /**
@@ -73,7 +73,18 @@ function assertLockableUpdate(meta, q, settles) {
73
73
  * database generated or the ORM filled is there, and a composite is named by every column of it.
74
74
  */
75
75
  function writtenIds(meta, rows) {
76
- return rows.map((row) => (namesKey(meta, row) ? idOf(meta, row) : undefined));
76
+ return rows.map((row) => {
77
+ const id = namesKey(meta, row) ? idOf(meta, row) : undefined;
78
+ if (id == null) {
79
+ throw new UqlUsageError(`an insert into '${meta.name}' left its key empty: name it`);
80
+ }
81
+ return id;
82
+ });
83
+ }
84
+ /** Which way an upsert writes `row`: a row naming no conflict key conflicts with none, so it is an insert. */
85
+ function upsertBranch(q) {
86
+ const keys = getKeys(q.$conflict);
87
+ return (row) => (namesEvery(row, keys) ? 'upsert' : 'insert');
77
88
  }
78
89
  /**
79
90
  * Whether an upsert has to read before it writes: `ON CONFLICT` updates a guarded row whatever tenant it belongs
@@ -85,24 +96,17 @@ function upsertsByReading(meta, q, rows) {
85
96
  writesRelations(meta, q.$update ? [...rows, q.$update] : rows));
86
97
  }
87
98
  /**
88
- * Writes the key an upsert reported onto each row, over the one it named: a found row keeps its own, and a row
89
- * reported none keeps what it has. Only the key, since an `onInsert` value was never written to a row the upsert
90
- * updated.
99
+ * Writes the key an upsert reported onto `row`, over the one it named: a found row keeps its own. Only the key, since
100
+ * an `onInsert` value was never written to a row the upsert updated. Answers `id`.
91
101
  */
92
- function adoptReportedIds(meta, rows, reported) {
93
- const [idKey] = meta.ids;
94
- rows.forEach((row, index) => {
95
- const id = reported[index];
96
- if (id === undefined) {
97
- return;
98
- }
99
- if (meta.ids.length > 1) {
100
- Object.assign(row, id);
101
- }
102
- else {
103
- row[idKey] = id;
104
- }
105
- });
102
+ function adoptId(meta, row, id) {
103
+ if (meta.ids.length > 1) {
104
+ Object.assign(row, id);
105
+ }
106
+ else {
107
+ row[meta.ids[0]] = id;
108
+ }
109
+ return id;
106
110
  }
107
111
  /** Normalizes either call form to `[entity, query, opts]`, throwing when a query object has no `$entity`. */
108
112
  function entityArgs(args) {
@@ -353,8 +357,12 @@ export class AbstractQuerier {
353
357
  if (!keys || !reportingWrites || !payload.length) {
354
358
  return this.writtenOrReadBack(entity, () => this.insertIds(entity, payload), opts);
355
359
  }
356
- const read = [...new Set([...keys, ...meta.ids])];
357
- return this.inserting(entity, payload, async (rows) => this.returned(entity, await this.insertRows(entity, rows, (inserted) => reportingWrites.insert(entity, inserted, read)), keys));
360
+ return this.inserting(entity, payload, (rows) => this.insertReturning(reportingWrites, entity, rows, keys));
361
+ }
362
+ /** Inserts `rows` as {@link insertRows} does, reporting each with the fields `keys` names off its own statement. */
363
+ async insertReturning(writes, entity, rows, keys) {
364
+ const read = [...new Set([...keys, ...getMeta(entity).ids])];
365
+ return this.returned(entity, await this.insertRows(entity, rows, (inserted) => writes.insert(entity, inserted, read)), keys);
358
366
  }
359
367
  /**
360
368
  * The ids of the rows inserted, in payload order. The `onInsert` values are filled before the write, so
@@ -364,16 +372,13 @@ export class AbstractQuerier {
364
372
  if (!payload.length) {
365
373
  return [];
366
374
  }
375
+ return this.inserting(entity, payload, (rows) => this.insertedIds(entity, rows));
376
+ }
377
+ /** Inserts `rows` as {@link insertRows} does, answering the key each got. */
378
+ async insertedIds(entity, rows) {
367
379
  const meta = getMeta(entity);
368
- return this.inserting(entity, payload, async (rows) => {
369
- await this.insertRows(entity, rows, (inserting) => this.internalInsertMany(entity, inserting));
370
- return writtenIds(meta, rows).map((id) => {
371
- if (id == null) {
372
- throw new UqlUsageError(`an insert into '${meta.name}' left its key empty: name it`);
373
- }
374
- return id;
375
- });
376
- });
380
+ await this.insertRows(entity, rows, (inserting) => this.internalInsertMany(entity, inserting));
381
+ return writtenIds(meta, rows);
377
382
  }
378
383
  /** `insert` of `payload` between the insert hooks, {@link atomically} where it writes relations too. */
379
384
  inserting(entity, payload, insert) {
@@ -393,15 +398,11 @@ export class AbstractQuerier {
393
398
  * says of them, since a soft-deleted row inserted is still written.
394
399
  */
395
400
  async readBack(entity, ids, keys, opts) {
396
- const meta = getMeta(entity);
397
- const known = ids.filter((id) => id !== undefined);
398
- if (known.length < ids.length) {
399
- throw new UqlUsageError(`'returning' reads each written '${entity.name}' back by its key, which ${this.dialect.engineName} did not report for every row: give the rows their own keys`);
400
- }
401
- if (!known.length) {
401
+ if (!ids.length) {
402
402
  return [];
403
403
  }
404
- const named = known.map((id) => whereIds(meta, id));
404
+ const meta = getMeta(entity);
405
+ const named = ids.map((id) => whereIds(meta, id));
405
406
  const read = withDeleted(opts);
406
407
  const rows = [];
407
408
  for (const q of this.keyedReads(meta.ids, named, [...keys, ...meta.ids])) {
@@ -618,39 +619,99 @@ export class AbstractQuerier {
618
619
  const meta = getMeta(entity);
619
620
  const keys = returnedKeys(meta, opts?.returning);
620
621
  const reportingWrites = keys && this.reportingWrites(meta, 'upsert');
621
- // Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither
622
- // the insert's nor the update's pair fits. How to write is decided on the rows the hooks hand over.
622
+ // Fires `beforeUpsert`/`afterUpsert`: whether a found row is updated is the database's to decide, so neither the
623
+ // insert's nor the update's pair fits. How to write is decided on the rows the hooks hand over: one naming no
624
+ // conflict key conflicts with none, so it is written as an insert.
625
+ const branch = upsertBranch(q);
623
626
  if (!keys || !reportingWrites) {
624
- return this.writtenOrReadBack(entity, () => this.hooked(entity, 'Upsert', payload, (rows) => this.upsertIds(entity, q, rows)), opts);
627
+ return this.writtenOrReadBack(entity, () => this.hooked(entity, 'Upsert', payload, (rows) => this.writeEach(rows, branch, {
628
+ insert: (inserts) => this.insertedIds(entity, inserts),
629
+ upsert: (upserts) => this.upsertIds(entity, q, upserts),
630
+ })), opts);
625
631
  }
626
- return this.atomically(() => this.hooked(entity, 'Upsert', payload, async (rows) => upsertsByReading(meta, q, rows)
627
- ? this.readBack(entity, await this.upsertIds(entity, q, rows), keys)
628
- : this.upsertReturning(reportingWrites, entity, q, rows, keys)));
629
- }
630
- /** Upserts `rows`, reading first where {@link upsertsByReading} says so, and answers the id each row got. */
632
+ return this.atomically(() => this.hooked(entity, 'Upsert', payload, (rows) => this.writeEach(rows, branch, {
633
+ insert: (inserts) => this.insertReturning(reportingWrites, entity, inserts, keys),
634
+ upsert: async (upserts) => upsertsByReading(meta, q, upserts)
635
+ ? this.readBack(entity, await this.upsertIds(entity, q, upserts), keys)
636
+ : this.upsertReturning(reportingWrites, entity, q, upserts, keys),
637
+ })));
638
+ }
639
+ /** Upserts `rows`, each naming every conflict key, reading first where {@link upsertsByReading} says so: the id each got. */
631
640
  async upsertIds(entity, q, rows) {
632
641
  const meta = getMeta(entity);
633
642
  const ids = upsertsByReading(meta, q, rows)
634
643
  ? await this.readThenUpsert(entity, q, rows)
635
- : await this.internalUpsertMany(entity, q, rows);
636
- adoptReportedIds(meta, rows, ids);
637
- return writtenIds(meta, rows);
644
+ : await this.reportedOrKeptIds(entity, q, rows);
645
+ return rows.map((row, index) => adoptId(meta, row, ids[index] ?? this.unmatched(entity, q, row)));
646
+ }
647
+ /**
648
+ * The id of each of `rows` the engine's upsert reports, or {@link withKept} reads back. A row matched on its own key
649
+ * names it, so needs neither.
650
+ */
651
+ async reportedOrKeptIds(entity, q, rows) {
652
+ const meta = getMeta(entity);
653
+ const ids = await this.internalUpsertMany(entity, q, rows);
654
+ return meta.ids.every((key) => Object.hasOwn(q.$conflict, key))
655
+ ? rows.map((row) => idOf(meta, row))
656
+ : this.withKept(entity, q, rows, ids, meta.ids, (row) => idOf(meta, row));
657
+ }
658
+ /**
659
+ * `written`, an upsert's report of each of `rows`, with each row it reported none of, kept by its `$where` or an
660
+ * empty `$update`, read back by its conflict keys selecting `select`: `undefined` where no row matches.
661
+ */
662
+ async withKept(entity, q, rows, written, select, of) {
663
+ const keptAt = rows.flatMap((_, index) => (written[index] === undefined ? [index] : []));
664
+ if (keptAt.length) {
665
+ const kept = await this.rowsByConflict(entity, q.$conflict, keptAt.map((index) => rows[index]), select);
666
+ keptAt.forEach((index, position) => {
667
+ const row = kept[position];
668
+ written[index] = row && of(row);
669
+ });
670
+ }
671
+ return written;
638
672
  }
639
673
  /**
640
- * An upsert of one statement reporting each row as it stands after it: off its `RETURNING` where it wrote the row,
641
- * else, where its `$where` or an empty `$update` kept it, read by the conflict keys.
674
+ * An upsert of one statement, of rows each naming every conflict key, reporting each row as it stands after it: off
675
+ * its `RETURNING` where it wrote the row, else, where its `$where` or an empty `$update` kept it, read by the
676
+ * conflict keys.
642
677
  */
643
678
  async upsertReturning(writes, entity, q, rows, keys) {
644
679
  const meta = getMeta(entity);
645
680
  const read = [...new Set([...keys, ...meta.ids, ...getKeys(q.$conflict)])];
646
- const written = await writes.upsert(entity, q, rows, read);
647
- const keptAt = rows.flatMap((_, index) => (written[index] === undefined ? [index] : []));
648
- const kept = await this.rowsByConflict(entity, q.$conflict, keptAt.map((index) => rows[index]), read);
649
- const keptBy = new Map(keptAt.map((index, position) => [index, kept[position]]));
650
- const stands = rows.map((row, index) => written[index] ?? keptBy.get(index) ?? this.unmatched(entity, q, row));
651
- adoptReportedIds(meta, rows, stands.map((row) => idOf(meta, row)));
681
+ const written = await this.withKept(entity, q, rows, await writes.upsert(entity, q, rows, read), read, (row) => row);
682
+ const stands = rows.map((row, index) => {
683
+ const stand = written[index] ?? this.unmatched(entity, q, row);
684
+ adoptId(meta, row, idOf(meta, stand));
685
+ return stand;
686
+ });
652
687
  return this.returned(entity, stands, keys);
653
688
  }
689
+ /**
690
+ * Writes each of `rows` through the writer `branch` names for it, the writers in their order, answering each row's
691
+ * result in `rows` order; {@link atomically} where more than one branch but those `idle` names, which write nothing.
692
+ */
693
+ async writeEach(rows, branch, writers, idle = []) {
694
+ const at = Map.groupBy(rows.keys(), (index) => branch(rows[index]));
695
+ const [only] = at.keys();
696
+ if (at.size === 1) {
697
+ return writers[only]([...rows]);
698
+ }
699
+ const results = new Array(rows.length);
700
+ const write = async () => {
701
+ for (const key of getKeys(writers)) {
702
+ const indexes = at.get(key);
703
+ if (indexes) {
704
+ const written = await writers[key](indexes.map((index) => rows[index]));
705
+ indexes.forEach((index, position) => {
706
+ results[index] = written[position];
707
+ });
708
+ }
709
+ }
710
+ return results;
711
+ };
712
+ const writing = [...at.keys()].filter((key) => !idle.includes(key));
713
+ return writing.length > 1 ? this.atomically(write) : write();
714
+ }
654
715
  /**
655
716
  * Refuses a row an upsert wrote or kept that no row matches by its conflict key, as read back: the engine stores
656
717
  * the key otherwise than the row spells it, a uuid in other letters, and a row left out would misalign the rest.
@@ -670,11 +731,9 @@ export class AbstractQuerier {
670
731
  async readThenUpsert(entity, q, rows) {
671
732
  const meta = getMeta(entity);
672
733
  guardWrite(meta, rows, 'insert');
673
- if (!rows.length) {
674
- return [];
675
- }
676
734
  return this.atomically(async () => {
677
- const ids = await this.idsByConflict(entity, q.$conflict, rows);
735
+ const found = await this.rowsByConflict(entity, q.$conflict, rows, meta.ids);
736
+ const ids = found.map((row) => row && idOf(meta, row));
678
737
  for (const [index, row] of rows.entries()) {
679
738
  const id = ids[index];
680
739
  if (id === undefined) {
@@ -696,8 +755,7 @@ export class AbstractQuerier {
696
755
  if (inserts.length) {
697
756
  await this.insertRows(entity, inserts, (inserting) => this.internalInsertMany(entity, inserting));
698
757
  }
699
- // A found row's key is adopted by the caller; an inserted one carries the key its insert wrote.
700
- return ids;
758
+ return rows.map((row, index) => ids[index] ?? idOf(meta, row));
701
759
  });
702
760
  }
703
761
  async deleteOneById(entity, id, opts) {
@@ -790,46 +848,22 @@ export class AbstractQuerier {
790
848
  * upserts on that key, so a stale id is written rather than silently missed, and an unnamed one
791
849
  * inserts. A composite is always named. The hooks follow the statement: a named row fires the upsert pair.
792
850
  */
793
- async saveIds(entity, payload) {
851
+ saveIds(entity, payload) {
794
852
  const meta = getMeta(entity);
795
- // Indexes, not rows: the result is reported in payload order so it can be zipped with what was
796
- // passed, which concatenating the branches did not do.
797
- const toInsert = [];
798
- const toUpsert = [];
799
- const ids = new Array(payload.length);
800
- /** Whether the row carries anything its primary key does not - something to write. */
801
- const writesMoreThanItsKey = (row) => someKey(row, (key) => !meta.ids.some((idKey) => idKey === key));
802
- for (let index = 0; index < payload.length; index++) {
803
- const it = payload[index];
804
- if (!namesKey(meta, it)) {
805
- toInsert.push(index);
806
- }
807
- else if (writesMoreThanItsKey(it)) {
808
- toUpsert.push(index);
809
- }
810
- else {
811
- // A row that names its key and carries nothing else is a *reference*, not a write - the
812
- // shape a to-many uses to link rows it did not author. Upserting it would stamp `onUpdate`
813
- // fields on a row the caller never asked to change, and create one that was meant to exist.
814
- ids[index] = idOf(meta, it);
815
- }
816
- }
817
- const write = async () => {
818
- if (toInsert.length) {
819
- const inserted = await this.insertIds(entity, toInsert.map((index) => payload[index]));
820
- for (let position = 0; position < toInsert.length; position++) {
821
- ids[toInsert[position]] = inserted[position];
822
- }
823
- }
824
- if (toUpsert.length) {
825
- const upserted = await this.upsertMany(entity, { $conflict: keySet(meta.ids) }, toUpsert.map((index) => payload[index]));
826
- for (let position = 0; position < toUpsert.length; position++) {
827
- ids[toUpsert[position]] = upserted[position];
828
- }
853
+ // A row that names its key and carries nothing else is a *reference*, not a write - the shape a to-many
854
+ // uses to link rows it did not author. Upserting it would stamp `onUpdate` fields on a row the caller
855
+ // never asked to change, and create one that was meant to exist.
856
+ const branch = (row) => {
857
+ if (!namesKey(meta, row)) {
858
+ return 'insert';
829
859
  }
860
+ return someKey(row, (key) => !meta.ids.some((idKey) => idKey === key)) ? 'upsert' : 'reference';
830
861
  };
831
- await (toInsert.length && toUpsert.length ? this.atomically(write) : write());
832
- return ids;
862
+ return this.writeEach(payload, branch, {
863
+ insert: (rows) => this.insertIds(entity, rows),
864
+ upsert: (rows) => this.upsertMany(entity, { $conflict: keySet(meta.ids) }, rows),
865
+ reference: async (rows) => writtenIds(meta, rows),
866
+ }, ['reference']);
833
867
  }
834
868
  /**
835
869
  * Writes the target of each to-one `rows` hold the key of, and points each row at its own: a row naming
@@ -1116,21 +1150,14 @@ export class AbstractQuerier {
1116
1150
  }
1117
1151
  await this.emitHook(entity, 'afterLoad', rows);
1118
1152
  }
1119
- /** The ids of `rows`, read by the columns an upsert matches them on, as {@link rowsByConflict} reads them. */
1120
- async idsByConflict(entity, conflictKeys, rows) {
1121
- const meta = getMeta(entity);
1122
- const found = await this.rowsByConflict(entity, conflictKeys, rows, meta.ids);
1123
- return found.map((row) => row && idOf(meta, row));
1124
- }
1125
1153
  /**
1126
- * The row each of `rows` matches on the columns an upsert matches on, with `select`, soft-deleted rows included
1127
- * since a unique key holds across both, held as {@link readForWrite} holds its rows. One no row matches, or two do,
1128
- * reads none, since a missing row is honest where a guessed one is not; a null key never conflicts, so is not read.
1154
+ * The row each of `rows` matches on the columns an upsert matches on, each naming every one, with `select`,
1155
+ * soft-deleted rows included since a unique key holds across both, held as {@link readForWrite} holds its rows. One
1156
+ * no row matches, or two do, reads none, since a missing row is honest where a guessed one is not.
1129
1157
  */
1130
1158
  async rowsByConflict(entity, conflictKeys, rows, select) {
1131
1159
  const keys = getKeys(conflictKeys);
1132
- const named = rows.filter((row) => namesEvery(row, keys));
1133
- const distinct = [...new Map(named.map((row) => [rowKey(row, keys), row])).values()];
1160
+ const distinct = [...new Map(rows.map((row) => [rowKey(row, keys), row])).values()];
1134
1161
  const byConflict = new Map();
1135
1162
  for (const q of this.keyedReads(keys, distinct, [...new Set([...select, ...keys])])) {
1136
1163
  for (const row of await this.readForWrite(entity, q, UPDATING_DELETED)) {
@@ -1140,20 +1167,6 @@ export class AbstractQuerier {
1140
1167
  }
1141
1168
  return rows.map((row) => byConflict.get(rowKey(row, keys)));
1142
1169
  }
1143
- /**
1144
- * `ids` completed where an upsert reported no id for a row whose key it does not keep (`kept`, asked before the
1145
- * write fills one in): read back by the conflict columns.
1146
- */
1147
- async withUnreportedIds(entity, conflictKeys, payload, ids, kept) {
1148
- const unplaced = payload.flatMap((_, index) => (ids[index] === undefined && !kept[index] ? [index] : []));
1149
- if (unplaced.length) {
1150
- const found = await this.idsByConflict(entity, conflictKeys, unplaced.map((index) => payload[index]));
1151
- unplaced.forEach((index, position) => {
1152
- ids[index] = found[position];
1153
- });
1154
- }
1155
- return ids;
1156
- }
1157
1170
  /** Reads of the rows matching one of `rows` on `keys`, as many per statement as a key list takes, selecting `select`. */
1158
1171
  keyedReads(keys, rows, select) {
1159
1172
  const $select = keySet(select);
@@ -1,7 +1,7 @@
1
1
  import type { AbstractSqlDialect } from '../dialect/index.js';
2
- import type { EntityData, EntityMeta, ExtraOptions, Query, QueryAggregate, QueryUpsert, QueryPage, StatementOptions, QuerySearch, QueryUpdateResult, RawRow, SavepointCommand, SqlQuerier, SqlStatement, Type, TransactionOptions, UpdatePayload, ReportedWrite } from '../type/index.js';
2
+ import type { EntityData, EntityMeta, ExtraOptions, WrittenId, Query, QueryAggregate, QueryUpsert, QueryPage, StatementOptions, QuerySearch, QueryUpdateResult, RawRow, SavepointCommand, SqlQuerier, SqlStatement, Type, TransactionOptions, UpdatePayload, ReportedWrite } from '../type/index.js';
3
3
  import type { SqlExecution } from '../util/sql.util.js';
4
- import { AbstractQuerier, type UpsertedId, type ReportingWrites } from './abstractQuerier.js';
4
+ import { AbstractQuerier, type ReportingWrites } from './abstractQuerier.js';
5
5
  /** A statement as it is sent: its SQL and the values it binds. */
6
6
  export type BoundStatement = {
7
7
  readonly sql: string;
@@ -123,17 +123,16 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
123
123
  /** The writes reading their rows off their own statement, where {@link AbstractSqlDialect.reportsWrite} says so. */
124
124
  protected reportingWrites<E>(meta: EntityMeta<E>, write: ReportedWrite): ReportingWrites | undefined;
125
125
  /**
126
- * The id each row got: off the upsert's `RETURNING` where it has one, else off the header. A row reported none of,
127
- * skipped by `DO NOTHING` or its `$where`, is read back by its conflict keys, unless it keeps its own key (`kept`,
128
- * asked before the statement fills `onInsert` keys in).
126
+ * The id each row got: off the upsert's `RETURNING` where it has one, else off the header, none for a row skipped by
127
+ * `DO NOTHING` or its `$where`.
129
128
  */
130
- protected internalUpsertMany<E extends object>(entity: Type<E>, q: QueryUpsert<E>, payload: E[]): Promise<(UpsertedId<E> | undefined)[]>;
129
+ protected internalUpsertMany<E extends object>(entity: Type<E>, q: QueryUpsert<E>, payload: E[]): Promise<(WrittenId<E> | undefined)[]>;
131
130
  /** The ids an upsert's header reports, by index: a statement of one row assigning a found row names its key. */
132
131
  private headerIds;
133
132
  /**
134
133
  * The rows of `payload` an upsert writes, in its order, with the fields `keys` names, off its `RETURNING`: matched by
135
- * the conflict keys `keys` includes, as no engine promises that order. `undefined` for a row it kept, or with no
136
- * conflict key. The statement fills `payload`'s `onInsert` fields.
134
+ * the conflict keys `keys` includes, as no engine promises that order. `undefined` for a row it kept. The statement
135
+ * fills `payload`'s `onInsert` fields.
137
136
  */
138
137
  private upsertedRows;
139
138
  /**
@@ -1,8 +1,8 @@
1
1
  import { AGGREGATE_VALUE_ALIAS, KEY_DEFAULT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
2
2
  import { getMeta } from '../entity/index.js';
3
- import { generatesKey, idOf, namesEvery, namesKey, soleId } from '../entity/metadata/definition.js';
3
+ import { generatesKey, idOf, namesKey, soleId } from '../entity/metadata/definition.js';
4
4
  import { QuerySql } from '../type/querySql.js';
5
- import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, upsertKeepsOwnKey, getKeys, rowKey, } from '../util/index.js';
5
+ import { buildUpdateResult, chunk, clone, getInsertFieldKeys, insertShapeOf, getKeys, rowKey } from '../util/index.js';
6
6
  import { sql, statementOf } from '../util/sql.js';
7
7
  import { UqlUsageError } from '../util/uqlError.js';
8
8
  import { AbstractQuerier } from './abstractQuerier.js';
@@ -394,31 +394,19 @@ export class AbstractSqlQuerier extends AbstractQuerier {
394
394
  #reportingWrites = {
395
395
  update: (entity, q, payload, opts, keys) => this.readRows((ctx) => this.dialect.update(ctx, entity, q, payload, opts, keys)),
396
396
  delete: (entity, q, opts, keys) => this.readRows((ctx) => this.dialect.delete(ctx, entity, q, opts, keys)),
397
- upsert: (entity, q, payload, keys) => {
398
- const nullKey = getKeys(q.$conflict).find((key) => payload.some((row) => row[key] === null));
399
- if (nullKey !== undefined) {
400
- throw new UqlUsageError(`a row's '${nullKey}' is null: no row reads back by it, so its upsert cannot report it`);
401
- }
402
- return this.upsertedRows(entity, q, clone(payload), keys);
403
- },
397
+ upsert: (entity, q, payload, keys) => this.upsertedRows(entity, q, clone(payload), keys),
404
398
  insert: (entity, rows, keys) => this.insertedRows(entity, rows, keys),
405
399
  };
406
400
  /**
407
- * The id each row got: off the upsert's `RETURNING` where it has one, else off the header. A row reported none of,
408
- * skipped by `DO NOTHING` or its `$where`, is read back by its conflict keys, unless it keeps its own key (`kept`,
409
- * asked before the statement fills `onInsert` keys in).
401
+ * The id each row got: off the upsert's `RETURNING` where it has one, else off the header, none for a row skipped by
402
+ * `DO NOTHING` or its `$where`.
410
403
  */
411
404
  async internalUpsertMany(entity, q, payload) {
412
- if (!payload.length) {
413
- return [];
414
- }
415
405
  payload = clone(payload);
416
406
  const meta = getMeta(entity);
417
- const kept = payload.map((row) => upsertKeepsOwnKey(meta, q.$conflict, row));
418
- const ids = this.dialect.features.reportsWrites.includes('upsert')
407
+ return this.dialect.features.reportsWrites.includes('upsert')
419
408
  ? (await this.upsertedRows(entity, q, payload, [...meta.ids, ...getKeys(q.$conflict)])).map((row) => row && idOf(meta, row))
420
- : await this.headerIds(entity, q, payload);
421
- return this.withUnreportedIds(entity, q.$conflict, payload, ids, kept);
409
+ : this.headerIds(entity, q, payload);
422
410
  }
423
411
  /** The ids an upsert's header reports, by index: a statement of one row assigning a found row names its key. */
424
412
  async headerIds(entity, q, payload) {
@@ -434,14 +422,14 @@ export class AbstractSqlQuerier extends AbstractQuerier {
434
422
  }
435
423
  /**
436
424
  * The rows of `payload` an upsert writes, in its order, with the fields `keys` names, off its `RETURNING`: matched by
437
- * the conflict keys `keys` includes, as no engine promises that order. `undefined` for a row it kept, or with no
438
- * conflict key. The statement fills `payload`'s `onInsert` fields.
425
+ * the conflict keys `keys` includes, as no engine promises that order. `undefined` for a row it kept. The statement
426
+ * fills `payload`'s `onInsert` fields.
439
427
  */
440
428
  async upsertedRows(entity, q, payload, keys) {
441
429
  const conflictKeys = getKeys(q.$conflict);
442
430
  const read = await this.readEach(this.upsertGroups(entity, q, payload).map(({ indexes }) => (ctx) => this.dialect.upsert(ctx, entity, q, indexes.map((index) => payload[index]), keys)));
443
431
  const written = new Map(read.flat().map((row) => [rowKey(row, conflictKeys), row]));
444
- return payload.map((row) => namesEvery(row, conflictKeys) ? written.get(rowKey(row, conflictKeys)) : undefined);
432
+ return payload.map((row) => written.get(rowKey(row, conflictKeys)));
445
433
  }
446
434
  /**
447
435
  * An upsert's statements: one per shape, each split again to fit the bind budget, less what its assignments bind
@@ -84,10 +84,10 @@ export interface Querier extends UniversalQuerier {
84
84
  }, opts?: QueryOptions & WriteOptions<E, S, V, W>) => Promise<WriteResults<E, S, V, W>['affectedMany']>) & UniversalQuerier['deleteMany'];
85
85
  upsertOne: (<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(q: QueryUpsert<E> & {
86
86
  $entity: Type<E>;
87
- }, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>) => Promise<WriteResults<E, S, V, W>['upserted']>) & UniversalQuerier['upsertOne'];
87
+ }, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>) => Promise<WriteResults<E, S, V, W>['written']>) & UniversalQuerier['upsertOne'];
88
88
  upsertMany: (<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(q: QueryUpsert<E> & {
89
89
  $entity: Type<E>;
90
- }, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>) => Promise<WriteResults<E, S, V, W>['upserted'][]>) & UniversalQuerier['upsertMany'];
90
+ }, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>) => Promise<WriteResults<E, S, V, W>['written'][]>) & UniversalQuerier['upsertMany'];
91
91
  /**
92
92
  * whether this querier is in a transaction or not.
93
93
  */
@@ -525,14 +525,12 @@ export type WriteOptions<E, S extends FieldKey<E> = FieldKey<E>, V = BooleanLike
525
525
  /** What each kind of write resolves to: its ids or its count where it reads nothing back, else the rows it reads. */
526
526
  export type WriteResults<E, S, V, W = false> = [W] extends [true] ? ReturnedRows<Pick<E, FieldKey<E>>> : [W] extends [false] ? WrittenIds<E> : [S] extends [never] ? WrittenIds<E> : ReturnedRows<ReturnedRow<E, S, V>>;
527
527
  type WrittenIds<E> = {
528
- readonly inserted: NonNullable<WrittenId<E>>;
529
- readonly upserted: WrittenId<E> | undefined;
528
+ readonly written: NonNullable<WrittenId<E>>;
530
529
  readonly affected: number;
531
530
  readonly affectedMany: number;
532
531
  };
533
532
  type ReturnedRows<R> = {
534
- readonly inserted: R;
535
- readonly upserted: R;
533
+ readonly written: R;
536
534
  readonly affected: R | undefined;
537
535
  readonly affectedMany: R[];
538
536
  };
@@ -84,12 +84,12 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
84
84
  */
85
85
  findManyStream: EntityRead<'many', 'stream', 'server', QueryOptions>;
86
86
  /** Insert a record and resolve to its id, or the row `returning` reads back. See {@link UniversalQuerier.insertMany}. */
87
- insertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted']>;
87
+ insertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
88
88
  /**
89
89
  * Insert records in as few statements as the bind limit allows, resolving to their ids in payload order, or
90
90
  * the rows `returning` reads back.
91
91
  */
92
- insertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted'][]>;
92
+ insertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
93
93
  /** Update the record with the given primary key; resolves to the number of affected rows, or the row `returning` reads back. */
94
94
  updateOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['affected']>;
95
95
  /** Update the records matching the query; resolves to the number of affected rows, or the rows `returning` reads back. */
@@ -103,13 +103,13 @@ export interface UniversalQuerier extends SharedQuerier<'server', QueryOptions>
103
103
  * conflicting row matching `q.$where` takes the payload less those keys, or `q.$update` as `updateMany` takes an
104
104
  * update: `{ uses: { $inc: 1 } }` counts, and `{}` leaves the row as it is. Either branch writes the cascaded relations it is given.
105
105
  */
106
- upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['upserted']>;
106
+ upsertOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
107
107
  /** Insert or update records by `q.$conflict`'s keys, as `upsertOne` does; resolves to their ids in payload order, or the rows. */
108
- upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['upserted'][]>;
108
+ upsertMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, q: QueryUpsert<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
109
109
  /** Insert a record, or upsert one naming its key; resolves to its id, or the row `returning` reads back. */
110
- saveOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted']>;
110
+ saveOne<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: EntityWrite<E>, opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written']>;
111
111
  /** Insert records, or upsert those naming their key; resolves to their ids in payload order, or the rows. */
112
- saveMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['inserted'][]>;
112
+ saveMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true, const W extends boolean = false>(entity: Type<E>, payload: readonly EntityWrite<E>[], opts?: WriteOptions<E, S, V, W>): Promise<WriteResults<E, S, V, W>['written'][]>;
113
113
  /**
114
114
  * Restore soft-deleted records (sets the soft-delete field back to `null`). Throws if the
115
115
  * entity has no soft-delete field.
@@ -1,5 +1,5 @@
1
1
  import type { IndexType } from '../schema/types.js';
2
- import { type AggregateCall, type CascadeType, type EntityAccess, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonArrayUpdateOp, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryConflictKeys, type QueryUpsert, type QueryGroupMap, type QueryOptions, QuerySql, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type StatementOptions, type UpdatePayload, type VectorDistance } from '../type/index.js';
2
+ import { type AggregateCall, type CascadeType, type EntityAccess, type EntityData, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonArrayUpdateOp, type JsonUpdateOp, type OnFieldCallback, type QueryAggMap, type QueryUpsert, type QueryGroupMap, type QueryOptions, QuerySql, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySortDirection, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorQuery, type QueryVectorSearch, type QueryWhere, type RelationKey, type StatementOptions, type UpdatePayload, type VectorDistance } from '../type/index.js';
3
3
  import { type CallbackKey } from './field.util.js';
4
4
  /** The keys of `payload` a write persists as columns. */
5
5
  export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
@@ -35,11 +35,6 @@ export declare function deletionOf<E, O extends QueryOptions>(meta: EntityMeta<E
35
35
  * does, and by default the payload less its key and what it matched on.
36
36
  */
37
37
  export declare function foundRowAssigned<E>(meta: EntityMeta<E>, q: QueryUpsert<E>, row: EntityData<E>): UpdatePayload<E> | undefined;
38
- /**
39
- * Whether an upsert of `row` lands under the key it names: it names one and matches on it, so a row it finds
40
- * has that key too. Elsewhere the key is the found row's, which the upsert reads back.
41
- */
42
- export declare function upsertKeepsOwnKey<E>(meta: EntityMeta<E>, conflictKeys: QueryConflictKeys<E>, row: E): boolean;
43
38
  /**
44
39
  * Where a write runs: a statement uql sends, or a trigger's body, which runs no JavaScript, so a fill there is
45
40
  * only a value or SQL; calling a callback would bake one value into the trigger.
@@ -1,5 +1,4 @@
1
1
  import { getContext } from '../context/context.js';
2
- import { namesKey } from '../entity/metadata/definition.js';
3
2
  import { QuerySql, resolveAggregateOp, } from '../type/index.js';
4
3
  import { DEFAULT_VECTOR_DISTANCE, VECTOR_INDEX_TYPES } from '../type/vector.js';
5
4
  import { defaultReadKeys, fieldKeys, isDatabaseWritten, isWrittenOn, jsonKey, jsonPathKeys, } from './field.util.js';
@@ -88,13 +87,6 @@ export function foundRowAssigned(meta, q, row) {
88
87
  }
89
88
  return hasKeys(update) ? { ...update } : undefined;
90
89
  }
91
- /**
92
- * Whether an upsert of `row` lands under the key it names: it names one and matches on it, so a row it finds
93
- * has that key too. Elsewhere the key is the found row's, which the upsert reads back.
94
- */
95
- export function upsertKeepsOwnKey(meta, conflictKeys, row) {
96
- return namesKey(meta, row) && meta.ids.every((key) => Object.hasOwn(conflictKeys, key));
97
- }
98
90
  /** Fills each field `callbackKey` generates on `payload` in place, where the caller left it unset, as `scope` can. */
99
91
  export function fillOnFields(meta, payload, callbackKey, scope = 'statement') {
100
92
  const payloads = Array.isArray(payload) ? payload : [payload];
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "homepage": "https://uql-orm.dev",
4
4
  "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
5
5
  "license": "MIT",
6
- "version": "0.114.2",
6
+ "version": "0.114.4",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=22.18"
@@ -122,9 +122,9 @@
122
122
  "@electric-sql/pglite-pgvector": "0.0.16",
123
123
  "@libsql/client": "^0.18.0",
124
124
  "@neondatabase/serverless": "^1.2.0",
125
- "@nestjs/common": "^12.3.3",
126
- "@nestjs/core": "^12.3.3",
127
- "@nestjs/testing": "^12.3.3",
125
+ "@nestjs/common": "^12.4.2",
126
+ "@nestjs/core": "^12.4.2",
127
+ "@nestjs/testing": "^12.4.2",
128
128
  "@tursodatabase/database": "^0.8.3",
129
129
  "@tursodatabase/serverless": "^1.4.1",
130
130
  "@types/better-sqlite3": "^9.6.0",
@@ -142,7 +142,7 @@
142
142
  "pg-query-stream": "^4.17.1",
143
143
  "rxjs": "^7.8.2",
144
144
  "sqlite-vec": "^0.1.9",
145
- "ws": "^8.22.1"
145
+ "ws": "^8.22.2"
146
146
  },
147
147
  "author": "Roger Padilla",
148
148
  "repository": {
@@ -89,7 +89,7 @@ export class Post {
89
89
  ```
90
90
 
91
91
  - A column is a builder: `f.string()`, `f.text()`, `f.uuid()`, `f.number()`, `f.bigint()`, `f.decimal(precision?, scale?)`, `f.boolean()`, `f.date()`, `f.json(schema?)`, `f.jsonb(schema?)`, `f.vector(dimensions)`, `f.enum(values)`, `f.version()`, `f.column(type)` for any other SQL type uql names (`f.column('smallint')`, `f.column('date')` for a day with no time, `f.column('timestamptz')`), typed by its family, and `f.references(() => Target)` for a foreign key typed as the target's key. A type uql does not name is ``.columnType(sql`citext`)``. Only the methods a column's type takes exist: `.length()` is a string's, `.precision()` a number's or a date's. A builder is immutable, so `const money = f.decimal(12, 2)` is shared across fields, each chaining its own `.nullable()`.
92
- - A column is NOT NULL unless `.nullable()`. Declare a NOT NULL property `!` (`email!: string`), and `?` what an insert may omit: nullable columns (`title?: string | null`), `.eager(false)` and computed fields, relations, and the version uql fills. A key the database generates is `@Field(f.number().autoIncrement()) id?: number` (`f.bigint().autoIncrement()` past 2^53); `.id()` alone generates nothing, so `f.number().id()` is a key the caller supplies and `@Field` refuses `?` on it, as on a `.references()` key. A NOT NULL field something fills (`.default()`, `.onInsert()`, a generated key) stays `!` when listed in the class's `[filledKey]?: 'id' | 'createdAt'`: inserts may omit it, reads always have it. MongoDB fills a text key declared `?` and `_id`. `insertOne`, `insertMany`, `saveOne` and `saveMany` resolve to a defined key, so no `!`; an upsert's may be `undefined`. On SQL engines an insert leaving out a key nothing declared fills throws before writing. `defineEntity` works all of this out.
92
+ - A column is NOT NULL unless `.nullable()`. Declare a NOT NULL property `!` (`email!: string`), and `?` what an insert may omit: nullable columns (`title?: string | null`), `.eager(false)` and computed fields, relations, and the version uql fills. A key the database generates is `@Field(f.number().autoIncrement()) id?: number` (`f.bigint().autoIncrement()` past 2^53); `.id()` alone generates nothing, so `f.number().id()` is a key the caller supplies and `@Field` refuses `?` on it, as on a `.references()` key. A NOT NULL field something fills (`.default()`, `.onInsert()`, a generated key) stays `!` when listed in the class's `[filledKey]?: 'id' | 'createdAt'`: inserts may omit it, reads always have it. MongoDB fills a text key declared `?` and `_id`. `insertOne`, `insertMany`, `saveOne`, `saveMany`, `upsertOne` and `upsertMany` resolve to a defined key, so no `!`. On SQL engines an insert leaving out a key nothing declared fills throws before writing. `defineEntity` works all of this out.
93
93
  - `.default()` takes a value of the field's type, or SQL the database evaluates per row: `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``sql`...` ``. A plain string is always text, `'CURRENT_TIMESTAMP'` included. A JSON column defaults to a value, `.default({})` or `.default(0)`, never its JSON text (`'{}'`, `'0'` are refused); any other string there is a JSON string.
94
94
  - `Date` is an instant, stored in UTC to the millisecond. `f.decimal()` is exact text (`price?: string | null`); `f.number().precision(10).scale(2)` opts into a rounding JS number.
95
95
  - A JSON column's property is `Json<T>`: `settings?: Json<{ theme?: string }> | null`. A plain object type reads as a relation, which `$where`, `$sort` and the update operators refuse.
@@ -98,7 +98,7 @@ export class Post {
98
98
  - Optimistic lock: `@Field(f.version())` with `[versionKey]?: 'version'` on the class. An update, and an upsert or save of a row that exists, must carry the version it read; a stale one throws `UqlOptimisticLockError`.
99
99
  - Computed fields are `readonly`: ``@Computed((u) => f.string().as(sql`${u.first} || ' ' || ${u.last}`))``, `.stored()` for a generated column, or a relation aggregate, `@Computed((user) => user.posts.count())`.
100
100
  - Indexes, checks, filters and triggers are `@Entity` options, each entry made by the helper the callback is handed. A partial index's predicate is a query: `indexes: (post, index) => [index([post.authorId], { where: { archived: { $ne: true } } })]`. A JSON path is indexed off the column's ref, `index([user.settings.theme])`: https://uql-orm.dev/entities/indexes.md
101
- - Triggers run in the database: `triggers: (post, trigger) => [trigger({ on: 'afterUpdate', of: [post.status], run })]`, where `run` returns a body built from `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse(message)`. They skip entity filters and run no JavaScript: an insert fills an `.onInsert()` value or SQL, but an `insertInto` names every required column a callback fills (`.onInsert(() => crypto.randomUUID())`) where no database default does. MongoDB has none: https://uql-orm.dev/entities/triggers.md
101
+ - Triggers run in the database: `triggers: (post, trigger) => [trigger({ on: 'afterUpdate', of: [post.status], run })]`, where `run` returns a body built from `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse(message)`. `on` is one event: a body several events share is one `run` passed to each entry. They skip entity filters and run no JavaScript: an insert fills an `.onInsert()` value or SQL, but an `insertInto` names every required column a callback fills (`.onInsert(() => crypto.randomUUID())`) where no database default does. MongoDB has none: https://uql-orm.dev/entities/triggers.md
102
102
  - Hooks are methods with `this` bound to the payload: `@BeforeInsert()`, `@AfterInsert()`, and the same pairs for update, upsert and delete, plus `@AfterLoad()`. Changes to `this` in a before-hook are written. `upsert*` runs only the upsert pair, and `save*` the upsert pair for a row carrying its key. Each receives `{ querier, onCommit }`.
103
103
  - **MongoDB:** a `f.number()` key left to the database is refused, since MongoDB only generates ObjectIds. Declare it a string, or give it an `.onInsert()` generator.
104
104
 
@@ -195,7 +195,7 @@ const users = await pool.findMany(User, {
195
195
  });
196
196
  ```
197
197
 
198
- - Methods: `findMany`, `findOne`, `findOneById`, `findManyAndCount`, `findManyPage`, `findManyStream`, `count`, `estimatedCount`, `exists`, `aggregate`, `insertOne`, `insertMany`, `updateOneById`, `updateMany`, `saveOne`, `saveMany`, `upsertOne`, `upsertMany`, `deleteOneById`, `deleteMany`. Each takes the entity class first; on a querier, each taking a query also takes it as the query's `$entity`, so the whole call is JSON. Signatures: https://uql-orm.dev/querying/methods.md
198
+ - Methods: `findMany`, `findOne`, `findOneById`, `findManyAndCount`, `findManyPage`, `findManyStream`, `count`, `estimatedCount`, `exists`, `aggregate`, `insertOne`, `insertMany`, `updateOneById`, `updateMany`, `saveOne`, `saveMany`, `upsertOne`, `upsertMany`, `deleteOneById`, `deleteMany`. Each takes the entity class first; on a querier, each taking a query also takes it as the query's `$entity`, so the whole call is JSON. Whether anything matches is `exists`, which stops at the first row, never `count(...) > 0`. Signatures: https://uql-orm.dev/querying/methods.md
199
199
  - Query keys: `$select`, `$where`, `$populate`, `$count`, `$distinct`, `$sort`, `$skip`, `$limit`, `$lock`. `$select: { password: false }` reads every field but `password`. `$count: { posts: true }` counts a to-many under `_count` without loading it.
200
200
  - Results are narrowed to what the query selected and populated, at every depth. Reading an unselected field is a compile error. Name a shape with `QueryFindResult<User, 'id' | 'email'>`, or `QueryFindResult<User, typeof query>` for a query declared `as const satisfies Query<User>`. A function forwarding a query keeps the narrowing typed `<E extends object, const Q extends Query<E>>(entity: Type<E>, q: Captured<Query<E>, Q>): Promise<QueryFindResult<E, Q>[]>`.
201
201
  - `$populate` loads relations in the same statement. Nothing is lazy: an unpopulated relation is absent. A populated to-many is always a list. A to-one is optional unless `$required: true`, which keeps only the parents that have one.