@proteinjs/db 1.47.3 → 1.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.47.3",
+  "version": "1.48.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "08154afae17a9a19c9e48520a3dd67ead7b997c6"
+  "gitHead": "ec3fd54430dde18afd406ec70eccd857492272a0"
 }

package/src/Db.ts

@@ -95,6 +95,15 @@ export interface DbDriver {
   ): Promise<SerializedRecord[]>;
   runDml(generateStatement: (config: DbDriverDmlStatementConfig) => Statement, transaction?: any): Promise<number>;
   runTransaction<T>(fn: (transaction: any) => Promise<T>): Promise<T>;
+  /**
+   * The driver's per-operation deadline, in milliseconds: the longest one statement it runs may
+   * take before the driver fails it — the bound the driver enforces, as configured. Not a whole
+   * transaction's budget (a transaction the database aborts and the driver re-runs may take
+   * longer in all). Code that waits on another request's write — a row it depends on whose insert
+   * may still be in flight — sizes its wait by this, so the wait follows what the deployment
+   * configured its database to tolerate rather than a number of its own.
+   */
+  getOperationDeadlineMs(): number;
 }
 
 export class Db<R extends Record = Record> implements DbService<R> {

package/src/services/TransactionRunnerService.ts

@@ -5,6 +5,26 @@ export const getTransactionRunnerService = serviceFactory<TransactionRunnerServi
   '@proteinjs/db/TransactionRunnerService'
 );
 
+/**
+ * What a write declares about the rows it depends on.
+ *
+ * A client that releases a queued write because its page is going away cannot order that write
+ * behind the writes it depends on — the page is gone before their answers arrive. The server
+ * outlives the page, so the write DECLARES its dependencies and the server honours them.
+ */
+export type TransactionRunOptions = {
+  /**
+   * Ids of rows the operations depend on that may not exist yet: the row an update or a
+   * membership update targets while its insert is still in flight, the permission source a
+   * child row attaches to while the root's own insert (and the owner grant that commits with
+   * it) is still landing. Every id must be a row the operations themselves reference. The
+   * runner waits, bounded, for each to exist AND be visible to the caller before running the
+   * operations; a row that never appears fails the request with a plain clause — never a
+   * silent zero-row write, never a hang.
+   */
+  afterRows?: string[];
+};
+
 export interface TransactionRunnerService extends Service {
-  run(ops: Operation<any>[]): Promise<void>;
+  run(ops: Operation<any>[], options?: TransactionRunOptions): Promise<void>;
 }

package/src/transaction/Transaction.ts

@@ -1,6 +1,7 @@
 import { Record } from '../Record';
 import { DbService, ObjectQuery } from '../services/DbService';
 import { getTransactionRunner } from './TransactionRunner';
+import { TransactionRunOptions } from '../services/TransactionRunnerService';
 import { addDefaultFieldValues, Table } from '../Table';
 import { isInstanceOf } from '@proteinjs/util';
 import { Condition, QueryBuilder } from '@proteinjs/db-query';
@@ -269,14 +270,22 @@ export class Transaction implements OperationQueue {
 
   /**
    * Run the operations in order (not a batch), as a single transaction.
+   *
+   * `options.afterRows` declares rows the operations depend on that may not exist yet (see
+   * {@link TransactionRunOptions}); the server waits for them before running. A run with nothing
+   * to declare hands the runner the operations alone — the request is the one it always was.
    */
-  async run(): Promise<void> {
+  async run(options?: TransactionRunOptions): Promise<void> {
     if (this.ops.length === 0) {
       return;
     }
 
     const runner = getTransactionRunner();
-    await runner.run(this.ops);
+    if (options?.afterRows && options.afterRows.length > 0) {
+      await runner.run(this.ops, { afterRows: options.afterRows });
+    } else {
+      await runner.run(this.ops);
+    }
     this.ops = [];
   }
 }

package/src/transaction/TransactionRunner.ts

@@ -1,10 +1,32 @@
-import { getDb } from '../Db';
-import { TransactionRunnerService, getTransactionRunnerService } from '../services/TransactionRunnerService';
+import { Logger } from '@proteinjs/logger';
+import { Db, getDb } from '../Db';
+import { Table, tableByName } from '../Table';
+import { getDefaultTransactionContextFactory } from './TransactionContextFactory';
+import {
+  TransactionRunnerService,
+  TransactionRunOptions,
+  getTransactionRunnerService,
+} from '../services/TransactionRunnerService';
 import { Operation } from './Transaction';
 
 export const getTransactionRunner = () =>
   typeof self === 'undefined' ? new TransactionRunner() : (getTransactionRunnerService() as TransactionRunner);
 
+/**
+ * Runs a client `Transaction`'s operations as one server-side transaction.
+ *
+ * A write may DECLARE the rows it depends on (`options.afterRows`): rows its operations
+ * reference whose own insert may still be in flight when this request arrives — a text update
+ * released by a page that was going away while its row's insert was still being served, a child
+ * row's insert whose root (its permission source, and the owner grant that commits with the
+ * root) is still landing. Without the declaration such a write ran to completion inside the
+ * insert's window and matched nothing, silently, or was refused at the door for a grant that was
+ * a moment from existing — and the page that could have retried was gone. The server outlives
+ * the page: it waits, bounded by the db driver's per-operation deadline, for every declared row to
+ * exist AND be visible to the caller (a read as the caller sees a row exactly when the caller's
+ * grant on its scope has committed), then runs the operations. A row that never appears fails the
+ * request with a plain clause.
+ */
 export class TransactionRunner implements TransactionRunnerService {
   public serviceMetadata = {
     auth: {
@@ -12,8 +34,17 @@ export class TransactionRunner implements TransactionRunnerService {
     },
   };
 
-  async run(ops: Operation<any>[]): Promise<void> {
+  private static readonly FIRST_POLL_INTERVAL_MS = 25;
+  private static readonly MAX_POLL_INTERVAL_MS = 250;
+
+  private logger = new Logger({ name: this.constructor.name });
+
+  async run(ops: Operation<any>[], options?: TransactionRunOptions): Promise<void> {
     const db = getDb();
+    const afterRows = options?.afterRows ?? [];
+    if (afterRows.length > 0) {
+      await this.awaitRows(ops, afterRows);
+    }
 
     await db.runTransaction(async () => {
       for (const op of ops) {
@@ -21,4 +52,144 @@ export class TransactionRunner implements TransactionRunnerService {
       }
     });
   }
+
+  /**
+   * Wait until every declared row exists and is visible to the caller, bounded by the db driver's
+   * per-operation deadline (`DbDriver.getOperationDeadlineMs`), read when the write waits. The
+   * bound is the ceiling for a row that NEVER comes — the named failure, never a hang. A
+   * dependency's insert lands in hundreds of milliseconds on a healthy link and in seconds on a
+   * degraded one (a root's birth of a few dozen sequential statements has taken 13 s), and the
+   * writes released behind it by a page that is gone have no second chance. The driver's deadline
+   * is how long the deployment lets one statement of that insert run before failing it: the wait
+   * takes its measure from there — one owner for the number, configured with the database — not
+   * from a number of its own. A write that waits here holds one request and a poll, nothing else.
+   *
+   * Each poll is a single-use strong read outside any transaction, so a commit is seen the moment
+   * it lands; the interval starts short and backs off so a dependency landing in hundreds of
+   * milliseconds is caught within tens.
+   */
+  private async awaitRows(ops: Operation<any>[], afterRows: string[]): Promise<void> {
+    if (getDefaultTransactionContextFactory()?.getTransactionContext().currentTransaction) {
+      throw new Error(
+        `TransactionRunner: afterRows cannot be honoured inside an ambient transaction — its reads would see the transaction's own snapshot, never a row committed after it began`
+      );
+    }
+
+    const tablesById = TransactionRunner.rowsTheOperationsReference(ops);
+    const unknown = afterRows.filter((id) => !tablesById.has(id));
+    if (unknown.length > 0) {
+      throw new Error(
+        `TransactionRunner: afterRows names rows none of the operations reference (${unknown.join(', ')}) — the write was not run`
+      );
+    }
+
+    const db = getDb();
+    const boundMs = Db.getDefaultDbDriver().getOperationDeadlineMs();
+    const started = Date.now();
+    const deadline = started + boundMs;
+    /** Per declared id, the (table, id) rows still absent. */
+    let waiting: { id: string; tables: Table<any>[] }[] = afterRows
+      .filter((id, index) => afterRows.indexOf(id) === index)
+      .map((id) => ({ id, tables: tablesById.get(id)!.slice() }));
+    let interval = TransactionRunner.FIRST_POLL_INTERVAL_MS;
+    let polls = 0;
+    for (;;) {
+      polls += 1;
+      for (const row of waiting) {
+        const stillAbsent: Table<any>[] = [];
+        for (const table of row.tables) {
+          if (!(await db.get(table, { id: row.id } as any))) {
+            stillAbsent.push(table);
+          }
+        }
+        row.tables = stillAbsent;
+      }
+      waiting = waiting.filter((row) => row.tables.length > 0);
+      if (waiting.length === 0) {
+        const waitedMs = Date.now() - started;
+        // One line when the seam did work (the row landed while this write waited); a row that
+        // was already there is the common case and stays quiet.
+        const line = { message: `Declared rows present`, obj: { afterRows, waitedMs, polls } };
+        if (polls > 1) {
+          this.logger.info(line);
+        } else {
+          this.logger.debug(line);
+        }
+        return;
+      }
+
+      const now = Date.now();
+      if (now >= deadline) {
+        const absent = waiting.map((row) => row.tables.map((table) => `${table.name}:${row.id}`).join(', ')).join(', ');
+        this.logger.warn({
+          message: `Declared rows absent at the bound — the write was not run`,
+          obj: { absent, boundMs, waitedMs: now - started, polls },
+        });
+        throw new Error(
+          `TransactionRunner: waited ${boundMs} ms for rows this write depends on to exist and be visible to the caller; still absent: ${absent} — the write was not run (the bound is the db driver's per-operation deadline)`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, Math.min(interval, deadline - now)));
+      interval = Math.min(interval * 2, TransactionRunner.MAX_POLL_INTERVAL_MS);
+    }
+  }
+
+  /**
+   * The rows the operations reference, by id → the table(s) they are read from: the permission
+   * source a row attaches to (an insert whose `permissionSource` is another row), the row an
+   * update / preserving update / membership update / delete targets. The rows the operations
+   * insert themselves are not dependencies.
+   */
+  private static rowsTheOperationsReference(ops: Operation<any>[]): Map<string, Table<any>[]> {
+    const inserted: string[] = [];
+    const referenced = new Map<string, Table<any>[]>();
+    const reference = (table: Table<any> | undefined, id: unknown) => {
+      if (!table || typeof id !== 'string') {
+        return;
+      }
+      let tables = referenced.get(id);
+      if (!tables) {
+        tables = [];
+        referenced.set(id, tables);
+      }
+      if (tables.indexOf(table) === -1) {
+        tables.push(table);
+      }
+    };
+
+    for (const op of ops) {
+      const args = op.args as unknown[];
+      const table = args[0] as Table<any> | undefined;
+      if (op.name === 'insert') {
+        const record = args[1] as
+          | { id?: string; permissionSource?: { _table?: string; _id?: string }; permissionSourceTable?: string }
+          | undefined;
+        if (record?.id) {
+          inserted.push(record.id);
+        }
+        const source = record?.permissionSource;
+        if (source?._id && source._id !== record?.id) {
+          const sourceTableName = record?.permissionSourceTable ?? source._table;
+          reference(sourceTableName ? TransactionRunner.tableNamed(sourceTableName, table) : table, source._id);
+        }
+      } else if (op.name === 'update' || op.name === 'updatePreserving') {
+        const record = args[1] as { id?: string } | undefined;
+        const query = args[2] as { id?: unknown } | undefined;
+        reference(table, record?.id ?? (query && typeof query === 'object' && 'id' in query ? query.id : undefined));
+      } else if (op.name === 'updateArrayMembership') {
+        reference(table, (args[1] as { recordId?: string } | undefined)?.recordId);
+      } else if (op.name === 'delete') {
+        const query = args[1] as { id?: unknown } | undefined;
+        reference(table, query && typeof query === 'object' ? query.id : undefined);
+      }
+    }
+
+    inserted.forEach((id) => referenced.delete(id));
+    return referenced;
+  }
+
+  /** The table a permission source lives in: the insert's own table when it names the same one. */
+  private static tableNamed(tableName: string, inserting: Table<any> | undefined): Table<any> {
+    return inserting && inserting.name === tableName ? inserting : tableByName(tableName);
+  }
 }