@ultimat3/entity 29.3.2 → 30.0.0

package/src/memory-lock.ts

@@ -0,0 +1,144 @@
+// Single responsibility: the memory driver's lock. A promise queue per key, reentrant within one
+// async chain, and bounded: Postgres has `statement_timeout` for a stuck waiter and deadlock
+// detection for a cycle, and this driver has neither, so a wait that lasts is the refusal instead.
+
+import { asyncContext } from '@ultimat3/core';
+import { driverError } from '@ultimat3/db';
+import { undoingBatch } from './memory-batch';
+import { memoryJournal, memoryRoot, refuseIfMemoryTxClosed } from './memory-journal';
+import { memoryTransactor } from './memory-transactor';
+import type { Tx } from './repo';
+
+/** Past this a waiter gives up. Generous for a test, and a cycle reaches it every time. */
+export const MEMORY_LOCK_WAIT_MS = 5_000;
+
+export interface MemoryLocks {
+  /**
+   * `work` under `key`, in a transaction: its own, or joined as a savepoint to `outer`, or to the
+   * one this async chain's lock already opened. Joined, the key is held to that transaction's end,
+   * because a Postgres lock taken in a savepoint lives to the root.
+   */
+  run<R>(key: string, outer: Tx | undefined, work: (tx: Tx) => Promise<R> | R): Promise<R>;
+  /**
+   * A plain write's turn at `key`, the wait an `update` does for a row lock on Postgres: waits for a
+   * holder, runs `work`, holds nothing after it. No wait when this chain or `outer` holds the key.
+   */
+  turn<R>(key: string, outer: Tx | undefined, work: () => R): Promise<R>;
+}
+
+/** What this async chain holds, and the transaction its innermost lock runs in. */
+interface Chain {
+  readonly names: ReadonlySet<string>;
+  readonly tx: Tx;
+}
+
+const heldByChain = asyncContext<Chain>('the memory locks this chain holds');
+
+let instances = 0;
+
+/** `57014`, what a Postgres waiter past its `statement_timeout` is: one code for one mistake. */
+const timedOut = (key: string, waitMs: number): Error =>
+  driverError(`memory lock "${key}"`, {
+    code: '57014',
+    message: `canceling statement: waited ${waitMs} ms for a lock another caller still holds, usually two locks taken in opposite order`,
+  });
+
+export const memoryLocks = (waitMs: number = MEMORY_LOCK_WAIT_MS): MemoryLocks => {
+  instances += 1;
+  const instance = instances;
+  /** The last holder's end, per key: a newcomer waits on it and becomes the new end. */
+  const tails = new Map<string, Promise<void>>();
+  /** What a joined scope still holds once it returned, per ROOT: same root, same key, no wait. */
+  const heldByTx = new WeakMap<Tx, Set<string>>();
+
+  const inTx = <R>(outer: Tx | undefined, work: (tx: Tx) => Promise<R> | R): Promise<R> =>
+    outer === undefined
+      ? memoryTransactor().run(async (tx) => work(tx))
+      : Promise.resolve(undoingBatch(outer, work));
+
+  const acquire = async (name: string): Promise<() => void> => {
+    const previous = tails.get(name);
+    const mine = Promise.withResolvers<void>();
+    const tail = (previous ?? Promise.resolve()).then(() => mine.promise);
+    tails.set(name, tail);
+    // Off the tail, never off `release`: a waiter giving up has released, while the tail it joined
+    // still ends with the live holder, and a newcomer has to queue behind that holder.
+    void tail.then(() => {
+      if (tails.get(name) === tail) tails.delete(name);
+    });
+    const release = (): void => mine.resolve();
+    if (previous === undefined) return release;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const bound = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(timedOut(name, waitMs)), waitMs);
+    });
+    try {
+      await Promise.race([previous, bound]);
+      return release;
+    } catch (error) {
+      // Its place in the queue is given up, so the waiter behind it is not held by a ghost.
+      release();
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
+  const holds = (name: string, chain: Chain | undefined, outer: Tx | undefined): boolean =>
+    chain?.names.has(name) === true ||
+    (outer !== undefined && heldByTx.get(memoryRoot(outer))?.has(name)) === true;
+
+  return {
+    async run(key, given, work) {
+      const name = `${instance}:${key}`;
+      const chain = heldByChain.get();
+      // The ambient memory transaction last: a lock taken in one is a savepoint of it, held to its
+      // root's end. Its own transaction instead released at that one's commit, and the root's
+      // rollback then overwrote what the next holder had committed.
+      const outer = given ?? chain?.tx ?? memoryJournal();
+      // Before the wait, as a statement on a finished transaction is refused before it is sent.
+      refuseIfMemoryTxClosed(outer);
+      // `work` runs knowing its own tx, so a lock nested in it with no options joins this one.
+      const body =
+        <R>(step: (tx: Tx) => Promise<R> | R) =>
+        (tx: Tx) =>
+          heldByChain.run({ names: new Set([...(chain?.names ?? []), name]), tx }, () => step(tx));
+      if (holds(name, chain, outer)) return inTx(outer, body(work));
+      const release = await acquire(name);
+      // Held to the root's end when there is one that can say so. A hand-written `Tx` with no
+      // `onCommit` cannot, and the scope's own end is the only moment left.
+      if (outer?.onCommit !== undefined) {
+        // Filed under the root, so any scope of it finds the key; released by `outer`'s end, which
+        // for a savepoint that commits is the root's, and for one that rolls back is its own.
+        const root = memoryRoot(outer);
+        const held = heldByTx.get(root) ?? new Set<string>();
+        held.add(name);
+        heldByTx.set(root, held);
+        const once = (): void => {
+          held.delete(name);
+          release();
+        };
+        outer.onCommit(once);
+        outer.onRollback(once);
+        return inTx(outer, body(work));
+      }
+      try {
+        return await inTx(outer, body(work));
+      } finally {
+        release();
+      }
+    },
+
+    async turn(key, outer, work) {
+      const name = `${instance}:${key}`;
+      const chain = heldByChain.get();
+      if (holds(name, chain, outer ?? chain?.tx ?? memoryJournal())) return work();
+      const release = await acquire(name);
+      try {
+        return work();
+      } finally {
+        release();
+      }
+    },
+  };
+};

package/src/memory-observed.ts

@@ -0,0 +1,121 @@
+// Single responsibility: the memory driver's half of `@ultimat3/db`'s statement seam. Generated
+// tests run on this driver, so a loop it never reported was a `statements` assertion that could not
+// fail. One event per repository operation, attributed exactly as `postgresRepo` attributes its
+// statement; nothing is sent, so `text` names the operation and holds no SQL.
+
+import { tryUseContext } from '@ultimat3/core';
+import { expectedQueryLoopReason, statementObserver } from '@ultimat3/db';
+import type { MemoryRepo } from './repo';
+
+/** What one operation reports: the verb `statementKind` reads, and its row count. */
+interface Reported {
+  readonly verb: 'select' | 'insert' | 'update' | 'delete';
+  readonly rows: (answer: unknown) => number;
+}
+
+const none = (): number => 0;
+const one = (answer: unknown): number => (answer === null || answer === undefined ? 0 : 1);
+const counted = (answer: unknown): number => (typeof answer === 'number' ? answer : 0);
+const listed = (answer: unknown): number => (Array.isArray(answer) ? answer.length : 0);
+const paged = (answer: unknown): number =>
+  typeof answer === 'object' && answer !== null && 'rows' in answer ? listed(answer.rows) : 0;
+
+/** Every operation that would be a statement. `reset` is a test seam and reaches no database. */
+const OPERATIONS = {
+  findById: { verb: 'select', rows: one },
+  findMany: { verb: 'select', rows: paged },
+  count: { verb: 'select', rows: one },
+  countBy: { verb: 'select', rows: none },
+  aggregate: { verb: 'select', rows: one },
+  series: { verb: 'select', rows: listed },
+  approximateCount: { verb: 'select', rows: one },
+  insert: { verb: 'insert', rows: one },
+  insertAll: { verb: 'insert', rows: listed },
+  upsertAll: { verb: 'insert', rows: listed },
+  update: { verb: 'update', rows: one },
+  updateWhere: { verb: 'update', rows: counted },
+  delete: { verb: 'delete', rows: () => 1 },
+  deleteWhere: { verb: 'delete', rows: counted },
+} as const satisfies Record<string, Reported>;
+
+type Operation = keyof typeof OPERATIONS;
+
+/** Taken before the body runs, as Postgres answers the lock before the body it guards. */
+const LOCKS = ['lock', 'lockKey'] as const;
+
+const report = (
+  entity: string,
+  op: string,
+  verb: Reported['verb'],
+  rows: number,
+  error?: unknown,
+): void => {
+  const observer = statementObserver();
+  if (observer === undefined) return;
+  observer.onStatement({
+    text: `${verb} ${entity}.${op} (memory driver, no SQL sent)`,
+    values: [],
+    // Nothing crossed a wire, and a duration made up of `Map` reads would only rank as noise.
+    durationMs: 0,
+    rows,
+    ...(error === undefined ? {} : { error }),
+    attribution: { entity, op },
+    expected: expectedQueryLoopReason(),
+  });
+};
+
+/**
+ * `postgresRepo`'s `findById` joins every lookup of one request's microtask into one `in` statement
+ * (`coalesce.ts`) and declines with no request in scope. Mirrored, or `Promise.all(ids.map(byId))`
+ * fails a test here that Postgres passes with one statement. The rows are still read one by one:
+ * this decides only what the seam is told.
+ */
+const pointLookups = (): (() => boolean) => {
+  let open: object | undefined;
+  return () => {
+    const ctx: object | undefined = tryUseContext();
+    if (ctx === undefined) return true;
+    if (open === ctx) return false;
+    open = ctx;
+    queueMicrotask(() => {
+      if (open === ctx) open = undefined;
+    });
+    return true;
+  };
+};
+
+type AnyMethod = (...args: readonly unknown[]) => Promise<unknown>;
+
+/** `repo`, each statement-shaped method reporting once it settles, as the funnels report. */
+export function observedMemoryRepo<Row>(entity: string, repo: MemoryRepo<Row>): MemoryRepo<Row> {
+  const wrapped: Record<string, AnyMethod> = {};
+  const firstInMicrotask = pointLookups();
+  for (const op of Object.keys(OPERATIONS) as Operation[]) {
+    const method = repo[op] as AnyMethod;
+    const { verb, rows } = OPERATIONS[op];
+    wrapped[op] = async (...args) => {
+      if (statementObserver() === undefined) return method(...args);
+      // Decided as the call is made: by the time the row is back the microtask has moved on.
+      const reports = op !== 'findById' || firstInMicrotask();
+      // `postgresRepo` attributes an aggregate to its function, never to `aggregate`.
+      const name = op === 'aggregate' ? String(args[0]) : op;
+      let answer: unknown;
+      try {
+        answer = await method(...args);
+      } catch (error) {
+        if (reports) report(entity, name, verb, 0, error);
+        throw error;
+      }
+      if (reports) report(entity, name, verb, rows(answer));
+      return answer;
+    };
+  }
+  for (const op of LOCKS) {
+    const method = repo[op] as AnyMethod;
+    wrapped[op] = async (...args) => {
+      report(entity, op, 'select', 1);
+      return method(...args);
+    };
+  }
+  return Object.assign({}, repo, wrapped);
+}