uql-orm 0.101.5 → 0.102.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 (37) hide show
  1. package/dist/dialect/abstractSqlDialect.d.ts +12 -3
  2. package/dist/dialect/abstractSqlDialect.js +24 -14
  3. package/dist/dialect/mysqlLikeSqlDialect.d.ts +2 -2
  4. package/dist/dialect/mysqlLikeSqlDialect.js +5 -2
  5. package/dist/dialect/pgLikeSqlDialect.js +1 -0
  6. package/dist/libsql/libsqlDialect.d.ts +5 -0
  7. package/dist/libsql/libsqlDialect.js +5 -0
  8. package/dist/migrate/builder/migrationBuilder.js +1 -1
  9. package/dist/migrate/builder/tableBuilder.js +9 -4
  10. package/dist/migrate/builder/types.d.ts +5 -1
  11. package/dist/migrate/generator/definitionToNode.d.ts +7 -4
  12. package/dist/migrate/generator/definitionToNode.js +12 -13
  13. package/dist/migrate/schemaGenerator.js +1 -1
  14. package/dist/mongodb/mongoDialect.js +1 -0
  15. package/dist/mongodb/mongoIntrospector.js +3 -2
  16. package/dist/mongodb/mongoSchemaGenerator.js +8 -8
  17. package/dist/mssql/mssqlDialect.d.ts +4 -4
  18. package/dist/mssql/mssqlDialect.js +7 -4
  19. package/dist/querier/abstractQuerier.d.ts +52 -17
  20. package/dist/querier/abstractQuerier.js +140 -79
  21. package/dist/querier/abstractSqlQuerier.d.ts +5 -1
  22. package/dist/querier/abstractSqlQuerier.js +16 -1
  23. package/dist/schema/indexDifferences.d.ts +5 -4
  24. package/dist/schema/indexDifferences.js +23 -12
  25. package/dist/schema/schemaASTBuilder.js +3 -3
  26. package/dist/sqlite/hranaQuerier.d.ts +2 -2
  27. package/dist/sqlite/hranaQuerier.js +2 -2
  28. package/dist/sqlite/sqliteDialect.d.ts +4 -3
  29. package/dist/sqlite/sqliteDialect.js +5 -1
  30. package/dist/type/dialect.d.ts +6 -0
  31. package/dist/type/querier.d.ts +6 -0
  32. package/dist/util/ddlExpression.util.d.ts +8 -2
  33. package/dist/util/ddlExpression.util.js +6 -3
  34. package/dist/util/sql.util.d.ts +7 -2
  35. package/dist/util/sql.util.js +16 -3
  36. package/package.json +1 -1
  37. package/skills/uql-orm/SKILL.md +3 -3
@@ -9,6 +9,11 @@ import { type TransactionScope } from './transaction.js';
9
9
  */
10
10
  /** What an upsert reports of a row: the value a driver answers for a lone key, or the key the read back names. */
11
11
  export type UpsertedId<E> = PrimaryKey | WrittenId<E>;
12
+ /** An `UPDATE` and a `DELETE` of one statement each, reporting the rows they wrote with the fields `keys` names. */
13
+ export type WritesReturning = {
14
+ update<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts: QueryOptions, keys: readonly FieldKey<E>[]): Promise<E[]>;
15
+ delete<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts: QueryOptions, keys: readonly FieldKey<E>[]): Promise<E[]>;
16
+ };
12
17
  /** Base class for all database queriers. */
13
18
  export declare abstract class AbstractQuerier implements Querier {
14
19
  #private;
@@ -114,10 +119,10 @@ export declare abstract class AbstractQuerier implements Querier {
114
119
  * transaction with only the fields it lists.
115
120
  */
116
121
  private writeReturning;
117
- /** The rows `q` matches with the fields `keys` names and their keys, through `afterLoad` as a read's are. */
118
- private readReturning;
119
122
  /** The rows `ids` names, in their order, each with only the fields `keys` names. */
120
123
  private readWritten;
124
+ /** What `returning` reports of `rows`: each through `afterLoad`, as a read's are, then only the fields `keys` names. */
125
+ private returned;
121
126
  /**
122
127
  * Writes `rows` and their relations: the to-ones they hold the keys of first, so each row inserts
123
128
  * pointing at its own, then the rows, then their children by the keys the rows got. An insert, and the
@@ -129,15 +134,25 @@ export declare abstract class AbstractQuerier implements Querier {
129
134
  updateOneById<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V> | undefined>>;
130
135
  updateMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V>[]>>;
131
136
  /**
132
- * The number of rows the update changed, or the rows `returning` reads back: their ids settled first, so a
133
- * payload changing what `$where` reads still names them, and read back by those ids in the same transaction.
137
+ * The number of rows the update changed, or the rows `returning` reads back: settled first and held, so the
138
+ * update writes those rows and no other, whatever a payload or another writer does to what `$where` reads.
134
139
  */
135
140
  private updateWhere;
136
- /** Updates the rows `q` matches between the update hooks, atomically where the payload writes relations too. */
141
+ /**
142
+ * An update of one statement reporting the rows it wrote, between the update hooks. A payload writing no
143
+ * column writes nothing, so the rows it names are read instead.
144
+ */
145
+ private updateReturning;
146
+ /**
147
+ * Updates the rows `q` matches, or the ones `settled` already names, between the update hooks, atomically
148
+ * where the payload writes relations too.
149
+ */
137
150
  private updateMatching;
138
151
  /**
139
152
  * The write every update runs, matching the version `lockKey` names where one is being held. Only a
140
- * restore passes none: it writes no content, so there is no update of anyone's to lose.
153
+ * restore passes none: it writes no content, so there is no update of anyone's to lose. A versioned row is
154
+ * named by its one id in `q`, so the lock path writes `q` and ignores `settled`. Elsewhere `settled` names
155
+ * the rows to write, in batches the engine's bind budget allows.
141
156
  */
142
157
  private updateRows;
143
158
  /**
@@ -147,6 +162,8 @@ export declare abstract class AbstractQuerier implements Querier {
147
162
  * still costs one statement. Best effort by nature - the row can change again while we ask.
148
163
  */
149
164
  private throwStaleVersion;
165
+ /** What every update does to its row before its statement: writes the to-ones it holds, fills and guards it. */
166
+ private prepareUpdate;
150
167
  /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
151
168
  private updateColumns;
152
169
  /**
@@ -155,14 +172,22 @@ export declare abstract class AbstractQuerier implements Querier {
155
172
  */
156
173
  protected settlesWrite<E extends object>(entity: Type<E>, q: QuerySearch<E>): boolean;
157
174
  /**
158
- * `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed:
159
- * in one transaction where there are several, so a write split to fit the engine still lands whole.
175
+ * `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed,
176
+ * inside its caller's transaction, so a write split to fit the engine still lands whole.
160
177
  */
161
- protected writeBatches<T>(rows: readonly T[], keyCount: number, write: (batch: T[]) => Promise<number>): Promise<number>;
178
+ private writeBatches;
162
179
  /** Runs a write of several statements as one: in a transaction of its own, or the one already open. */
163
180
  protected atomically<T>(write: () => Promise<T>): Promise<T>;
164
- /** The ids `q` matches, in its own order and page. */
165
- protected settleIds<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<EntityId<E>[]>;
181
+ /** The ids `q` matches, in its own order and page, held as {@link readForWrite} holds them. */
182
+ private settleIds;
183
+ /**
184
+ * The rows a write reads before it writes, held until the open transaction ends where the engine has row
185
+ * locks, so a racing writer waits for the commit; outside a transaction a lock would hold nothing. Elsewhere
186
+ * the transaction is the guard: libSQL and Turso take the write lock at `BEGIN`, SQLite and MongoDB fail the racer.
187
+ */
188
+ private readForWrite;
189
+ /** How the engine writes rows and reports them in one statement, or `undefined` where a write reads them first. */
190
+ protected get writesReturning(): WritesReturning | undefined;
166
191
  /** Runs one UPDATE over `q`, which names its rows by id wherever {@link updateMany} settled them. */
167
192
  protected abstract internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
168
193
  restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;
@@ -177,7 +202,8 @@ export declare abstract class AbstractQuerier implements Querier {
177
202
  /**
178
203
  * An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
179
204
  * as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
180
- * tenant's. A row inserted concurrently fails on its key. See architecture/security-filter-writes.md.
205
+ * tenant's. A found row is held until the write, and a row inserted concurrently fails on its key. See
206
+ * architecture/security-filter-writes.md.
181
207
  */
182
208
  private readThenUpsert;
183
209
  /** Upserts `payload`, answering each row's key in payload order where the engine reports every one. */
@@ -188,8 +214,15 @@ export declare abstract class AbstractQuerier implements Querier {
188
214
  $entity: Type<E>;
189
215
  }, opts?: QueryOptions): Promise<number>;
190
216
  deleteMany<E extends object, const S extends FieldKey<E> = never, const V extends BooleanLike = true>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions & WriteOptions<E, S, V>): Promise<ReturningResult<S, number, QueryFindResult<E, S, V>[]>>;
191
- /** The number of rows deleted, or the rows `returning` reads as they were, before the delete and in its transaction. */
217
+ /** The number of rows deleted, or the rows `returning` reads as they were: held before the delete, which deletes those. */
192
218
  private deleteWhere;
219
+ /** Whether an update is its one statement over `q`: no version to lock, relation to write or page to settle first. */
220
+ private updatesByFilter;
221
+ /** Whether a delete is its one statement over `q`: no hook, cascade or page needs its rows read first. */
222
+ private deletesByFilter;
223
+ /** Whether a delete hook listens on the entity, so a delete reads each row whole to hand it over. */
224
+ private watchesDelete;
225
+ /** Deletes the rows `q` matches, or the ones `read` holds, reading them first where a hook, cascade or page needs them. */
193
226
  private deleteRows;
194
227
  /** Runs one DELETE (or soft-delete stamp) over `q`, which names its rows by id wherever {@link deleteMany} settled them. */
195
228
  protected abstract internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
@@ -210,7 +243,8 @@ export declare abstract class AbstractQuerier implements Querier {
210
243
  private insertChildren;
211
244
  /**
212
245
  * Makes `value` the children of each parent `ids` names, which it owns: the rows it lists are saved,
213
- * keeping what each does not write, and the parent's other children (a junction's other links) go.
246
+ * keeping what each does not write, and the parent's other children (a junction's other links) go. Inside
247
+ * the transaction the update holds.
214
248
  */
215
249
  private replaceChildren;
216
250
  /** A many-to-many's links: the targets are saved, the parent's links to any other go, and the missing ones are added. */
@@ -281,9 +315,10 @@ export declare abstract class AbstractQuerier implements Querier {
281
315
  */
282
316
  private emitLoaded;
283
317
  /**
284
- * The ids of `rows`, read through the filters by the columns an upsert matches them on: after a
285
- * statement that could not report them in payload order, or before a guarded upsert. A row that no
286
- * read row matches, or that two do, keeps `undefined`: a missing id is honest where a guessed one is not.
318
+ * The ids of `rows`, read through the filters by the columns an upsert matches them on, and held as
319
+ * {@link readForWrite} holds them: after a statement that could not report them in payload order, or before a
320
+ * guarded upsert. A row that no read row matches, or that two do, keeps `undefined`: a missing id is honest
321
+ * where a guessed one is not.
287
322
  */
288
323
  protected idsByConflict<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, rows: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
289
324
  /**
@@ -139,6 +139,10 @@ function returnedKeys(meta, returning) {
139
139
  function deletableRows(opts) {
140
140
  return opts?.hardDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts;
141
141
  }
142
+ /** Whether an update of `row` writes a column, its `onUpdate` fills included: one that writes none sends nothing. */
143
+ function writesColumns(meta, row) {
144
+ return filterFieldKeys(meta, row, 'onUpdate').length > 0;
145
+ }
142
146
  /** `row` with only the fields `keys` names. */
143
147
  function pickFields(row, keys) {
144
148
  const picked = {};
@@ -376,15 +380,6 @@ export class AbstractQuerier {
376
380
  const keys = returnedKeys(getMeta(entity), opts?.returning);
377
381
  return keys ? this.atomically(async () => this.readWritten(entity, await write(), keys)) : write();
378
382
  }
379
- /** The rows `q` matches with the fields `keys` names and their keys, through `afterLoad` as a read's are. */
380
- async readReturning(entity, q, keys, opts) {
381
- const $select = keySet([...keys, ...getMeta(entity).ids]);
382
- const rows = await this.internalFindMany(entity, { ...q, $select }, opts);
383
- if (this.hasHook(entity, 'afterLoad')) {
384
- await this.emitHook(entity, 'afterLoad', rows);
385
- }
386
- return rows;
387
- }
388
383
  /** The rows `ids` names, in their order, each with only the fields `keys` names. */
389
384
  async readWritten(entity, ids, keys, opts) {
390
385
  const meta = getMeta(entity);
@@ -397,15 +392,19 @@ export class AbstractQuerier {
397
392
  }
398
393
  // The rows this write wrote, whatever a filter says of them: a soft-deleted one inserted is still written.
399
394
  const read = { ...opts, filters: withoutSoftDeleteFilter(opts?.filters) };
395
+ const $select = keySet([...keys, ...meta.ids]);
400
396
  const rows = [];
401
397
  for (const batch of chunk(known, this.dialect.keyListCapacity(meta.ids.length))) {
402
- rows.push(...(await this.readReturning(entity, { $where: whereIds(meta, batch) }, keys, read)));
398
+ rows.push(...(await this.internalFindMany(entity, { $select, $where: whereIds(meta, batch) }, read)));
403
399
  }
404
400
  const byKey = new Map(rows.map((row) => [rowKey(row, meta.ids), row]));
405
- return known.flatMap((id) => {
406
- const row = byKey.get(rowKey(whereIds(meta, id), meta.ids));
407
- return row ? [pickFields(row, keys)] : [];
408
- });
401
+ const ordered = known.flatMap((id) => byKey.get(rowKey(whereIds(meta, id), meta.ids)) ?? []);
402
+ return this.returned(entity, ordered, keys);
403
+ }
404
+ /** What `returning` reports of `rows`: each through `afterLoad`, as a read's are, then only the fields `keys` names. */
405
+ async returned(entity, rows, keys) {
406
+ await this.emitLoaded(entity, rows, undefined);
407
+ return rows.map((row) => pickFields(row, keys));
409
408
  }
410
409
  /**
411
410
  * Writes `rows` and their relations: the to-ones they hold the keys of first, so each row inserts
@@ -429,8 +428,8 @@ export class AbstractQuerier {
429
428
  return this.updateWhere(entity, q, payload, opts);
430
429
  }
431
430
  /**
432
- * The number of rows the update changed, or the rows `returning` reads back: their ids settled first, so a
433
- * payload changing what `$where` reads still names them, and read back by those ids in the same transaction.
431
+ * The number of rows the update changed, or the rows `returning` reads back: settled first and held, so the
432
+ * update writes those rows and no other, whatever a payload or another writer does to what `$where` reads.
434
433
  */
435
434
  async updateWhere(entity, q, payload, opts) {
436
435
  assertNamesRows(entity, 'updateMany', q, opts);
@@ -440,27 +439,49 @@ export class AbstractQuerier {
440
439
  if (!keys) {
441
440
  return this.updateMatching(entity, q, payload, opts);
442
441
  }
442
+ const { writesReturning } = this;
443
+ if (writesReturning && this.updatesByFilter(entity, q, payload)) {
444
+ return this.updateReturning(writesReturning, entity, q, payload, rest, keys);
445
+ }
443
446
  return this.atomically(async () => {
444
447
  const ids = await this.settleIds(entity, q, rest);
445
- await this.updateMatching(entity, q, payload, rest);
448
+ await this.updateMatching(entity, q, payload, rest, ids);
446
449
  return this.readWritten(entity, ids, keys, rest);
447
450
  });
448
451
  }
449
- /** Updates the rows `q` matches between the update hooks, atomically where the payload writes relations too. */
450
- updateMatching(entity, q, payload, opts) {
452
+ /**
453
+ * An update of one statement reporting the rows it wrote, between the update hooks. A payload writing no
454
+ * column writes nothing, so the rows it names are read instead.
455
+ */
456
+ updateReturning(writes, entity, q, payload, opts, keys) {
457
+ const meta = getMeta(entity);
458
+ const read = [...keys, ...meta.ids];
459
+ return this.hooked(entity, 'Update', [payload], async ([row]) => {
460
+ await this.prepareUpdate(entity, row);
461
+ const rows = writesColumns(meta, row)
462
+ ? await writes.update(entity, q, row, opts, read)
463
+ : await this.internalFindMany(entity, { ...q, $select: keySet(read) }, opts);
464
+ return this.returned(entity, rows, keys);
465
+ });
466
+ }
467
+ /**
468
+ * Updates the rows `q` matches, or the ones `settled` already names, between the update hooks, atomically
469
+ * where the payload writes relations too.
470
+ */
471
+ updateMatching(entity, q, payload, opts, settled) {
451
472
  const meta = getMeta(entity);
452
- const update = () => this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, meta.version));
473
+ const update = () => this.hooked(entity, 'Update', [payload], ([row]) => this.updateRows(entity, q, row, opts, meta.version, settled));
453
474
  return writesRelations(meta, [payload]) ? this.atomically(update) : update();
454
475
  }
455
476
  /**
456
477
  * The write every update runs, matching the version `lockKey` names where one is being held. Only a
457
- * restore passes none: it writes no content, so there is no update of anyone's to lose.
478
+ * restore passes none: it writes no content, so there is no update of anyone's to lose. A versioned row is
479
+ * named by its one id in `q`, so the lock path writes `q` and ignores `settled`. Elsewhere `settled` names
480
+ * the rows to write, in batches the engine's bind budget allows.
458
481
  */
459
- async updateRows(entity, q, row, opts, lockKey) {
482
+ async updateRows(entity, q, row, opts, lockKey, settled) {
460
483
  const meta = getMeta(entity);
461
- await this.writeHeldReferences(entity, [row]);
462
- fillOnFields(meta, [row], 'onUpdate');
463
- guardWrite(meta, [row], 'update');
484
+ await this.prepareUpdate(entity, row);
464
485
  const relKeys = ownedRelations(meta).filter((key) => Object.hasOwn(row, key));
465
486
  const settles = !!relKeys.length || this.settlesWrite(entity, q);
466
487
  if (lockKey) {
@@ -470,18 +491,20 @@ export class AbstractQuerier {
470
491
  const changes = await this.updateColumns(entity, lock.q, row, opts, 0);
471
492
  return changes || this.throwStaleVersion(entity, lockKey, q, lock.expected, opts);
472
493
  }
473
- if (!settles) {
494
+ if (!settles && !settled) {
474
495
  return this.updateColumns(entity, q, row, opts, 0);
475
496
  }
476
- const ids = await this.settleIds(entity, q, opts);
477
- if (!ids.length) {
478
- return 0;
479
- }
480
- const changes = await this.writeBatches(ids, meta.ids.length, (batch) => this.updateColumns(entity, { $where: whereIds(meta, batch) }, row, opts, batch.length));
481
- for (const relKey of relKeys) {
482
- await this.replaceChildren(entity, relKey, ids, row[relKey]);
483
- }
484
- return changes;
497
+ return this.atomically(async () => {
498
+ const ids = settled ?? (await this.settleIds(entity, q, opts));
499
+ if (!ids.length) {
500
+ return 0;
501
+ }
502
+ const changes = await this.writeBatches(ids, meta.ids.length, (batch) => this.updateColumns(entity, { $where: whereIds(meta, batch) }, row, opts, batch.length));
503
+ for (const relKey of relKeys) {
504
+ await this.replaceChildren(entity, relKey, ids, row[relKey]);
505
+ }
506
+ return changes;
507
+ });
485
508
  }
486
509
  /**
487
510
  * Why an update matched no row. The filter named the row by its id, so reading by that id alone
@@ -500,10 +523,16 @@ export class AbstractQuerier {
500
523
  : `'${entityName(meta)}' moved on: the payload carries '${key}' ${String(expected)}, the row is at ${String(actual)}`;
501
524
  throw new UqlOptimisticLockError(message, expected, actual);
502
525
  }
526
+ /** What every update does to its row before its statement: writes the to-ones it holds, fills and guards it. */
527
+ async prepareUpdate(entity, row) {
528
+ const meta = getMeta(entity);
529
+ await this.writeHeldReferences(entity, [row]);
530
+ fillOnFields(meta, [row], 'onUpdate');
531
+ guardWrite(meta, [row], 'update');
532
+ }
503
533
  /** The UPDATE, skipped where the payload writes no column, reporting `unwritten` instead. */
504
534
  async updateColumns(entity, q, row, opts, unwritten) {
505
- const writes = filterFieldKeys(getMeta(entity), row, 'onUpdate').length > 0;
506
- return writes ? this.internalUpdateMany(entity, q, row, opts) : unwritten;
535
+ return writesColumns(getMeta(entity), row) ? this.internalUpdateMany(entity, q, row, opts) : unwritten;
507
536
  }
508
537
  /**
509
538
  * Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or
@@ -514,30 +543,39 @@ export class AbstractQuerier {
514
543
  return isPagedQuery(q) || (!dialect.features.correlatedWrites && dialect.constrainsRelations(entity, q.$where));
515
544
  }
516
545
  /**
517
- * `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed:
518
- * in one transaction where there are several, so a write split to fit the engine still lands whole.
546
+ * `write` over `rows` in lists of as many as one statement names by `keyCount` keys, summing what each changed,
547
+ * inside its caller's transaction, so a write split to fit the engine still lands whole.
519
548
  */
520
549
  async writeBatches(rows, keyCount, write) {
521
- const batches = chunk(rows, this.dialect.keyListCapacity(keyCount));
522
- const each = async () => {
523
- let changes = 0;
524
- for (const batch of batches) {
525
- changes += await write(batch);
526
- }
527
- return changes;
528
- };
529
- return batches.length > 1 ? this.atomically(each) : each();
550
+ let changes = 0;
551
+ for (const batch of chunk(rows, this.dialect.keyListCapacity(keyCount))) {
552
+ changes += await write(batch);
553
+ }
554
+ return changes;
530
555
  }
531
556
  /** Runs a write of several statements as one: in a transaction of its own, or the one already open. */
532
557
  atomically(write) {
533
558
  return this.scopeHere() ? write() : this.transaction(write);
534
559
  }
535
- /** The ids `q` matches, in its own order and page. */
560
+ /** The ids `q` matches, in its own order and page, held as {@link readForWrite} holds them. */
536
561
  async settleIds(entity, q, opts) {
537
562
  const meta = getMeta(entity);
538
- const rows = await this.internalFindMany(entity, idOnlyQuery(meta, q), opts);
563
+ const rows = await this.readForWrite(entity, idOnlyQuery(meta, q), opts);
539
564
  return rows.map((row) => idOf(meta, row));
540
565
  }
566
+ /**
567
+ * The rows a write reads before it writes, held until the open transaction ends where the engine has row
568
+ * locks, so a racing writer waits for the commit; outside a transaction a lock would hold nothing. Elsewhere
569
+ * the transaction is the guard: libSQL and Turso take the write lock at `BEGIN`, SQLite and MongoDB fail the racer.
570
+ */
571
+ readForWrite(entity, q, opts) {
572
+ const held = this.dialect.features.rowLocks && this.scopeHere() ? { ...q, $lock: true } : q;
573
+ return this.internalFindMany(entity, held, opts);
574
+ }
575
+ /** How the engine writes rows and reports them in one statement, or `undefined` where a write reads them first. */
576
+ get writesReturning() {
577
+ return undefined;
578
+ }
541
579
  async restoreOneById(entity, id) {
542
580
  assertIdValue(entity, id);
543
581
  return this.restoreMany(entity, { $where: whereIds(getMeta(entity), id) });
@@ -580,7 +618,8 @@ export class AbstractQuerier {
580
618
  /**
581
619
  * An upsert as a read, then writes: the rows the conflict names are read through the filters, those found update
582
620
  * as `updateMany` does and the rest insert, so either branch writes its relations and a guarded row stays its
583
- * tenant's. A row inserted concurrently fails on its key. See architecture/security-filter-writes.md.
621
+ * tenant's. A found row is held until the write, and a row inserted concurrently fails on its key. See
622
+ * architecture/security-filter-writes.md.
584
623
  */
585
624
  async readThenUpsert(entity, conflictPaths, rows, update) {
586
625
  const meta = getMeta(entity);
@@ -589,7 +628,7 @@ export class AbstractQuerier {
589
628
  return [];
590
629
  }
591
630
  const keys = getKeys(conflictPaths);
592
- const write = async () => {
631
+ return this.atomically(async () => {
593
632
  const ids = await this.idsByConflict(entity, conflictPaths, rows);
594
633
  for (const [index, row] of rows.entries()) {
595
634
  // An empty `update` leaves a found row as it is, as `DO NOTHING` does.
@@ -606,10 +645,7 @@ export class AbstractQuerier {
606
645
  }
607
646
  // A found row's key is adopted by the caller; an inserted one carries the key its insert wrote.
608
647
  return ids;
609
- };
610
- return rows.length > 1 || writesRelations(meta, [...rows, ...(update ? [update] : [])])
611
- ? this.atomically(write)
612
- : write();
648
+ });
613
649
  }
614
650
  async deleteOneById(entity, id, opts) {
615
651
  assertIdValue(entity, id);
@@ -620,7 +656,7 @@ export class AbstractQuerier {
620
656
  const [entity, q, opts] = entityArgs(args);
621
657
  return this.deleteWhere(entity, q, opts);
622
658
  }
623
- /** The number of rows deleted, or the rows `returning` reads as they were, before the delete and in its transaction. */
659
+ /** The number of rows deleted, or the rows `returning` reads as they were: held before the delete, which deletes those. */
624
660
  async deleteWhere(entity, q, opts) {
625
661
  assertNamesRows(entity, 'deleteMany', q, opts);
626
662
  const meta = getMeta(entity);
@@ -629,27 +665,51 @@ export class AbstractQuerier {
629
665
  if (!keys) {
630
666
  return this.deleteRows(entity, q, opts);
631
667
  }
668
+ const read = [...keys, ...meta.ids];
669
+ // A soft delete stamps the rows, which a `RETURNING` would report stamped rather than as they were.
670
+ const { writesReturning } = this;
671
+ if (writesReturning && (rest.hardDelete || !meta.softDelete) && this.deletesByFilter(entity, q)) {
672
+ return this.returned(entity, await writesReturning.delete(entity, q, rest, read), keys);
673
+ }
674
+ // A delete hook receives whole rows; without one, only the keys `returning` names and the ids are read.
675
+ const $select = this.watchesDelete(entity) ? undefined : keySet(read);
632
676
  return this.atomically(async () => {
633
- const rows = await this.readReturning(entity, q, keys, deletableRows(rest));
634
- await this.deleteRows(entity, q, rest);
635
- return rows.map((row) => pickFields(row, keys));
677
+ const rows = await this.readForWrite(entity, { ...q, $select }, deletableRows(rest));
678
+ // `afterLoad` sees copies, as a read's rows, so a delete hook still gets each row as it was read.
679
+ const reported = await this.returned(entity, clone(rows), keys);
680
+ await this.deleteRows(entity, q, rest, rows);
681
+ return reported;
636
682
  });
637
683
  }
638
- async deleteRows(entity, q, opts) {
684
+ /** Whether an update is its one statement over `q`: no version to lock, relation to write or page to settle first. */
685
+ updatesByFilter(entity, q, payload) {
639
686
  const meta = getMeta(entity);
640
- const cascades = cascadingRelations(meta, 'delete').length > 0;
641
- const watched = this.hasHook(entity, 'beforeDelete') || this.hasHook(entity, 'afterDelete');
642
- if (!watched && !cascades && !this.settlesWrite(entity, q)) {
687
+ return !meta.version && !writesRelations(meta, [payload]) && !this.settlesWrite(entity, q);
688
+ }
689
+ /** Whether a delete is its one statement over `q`: no hook, cascade or page needs its rows read first. */
690
+ deletesByFilter(entity, q) {
691
+ const meta = getMeta(entity);
692
+ return !this.watchesDelete(entity) && !cascadingRelations(meta, 'delete').length && !this.settlesWrite(entity, q);
693
+ }
694
+ /** Whether a delete hook listens on the entity, so a delete reads each row whole to hand it over. */
695
+ watchesDelete(entity) {
696
+ return this.hasHook(entity, 'beforeDelete') || this.hasHook(entity, 'afterDelete');
697
+ }
698
+ /** Deletes the rows `q` matches, or the ones `read` holds, reading them first where a hook, cascade or page needs them. */
699
+ async deleteRows(entity, q, opts, read) {
700
+ const meta = getMeta(entity);
701
+ if (!read && this.deletesByFilter(entity, q)) {
643
702
  return this.internalDeleteMany(entity, q, opts);
644
703
  }
645
- const readOpts = deletableRows(opts);
646
- // A hook receives the rows themselves; the ids read off them name the same rows a second read might not.
647
- const doomed = watched ? await this.internalFindMany(entity, q, readOpts) : [];
648
- const ids = watched ? doomed.map((row) => idOf(meta, row)) : await this.settleIds(entity, q, readOpts);
649
- if (!ids.length) {
650
- return 0;
651
- }
652
- const remove = async () => {
704
+ const cascades = cascadingRelations(meta, 'delete').length > 0;
705
+ const watched = this.watchesDelete(entity);
706
+ return this.atomically(async () => {
707
+ // A hook receives the rows themselves; the ids read off them name the same rows a second read might not.
708
+ const doomed = read ?? (await this.readForWrite(entity, watched ? q : idOnlyQuery(meta, q), deletableRows(opts)));
709
+ if (!doomed.length) {
710
+ return 0;
711
+ }
712
+ const ids = doomed.map((row) => idOf(meta, row));
653
713
  await this.emitHook(entity, 'beforeDelete', doomed);
654
714
  const changes = await this.writeBatches(ids, meta.ids.length, async (batch) => {
655
715
  // Children first: they hold the foreign key, which a schema without `ON DELETE CASCADE` enforces.
@@ -660,8 +720,7 @@ export class AbstractQuerier {
660
720
  });
661
721
  await this.emitHook(entity, 'afterDelete', doomed);
662
722
  return changes;
663
- };
664
- return cascades ? this.atomically(remove) : remove();
723
+ });
665
724
  }
666
725
  async saveOne(entity, payload, opts) {
667
726
  const [written] = await this.writeReturning(entity, () => this.saveIds(entity, [payload]), opts);
@@ -754,7 +813,8 @@ export class AbstractQuerier {
754
813
  }
755
814
  /**
756
815
  * Makes `value` the children of each parent `ids` names, which it owns: the rows it lists are saved,
757
- * keeping what each does not write, and the parent's other children (a junction's other links) go.
816
+ * keeping what each does not write, and the parent's other children (a junction's other links) go. Inside
817
+ * the transaction the update holds.
758
818
  */
759
819
  async replaceChildren(entity, relKey, ids, value) {
760
820
  const relOpts = relationOf(getMeta(entity), relKey);
@@ -1011,9 +1071,10 @@ export class AbstractQuerier {
1011
1071
  await this.emitHook(entity, 'afterLoad', rows);
1012
1072
  }
1013
1073
  /**
1014
- * The ids of `rows`, read through the filters by the columns an upsert matches them on: after a
1015
- * statement that could not report them in payload order, or before a guarded upsert. A row that no
1016
- * read row matches, or that two do, keeps `undefined`: a missing id is honest where a guessed one is not.
1074
+ * The ids of `rows`, read through the filters by the columns an upsert matches them on, and held as
1075
+ * {@link readForWrite} holds them: after a statement that could not report them in payload order, or before a
1076
+ * guarded upsert. A row that no read row matches, or that two do, keeps `undefined`: a missing id is honest
1077
+ * where a guessed one is not.
1017
1078
  */
1018
1079
  async idsByConflict(entity, conflictPaths, rows) {
1019
1080
  const meta = getMeta(entity);
@@ -1024,7 +1085,7 @@ export class AbstractQuerier {
1024
1085
  const found = [];
1025
1086
  for (const batch of chunk(distinct, this.dialect.keyListCapacity(keys.length))) {
1026
1087
  const q = { $select: keySet([...meta.ids, ...keys]), $where: whereKeysIn(keys, batch) };
1027
- found.push(await this.internalFindMany(entity, q, { filters: withoutSoftDeleteFilter(undefined) }));
1088
+ found.push(await this.readForWrite(entity, q, { filters: withoutSoftDeleteFilter(undefined) }));
1028
1089
  }
1029
1090
  const byConflict = new Map();
1030
1091
  for (const row of found.flat()) {
@@ -1,7 +1,7 @@
1
1
  import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import type { EntityData, ExtraOptions, Query, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryPage, QueryGroupMap, QueryOptions, QuerySearch, QueryUpdateResult, RawRow, SavepointCommand, SqlQuerier, SqlStatement, TransactionOptions, Type, UpdatePayload } from '../type/index.js';
3
3
  import type { BuildUpdateResultPayload } from '../util/sql.util.js';
4
- import { AbstractQuerier, type UpsertedId } from './abstractQuerier.js';
4
+ import { AbstractQuerier, type UpsertedId, type WritesReturning } from './abstractQuerier.js';
5
5
  export declare abstract class AbstractSqlQuerier extends AbstractQuerier implements SqlQuerier {
6
6
  #private;
7
7
  readonly dialect: AbstractSqlDialect;
@@ -83,6 +83,10 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
83
83
  protected internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
84
84
  internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
85
85
  internalUpdateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
86
+ /** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
87
+ protected get writesReturning(): WritesReturning | undefined;
88
+ /** The rows the write `build` renders reports, `RETURNING` the fields `keys` names. */
89
+ private reportedRows;
86
90
  protected internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E[], update?: UpdatePayload<E>): Promise<(UpsertedId<E> | undefined)[] | undefined>;
87
91
  private runUpsert;
88
92
  protected internalDeleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
@@ -278,6 +278,21 @@ export class AbstractSqlQuerier extends AbstractQuerier {
278
278
  const { changes = 0 } = await this.exec((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
279
279
  return changes;
280
280
  }
281
+ /** `UPDATE` and `DELETE` with a `RETURNING` read as a read's rows are, where the engine has it. */
282
+ get writesReturning() {
283
+ return this.dialect.features.writeReturning ? this.#returningWrites : undefined;
284
+ }
285
+ #returningWrites = {
286
+ update: (entity, q, payload, opts, keys) => this.reportedRows(entity, keys, (ctx) => this.dialect.update(ctx, entity, q, payload, opts)),
287
+ delete: (entity, q, opts, keys) => this.reportedRows(entity, keys, (ctx) => this.dialect.delete(ctx, entity, q, opts)),
288
+ };
289
+ /** The rows the write `build` renders reports, `RETURNING` the fields `keys` names. */
290
+ reportedRows(entity, keys, build) {
291
+ return this.readRows((ctx) => {
292
+ build(ctx);
293
+ return this.dialect.returning(ctx, entity, keys);
294
+ });
295
+ }
281
296
  async internalUpsertMany(entity, conflictPaths, payload, update) {
282
297
  if (!payload.length) {
283
298
  return [];
@@ -364,7 +379,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
364
379
  * case it overrides all three. The bookkeeping around them stays above, written once.
365
380
  */
366
381
  async internalBegin(opts) {
367
- for (const sql of this.dialect.getBeginTransactionStatements(opts?.isolationLevel)) {
382
+ for (const sql of this.dialect.getBeginTransactionStatements(opts)) {
368
383
  await this.runTransactionCommand(sql);
369
384
  }
370
385
  }
@@ -7,7 +7,7 @@ import type { IndexNode } from './types.js';
7
7
  * `textIndex` is a text index's weights and language, kept by an engine that lists its fields in no declared order.
8
8
  */
9
9
  export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector' | 'distance' | 'textIndex';
10
- type ComparableIndex = Pick<IndexNode, 'name' | 'entries' | 'unique'>;
10
+ type ComparableIndex = Pick<IndexNode, 'name' | 'entries' | 'unique' | 'where'>;
11
11
  /**
12
12
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
13
13
  * over an expression, whose text the engine reprints, falls back to its name.
@@ -20,7 +20,7 @@ export declare function indexSignature(index: ComparableIndex): string;
20
20
  export declare function indexNameStem(name: string): string;
21
21
  /**
22
22
  * Pairs by name, then what is left by shape: an index the database has under another name is still
23
- * the one asked for. What stays unpaired is created or dropped.
23
+ * the one asked for. A partial index pairs by name alone, since its predicate is in its name.
24
24
  */
25
25
  export declare function pairIndexes<S extends ComparableIndex, T extends ComparableIndex>(source: readonly S[], target: readonly T[]): {
26
26
  created: S[];
@@ -49,8 +49,9 @@ export declare function indexChanges<I extends IndexSchema>(table: string, decla
49
49
  kept: IndexNode[];
50
50
  };
51
51
  /**
52
- * What two indexes differ by, comparing only what both sides state structurally: an expression, a JSON
53
- * path or a predicate is reprinted by the engine, so never compared.
52
+ * What two indexes differ by, comparing only what both sides state structurally. An expression or a JSON
53
+ * path is reprinted by the engine, so never compared; a predicate only by whether there is one, its text
54
+ * being in an unnamed index's name.
54
55
  */
55
56
  export declare function describeIndexDifferences(source: IndexSchema, target: IndexSchema, facets: ReadonlySet<IndexFacet>): string[];
56
57
  export {};