@vytches/ddd-aggregates 0.31.0-alpha.0 → 0.31.0

package/LLMGUIDE.md

@@ -41,7 +41,8 @@ class Order extends AggregateRoot<string> {
 // Usage
 const order = Order.create('c-1', 500);
 const events = order.getDomainEvents(); // [{ eventName: 'OrderCreated', ... }]
-order.commit(); // clear pending events after saving
+order.getDomainEvents() === events; // true — same array reference until the next mutation
+order.commit(); // clear pending events after saving; getDomainEvents() now returns a new, empty array
 ```
 
 ## Key API
@@ -82,19 +83,19 @@ order.commit(); // clear pending events after saving
 
 ### `AggregateRoot` method reference
 
-| Method                                  | Description                                                               |
-| --------------------------------------- | ------------------------------------------------------------------------- |
-| `apply(eventType, payload?, metadata?)` | Record a domain event, increment version, call handler                    |
-| `loadFromHistory(events)`               | Replay historical events to restore state without accumulating new events |
-| `getDomainEvents()`                     | Return readonly array of uncommitted events since last `commit()`         |
-| `commit()`                              | Clear uncommitted events; call after persisting to storage                |
-| `hasChanges()`                          | `true` if there are uncommitted events                                    |
-| `getVersion()`                          | Current version after all applied events                                  |
-| `getInitialVersion()`                   | Version when last loaded from storage (for optimistic locking)            |
-| `addCapability(cap)`                    | Attach a capability; calls `cap.attach(this)`                             |
-| `getCapability(CapClass)`               | Retrieve capability by constructor, returns `undefined` if absent         |
-| `hasCapability(CapClass)`               | Type-safe capability presence check                                       |
-| `registerEventHandler(type, fn)`        | Protected; wire event name to state mutation function                     |
+| Method                                  | Description                                                                                                                                                                                                           |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apply(eventType, payload?, metadata?)` | Record a domain event, increment version, call handler                                                                                                                                                                |
+| `loadFromHistory(events)`               | Replay historical events to restore state without accumulating new events                                                                                                                                             |
+| `getDomainEvents()`                     | Return readonly, deep-frozen array of uncommitted events since last `commit()`. Same array reference on repeat calls — rebuilt only on the next mutation (`apply`/`commit`/`loadFromHistory`/`transformDomainEvents`) |
+| `commit()`                              | Clear uncommitted events; call after persisting to storage                                                                                                                                                            |
+| `hasChanges()`                          | `true` if there are uncommitted events                                                                                                                                                                                |
+| `getVersion()`                          | Current version after all applied events                                                                                                                                                                              |
+| `getInitialVersion()`                   | Version when last loaded from storage (for optimistic locking)                                                                                                                                                        |
+| `addCapability(cap)`                    | Attach a capability; calls `cap.attach(this)`                                                                                                                                                                         |
+| `getCapability(CapClass)`               | Retrieve capability by constructor, returns `undefined` if absent                                                                                                                                                     |
+| `hasCapability(CapClass)`               | Type-safe capability presence check                                                                                                                                                                                   |
+| `registerEventHandler(type, fn)`        | Protected; wire event name to state mutation function                                                                                                                                                                 |
 
 ## Patterns
 

package/dist/core/aggregate-root.d.ts

@@ -119,6 +119,20 @@ export declare class AggregateRoot<TId = string> implements IAggregateRoot<TId>
     private _version;
     private _initialVersion;
     private _domainEvents;
+    /**
+     * VP-012b (D2, F15/F5): memoized, deep-frozen view returned by
+     * {@link getDomainEvents}. Rebuilt lazily on next read only when
+     * `_domainEventsCacheDirty` is true — see `_invalidateDomainEventsCache()`.
+     */
+    private _domainEventsCache;
+    /**
+     * VP-012b (D2): dirty flag for `_domainEventsCache`. Set true by
+     * `_invalidateDomainEventsCache()`, the single helper called from every
+     * site that mutates `_domainEvents` (apply, commit, transformDomainEvents,
+     * loadFromHistory, _internal_setState). Starts true so the first
+     * `getDomainEvents()` call always builds the cache.
+     */
+    private _domainEventsCacheDirty;
     private _eventHandlers;
     private _capabilities;
     /**
@@ -191,13 +205,78 @@ export declare class AggregateRoot<TId = string> implements IAggregateRoot<TId>
      * data) inside it could still be mutated in place, silently corrupting
      * state shared with `_domainEvents` (the same object references are
      * stored internally — events are never re-cloned after creation).
+     *
+     * VP-012b (D2, BREAKING behavior change, non-breaking signature): the
+     * returned array reference is now **stable between calls** — the same
+     * frozen array object is returned on every call until the next mutation
+     * (`apply()`, `commit()`, `loadFromHistory()`, or
+     * `transformDomainEvents()`), instead of a fresh array being built on
+     * every call as before. Content equality (`toEqual`) is unaffected either
+     * way. Code that relies on *identity* — e.g. asserting `not.toBe`/`!==`
+     * between two `getDomainEvents()` calls to prove "each call returns a new
+     * array" — will observe the new stable-reference behavior and must be
+     * updated; asserting `.toBe`/`===` between two calls made with no
+     * intervening mutation now holds, where it previously did not. This is
+     * safe to alias: the returned array and its contents are frozen, so
+     * holding onto the reference across a mutation still reflects the state
+     * as of the call that produced it (the cache is not that same array
+     * anymore after invalidation — a stored old reference is simply stale
+     * data, never mutated out from under the caller).
      * @returns {ReadonlyArray<IDomainEvent>} Array of uncommitted domain events
      */
     getDomainEvents(): ReadonlyArray<IDomainEvent>;
+    /**
+     * VP-012b (D2): single invalidation point for `_domainEventsCache`,
+     * called from every site that mutates `_domainEvents` — `apply()`,
+     * `commit()`, `transformDomainEvents()`, `loadFromHistory()`, and
+     * `_internal_setState()`. Keeping invalidation in one helper (rather than
+     * setting the flag ad hoc at each call site) means a future mutation site
+     * cannot silently forget to invalidate.
+     */
+    private _invalidateDomainEventsCache;
     /**
      * Clear all uncommitted domain events and update initial version
      */
     commit(): void;
+    /**
+     * Rewrite the payload and/or metadata of the uncommitted domain events.
+     *
+     * This is an infrastructure boundary API, in the same family as `commit()`:
+     * call it from a repository immediately before persisting, never from the
+     * domain or application layer. An aggregate records events through `apply()`;
+     * it does not rewrite its own history.
+     *
+     * It exists for data that only the persistence boundary knows — a
+     * crypto-shredding key id resolved at save time, a correlation id assigned at
+     * dispatch, an encrypted payload. Doing this by hand from outside is not
+     * possible: `getDomainEvents()` deep-freezes what it returns, and the
+     * internal list is private. The transformation has to land here rather than
+     * on a local copy inside `save()`, because the event dispatcher reads the
+     * aggregate's events again — a local copy would leave the in-process event
+     * bus publishing the untransformed originals.
+     *
+     * Only `payload` and `metadata` can be replaced. `eventName`, identity, and
+     * the number and order of events are fixed: changing those would desync
+     * handlers on replay or break the version invariant. Return nothing to leave
+     * an event as it is.
+     *
+     * Identity, prototype and `instanceof` survive, and the event's constructor
+     * is never called, so event classes with their own constructor arguments are
+     * safe.
+     *
+     * @example
+     * // inside a repository's save(), before persisting:
+     * order.transformDomainEvents(event => ({
+     *   payload: encrypt(event.payload, key),
+     *   metadata: { userSpecificKeyId: key.id },
+     * }));
+     *
+     * @param transform - Called per event; returns the parts to replace, or nothing to keep it
+     */
+    transformDomainEvents<P = unknown>(transform: (event: Readonly<IDomainEvent<P>>, index: number) => {
+        payload?: P;
+        metadata?: Partial<IEventMetadata>;
+    } | void): void;
     /**
      * @param {string} eventType - Event type to register handler for
      * @param {IAggregateEventHandler<T>} handler - Event handler function

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("@vytches/ddd-contracts"),S=require("@vytches/ddd-contracts/internal"),h=require("@vytches/ddd-utils"),o=require("@vytches/ddd-domain-primitives");class p extends u.Capability{constructor(){super(...arguments),this.type="versioning",this.upcasters=new Map}static get capabilityType(){return"versioning"}attach(t){this.aggregate=t}detach(){this.aggregate=void 0,this.upcasters.clear()}registerUpcaster(t,e,i){this.upcasters.has(t)||this.upcasters.set(t,new Map),this.upcasters.get(t).set(e,i)}handleVersionedEvent(t,e){const i=t.metadata?.version||1,a=t.metadata?.targetVersion||i;let n=t;if(i<a&&this.upcasters.has(t.eventName)){const l=this.upcasters.get(t.eventName);for(let c=i;c<a;c++){const E=l.get(c);if(!E){S.internalLogger.warn("VersioningCapability: Missing upcaster for event version — event will be processed without upcast",{eventName:t.eventName,fromVersion:c,toVersion:c+1});continue}const I=E.upcast(n.payload,n.metadata);n={...n,payload:I,metadata:{...n.metadata,version:c+1}}}}const g=e.get(n.eventName);g&&g(n.payload,n.metadata)}getRegisteredEventTypes(){return Array.from(this.upcasters.keys())}hasUpcaster(t,e){return this.upcasters.get(t)?.has(e)||!1}getUpcastersForType(t){return this.upcasters.get(t)}clearUpcastersForType(t){this.upcasters.delete(t)}getTotalUpcasterCount(){let t=0;for(const e of this.upcasters.values())t+=e.size;return t}}const w=Symbol("vytches-ddd-aggregate-internal-state");class d{constructor(t){this._version=0,this._initialVersion=0,this._domainEvents=[],this._eventHandlers=new Map,this._capabilities=new u.CapabilityRegistry,this._id=t.id,this._version=t.version||0,this._initialVersion=t.version||0,this._maxEvents=t.maxEvents,this._onMissingHandler=t.onMissingHandler??"warn"}getId(){return this._id}equals(t){return t==null?!1:t===this?!0:t instanceof d?this._id.equals(t._id):!1}getVersion(){return this._version}getInitialVersion(){return this._initialVersion}hasChanges(){return this._domainEvents.length>0}getDomainEvents(){const t=this._domainEvents.map(e=>h.LibUtils.deepFreeze(e));return Object.freeze(t)}commit(){this._domainEvents=[],this._initialVersion=this._version}registerEventHandler(t,e){return this._eventHandlers.set(t,e),this}apply(t,e,i){if(this._maxEvents!==void 0&&this._domainEvents.length>=this._maxEvents)throw new Error(`Aggregate ${this.constructor.name} (id=${this._id.toString()}) exceeded maxEvents limit of ${this._maxEvents}. This usually indicates a runaway loop or replay of a corrupted event stream. Increase maxEvents in the aggregate constructor params if the limit is too restrictive for your domain.`);const a=this._version+1;let n,g;typeof t=="string"?(n=u.createDomainEvent(t,e,i),g=n.metadata):(n=t,g=i?{...n.metadata,...i}:n.metadata);const l=d.sanitizeMetadata({...g,aggregateId:this._id.toString(),aggregateType:this.constructor.name,aggregateVersion:a,timestamp:g?.timestamp??new Date}),c=Object.assign(Object.create(Object.getPrototypeOf(n)),n,{metadata:l});this._version=a,this._domainEvents.push(c),this.handleEvent(c)}handleEvent(t){const e=this.getCapability(p);if(e)e.handleVersionedEvent(t,this._eventHandlers);else{const i=this._eventHandlers.get(t.eventName);i?i(t.payload,t.metadata):this.reportMissingHandler(t.eventName)}}reportMissingHandler(t){const e=`Aggregate ${this.constructor.name} (id=${this._id.toString()}) has no registered handler for event "${t}". State will not be updated for this event. Register a handler via registerEventHandler('${t}', ...) before applying/replaying this event, or pass onMissingHandler: "warn" explicitly to silence this in the constructor params.`;if(this._onMissingHandler==="throw")throw new Error(e);S.internalLogger.warn(e,{aggregateType:this.constructor.name,aggregateId:this._id.toString(),eventName:t})}loadFromHistory(t){this._version=this._initialVersion,this._domainEvents=[];for(const e of t)this.handleEvent(e),this._version++;this._initialVersion=this._version}addCapability(t){return"attach"in t&&typeof t.attach=="function"&&t.attach(this),this._capabilities.register(t),this}getCapability(t){return this._capabilities.get(t)}hasCapability(t){return this._capabilities.has(t)}removeCapability(t){const e=this._capabilities.get(t);return e&&"detach"in e&&typeof e.detach=="function"&&e.detach(),this._capabilities.remove(t),this}getAllCapabilities(){return this._capabilities.getAll()}getCapabilityTypes(){return this._capabilities.getTypes()}static sanitizeMetadata(t){if(!Object.prototype.hasOwnProperty.call(t,"__proto__")&&!Object.prototype.hasOwnProperty.call(t,"constructor")&&!Object.prototype.hasOwnProperty.call(t,"prototype"))return t;const e={};for(const i of Object.keys(t))i==="__proto__"||i==="constructor"||i==="prototype"||(e[i]=t[i]);return e}_internal_setState(t,e){if(t!==w)throw new TypeError("_internal_setState: invalid or missing internal state token. This method is restricted to capabilities within @vytches/ddd-aggregates.");this._version=e.version,this._initialVersion=e.initialVersion,this._domainEvents=[...e.domainEvents]}}class m extends u.Capability{constructor(){super(...arguments),this.type="audit",this.auditLog=[]}static get capabilityType(){return"audit"}attach(t){this.aggregate=t;const e=this.aggregate;typeof e.apply=="function"&&(this.originalApply=e.apply,this.originalApply&&(this.aggregate.apply=(...i)=>{const a=this.originalApply.call(this.aggregate,...i);return this.recordAuditEvent(),a}))}detach(){this.aggregate&&this.originalApply&&(this.aggregate.apply=this.originalApply),this.aggregate=void 0,this.auditLog=[],this.originalApply=void 0}getAuditLog(){return[...this.auditLog]}clearAuditLog(){this.auditLog=[]}getAuditStatistics(){const t={};let e=0;this.auditLog.forEach((a,n)=>{if(t[a.eventName]=(t[a.eventName]||0)+1,n>0){const g=this.auditLog[n-1];if(g){const l=new Date(g.timestamp).getTime(),c=new Date(a.timestamp).getTime();e+=c-l}}});const i=this.auditLog.length>1?e/(this.auditLog.length-1):0;return{totalEvents:this.auditLog.length,eventsByType:t,averageTimeBetweenEvents:i}}recordAuditEvent(){const t=this.aggregate.getDomainEvents(),e=t[t.length-1];e&&this.recordEvent(e)}recordEvent(t){const e={eventId:t.metadata?.eventId||`audit-${h.LibUtils.getUUID()}`,eventName:t.eventName,aggregateId:this.aggregate.getId().toString(),aggregateType:this.aggregate.constructor.name,aggregateVersion:this.aggregate.getVersion(),timestamp:new Date,payload:t.payload,metadata:{...t.metadata,auditCapability:!0},actor:t.metadata?.userId};this.auditLog.push(e)}getEventsByName(t){return this.auditLog.filter(e=>e.eventName===t)}getEventsByTimeRange(t,e){return this.auditLog.filter(i=>{const a=new Date(i.timestamp).getTime();return a>=t.getTime()&&a<=e.getTime()})}getFirstEvent(){return this.auditLog[0]||null}getLastEvent(){return this.auditLog[this.auditLog.length-1]||null}}class r extends o.IDomainError{static invalidArguments(t,e){const i={code:o.DomainErrorCode.InvalidParameter,data:e};return new r(t,i)}static versionConflict(t,e,i,a){const n=`Version conflict: Aggregate ${t} with ID ${e} has version ${i}, but expected ${a}`,g={code:o.DomainErrorCode.ValidationFailed,data:{aggregateType:t,aggregateId:e,currentVersion:i,expectedVersion:a}};return new r(n,g)}static featureNotEnabled(t){const e=`Feature '${t}' is not enabled on aggregate`,i={code:o.DomainErrorCode.ValidationFailed,data:{feature:t}};return new r(e,i)}static methodNotImplemented(t,e){const i=`Method '${t}' must be implemented by ${e} to use this feature`,a={code:o.DomainErrorCode.MissingValue,data:{methodName:t,aggregateType:e}};return new r(i,a)}static invalidSnapshot(t,e){const i=`Invalid snapshot for aggregate ${t}${e?`: ${e}`:""}`,a={code:o.DomainErrorCode.InvalidFormat,data:{aggregateType:t,reason:e}};return new r(i,a)}static idMismatch(t,e){const i=`ID mismatch: Snapshot is for ID ${t}, but aggregate has ID ${e}`,a={code:o.DomainErrorCode.ValidationFailed,data:{snapshotId:t,aggregateId:e}};return new r(i,a)}static typeMismatch(t,e){const i=`Aggregate type mismatch: Snapshot is for type ${t}, but trying to load into ${e}`,a={code:o.DomainErrorCode.ValidationFailed,data:{snapshotType:t,aggregateType:e}};return new r(i,a)}static duplicateUpcaster(t,e){const i=`Upcaster for event ${t} version ${e} already exists`,a={code:o.DomainErrorCode.DuplicateEntry,data:{eventType:t,sourceVersion:e}};return new r(i,a)}static missingUpcaster(t,e,i){const a=`Missing upcaster for event ${t} from version ${e} to ${i}`,n={code:o.DomainErrorCode.MissingValue,data:{eventType:t,fromVersion:e,toVersion:i}};return new r(a,n)}static configurationError(t,e){const i=`Configuration error in ${t}: ${e}`,a={code:o.DomainErrorCode.ValidationFailed,data:{aggregateType:t,configurationError:e}};return new r(i,a)}static cannotInterceptApplyMethod(t,e){const i=`Cannot intercept apply method - method not found on aggregate ${t}`,a={code:o.DomainErrorCode.InternalError,data:{aggergateId:t,...e}};return new r(i,a)}static eventStoreNotConfigured(t){const e="Event store not configured",i={code:o.DomainErrorCode.MissingValue,data:t};return new r(e,i)}static aggregateDoesNotSupportReplay(t,e){const i=`Aggregate ${t} does not support event replay`,a={code:o.DomainErrorCode.MethodNotSupported,data:{aggregateType:t,...e}};return new r(i,a)}}class f extends u.Capability{constructor(){super(...arguments),this.type="eventSourcing",this.eventStore=null}static get capabilityType(){return"eventSourcing"}attach(t){this.aggregate=t}detach(){this.aggregate=void 0,this.eventStore=null}setEventStore(t){this.eventStore=t}getEventStore(){return this.eventStore}async loadFromEventStore(t){if(!this.eventStore)throw r.configurationError(this.aggregate.constructor.name,"Event store not configured");const e=await this.eventStore.getEvents(t);if(e.length===0)return;const i=this.aggregate;i.loadFromHistory&&i.loadFromHistory(e)}async saveToEventStore(){if(!this.eventStore)throw r.configurationError(this.aggregate.constructor.name,"Event store not configured");const t=this.aggregate.getDomainEvents();t.length!==0&&await this.eventStore.saveEvents(this.aggregate.getId().toString(),[...t],this.aggregate.getInitialVersion())}hasEventStore(){return this.eventStore!==null}getStreamName(){return`${this.aggregate.constructor.name}-${this.aggregate.getId().toString()}`}async loadFromVersion(t,e){if(!this.eventStore)throw r.configurationError(this.aggregate.constructor.name,"Event store not configured");const i=await this.eventStore.getEventsAfterVersion(t,e),a=this.aggregate;a.loadFromHistory&&i.length>0&&a.loadFromHistory(i)}}class y extends u.Capability{constructor(){super(...arguments),this.type="snapshot",this._snapshot=null}static get capabilityType(){return"snapshot"}attach(t){this.aggregate=t}detach(){this.aggregate=void 0,this._snapshot=null}createSnapshot(t,e){const i=this.aggregate.getDomainEvents(),n=(i.length>0?i[i.length-1]:null)?.metadata?.eventId,l={aggregateId:this.aggregate.getId().toString(),version:this.aggregate.getVersion(),aggregateType:this.aggregate.constructor.name,state:t(),timestamp:new Date,...n!==void 0&&{lastEventId:n}};return e&&(l.metadata=e()),l}restoreFromSnapshot(t,e,i){if(!t||!t.state)throw r.invalidSnapshot(this.aggregate.constructor.name,"Invalid snapshot");const a=this.aggregate.getId().toString();if(t.aggregateId!==a)throw r.idMismatch(t.aggregateId,a);if(t.aggregateType!==this.aggregate.constructor.name)throw r.typeMismatch(t.aggregateType,this.aggregate.constructor.name);e(t.state),t.metadata&&i&&i(t.metadata),this.aggregate._internal_setState(w,{version:t.version,initialVersion:t.version,domainEvents:[]})}saveTemporaryState(t){this._snapshot=this.createSnapshot(()=>t)}getLastSnapshotTimestamp(){return this._snapshot?.timestamp||null}saveSnapshot(t,e){this._snapshot=this.createSnapshot(t,e)}getPreviousState(){const t=this._snapshot;return this._snapshot=null,t}}class v{constructor(t){this.capabilities=[],this.params=t}static create(t){const e={id:t.id instanceof u.EntityId?t.id:new u.EntityId(t.id,"text"),version:t.version||0};return new v(e)}withSnapshots(){return this.capabilities.push({capability:new y}),this}withVersioning(){return this.capabilities.push({capability:new p}),this}withAudit(){return this.capabilities.push({capability:new m}),this}withEventSourcing(t){const e=new f;return this.capabilities.push({capability:e,configure:i=>{const a=i;t?a.setEventStore(t):this.eventStore&&a.setEventStore(this.eventStore)}}),this}withCapability(t,e){return this.capabilities.push({capability:t,configure:e?i=>e(i):void 0}),this}setEventStore(t){return this.eventStore=t,this}build(t){const e=t||d,i=new e(this.params);for(const{capability:a,configure:n}of this.capabilities)i.addCapability(a),n&&n(a);return i}buildWithAllCapabilities(t){return this.withSnapshots().withVersioning().withAudit().withEventSourcing().build(t)}}function D(s){return v.create(s)}class b{constructor(t){this._id=t}getId(){return this._id}equals(t){return t==null?!1:t===this?!0:t instanceof b?this._id.equals(t._id):!1}}function _(s){return s.hasCapability(y)}function C(s){return s.hasCapability(p)}function A(s){return s.hasCapability(m)}function V(s){return s.hasCapability(f)}function $(s){if(!_(s))throw r.featureNotEnabled("snapshot");return s}function M(s){return _(s)?h.Result.ok(s):h.Result.fail(r.featureNotEnabled("snapshot"))}function N(s){if(!C(s))throw r.featureNotEnabled("versioning");return s}function T(s){return C(s)?h.Result.ok(s):h.Result.fail(r.featureNotEnabled("versioning"))}function L(s){if(!A(s))throw r.featureNotEnabled("audit");return s}function F(s){return A(s)?h.Result.ok(s):h.Result.fail(r.featureNotEnabled("audit"))}function H(s){if(!V(s))throw r.featureNotEnabled("eventSourcing");return s}function x(s){return V(s)?h.Result.ok(s):h.Result.fail(r.featureNotEnabled("eventSourcing"))}function U(s){return s.getCapabilityTypes()}function R(s,t){return t.every(e=>s.hasCapability(e))}exports.AggregateBuilder=v;exports.AggregateError=r;exports.AggregateRoot=d;exports.AuditCapability=m;exports.Entity=b;exports.EventSourcingCapability=f;exports.SnapshotCapability=y;exports.VersioningCapability=p;exports.aggregateBuilder=D;exports.asAuditAggregate=L;exports.asEventSourcingAggregate=H;exports.asSnapshotAggregate=$;exports.asVersioningAggregate=N;exports.getAggregateCapabilities=U;exports.hasAllCapabilities=R;exports.tryAsAuditAggregate=F;exports.tryAsEventSourcingAggregate=x;exports.tryAsSnapshotAggregate=M;exports.tryAsVersioningAggregate=T;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("@vytches/ddd-contracts"),S=require("@vytches/ddd-contracts/internal"),h=require("@vytches/ddd-utils"),o=require("@vytches/ddd-domain-primitives");class p extends l.Capability{constructor(){super(...arguments),this.type="versioning",this.upcasters=new Map}static get capabilityType(){return"versioning"}attach(t){this.aggregate=t}detach(){this.aggregate=void 0,this.upcasters.clear()}registerUpcaster(t,e,i){this.upcasters.has(t)||this.upcasters.set(t,new Map),this.upcasters.get(t).set(e,i)}handleVersionedEvent(t,e){const i=t.metadata?.version||1,a=t.metadata?.targetVersion||i;let s=t;if(i<a&&this.upcasters.has(t.eventName)){const u=this.upcasters.get(t.eventName);for(let c=i;c<a;c++){const b=u.get(c);if(!b){S.internalLogger.warn("VersioningCapability: Missing upcaster for event version — event will be processed without upcast",{eventName:t.eventName,fromVersion:c,toVersion:c+1});continue}const V=b.upcast(s.payload,s.metadata);s={...s,payload:V,metadata:{...s.metadata,version:c+1}}}}const g=e.get(s.eventName);g&&g(s.payload,s.metadata)}getRegisteredEventTypes(){return Array.from(this.upcasters.keys())}hasUpcaster(t,e){return this.upcasters.get(t)?.has(e)||!1}getUpcastersForType(t){return this.upcasters.get(t)}clearUpcastersForType(t){this.upcasters.delete(t)}getTotalUpcasterCount(){let t=0;for(const e of this.upcasters.values())t+=e.size;return t}}const _=Symbol("vytches-ddd-aggregate-internal-state");class d{constructor(t){this._version=0,this._initialVersion=0,this._domainEvents=[],this._domainEventsCache=Object.freeze([]),this._domainEventsCacheDirty=!0,this._eventHandlers=new Map,this._capabilities=new l.CapabilityRegistry,this._id=t.id,this._version=t.version||0,this._initialVersion=t.version||0,this._maxEvents=t.maxEvents,this._onMissingHandler=t.onMissingHandler??"warn"}getId(){return this._id}equals(t){return t==null?!1:t===this?!0:t instanceof d?this._id.equals(t._id):!1}getVersion(){return this._version}getInitialVersion(){return this._initialVersion}hasChanges(){return this._domainEvents.length>0}getDomainEvents(){if(this._domainEventsCacheDirty){const t=new WeakSet,e=this._domainEvents.map(i=>h.LibUtils.deepFreeze(i,t));this._domainEventsCache=Object.freeze(e),this._domainEventsCacheDirty=!1}return this._domainEventsCache}_invalidateDomainEventsCache(){this._domainEventsCacheDirty=!0}commit(){this._domainEvents=[],this._initialVersion=this._version,this._invalidateDomainEventsCache()}transformDomainEvents(t){this._domainEvents=this._domainEvents.map((e,i)=>{const a=t(e,i);return a?l.enrichEvent(e,a):e}),this._invalidateDomainEventsCache()}registerEventHandler(t,e){return this._eventHandlers.set(t,e),this}apply(t,e,i){if(this._maxEvents!==void 0&&this._domainEvents.length>=this._maxEvents)throw new Error(`Aggregate ${this.constructor.name} (id=${this._id.toString()}) exceeded maxEvents limit of ${this._maxEvents}. This usually indicates a runaway loop or replay of a corrupted event stream. Increase maxEvents in the aggregate constructor params if the limit is too restrictive for your domain.`);const a=this._version+1;let s,g;typeof t=="string"?(s=l.createDomainEvent(t,e,i),g=s.metadata):(s=t,g=i?{...s.metadata,...i}:s.metadata);const u=d.sanitizeMetadata({...g,aggregateId:this._id.toString(),aggregateType:this.constructor.name,aggregateVersion:a,timestamp:g?.timestamp??new Date}),c=Object.assign(Object.create(Object.getPrototypeOf(s)),s,{metadata:u});this._version=a,this._domainEvents.push(c),this._invalidateDomainEventsCache(),this.handleEvent(c)}handleEvent(t){const e=this.getCapability(p);if(e)e.handleVersionedEvent(t,this._eventHandlers);else{const i=this._eventHandlers.get(t.eventName);i?i(t.payload,t.metadata):this.reportMissingHandler(t.eventName)}}reportMissingHandler(t){const e=`Aggregate ${this.constructor.name} (id=${this._id.toString()}) has no registered handler for event "${t}". State will not be updated for this event. Register a handler via registerEventHandler('${t}', ...) before applying/replaying this event, or pass onMissingHandler: "warn" explicitly to silence this in the constructor params.`;if(this._onMissingHandler==="throw")throw new Error(e);S.internalLogger.warn(e,{aggregateType:this.constructor.name,aggregateId:this._id.toString(),eventName:t})}loadFromHistory(t){this._version=this._initialVersion,this._domainEvents=[],this._invalidateDomainEventsCache();for(const e of t)this.handleEvent(e),this._version++;this._initialVersion=this._version}addCapability(t){return"attach"in t&&typeof t.attach=="function"&&t.attach(this),this._capabilities.register(t),this}getCapability(t){return this._capabilities.get(t)}hasCapability(t){return this._capabilities.has(t)}removeCapability(t){const e=this._capabilities.get(t);return e&&"detach"in e&&typeof e.detach=="function"&&e.detach(),this._capabilities.remove(t),this}getAllCapabilities(){return this._capabilities.getAll()}getCapabilityTypes(){return this._capabilities.getTypes()}static sanitizeMetadata(t){if(!Object.prototype.hasOwnProperty.call(t,"__proto__")&&!Object.prototype.hasOwnProperty.call(t,"constructor")&&!Object.prototype.hasOwnProperty.call(t,"prototype"))return t;const e={};for(const i of Object.keys(t))i==="__proto__"||i==="constructor"||i==="prototype"||(e[i]=t[i]);return e}_internal_setState(t,e){if(t!==_)throw new TypeError("_internal_setState: invalid or missing internal state token. This method is restricted to capabilities within @vytches/ddd-aggregates.");this._version=e.version,this._initialVersion=e.initialVersion,this._domainEvents=[...e.domainEvents],this._invalidateDomainEventsCache()}}class m extends l.Capability{constructor(){super(...arguments),this.type="audit",this.auditLog=[]}static get capabilityType(){return"audit"}attach(t){this.aggregate=t;const e=this.aggregate;typeof e.apply=="function"&&(this.originalApply=e.apply,this.originalApply&&(this.aggregate.apply=(...i)=>{const a=this.originalApply.call(this.aggregate,...i);return this.recordAuditEvent(),a}))}detach(){this.aggregate&&this.originalApply&&(this.aggregate.apply=this.originalApply),this.aggregate=void 0,this.auditLog=[],this.originalApply=void 0}getAuditLog(){return[...this.auditLog]}clearAuditLog(){this.auditLog=[]}getAuditStatistics(){const t={};let e=0;this.auditLog.forEach((a,s)=>{if(t[a.eventName]=(t[a.eventName]||0)+1,s>0){const g=this.auditLog[s-1];if(g){const u=new Date(g.timestamp).getTime(),c=new Date(a.timestamp).getTime();e+=c-u}}});const i=this.auditLog.length>1?e/(this.auditLog.length-1):0;return{totalEvents:this.auditLog.length,eventsByType:t,averageTimeBetweenEvents:i}}recordAuditEvent(){const t=this.aggregate.getDomainEvents(),e=t[t.length-1];e&&this.recordEvent(e)}recordEvent(t){const e={eventId:t.metadata?.eventId||`audit-${h.LibUtils.getUUID()}`,eventName:t.eventName,aggregateId:this.aggregate.getId().toString(),aggregateType:this.aggregate.constructor.name,aggregateVersion:this.aggregate.getVersion(),timestamp:new Date,payload:t.payload,metadata:{...t.metadata,auditCapability:!0},actor:t.metadata?.userId};this.auditLog.push(e)}getEventsByName(t){return this.auditLog.filter(e=>e.eventName===t)}getEventsByTimeRange(t,e){return this.auditLog.filter(i=>{const a=new Date(i.timestamp).getTime();return a>=t.getTime()&&a<=e.getTime()})}getFirstEvent(){return this.auditLog[0]||null}getLastEvent(){return this.auditLog[this.auditLog.length-1]||null}}class r extends o.IDomainError{static invalidArguments(t,e){const i={code:o.DomainErrorCode.InvalidParameter,data:e};return new r(t,i)}static versionConflict(t,e,i,a){const s=`Version conflict: Aggregate ${t} with ID ${e} has version ${i}, but expected ${a}`,g={code:o.DomainErrorCode.ValidationFailed,data:{aggregateType:t,aggregateId:e,currentVersion:i,expectedVersion:a}};return new r(s,g)}static featureNotEnabled(t){const e=`Feature '${t}' is not enabled on aggregate`,i={code:o.DomainErrorCode.ValidationFailed,data:{feature:t}};return new r(e,i)}static methodNotImplemented(t,e){const i=`Method '${t}' must be implemented by ${e} to use this feature`,a={code:o.DomainErrorCode.MissingValue,data:{methodName:t,aggregateType:e}};return new r(i,a)}static invalidSnapshot(t,e){const i=`Invalid snapshot for aggregate ${t}${e?`: ${e}`:""}`,a={code:o.DomainErrorCode.InvalidFormat,data:{aggregateType:t,reason:e}};return new r(i,a)}static idMismatch(t,e){const i=`ID mismatch: Snapshot is for ID ${t}, but aggregate has ID ${e}`,a={code:o.DomainErrorCode.ValidationFailed,data:{snapshotId:t,aggregateId:e}};return new r(i,a)}static typeMismatch(t,e){const i=`Aggregate type mismatch: Snapshot is for type ${t}, but trying to load into ${e}`,a={code:o.DomainErrorCode.ValidationFailed,data:{snapshotType:t,aggregateType:e}};return new r(i,a)}static duplicateUpcaster(t,e){const i=`Upcaster for event ${t} version ${e} already exists`,a={code:o.DomainErrorCode.DuplicateEntry,data:{eventType:t,sourceVersion:e}};return new r(i,a)}static missingUpcaster(t,e,i){const a=`Missing upcaster for event ${t} from version ${e} to ${i}`,s={code:o.DomainErrorCode.MissingValue,data:{eventType:t,fromVersion:e,toVersion:i}};return new r(a,s)}static configurationError(t,e){const i=`Configuration error in ${t}: ${e}`,a={code:o.DomainErrorCode.ValidationFailed,data:{aggregateType:t,configurationError:e}};return new r(i,a)}static cannotInterceptApplyMethod(t,e){const i=`Cannot intercept apply method - method not found on aggregate ${t}`,a={code:o.DomainErrorCode.InternalError,data:{aggergateId:t,...e}};return new r(i,a)}static eventStoreNotConfigured(t){const e="Event store not configured",i={code:o.DomainErrorCode.MissingValue,data:t};return new r(e,i)}static aggregateDoesNotSupportReplay(t,e){const i=`Aggregate ${t} does not support event replay`,a={code:o.DomainErrorCode.MethodNotSupported,data:{aggregateType:t,...e}};return new r(i,a)}}class f extends l.Capability{constructor(){super(...arguments),this.type="eventSourcing",this.eventStore=null}static get capabilityType(){return"eventSourcing"}attach(t){this.aggregate=t}detach(){this.aggregate=void 0,this.eventStore=null}setEventStore(t){this.eventStore=t}getEventStore(){return this.eventStore}async loadFromEventStore(t){if(!this.eventStore)throw r.configurationError(this.aggregate.constructor.name,"Event store not configured");const e=await this.eventStore.getEvents(t);if(e.length===0)return;const i=this.aggregate;i.loadFromHistory&&i.loadFromHistory(e)}async saveToEventStore(){if(!this.eventStore)throw r.configurationError(this.aggregate.constructor.name,"Event store not configured");const t=this.aggregate.getDomainEvents();t.length!==0&&await this.eventStore.saveEvents(this.aggregate.getId().toString(),[...t],this.aggregate.getInitialVersion())}hasEventStore(){return this.eventStore!==null}getStreamName(){return`${this.aggregate.constructor.name}-${this.aggregate.getId().toString()}`}async loadFromVersion(t,e){if(!this.eventStore)throw r.configurationError(this.aggregate.constructor.name,"Event store not configured");const i=await this.eventStore.getEventsAfterVersion(t,e),a=this.aggregate;a.loadFromHistory&&i.length>0&&a.loadFromHistory(i)}}class y extends l.Capability{constructor(){super(...arguments),this.type="snapshot",this._snapshot=null}static get capabilityType(){return"snapshot"}attach(t){this.aggregate=t}detach(){this.aggregate=void 0,this._snapshot=null}createSnapshot(t,e){const i=this.aggregate.getDomainEvents(),s=(i.length>0?i[i.length-1]:null)?.metadata?.eventId,u={aggregateId:this.aggregate.getId().toString(),version:this.aggregate.getVersion(),aggregateType:this.aggregate.constructor.name,state:t(),timestamp:new Date,...s!==void 0&&{lastEventId:s}};return e&&(u.metadata=e()),u}restoreFromSnapshot(t,e,i){if(!t||!t.state)throw r.invalidSnapshot(this.aggregate.constructor.name,"Invalid snapshot");const a=this.aggregate.getId().toString();if(t.aggregateId!==a)throw r.idMismatch(t.aggregateId,a);if(t.aggregateType!==this.aggregate.constructor.name)throw r.typeMismatch(t.aggregateType,this.aggregate.constructor.name);e(t.state),t.metadata&&i&&i(t.metadata),this.aggregate._internal_setState(_,{version:t.version,initialVersion:t.version,domainEvents:[]})}saveTemporaryState(t){this._snapshot=this.createSnapshot(()=>t)}getLastSnapshotTimestamp(){return this._snapshot?.timestamp||null}saveSnapshot(t,e){this._snapshot=this.createSnapshot(t,e)}getPreviousState(){const t=this._snapshot;return this._snapshot=null,t}}class v{constructor(t){this.capabilities=[],this.params=t}static create(t){const e={id:t.id instanceof l.EntityId?t.id:new l.EntityId(t.id,"text"),version:t.version||0};return new v(e)}withSnapshots(){return this.capabilities.push({capability:new y}),this}withVersioning(){return this.capabilities.push({capability:new p}),this}withAudit(){return this.capabilities.push({capability:new m}),this}withEventSourcing(t){const e=new f;return this.capabilities.push({capability:e,configure:i=>{const a=i;t?a.setEventStore(t):this.eventStore&&a.setEventStore(this.eventStore)}}),this}withCapability(t,e){return this.capabilities.push({capability:t,configure:e?i=>e(i):void 0}),this}setEventStore(t){return this.eventStore=t,this}build(t){const e=t||d,i=new e(this.params);for(const{capability:a,configure:s}of this.capabilities)i.addCapability(a),s&&s(a);return i}buildWithAllCapabilities(t){return this.withSnapshots().withVersioning().withAudit().withEventSourcing().build(t)}}function I(n){return v.create(n)}class E{constructor(t){this._id=t}getId(){return this._id}equals(t){return t==null?!1:t===this?!0:t instanceof E?this._id.equals(t._id):!1}}function w(n){return n.hasCapability(y)}function C(n){return n.hasCapability(p)}function A(n){return n.hasCapability(m)}function D(n){return n.hasCapability(f)}function $(n){if(!w(n))throw r.featureNotEnabled("snapshot");return n}function M(n){return w(n)?h.Result.ok(n):h.Result.fail(r.featureNotEnabled("snapshot"))}function N(n){if(!C(n))throw r.featureNotEnabled("versioning");return n}function T(n){return C(n)?h.Result.ok(n):h.Result.fail(r.featureNotEnabled("versioning"))}function L(n){if(!A(n))throw r.featureNotEnabled("audit");return n}function F(n){return A(n)?h.Result.ok(n):h.Result.fail(r.featureNotEnabled("audit"))}function H(n){if(!D(n))throw r.featureNotEnabled("eventSourcing");return n}function x(n){return D(n)?h.Result.ok(n):h.Result.fail(r.featureNotEnabled("eventSourcing"))}function U(n){return n.getCapabilityTypes()}function O(n,t){return t.every(e=>n.hasCapability(e))}exports.AggregateBuilder=v;exports.AggregateError=r;exports.AggregateRoot=d;exports.AuditCapability=m;exports.Entity=E;exports.EventSourcingCapability=f;exports.SnapshotCapability=y;exports.VersioningCapability=p;exports.aggregateBuilder=I;exports.asAuditAggregate=L;exports.asEventSourcingAggregate=H;exports.asSnapshotAggregate=$;exports.asVersioningAggregate=N;exports.getAggregateCapabilities=U;exports.hasAllCapabilities=O;exports.tryAsAuditAggregate=F;exports.tryAsEventSourcingAggregate=x;exports.tryAsSnapshotAggregate=M;exports.tryAsVersioningAggregate=T;

package/dist/index.js

@@ -1,7 +1,7 @@
-import { Capability as d, CapabilityRegistry as M, createDomainEvent as T, EntityId as f } from "@vytches/ddd-contracts";
+import { Capability as d, CapabilityRegistry as N, enrichEvent as M, createDomainEvent as T, EntityId as f } from "@vytches/ddd-contracts";
 import { internalLogger as y } from "@vytches/ddd-contracts/internal";
-import { LibUtils as b, Result as l } from "@vytches/ddd-utils";
-import { IDomainError as L, DomainErrorCode as g } from "@vytches/ddd-domain-primitives";
+import { LibUtils as E, Result as l } from "@vytches/ddd-utils";
+import { IDomainError as L, DomainErrorCode as c } from "@vytches/ddd-domain-primitives";
 class p extends d {
   constructor() {
     super(...arguments), this.type = "versioning", this.upcasters = /* @__PURE__ */ new Map();
@@ -44,36 +44,36 @@ class p extends d {
    * @param {Map<string, IAggregateEventHandler>} handlers - Map of event handlers
    */
   handleVersionedEvent(t, e) {
-    const i = t.metadata?.version || 1, s = t.metadata?.targetVersion || i;
-    let n = t;
-    if (i < s && this.upcasters.has(t.eventName)) {
-      const h = this.upcasters.get(t.eventName);
-      for (let c = i; c < s; c++) {
-        const m = h.get(c);
+    const i = t.metadata?.version || 1, a = t.metadata?.targetVersion || i;
+    let s = t;
+    if (i < a && this.upcasters.has(t.eventName)) {
+      const g = this.upcasters.get(t.eventName);
+      for (let h = i; h < a; h++) {
+        const m = g.get(h);
         if (!m) {
           y.warn(
             "VersioningCapability: Missing upcaster for event version — event will be processed without upcast",
             {
               eventName: t.eventName,
-              fromVersion: c,
-              toVersion: c + 1
+              fromVersion: h,
+              toVersion: h + 1
             }
           );
           continue;
         }
-        const N = m.upcast(n.payload, n.metadata);
-        n = {
-          ...n,
-          payload: N,
+        const D = m.upcast(s.payload, s.metadata);
+        s = {
+          ...s,
+          payload: D,
           metadata: {
-            ...n.metadata,
-            version: c + 1
+            ...s.metadata,
+            version: h + 1
           }
         };
       }
     }
-    const o = e.get(n.eventName);
-    o && o(n.payload, n.metadata);
+    const o = e.get(s.eventName);
+    o && o(s.payload, s.metadata);
   }
   /**
    * @returns {string[]} Array of event types that have registered upcasters
@@ -112,10 +112,10 @@ class p extends d {
     return t;
   }
 }
-const E = Symbol("vytches-ddd-aggregate-internal-state");
+const b = Symbol("vytches-ddd-aggregate-internal-state");
 class u {
   constructor(t) {
-    this._version = 0, this._initialVersion = 0, this._domainEvents = [], this._eventHandlers = /* @__PURE__ */ new Map(), this._capabilities = new M(), this._id = t.id, this._version = t.version || 0, this._initialVersion = t.version || 0, this._maxEvents = t.maxEvents, this._onMissingHandler = t.onMissingHandler ?? "warn";
+    this._version = 0, this._initialVersion = 0, this._domainEvents = [], this._domainEventsCache = Object.freeze([]), this._domainEventsCacheDirty = !0, this._eventHandlers = /* @__PURE__ */ new Map(), this._capabilities = new N(), this._id = t.id, this._version = t.version || 0, this._initialVersion = t.version || 0, this._maxEvents = t.maxEvents, this._onMissingHandler = t.onMissingHandler ?? "warn";
   }
   // ==========================================
   // CORE AGGREGATE FUNCTIONALITY
@@ -181,17 +181,89 @@ class u {
    * data) inside it could still be mutated in place, silently corrupting
    * state shared with `_domainEvents` (the same object references are
    * stored internally — events are never re-cloned after creation).
+   *
+   * VP-012b (D2, BREAKING behavior change, non-breaking signature): the
+   * returned array reference is now **stable between calls** — the same
+   * frozen array object is returned on every call until the next mutation
+   * (`apply()`, `commit()`, `loadFromHistory()`, or
+   * `transformDomainEvents()`), instead of a fresh array being built on
+   * every call as before. Content equality (`toEqual`) is unaffected either
+   * way. Code that relies on *identity* — e.g. asserting `not.toBe`/`!==`
+   * between two `getDomainEvents()` calls to prove "each call returns a new
+   * array" — will observe the new stable-reference behavior and must be
+   * updated; asserting `.toBe`/`===` between two calls made with no
+   * intervening mutation now holds, where it previously did not. This is
+   * safe to alias: the returned array and its contents are frozen, so
+   * holding onto the reference across a mutation still reflects the state
+   * as of the call that produced it (the cache is not that same array
+   * anymore after invalidation — a stored old reference is simply stale
+   * data, never mutated out from under the caller).
    * @returns {ReadonlyArray<IDomainEvent>} Array of uncommitted domain events
    */
   getDomainEvents() {
-    const t = this._domainEvents.map((e) => b.deepFreeze(e));
-    return Object.freeze(t);
+    if (this._domainEventsCacheDirty) {
+      const t = /* @__PURE__ */ new WeakSet(), e = this._domainEvents.map((i) => E.deepFreeze(i, t));
+      this._domainEventsCache = Object.freeze(e), this._domainEventsCacheDirty = !1;
+    }
+    return this._domainEventsCache;
+  }
+  /**
+   * VP-012b (D2): single invalidation point for `_domainEventsCache`,
+   * called from every site that mutates `_domainEvents` — `apply()`,
+   * `commit()`, `transformDomainEvents()`, `loadFromHistory()`, and
+   * `_internal_setState()`. Keeping invalidation in one helper (rather than
+   * setting the flag ad hoc at each call site) means a future mutation site
+   * cannot silently forget to invalidate.
+   */
+  _invalidateDomainEventsCache() {
+    this._domainEventsCacheDirty = !0;
   }
   /**
    * Clear all uncommitted domain events and update initial version
    */
   commit() {
-    this._domainEvents = [], this._initialVersion = this._version;
+    this._domainEvents = [], this._initialVersion = this._version, this._invalidateDomainEventsCache();
+  }
+  /**
+   * Rewrite the payload and/or metadata of the uncommitted domain events.
+   *
+   * This is an infrastructure boundary API, in the same family as `commit()`:
+   * call it from a repository immediately before persisting, never from the
+   * domain or application layer. An aggregate records events through `apply()`;
+   * it does not rewrite its own history.
+   *
+   * It exists for data that only the persistence boundary knows — a
+   * crypto-shredding key id resolved at save time, a correlation id assigned at
+   * dispatch, an encrypted payload. Doing this by hand from outside is not
+   * possible: `getDomainEvents()` deep-freezes what it returns, and the
+   * internal list is private. The transformation has to land here rather than
+   * on a local copy inside `save()`, because the event dispatcher reads the
+   * aggregate's events again — a local copy would leave the in-process event
+   * bus publishing the untransformed originals.
+   *
+   * Only `payload` and `metadata` can be replaced. `eventName`, identity, and
+   * the number and order of events are fixed: changing those would desync
+   * handlers on replay or break the version invariant. Return nothing to leave
+   * an event as it is.
+   *
+   * Identity, prototype and `instanceof` survive, and the event's constructor
+   * is never called, so event classes with their own constructor arguments are
+   * safe.
+   *
+   * @example
+   * // inside a repository's save(), before persisting:
+   * order.transformDomainEvents(event => ({
+   *   payload: encrypt(event.payload, key),
+   *   metadata: { userSpecificKeyId: key.id },
+   * }));
+   *
+   * @param transform - Called per event; returns the parts to replace, or nothing to keep it
+   */
+  transformDomainEvents(t) {
+    this._domainEvents = this._domainEvents.map((e, i) => {
+      const a = t(e, i);
+      return a ? M(e, a) : e;
+    }), this._invalidateDomainEventsCache();
   }
   // ==========================================
   // EVENT HANDLING - Type-safe approach
@@ -228,21 +300,21 @@ class u {
       throw new Error(
         `Aggregate ${this.constructor.name} (id=${this._id.toString()}) exceeded maxEvents limit of ${this._maxEvents}. This usually indicates a runaway loop or replay of a corrupted event stream. Increase maxEvents in the aggregate constructor params if the limit is too restrictive for your domain.`
       );
-    const s = this._version + 1;
-    let n, o;
-    typeof t == "string" ? (n = T(t, e, i), o = n.metadata) : (n = t, o = i ? { ...n.metadata, ...i } : n.metadata);
-    const h = u.sanitizeMetadata({
+    const a = this._version + 1;
+    let s, o;
+    typeof t == "string" ? (s = T(t, e, i), o = s.metadata) : (s = t, o = i ? { ...s.metadata, ...i } : s.metadata);
+    const g = u.sanitizeMetadata({
       ...o,
       aggregateId: this._id.toString(),
       aggregateType: this.constructor.name,
-      aggregateVersion: s,
+      aggregateVersion: a,
       timestamp: o?.timestamp ?? /* @__PURE__ */ new Date()
-    }), c = Object.assign(
-      Object.create(Object.getPrototypeOf(n)),
-      n,
-      { metadata: h }
+    }), h = Object.assign(
+      Object.create(Object.getPrototypeOf(s)),
+      s,
+      { metadata: g }
     );
-    this._version = s, this._domainEvents.push(c), this.handleEvent(c);
+    this._version = a, this._domainEvents.push(h), this._invalidateDomainEventsCache(), this.handleEvent(h);
   }
   handleEvent(t) {
     const e = this.getCapability(p);
@@ -273,7 +345,7 @@ class u {
    * @param {IDomainEvent[]} events - Array of events to replay for state reconstruction
    */
   loadFromHistory(t) {
-    this._version = this._initialVersion, this._domainEvents = [];
+    this._version = this._initialVersion, this._domainEvents = [], this._invalidateDomainEventsCache();
     for (const e of t)
       this.handleEvent(e), this._version++;
     this._initialVersion = this._version;
@@ -352,14 +424,14 @@ class u {
    * @throws {TypeError} if `token` does not match {@link INTERNAL_STATE_TOKEN}
    */
   _internal_setState(t, e) {
-    if (t !== E)
+    if (t !== b)
       throw new TypeError(
         "_internal_setState: invalid or missing internal state token. This method is restricted to capabilities within @vytches/ddd-aggregates."
       );
-    this._version = e.version, this._initialVersion = e.initialVersion, this._domainEvents = [...e.domainEvents];
+    this._version = e.version, this._initialVersion = e.initialVersion, this._domainEvents = [...e.domainEvents], this._invalidateDomainEventsCache();
   }
 }
-class w extends d {
+class _ extends d {
   constructor() {
     super(...arguments), this.type = "audit", this.auditLog = [];
   }
@@ -373,8 +445,8 @@ class w extends d {
     this.aggregate = t;
     const e = this.aggregate;
     typeof e.apply == "function" && (this.originalApply = e.apply, this.originalApply && (this.aggregate.apply = (...i) => {
-      const s = this.originalApply.call(this.aggregate, ...i);
-      return this.recordAuditEvent(), s;
+      const a = this.originalApply.call(this.aggregate, ...i);
+      return this.recordAuditEvent(), a;
     }));
   }
   detach() {
@@ -395,12 +467,12 @@ class w extends d {
   getAuditStatistics() {
     const t = {};
     let e = 0;
-    this.auditLog.forEach((s, n) => {
-      if (t[s.eventName] = (t[s.eventName] || 0) + 1, n > 0) {
-        const o = this.auditLog[n - 1];
+    this.auditLog.forEach((a, s) => {
+      if (t[a.eventName] = (t[a.eventName] || 0) + 1, s > 0) {
+        const o = this.auditLog[s - 1];
         if (o) {
-          const h = new Date(o.timestamp).getTime(), c = new Date(s.timestamp).getTime();
-          e += c - h;
+          const g = new Date(o.timestamp).getTime(), h = new Date(a.timestamp).getTime();
+          e += h - g;
         }
       }
     });
@@ -423,7 +495,7 @@ class w extends d {
    */
   recordEvent(t) {
     const e = {
-      eventId: t.metadata?.eventId || `audit-${b.getUUID()}`,
+      eventId: t.metadata?.eventId || `audit-${E.getUUID()}`,
       eventName: t.eventName,
       aggregateId: this.aggregate.getId().toString(),
       aggregateType: this.aggregate.constructor.name,
@@ -452,8 +524,8 @@ class w extends d {
    */
   getEventsByTimeRange(t, e) {
     return this.auditLog.filter((i) => {
-      const s = new Date(i.timestamp).getTime();
-      return s >= t.getTime() && s <= e.getTime();
+      const a = new Date(i.timestamp).getTime();
+      return a >= t.getTime() && a <= e.getTime();
     });
   }
   /**
@@ -475,7 +547,7 @@ class r extends L {
    */
   static invalidArguments(t, e) {
     const i = {
-      code: g.InvalidParameter,
+      code: c.InvalidParameter,
       data: e
     };
     return new r(t, i);
@@ -483,24 +555,24 @@ class r extends L {
   /**
    * Error for version conflicts in the aggregate
    */
-  static versionConflict(t, e, i, s) {
-    const n = `Version conflict: Aggregate ${t} with ID ${e} has version ${i}, but expected ${s}`, o = {
-      code: g.ValidationFailed,
+  static versionConflict(t, e, i, a) {
+    const s = `Version conflict: Aggregate ${t} with ID ${e} has version ${i}, but expected ${a}`, o = {
+      code: c.ValidationFailed,
       data: {
         aggregateType: t,
         aggregateId: e,
         currentVersion: i,
-        expectedVersion: s
+        expectedVersion: a
       }
     };
-    return new r(n, o);
+    return new r(s, o);
   }
   /**
    * Error for when a required feature is not enabled
    */
   static featureNotEnabled(t) {
     const e = `Feature '${t}' is not enabled on aggregate`, i = {
-      code: g.ValidationFailed,
+      code: c.ValidationFailed,
       data: {
         feature: t
       }
@@ -511,113 +583,113 @@ class r extends L {
    * Error for when a required method is not implemented
    */
   static methodNotImplemented(t, e) {
-    const i = `Method '${t}' must be implemented by ${e} to use this feature`, s = {
-      code: g.MissingValue,
+    const i = `Method '${t}' must be implemented by ${e} to use this feature`, a = {
+      code: c.MissingValue,
       data: {
         methodName: t,
         aggregateType: e
       }
     };
-    return new r(i, s);
+    return new r(i, a);
   }
   /**
    * Error for invalid snapshot
    */
   static invalidSnapshot(t, e) {
-    const i = `Invalid snapshot for aggregate ${t}${e ? `: ${e}` : ""}`, s = {
-      code: g.InvalidFormat,
+    const i = `Invalid snapshot for aggregate ${t}${e ? `: ${e}` : ""}`, a = {
+      code: c.InvalidFormat,
       data: {
         aggregateType: t,
         reason: e
       }
     };
-    return new r(i, s);
+    return new r(i, a);
   }
   /**
    * Error for ID mismatch during snapshot restoration
    */
   static idMismatch(t, e) {
-    const i = `ID mismatch: Snapshot is for ID ${t}, but aggregate has ID ${e}`, s = {
-      code: g.ValidationFailed,
+    const i = `ID mismatch: Snapshot is for ID ${t}, but aggregate has ID ${e}`, a = {
+      code: c.ValidationFailed,
       data: {
         snapshotId: t,
         aggregateId: e
       }
     };
-    return new r(i, s);
+    return new r(i, a);
   }
   /**
    * Error for type mismatch during snapshot restoration
    */
   static typeMismatch(t, e) {
-    const i = `Aggregate type mismatch: Snapshot is for type ${t}, but trying to load into ${e}`, s = {
-      code: g.ValidationFailed,
+    const i = `Aggregate type mismatch: Snapshot is for type ${t}, but trying to load into ${e}`, a = {
+      code: c.ValidationFailed,
       data: {
         snapshotType: t,
         aggregateType: e
       }
     };
-    return new r(i, s);
+    return new r(i, a);
   }
   /**
    * Error for duplicate upcaster registration
    */
   static duplicateUpcaster(t, e) {
-    const i = `Upcaster for event ${t} version ${e} already exists`, s = {
-      code: g.DuplicateEntry,
+    const i = `Upcaster for event ${t} version ${e} already exists`, a = {
+      code: c.DuplicateEntry,
       data: {
         eventType: t,
         sourceVersion: e
       }
     };
-    return new r(i, s);
+    return new r(i, a);
   }
   /**
    * Error for missing upcaster
    */
   static missingUpcaster(t, e, i) {
-    const s = `Missing upcaster for event ${t} from version ${e} to ${i}`, n = {
-      code: g.MissingValue,
+    const a = `Missing upcaster for event ${t} from version ${e} to ${i}`, s = {
+      code: c.MissingValue,
       data: {
         eventType: t,
         fromVersion: e,
         toVersion: i
       }
     };
-    return new r(s, n);
+    return new r(a, s);
   }
   /**
    * Error for configuration problems
    */
   static configurationError(t, e) {
-    const i = `Configuration error in ${t}: ${e}`, s = {
-      code: g.ValidationFailed,
+    const i = `Configuration error in ${t}: ${e}`, a = {
+      code: c.ValidationFailed,
       data: {
         aggregateType: t,
         configurationError: e
       }
     };
-    return new r(i, s);
+    return new r(i, a);
   }
   /**
    * Error for when apply method interception fails (e.g. method not found)
    */
   static cannotInterceptApplyMethod(t, e) {
-    const i = `Cannot intercept apply method - method not found on aggregate ${t}`, s = {
-      code: g.InternalError,
+    const i = `Cannot intercept apply method - method not found on aggregate ${t}`, a = {
+      code: c.InternalError,
       data: {
         aggergateId: t,
         ...e
       }
     };
-    return new r(i, s);
+    return new r(i, a);
   }
   /**
    * Error for when event store is not configured
    */
   static eventStoreNotConfigured(t) {
     const e = "Event store not configured", i = {
-      code: g.MissingValue,
+      code: c.MissingValue,
       data: t
     };
     return new r(e, i);
@@ -626,17 +698,17 @@ class r extends L {
    * Error for when aggregate does not support event replay
    */
   static aggregateDoesNotSupportReplay(t, e) {
-    const i = `Aggregate ${t} does not support event replay`, s = {
-      code: g.MethodNotSupported,
+    const i = `Aggregate ${t} does not support event replay`, a = {
+      code: c.MethodNotSupported,
       data: {
         aggregateType: t,
         ...e
       }
     };
-    return new r(i, s);
+    return new r(i, a);
   }
 }
-class S extends d {
+class w extends d {
   constructor() {
     super(...arguments), this.type = "eventSourcing", this.eventStore = null;
   }
@@ -719,11 +791,11 @@ class S extends d {
         this.aggregate.constructor.name,
         "Event store not configured"
       );
-    const i = await this.eventStore.getEventsAfterVersion(t, e), s = this.aggregate;
-    s.loadFromHistory && i.length > 0 && s.loadFromHistory(i);
+    const i = await this.eventStore.getEventsAfterVersion(t, e), a = this.aggregate;
+    a.loadFromHistory && i.length > 0 && a.loadFromHistory(i);
   }
 }
-class _ extends d {
+class S extends d {
   constructor() {
     super(...arguments), this.type = "snapshot", this._snapshot = null;
   }
@@ -745,15 +817,15 @@ class _ extends d {
    * @returns {IAggregateSnapshot<TState, TMeta>} Created snapshot with state and metadata
    */
   createSnapshot(t, e) {
-    const i = this.aggregate.getDomainEvents(), n = (i.length > 0 ? i[i.length - 1] : null)?.metadata?.eventId, h = {
+    const i = this.aggregate.getDomainEvents(), s = (i.length > 0 ? i[i.length - 1] : null)?.metadata?.eventId, g = {
       aggregateId: this.aggregate.getId().toString(),
       version: this.aggregate.getVersion(),
       aggregateType: this.aggregate.constructor.name,
       state: t(),
       timestamp: /* @__PURE__ */ new Date(),
-      ...n !== void 0 && { lastEventId: n }
+      ...s !== void 0 && { lastEventId: s }
     };
-    return e && (h.metadata = e()), h;
+    return e && (g.metadata = e()), g;
   }
   /**
    * @param {IAggregateSnapshot<TState, TMeta>} snapshot - Snapshot to restore from
@@ -764,12 +836,12 @@ class _ extends d {
   restoreFromSnapshot(t, e, i) {
     if (!t || !t.state)
       throw r.invalidSnapshot(this.aggregate.constructor.name, "Invalid snapshot");
-    const s = this.aggregate.getId().toString();
-    if (t.aggregateId !== s)
-      throw r.idMismatch(t.aggregateId, s);
+    const a = this.aggregate.getId().toString();
+    if (t.aggregateId !== a)
+      throw r.idMismatch(t.aggregateId, a);
     if (t.aggregateType !== this.aggregate.constructor.name)
       throw r.typeMismatch(t.aggregateType, this.aggregate.constructor.name);
-    e(t.state), t.metadata && i && i(t.metadata), this.aggregate._internal_setState(E, {
+    e(t.state), t.metadata && i && i(t.metadata), this.aggregate._internal_setState(b, {
       version: t.version,
       initialVersion: t.version,
       domainEvents: []
@@ -817,7 +889,7 @@ class v {
     return new v(e);
   }
   withSnapshots() {
-    return this.capabilities.push({ capability: new _() }), this;
+    return this.capabilities.push({ capability: new S() }), this;
   }
   /**
    * @returns {this} Builder instance for method chaining
@@ -829,19 +901,19 @@ class v {
    * @returns {this} Builder instance for method chaining
    */
   withAudit() {
-    return this.capabilities.push({ capability: new w() }), this;
+    return this.capabilities.push({ capability: new _() }), this;
   }
   /**
    * @param {IEventStore} [eventStore] - Optional event store for event sourcing
    * @returns {this} Builder instance for method chaining
    */
   withEventSourcing(t) {
-    const e = new S();
+    const e = new w();
     return this.capabilities.push({
       capability: e,
       configure: (i) => {
-        const s = i;
-        t ? s.setEventStore(t) : this.eventStore && s.setEventStore(this.eventStore);
+        const a = i;
+        t ? a.setEventStore(t) : this.eventStore && a.setEventStore(this.eventStore);
       }
     }), this;
   }
@@ -865,8 +937,8 @@ class v {
   }
   build(t) {
     const e = t || u, i = new e(this.params);
-    for (const { capability: s, configure: n } of this.capabilities)
-      i.addCapability(s), n && n(s);
+    for (const { capability: a, configure: s } of this.capabilities)
+      i.addCapability(a), s && s(a);
     return i;
   }
   /**
@@ -877,8 +949,8 @@ class v {
     return this.withSnapshots().withVersioning().withAudit().withEventSourcing().build(t);
   }
 }
-function U(a) {
-  return v.create(a);
+function O(n) {
+  return v.create(n);
 }
 class C {
   constructor(t) {
@@ -902,74 +974,74 @@ class C {
     return t == null ? !1 : t === this ? !0 : t instanceof C ? this._id.equals(t._id) : !1;
   }
 }
-function V(a) {
-  return a.hasCapability(_);
+function V(n) {
+  return n.hasCapability(S);
 }
-function I(a) {
-  return a.hasCapability(p);
+function I(n) {
+  return n.hasCapability(p);
 }
-function A(a) {
-  return a.hasCapability(w);
+function A(n) {
+  return n.hasCapability(_);
 }
-function $(a) {
-  return a.hasCapability(S);
+function $(n) {
+  return n.hasCapability(w);
 }
-function O(a) {
-  if (!V(a))
+function j(n) {
+  if (!V(n))
     throw r.featureNotEnabled("snapshot");
-  return a;
+  return n;
 }
-function j(a) {
-  return V(a) ? l.ok(a) : l.fail(r.featureNotEnabled("snapshot"));
+function k(n) {
+  return V(n) ? l.ok(n) : l.fail(r.featureNotEnabled("snapshot"));
 }
-function k(a) {
-  if (!I(a))
+function P(n) {
+  if (!I(n))
     throw r.featureNotEnabled("versioning");
-  return a;
+  return n;
 }
-function P(a) {
-  return I(a) ? l.ok(a) : l.fail(r.featureNotEnabled("versioning"));
+function W(n) {
+  return I(n) ? l.ok(n) : l.fail(r.featureNotEnabled("versioning"));
 }
-function W(a) {
-  if (!A(a))
+function z(n) {
+  if (!A(n))
     throw r.featureNotEnabled("audit");
-  return a;
+  return n;
 }
-function z(a) {
-  return A(a) ? l.ok(a) : l.fail(r.featureNotEnabled("audit"));
+function B(n) {
+  return A(n) ? l.ok(n) : l.fail(r.featureNotEnabled("audit"));
 }
-function B(a) {
-  if (!$(a))
+function R(n) {
+  if (!$(n))
     throw r.featureNotEnabled("eventSourcing");
-  return a;
+  return n;
 }
-function R(a) {
-  return $(a) ? l.ok(a) : l.fail(r.featureNotEnabled("eventSourcing"));
+function q(n) {
+  return $(n) ? l.ok(n) : l.fail(r.featureNotEnabled("eventSourcing"));
 }
-function q(a) {
-  return a.getCapabilityTypes();
+function K(n) {
+  return n.getCapabilityTypes();
 }
-function K(a, t) {
-  return t.every((e) => a.hasCapability(e));
+function G(n, t) {
+  return t.every((e) => n.hasCapability(e));
 }
 export {
   v as AggregateBuilder,
   r as AggregateError,
   u as AggregateRoot,
-  w as AuditCapability,
+  _ as AuditCapability,
   C as Entity,
-  S as EventSourcingCapability,
-  _ as SnapshotCapability,
+  w as EventSourcingCapability,
+  S as SnapshotCapability,
   p as VersioningCapability,
-  U as aggregateBuilder,
-  W as asAuditAggregate,
-  B as asEventSourcingAggregate,
-  O as asSnapshotAggregate,
-  k as asVersioningAggregate,
-  q as getAggregateCapabilities,
-  K as hasAllCapabilities,
-  z as tryAsAuditAggregate,
-  R as tryAsEventSourcingAggregate,
-  j as tryAsSnapshotAggregate,
-  P as tryAsVersioningAggregate
+  O as aggregateBuilder,
+  z as asAuditAggregate,
+  R as asEventSourcingAggregate,
+  j as asSnapshotAggregate,
+  P as asVersioningAggregate,
+  K as getAggregateCapabilities,
+  G as hasAllCapabilities,
+  B as tryAsAuditAggregate,
+  q as tryAsEventSourcingAggregate,
+  k as tryAsSnapshotAggregate,
+  W as tryAsVersioningAggregate
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vytches/ddd-aggregates",
-  "version": "0.31.0-alpha.0",
+  "version": "0.31.0",
   "description": "Aggregate root implementations with capabilities",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,10 +34,10 @@
     "directory": "packages/aggregates"
   },
   "dependencies": {
-    "@vytches/ddd-contracts": "0.31.0-alpha.0",
-    "@vytches/ddd-value-objects": "0.31.0-alpha.0",
-    "@vytches/ddd-domain-primitives": "0.31.0-alpha.0",
-    "@vytches/ddd-utils": "0.31.0-alpha.0"
+    "@vytches/ddd-contracts": "0.31.0",
+    "@vytches/ddd-utils": "0.31.0",
+    "@vytches/ddd-value-objects": "0.31.0",
+    "@vytches/ddd-domain-primitives": "0.31.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0",