uql-orm 0.114.3 → 0.115.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 (85) hide show
  1. package/dist/cockroachdb/cockroachDialect.d.ts +2 -0
  2. package/dist/cockroachdb/cockroachDialect.js +5 -0
  3. package/dist/d1/d1Querier.d.ts +2 -4
  4. package/dist/d1/d1Querier.js +0 -4
  5. package/dist/d1/d1SqliteDialect.js +1 -1
  6. package/dist/dialect/abstractDialect.d.ts +17 -8
  7. package/dist/dialect/abstractDialect.js +30 -16
  8. package/dist/dialect/abstractSqlDialect.d.ts +11 -2
  9. package/dist/dialect/abstractSqlDialect.js +17 -2
  10. package/dist/dialect/mysqlLikeSqlDialect.js +2 -0
  11. package/dist/dialect/operators.d.ts +2 -2
  12. package/dist/dialect/pgLikeSqlDialect.d.ts +8 -1
  13. package/dist/dialect/pgLikeSqlDialect.js +20 -0
  14. package/dist/entity/columnOptionsBuilder.d.ts +2 -1
  15. package/dist/entity/columnOptionsBuilder.js +3 -0
  16. package/dist/entity/metadata/definedFixture/author.d.ts +1 -1
  17. package/dist/entity/metadata/definedFixture/book.d.ts +2 -2
  18. package/dist/entity/metadata/definedFixture/folder.d.ts +1 -1
  19. package/dist/entity/metadata/definition.js +69 -30
  20. package/dist/http/api.d.ts +1 -1
  21. package/dist/http/wireQuery.js +1 -1
  22. package/dist/index.d.ts +2 -0
  23. package/dist/index.js +2 -0
  24. package/dist/migrate/ddl/tableDdl.d.ts +5 -0
  25. package/dist/migrate/ddl/tableDdl.js +9 -0
  26. package/dist/migrate/drift/driftDetector.js +2 -1
  27. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +3 -1
  28. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +7 -1
  29. package/dist/migrate/introspection/postgresIntrospector.d.ts +3 -1
  30. package/dist/migrate/introspection/postgresIntrospector.js +14 -1
  31. package/dist/migrate/introspection/tableSchemaAST.js +1 -0
  32. package/dist/migrate/policySql.d.ts +12 -0
  33. package/dist/migrate/policySql.js +74 -0
  34. package/dist/migrate/schemaChange.js +1 -0
  35. package/dist/migrate/schemaGenerator.d.ts +2 -0
  36. package/dist/migrate/schemaGenerator.js +37 -11
  37. package/dist/mongodb/mongoDialect.js +3 -1
  38. package/dist/mongodb/mongodbQuerier.d.ts +2 -5
  39. package/dist/mongodb/mongodbQuerier.js +14 -26
  40. package/dist/mssql/mssqlDialect.js +2 -0
  41. package/dist/neon/neonQuerier.d.ts +1 -2
  42. package/dist/nestjs/uqlContextInterceptor.d.ts +1 -1
  43. package/dist/nestjs/uqlContextInterceptor.js +1 -1
  44. package/dist/nestjs/uqlModule.d.ts +2 -2
  45. package/dist/nestjs/uqlModule.js +1 -1
  46. package/dist/querier/abstractQuerier.d.ts +68 -30
  47. package/dist/querier/abstractQuerier.js +249 -168
  48. package/dist/querier/abstractQuerierPool.js +2 -0
  49. package/dist/querier/abstractSqlQuerier.d.ts +22 -13
  50. package/dist/querier/abstractSqlQuerier.js +75 -27
  51. package/dist/querier/queryError.js +1 -0
  52. package/dist/schema/schemaAST.js +1 -0
  53. package/dist/schema/schemaASTBuilder.d.ts +3 -1
  54. package/dist/schema/schemaASTBuilder.js +1 -0
  55. package/dist/schema/schemaASTDiffer.js +4 -2
  56. package/dist/schema/types.d.ts +12 -4
  57. package/dist/sqlite/bindValues.d.ts +1 -1
  58. package/dist/sqlite/hranaQuerier.d.ts +2 -2
  59. package/dist/sqlite/sqliteDialect.js +2 -0
  60. package/dist/turso/tursoSessionQuerier.d.ts +2 -2
  61. package/dist/type/column.d.ts +10 -0
  62. package/dist/type/definedEntity.d.ts +9 -4
  63. package/dist/type/dialect.d.ts +13 -0
  64. package/dist/type/entity.d.ts +10 -0
  65. package/dist/type/index.d.ts +1 -0
  66. package/dist/type/index.js +1 -0
  67. package/dist/type/migration.d.ts +5 -1
  68. package/dist/type/policy.d.ts +91 -0
  69. package/dist/type/policy.js +1 -0
  70. package/dist/type/querier.d.ts +16 -2
  71. package/dist/type/querierPool.d.ts +2 -2
  72. package/dist/type/query.d.ts +20 -35
  73. package/dist/type/query.js +2 -0
  74. package/dist/type/universalQuerier.d.ts +6 -6
  75. package/dist/util/contextRefs.d.ts +6 -0
  76. package/dist/util/contextRefs.js +5 -0
  77. package/dist/util/dialect.util.d.ts +10 -16
  78. package/dist/util/dialect.util.js +70 -64
  79. package/dist/util/fieldOption.util.js +1 -0
  80. package/dist/util/policy.util.d.ts +100 -0
  81. package/dist/util/policy.util.js +234 -0
  82. package/dist/util/uqlError.d.ts +2 -5
  83. package/dist/util/uqlError.js +2 -5
  84. package/package.json +1 -1
  85. package/skills/uql-orm/SKILL.md +24 -14
@@ -1,9 +1,9 @@
1
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
- import { parseQueryLock } from '../type/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, isClass, defaultReadKeys, holdsForeignKey, noop, } from '../util/index.js';
6
- import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
4
+ import { parseQueryLock, PAST_POLICIES } from '../type/index.js';
5
+ import { childrenExcept, childrenOf, chunk, clone, entityName, fillOnFields, filterFieldKeys, getKeys, deletionOf, hasKeys, getRelationRequestSummary, guardWrite, pinWrite, idOnlyQuery, keyJoins, keySet, isPagedQuery, isScalarId, LoggerWrapper, normalizeScalarFieldSelection, parentJoins, pointAt, queryLoggerFor, parseRelationAtKey, rowKey, runHooks, someKey, targetJoins, foundRowAssigned, whereAnd, whereIds, whereKeysIn, whereWith, withDeleted, cascadingRelations, isClass, defaultReadKeys, holdsForeignKey, noop, } from '../util/index.js';
6
+ import { UqlOptimisticLockError, UqlSecurityError, UqlUsageError } from '../util/uqlError.js';
7
7
  import { keysetRead } from './keyset.js';
8
8
  import { enrichError } from './queryError.js';
9
9
  import { awaitTurn, claim, currentTransaction, depthOf, free, inTransaction, newScope, slotOf, } from './transaction.js';
@@ -73,36 +73,31 @@ 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
+ });
77
83
  }
78
- /**
79
- * Whether an upsert has to read before it writes: `ON CONFLICT` updates a guarded row whatever tenant it belongs
80
- * to, writes no relation, and cannot tell a found row it skipped for a stale version.
81
- */
82
- function upsertsByReading(meta, q, rows) {
83
- return (meta.version !== undefined ||
84
- securityConditions(meta, ['read', 'insert', 'update']).length > 0 ||
85
- writesRelations(meta, q.$update ? [...rows, q.$update] : rows));
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');
86
88
  }
87
89
  /**
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.
90
+ * Writes the key an upsert reported onto `row`, over the one it named: a found row keeps its own. Only the key, since
91
+ * an `onInsert` value was never written to a row the upsert updated. Answers `id`.
91
92
  */
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
- });
93
+ function adoptId(meta, row, id) {
94
+ if (meta.ids.length > 1) {
95
+ Object.assign(row, id);
96
+ }
97
+ else {
98
+ row[meta.ids[0]] = id;
99
+ }
100
+ return id;
106
101
  }
107
102
  /** Normalizes either call form to `[entity, query, opts]`, throwing when a query object has no `$entity`. */
108
103
  function entityArgs(args) {
@@ -173,9 +168,11 @@ async function runCallbacks(callbacks) {
173
168
  }
174
169
  /**
175
170
  * What an upsert or a restore reads and updates rows with: soft-deleted ones too, since a key holds across both, held
176
- * to the `security` filters an update is.
171
+ * to the policies an update is.
177
172
  */
178
173
  const UPDATING_DELETED = { ...withDeleted(), access: 'update' };
174
+ /** A read of rows as they are stored, past filters and policies: what checks a write the policies settled. */
175
+ const UNPOLICED = { filters: false, [PAST_POLICIES]: true };
179
176
  const STREAM_HOLDS_QUERIER = 'a stream is reading on this querier: run the statement after its loop, or on another querier';
180
177
  /** Base class for all database queriers. */
181
178
  export class AbstractQuerier {
@@ -353,8 +350,12 @@ export class AbstractQuerier {
353
350
  if (!keys || !reportingWrites || !payload.length) {
354
351
  return this.writtenOrReadBack(entity, () => this.insertIds(entity, payload), opts);
355
352
  }
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));
353
+ return this.inserting(entity, payload, (rows) => this.insertReturning(reportingWrites, entity, rows, keys));
354
+ }
355
+ /** Inserts `rows` as {@link insertRows} does, reporting each with the fields `keys` names off its own statement. */
356
+ async insertReturning(writes, entity, rows, keys) {
357
+ const read = [...new Set([...keys, ...getMeta(entity).ids])];
358
+ return this.returned(entity, await this.insertRows(entity, rows, (inserted) => writes.insert(entity, inserted, read)), keys);
358
359
  }
359
360
  /**
360
361
  * The ids of the rows inserted, in payload order. The `onInsert` values are filled before the write, so
@@ -364,16 +365,13 @@ export class AbstractQuerier {
364
365
  if (!payload.length) {
365
366
  return [];
366
367
  }
368
+ return this.inserting(entity, payload, (rows) => this.insertedIds(entity, rows));
369
+ }
370
+ /** Inserts `rows` as {@link insertRows} does, answering the key each got. */
371
+ async insertedIds(entity, rows) {
367
372
  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
- });
373
+ await this.insertRows(entity, rows, (inserting) => this.internalInsertMany(entity, inserting));
374
+ return writtenIds(meta, rows);
377
375
  }
378
376
  /** `insert` of `payload` between the insert hooks, {@link atomically} where it writes relations too. */
379
377
  inserting(entity, payload, insert) {
@@ -393,15 +391,11 @@ export class AbstractQuerier {
393
391
  * says of them, since a soft-deleted row inserted is still written.
394
392
  */
395
393
  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) {
394
+ if (!ids.length) {
402
395
  return [];
403
396
  }
404
- const named = known.map((id) => whereIds(meta, id));
397
+ const meta = getMeta(entity);
398
+ const named = ids.map((id) => whereIds(meta, id));
405
399
  const read = withDeleted(opts);
406
400
  const rows = [];
407
401
  for (const q of this.keyedReads(meta.ids, named, [...keys, ...meta.ids])) {
@@ -424,10 +418,71 @@ export class AbstractQuerier {
424
418
  const meta = getMeta(entity);
425
419
  await this.writeHeldReferences(entity, rows);
426
420
  fillOnFields(meta, rows, 'onInsert');
427
- guardWrite(meta, rows, 'insert');
428
- const inserted = await insert(rows);
429
- await this.insertChildren(entity, rows);
430
- return inserted;
421
+ const held = this.guarded(entity, rows, 'insert');
422
+ return held(async () => {
423
+ const inserted = await insert(rows);
424
+ await this.insertChildren(entity, rows);
425
+ return inserted;
426
+ }, () => rows.map((row) => idOf(meta, row)));
427
+ }
428
+ /**
429
+ * {@link guardWrite} under a pool holding writes to the policies, answering how the write of `rows` runs: alone, or
430
+ * with the rows it wrote read back against the check they could not settle, in a transaction undoing it where one
431
+ * does not hold. Where the database holds the policies the rows still get their pinned fields and an early refusal,
432
+ * and nothing is read back. A checked write is refused where this querier holds no transaction to undo it in.
433
+ */
434
+ guarded(entity, rows, write) {
435
+ const check = this.guardRows(getMeta(entity), rows, write);
436
+ const held = (run, written) => {
437
+ if (!check) {
438
+ return run();
439
+ }
440
+ if (!this.undoesSteps()) {
441
+ throw new UqlUsageError(`'${entity.name}' policies check written rows by reading them back, which needs a transaction ${this.dialect.engineName} holds none of here`);
442
+ }
443
+ return this.atomically(async () => {
444
+ const result = await run();
445
+ await this.holdToCheck(entity, written(result), check);
446
+ return result;
447
+ });
448
+ };
449
+ return Object.assign(held, { reads: !!check });
450
+ }
451
+ /**
452
+ * {@link guardWrite} where this pool reads written rows back, answering the check to read them against; else
453
+ * {@link pinUpserted}'s pinning alone, where it guards writes at all.
454
+ */
455
+ guardRows(meta, rows, write) {
456
+ const { guards, checks } = this.dialect.policies;
457
+ if (checks) {
458
+ return guardWrite(meta, rows, write);
459
+ }
460
+ if (guards) {
461
+ pinWrite(meta, rows, write);
462
+ }
463
+ return undefined;
464
+ }
465
+ /** {@link pinWrite} where this pool guards writes: an upsert's branches check what they write, or its database does. */
466
+ pinUpserted(meta, rows) {
467
+ if (this.dialect.policies.guards) {
468
+ pinWrite(meta, rows, 'insert');
469
+ }
470
+ }
471
+ /** Whether {@link atomically} undoes every step of a write that fails partway: a transaction holds them. */
472
+ undoesSteps() {
473
+ return this.dialect.features.transactions || this.scopeHere() !== undefined;
474
+ }
475
+ /** Refuses, undoing the write, where any row `ids` names does not hold `check` once written. */
476
+ async holdToCheck(entity, ids, check) {
477
+ const meta = getMeta(entity);
478
+ const known = ids.filter((id) => id !== undefined);
479
+ if (known.length < ids.length) {
480
+ throw new UqlUsageError(`'${entity.name}' wrote a row whose key it cannot read back to check against its policies`);
481
+ }
482
+ const holding = await this.writeBatches(known, meta.ids.length, (batch) => this.internalCount(entity, { $where: whereAnd(whereIds(meta, batch), [check]) }, UNPOLICED));
483
+ if (holding < known.length) {
484
+ throw new UqlSecurityError(`a row written to '${entity.name}' does not hold its policies under this context`);
485
+ }
431
486
  }
432
487
  async updateOneById(entity, id, payload, opts) {
433
488
  assertIdValue(entity, id);
@@ -451,7 +506,7 @@ export class AbstractQuerier {
451
506
  return this.updateMatching(entity, q, payload, rest);
452
507
  }
453
508
  const reportingWrites = this.reportingWrites(meta, 'update');
454
- const reporting = (row) => reportingWrites && this.updatesByFilter(entity, q, row) ? reportingWrites : undefined;
509
+ const reporting = (row) => reportingWrites && this.updatesByFilter(entity, q, row, rest) ? reportingWrites : undefined;
455
510
  // Decided again on the row the hooks hand over, which may now write a relation one statement cannot.
456
511
  const write = () => this.hooked(entity, 'Update', [payload], async ([row]) => {
457
512
  const writes = reporting(row);
@@ -473,10 +528,10 @@ export class AbstractQuerier {
473
528
  async updateReturning(writes, entity, q, row, opts, keys) {
474
529
  const meta = getMeta(entity);
475
530
  const read = [...keys, ...meta.ids];
476
- await this.prepareUpdate(entity, row);
477
- const rows = writesColumns(meta, row)
478
- ? await writes.update(entity, q, row, opts, read)
479
- : await this.internalFindMany(entity, { ...q, $select: keySet(read) }, opts);
531
+ const held = await this.prepareUpdate(entity, row);
532
+ const rows = await held(() => writesColumns(meta, row)
533
+ ? writes.update(entity, q, row, opts, read)
534
+ : this.internalFindMany(entity, { ...q, $select: keySet(read) }, opts), (written) => written.map((it) => idOf(meta, it)));
480
535
  return this.returned(entity, rows, keys);
481
536
  }
482
537
  /**
@@ -496,30 +551,32 @@ export class AbstractQuerier {
496
551
  */
497
552
  async updateRows(entity, q, row, opts, lockKey, settled) {
498
553
  const meta = getMeta(entity);
499
- await this.prepareUpdate(entity, row);
554
+ const held = await this.prepareUpdate(entity, row);
500
555
  const relKeys = ownedRelations(meta).filter((key) => Object.hasOwn(row, key));
501
- const settles = !!relKeys.length || this.settlesWrite(entity, q);
556
+ const settles = !!relKeys.length || this.settlesWrite(entity, q, opts);
502
557
  if (lockKey) {
503
558
  assertLockableUpdate(meta, q, settles);
504
559
  const lock = lockVersion(meta, lockKey, q, row);
505
560
  row[lockKey] = lock.next;
506
- const changes = await this.updateColumns(entity, lock.q, row, opts, 0);
561
+ const changes = await held(() => this.updateColumns(entity, lock.q, row, opts, 0), (changed) => (changed ? [idOf(meta, { ...q.$where })] : []));
507
562
  return changes || this.throwStaleVersion(entity, lockKey, q, lock.expected, opts);
508
563
  }
509
- if (!settles && !settled) {
564
+ if (!settles && !settled && !held.reads) {
510
565
  return this.updateColumns(entity, q, row, opts, 0);
511
566
  }
512
- return this.atomically(async () => {
567
+ const write = async () => {
513
568
  const ids = settled ?? (await this.settleIds(entity, q, opts));
514
569
  if (!ids.length) {
515
- return 0;
570
+ return { ids, changes: 0 };
516
571
  }
517
572
  const changes = await this.writeBatches(ids, meta.ids.length, (batch) => this.updateColumns(entity, { $where: whereIds(meta, batch) }, row, opts, batch.length));
518
573
  for (const relKey of relKeys) {
519
574
  await this.replaceChildren(entity, relKey, ids, row[relKey]);
520
575
  }
521
- return changes;
522
- });
576
+ return { ids, changes };
577
+ };
578
+ const { changes } = await held(() => this.atomically(write), ({ ids }) => ids);
579
+ return changes;
523
580
  }
524
581
  /**
525
582
  * Why an update matched no row. The filter named the row by its id, so reading by that id alone
@@ -539,12 +596,15 @@ export class AbstractQuerier {
539
596
  : `'${entityName(meta)}' moved on: the payload carries '${key}' ${String(expected)}, the row is at ${String(actual)}`;
540
597
  throw new UqlOptimisticLockError(message, expected, actual);
541
598
  }
542
- /** What every update does to its row before its statement: writes the to-ones it holds, fills and guards it. */
599
+ /**
600
+ * What every update does to its row before its statement: writes the to-ones it holds, fills and guards it.
601
+ * Answers how its write runs, as {@link guarded} does.
602
+ */
543
603
  async prepareUpdate(entity, row) {
544
604
  const meta = getMeta(entity);
545
605
  await this.writeHeldReferences(entity, [row]);
546
606
  fillOnFields(meta, [row], 'onUpdate');
547
- guardWrite(meta, [row], 'update');
607
+ return this.guarded(entity, [row], 'update');
548
608
  }
549
609
  /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
550
610
  async updateColumns(entity, q, row, opts, unwritten) {
@@ -554,9 +614,9 @@ export class AbstractQuerier {
554
614
  * Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or
555
615
  * delete, and one without {@link DialectFeatures.correlatedWrites} cannot read a relation in its filter.
556
616
  */
557
- settlesWrite(entity, q) {
617
+ settlesWrite(entity, q, opts) {
558
618
  const { dialect } = this;
559
- return isPagedQuery(q) || (!dialect.features.correlatedWrites && dialect.constrainsRelations(entity, q.$where));
619
+ return (isPagedQuery(q) || (!dialect.features.correlatedWrites && dialect.constrainsRelations(entity, q.$where, opts)));
560
620
  }
561
621
  /**
562
622
  * `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed,
@@ -571,7 +631,7 @@ export class AbstractQuerier {
571
631
  }
572
632
  /** Runs a write of several statements as one: in a transaction of its own, or the one already open. */
573
633
  atomically(write) {
574
- return this.scopeHere() ? write() : this.transaction(write);
634
+ return this.scopeHere() || !this.dialect.features.transactions ? write() : this.transaction(write);
575
635
  }
576
636
  /** The ids `q` matches, in its own order and page, held as {@link readForWrite} holds them. */
577
637
  async settleIds(entity, q, opts) {
@@ -618,39 +678,109 @@ export class AbstractQuerier {
618
678
  const meta = getMeta(entity);
619
679
  const keys = returnedKeys(meta, opts?.returning);
620
680
  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.
681
+ // Fires `beforeUpsert`/`afterUpsert`: whether a found row is updated is the database's to decide, so neither the
682
+ // insert's nor the update's pair fits. How to write is decided on the rows the hooks hand over: one naming no
683
+ // conflict key conflicts with none, so it is written as an insert.
684
+ const branch = upsertBranch(q);
623
685
  if (!keys || !reportingWrites) {
624
- return this.writtenOrReadBack(entity, () => this.hooked(entity, 'Upsert', payload, (rows) => this.upsertIds(entity, q, rows)), opts);
686
+ return this.writtenOrReadBack(entity, () => this.hooked(entity, 'Upsert', payload, (rows) => this.writeEach(rows, branch, {
687
+ insert: (inserts) => this.insertedIds(entity, inserts),
688
+ upsert: (upserts) => this.upsertIds(entity, q, upserts, this.upsertsByReading(meta, q, upserts)),
689
+ })), opts);
625
690
  }
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)));
691
+ return this.atomically(() => this.hooked(entity, 'Upsert', payload, (rows) => this.writeEach(rows, branch, {
692
+ insert: (inserts) => this.insertReturning(reportingWrites, entity, inserts, keys),
693
+ upsert: async (upserts) => this.upsertsByReading(meta, q, upserts)
694
+ ? this.readBack(entity, await this.upsertIds(entity, q, upserts, true), keys)
695
+ : this.upsertReturning(reportingWrites, entity, q, upserts, keys),
696
+ })));
697
+ }
698
+ /**
699
+ * Whether an upsert has to read before it writes: `ON CONFLICT` updates a row the querier holds to policies whatever
700
+ * tenant it belongs to, writes no relation, and cannot tell a found row it skipped for a stale version. A database
701
+ * holding the policies itself holds the conflicting row to them in the one statement.
702
+ */
703
+ upsertsByReading(meta, q, rows) {
704
+ return (meta.version !== undefined ||
705
+ (this.dialect.policies.scopes && !!meta.policies?.length) ||
706
+ writesRelations(meta, q.$update ? [...rows, q.$update] : rows));
629
707
  }
630
- /** Upserts `rows`, reading first where {@link upsertsByReading} says so, and answers the id each row got. */
631
- async upsertIds(entity, q, rows) {
708
+ /** Upserts `rows`, each naming every conflict key, reading first where `reads`: the id each got. */
709
+ async upsertIds(entity, q, rows, reads) {
632
710
  const meta = getMeta(entity);
633
- const ids = upsertsByReading(meta, q, rows)
634
- ? await this.readThenUpsert(entity, q, rows)
635
- : await this.internalUpsertMany(entity, q, rows);
636
- adoptReportedIds(meta, rows, ids);
637
- return writtenIds(meta, rows);
711
+ this.pinUpserted(meta, rows);
712
+ const ids = reads ? await this.readThenUpsert(entity, q, rows) : await this.reportedOrKeptIds(entity, q, rows);
713
+ return rows.map((row, index) => adoptId(meta, row, ids[index] ?? this.unmatched(entity, q, row)));
714
+ }
715
+ /**
716
+ * The id of each of `rows` the engine's upsert reports, or {@link withKept} reads back. A row matched on its own key
717
+ * names it, so needs neither.
718
+ */
719
+ async reportedOrKeptIds(entity, q, rows) {
720
+ const meta = getMeta(entity);
721
+ const ids = await this.internalUpsertMany(entity, q, rows);
722
+ return meta.ids.every((key) => Object.hasOwn(q.$conflict, key))
723
+ ? rows.map((row) => idOf(meta, row))
724
+ : this.withKept(entity, q, rows, ids, meta.ids, (row) => idOf(meta, row));
725
+ }
726
+ /**
727
+ * `written`, an upsert's report of each of `rows`, with each row it reported none of, kept by its `$where` or an
728
+ * empty `$update`, read back by its conflict keys selecting `select`: `undefined` where no row matches.
729
+ */
730
+ async withKept(entity, q, rows, written, select, of) {
731
+ const keptAt = rows.flatMap((_, index) => (written[index] === undefined ? [index] : []));
732
+ if (keptAt.length) {
733
+ const kept = await this.rowsByConflict(entity, q.$conflict, keptAt.map((index) => rows[index]), select);
734
+ keptAt.forEach((index, position) => {
735
+ const row = kept[position];
736
+ written[index] = row && of(row);
737
+ });
738
+ }
739
+ return written;
638
740
  }
639
741
  /**
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.
742
+ * An upsert of one statement, of rows each naming every conflict key, reporting each row as it stands after it: off
743
+ * its `RETURNING` where it wrote the row, else, where its `$where` or an empty `$update` kept it, read by the
744
+ * conflict keys.
642
745
  */
643
746
  async upsertReturning(writes, entity, q, rows, keys) {
644
747
  const meta = getMeta(entity);
645
748
  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)));
749
+ this.pinUpserted(meta, rows);
750
+ const written = await this.withKept(entity, q, rows, await writes.upsert(entity, q, rows, read), read, (row) => row);
751
+ const stands = rows.map((row, index) => {
752
+ const stand = written[index] ?? this.unmatched(entity, q, row);
753
+ adoptId(meta, row, idOf(meta, stand));
754
+ return stand;
755
+ });
652
756
  return this.returned(entity, stands, keys);
653
757
  }
758
+ /**
759
+ * Writes each of `rows` through the writer `branch` names for it, the writers in their order, answering each row's
760
+ * result in `rows` order; {@link atomically} where more than one branch but those `idle` names, which write nothing.
761
+ */
762
+ async writeEach(rows, branch, writers, idle = []) {
763
+ const at = Map.groupBy(rows.keys(), (index) => branch(rows[index]));
764
+ const [only] = at.keys();
765
+ if (at.size === 1) {
766
+ return writers[only]([...rows]);
767
+ }
768
+ const results = new Array(rows.length);
769
+ const write = async () => {
770
+ for (const key of getKeys(writers)) {
771
+ const indexes = at.get(key);
772
+ if (indexes) {
773
+ const written = await writers[key](indexes.map((index) => rows[index]));
774
+ indexes.forEach((index, position) => {
775
+ results[index] = written[position];
776
+ });
777
+ }
778
+ }
779
+ return results;
780
+ };
781
+ const writing = [...at.keys()].filter((key) => !idle.includes(key));
782
+ return writing.length > 1 ? this.atomically(write) : write();
783
+ }
654
784
  /**
655
785
  * Refuses a row an upsert wrote or kept that no row matches by its conflict key, as read back: the engine stores
656
786
  * the key otherwise than the row spells it, a uuid in other letters, and a row left out would misalign the rest.
@@ -664,17 +794,14 @@ export class AbstractQuerier {
664
794
  /**
665
795
  * An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
666
796
  * by id as `updateOne` does, a versioned one at its version, and the rest insert, so either branch writes its
667
- * relations and a guarded row stays its tenant's. Inside a transaction a found row is held until the write, and
668
- * a row inserted concurrently fails on its key. See architecture/security-filter-writes.md.
797
+ * relations and a policied row stays its tenant's. Inside a transaction a found row is held until the write, and
798
+ * a row inserted concurrently fails on its key. See architecture/row-level-security.md.
669
799
  */
670
800
  async readThenUpsert(entity, q, rows) {
671
801
  const meta = getMeta(entity);
672
- guardWrite(meta, rows, 'insert');
673
- if (!rows.length) {
674
- return [];
675
- }
676
802
  return this.atomically(async () => {
677
- const ids = await this.idsByConflict(entity, q.$conflict, rows);
803
+ const found = await this.rowsByConflict(entity, q.$conflict, rows, meta.ids);
804
+ const ids = found.map((row) => row && idOf(meta, row));
678
805
  for (const [index, row] of rows.entries()) {
679
806
  const id = ids[index];
680
807
  if (id === undefined) {
@@ -696,8 +823,7 @@ export class AbstractQuerier {
696
823
  if (inserts.length) {
697
824
  await this.insertRows(entity, inserts, (inserting) => this.internalInsertMany(entity, inserting));
698
825
  }
699
- // A found row's key is adopted by the caller; an inserted one carries the key its insert wrote.
700
- return ids;
826
+ return rows.map((row, index) => ids[index] ?? idOf(meta, row));
701
827
  });
702
828
  }
703
829
  async deleteOneById(entity, id, opts) {
@@ -723,7 +849,7 @@ export class AbstractQuerier {
723
849
  // A soft delete stamps the rows, which a `RETURNING` would report stamped rather than as they were.
724
850
  const reportingWrites = this.reportingWrites(meta, 'delete');
725
851
  const deletion = deletionOf(meta, rest);
726
- if (reportingWrites && !deletion.stamp && this.deletesByFilter(entity, q)) {
852
+ if (reportingWrites && !deletion.stamp && this.deletesByFilter(entity, q, rest)) {
727
853
  return this.returned(entity, await reportingWrites.delete(entity, q, rest, read), keys);
728
854
  }
729
855
  // A delete hook receives whole rows; without one, only the keys `returning` names and the ids are read.
@@ -737,14 +863,14 @@ export class AbstractQuerier {
737
863
  });
738
864
  }
739
865
  /** Whether an update is its one statement over `q`: no version to lock, relation to write or page to settle first. */
740
- updatesByFilter(entity, q, payload) {
866
+ updatesByFilter(entity, q, payload, opts) {
741
867
  const meta = getMeta(entity);
742
- return !meta.version && !writesRelations(meta, [payload]) && !this.settlesWrite(entity, q);
868
+ return !meta.version && !writesRelations(meta, [payload]) && !this.settlesWrite(entity, q, opts);
743
869
  }
744
870
  /** Whether a delete is its one statement over `q`: no hook, cascade or page needs its rows read first. */
745
- deletesByFilter(entity, q) {
871
+ deletesByFilter(entity, q, opts) {
746
872
  const meta = getMeta(entity);
747
- return !this.watchesDelete(entity) && !cascadingRelations(meta, 'delete').length && !this.settlesWrite(entity, q);
873
+ return (!this.watchesDelete(entity) && !cascadingRelations(meta, 'delete').length && !this.settlesWrite(entity, q, opts));
748
874
  }
749
875
  /** Whether a delete hook listens on the entity, so a delete reads each row whole to hand it over. */
750
876
  watchesDelete(entity) {
@@ -753,7 +879,7 @@ export class AbstractQuerier {
753
879
  /** Deletes the rows `q` matches, or the ones `read` holds, reading them first where a hook, cascade or page needs them. */
754
880
  async deleteRows(entity, q, opts, read) {
755
881
  const meta = getMeta(entity);
756
- if (!read && this.deletesByFilter(entity, q)) {
882
+ if (!read && this.deletesByFilter(entity, q, opts)) {
757
883
  return this.internalDeleteMany(entity, q, opts);
758
884
  }
759
885
  const cascades = cascadingRelations(meta, 'delete').length > 0;
@@ -790,46 +916,22 @@ export class AbstractQuerier {
790
916
  * upserts on that key, so a stale id is written rather than silently missed, and an unnamed one
791
917
  * inserts. A composite is always named. The hooks follow the statement: a named row fires the upsert pair.
792
918
  */
793
- async saveIds(entity, payload) {
919
+ saveIds(entity, payload) {
794
920
  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
- }
921
+ // A row that names its key and carries nothing else is a *reference*, not a write - the shape a to-many
922
+ // uses to link rows it did not author. Upserting it would stamp `onUpdate` fields on a row the caller
923
+ // never asked to change, and create one that was meant to exist.
924
+ const branch = (row) => {
925
+ if (!namesKey(meta, row)) {
926
+ return 'insert';
829
927
  }
928
+ return someKey(row, (key) => !meta.ids.some((idKey) => idKey === key)) ? 'upsert' : 'reference';
830
929
  };
831
- await (toInsert.length && toUpsert.length ? this.atomically(write) : write());
832
- return ids;
930
+ return this.writeEach(payload, branch, {
931
+ insert: (rows) => this.insertIds(entity, rows),
932
+ upsert: (rows) => this.upsertMany(entity, { $conflict: keySet(meta.ids) }, rows),
933
+ reference: async (rows) => writtenIds(meta, rows),
934
+ }, ['reference']);
833
935
  }
834
936
  /**
835
937
  * Writes the target of each to-one `rows` hold the key of, and points each row at its own: a row naming
@@ -1116,21 +1218,14 @@ export class AbstractQuerier {
1116
1218
  }
1117
1219
  await this.emitHook(entity, 'afterLoad', rows);
1118
1220
  }
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
1221
  /**
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.
1222
+ * The row each of `rows` matches on the columns an upsert matches on, each naming every one, with `select`,
1223
+ * soft-deleted rows included since a unique key holds across both, held as {@link readForWrite} holds its rows. One
1224
+ * no row matches, or two do, reads none, since a missing row is honest where a guessed one is not.
1129
1225
  */
1130
1226
  async rowsByConflict(entity, conflictKeys, rows, select) {
1131
1227
  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()];
1228
+ const distinct = [...new Map(rows.map((row) => [rowKey(row, keys), row])).values()];
1134
1229
  const byConflict = new Map();
1135
1230
  for (const q of this.keyedReads(keys, distinct, [...new Set([...select, ...keys])])) {
1136
1231
  for (const row of await this.readForWrite(entity, q, UPDATING_DELETED)) {
@@ -1140,20 +1235,6 @@ export class AbstractQuerier {
1140
1235
  }
1141
1236
  return rows.map((row) => byConflict.get(rowKey(row, keys)));
1142
1237
  }
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
1238
  /** Reads of the rows matching one of `rows` on `keys`, as many per statement as a key list takes, selecting `select`. */
1158
1239
  keyedReads(keys, rows, select) {
1159
1240
  const $select = keySet(select);
@@ -61,6 +61,8 @@ export class AbstractQuerierPool {
61
61
  constructor(dialect, extra) {
62
62
  this.dialect = dialect;
63
63
  this.extra = extra;
64
+ // Reading `policies` refuses a mode the engine cannot hold: read now, the pool is refused when built.
65
+ void dialect.policies;
64
66
  }
65
67
  /** The querier of the transaction this flow runs in, where this pool handed it out. */
66
68
  ambientQuerier() {