@mistriwork/engine 1.0.0-rc.33 → 1.0.0-rc.35

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.
@@ -454,11 +454,55 @@ export interface WriteTransaction {
454
454
  insert(request: InsertRequest): Promise<InsertResult>;
455
455
  remove(request: DeleteRequest): Promise<DeleteResult>;
456
456
  update(request: UpdateRequest): Promise<UpdateResult>;
457
+ /** Several rows of one table created in one statement, each under `insert`'s contract; results in request order.
458
+ * Optional: a layer that cannot carry a batch through its own checks leaves it out, and `insertAll` falls back to
459
+ * `insert` a row at a time, so every check still runs per row. */
460
+ insertMany?(requests: readonly InsertRequest[]): Promise<InsertResult[]>;
461
+ /** Several rows of one table changed in one statement, each under `update`'s contract (its key, its own values,
462
+ * its own `expected`); results in request order. Optional, like `insertMany`, and `updateAll` falls back the same way. */
463
+ updateMany?(requests: readonly UpdateRequest[]): Promise<UpdateResult[]>;
457
464
  /** Internal: a flow's notify step (appFlows.ts). The record's `notify` rules on `{ flow: audience }` tell their people
458
465
  * in this transaction, as a write's rules do, with the step's words. Writes nothing to the record. Only the flows'
459
466
  * own command reaches it, about its own target; a facade that cannot carry it omits it. */
460
467
  tell?(request: TellRequest): Promise<void>;
461
468
  }
469
+ /** Several inserts of one table: one statement where the transaction carries a batch, else one at a time, in order. */
470
+ export declare function insertAll(tx: WriteTransaction, requests: readonly InsertRequest[]): Promise<InsertResult[]>;
471
+ /** Several updates of one table: one statement where the transaction carries a batch, else one at a time, in order. */
472
+ export declare function updateAll(tx: WriteTransaction, requests: readonly UpdateRequest[]): Promise<UpdateResult[]>;
473
+ /** Each request written in turn, each waiting for the one before it. */
474
+ export declare function oneAtATime<Q, R>(requests: readonly Q[], write: (request: Q) => Promise<R>): Promise<R[]>;
475
+ /**
476
+ * A batch carried through a layer whose single write is `through(request, write)`: the layer's own checks before and
477
+ * after its write, around a write it is handed. Each row runs its checks in order up to its write and waits there;
478
+ * the rows that reached their write are written by `many` in one statement; then each row hears its own result and
479
+ * finishes its checks after it, one row at a time, in order. So a layer that offers a batch runs exactly the checks
480
+ * it runs for one row, and its inner layer sees one call.
481
+ *
482
+ * What differs from a row at a time, and is the price of one statement: a row's checks before its write run before
483
+ * the rows ahead of it are written (rows of one batch cannot depend on each other), and a check after a write sees
484
+ * the whole batch written. A row whose checks answer without writing keeps its own answer. Any row refused before
485
+ * the statement refuses the batch and nothing is written; a statement that fails, or a row refused after it, fails
486
+ * the batch, and the transaction it runs in rolls back.
487
+ */
488
+ export declare function gathered<Q, R>(requests: readonly Q[], through: (request: Q, write: (request: Q) => Promise<R>) => Promise<R>, many: (requests: readonly Q[]) => Promise<R[]>): Promise<R[]>;
489
+ /** A batch is one table's: its rows' own table names, which must agree. */
490
+ export declare function sameTable(tables: readonly string[]): string;
491
+ /** Consecutive rows naming the same columns, so each run is one multi-row VALUES list. */
492
+ export declare function runsOfColumns<T extends {
493
+ applied: Record<string, unknown>;
494
+ }>(plans: readonly T[]): T[][];
495
+ /** Rows split so no statement binds more parameters than a database takes; most batches are one chunk. */
496
+ export declare function chunked<T>(rows: readonly T[], weight: (row: T) => number): T[][];
497
+ /**
498
+ * RETURNING's rows put back in the order of the requests that wrote them. Neither SQLite nor PostgreSQL promises
499
+ * the order of a multi-row INSERT's RETURNING, though both answer in VALUES order: each request takes the row in
500
+ * its own place when that row holds its values, else the first unclaimed row that does. Two requests whose values
501
+ * agree wrote rows a caller cannot tell apart by what it asked, so either is a right answer.
502
+ */
503
+ export declare function batchedRows(applied: ReadonlyArray<Record<string, unknown>>, stored: ReadonlyArray<Record<string, unknown>>): Record<string, unknown>[];
504
+ /** A key that matched no row, or more than one: a guarded update's miss is a conflict, any other a refusal. */
505
+ export declare function refuseUpdateMatches(request: UpdateRequest, count: number): never;
462
506
  /** What a flow's notify step tells: whom (an audience a `notify` rule names `on: { flow }`), about which record, and its words. */
463
507
  export interface TellRequest {
464
508
  table: string;
@@ -355,6 +355,168 @@ export class Serial {
355
355
  return next;
356
356
  }
357
357
  }
358
+ /** Several inserts of one table: one statement where the transaction carries a batch, else one at a time, in order. */
359
+ export function insertAll(tx, requests) {
360
+ return tx.insertMany && requests.length > 1 ? tx.insertMany(requests) : oneAtATime(requests, (request) => tx.insert(request));
361
+ }
362
+ /** Several updates of one table: one statement where the transaction carries a batch, else one at a time, in order. */
363
+ export function updateAll(tx, requests) {
364
+ return tx.updateMany && requests.length > 1 ? tx.updateMany(requests) : oneAtATime(requests, (request) => tx.update(request));
365
+ }
366
+ /** Each request written in turn, each waiting for the one before it. */
367
+ export async function oneAtATime(requests, write) {
368
+ const results = [];
369
+ for (const request of requests)
370
+ results.push(await write(request));
371
+ return results;
372
+ }
373
+ /**
374
+ * A batch carried through a layer whose single write is `through(request, write)`: the layer's own checks before and
375
+ * after its write, around a write it is handed. Each row runs its checks in order up to its write and waits there;
376
+ * the rows that reached their write are written by `many` in one statement; then each row hears its own result and
377
+ * finishes its checks after it, one row at a time, in order. So a layer that offers a batch runs exactly the checks
378
+ * it runs for one row, and its inner layer sees one call.
379
+ *
380
+ * What differs from a row at a time, and is the price of one statement: a row's checks before its write run before
381
+ * the rows ahead of it are written (rows of one batch cannot depend on each other), and a check after a write sees
382
+ * the whole batch written. A row whose checks answer without writing keeps its own answer. Any row refused before
383
+ * the statement refuses the batch and nothing is written; a statement that fails, or a row refused after it, fails
384
+ * the batch, and the transaction it runs in rolls back.
385
+ */
386
+ export async function gathered(requests, through, many) {
387
+ const rows = [];
388
+ const collected = [];
389
+ /* Unblock every row still waiting at its write and let it run its own failure path, so nothing is left pending. */
390
+ const abandon = async (error, from = 0) => {
391
+ let first;
392
+ for (const row of rows.slice(from)) {
393
+ row.fail?.(error);
394
+ try {
395
+ await row.outcome;
396
+ }
397
+ catch (rowError) {
398
+ first ??= { error: rowError };
399
+ }
400
+ }
401
+ return first ? first.error : error;
402
+ };
403
+ for (const request of requests) {
404
+ const row = { outcome: undefined };
405
+ let reached;
406
+ const reachedWrite = new Promise((resolve) => (reached = resolve));
407
+ const answer = new Promise((resolve, reject) => {
408
+ row.settle = resolve;
409
+ row.fail = reject;
410
+ });
411
+ row.outcome = Promise.resolve().then(() => through(request, (written) => {
412
+ if (row.at !== undefined)
413
+ return Promise.reject(new Error('A gathered row may write once.'));
414
+ row.at = collected.push(written) - 1;
415
+ reached();
416
+ return answer;
417
+ }));
418
+ rows.push(row);
419
+ const ended = row.outcome.then(() => undefined, (error) => ({ error }));
420
+ const early = await Promise.race([reachedWrite.then(() => undefined), ended]);
421
+ if (row.at === undefined && early) {
422
+ /* Refused before its write: nothing is written; the rows waiting at theirs hear the refusal. */
423
+ rows.pop();
424
+ await abandon(early.error);
425
+ throw early.error;
426
+ }
427
+ if (row.at === undefined) {
428
+ delete row.settle;
429
+ delete row.fail;
430
+ }
431
+ }
432
+ if (collected.length) {
433
+ let written;
434
+ try {
435
+ written = await many(collected);
436
+ }
437
+ catch (error) {
438
+ throw await abandon(error);
439
+ }
440
+ for (let index = 0; index < rows.length; index++) {
441
+ const row = rows[index];
442
+ if (row.at !== undefined)
443
+ row.settle(written[row.at]);
444
+ try {
445
+ await row.outcome;
446
+ }
447
+ catch (error) {
448
+ await abandon(error, index + 1);
449
+ throw error;
450
+ }
451
+ }
452
+ }
453
+ return Promise.all(rows.map((row) => row.outcome));
454
+ }
455
+ /** A batch is one table's: its rows' own table names, which must agree. */
456
+ export function sameTable(tables) {
457
+ const table = tables[0];
458
+ if (table === undefined || tables.some((name) => name !== table))
459
+ throw new Refusal('A batch writes one table.');
460
+ return table;
461
+ }
462
+ /** Consecutive rows naming the same columns, so each run is one multi-row VALUES list. */
463
+ export function runsOfColumns(plans) {
464
+ const runs = [];
465
+ let shape;
466
+ for (const plan of plans) {
467
+ const next = JSON.stringify(Object.keys(plan.applied));
468
+ if (next === shape)
469
+ runs.at(-1).push(plan);
470
+ else
471
+ runs.push([plan]);
472
+ shape = next;
473
+ }
474
+ return runs;
475
+ }
476
+ /* Under SQLite's bound-parameter ceiling (32766 since 3.32) and PostgreSQL's (65535), with room to spare. */
477
+ const BATCH_PARAMETERS = 30_000;
478
+ /** Rows split so no statement binds more parameters than a database takes; most batches are one chunk. */
479
+ export function chunked(rows, weight) {
480
+ const chunks = [];
481
+ let size = 0;
482
+ for (const row of rows) {
483
+ const cost = weight(row);
484
+ if (!chunks.length || size + cost > BATCH_PARAMETERS) {
485
+ chunks.push([]);
486
+ size = 0;
487
+ }
488
+ chunks.at(-1).push(row);
489
+ size += cost;
490
+ }
491
+ return chunks;
492
+ }
493
+ /**
494
+ * RETURNING's rows put back in the order of the requests that wrote them. Neither SQLite nor PostgreSQL promises
495
+ * the order of a multi-row INSERT's RETURNING, though both answer in VALUES order: each request takes the row in
496
+ * its own place when that row holds its values, else the first unclaimed row that does. Two requests whose values
497
+ * agree wrote rows a caller cannot tell apart by what it asked, so either is a right answer.
498
+ */
499
+ export function batchedRows(applied, stored) {
500
+ if (stored.length !== applied.length)
501
+ throw new Error(`A batch of ${applied.length} rows returned ${stored.length}.`);
502
+ const same = (a, b) => a === null || b === null || a === undefined || b === undefined
503
+ ? (a ?? null) === (b ?? null)
504
+ : String(typeof a === 'boolean' ? Number(a) : a) === String(typeof b === 'boolean' ? Number(b) : b);
505
+ const holds = (values, row) => Object.keys(values).every((c) => same(values[c], row[c]));
506
+ const claimed = new Set();
507
+ return applied.map((values, index) => {
508
+ const at = holds(values, stored[index]) && !claimed.has(index) ? index : stored.findIndex((row, i) => !claimed.has(i) && holds(values, row));
509
+ const take = at >= 0 ? at : stored.findIndex((_, i) => !claimed.has(i));
510
+ claimed.add(take);
511
+ return stored[take];
512
+ });
513
+ }
514
+ /** A key that matched no row, or more than one: a guarded update's miss is a conflict, any other a refusal. */
515
+ export function refuseUpdateMatches(request, count) {
516
+ if (request.expected !== undefined && count === 0)
517
+ throw new WriteConflict();
518
+ throw new Refusal(`Refused: that key matches ${count} rows, not 1. An update is only allowed when it is certain which row it changes.`);
519
+ }
358
520
  /**
359
521
  * Drain accepted operations before commit/rollback, then refuse escaped handles.
360
522
  *
@@ -242,6 +242,8 @@ export declare class PostgresAdapter implements Adapter {
242
242
  * believed.
243
243
  */
244
244
  update(request: UpdateRequest): Promise<UpdateResult>;
245
+ /** What `update` refuses before it writes, and the values it writes, coerced to their columns. */
246
+ private updatePlan;
245
247
  private updateNow;
246
248
  /**
247
249
  * Add one row.
@@ -258,6 +260,12 @@ export declare class PostgresAdapter implements Adapter {
258
260
  * window for another write to land in between.
259
261
  */
260
262
  insert(request: InsertRequest): Promise<InsertResult>;
263
+ /** What `insert` refuses before it writes, and the values it writes, coerced to their columns. */
264
+ private insertPlan;
265
+ /** Several rows of one table added by one statement inside a transaction, each refused as `insert` refuses one (postgresBatchWrites). */
266
+ private insertManyNow;
267
+ /** Several rows of one table changed by one statement inside a transaction, each refused as `update` refuses one. */
268
+ private updateManyNow;
261
269
  private insertNow;
262
270
  /**
263
271
  * Remove one row, having proved it is one row.
@@ -11,7 +11,7 @@ import { isProxy } from 'node:util/types';
11
11
  import { inlineRows } from '../shared/anyRows.js';
12
12
  import { asksAboutRows } from '../shared/filter.js';
13
13
  import { qualifiedTable } from '../shared/sqlRelation.js';
14
- import { POSTGRES_STYLE, buildWhere, clampLimit, boundStatement, dedupe, looksWrappable, refuseStacked, trimStatement, clampOffset, Refusal, WriteConflict, TransactionOperations, queueRecordLock, recordLockFilter, TransactionOutcomeUnknown, refuseAnalyze, countStatement, countEachStatement, countEachRows, countsTogether, orderClause, lanesStatement, withoutLaneRow, } from './adapter.js';
14
+ import { POSTGRES_STYLE, buildWhere, clampLimit, boundStatement, dedupe, looksWrappable, refuseStacked, trimStatement, clampOffset, Refusal, WriteConflict, TransactionOperations, queueRecordLock, recordLockFilter, TransactionOutcomeUnknown, refuseAnalyze, countStatement, countEachStatement, countEachRows, countsTogether, orderClause, lanesStatement, withoutLaneRow, refuseUpdateMatches, } from './adapter.js';
15
15
  import { compileAggregate } from '../shared/aggregate.js';
16
16
  import { coerceForColumn } from '../shared/schema.js';
17
17
  import { buildUpdateGuard } from './scoped/updateGuard.js';
@@ -20,6 +20,7 @@ import { attestPostgresTriggers, effectCatalogFacts, hierarchyRecheck, joinedHie
20
20
  import { postgresTriggerAnalyzer, postgresTriggersByTable, postgresTriggerStatement, readPostgresTableCode, } from './scoped/postgresTriggers.js';
21
21
  import { captureScopeCatalog, mapScopeCatalog } from '../shared/scopeCatalog.js';
22
22
  import { createPinnedPostgresReadOwner } from './postgresReadCatalog.js';
23
+ import { batchesThrough, gatheredBatches, insertPlanned, updatePlanned } from './postgresBatchWrites.js';
23
24
  import { isRuntimeRelation, qualified, redact, valueSafe, withBytes, toJsonSafe } from './postgresValues.js';
24
25
  import { beginWriteCapture, capturesWrites, committedWriteCapture, finishWriteCapture } from './writeCapture.js';
25
26
  import { lendStoreHost, } from './storeHost.js';
@@ -895,9 +896,8 @@ export class PostgresAdapter {
895
896
  return this.transact(lane, (tx) => tx.update(request));
896
897
  return this.watched(this.writes.run(lane, () => this.connections.withWriteClient((write) => this.updateNow(request, write))));
897
898
  }
898
- async updateNow(request, write, read) {
899
- const transactional = read !== undefined;
900
- read ??= await this.conn();
899
+ /** What `update` refuses before it writes, and the values it writes, coerced to their columns. */
900
+ async updatePlan(request, read) {
901
901
  const found = await this.assertTable(request.table, read);
902
902
  const id = `${found.schema}.${found.name}`;
903
903
  /* Postgres updates through a simple view, and the update lands on the
@@ -937,6 +937,13 @@ export class PostgresAdapter {
937
937
  throw new Refusal(`"${column}" is NOT NULL and cannot be emptied.`);
938
938
  }
939
939
  }
940
+ return { found, meta, pk, applied };
941
+ }
942
+ async updateNow(request, write, read) {
943
+ const transactional = read !== undefined;
944
+ read ??= await this.conn();
945
+ const { found, meta, pk, applied } = await this.updatePlan(request, read);
946
+ const id = `${found.schema}.${found.name}`;
940
947
  const filter = {
941
948
  groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))],
942
949
  };
@@ -944,11 +951,7 @@ export class PostgresAdapter {
944
951
  one the UPDATE's own row count is the check: the key is the whole
945
952
  primary key, so it matches one row or none, and a refusal rolls the
946
953
  transaction back. */
947
- const refuseMatches = (matches) => {
948
- if (request.expected !== undefined && matches === 0)
949
- throw new WriteConflict();
950
- throw new Refusal(`Refused: that key matches ${matches} rows, not 1. An update is only allowed when it is certain which row it changes.`);
951
- };
954
+ const refuseMatches = (matches) => refuseUpdateMatches(request, matches);
952
955
  const matches = transactional ? 1 : await this.count(id, filter);
953
956
  if (matches !== 1)
954
957
  refuseMatches(matches);
@@ -992,16 +995,15 @@ export class PostgresAdapter {
992
995
  return this.transact([], (tx) => tx.insert(request));
993
996
  return this.watched(this.writes.run([], () => this.connections.withWriteClient((write) => this.insertNow(request, write))));
994
997
  }
995
- async insertNow(request, write, read, scoped = false) {
996
- read ??= await this.conn();
998
+ /** What `insert` refuses before it writes, and the values it writes, coerced to their columns. */
999
+ async insertPlan(request, read) {
997
1000
  const found = await this.assertTable(request.table, read);
998
1001
  const id = `${found.schema}.${found.name}`;
999
1002
  if (found.isView)
1000
1003
  throw new Refusal(`${id} is a view. Insert into the table underneath it.`);
1001
1004
  const meta = await this.columnsOf(found.schema, found.name, read);
1002
- const entries = Object.entries(request.values ?? {});
1003
1005
  const applied = {};
1004
- for (const [column, raw] of entries) {
1006
+ for (const [column, raw] of Object.entries(request.values ?? {})) {
1005
1007
  const declared = meta.find((c) => c.name === column);
1006
1008
  if (!declared)
1007
1009
  throw new Refusal(`${id} has no column called "${column}".`);
@@ -1010,6 +1012,25 @@ export class PostgresAdapter {
1010
1012
  throw new Refusal(`"${column}" is NOT NULL and cannot be null. Leave it out to use its default, if it has one.`);
1011
1013
  }
1012
1014
  }
1015
+ return { found, meta, applied };
1016
+ }
1017
+ /** Several rows of one table added by one statement inside a transaction, each refused as `insert` refuses one (postgresBatchWrites). */
1018
+ async insertManyNow(requests, write) {
1019
+ const plans = [];
1020
+ for (const request of requests)
1021
+ plans.push(await this.insertPlan(request, write));
1022
+ return insertPlanned(plans, write);
1023
+ }
1024
+ /** Several rows of one table changed by one statement inside a transaction, each refused as `update` refuses one. */
1025
+ async updateManyNow(requests, write) {
1026
+ const plans = [];
1027
+ for (const request of requests)
1028
+ plans.push({ request, ...(await this.updatePlan(request, write)) });
1029
+ return updatePlanned(plans, write);
1030
+ }
1031
+ async insertNow(request, write, read, scoped = false) {
1032
+ read ??= await this.conn();
1033
+ const { found, meta, applied } = await this.insertPlan(request, read);
1013
1034
  const columns = Object.keys(applied);
1014
1035
  const text = `INSERT INTO ${qualified(found)}` +
1015
1036
  (columns.length
@@ -1096,6 +1117,7 @@ export class PostgresAdapter {
1096
1117
  insert: (r) => history.insert(r, base.insert),
1097
1118
  update: (r) => history.update(r, base.update),
1098
1119
  remove: (r) => history.remove(r, base.remove),
1120
+ ...gatheredBatches(base, history),
1099
1121
  tell: (r) => history.tell(r),
1100
1122
  finish: () => finishWriteCapture(history),
1101
1123
  committed: () => committedWriteCapture(history),
@@ -1176,6 +1198,8 @@ export class PostgresAdapter {
1176
1198
  insert: (r) => this.insertNow(r, write, write),
1177
1199
  remove: (r) => this.removeNow(r, write, write),
1178
1200
  update: (r) => this.updateNow(r, write, write),
1201
+ insertMany: (rs) => this.insertManyNow(rs, write),
1202
+ updateMany: (rs) => this.updateManyNow(rs, write),
1179
1203
  }, reads);
1180
1204
  // The transaction's own work runs without the hint: a transaction it opens is not this one.
1181
1205
  const out = await withoutWriteAhead(() => withoutSnapshotRead(() => run({
@@ -1186,6 +1210,7 @@ export class PostgresAdapter {
1186
1210
  insert: (r) => operations.run(() => writes.insert(r)),
1187
1211
  remove: (r) => operations.run(() => writes.remove(r)),
1188
1212
  update: (r) => operations.run(() => writes.update(r)),
1213
+ ...batchesThrough(writes, (work) => operations.run(work)),
1189
1214
  ...(writes.tell ? { tell: (r) => operations.run(() => writes.tell(r)) } : {}),
1190
1215
  })));
1191
1216
  await operations.finish();
@@ -1337,6 +1362,8 @@ export class PostgresAdapter {
1337
1362
  insert: (r) => this.insertNow(r, write, write),
1338
1363
  remove: (r) => this.removeNow(r, write, write),
1339
1364
  update: (r) => this.updateNow(r, write, write),
1365
+ insertMany: (rs) => this.insertManyNow(rs, write),
1366
+ updateMany: (rs) => this.updateManyNow(rs, write),
1340
1367
  }, reads);
1341
1368
  const records = {
1342
1369
  lockRecord: (r) => queueRecordLock(operations, r, (request) => this.lockRecordNow(request, write)),
@@ -1346,6 +1373,7 @@ export class PostgresAdapter {
1346
1373
  insert: (r) => operations.run(() => writes.insert(r)),
1347
1374
  remove: (r) => operations.run(() => writes.remove(r)),
1348
1375
  update: (r) => operations.run(() => writes.update(r)),
1376
+ ...batchesThrough(writes, (work) => operations.run(work)),
1349
1377
  ...(writes.tell ? { tell: (r) => operations.run(() => writes.tell(r)) } : {}),
1350
1378
  };
1351
1379
  // The transaction's own work runs without the hint: a transaction it opens is not this one.
@@ -0,0 +1,39 @@
1
+ /** Several rows of one table written by one statement: the SQL behind the command `db`'s `insertMany` and `updateWhere`. */
2
+ import { type InsertRequest, type InsertResult, type UpdateRequest, type UpdateResult, type WriteTransaction } from './adapter.js';
3
+ import type { Located, PgColumnRow } from './postgresCatalog.js';
4
+ import type { PgQuery } from './postgresPool.js';
5
+ type Applied = Record<string, string | number | boolean | null>;
6
+ /** What the adapter's insert refuses before it writes, already passed: the table and the values coerced to their columns. */
7
+ export interface InsertPlan {
8
+ found: Located;
9
+ meta: PgColumnRow[];
10
+ applied: Applied;
11
+ }
12
+ /** An update's request beside what its refusals already passed. */
13
+ export interface UpdatePlan extends InsertPlan {
14
+ request: UpdateRequest;
15
+ pk: string[];
16
+ }
17
+ /**
18
+ * Rows added inside a transaction, each as the adapter's single insert adds one: one multi-row
19
+ * `INSERT … RETURNING *` for each run of rows naming the same columns, its rows matched back to the
20
+ * requests that wrote them (batchedRows).
21
+ */
22
+ export declare function insertPlanned(plans: readonly InsertPlan[], write: PgQuery): Promise<InsertResult[]>;
23
+ /**
24
+ * Rows changed inside a transaction, each as the adapter's single update changes one: each row's own values and
25
+ * `expected`, one row a key. A `CASE` a column picks each row's value, the WHERE matches each key with its own
26
+ * guard, and RETURNING says which requests matched, so a row whose key or guard missed refuses the batch as it
27
+ * would have refused alone.
28
+ */
29
+ export declare function updatePlanned(plans: readonly UpdatePlan[], write: PgQuery): Promise<UpdateResult[]>;
30
+ /** A transaction's batch writes, each run through `run` as its single writes are (a queue, a lock), when it has them. */
31
+ export declare function batchesThrough(writes: Pick<WriteTransaction, 'insertMany' | 'updateMany'>, run: <T>(work: () => Promise<T>) => Promise<T>): Pick<WriteTransaction, 'insertMany' | 'updateMany'>;
32
+ /** A transaction's batch writes with each row passed through `insert` or `update` as it is alone, around the one
33
+ * statement (gathered): a before image read under its lock still waits for that row's read, and an after image
34
+ * rides behind the batch's UPDATE as behind one row's. */
35
+ export declare function gatheredBatches(writes: Pick<WriteTransaction, 'insertMany' | 'updateMany'>, around: {
36
+ insert(request: InsertRequest, write: (request: InsertRequest) => Promise<InsertResult>): Promise<InsertResult>;
37
+ update(request: UpdateRequest, write: (request: UpdateRequest) => Promise<UpdateResult>): Promise<UpdateResult>;
38
+ }): Pick<WriteTransaction, 'insertMany' | 'updateMany'>;
39
+ export {};
@@ -0,0 +1,113 @@
1
+ /** Several rows of one table written by one statement: the SQL behind the command `db`'s `insertMany` and `updateWhere`. */
2
+ import { POSTGRES_STYLE, Refusal, batchedRows, buildWhere, chunked, gathered, refuseUpdateMatches, runsOfColumns, sameTable, } from './adapter.js';
3
+ import { qualified, toJsonSafe } from './postgresValues.js';
4
+ import { buildUpdateGuard } from './scoped/updateGuard.js';
5
+ /**
6
+ * Rows added inside a transaction, each as the adapter's single insert adds one: one multi-row
7
+ * `INSERT … RETURNING *` for each run of rows naming the same columns, its rows matched back to the
8
+ * requests that wrote them (batchedRows).
9
+ */
10
+ export async function insertPlanned(plans, write) {
11
+ sameTable(plans.map((plan) => `${plan.found.schema}.${plan.found.name}`));
12
+ const found = plans[0].found;
13
+ const pk = plans[0].meta.filter((c) => c.is_pk).map((c) => c.name);
14
+ const results = [];
15
+ for (const run of runsOfColumns(plans)) {
16
+ const columns = Object.keys(run[0].applied);
17
+ /* DEFAULT VALUES is one row; rows that name no column are added one statement each. */
18
+ for (const chunk of columns.length ? chunked(run, () => columns.length) : run.map((plan) => [plan])) {
19
+ const params = chunk.flatMap((plan) => Object.values(plan.applied));
20
+ const text = `INSERT INTO ${qualified(found)}` +
21
+ (columns.length
22
+ ? ` (${columns.map((c) => POSTGRES_STYLE.quote(c)).join(', ')}) VALUES ${chunk
23
+ .map((_, row) => `(${columns.map((_, i) => POSTGRES_STYLE.placeholder(row * columns.length + i + 1)).join(', ')})`)
24
+ .join(', ')}`
25
+ : ' DEFAULT VALUES') +
26
+ ' RETURNING *';
27
+ const result = await write.query(text, params);
28
+ batchedRows(chunk.map((plan) => plan.applied), result.rows).forEach((stored, index) => {
29
+ const row = toJsonSafe(stored);
30
+ const key = {};
31
+ for (const c of pk)
32
+ key[c] = row[c];
33
+ results.push({ key, row, applied: chunk[index].applied, sql: { text, params } });
34
+ });
35
+ }
36
+ }
37
+ return results;
38
+ }
39
+ /**
40
+ * Rows changed inside a transaction, each as the adapter's single update changes one: each row's own values and
41
+ * `expected`, one row a key. A `CASE` a column picks each row's value, the WHERE matches each key with its own
42
+ * guard, and RETURNING says which requests matched, so a row whose key or guard missed refuses the batch as it
43
+ * would have refused alone.
44
+ */
45
+ export async function updatePlanned(plans, write) {
46
+ sameTable(plans.map((plan) => `${plan.found.schema}.${plan.found.name}`));
47
+ const { found, pk } = plans[0];
48
+ const types = Object.fromEntries(plans[0].meta.map((column) => [column.name, column.type]));
49
+ const keys = new Set();
50
+ for (const { request } of plans) {
51
+ const key = JSON.stringify(pk.map((column) => String(request.key[column])));
52
+ if (keys.has(key))
53
+ throw new Refusal(`A batch changes each row of ${found.name} once; that key appears twice.`);
54
+ keys.add(key);
55
+ }
56
+ const results = [];
57
+ for (const chunk of chunked(plans, (plan) => pk.length * (Object.keys(plan.applied).length + 3) + 2 * Object.keys(plan.applied).length)) {
58
+ const params = [];
59
+ const match = (request) => {
60
+ const where = buildWhere({ groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))] }, POSTGRES_STYLE, params.length + 1);
61
+ params.push(...where.params);
62
+ return where.text.replace(/^ WHERE /, '');
63
+ };
64
+ const columns = [...new Set(chunk.flatMap((plan) => Object.keys(plan.applied)))];
65
+ const assignments = columns.map((column) => {
66
+ const cases = chunk
67
+ .filter((plan) => Object.hasOwn(plan.applied, column))
68
+ .map((plan) => {
69
+ const key = match(plan.request);
70
+ params.push(plan.applied[column]);
71
+ return `WHEN ${key} THEN ${POSTGRES_STYLE.placeholder(params.length)}`;
72
+ });
73
+ const quoted = POSTGRES_STYLE.quote(column);
74
+ return `${quoted} = CASE ${cases.join(' ')} ELSE ${quoted} END`;
75
+ });
76
+ const wheres = chunk.map((plan) => {
77
+ const key = match(plan.request);
78
+ const guard = buildUpdateGuard(plan.request, types, POSTGRES_STYLE, 'postgres', params.length + 1);
79
+ params.push(...guard.params);
80
+ return `(${key}${guard.text})`;
81
+ });
82
+ const which = chunk.map((plan, index) => `WHEN ${match(plan.request)} THEN ${index}`);
83
+ const text = `UPDATE ${qualified(found)} SET ${assignments.join(', ')} WHERE ${wheres.join(' OR ')}` +
84
+ ` RETURNING CASE ${which.join(' ')} END AS ${POSTGRES_STYLE.quote('mistri_batch_row')}`;
85
+ const result = await write.query(text, params);
86
+ const matched = new Set(result.rows.map((row) => Number(row.mistri_batch_row)));
87
+ chunk.forEach((plan, index) => {
88
+ if (!matched.has(index))
89
+ refuseUpdateMatches(plan.request, 0);
90
+ results.push({ affected: 1, applied: plan.applied, sql: { text, params } });
91
+ });
92
+ }
93
+ return results;
94
+ }
95
+ /** A transaction's batch writes, each run through `run` as its single writes are (a queue, a lock), when it has them. */
96
+ export function batchesThrough(writes, run) {
97
+ const { insertMany, updateMany } = writes;
98
+ if (!insertMany || !updateMany)
99
+ return {};
100
+ return { insertMany: (rs) => run(() => insertMany(rs)), updateMany: (rs) => run(() => updateMany(rs)) };
101
+ }
102
+ /** A transaction's batch writes with each row passed through `insert` or `update` as it is alone, around the one
103
+ * statement (gathered): a before image read under its lock still waits for that row's read, and an after image
104
+ * rides behind the batch's UPDATE as behind one row's. */
105
+ export function gatheredBatches(writes, around) {
106
+ const { insertMany, updateMany } = writes;
107
+ if (!insertMany || !updateMany)
108
+ return {};
109
+ return {
110
+ insertMany: (rs) => gathered(rs, (r, write) => around.insert(r, write), insertMany),
111
+ updateMany: (rs) => gathered(rs, (r, write) => around.update(r, write), updateMany),
112
+ };
113
+ }
@@ -1,5 +1,8 @@
1
1
  /** Adapter-owned command queue capture and failure accounting within a scoped transaction. */
2
2
  import { type TransactionOperations } from '../adapter.js';
3
3
  /** Shared adapter queue boundary: capture before waiting; caught malformed or
4
- * failed operations still poison the transaction. No writer escapes here. */
4
+ * failed operations still poison the transaction. No writer escapes here.
5
+ * `verify` runs around each operation: the adapter's step check, which verifies
6
+ * whole only when the schema moved (sqlite.ts verifiedStep), never its full
7
+ * opening or pre-COMMIT verification. */
5
8
  export declare function scopedCommandInvoker(operations: TransactionOperations, scoped: boolean, command: boolean, runtime: (table: string) => boolean, verify?: () => void): <A, R>(input: A, work: (input: A) => Promise<R>, read?: boolean) => Promise<R>;
@@ -2,7 +2,10 @@
2
2
  import { Refusal } from '../adapter.js';
3
3
  import { snapshotScopedData } from './scopedReads.js';
4
4
  /** Shared adapter queue boundary: capture before waiting; caught malformed or
5
- * failed operations still poison the transaction. No writer escapes here. */
5
+ * failed operations still poison the transaction. No writer escapes here.
6
+ * `verify` runs around each operation: the adapter's step check, which verifies
7
+ * whole only when the schema moved (sqlite.ts verifiedStep), never its full
8
+ * opening or pre-COMMIT verification. */
6
9
  export function scopedCommandInvoker(operations, scoped, command, runtime, verify = () => { }) {
7
10
  let failed = false;
8
11
  /* `read`: the work only reads, so on a transaction that sends together it may start beside reads in flight