@shirudo/ddd-kit 3.0.0-rc.7 → 3.0.0-rc.9

package/dist/testing.d.ts

@@ -147,6 +147,14 @@ interface EsRepositoryContractHarness<TAggregate extends Aggregate<Id<string>, T
    * Enables the snapshot catch-up proof.
    */
   captureSnapshot?(aggregate: TAggregate, environment: EsRepositoryContractEnvironment<TAggregate, TEvent>): Promise<void>;
+  /**
+   * Bound for the overlapping `run` calls, in milliseconds: the second call
+   * of the environment preflight, and the committing call of each
+   * stale-writer proof. Raise it only for a second connection that needs
+   * more time to open, or for a slow commit. Keep twice the bound, plus
+   * environment creation and teardown, below the test timeout of the runner.
+   */
+  overlappingCallsBoundMs?: number;
 }
 type EsRepositoryContractTest = ContractTest;
 /**
@@ -494,7 +502,8 @@ declare function createProjectionCheckpointStoreContractTests<TCtx>(harness: Pro
 interface ContractRepository<TAggregate extends Aggregate<Id<string>, AnyDomainEvent>> {
   findById(id: TAggregate["id"]): Promise<TAggregate | undefined>;
   add(aggregate: TAggregate): void;
-  update(aggregate: TAggregate): void;
+  /** An append-only port declares no update. */
+  update?(aggregate: TAggregate): void;
   /** Physical removal is an optional persistence capability. */
   remove?(aggregate: TAggregate): void;
 }
@@ -533,10 +542,26 @@ interface RepositoryContractHarness<TAggregate extends Aggregate<Id<string>, TEv
   snapshotState?(aggregate: TAggregate): unknown;
   /** Opt out only for an intentionally upserting add implementation. */
   insertsAreDuplicateChecked?: boolean;
+  /**
+   * Opt out only for an append-only port, one that the definition marks
+   * with `appendOnly: true`. The suite then skips every update proof. The
+   * duplicate-add proof is the concurrency proof that remains, so it is
+   * mandatory. Provide `createAggregateWithId` and keep
+   * `insertsAreDuplicateChecked`, or the proof fails instead of skipping.
+   */
+  updatesAreSupported?: boolean;
   /** Enables physical-remove behavior and stale-remove OCC tests. */
   removesAreSupported?: boolean;
   /** The remove flush predicates on the version captured at load. */
   removesAreVersionChecked?: boolean;
+  /**
+   * Bound for the overlapping `run` calls, in milliseconds: the second call
+   * of the environment preflight, and the committing call of each
+   * stale-writer proof. Raise it only for a second connection that needs
+   * more time to open, or for a slow commit. Keep twice the bound, plus
+   * environment creation and teardown, below the test timeout of the runner.
+   */
+  overlappingCallsBoundMs?: number;
 }
 type RepositoryContractTest = ContractTest;
 /**

package/dist/testing.js

@@ -1,4 +1,4 @@
-import { E as deepEqual, t as isDispatchTrackingOutbox, u as isRecordedDomainEvent } from "./chunks/ports.js";
+import { N as deepEqual, _ as isRecordedDomainEvent, i as runBoundedExecution, t as isDispatchTrackingOutbox } from "./chunks/ports.js";
 
 //#region src/testing/contract-assertions.ts
 /**
@@ -44,6 +44,123 @@ function captureRejection(promise) {
 	return promise.then(() => void 0, (error) => error);
 }
 /**
+* Default bound for the overlapping `run` calls of the contract suites, in
+* milliseconds. On an environment that gives each `run` call its own
+* connection, the second call completes in milliseconds. The failure path
+* takes up to twice the bound: the bound itself, then the wait for the
+* released calls to settle. Twice the bound plus environment creation and
+* teardown stays below the default test timeout of common runners
+* (5000 ms). So the named failure reaches the report before the runner's
+* own timeout replaces it.
+*/
+const OVERLAPPING_CALLS_BOUND_MS = 1e3;
+const overlappingCallsViolation = (boundMs) => `run must permit overlapping calls: a second run call did not complete within ${boundMs} ms while the first call stayed open. Either run serializes its calls, the first call holds a lock that blocks the second one, or the second call needs more time than the bound. Give each call its own transaction and connection, load without row locks, or raise overlappingCallsBoundMs on the harness`;
+function settle(promise) {
+	return promise.then((value) => ({
+		status: "fulfilled",
+		value
+	}), (reason) => ({
+		status: "rejected",
+		reason
+	}));
+}
+/** Outcomes of every promise, or `undefined` when one is still open after `boundMs`. */
+function settledWithin(promises, boundMs) {
+	return runBoundedExecution("release of the overlapping calls", { timeoutMs: boundMs }, () => Promise.allSettled(promises)).catch(() => void 0);
+}
+/**
+* Starts a `run` call and holds it open. `start` receives `hold`. The work
+* of the call awaits `hold()` at the point where it must stay open, for
+* example after its load. The result resolves once the work holds and the
+* call is still open. A call that rejects before that propagates its
+* rejection. A call that resolves while its work holds fails: `run` did not
+* await its work.
+*/
+async function parkRunCall(start) {
+	let release;
+	const mayContinue = new Promise((resolve) => {
+		release = resolve;
+	});
+	let markHolding;
+	const holding = new Promise((resolve) => {
+		markHolding = () => resolve("holding");
+	});
+	const call = start(() => {
+		markHolding();
+		return mayContinue;
+	});
+	const settled = settle(call).then((outcome) => outcome.status);
+	let state = await Promise.race([holding, settled]);
+	if (state === "holding") state = await Promise.race([settled, Promise.resolve("holding")]);
+	if (state === "rejected") await call;
+	assert(state === "holding", "run must await its work: the call resolved while its work still holds");
+	return {
+		call,
+		release
+	};
+}
+/**
+* Starts a `run` call through `startCall` and awaits it. The call must
+* complete while `parked` stays open. On an environment that serializes
+* `run`, it never completes. So this bounds the wait. After `boundMs` it
+* releases the parked call and waits up to `boundMs` for both calls to
+* settle. Then it fails with the requirement. A rejection of the call, or a
+* synchronous throw of `startCall`, releases the parked call the same way
+* and then propagates. On success the parked call stays parked; the proof
+* releases it when it is ready.
+*/
+async function awaitOverlappingCall(startCall, parked, boundMs) {
+	let call;
+	try {
+		call = startCall();
+	} catch (error) {
+		parked.release();
+		await settledWithin([parked.call], boundMs);
+		throw error;
+	}
+	const outcome = await runBoundedExecution("overlapping run call", { timeoutMs: boundMs }, () => settle(call)).catch(() => void 0);
+	if (outcome?.status === "fulfilled") return outcome.value;
+	parked.release();
+	await settledWithin([parked.call, call], boundMs);
+	assert(outcome !== void 0, overlappingCallsViolation(boundMs));
+	throw outcome.reason;
+}
+/**
+* Proves that the environment lets two `run` calls stay open at once.
+*
+* The stale-writer proofs hold one transaction open while a second one
+* commits. An environment that serializes `run` (one connection, a mutex)
+* blocks the second call behind the first. The suite then hangs at the test
+* timeout with no cause. This proof turns that hang into a named failure
+* within `boundMs`. It releases the first call before it returns and waits
+* up to `boundMs` for both calls to complete. A second call that is still
+* blocked after that stays in flight, observed, while the failure reports.
+*/
+async function assertRunPermitsOverlappingCalls(run, boundMs) {
+	const first = await parkRunCall((hold) => run(hold));
+	await awaitOverlappingCall(() => run(async () => {}), first, boundMs);
+	first.release();
+	const firstOutcome = (await settledWithin([first.call], boundMs))?.[0];
+	assert(firstOutcome !== void 0, `the first run call did not complete within ${boundMs} ms after the proof released it`);
+	if (firstOutcome.status === "rejected") throw firstOutcome.reason;
+}
+/**
+* The preflight entry both repository suites put first: it names a
+* serializing environment before the stale-writer proofs can hang on it.
+* Each `run` call of the proof reads `freshId()` before it holds. So an
+* adapter that reserves its connection on the first statement holds the
+* connection while the call stays open.
+*/
+function overlappingCallsPreflight(inEnvironment, freshId, boundMs) {
+	return {
+		name: "environment preflight: a second run call completes while the first call stays open",
+		run: inEnvironment((env) => assertRunPermitsOverlappingCalls((work) => env.run(async ({ repository }) => {
+			await repository.findById(freshId());
+			await work();
+		}), boundMs))
+	};
+}
+/**
 * Load with a contract diagnostic instead of a bare TypeError downstream.
 * `suspectHint` names the suite-specific likely cause (broken hydration
 * vs broken replay read).
@@ -804,6 +921,7 @@ function createEsRepositoryContractTests(harness) {
 	const createAggregateWithId = harness.createAggregateWithId;
 	const snapshotState = harness.snapshotState;
 	const captureSnapshot = harness.captureSnapshot;
+	const overlappingCallsBoundMs = harness.overlappingCallsBoundMs ?? 1e3;
 	const load = (repository, id) => loadAggregateOrFail(repository, id, "the stream was not appended or replayed correctly");
 	const streamFor = (id) => harness.streamKeyFor(id);
 	const recordedIds = (events) => recordedPendingEventIds(events, "pending events must be recorded before flush");
@@ -820,6 +938,7 @@ function createEsRepositoryContractTests(harness) {
 		return aggregate;
 	}
 	const tests = [
+		overlappingCallsPreflight(inEnvironment, () => harness.createAggregate().id, overlappingCallsBoundMs),
 		{
 			name: "add appends the exact creation batch to stream and outbox",
 			run: inEnvironment(async (environment) => {
@@ -839,32 +958,22 @@ function createEsRepositoryContractTests(harness) {
 			name: "MANDATORY stale append: writer B conflicts after writer A commits and appends no prefix",
 			run: inEnvironment(async (environment) => {
 				const seeded = await seed(environment);
-				let loaded;
-				const bLoaded = new Promise((resolve) => {
-					loaded = resolve;
-				});
-				let release;
-				const mayAppend = new Promise((resolve) => {
-					release = resolve;
-				});
-				const writerB = environment.run(async ({ repository }) => {
+				const writerB = await parkRunCall((hold) => environment.run(async ({ repository }) => {
 					const stale = await load(repository, seeded.id);
-					loaded();
-					await mayAppend;
+					await hold();
 					harness.mutate(stale);
 					harness.mutate(stale);
 					repository.update(stale);
-				});
-				await bLoaded;
-				const winner = await environment.run(async ({ repository }) => {
+				}));
+				const winner = await awaitOverlappingCall(() => environment.run(async ({ repository }) => {
 					const current = await load(repository, seeded.id);
 					harness.mutate(current);
 					repository.update(current);
 					return current;
-				});
+				}), writerB, overlappingCallsBoundMs);
 				const streamAfterWinner = await environment.committedStreamEvents(streamFor(seeded.id), readAll);
-				release();
-				const rejection = await captureRejection(writerB);
+				writerB.release();
+				const rejection = await captureRejection(writerB.call);
 				assertChainContainsKitError(rejection, ["CONCURRENCY_CONFLICT"], `stale append must reject with ConcurrencyConflictError; got ${describeError(rejection)}`);
 				const finalStream = await environment.committedStreamEvents(streamFor(seeded.id), readAll);
 				assert(finalStream.exists && deepEqual(ids(finalStream.events), ids(streamAfterWinner.events)), "a rejected multi-event append must leave no prefix in the stream");
@@ -2487,9 +2596,19 @@ function createRepositoryContractTests(harness) {
 	const mutateVersionOnly = harness.mutateVersionOnly;
 	const mutateChildCollection = harness.mutateChildCollection;
 	const insertsAreDuplicateChecked = harness.insertsAreDuplicateChecked !== false;
+	const updatesAreSupported = harness.updatesAreSupported !== false;
 	const removesAreSupported = harness.removesAreSupported === true;
 	const removesAreVersionChecked = removesAreSupported && harness.removesAreVersionChecked === true;
+	const overlappingCallsBoundMs = harness.overlappingCallsBoundMs ?? 1e3;
 	const load = (repository, id) => loadAggregateOrFail(repository, id, "the adapter did not commit or reconstitute the aggregate");
+	const update = (repository, aggregate) => {
+		assert(repository.update !== void 0, "the harness keeps updatesAreSupported, but the repository has no update");
+		repository.update(aggregate);
+	};
+	const updateGate = {
+		capability: "updatesAreSupported",
+		satisfiedBy: updatesAreSupported
+	};
 	async function seed(environment) {
 		const aggregate = harness.createAggregate();
 		harness.mutate(aggregate);
@@ -2502,6 +2621,7 @@ function createRepositoryContractTests(harness) {
 	const eventIds = (events) => sortedCommittedEventIds(events);
 	const pendingEventIds = (events) => recordedPendingEventIds(events, "the harness must record pending events before persistence");
 	const tests = [
+		overlappingCallsPreflight(inEnvironment, () => harness.createAggregate().id, overlappingCallsBoundMs),
 		{
 			name: "add flushes a new aggregate and its exact event batch atomically",
 			run: inEnvironment(async (environment) => {
@@ -2539,42 +2659,32 @@ function createRepositoryContractTests(harness) {
 				});
 			})
 		},
-		{
+		gatedContractTest(updateGate, {
 			name: "MANDATORY stale update: writer B conflicts after writer A commits and persists nothing",
 			run: inEnvironment(async (environment) => {
 				const seeded = await seed(environment);
-				let loadedB;
-				const bLoaded = new Promise((resolve) => {
-					loadedB = resolve;
-				});
-				let releaseB;
-				const bMayFlush = new Promise((resolve) => {
-					releaseB = resolve;
-				});
-				const writerB = environment.run(async ({ repository }) => {
+				const writerB = await parkRunCall((hold) => environment.run(async ({ repository }) => {
 					const stale = await load(repository, seeded.id);
-					loadedB();
-					await bMayFlush;
+					await hold();
 					harness.mutate(stale);
-					repository.update(stale);
-				});
-				await bLoaded;
-				const committedA = await environment.run(async ({ repository }) => {
+					update(repository, stale);
+				}));
+				const committedA = await awaitOverlappingCall(() => environment.run(async ({ repository }) => {
 					const current = await load(repository, seeded.id);
 					harness.mutate(current);
-					repository.update(current);
+					update(repository, current);
 					return current;
-				});
+				}), writerB, overlappingCallsBoundMs);
 				const outboxAfterA = await environment.committedOutboxEvents();
-				releaseB();
-				const rejection = await captureRejection(writerB);
+				writerB.release();
+				const rejection = await captureRejection(writerB.call);
 				assertChainContainsKitError(rejection, ["CONCURRENCY_CONFLICT"], `stale update must reject with ConcurrencyConflictError; got ${describeError(rejection)}`);
 				const final = await reload(environment, seeded.id);
 				assertEqual(final.version, committedA.version, "the stale writer must not replace writer A's version");
 				if (snapshotState) assert(deepEqual(snapshotState.call(harness, final), snapshotState.call(harness, committedA)), "the stale writer must not replace writer A's state");
 				assert(deepEqual(eventIds(await environment.committedOutboxEvents()), eventIds(outboxAfterA)), "a rejected stale flush must add no outbox records");
 			})
-		},
+		}),
 		{
 			name: "rollback acknowledges nothing and commits neither state nor outbox",
 			run: inEnvironment(async (environment) => {
@@ -2619,26 +2729,26 @@ function createRepositoryContractTests(harness) {
 				});
 			})
 		},
-		{
+		gatedContractTest(updateGate, {
 			name: "an unchanged explicit update is safe and emits no event",
 			run: inEnvironment(async (environment) => {
 				const seeded = await seed(environment);
 				const before = await environment.committedOutboxEvents();
 				await environment.run(async ({ repository }) => {
 					const aggregate = await load(repository, seeded.id);
-					repository.update(aggregate);
+					update(repository, aggregate);
 				});
 				assert(deepEqual(eventIds(await environment.committedOutboxEvents()), eventIds(before)), "an unchanged update must not manufacture an outbox event");
 			})
-		}
+		})
 	];
 	tests.push(gatedContractTest({
 		capability: createAggregateWithId ? "insertsAreDuplicateChecked" : "createAggregateWithId",
-		satisfiedBy: Boolean(createAggregateWithId) && insertsAreDuplicateChecked
+		satisfiedBy: Boolean(createAggregateWithId) && insertsAreDuplicateChecked || !updatesAreSupported
 	}, {
 		name: "duplicate add rejects and preserves the existing aggregate",
 		run: inEnvironment(async (environment) => {
-			assert(createAggregateWithId !== void 0, "capability gate");
+			assert(createAggregateWithId !== void 0 && insertsAreDuplicateChecked, "an append-only harness must provide createAggregateWithId and keep insertsAreDuplicateChecked: the duplicate-add proof is its only concurrency proof");
 			const seeded = await seed(environment);
 			const duplicate = createAggregateWithId.call(harness, seeded.id);
 			harness.mutate(duplicate);
@@ -2652,7 +2762,7 @@ function createRepositoryContractTests(harness) {
 			if (snapshotState) assert(deepEqual(snapshotState.call(harness, final), snapshotState.call(harness, seeded)), "the existing row's state must be untouched by the rejected duplicate add");
 		})
 	}));
-	tests.push(gatedContractTest({
+	tests.push(gatedContractTest(updateGate, gatedContractTest({
 		capability: "mutateVersionOnly",
 		satisfiedBy: Boolean(mutateVersionOnly)
 	}, {
@@ -2664,14 +2774,14 @@ function createRepositoryContractTests(harness) {
 			await environment.run(async ({ repository }) => {
 				const aggregate = await load(repository, seeded.id);
 				mutateVersionOnly.call(harness, aggregate);
-				repository.update(aggregate);
+				update(repository, aggregate);
 			});
 			const reloaded = await reload(environment, seeded.id);
 			assertEqual(reloaded.version, seeded.version + 1, "a version-only change (empty change set, bumped version) must still be persisted; skipping it desyncs the persisted version and produces false concurrency conflicts later");
 			assert(deepEqual(eventIds(await environment.committedOutboxEvents()), eventIds(outboxBefore)), "state-only update must not create an outbox event");
 		})
-	}));
-	tests.push(gatedContractTest({
+	})));
+	tests.push(gatedContractTest(updateGate, gatedContractTest({
 		capability: "mutateChildCollection",
 		satisfiedBy: Boolean(mutateChildCollection)
 	}, {
@@ -2682,12 +2792,12 @@ function createRepositoryContractTests(harness) {
 			await environment.run(async ({ repository }) => {
 				const aggregate = await load(repository, seeded.id);
 				mutateChildCollection.call(harness, aggregate);
-				repository.update(aggregate);
+				update(repository, aggregate);
 			});
 			const reloaded = await reload(environment, seeded.id);
 			assertEqual(reloaded.version, seeded.version + 1, "nested collection update must advance the persisted root version");
 		})
-	}));
+	})));
 	tests.push(gatedContractTest({
 		capability: "removesAreSupported",
 		satisfiedBy: removesAreSupported
@@ -2704,40 +2814,30 @@ function createRepositoryContractTests(harness) {
 			assert(await environment.run(({ repository }) => repository.findById(seeded.id)) === void 0, "remove must physically remove the aggregate after commit");
 		})
 	}));
-	tests.push(gatedContractTest({
+	tests.push(gatedContractTest(updateGate, gatedContractTest({
 		capability: "removesAreVersionChecked",
 		satisfiedBy: removesAreVersionChecked
 	}, {
 		name: "stale remove conflicts and cannot delete a concurrent update",
 		run: inEnvironment(async (environment) => {
 			const seeded = await seed(environment);
-			let loaded;
-			const staleLoaded = new Promise((resolve) => {
-				loaded = resolve;
-			});
-			let release;
-			const mayRemove = new Promise((resolve) => {
-				release = resolve;
-			});
-			const staleRemove = environment.run(async ({ repository }) => {
+			const staleRemove = await parkRunCall((hold) => environment.run(async ({ repository }) => {
 				assert(repository.remove !== void 0, "remove capability gate");
 				const stale = await load(repository, seeded.id);
-				loaded();
-				await mayRemove;
+				await hold();
 				repository.remove(stale);
-			});
-			await staleLoaded;
-			await environment.run(async ({ repository }) => {
+			}));
+			await awaitOverlappingCall(() => environment.run(async ({ repository }) => {
 				const current = await load(repository, seeded.id);
 				harness.mutate(current);
-				repository.update(current);
-			});
-			release();
-			const rejection = await captureRejection(staleRemove);
+				update(repository, current);
+			}), staleRemove, overlappingCallsBoundMs);
+			staleRemove.release();
+			const rejection = await captureRejection(staleRemove.call);
 			assertChainContainsKitError(rejection, ["CONCURRENCY_CONFLICT"], `stale remove must reject with ConcurrencyConflictError; got ${describeError(rejection)}`);
 			assert(await reload(environment, seeded.id) !== void 0, "stale remove must not delete the concurrent winner");
 		})
-	}));
+	})));
 	return tests;
 }