@shirudo/ddd-kit 1.0.0-rc.6 → 1.0.0-rc.8

package/dist/index.js

@@ -399,6 +399,26 @@ function setEventIdFactory(factory) {
   currentEventIdFactory = factory;
 }
 __name(setEventIdFactory, "setEventIdFactory");
+function assertNotThenable(result, helperName) {
+  if (result !== null && (typeof result === "object" || typeof result === "function") && typeof result.then === "function") {
+    throw new Error(
+      `${helperName}: fn returned a thenable. The factory is only installed for the synchronous portion of fn; awaited continuations would see the previous factory. For async-scoped factories use AsyncLocalStorage.`
+    );
+  }
+}
+__name(assertNotThenable, "assertNotThenable");
+function withEventIdFactory(factory, fn) {
+  const previous = currentEventIdFactory;
+  currentEventIdFactory = factory;
+  try {
+    const result = fn();
+    assertNotThenable(result, "withEventIdFactory");
+    return result;
+  } finally {
+    currentEventIdFactory = previous;
+  }
+}
+__name(withEventIdFactory, "withEventIdFactory");
 function resetEventIdFactory() {
   currentEventIdFactory = defaultEventIdFactory;
 }
@@ -409,6 +429,18 @@ function setClockFactory(factory) {
   currentClockFactory = factory;
 }
 __name(setClockFactory, "setClockFactory");
+function withClockFactory(factory, fn) {
+  const previous = currentClockFactory;
+  currentClockFactory = factory;
+  try {
+    const result = fn();
+    assertNotThenable(result, "withClockFactory");
+    return result;
+  } finally {
+    currentClockFactory = previous;
+  }
+}
+__name(withClockFactory, "withClockFactory");
 function resetClockFactory() {
   currentClockFactory = defaultClockFactory;
 }
@@ -587,18 +619,61 @@ var AggregateRoot = class extends Entity {
     this._pendingEvents = [];
   }
   /**
-   * Post-save hook called by a `Repository.save()` implementation to push
-   * the persisted version back into the in-memory aggregate and clear
-   * pendingEvents (they are now safely on the write side / in the
-   * outbox).
+   * **Framework lifecycle method — `@sealed`.** Called by `withCommit`
+   * (or by your own orchestration code, after harvesting `pendingEvents`)
+   * to push the persisted version back into the in-memory aggregate and
+   * clear `pendingEvents`. TypeScript has no `final` keyword, but
+   * subclasses **should not** override this method directly.
+   *
+   * Overriding without calling `super.markPersisted(version)` silently
+   * leaks `pendingEvents` — the next `withCommit` will re-dispatch them
+   * through the outbox, double-emitting events. This bug has been hit
+   * in production by consumers; the {@link onPersisted} hook below is
+   * the safer extension point.
+   *
+   * If you must override (legitimate cases are very rare), call
+   * `super.markPersisted(version)` FIRST so the framework's cleanup
+   * runs, then add your logic afterwards.
    *
-   * Use this so `save()` can keep its `Promise<void>` return type: the
-   * caller holds the aggregate reference, which is up to date after this
-   * call.
+   * @param version - The version assigned by the persistence layer
+   * @see onPersisted — the safe extension point for subclasses
    */
   markPersisted(version) {
     this.setVersion(version);
     this._pendingEvents = [];
+    this.onPersisted(version);
+  }
+  /**
+   * Subclass extension point — fires AFTER {@link markPersisted} has
+   * updated the version and cleared `pendingEvents`. Override this for
+   * post-persist logging, metrics, or cache-eviction without risk of
+   * breaking the framework's pendingEvents cleanup.
+   *
+   * The default implementation is a no-op. Subclasses do NOT need to
+   * call `super.onPersisted(version)` — there is nothing in the parent
+   * implementation to preserve.
+   *
+   * **`onPersisted` deliberately receives only the version, not the
+   * drained events.** Event-driven post-persist logic (aggregate-level
+   * audit logging, per-event-type side effects) belongs in `EventBus`
+   * subscribers or the outbox dispatcher — that is the proper
+   * Aggregate-Boundary separation. Building event-aware logic into
+   * `onPersisted` couples aggregate lifecycle to event processing and
+   * recreates the boundary problems Vernon's aggregate discipline is
+   * meant to prevent.
+   *
+   * **The hook must return synchronously.** `markPersisted` is `void`-
+   * typed and calls `onPersisted` without `await`. TypeScript's
+   * permissive `void` will accept an `async`-override returning
+   * `Promise<void>`, but the returned promise is fire-and-forget —
+   * any rejection becomes an unhandled rejection and `withCommit`
+   * proceeds without waiting. For asynchronous work, subscribe to the
+   * relevant domain event on the `EventBus` instead; that is the
+   * properly awaited extension point.
+   *
+   * @param version - The version that was just persisted
+   */
+  onPersisted(_version) {
   }
   /**
    * Mutates state and records the resulting domain events in the
@@ -689,6 +764,47 @@ var AggregateRoot = class extends Entity {
   addDomainEvent(event) {
     this._pendingEvents.push(event);
   }
+  /**
+   * Sugar for `createDomainEvent` that auto-injects `aggregateId`
+   * (from `this.id`) and `aggregateType` (from {@link aggregateType})
+   * into the event's metadata fields. This is the canonical path for
+   * recording events from inside aggregate domain methods.
+   *
+   * Downstream consumers — outbox dispatchers, projection handlers,
+   * audit logs — route by these two fields. Calling
+   * `createDomainEvent(...)` directly inside an aggregate method
+   * leaves them unset and is caught at the `withCommit` harvest
+   * boundary, but `this.recordEvent(...)` makes the right thing
+   * impossible to forget.
+   *
+   * @example
+   * ```ts
+   * class Order extends AggregateRoot<OrderState, OrderId, OrderEvent> {
+   *   protected readonly aggregateType = "Order";
+   *
+   *   confirm(): void {
+   *     this.commit(
+   *       { ...this.state, status: "confirmed" },
+   *       this.recordEvent("OrderConfirmed", { orderId: this.id }),
+   *     );
+   *   }
+   * }
+   * ```
+   *
+   * @param type    - event type discriminator (must be one of `TEvent`'s tags)
+   * @param payload - payload for that event subtype
+   * @param options - any remaining `createDomainEvent` options
+   *   (`eventId`, `occurredAt`, `metadata`, `version`); `aggregateId`
+   *   and `aggregateType` are deliberately omitted — the helper sets
+   *   them.
+   */
+  recordEvent(type, payload, options) {
+    return createDomainEvent(type, payload, {
+      ...options,
+      aggregateId: this.id,
+      aggregateType: this.aggregateType
+    });
+  }
   /**
    * Manually bumps the aggregate version.
    * Call this after state changes for Optimistic Concurrency Control.
@@ -834,18 +950,96 @@ var EventSourcedAggregate = class extends Entity {
     this._pendingEvents = [];
   }
   /**
-   * Post-save hook called by a `Repository.save()` implementation to push
-   * the persisted version back into the in-memory aggregate and clear the
-   * pending events (they are now in the event store / outbox). Lets
-   * `save()` keep its `Promise<void>` return type.
+   * **Framework lifecycle method — `@sealed`.** Called by `withCommit`
+   * (or by your own orchestration code, after harvesting `pendingEvents`)
+   * to push the persisted version back into the in-memory aggregate and
+   * clear `pendingEvents`. TypeScript has no `final` keyword, but
+   * subclasses **should not** override this method directly.
+   *
+   * Overriding without calling `super.markPersisted(version)` silently
+   * leaks `pendingEvents` — the next `withCommit` will re-dispatch them
+   * through the outbox, double-emitting events. This bug has been hit
+   * in production by consumers; the {@link onPersisted} hook below is
+   * the safer extension point.
+   *
+   * If you must override (legitimate cases are very rare), call
+   * `super.markPersisted(version)` FIRST so the framework's cleanup
+   * runs, then add your logic afterwards.
+   *
+   * @param version - The version assigned by the persistence layer
+   * @see onPersisted — the safe extension point for subclasses
    */
   markPersisted(version) {
     this.setVersion(version);
     this._pendingEvents = [];
+    this.onPersisted(version);
+  }
+  /**
+   * Subclass extension point — fires AFTER {@link markPersisted} has
+   * updated the version and cleared `pendingEvents`. Override this for
+   * post-persist logging, metrics, or cache-eviction without risk of
+   * breaking the framework's pendingEvents cleanup.
+   *
+   * The default implementation is a no-op. Subclasses do NOT need to
+   * call `super.onPersisted(version)` — there is nothing in the parent
+   * implementation to preserve.
+   *
+   * **`onPersisted` deliberately receives only the version, not the
+   * drained events.** Event-driven post-persist logic (aggregate-level
+   * audit logging, per-event-type side effects) belongs in `EventBus`
+   * subscribers or the outbox dispatcher — that is the proper
+   * Aggregate-Boundary separation. Building event-aware logic into
+   * `onPersisted` couples aggregate lifecycle to event processing and
+   * recreates the boundary problems Vernon's aggregate discipline is
+   * meant to prevent.
+   *
+   * **The hook must return synchronously.** `markPersisted` is `void`-
+   * typed and calls `onPersisted` without `await`. TypeScript's
+   * permissive `void` will accept an `async`-override returning
+   * `Promise<void>`, but the returned promise is fire-and-forget —
+   * any rejection becomes an unhandled rejection and `withCommit`
+   * proceeds without waiting. For asynchronous work, subscribe to the
+   * relevant domain event on the `EventBus` instead; that is the
+   * properly awaited extension point.
+   *
+   * @param version - The version that was just persisted
+   */
+  onPersisted(_version) {
   }
   constructor(id, initialState) {
     super(id, initialState);
   }
+  /**
+   * Sugar for `createDomainEvent` that auto-injects `aggregateId`
+   * (from `this.id`) and `aggregateType` (from {@link aggregateType})
+   * into the event's metadata fields. The canonical path for
+   * constructing events to feed into `apply()` from inside aggregate
+   * domain methods.
+   *
+   * @example
+   * ```ts
+   * class Order extends EventSourcedAggregate<OrderState, OrderEvent, OrderId> {
+   *   protected readonly aggregateType = "Order";
+   *
+   *   confirm(): void {
+   *     this.apply(this.recordEvent("OrderConfirmed", { orderId: this.id }));
+   *   }
+   * }
+   * ```
+   *
+   * Calling `createDomainEvent(...)` directly inside an aggregate
+   * method leaves `aggregateId` and `aggregateType` unset; the
+   * `withCommit` harvest boundary catches it at runtime, but
+   * `this.recordEvent(...)` makes the right thing impossible to
+   * forget.
+   */
+  recordEvent(type, payload, options) {
+    return createDomainEvent(type, payload, {
+      ...options,
+      aggregateId: this.id,
+      aggregateType: this.aggregateType
+    });
+  }
   // --- Event application ---
   /**
    * Validates an event before it is applied. Default is no-op.
@@ -987,13 +1181,26 @@ async function withCommit(deps, fn) {
   const { result, aggregates, events } = await deps.scope.transactional(
     async (ctx) => {
       const fnResult = await fn(ctx);
-      const harvested = fnResult.aggregates.flatMap(
+      const uniqueAggregates = Array.from(new Set(fnResult.aggregates));
+      const harvested = uniqueAggregates.flatMap(
         (agg) => agg.pendingEvents
       );
+      for (const event of harvested) {
+        const missing = [];
+        if (!event.aggregateId) missing.push("aggregateId");
+        if (!event.aggregateType) missing.push("aggregateType");
+        if (missing.length > 0) {
+          throw new Error(
+            `withCommit: event "${event.type}" is missing ${missing.join(
+              " and "
+            )}. Use this.recordEvent(type, payload) inside aggregate methods instead of createDomainEvent(...) \u2014 recordEvent auto-injects aggregateId and aggregateType. Outbox dispatchers and projection handlers rely on these fields for routing.`
+          );
+        }
+      }
       if (harvested.length > 0) {
         await deps.outbox.add(harvested);
       }
-      return { ...fnResult, events: harvested };
+      return { ...fnResult, aggregates: uniqueAggregates, events: harvested };
     }
   );
   for (const agg of aggregates) {
@@ -1163,6 +1370,6 @@ var InMemoryOutbox = class {
   }
 };
 
-export { AggregateNotFoundError, AggregateRoot, CommandBus, ConcurrencyConflictError, DomainError, Entity, EventBusImpl, EventSourcedAggregate, InMemoryOutbox, InfrastructureError, MissingHandlerError, QueryBus, ValueObject, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepEqual, deepEqualExcept, deepFreeze, deepOmit, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voWithValidation, withCommit };
+export { AggregateNotFoundError, AggregateRoot, CommandBus, ConcurrencyConflictError, DomainError, Entity, EventBusImpl, EventSourcedAggregate, InMemoryOutbox, InfrastructureError, MissingHandlerError, QueryBus, ValueObject, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepEqual, deepEqualExcept, deepFreeze, deepOmit, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voWithValidation, withClockFactory, withCommit, withEventIdFactory };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map