@shirudo/ddd-kit 1.0.0-rc.8 → 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);
   }
@@ -676,93 +724,28 @@ var AggregateRoot = class extends Entity {
   onPersisted(_version) {
   }
   /**
-   * Mutates state and records the resulting domain events in the
-   * **canonical record-after-mutation order**. Use this instead of calling
-   * `setState` + `addDomainEvent` separately and you cannot trip the
-   * "event for a fact that never happened" footgun.
-   *
-   * Order of operations:
-   *  1. `setState(newState, true)` — runs `validateState` first.
-   *     If it throws, the method propagates and **no event is recorded
-   *     and no version is bumped**.
-   *  2. Each event in `events` is appended via `addDomainEvent`.
-   *
-   * `commit()` **always bumps the version**, regardless of the aggregate's
-   * `autoVersionBump` config. Recording a domain event implies "something
-   * happened that the outside world cares about", and optimistic-
-   * concurrency callers must see a fresh version every time. The config
-   * still governs the un-coupled `setState` path. If you need to mutate
-   * state without bumping (e.g. cosmetic caches), call `setState(newState,
-   * false)` and skip `commit` entirely.
-   *
-   * `events` accepts a single event or an array. Omit it (or pass `[]`)
-   * for state-only mutations.
-   *
-   * @example
-   * ```ts
-   * confirm(): void {
-   *   if (this.state.status === "confirmed") {
-   *     throw new OrderAlreadyConfirmedError(this.id);
-   *   }
-   *   this.commit(
-   *     { ...this.state, status: "confirmed" },
-   *     { type: "OrderConfirmed", orderId: this.id },
-   *   );
-   * }
-   * ```
-   *
-   * `EventSourcedAggregate.apply()` enforces the same ordering
-   * structurally; `commit()` is the opt-in equivalent on `AggregateRoot`,
-   * where `setState` and `addDomainEvent` are otherwise decoupled and the
-   * ordering is convention-only.
-   *
-   * @param newState - The new state (validated by `validateState`)
-   * @param events - One event, an array of events, or none (default)
+   * 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`).
    */
-  commit(newState, events = []) {
-    this.setState(newState, true);
-    const list = Array.isArray(events) ? events : [events];
-    for (const ev of list) {
-      this.addDomainEvent(ev);
-    }
-  }
-  constructor(id, initialState, config) {
-    super(id, initialState);
-    this._config = config ?? {};
-    this._autoVersionBump = this._config.autoVersionBump ?? false;
+  addDomainEvent(event) {
+    this._pendingEvents.push(event);
   }
   /**
-   * 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
+   * 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.
    */
-  addDomainEvent(event) {
-    this._pendingEvents.push(event);
+  createSnapshot() {
+    return {
+      state: structuredClone(this._state),
+      version: this.version,
+      snapshotAt: /* @__PURE__ */ new Date()
+    };
   }
   /**
    * Sugar for `createDomainEvent` that auto-injects `aggregateId`
@@ -805,21 +788,72 @@ var AggregateRoot = class extends Entity {
       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;
+  }
   /**
-   * Manually bumps the aggregate version.
-   * Call this after state changes for Optimistic Concurrency Control.
+   * Mutates state and records the resulting domain events in the
+   * **canonical record-after-mutation order**. Use this instead of calling
+   * `setState` + `addDomainEvent` separately and you cannot trip the
+   * "event for a fact that never happened" footgun.
+   *
+   * Order of operations:
+   *  1. `setState(newState, true)` — runs `validateState` first.
+   *     If it throws, the method propagates and **no event is recorded
+   *     and no version is bumped**.
+   *  2. Each event in `events` is appended via `addDomainEvent`.
+   *
+   * `commit()` **always bumps the version**, regardless of the aggregate's
+   * `autoVersionBump` config. Recording a domain event implies "something
+   * happened that the outside world cares about", and optimistic-
+   * concurrency callers must see a fresh version every time. The config
+   * still governs the un-coupled `setState` path. If you need to mutate
+   * state without bumping (e.g. cosmetic caches), call `setState(newState,
+   * false)` and skip `commit` entirely.
+   *
+   * `events` accepts a single event or an array. Omit it (or pass `[]`)
+   * for state-only mutations.
+   *
+   * @example
+   * ```ts
+   * confirm(): void {
+   *   if (this.state.status === "confirmed") {
+   *     throw new OrderAlreadyConfirmedError(this.id);
+   *   }
+   *   this.commit(
+   *     { ...this.state, status: "confirmed" },
+   *     this.recordEvent("OrderConfirmed", { orderId: this.id }),
+   *   );
+   * }
+   * ```
    *
-   * If `autoVersionBump` is enabled, this is called automatically
-   * when using `setState()`.
+   * `EventSourcedAggregate.apply()` enforces the same ordering
+   * structurally; `commit()` is the opt-in equivalent on `AggregateRoot`,
+   * where `setState` and `addDomainEvent` are otherwise decoupled and the
+   * ordering is convention-only.
+   *
+   * @param newState - The new state (validated by `validateState`)
+   * @param events - One event, an array of events, or none (default)
    */
-  bumpVersion() {
-    this.setVersion(this._version + 1);
+  commit(newState, events = []) {
+    this.setState(newState, true);
+    const list = Array.isArray(events) ? events : [events];
+    for (const ev of list) {
+      this.addDomainEvent(ev);
+    }
   }
   /**
    * 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)
@@ -832,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 {
@@ -929,118 +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);
-  }
-  /**
-   * 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.
    * Subclasses override to throw a concrete `DomainError` subclass when
@@ -1085,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
@@ -1102,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);
@@ -1111,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`:
@@ -1136,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) {
@@ -1149,7 +1038,9 @@ var EventSourcedAggregate = class extends Entity {
         throw e;
       }
     }
-    this.setVersion(snapshot.version + eventsAfterSnapshot.length);
+    this.markRestored(
+      snapshot.version + eventsAfterSnapshot.length
+    );
     return ok();
   }
 };