@shirudo/ddd-kit 3.0.0-rc.3 → 3.0.0-rc.4

package/dist/index.js

@@ -153,7 +153,7 @@ var Entity = class {
 	* today's decision validator.
 	*/
 	_state;
-	_deepFreezeState;
+	_stateFreezeMode;
 	validateState;
 	/**
 	* **State ownership.** Plain-object and array states are shallow-copied
@@ -172,9 +172,9 @@ var Entity = class {
 	constructor(id, initialState, config) {
 		if (id === null || id === void 0) throw new Error("Entity ID cannot be null or undefined");
 		this.id = id;
-		this._deepFreezeState = config?.deepFreezeState ?? false;
+		this._stateFreezeMode = config?.deepFreezeState ?? false ? "deep" : "shallow";
 		this.validateState = config?.validateState ?? noStateValidation;
-		this._state = freezeStateByMode(shallowCopyOwned(initialState), this._deepFreezeState);
+		this._state = freezeStateByMode(shallowCopyOwned(initialState), this._stateFreezeMode);
 		this.validateState(this._state);
 	}
 	/**
@@ -187,7 +187,7 @@ var Entity = class {
 	* path. Ordinary domain behavior should use {@link setState} instead.
 	*/
 	freezeState(value) {
-		return freezeStateByMode(value, this._deepFreezeState);
+		return freezeStateByMode(value, this._stateFreezeMode);
 	}
 	/**
 	* Sets the state of the entity.
@@ -210,8 +210,8 @@ var Entity = class {
 	}
 };
 const noStateValidation = () => {};
-function freezeStateByMode(value, deep) {
-	return deep ? deepFreeze(value) : freezeShallow(value);
+function freezeStateByMode(value, mode) {
+	return mode === "deep" ? deepFreeze(value) : freezeShallow(value);
 }
 /**
 * Shallow-freezes `value` when it's a non-null object or array, so that
@@ -1025,7 +1025,7 @@ function mapHandlerFailure(error, mapExpectedError, busKind) {
 * Supports an optional type map (`TMap`) for automatic return type inference.
 * When `TMap` is concrete, `execute()` infers the result type from the command type.
 * An explicit competing result generic cannot override that map.
-* Without `TMap`, it works like before (return type defaults to `unknown` or can be specified manually).
+* Without `TMap`, the return type defaults to `unknown` or is specified per call.
 *
 * **Note:** This is a basic implementation suitable for development and simple use cases.
 * For production environments, consider implementing or using a more feature-rich bus that includes:
@@ -1043,13 +1043,13 @@ function mapHandlerFailure(error, mapExpectedError, busKind) {
 *
 * @example
 * ```typescript
-* // With type map – full inference
+* // With a type map: full inference
 * type Commands = { CreateOrder: OrderId; CancelOrder: void };
 * const bus = new CommandBus<Commands>();
 * const result = await bus.execute({ type: "CreateOrder", ... });
 * // result: Result<OrderId, string>
 *
-* // Without type map – same as before
+* // Without a type map: specify the return type per call
 * const bus = new CommandBus();
 * bus.register("CreateOrder", async (cmd) => ok(orderId));
 * const result = await bus.execute({ type: "CreateOrder", ... });
@@ -1788,42 +1788,62 @@ async function withIdempotentCommit(deps, request, fn) {
 		claim: void 0,
 		heartbeat: void 0
 	};
-	const scope = { transactional: (work, options) => deps.scope.transactional(async (ctx) => {
-		attempt.claim = void 0;
-		attempt.heartbeat = void 0;
+	const scope = { transactional: async (work, options) => {
 		try {
-			const result = await work(ctx);
-			const currentHeartbeat = attempt.heartbeat;
-			await currentHeartbeat?.stop();
-			const heartbeatFailure = currentHeartbeat?.failure();
-			if (heartbeatFailure !== void 0) throw heartbeatFailure;
-			return result;
+			return await deps.scope.transactional(async (ctx) => {
+				attempt.claim = void 0;
+				attempt.heartbeat = void 0;
+				try {
+					const result = await work(ctx);
+					const currentHeartbeat = attempt.heartbeat;
+					await currentHeartbeat?.stop();
+					const heartbeatFailure = currentHeartbeat?.failure();
+					if (heartbeatFailure !== void 0) throw heartbeatFailure;
+					return result;
+				} catch (error) {
+					const currentHeartbeat = attempt.heartbeat;
+					await currentHeartbeat?.stop();
+					const heartbeatFailure = currentHeartbeat?.failure();
+					const currentClaim = attempt.claim;
+					if (heartbeatFailure !== void 0 && heartbeatFailure !== error && currentClaim) reportToObserver(() => deps.onIdempotencyError?.(heartbeatFailure, {
+						operation: "renew",
+						key: currentClaim.key,
+						token: currentClaim.token
+					}));
+					const abandoned = attempt.claim;
+					if (abandoned) {
+						attempt.claim = void 0;
+						try {
+							await store.abandon(abandoned);
+						} catch (abandonError) {
+							reportToObserver(() => deps.onIdempotencyError?.(abandonError, {
+								operation: "abandon",
+								key: abandoned.key,
+								token: abandoned.token
+							}));
+						}
+					}
+					throw error;
+				}
+			}, options);
 		} catch (error) {
-			const currentHeartbeat = attempt.heartbeat;
-			await currentHeartbeat?.stop();
-			const heartbeatFailure = currentHeartbeat?.failure();
-			const currentClaim = attempt.claim;
-			if (heartbeatFailure !== void 0 && heartbeatFailure !== error && currentClaim) reportToObserver(() => deps.onIdempotencyError?.(heartbeatFailure, {
-				operation: "renew",
-				key: currentClaim.key,
-				token: currentClaim.token
-			}));
-			const abandoned = attempt.claim;
-			if (abandoned) {
+			const staged = attempt.claim;
+			if (staged) {
 				attempt.claim = void 0;
+				attempt.heartbeat = void 0;
 				try {
-					await store.abandon(abandoned);
+					await store.abandon(staged);
 				} catch (abandonError) {
 					reportToObserver(() => deps.onIdempotencyError?.(abandonError, {
 						operation: "abandon",
-						key: abandoned.key,
-						token: abandoned.token
+						key: staged.key,
+						token: staged.token
 					}));
 				}
 			}
 			throw error;
 		}
-	}, options) };
+	} };
 	const outcome = await withCommit({
 		...deps,
 		scope
@@ -2073,7 +2093,7 @@ var InMemoryIdempotencyStore = class {
 * Supports an optional type map (`TMap`) for automatic return type inference.
 * When `TMap` is concrete, `execute()` and `executeUnsafe()` infer the result type from the query type.
 * Explicit competing result generics cannot override that map.
-* Without `TMap`, it works like before (return type defaults to `unknown` or can be specified manually).
+* Without `TMap`, the return type defaults to `unknown` or is specified per call.
 *
 * **Note:** This is a basic implementation suitable for development and simple use cases.
 * For production environments, consider implementing or using a more feature-rich bus that includes:
@@ -2091,13 +2111,13 @@ var InMemoryIdempotencyStore = class {
 *
 * @example
 * ```typescript
-* // With type map – full inference
+* // With a type map: full inference
 * type Queries = { GetOrder: Order | null; ListOrders: Order[] };
 * const bus = new QueryBus<Queries>();
 * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
 * // result: Result<Order | null, string>
 *
-* // Without type map – same as before
+* // Without a type map: specify the return type per call
 * const bus = new QueryBus();
 * bus.register("GetOrder", async (query) => repository.findById(query.orderId));
 * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
@@ -2695,7 +2715,8 @@ var UnitOfWork = class {
 			throw classifyRunError(error, {
 				workThrew,
 				workCompleted,
-				workError
+				workError,
+				signal: options?.signal
 			});
 		} finally {
 			session?.close();
@@ -3152,6 +3173,7 @@ function makeContext(repositories, session, signal) {
 *   scope failed to even open a transaction); pass the error through.
 */
 function classifyRunError(error, state) {
+	if (state.signal?.aborted && state.signal.reason !== void 0 && (error === state.signal.reason || causeChainContains(error, state.signal.reason))) return error;
 	if (state.workThrew) {
 		if (error === state.workError || causeChainContains(error, state.workError)) return error;
 		return new RollbackError(state.workError, error);
@@ -3545,18 +3567,23 @@ var DeadlineProcessor = class extends PollLoop {
 			const delivered = [];
 			for (const deadline of batch) {
 				if (signal?.aborted) break;
+				let boundedContext;
 				try {
 					await runBoundedExecution("DeadlineProcessor.handler", {
 						signal,
 						timeoutMs: this.deliveryTimeoutMs
-					}, (context) => this.handler(deadline, context));
+					}, (context) => {
+						boundedContext = context;
+						return this.handler(deadline, context);
+					});
 					delivered.push(deadline);
 				} catch (error) {
 					if (signal?.aborted) break;
 					handlerFailed = true;
 					const assessment = assessDeliveryFailure(error, this.classifyFailure);
 					reportToObserver(() => this.observers.onDeliveryError(error, deadline, assessment));
-					if (assessment.kind !== "transient") try {
+					const ownBudgetExpired = !signal?.aborted && boundedContext?.signal.aborted === true;
+					if (assessment.kind !== "transient" || ownBudgetExpired) try {
 						const deadLetter = await runBoundedExecution("DeadlineProcessor.markFailed", {
 							signal,
 							timeoutMs: this.storageTimeoutMs
@@ -4471,24 +4498,42 @@ var EventBusImpl = class {
 	*    `AggregateError` for multiple failures).
 	*/
 	async publish(events, options = {}) {
-		return runBoundedExecution("EventBus.publish", {
-			signal: options.signal,
-			timeoutMs: options.timeoutMs ?? 3e4
-		}, (context) => this.publishWithinContext(events, context));
-	}
-	async publishWithinContext(events, context) {
 		const errors = [];
+		try {
+			await runBoundedExecution("EventBus.publish", {
+				signal: options.signal,
+				timeoutMs: options.timeoutMs ?? 3e4
+			}, (context) => this.publishWithinContext(events, context, errors));
+		} catch (boundedError) {
+			if (errors.length === 0) throw boundedError;
+			throw new AggregateError([boundedError instanceof Error ? boundedError : new Error(String(boundedError), { cause: boundedError }), ...errors], "EventBus.publish aborted after handler failures");
+		}
+		if (errors.length === 1) throw errors[0];
+		if (errors.length > 1) throw new AggregateError(errors, "Multiple event handlers failed");
+	}
+	async publishWithinContext(events, context, errors) {
 		for (const event of events) {
 			if (context.signal.aborted) throw abortReason(context.signal, "EventBus.publish aborted");
 			const batch = [...this.handlers.get(event.type) ?? [], ...this.catchAllHandlers];
 			if (batch.length > 0) {
-				const results = await Promise.allSettled(batch.map(async (handler) => handler(event, context)));
-				for (const result of results) if (result.status === "rejected") errors.push(result.reason instanceof Error ? result.reason : new Error(String(result.reason), { cause: result.reason }));
+				const batchStart = errors.length;
+				const failedIndices = [];
+				await Promise.allSettled(batch.map(async (handler, index) => {
+					try {
+						await handler(event, context);
+					} catch (reason) {
+						failedIndices.push(index);
+						errors.push(reason instanceof Error ? reason : new Error(String(reason), { cause: reason }));
+					}
+				}));
+				const settled = errors.splice(batchStart);
+				errors.push(...failedIndices.map((index, i) => ({
+					index,
+					error: settled[i]
+				})).sort((a, b) => a.index - b.index).map((entry) => entry.error));
 			}
 			if (context.signal.aborted) throw abortReason(context.signal, "EventBus.publish aborted");
 		}
-		if (errors.length === 1) throw errors[0];
-		if (errors.length > 1) throw new AggregateError(errors, "Multiple event handlers failed");
 	}
 };
 
@@ -4772,7 +4817,7 @@ var InMemoryOutbox = class {
 			const dispatchedReceipt = this.dispatchedEventIds.get(event.eventId);
 			if (dispatchedReceipt !== void 0) {
 				assertSameEventSource(event, source, dispatchedReceipt.source);
-				assertSameCandidateReceipt(event, position, dispatchedReceipt.position, false);
+				assertSameCandidateReceipt(event, position, dispatchedReceipt.position);
 				this.rememberDispatched(event.eventId, dispatchedReceipt.source, dispatchedReceipt.position);
 				continue;
 			}
@@ -4780,11 +4825,11 @@ var InMemoryOutbox = class {
 			const deadLetter = this.dead.get(event.eventId);
 			if (existing !== void 0) {
 				assertSameEventSource(event, source, existing.source);
-				assertSameCandidateReceipt(event, position, existing.position, true);
+				assertSameCandidateReceiptAllowingVersionRefresh(event, position, existing.position);
 			}
 			if (deadLetter) {
 				assertSameEventSource(event, source, deadLetter.source);
-				assertSameCandidateReceipt(event, position, deadLetter.position, false);
+				assertSameCandidateReceipt(event, position, deadLetter.position);
 				this.dead.delete(event.eventId);
 				this.pending.set(event.eventId, {
 					dispatchId: deadLetter.dispatchId,
@@ -4801,7 +4846,7 @@ var InMemoryOutbox = class {
 			let staleHeadVersion;
 			if (existing !== void 0 && position.aggregateVersion < existing.position.aggregateVersion) staleHeadVersion = existing.position.aggregateVersion;
 			else if (existing === void 0 && sourceCursor !== void 0 && position.aggregateVersion < sourceCursor.aggregateVersion) staleHeadVersion = sourceCursor.aggregateVersion;
-			if (staleHeadVersion !== void 0) throw new EventHarvestError(`InMemoryOutbox rejected stale event "${event.eventId}" for ${source.aggregateType} ${source.aggregateId} at aggregate version ${position.aggregateVersion}: the event-source head is already ${staleHeadVersion}. The dispatched-id receipt may have expired; use a durable outbox with a transactional eventId unique key for unbounded idempotency.`, event.type);
+			if (staleHeadVersion !== void 0) throw staleHeadError(event, source, position, staleHeadVersion);
 			if (sourceCursor?.aggregateVersion === position.aggregateVersion) {
 				if (sourceCursor.commitSize !== position.commitSize) throw new EventHarvestError(`InMemoryOutbox rejected event "${event.eventId}" for ${source.aggregateType} ${source.aggregateId}: aggregate version ${position.aggregateVersion} was already recorded with commitSize ${sourceCursor.commitSize}, not ${position.commitSize}.`, event.type);
 				const positionOwner = sourceCursor.eventIdsBySequence.get(position.commitSequence);
@@ -4880,7 +4925,7 @@ var InMemoryOutbox = class {
 			const batchReceipt = receiptsInBatch.get(event.eventId);
 			if (batchReceipt !== void 0) {
 				assertSameEventSource(event, source, batchReceipt.source);
-				assertSameCandidateReceipt(event, position, batchReceipt.position, false);
+				assertSameCandidateReceipt(event, position, batchReceipt.position);
 			} else receiptsInBatch.set(event.eventId, {
 				source,
 				position
@@ -4888,18 +4933,18 @@ var InMemoryOutbox = class {
 			const dispatchedReceipt = this.dispatchedEventIds.get(event.eventId);
 			if (dispatchedReceipt !== void 0) {
 				assertSameEventSource(event, source, dispatchedReceipt.source);
-				assertSameCandidateReceipt(event, position, dispatchedReceipt.position, false);
+				assertSameCandidateReceipt(event, position, dispatchedReceipt.position);
 				continue;
 			}
 			const existing = this.pending.get(event.eventId);
 			if (existing !== void 0) {
 				assertSameEventSource(event, source, existing.source);
-				assertSameCandidateReceipt(event, position, existing.position, true);
+				assertSameCandidateReceiptAllowingVersionRefresh(event, position, existing.position);
 			}
 			const deadLetter = this.dead.get(event.eventId);
 			if (deadLetter !== void 0) {
 				assertSameEventSource(event, source, deadLetter.source);
-				assertSameCandidateReceipt(event, position, deadLetter.position, false);
+				assertSameCandidateReceipt(event, position, deadLetter.position);
 			}
 		}
 	}
@@ -4917,7 +4962,12 @@ var InMemoryOutbox = class {
 				});
 				continue;
 			}
-			if (position.aggregateVersion < cursor.aggregateVersion) continue;
+			if (position.aggregateVersion < cursor.aggregateVersion) {
+				const dedupes = this.dispatchedEventIds.has(event.eventId) || this.dead.has(event.eventId);
+				const pendingRecord = this.pending.get(event.eventId);
+				if (pendingRecord !== void 0 && position.aggregateVersion < pendingRecord.position.aggregateVersion || pendingRecord === void 0 && !dedupes) throw staleHeadError(event, source, position, pendingRecord?.position.aggregateVersion ?? cursor.aggregateVersion);
+				continue;
+			}
 			if (cursor.commitSize !== position.commitSize) throw new EventHarvestError(`InMemoryOutbox rejected event "${event.eventId}" for ${source.aggregateType} ${source.aggregateId}: aggregate version ${position.aggregateVersion} was already recorded with commitSize ${cursor.commitSize}, not ${position.commitSize}.`, event.type);
 			const positionOwner = cursor.eventIdsBySequence.get(position.commitSequence);
 			if (positionOwner !== void 0 && positionOwner !== event.eventId) throw new EventHarvestError(`InMemoryOutbox rejected event "${event.eventId}" for ${source.aggregateType} ${source.aggregateId}: source position (${position.aggregateVersion}, ${position.commitSequence}) is already owned by event "${positionOwner}". One qualified source position must identify exactly one immutable event.`, event.type);
@@ -4992,10 +5042,24 @@ function cursorWithEvent(cursor, commitSequence, eventId) {
 		eventIdsBySequence: new Map(cursor.eventIdsBySequence).set(commitSequence, eventId)
 	};
 }
-function assertSameCandidateReceipt(event, received, recorded, allowAggregateVersionRefresh) {
+function assertSameCandidateReceipt(event, received, recorded) {
+	assertReceiptShape(event, received, recorded, false);
+}
+/**
+* The lenient variant for PENDING records only: this in-memory adapter
+* cannot observe rollback, so a re-harvested event may legitimately arrive
+* at a new aggregateVersion. Index and commit cardinality stay immutable.
+*/
+function assertSameCandidateReceiptAllowingVersionRefresh(event, received, recorded) {
+	assertReceiptShape(event, received, recorded, true);
+}
+function assertReceiptShape(event, received, recorded, allowAggregateVersionRefresh) {
 	if ((allowAggregateVersionRefresh || received.aggregateVersion === recorded.aggregateVersion) && received.commitSequence === recorded.commitSequence && received.commitSize === recorded.commitSize) return;
 	throw new EventHarvestError(`InMemoryOutbox rejected event "${event.eventId}": its commit candidate changed from (${recorded.aggregateVersion}, ${recorded.commitSequence}; commitSize=${recorded.commitSize}) to (${received.aggregateVersion}, ${received.commitSequence}; commitSize=${received.commitSize}). An exact redelivery must keep its source position immutable.`, event.type);
 }
+function staleHeadError(event, source, position, staleHeadVersion) {
+	return new EventHarvestError(`InMemoryOutbox rejected stale event "${event.eventId}" for ${source.aggregateType} ${source.aggregateId} at aggregate version ${position.aggregateVersion}: the event-source head is already ${staleHeadVersion}. The dispatched-id receipt may have expired; use a durable outbox with a transactional eventId unique key for unbounded idempotency.`, event.type);
+}
 function assertSameEventSource(event, received, recorded) {
 	if (received.aggregateType === recorded.aggregateType && received.aggregateId === recorded.aggregateId) return;
 	throw new EventHarvestError(`InMemoryOutbox rejected eventId collision for "${event.eventId}": it already belongs to ${recorded.aggregateType} ${recorded.aggregateId}, but was received for ${received.aggregateType} ${received.aggregateId}. An eventId must identify one immutable event across all aggregate sources.`, event.type);
@@ -5740,7 +5804,7 @@ var InMemoryEventStore = class {
 			storedEvents = [];
 			this.streams.set(key, storedEvents);
 		}
-		for (const event of events) storedEvents.push(event);
+		for (const event of events) storedEvents.push(structuredClone(event));
 		this.totalEvents += events.length;
 	}
 	async readStream(stream, options) {
@@ -5759,7 +5823,7 @@ var InMemoryEventStore = class {
 		return {
 			exists: true,
 			lastVersion: events.length,
-			events: events.slice(fromVersion, pageEnd)
+			events: structuredClone(events.slice(fromVersion, pageEnd))
 		};
 	}
 };
@@ -5893,7 +5957,7 @@ var RetryingTransactionScope = class {
 		assertNonNegativeFinite("RetryingTransactionScope", "maxDelayMs", this.maxDelayMs);
 		this.isRetryable = policy.isRetryable ?? someChainRetryable;
 		this.sleep = policy.sleep ?? defaultSleep;
-		this.random = policy.random ?? Math.random;
+		this.random = neutralJitterSource(policy.random ?? Math.random);
 		this.onRetry = policy.onRetry;
 	}
 	async transactional(fn, options) {
@@ -5933,8 +5997,9 @@ var RetryingTransactionScope = class {
 //#region src/repo/snapshot-model.ts
 /** Type-inference helper for declaring an adapter-owned snapshot model. */
 function defineSnapshotModel(model) {
-	assertSnapshotModel(model);
-	return Object.freeze({ ...model });
+	const detached = Object.freeze({ ...model });
+	assertSnapshotModel(detached);
+	return detached;
 }
 /**
 * Captures a detached persistence envelope at an application-supplied time.
@@ -5989,6 +6054,8 @@ function reconstituteAggregateFromSnapshot(model, id, snapshot) {
 function assertSnapshotModel(model) {
 	if (typeof model.aggregateType !== "string" || model.aggregateType.trim().length === 0) throw new TypeError("SnapshotModel.aggregateType must be a non-empty string");
 	assertPositiveSafeInteger("SnapshotModel", "schemaVersion", model.schemaVersion);
+	for (const key of ["capture", "reconstitute"]) if (typeof model[key] !== "function") throw new TypeError(`SnapshotModel.${key} is missing or not a function. defineSnapshotModel copies own enumerable properties only; prototype methods are not carried. Pass a plain object literal.`);
+	if (model.migrate !== void 0 && typeof model.migrate !== "function") throw new TypeError("SnapshotModel.migrate must be a function when set");
 }
 function copySnapshotAt(snapshotAt) {
 	if (!(snapshotAt instanceof Date) || !Number.isFinite(snapshotAt.getTime())) throw new SnapshotTimeValidationError();