uql-orm 0.107.3 → 0.108.0

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.
Files changed (89) hide show
  1. package/dist/browser/uql-browser.min.js +2 -2
  2. package/dist/browser/uql-browser.min.js.map +5 -5
  3. package/dist/cockroachdb/cockroachDialect.d.ts +1 -4
  4. package/dist/cockroachdb/cockroachDialect.js +1 -5
  5. package/dist/dialect/abstractSqlDialect.d.ts +84 -43
  6. package/dist/dialect/abstractSqlDialect.js +270 -192
  7. package/dist/dialect/aliases.d.ts +2 -0
  8. package/dist/dialect/aliases.js +2 -0
  9. package/dist/dialect/jsonSql.d.ts +9 -7
  10. package/dist/dialect/jsonSql.js +16 -10
  11. package/dist/dialect/mergeSqlDialect.d.ts +5 -7
  12. package/dist/dialect/mergeSqlDialect.js +20 -19
  13. package/dist/dialect/mysqlLikeSqlDialect.d.ts +12 -6
  14. package/dist/dialect/mysqlLikeSqlDialect.js +34 -12
  15. package/dist/dialect/operators.d.ts +7 -1
  16. package/dist/dialect/operators.js +37 -2
  17. package/dist/dialect/pgLikeSqlDialect.d.ts +4 -4
  18. package/dist/dialect/pgLikeSqlDialect.js +8 -7
  19. package/dist/entity/index.d.ts +1 -1
  20. package/dist/entity/index.js +1 -1
  21. package/dist/entity/metadata/definedFixture/author.d.ts +4 -4
  22. package/dist/entity/metadata/definedFixture/book.d.ts +5 -5
  23. package/dist/entity/metadata/definition.d.ts +2 -0
  24. package/dist/entity/metadata/definition.js +19 -11
  25. package/dist/index.d.ts +1 -1
  26. package/dist/index.js +1 -1
  27. package/dist/mariadb/mariaDialect.d.ts +2 -2
  28. package/dist/mariadb/mariaDialect.js +3 -2
  29. package/dist/migrate/codegen/fieldOptionsSource.js +28 -7
  30. package/dist/migrate/ddl/defaultSql.d.ts +3 -2
  31. package/dist/migrate/ddl/defaultSql.js +8 -12
  32. package/dist/migrate/ddl/mysqlTableDdl.js +1 -1
  33. package/dist/migrate/ddl/tableDdl.d.ts +1 -1
  34. package/dist/migrate/drift/driftDetector.js +10 -3
  35. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +2 -2
  36. package/dist/migrate/introspection/mssqlIntrospector.d.ts +2 -2
  37. package/dist/migrate/introspection/mysqlIntrospector.d.ts +2 -2
  38. package/dist/migrate/introspection/postgresIntrospector.d.ts +2 -2
  39. package/dist/migrate/introspection/sqliteIntrospector.d.ts +2 -2
  40. package/dist/migrate/migrator.js +2 -1
  41. package/dist/migrate/schemaChange.d.ts +0 -2
  42. package/dist/migrate/schemaChange.js +1 -4
  43. package/dist/migrate/schemaGenerator.d.ts +2 -2
  44. package/dist/migrate/triggerSql.js +11 -15
  45. package/dist/mongodb/mongoDialect.d.ts +6 -1
  46. package/dist/mongodb/mongoDialect.js +90 -46
  47. package/dist/mongodb/mongoSchemaGenerator.js +2 -2
  48. package/dist/mongodb/mongodbQuerier.d.ts +7 -9
  49. package/dist/mongodb/mongodbQuerier.js +54 -47
  50. package/dist/mssql/mssqlDialect.d.ts +9 -9
  51. package/dist/mssql/mssqlDialect.js +51 -28
  52. package/dist/mssql/mssqlWireTypes.d.ts +1 -4
  53. package/dist/mssql/mssqlWireTypes.js +19 -10
  54. package/dist/querier/abstractQuerier.d.ts +53 -29
  55. package/dist/querier/abstractQuerier.js +154 -102
  56. package/dist/querier/abstractSqlQuerier.d.ts +41 -10
  57. package/dist/querier/abstractSqlQuerier.js +145 -79
  58. package/dist/schema/declaredColumn.js +2 -2
  59. package/dist/schema/schemaASTDiffer.d.ts +3 -3
  60. package/dist/schema/sqlExpression.d.ts +7 -5
  61. package/dist/schema/sqlExpression.js +20 -16
  62. package/dist/schema/types.d.ts +8 -2
  63. package/dist/sqlite/sqliteDialect.js +1 -2
  64. package/dist/type/definedEntity.d.ts +5 -5
  65. package/dist/type/dialect.d.ts +26 -15
  66. package/dist/type/entity.d.ts +14 -8
  67. package/dist/type/query.d.ts +7 -2
  68. package/dist/type/queryAggregate.d.ts +4 -4
  69. package/dist/type/querySql.d.ts +4 -1
  70. package/dist/type/querySql.js +5 -1
  71. package/dist/type/queryWhere.d.ts +16 -11
  72. package/dist/type/universalQuerier.d.ts +7 -7
  73. package/dist/util/ddlExpression.util.d.ts +5 -0
  74. package/dist/util/ddlExpression.util.js +9 -2
  75. package/dist/util/dialect.util.d.ts +14 -6
  76. package/dist/util/dialect.util.js +17 -13
  77. package/dist/util/field.util.d.ts +12 -0
  78. package/dist/util/field.util.js +17 -1
  79. package/dist/util/fieldOption.util.js +5 -1
  80. package/dist/util/object.util.d.ts +4 -0
  81. package/dist/util/object.util.js +13 -0
  82. package/dist/util/query.util.d.ts +5 -3
  83. package/dist/util/query.util.js +7 -2
  84. package/dist/util/sql.d.ts +25 -7
  85. package/dist/util/sql.js +58 -18
  86. package/dist/util/triggerWrite.d.ts +7 -4
  87. package/dist/util/triggerWrite.js +5 -4
  88. package/package.json +1 -1
  89. package/skills/uql-orm/SKILL.md +10 -8
@@ -1,8 +1,8 @@
1
- import { getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
1
+ import { getMeta, idOf, namesEvery, namesKey, relationOf } from '../entity/index.js';
2
2
  import { SAVEPOINT_PREFIX } from '../dialect/aliases.js';
3
3
  import { namesRows } from '../dialect/operators.js';
4
4
  import { parseQueryLock } from '../type/index.js';
5
- import { childrenExcept, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, getKeys, omitKeys, deletionOf, hasKeys, getRelationRequestSummary, guardWrite, idOnlyQuery, keyJoins, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, pointAt, queryLoggerFor, parseRelationAtKey, rowKey, runHooks, securityConditions, someKey, targetJoins, whereEach, whereIds, whereKeysIn, whereWith, withDeleted, cascadingRelations, holdsForeignKey, } from '../util/index.js';
5
+ import { childrenExcept, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, getKeys, deletionOf, hasKeys, getRelationRequestSummary, guardWrite, idOnlyQuery, keyJoins, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, pointAt, queryLoggerFor, parseRelationAtKey, rowKey, runHooks, securityConditions, someKey, targetJoins, foundRowAssigned, whereAnd, whereIds, whereKeysIn, whereWith, withDeleted, cascadingRelations, holdsForeignKey, } from '../util/index.js';
6
6
  import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
7
7
  import { keysetRead } from './keyset.js';
8
8
  import { enrichError } from './queryError.js';
@@ -55,16 +55,6 @@ function lockVersion(meta, key, q, row) {
55
55
  // the version contradicts itself into matching nothing, which is what they asked for.
56
56
  return { expected, next, q: { ...q, $where: whereWith(key, expected, q.$where) } };
57
57
  }
58
- /**
59
- * Refuses a write that cannot carry the lock, rather than writing over whatever the row holds now.
60
- * An upsert has no portable way to match a version - MySQL's `ON DUPLICATE KEY UPDATE` takes no
61
- * `WHERE` - and a write the library itself composes has no version to carry.
62
- */
63
- function assertUnversioned(meta, what) {
64
- if (meta.version) {
65
- throw new UqlUsageError(`cannot ${what} the versioned '${entityName(meta)}': it carries no '${meta.version}' to match, so update it by id`);
66
- }
67
- }
68
58
  /**
69
59
  * What a versioned update has to be for its lock to hold: one row, named by its id, written by one
70
60
  * statement. A filter naming more than one row cannot say which of them the payload's single version
@@ -87,10 +77,12 @@ function writtenIds(meta, rows) {
87
77
  }
88
78
  /**
89
79
  * Whether an upsert has to read before it writes: `ON CONFLICT` updates a guarded row whatever tenant it belongs
90
- * to, and writes no relation.
80
+ * to, writes no relation, and cannot tell a found row it skipped for a stale version.
91
81
  */
92
82
  function upsertsByReading(meta, rows, update) {
93
- return securityConditions(meta).length > 0 || writesRelations(meta, update ? [...rows, update] : rows);
83
+ return (meta.version !== undefined ||
84
+ securityConditions(meta).length > 0 ||
85
+ writesRelations(meta, update ? [...rows, update] : rows));
94
86
  }
95
87
  /**
96
88
  * Writes the key an upsert reported onto each row, over the one it named: a found row keeps its own, and a row
@@ -324,11 +316,25 @@ export class AbstractQuerier {
324
316
  return this.internalAggregate(entity, q, opts);
325
317
  }
326
318
  async insertOne(entity, payload, opts) {
327
- const [written] = await this.writeReturning(entity, () => this.insertIds(entity, [payload]), opts);
319
+ const [written] = await this.insertWritten(entity, [payload], opts);
328
320
  return written;
329
321
  }
330
322
  async insertMany(entity, payload, opts) {
331
- return this.writeReturning(entity, () => this.insertIds(entity, payload), opts);
323
+ return this.insertWritten(entity, payload, opts);
324
+ }
325
+ /**
326
+ * What an insert reports: the ids, or the rows `returning` asks for, off the insert's own statement where
327
+ * {@link reportingWrites} can, else read back.
328
+ */
329
+ insertWritten(entity, payload, opts) {
330
+ const meta = getMeta(entity);
331
+ const keys = returnedKeys(meta, opts?.returning);
332
+ const reportingWrites = keys && this.reportingWrites(meta, 'insert');
333
+ if (!keys || !reportingWrites || !payload.length) {
334
+ return this.writtenOrReadBack(entity, () => this.insertIds(entity, payload), opts);
335
+ }
336
+ const read = [...new Set([...keys, ...meta.ids])];
337
+ return this.inserting(entity, payload, async (rows) => this.returned(entity, await this.insertRows(entity, rows, (inserted) => reportingWrites.insert(entity, inserted, read)), keys));
332
338
  }
333
339
  /**
334
340
  * The ids of the rows inserted, in payload order. The `onInsert` values are filled before the write, so
@@ -339,17 +345,21 @@ export class AbstractQuerier {
339
345
  return [];
340
346
  }
341
347
  const meta = getMeta(entity);
342
- const insert = () => this.hooked(entity, 'Insert', payload, async (rows) => {
343
- await this.insertRows(entity, rows);
348
+ return this.inserting(entity, payload, async (rows) => {
349
+ await this.insertRows(entity, rows, (inserting) => this.internalInsertMany(entity, inserting));
344
350
  return writtenIds(meta, rows);
345
351
  });
346
- return writesRelations(meta, payload) ? this.atomically(insert) : insert();
352
+ }
353
+ /** `insert` of `payload` between the insert hooks, {@link atomically} where it writes relations too. */
354
+ inserting(entity, payload, insert) {
355
+ const write = () => this.hooked(entity, 'Insert', payload, insert);
356
+ return writesRelations(getMeta(entity), payload) ? this.atomically(write) : write();
347
357
  }
348
358
  /**
349
- * The ids `write` reports, or, where `opts` asks for `returning`, the rows they name, read back in the same
350
- * transaction with only the fields it lists.
359
+ * The ids `write` reports, or, where `opts` asks for `returning`, the rows they name, read back
360
+ * {@link atomically} with the write and only the fields it lists.
351
361
  */
352
- writeReturning(entity, write, opts) {
362
+ writtenOrReadBack(entity, write, opts) {
353
363
  const keys = returnedKeys(getMeta(entity), opts?.returning);
354
364
  return keys ? this.atomically(async () => this.readBack(entity, await write(), keys)) : write();
355
365
  }
@@ -382,16 +392,17 @@ export class AbstractQuerier {
382
392
  }
383
393
  /**
384
394
  * Writes `rows` and their relations: the to-ones they hold the keys of first, so each row inserts
385
- * pointing at its own, then the rows, then their children by the keys the rows got. An insert, and the
386
- * insert half of a read upsert.
395
+ * pointing at its own, then the rows, by `insert`, then their children by the keys the rows got. An insert,
396
+ * and the insert half of a read upsert. Answers what `insert` reports.
387
397
  */
388
- async insertRows(entity, rows) {
398
+ async insertRows(entity, rows, insert) {
389
399
  const meta = getMeta(entity);
390
400
  await this.writeHeldReferences(entity, rows);
391
401
  fillOnFields(meta, rows, 'onInsert');
392
402
  guardWrite(meta, rows, 'insert');
393
- await this.internalInsertMany(entity, rows);
403
+ const inserted = await insert(rows);
394
404
  await this.insertChildren(entity, rows);
405
+ return inserted;
395
406
  }
396
407
  async updateOneById(entity, id, payload, opts) {
397
408
  assertIdValue(entity, id);
@@ -413,30 +424,34 @@ export class AbstractQuerier {
413
424
  if (!keys) {
414
425
  return this.updateMatching(entity, q, payload, opts);
415
426
  }
416
- const { writesReturning } = this;
417
- if (writesReturning && this.updatesByFilter(entity, q, payload)) {
418
- return this.updateReturning(writesReturning, entity, q, payload, rest, keys);
419
- }
420
- return this.atomically(async () => {
421
- const ids = await this.settleIds(entity, q, rest);
422
- await this.updateMatching(entity, q, payload, rest, ids);
423
- return this.readBack(entity, ids, keys, rest);
427
+ const reportingWrites = this.reportingWrites(meta, 'update');
428
+ const reporting = (row) => reportingWrites && this.updatesByFilter(entity, q, row) ? reportingWrites : undefined;
429
+ // Decided again on the row the hooks hand over, which may now write a relation one statement cannot.
430
+ const write = () => this.hooked(entity, 'Update', [payload], async ([row]) => {
431
+ const writes = reporting(row);
432
+ if (writes) {
433
+ return this.updateReturning(writes, entity, q, row, rest, keys);
434
+ }
435
+ return this.atomically(async () => {
436
+ const ids = await this.settleIds(entity, q, rest);
437
+ await this.updateRows(entity, q, row, rest, meta.version, ids);
438
+ return this.readBack(entity, ids, keys, rest);
439
+ });
424
440
  });
441
+ return reporting(payload) ? write() : this.atomically(write);
425
442
  }
426
443
  /**
427
- * An update of one statement reporting the rows it wrote, between the update hooks. A payload writing no
428
- * column writes nothing, so the rows it names are read instead.
444
+ * An update of one statement reporting the rows it wrote. A row writing no column writes nothing, so the rows
445
+ * it names are read instead.
429
446
  */
430
- updateReturning(writes, entity, q, payload, opts, keys) {
447
+ async updateReturning(writes, entity, q, row, opts, keys) {
431
448
  const meta = getMeta(entity);
432
449
  const read = [...keys, ...meta.ids];
433
- return this.hooked(entity, 'Update', [payload], async ([row]) => {
434
- await this.prepareUpdate(entity, row);
435
- const rows = writesColumns(meta, row)
436
- ? await writes.update(entity, q, row, opts, read)
437
- : await this.internalFindMany(entity, { ...q, $select: keySet(read) }, opts);
438
- return this.returned(entity, rows, keys);
439
- });
450
+ await this.prepareUpdate(entity, row);
451
+ const rows = writesColumns(meta, row)
452
+ ? await writes.update(entity, q, row, opts, read)
453
+ : await this.internalFindMany(entity, { ...q, $select: keySet(read) }, opts);
454
+ return this.returned(entity, rows, keys);
440
455
  }
441
456
  /**
442
457
  * Updates the rows `q` matches, or the ones `settled` already names, between the update hooks, atomically
@@ -541,14 +556,15 @@ export class AbstractQuerier {
541
556
  /**
542
557
  * The rows a write reads before it writes, held until the open transaction ends where the engine has row
543
558
  * locks, so a racing writer waits for the commit; outside a transaction a lock would hold nothing. Elsewhere
544
- * the transaction is the guard: libSQL and Turso take the write lock at `BEGIN`, SQLite and MongoDB fail the racer.
559
+ * the transaction is the guard: libSQL and Turso take the write lock at `BEGIN`, SQLite fails the racer, and so
560
+ * does MongoDB inside a transaction the caller opens.
545
561
  */
546
562
  readForWrite(entity, q, opts) {
547
563
  const held = this.dialect.features.rowLocks && this.scopeHere() ? { ...q, $lock: true } : q;
548
564
  return this.internalFindMany(entity, held, opts);
549
565
  }
550
- /** How the engine writes rows and reports them in one statement, or `undefined` where a write reads them first. */
551
- get writesReturning() {
566
+ /** How the engine writes rows of `meta` and reports them in one statement, or `undefined` where `write` reads them. */
567
+ reportingWrites(_meta, _write) {
552
568
  return undefined;
553
569
  }
554
570
  async restoreOneById(entity, id) {
@@ -563,61 +579,93 @@ export class AbstractQuerier {
563
579
  const $where = whereWith(meta.softDelete, { $ne: null }, q.$where);
564
580
  // No version: a restore only undoes the stamp a delete left, which takes none either, and two of
565
581
  // them racing agree on the result anyway. A lock is for content, and a restore writes none.
566
- return this.unversionedUpdate(entity, { ...q, $where }, { [meta.softDelete]: null }, withDeleted());
582
+ return this.hooked(entity, 'Update', [{ [meta.softDelete]: null }], ([row]) => this.updateRows(entity, { ...q, $where }, row, withDeleted(), undefined));
567
583
  }
568
- /**
569
- * An update the library writes of its own, hooked as a caller's is but carrying no version: a restore's
570
- * cleared stamp, or a row pointed at the relation just inserted for it.
571
- */
572
- unversionedUpdate(entity, q, payload, opts) {
573
- return this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, undefined));
574
- }
575
- async upsertOne(entity, conflictPaths, payload, update, opts) {
576
- const [written] = await this.upsertMany(entity, conflictPaths, [payload], update, opts);
584
+ async upsertOne(entity, q, payload, update, opts) {
585
+ const [written] = await this.upsertMany(entity, q, [payload], update, opts);
577
586
  return written;
578
587
  }
579
- async upsertMany(entity, conflictPaths, payload, update, opts) {
588
+ async upsertMany(entity, q, payload, update, opts) {
580
589
  const meta = getMeta(entity);
581
- assertUnversioned(meta, "'upsert'");
590
+ const keys = returnedKeys(meta, opts?.returning);
591
+ const reportingWrites = keys && this.reportingWrites(meta, 'upsert');
582
592
  // Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither
583
- // the insert's nor the update's pair fits.
584
- const upsert = () => this.hooked(entity, 'Upsert', payload, async (rows) => {
585
- const ids = upsertsByReading(meta, rows, update)
586
- ? await this.readThenUpsert(entity, conflictPaths, rows, update)
587
- : await this.internalUpsertMany(entity, conflictPaths, rows, update);
588
- adoptReportedIds(meta, rows, ids);
589
- return writtenIds(meta, rows);
590
- });
591
- return this.writeReturning(entity, upsert, opts);
593
+ // the insert's nor the update's pair fits. How to write is decided on the rows the hooks hand over.
594
+ if (!keys || !reportingWrites) {
595
+ return this.writtenOrReadBack(entity, () => this.hooked(entity, 'Upsert', payload, (rows) => this.upsertIds(entity, q, rows, update)), opts);
596
+ }
597
+ return this.atomically(() => this.hooked(entity, 'Upsert', payload, async (rows) => upsertsByReading(meta, rows, update)
598
+ ? this.readBack(entity, await this.upsertIds(entity, q, rows, update), keys)
599
+ : this.upsertReturning(reportingWrites, entity, q, rows, update, keys)));
600
+ }
601
+ /** Upserts `rows`, reading first where {@link upsertsByReading} says so, and answers the id each row got. */
602
+ async upsertIds(entity, q, rows, update) {
603
+ const meta = getMeta(entity);
604
+ const ids = upsertsByReading(meta, rows, update)
605
+ ? await this.readThenUpsert(entity, q, rows, update)
606
+ : await this.internalUpsertMany(entity, q, rows, update);
607
+ adoptReportedIds(meta, rows, ids);
608
+ return writtenIds(meta, rows);
609
+ }
610
+ /**
611
+ * An upsert of one statement reporting each row as it stands after it: off its `RETURNING` where it wrote the row,
612
+ * else, where its `$where` or an empty `update` kept it, read by the conflict keys.
613
+ */
614
+ async upsertReturning(writes, entity, q, rows, update, keys) {
615
+ const meta = getMeta(entity);
616
+ const read = [...new Set([...keys, ...meta.ids, ...getKeys(q.$conflict)])];
617
+ const written = await writes.upsert(entity, q, rows, update, read);
618
+ const keptAt = rows.flatMap((_, index) => (written[index] === undefined ? [index] : []));
619
+ const kept = await this.rowsByConflict(entity, q.$conflict, keptAt.map((index) => rows[index]), read);
620
+ const keptBy = new Map(keptAt.map((index, position) => [index, kept[position]]));
621
+ const stands = rows.map((row, index) => written[index] ?? keptBy.get(index) ?? this.unmatched(entity, q, row));
622
+ adoptReportedIds(meta, rows, stands.map((row) => idOf(meta, row)));
623
+ return this.returned(entity, stands, keys);
624
+ }
625
+ /**
626
+ * Refuses a row an upsert wrote or kept that no row matches by its conflict key, as read back: the engine stores
627
+ * the key otherwise than the row spells it, a uuid in other letters, and a row left out would misalign the rest.
628
+ */
629
+ unmatched(entity, q, row) {
630
+ const named = getKeys(q.$conflict)
631
+ .map((key) => `'${key}' ${String(row[key])}`)
632
+ .join(', ');
633
+ throw new UqlUsageError(`no '${entity.name}' row reads back with ${named}: write the key as ${this.dialect.engineName} stores it`);
592
634
  }
593
635
  /**
594
636
  * An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
595
- * as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
596
- * tenant's. A found row is held until the write, and a row inserted concurrently fails on its key. See
597
- * architecture/security-filter-writes.md.
637
+ * by id as `updateOne` does, a versioned one at its version, and the rest insert, so either branch writes its
638
+ * relations and a guarded row stays its tenant's. Inside a transaction a found row is held until the write, and
639
+ * a row inserted concurrently fails on its key. See architecture/security-filter-writes.md.
598
640
  */
599
- async readThenUpsert(entity, conflictPaths, rows, update) {
641
+ async readThenUpsert(entity, q, rows, update) {
600
642
  const meta = getMeta(entity);
601
643
  guardWrite(meta, rows, 'insert');
602
644
  if (!rows.length) {
603
645
  return [];
604
646
  }
605
- const keys = getKeys(conflictPaths);
606
647
  return this.atomically(async () => {
607
- const ids = await this.idsByConflict(entity, conflictPaths, rows);
648
+ const ids = await this.idsByConflict(entity, q.$conflict, rows);
608
649
  for (const [index, row] of rows.entries()) {
609
- // An empty `update` leaves a found row as it is, as `DO NOTHING` does.
610
- if (ids[index] !== undefined && (update === undefined || hasKeys(update))) {
611
- const q = { $where: whereEach(keys, (key) => row[key]) };
612
- // A copy each, as the update fills its `onUpdate` fields into it; by default, the payload less the found
613
- // row's key and the columns it matched on.
614
- const assigned = update ? { ...update } : omitKeys(row, [...meta.ids, ...keys]);
615
- await this.updateRows(entity, q, assigned, withDeleted(), undefined);
650
+ const id = ids[index];
651
+ if (id === undefined) {
652
+ continue;
653
+ }
654
+ const assigned = foundRowAssigned(meta, q.$conflict, row, update);
655
+ if (assigned) {
656
+ const $where = q.$where ? whereAnd(whereIds(meta, id), [q.$where]) : whereIds(meta, id);
657
+ await this.updateRows(entity, { $where }, assigned, withDeleted(), meta.version).catch((error) => {
658
+ // Still at its version, so its `$where` excluded it: kept, as an unversioned row is.
659
+ if (q.$where && error instanceof UqlOptimisticLockError && error.actual === error.expected) {
660
+ return 0;
661
+ }
662
+ throw error;
663
+ });
616
664
  }
617
665
  }
618
666
  const inserts = rows.filter((_, index) => ids[index] === undefined);
619
667
  if (inserts.length) {
620
- await this.insertRows(entity, inserts);
668
+ await this.insertRows(entity, inserts, (inserting) => this.internalInsertMany(entity, inserting));
621
669
  }
622
670
  // A found row's key is adopted by the caller; an inserted one carries the key its insert wrote.
623
671
  return ids;
@@ -643,10 +691,10 @@ export class AbstractQuerier {
643
691
  }
644
692
  const read = [...keys, ...meta.ids];
645
693
  // A soft delete stamps the rows, which a `RETURNING` would report stamped rather than as they were.
646
- const { writesReturning } = this;
694
+ const reportingWrites = this.reportingWrites(meta, 'delete');
647
695
  const deletion = deletionOf(meta, rest);
648
- if (writesReturning && !deletion.stamp && this.deletesByFilter(entity, q)) {
649
- return this.returned(entity, await writesReturning.delete(entity, q, rest, read), keys);
696
+ if (reportingWrites && !deletion.stamp && this.deletesByFilter(entity, q)) {
697
+ return this.returned(entity, await reportingWrites.delete(entity, q, rest, read), keys);
650
698
  }
651
699
  // A delete hook receives whole rows; without one, only the keys `returning` names and the ids are read.
652
700
  const $select = this.watchesDelete(entity) ? undefined : keySet(read);
@@ -701,11 +749,11 @@ export class AbstractQuerier {
701
749
  });
702
750
  }
703
751
  async saveOne(entity, payload, opts) {
704
- const [written] = await this.writeReturning(entity, () => this.saveIds(entity, [payload]), opts);
752
+ const [written] = await this.writtenOrReadBack(entity, () => this.saveIds(entity, [payload]), opts);
705
753
  return written;
706
754
  }
707
755
  async saveMany(entity, payload, opts) {
708
- return this.writeReturning(entity, () => this.saveIds(entity, payload), opts);
756
+ return this.writtenOrReadBack(entity, () => this.saveIds(entity, payload), opts);
709
757
  }
710
758
  /**
711
759
  * Whether a row names its key decides its statement, never whether the row exists: a named row
@@ -714,7 +762,6 @@ export class AbstractQuerier {
714
762
  */
715
763
  async saveIds(entity, payload) {
716
764
  const meta = getMeta(entity);
717
- assertUnversioned(meta, "'save'");
718
765
  // Indexes, not rows: the result is reported in payload order so it can be zipped with what was
719
766
  // passed, which concatenating the branches did not do.
720
767
  const toInsert = [];
@@ -745,8 +792,7 @@ export class AbstractQuerier {
745
792
  }
746
793
  }
747
794
  if (toUpsert.length) {
748
- const conflictPaths = keySet(meta.ids);
749
- const upserted = await this.upsertMany(entity, conflictPaths, toUpsert.map((index) => payload[index]));
795
+ const upserted = await this.upsertMany(entity, { $conflict: keySet(meta.ids) }, toUpsert.map((index) => payload[index]));
750
796
  for (let position = 0; position < toUpsert.length; position++) {
751
797
  ids[toUpsert[position]] = upserted[position];
752
798
  }
@@ -1048,21 +1094,26 @@ export class AbstractQuerier {
1048
1094
  }
1049
1095
  await this.emitHook(entity, 'afterLoad', rows);
1050
1096
  }
1097
+ /** The ids of `rows`, read by the columns an upsert matches them on, as {@link rowsByConflict} reads them. */
1098
+ async idsByConflict(entity, conflictKeys, rows) {
1099
+ const meta = getMeta(entity);
1100
+ const found = await this.rowsByConflict(entity, conflictKeys, rows, meta.ids);
1101
+ return found.map((row) => row && idOf(meta, row));
1102
+ }
1051
1103
  /**
1052
- * The ids of `rows`, read by the columns an upsert matches them on, soft-deleted rows included since a unique key
1053
- * holds across both, each read held as {@link readForWrite} holds its rows. A row no found row matches, or two do,
1054
- * reads none, since a missing id is honest where a guessed one is not; a null key never conflicts, so is not read.
1104
+ * The row each of `rows` matches on the columns an upsert matches on, with `select`, soft-deleted rows included
1105
+ * since a unique key holds across both, held as {@link readForWrite} holds its rows. One no row matches, or two do,
1106
+ * reads none, since a missing row is honest where a guessed one is not; a null key never conflicts, so is not read.
1055
1107
  */
1056
- async idsByConflict(entity, conflictPaths, rows) {
1057
- const meta = getMeta(entity);
1058
- const keys = getKeys(conflictPaths);
1059
- const named = rows.filter((row) => keys.every((key) => row[key] != null));
1108
+ async rowsByConflict(entity, conflictKeys, rows, select) {
1109
+ const keys = getKeys(conflictKeys);
1110
+ const named = rows.filter((row) => namesEvery(row, keys));
1060
1111
  const distinct = [...new Map(named.map((row) => [rowKey(row, keys), row])).values()];
1061
1112
  const byConflict = new Map();
1062
- for (const q of this.keyedReads(keys, distinct, [...meta.ids, ...keys])) {
1113
+ for (const q of this.keyedReads(keys, distinct, [...new Set([...select, ...keys])])) {
1063
1114
  for (const row of await this.readForWrite(entity, q, withDeleted())) {
1064
1115
  const key = rowKey(row, keys);
1065
- byConflict.set(key, byConflict.has(key) ? undefined : idOf(meta, row));
1116
+ byConflict.set(key, byConflict.has(key) ? undefined : row);
1066
1117
  }
1067
1118
  }
1068
1119
  return rows.map((row) => byConflict.get(rowKey(row, keys)));
@@ -1071,10 +1122,10 @@ export class AbstractQuerier {
1071
1122
  * `ids` completed where an upsert reported no id for a row whose key it does not keep (`kept`, asked before the
1072
1123
  * write fills one in): read back by the conflict columns.
1073
1124
  */
1074
- async withUnreportedIds(entity, conflictPaths, payload, ids, kept) {
1125
+ async withUnreportedIds(entity, conflictKeys, payload, ids, kept) {
1075
1126
  const unplaced = payload.flatMap((_, index) => (ids[index] === undefined && !kept[index] ? [index] : []));
1076
1127
  if (unplaced.length) {
1077
- const found = await this.idsByConflict(entity, conflictPaths, unplaced.map((index) => payload[index]));
1128
+ const found = await this.idsByConflict(entity, conflictKeys, unplaced.map((index) => payload[index]));
1078
1129
  unplaced.forEach((index, position) => {
1079
1130
  ids[index] = found[position];
1080
1131
  });
@@ -1083,8 +1134,9 @@ export class AbstractQuerier {
1083
1134
  }
1084
1135
  /** Reads of the rows matching one of `rows` on `keys`, as many per statement as a key list takes, selecting `select`. */
1085
1136
  keyedReads(keys, rows, select) {
1137
+ const $select = keySet(select);
1086
1138
  return chunk(rows, this.dialect.keyListCapacity(keys.length)).map((batch) => ({
1087
- $select: keySet(select),
1139
+ $select,
1088
1140
  $where: whereKeysIn(keys, batch),
1089
1141
  }));
1090
1142
  }
@@ -1,7 +1,7 @@
1
1
  import type { AbstractSqlDialect } from '../dialect/index.js';
2
- import type { EntityData, ExtraOptions, Query, QueryAggregate, QueryConflictPaths, QueryPage, QueryOptions, QuerySearch, QueryUpdateResult, RawRow, SavepointCommand, SqlQuerier, SqlStatement, Type, TransactionOptions, UpdatePayload } from '../type/index.js';
2
+ import type { EntityData, EntityMeta, ExtraOptions, Query, QueryAggregate, QueryUpsert, QueryPage, QueryOptions, 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 WritesReturning } from './abstractQuerier.js';
4
+ import { AbstractQuerier, type UpsertedId, 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;
@@ -47,6 +47,8 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
47
47
  private inTurn;
48
48
  /** Runs `task` on the connection, connected, after everything queued before it. */
49
49
  private onConnection;
50
+ /** The read `build` writes, bound as {@link bound} binds a statement, with the terms its rows are read as. */
51
+ private boundRead;
50
52
  /** The statement `build` writes, refused past the bind budget before the driver fails it. */
51
53
  private bound;
52
54
  /** Refused before the driver fails it, or PGlite answers it and every read after it wrong. */
@@ -73,8 +75,13 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
73
75
  * transaction of its own where the tuning needs one and none is open.
74
76
  */
75
77
  private selectRows;
76
- /** The rows of a statement the dialect builds, each as the terms it returns say, after the `leading` ones. */
78
+ /**
79
+ * The rows of a statement the dialect builds, each as the terms it returns say, after the `leading` ones. Every read
80
+ * takes it, so it builds no list {@link readEach} would: measured in `pgAllocation.test.ts`.
81
+ */
77
82
  private readRows;
83
+ /** The rows of each statement the dialect builds, read as its terms say, all or none where two or more. */
84
+ private readEach;
78
85
  /**
79
86
  * The one read not going through `runStatements`: it holds the connection for its loop, so it checks its budget
80
87
  * and connects on its own, its values going as the context holds them, each normalized as it was bound. Tuning
@@ -97,14 +104,38 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
97
104
  estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
98
105
  protected internalAggregate<E extends object>(entity: Type<E>, q: QueryAggregate<E>, opts?: QueryOptions): Promise<RawRow[]>;
99
106
  internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
107
+ /**
108
+ * The statements an insert of `rows` takes, as the indexes of the rows each writes. Grouped by whether a row names
109
+ * its key, as the two carry different columns: a budget taken over their union would under-fill the statement
110
+ * missing one. One row per statement where its `RETURNING` reports a key nothing orders, as {@link inPayloadOrder} says.
111
+ */
112
+ private insertChunks;
113
+ /** Inserts `rows`, reporting each, in their order, with the fields `keys` names, off its own `RETURNING`, and placing its key on it. */
114
+ private insertedRows;
100
115
  internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
101
- /** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
102
- protected get writesReturning(): WritesReturning | undefined;
103
- /** The rows the write `build` renders reports, `RETURNING` the fields `keys` names. */
104
- private reportedRows;
105
- protected internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<(UpsertedId<E> | undefined)[]>;
106
- /** The ids an upsert reports of its rows: its `RETURNING` rows' in order, or its one row's in the header. */
107
- private reportedIds;
116
+ /** The writes reading their rows off their own statement, where {@link AbstractSqlDialect.reportsWrite} says so. */
117
+ protected reportingWrites<E>(meta: EntityMeta<E>, write: ReportedWrite): ReportingWrites | undefined;
118
+ /**
119
+ * The id each row got: off the upsert's `RETURNING` where it has one, else off the header. A row reported none of,
120
+ * skipped by `DO NOTHING` or its `$where`, is read back by its conflict keys, unless it keeps its own key (`kept`,
121
+ * asked before the statement fills `onInsert` keys in).
122
+ */
123
+ protected internalUpsertMany<E extends object>(entity: Type<E>, q: QueryUpsert<E>, payload: E[], update?: UpdatePayload<E>): Promise<(UpsertedId<E> | undefined)[]>;
124
+ /** The ids an upsert's header reports, by index: a statement of one row assigning a found row names its key. */
125
+ private headerIds;
126
+ /**
127
+ * The rows of `payload` an upsert writes, in its order, with the fields `keys` names, off its `RETURNING`: matched by
128
+ * the conflict keys `keys` includes, as no engine promises that order. `undefined` for a row it kept, or with no
129
+ * conflict key. The statement fills `payload`'s `onInsert` fields.
130
+ */
131
+ private upsertedRows;
132
+ /**
133
+ * An upsert's statements: one per shape, each split again to fit the bind budget, less what its assignments bind
134
+ * once. Grouping first is what makes that one figure: every row of a group carries the same columns. No row cap:
135
+ * the one engine with one, SQL Server, upserts through a MERGE, whose source takes any number. `reports`: the
136
+ * statement's header names its row's id, which spares the read back.
137
+ */
138
+ private upsertGroups;
108
139
  protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
109
140
  protected openTransaction(opts?: TransactionOptions): Promise<void>;
110
141
  /**