@shirudo/ddd-kit 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -709,6 +709,14 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
      * Subclasses can mutate this directly or use helper methods.
      */
     protected _state: TState;
+    /**
+     * **State ownership.** Plain-object and array states are shallow-copied
+     * before the freeze, so the caller's own object stays mutable. A CLASS
+     * INSTANCE passed as state is an ownership transfer: it is frozen
+     * in place (a copy would strip its prototype) — do not keep mutating
+     * the instance after handing it to the entity. The same contract
+     * applies to {@link setState}.
+     */
     protected constructor(id: TId, initialState: TState);
     /**
      * Optional validation hook to ensure state invariants. Called during
@@ -737,6 +745,10 @@ declare abstract class Entity<TState, TId extends Id<string>> implements IEntity
      * This is a convenience method for state mutations.
      * Automatically validates the newState using `validateState()`.
      *
+     * Plain-object and array states are shallow-copied before the freeze
+     * (the caller's object stays mutable); a class-instance state is an
+     * ownership transfer and is frozen in place — see the constructor.
+     *
      * @param newState - The new state
      */
     protected setState(newState: TState): void;
@@ -917,8 +929,12 @@ declare function entityIds<TId extends Id<string>, T extends Identifiable<TId>>(
  * @template TEvent - The domain-event union. Defaults to `never` so
  *   aggregates without a declared event type cannot emit events
  *   (emitting any event becomes a compile error).
+ * @template TSnapshotState - The plain-data shape stored in snapshots.
+ *   Defaults to `TState` for plain-data states. Aggregates whose state
+ *   carries class-based child entities declare a plain DTO shape here
+ *   and override {@link toSnapshotState} / {@link fromSnapshotState}.
  */
-declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent extends AnyDomainEvent = never> extends Entity<TState, TId> implements IAggregateRoot<TId, TEvent> {
+declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent extends AnyDomainEvent = never, TSnapshotState = TState> extends Entity<TState, TId> implements IAggregateRoot<TId, TEvent> {
     /**
      * The aggregate's domain type as a string, used to populate
      * `aggregateType` on events recorded via {@link recordEvent}.
@@ -1028,6 +1044,12 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      * call `super.onPersisted(version)` — there is nothing in the parent
      * implementation to preserve.
      *
+     * **Observer contract: errors are swallowed.** `withCommit` invokes
+     * `markPersisted` after the transaction has committed; a throwing hook
+     * must neither abort the loop for peer aggregates nor make the
+     * committed write look failed, so `withCommit` catches and discards
+     * hook errors. Handle failures inside the hook if you need them.
+     *
      * **`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`
@@ -1063,8 +1085,35 @@ declare abstract class BaseAggregate<TState, TId extends Id<string>, TEvent exte
      * 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.
+     *
+     * The state is converted via {@link toSnapshotState}; the default
+     * requires plain, serialisable data and fails fast otherwise.
+     */
+    createSnapshot(): AggregateSnapshot<TSnapshotState>;
+    /**
+     * Converts live aggregate state into the plain-data shape stored in a
+     * snapshot. The default validates that the state graph is plain,
+     * serialisable data (no class instances, functions, Promise/WeakMap/
+     * WeakSet) and then `structuredClone`s it — class instances would
+     * silently lose their prototype here AND on every snapshot-store
+     * round-trip, so the default fails fast with the offending path
+     * instead of producing a snapshot that breaks on first method call
+     * after restore.
+     *
+     * Override this together with {@link fromSnapshotState} (and the
+     * `TSnapshotState` generic) when the state carries class-based child
+     * entities. The override owns isolation: return fresh objects, not
+     * references into live state.
+     */
+    protected toSnapshotState(state: TState): TSnapshotState;
+    /**
+     * Converts the plain-data snapshot shape back into live aggregate
+     * state. The default `structuredClone`s the stored state so the
+     * restored aggregate never aliases the snapshot object. Override
+     * together with {@link toSnapshotState} to reconstruct class-based
+     * child entities.
      */
-    createSnapshot(): AggregateSnapshot<TState>;
+    protected fromSnapshotState(stored: TSnapshotState): TState;
     /**
      * Sugar for `createDomainEvent` that auto-injects `aggregateId`
      * (from `this.id`) and `aggregateType` (from {@link aggregateType})
@@ -1162,7 +1211,7 @@ interface AggregateConfig {
  * }
  * ```
  */
-declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent extends AnyDomainEvent = never> extends BaseAggregate<TState, TId, TEvent> {
+declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent extends AnyDomainEvent = never, TSnapshotState = TState> extends BaseAggregate<TState, TId, TEvent, TSnapshotState> {
     private readonly _autoVersionBump;
     protected constructor(id: TId, initialState: TState, config?: AggregateConfig);
     /**
@@ -1225,7 +1274,7 @@ declare abstract class AggregateRoot<TState, TId extends Id<string>, TEvent exte
      *
      * @param snapshot - The snapshot to restore from
      */
-    restoreFromSnapshot(snapshot: AggregateSnapshot<TState>): void;
+    restoreFromSnapshot(snapshot: AggregateSnapshot<TSnapshotState>): void;
 }
 
 type Handler<TState, TEvent extends AnyDomainEvent> = (state: TState, event: TEvent) => TState;
@@ -1282,7 +1331,7 @@ type Handler<TState, TEvent extends AnyDomainEvent> = (state: TState, event: TEv
  * }
  * ```
  */
-declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEvent, TId extends Id<string>> extends BaseAggregate<TState, TId, TEvent> implements IEventSourcedAggregate<TId, TEvent> {
+declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEvent, TId extends Id<string>, TSnapshotState = TState> extends BaseAggregate<TState, TId, TEvent, TSnapshotState> implements IEventSourcedAggregate<TId, TEvent> {
     /**
      * Validates an event before it is applied. Default is no-op.
      * Subclasses override to throw a concrete `DomainError` subclass when
@@ -1324,6 +1373,12 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEve
      * infrastructure boundary, where event-stream corruption is an expected
      * recoverable failure. Unexpected (non-DomainError) throws propagate.
      *
+     * All-or-nothing: if any event mid-stream throws, the aggregate's state
+     * is rolled back to its pre-call value — same contract as
+     * `restoreFromSnapshotWithEvents`. Partial replay is never observable.
+     * (Version needs no rollback: replay dispatches with `isNew = false`,
+     * which never bumps it; only the final `markRestored` advances it.)
+     *
      * Version advances additively: the aggregate's pre-existing version plus
      * `history.length`. A fresh aggregate (v=0) loading 3 events ends at v=3;
      * an aggregate already at v=1 (e.g. after a creation event) loading
@@ -1340,7 +1395,7 @@ declare abstract class EventSourcedAggregate<TState, TEvent extends AnyDomainEve
      * aggregate is rolled back to its pre-call state + version. Partial
      * restoration is never observable to the caller.
      */
-    restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TState>, eventsAfterSnapshot: ReadonlyArray<TEvent>): Result<void, DomainError>;
+    restoreFromSnapshotWithEvents(snapshot: AggregateSnapshot<TSnapshotState>, eventsAfterSnapshot: ReadonlyArray<TEvent>): Result<void, DomainError>;
     /**
      * A map of event types to their corresponding handlers.
      * Subclasses MUST implement this property.
@@ -1838,6 +1893,16 @@ interface TransactionScope<TCtx> {
  * outbox still holds the events and an outbox-dispatcher will deliver
  * them (eventual consistency).
  *
+ * **A `bus.publish` failure never rejects `withCommit`.** Once the
+ * transaction has committed, the write succeeded — surfacing a subscriber
+ * failure as a rejection would hand the caller a use-case failure for a
+ * committed write (a typical caller retries, double-executing it). The
+ * in-process fast path is best-effort by design; the error is reported to
+ * the optional `onPublishError(error, events)` hook (wire it to your
+ * logger/metrics) and otherwise dropped — delivery is still guaranteed via
+ * the outbox. The hook is an observer: if it throws, its error is
+ * swallowed so the post-commit invariant holds.
+ *
  * If the transaction rolls back, `markPersisted` is **not** called — the
  * aggregate keeps its pending events, so the caller can retry or discard.
  *
@@ -1869,6 +1934,12 @@ declare function withCommit<Evt extends AnyDomainEvent, R, TCtx>(deps: {
     outbox: Outbox<Evt>;
     bus?: EventBus<Evt>;
     scope: TransactionScope<TCtx>;
+    /**
+     * Observer for post-commit `bus.publish` failures. Called with the
+     * error and the events that were published. Must not be relied on
+     * for delivery — the outbox dispatcher is the reliable path.
+     */
+    onPublishError?: (error: unknown, events: ReadonlyArray<Evt>) => void;
 }, fn: (ctx: TCtx) => Promise<{
     result: R;
     aggregates: ReadonlyArray<IAggregateRoot<Id<string>, Evt>>;
@@ -2348,15 +2419,32 @@ type VO<T> = Readonly<T>;
  * Note: `deepFreeze` mutates its argument in place — it sets `[[Frozen]]`
  * on the object you pass in. Callers that need to avoid touching the
  * input (e.g. `vo()`) should deep-clone first.
+ *
+ * Date/Map/Set keep internal-slot mutability under `Object.freeze`
+ * (`setTime`, `set`, `add`, … still work on frozen instances), so their
+ * mutator methods are shadowed with throwing own properties and Map/Set
+ * contents are frozen recursively. The shadows are non-enumerable —
+ * invisible to `Object.keys`, spread, `deepEqual`, and `structuredClone`.
+ *
+ * The shadowing is deny-by-enumeration: only the mutators known at
+ * release time are blocked. If the runtime grows a NEW mutator (e.g. the
+ * stage-3 `Map.prototype.getOrInsert` upsert proposal), it is not blocked
+ * until the list is updated — treat the mutator blocking as a guard rail,
+ * not a security boundary.
+ *
+ * Limitation: ArrayBuffer views (TypedArrays, DataView) are passed through
+ * unfrozen — the spec forbids freezing a view with elements, and freezing
+ * cannot protect the underlying buffer. Their contents remain mutable.
  */
 declare function deepFreeze<T>(obj: T, visited?: WeakSet<object>): Readonly<T>;
 /**
  * Creates a deeply immutable value object from the given data.
  *
- * The input is first deep-cloned with `structuredClone`, then the clone
- * is frozen — so calling `vo(input)` never freezes the caller's own
- * object graph as a side-effect. Mutating the input afterwards does not
- * bleed into the VO.
+ * The input is first deep-cloned, then the clone is frozen — so calling
+ * `vo(input)` never freezes the caller's own object graph as a
+ * side-effect. Mutating the input afterwards does not bleed into the VO.
+ * Symbol-keyed properties are preserved (matching `voEquals`); function
+ * values are rejected (Value Objects are data, not behaviour).
  *
  * @example
  * ```typescript
@@ -2441,6 +2529,11 @@ declare function voEqualsExcept<T>(a: VO<T>, b: VO<T>, options: DeepEqualExceptO
  * Creates a value object with optional validation.
  * Returns a Result type instead of throwing an error.
  *
+ * Note: the Result covers VALIDATION failures only. Non-data values in
+ * the input (functions, Promise/WeakMap/WeakSet) still throw a
+ * `TypeError` from `vo()` — they cannot occur in parsed JSON and signal
+ * a programming error, not a validation failure.
+ *
  * @param t - The data to convert into a value object
  * @param validate - Validation function that returns true if valid
  * @param errorMessage - Optional custom error message if validation fails
@@ -2505,7 +2598,9 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
     readonly props: Readonly<T>;
     /**
      * Creates a new ValueObject.
-     * The properties are deeply frozen to ensure immutability.
+     * The properties are deep-cloned (prototype-preserving) and then deeply
+     * frozen — the caller's own object graph is never frozen or mutated,
+     * and later mutation of the input does not bleed into the value object.
      *
      * @param props - The properties of the value object
      * @example