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

package/dist/index.js

@@ -589,35 +589,83 @@ function entityIds(entities) {
 }
 __name(entityIds, "entityIds");
 
-// src/aggregate/aggregate-root.ts
-var AggregateRoot = class extends Entity {
+// src/aggregate/base-aggregate.ts
+var BaseAggregate = class extends Entity {
   static {
-    __name(this, "AggregateRoot");
+    __name(this, "BaseAggregate");
   }
   _version = 0;
+  /**
+   * DB-baseline version. `undefined` until the aggregate has been
+   * persisted or restored at least once. Repository implementations
+   * route INSERT vs UPDATE on this field and use it as the OCC
+   * baseline. See `IRepository.save` JSDoc.
+   *
+   * Distinct from {@link version}, which is the in-memory
+   * post-mutation value. Mutations bump `_version` but never touch
+   * `_persistedVersion` — that field only moves on {@link markRestored}
+   * (Post-Load) and {@link markPersisted} (Post-Save).
+   */
+  _persistedVersion = void 0;
+  _pendingEvents = [];
   get version() {
     return this._version;
   }
-  setVersion(version) {
-    this._version = version;
+  get persistedVersion() {
+    return this._persistedVersion;
   }
-  _config;
-  _autoVersionBump;
-  _pendingEvents = [];
   /**
-   * Read-only list of domain events recorded on this aggregate that have
-   * not yet been flushed to the outbox / persistence layer.
+   * Read-only list of domain events recorded on this aggregate that
+   * have not yet been flushed to the outbox / persistence layer.
    */
   get pendingEvents() {
     return Object.freeze(this._pendingEvents.slice());
   }
   /**
-   * Clears the pending-event list. Call this after the events have been
-   * dispatched (typically `markPersisted` handles it for you).
+   * Clears the pending-event list. Called by `markPersisted` after a
+   * successful write — the events have been handed off to the outbox
+   * / event store and are no longer the aggregate's responsibility.
    */
   clearPendingEvents() {
     this._pendingEvents = [];
   }
+  setVersion(version) {
+    this._version = version;
+  }
+  /**
+   * Manually bumps the aggregate version. Used by state-stored
+   * aggregates' `setState(_, true)` / `commit()` paths and by the
+   * event-sourced replay path after each applied event.
+   */
+  bumpVersion() {
+    this.setVersion(this._version + 1);
+  }
+  /**
+   * **Lifecycle marker — Post-Load.** Syncs both `_version` and
+   * `_persistedVersion` to the DB-stored version. Used by
+   * `reconstitute(...)` factories to assemble an in-memory aggregate
+   * from a persisted row.
+   *
+   * Does NOT fire {@link onPersisted} — that hook has post-save
+   * semantics (metrics, audit, cache eviction), not post-load. The
+   * Factory-vs-Reconstitution distinction (Vernon §11) is honoured
+   * structurally: two separate markers, one for each transition.
+   *
+   * @param version - The version the row currently holds in the DB
+   *
+   * @example
+   * ```ts
+   * static reconstitute(id: OrderId, state: OrderState, version: Version): Order {
+   *   const order = new Order(id, state);
+   *   order.markRestored(version);
+   *   return order;
+   * }
+   * ```
+   */
+  markRestored(version) {
+    this.setVersion(version);
+    this._persistedVersion = version;
+  }
   /**
    * **Framework lifecycle method — `@sealed`.** Called by `withCommit`
    * (or by your own orchestration code, after harvesting `pendingEvents`)
@@ -639,7 +687,7 @@ var AggregateRoot = class extends Entity {
    * @see onPersisted — the safe extension point for subclasses
    */
   markPersisted(version) {
-    this.setVersion(version);
+    this.markRestored(version);
     this._pendingEvents = [];
     this.onPersisted(version);
   }
@@ -675,6 +723,83 @@ var AggregateRoot = class extends Entity {
    */
   onPersisted(_version) {
   }
+  /**
+   * Appends a domain event to the pending list. Prefer the higher-level
+   * `AggregateRoot.commit()` (state-stored) or `EventSourcedAggregate.apply()`
+   * (event-sourced) call sites — both wrap `addDomainEvent` in the
+   * canonical record-AFTER-mutation order (Vernon §8). Calling
+   * `addDomainEvent` directly is appropriate only when state and event
+   * recording have already been decoupled deliberately (e.g. a
+   * deletion event before a hard-delete; see `docs/guide/repository.md`).
+   */
+  addDomainEvent(event) {
+    this._pendingEvents.push(event);
+  }
+  /**
+   * Creates a snapshot of the current aggregate state — the state at
+   * this moment plus the version. Useful for ES snapshot policies and
+   * for state-stored backup / restore.
+   */
+  createSnapshot() {
+    return {
+      state: structuredClone(this._state),
+      version: this.version,
+      snapshotAt: /* @__PURE__ */ new Date()
+    };
+  }
+  /**
+   * 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
+    });
+  }
+};
+
+// src/aggregate/aggregate-root.ts
+var AggregateRoot = class extends BaseAggregate {
+  static {
+    __name(this, "AggregateRoot");
+  }
+  _autoVersionBump;
+  constructor(id, initialState, config) {
+    super(id, initialState);
+    this._autoVersionBump = config?.autoVersionBump ?? false;
+  }
   /**
    * Mutates state and records the resulting domain events in the
    * **canonical record-after-mutation order**. Use this instead of calling
@@ -706,7 +831,7 @@ var AggregateRoot = class extends Entity {
    *   }
    *   this.commit(
    *     { ...this.state, status: "confirmed" },
-   *     { type: "OrderConfirmed", orderId: this.id },
+   *     this.recordEvent("OrderConfirmed", { orderId: this.id }),
    *   );
    * }
    * ```
@@ -726,59 +851,9 @@ var AggregateRoot = class extends Entity {
       this.addDomainEvent(ev);
     }
   }
-  constructor(id, initialState, config) {
-    super(id, initialState);
-    this._config = config ?? {};
-    this._autoVersionBump = this._config.autoVersionBump ?? false;
-  }
-  /**
-   * Records a domain event for later publication.
-   *
-   * **Ordering: record AFTER state mutation.** Vernon (IDDD §8) is
-   * explicit: a domain event describes something that has just happened
-   * to the aggregate — its existence implies the state change already
-   * occurred. Concretely:
-   *
-   * ```ts
-   * confirm(): void {
-   *   if (this.state.status === "confirmed") {
-   *     throw new OrderAlreadyConfirmedError(this.id);
-   *   }
-   *   this.setState({ ...this.state, status: "confirmed" }, true);
-   *   this.addDomainEvent({ type: "OrderConfirmed", orderId: this.id });
-   *   // ↑ post-mutation. The event represents the committed fact.
-   * }
-   * ```
-   *
-   * Recording before mutation is a footgun: if a subsequent invariant
-   * check throws, the event has already been queued but the state never
-   * actually changed — consumers see an event for a fact that did not
-   * happen.
-   *
-   * `EventSourcedAggregate.apply()` enforces this ordering structurally;
-   * `AggregateRoot` leaves it as a convention because the state-mutation
-   * path (`setState`) is decoupled from event recording.
-   *
-   * @param event - The domain event to record
-   */
-  addDomainEvent(event) {
-    this._pendingEvents.push(event);
-  }
-  /**
-   * Manually bumps the aggregate version.
-   * Call this after state changes for Optimistic Concurrency Control.
-   *
-   * If `autoVersionBump` is enabled, this is called automatically
-   * when using `setState()`.
-   */
-  bumpVersion() {
-    this.setVersion(this._version + 1);
-  }
   /**
    * Sets the state and optionally bumps the version automatically.
-   * This is a convenience method for state mutations.
-   * Automatically validates the newState using `validateState()`.
-   * Overrides Entity.setState to add version bumping.
+   * Validates `newState` via `validateState()`.
    *
    * @param newState - The new state
    * @param bumpVersion - Whether to bump the version (defaults to autoVersionBump config)
@@ -791,43 +866,17 @@ var AggregateRoot = class extends Entity {
     }
   }
   /**
-   * Creates a snapshot of the current aggregate state.
-   * Useful for performance optimization, backup/restore, and audit trails.
-   *
-   * @returns A snapshot containing the current state and version
-   *
-   * @example
-   * ```typescript
-   * const snapshot = aggregate.createSnapshot();
-   * await snapshotRepository.save(aggregate.id, snapshot);
-   * ```
-   */
-  createSnapshot() {
-    return {
-      state: structuredClone(this._state),
-      version: this.version,
-      snapshotAt: /* @__PURE__ */ new Date()
-    };
-  }
-  /**
-   * Restores the aggregate from a snapshot.
-   * This is useful for loading aggregates from snapshots instead of
-   * rebuilding them from scratch.
-   * Validates the restored state.
+   * Restores the aggregate from a snapshot — loads state and aligns
+   * `version` + `persistedVersion` to the snapshot version. Validates
+   * the restored state.
    *
    * @param snapshot - The snapshot to restore from
-   *
-   * @example
-   * ```typescript
-   * const snapshot = await snapshotRepository.getLatest(aggregateId);
-   * aggregate.restoreFromSnapshot(snapshot);
-   * ```
    */
   restoreFromSnapshot(snapshot) {
     const cloned = structuredClone(snapshot.state);
     this.validateState(cloned);
     this._state = freezeShallow(cloned);
-    this.setVersion(snapshot.version);
+    this.markRestored(snapshot.version);
   }
 };
 var DomainError = class extends BaseError {
@@ -888,87 +937,10 @@ var ConcurrencyConflictError = class extends InfrastructureError {
 };
 
 // src/aggregate/event-sourced-aggregate.ts
-var EventSourcedAggregate = class extends Entity {
+var EventSourcedAggregate = class extends BaseAggregate {
   static {
     __name(this, "EventSourcedAggregate");
   }
-  // --- Version management (own, not inherited from AggregateRoot) ---
-  _version = 0;
-  get version() {
-    return this._version;
-  }
-  setVersion(version) {
-    this._version = version;
-  }
-  // --- Event tracking ---
-  _pendingEvents = [];
-  get pendingEvents() {
-    return Object.freeze(this._pendingEvents.slice());
-  }
-  clearPendingEvents() {
-    this._pendingEvents = [];
-  }
-  /**
-   * **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);
-  }
-  // --- Event application ---
   /**
    * Validates an event before it is applied. Default is no-op.
    * Subclasses override to throw a concrete `DomainError` subclass when
@@ -1013,11 +985,10 @@ var EventSourcedAggregate = class extends Entity {
     const nextState = handler(this._state, event);
     this._state = freezeShallow(nextState);
     if (isNew) {
-      this._pendingEvents.push(event);
-      this.setVersion(this._version + 1);
+      this.addDomainEvent(event);
+      this.bumpVersion();
     }
   }
-  // --- History & Snapshots ---
   /**
    * Reconstitutes the aggregate from an event history. Catches `DomainError`
    * thrown during replay and returns it as an `Err` — this is the
@@ -1030,7 +1001,7 @@ var EventSourcedAggregate = class extends Entity {
    * 2 events ends at v=3, not v=2.
    */
   loadFromHistory(history) {
-    const startVersion = this._version;
+    const startVersion = this.version;
     for (const event of history) {
       try {
         this.dispatchAndCommit(event, false);
@@ -1039,19 +1010,9 @@ var EventSourcedAggregate = class extends Entity {
         throw e;
       }
     }
-    this.setVersion(startVersion + history.length);
+    this.markRestored(startVersion + history.length);
     return ok();
   }
-  /**
-   * Creates a snapshot of the current aggregate state.
-   */
-  createSnapshot() {
-    return {
-      state: structuredClone(this._state),
-      version: this._version,
-      snapshotAt: /* @__PURE__ */ new Date()
-    };
-  }
   /**
    * Restores the aggregate from a snapshot and applies events that occurred
    * after. Same infrastructure-boundary semantics as `loadFromHistory`:
@@ -1064,7 +1025,7 @@ var EventSourcedAggregate = class extends Entity {
    */
   restoreFromSnapshotWithEvents(snapshot, eventsAfterSnapshot) {
     const previousState = this._state;
-    const previousVersion = this._version;
+    const previousVersion = this.version;
     this._state = freezeShallow(structuredClone(snapshot.state));
     this.setVersion(snapshot.version);
     for (const event of eventsAfterSnapshot) {
@@ -1077,7 +1038,9 @@ var EventSourcedAggregate = class extends Entity {
         throw e;
       }
     }
-    this.setVersion(snapshot.version + eventsAfterSnapshot.length);
+    this.markRestored(
+      snapshot.version + eventsAfterSnapshot.length
+    );
     return ok();
   }
 };
@@ -1113,6 +1076,18 @@ async function withCommit(deps, fn) {
       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);
       }