@vytches/ddd-aggregates 0.26.0

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

@@ -0,0 +1,233 @@
+import { Result } from '../../../utils/src/index.ts';
+import { CapabilityConstructor, Capability, IAggregateCapability, IAggregateSnapshot } from '../../../contracts/src/index.ts';
+import { AggregateError } from '../aggregate-errors';
+import { SnapshotCapability } from '../capabilities/snapshot-capability';
+import { VersioningCapability } from '../capabilities/versioning-capability';
+import { EventSourcingCapability } from '../capabilities/event-sourcing-capability';
+import { AuditCapability } from '../capabilities/audit-capability';
+import { AggregateRoot } from './aggregate-root';
+/**
+ * Type utility for aggregates with specific capability requirements.
+ * Provides compile-time type safety for capability-dependent operations.
+ */
+export type AggregateWithCapability<TId, TCap extends Capability> = AggregateRoot<TId> & {
+    getCapability<T extends TCap>(CapabilityClass: CapabilityConstructor<T>): T;
+};
+/**
+ * Type alias for aggregates with snapshot capability.
+ * Ensures aggregate has snapshot functionality for state persistence.
+ */
+export type AggregateWithSnapshotCapability<TId> = AggregateWithCapability<TId, SnapshotCapability>;
+/**
+ * Type alias for aggregates with versioning capability.
+ * Ensures aggregate has event versioning and upcasting functionality.
+ */
+export type AggregateWithVersioningCapability<TId> = AggregateWithCapability<TId, VersioningCapability>;
+/**
+ * Type alias for aggregates with audit capability.
+ * Ensures aggregate has audit logging functionality for compliance.
+ */
+export type AggregateWithAuditCapability<TId> = AggregateWithCapability<TId, AuditCapability>;
+/**
+ * Type alias for aggregates with event sourcing capability.
+ * Ensures aggregate has event store integration for persistence.
+ */
+export type AggregateWithEventSourcingCapability<TId> = AggregateWithCapability<TId, EventSourcingCapability>;
+/**
+ * @param {AggregateRoot<TId>} aggregate - aggregate parameter
+ * @returns {aggregate is AggregateWithSnapshotCapability<TId>} Returns aggregate is AggregateWithSnapshotCapability<TId>
+ * @throws {Error} When validation fails
+ */
+export declare function hasSnapshotCapability<TId>(aggregate: AggregateRoot<TId>): aggregate is AggregateWithSnapshotCapability<TId>;
+/**
+ * @param {AggregateRoot<TId>} aggregate - aggregate parameter
+ * @returns {aggregate is AggregateWithVersioningCapability<TId>} Returns aggregate is AggregateWithVersioningCapability<TId>
+ * @throws {Error} When validation fails
+ */
+export declare function hasVersioningCapability<TId>(aggregate: AggregateRoot<TId>): aggregate is AggregateWithVersioningCapability<TId>;
+/**
+ * @param {AggregateRoot<TId>} aggregate - aggregate parameter
+ * @returns {aggregate is AggregateWithAuditCapability<TId>} Returns aggregate is AggregateWithAuditCapability<TId>
+ * @throws {Error} When validation fails
+ */
+export declare function hasAuditCapability<TId>(aggregate: AggregateRoot<TId>): aggregate is AggregateWithAuditCapability<TId>;
+/**
+ * @param {AggregateRoot<TId>} aggregate - aggregate parameter
+ * @returns {aggregate is AggregateWithEventSourcingCapability<TId>} Returns aggregate is AggregateWithEventSourcingCapability<TId>
+ * @throws {Error} When validation fails
+ */
+export declare function hasEventSourcingCapability<TId>(aggregate: AggregateRoot<TId>): aggregate is AggregateWithEventSourcingCapability<TId>;
+/**
+ * @param {AggregateRoot<TId>} aggregate - aggregate parameter
+ * @returns {AggregateWithSnapshotCapability<TId>} Returns AggregateWithSnapshotCapability<TId>
+ * @throws {Error} When validation fails
+ */
+export declare function asSnapshotAggregate<TId>(aggregate: AggregateRoot<TId>): AggregateWithSnapshotCapability<TId>;
+/**
+ * Returns the aggregate cast to snapshot-capable type, or a failed Result if the capability
+ * is not registered. Use this variant when missing capability is an expected condition.
+ *
+ * @param aggregate - Aggregate to cast
+ * @returns `Result.ok` with the cast aggregate, or `Result.fail` with an {@link AggregateError}
+ * @public
+ * @stable
+ * @since 0.24.0
+ */
+export declare function tryAsSnapshotAggregate<TId>(aggregate: AggregateRoot<TId>): Result<AggregateWithSnapshotCapability<TId>, AggregateError>;
+/**
+ * @param {AggregateRoot<TId>} aggregate - aggregate parameter
+ * @returns {AggregateWithVersioningCapability<TId>} Returns AggregateWithVersioningCapability<TId>
+ * @throws {Error} When validation fails
+ */
+export declare function asVersioningAggregate<TId>(aggregate: AggregateRoot<TId>): AggregateWithVersioningCapability<TId>;
+/**
+ * Returns the aggregate cast to versioning-capable type, or a failed Result if the capability
+ * is not registered. Use this variant when missing capability is an expected condition.
+ *
+ * @param aggregate - Aggregate to cast
+ * @returns `Result.ok` with the cast aggregate, or `Result.fail` with an {@link AggregateError}
+ * @public
+ * @stable
+ * @since 0.24.0
+ */
+export declare function tryAsVersioningAggregate<TId>(aggregate: AggregateRoot<TId>): Result<AggregateWithVersioningCapability<TId>, AggregateError>;
+/**
+ * @param {AggregateRoot<TId>} aggregate - aggregate parameter
+ * @returns {AggregateWithAuditCapability<TId>} Returns AggregateWithAuditCapability<TId>
+ * @throws {Error} When validation fails
+ */
+export declare function asAuditAggregate<TId>(aggregate: AggregateRoot<TId>): AggregateWithAuditCapability<TId>;
+/**
+ * Returns the aggregate cast to audit-capable type, or a failed Result if the capability
+ * is not registered. Use this variant when missing capability is an expected condition.
+ *
+ * @param aggregate - Aggregate to cast
+ * @returns `Result.ok` with the cast aggregate, or `Result.fail` with an {@link AggregateError}
+ * @public
+ * @stable
+ * @since 0.24.0
+ */
+export declare function tryAsAuditAggregate<TId>(aggregate: AggregateRoot<TId>): Result<AggregateWithAuditCapability<TId>, AggregateError>;
+/**
+ * @param {AggregateRoot<TId>} aggregate - aggregate parameter
+ * @returns {AggregateWithEventSourcingCapability<TId>} Returns AggregateWithEventSourcingCapability<TId>
+ * @throws {Error} When validation fails
+ */
+export declare function asEventSourcingAggregate<TId>(aggregate: AggregateRoot<TId>): AggregateWithEventSourcingCapability<TId>;
+/**
+ * Returns the aggregate cast to event-sourcing-capable type, or a failed Result if the
+ * capability is not registered. Use this variant when missing capability is an expected condition.
+ *
+ * @param aggregate - Aggregate to cast
+ * @returns `Result.ok` with the cast aggregate, or `Result.fail` with an {@link AggregateError}
+ * @public
+ * @stable
+ * @since 0.24.0
+ */
+export declare function tryAsEventSourcingAggregate<TId>(aggregate: AggregateRoot<TId>): Result<AggregateWithEventSourcingCapability<TId>, AggregateError>;
+/**
+ * @param {AggregateRoot<unknown>} aggregate - aggregate parameter
+ * @returns {string[]} Returns string[]
+ * @throws {Error} When validation fails
+ */
+export declare function getAggregateCapabilities(aggregate: AggregateRoot<unknown>): string[];
+/**
+ * @param {AggregateRoot<unknown>} aggregate - aggregate parameter
+ * @param {CapabilityConstructor<T>[]} capabilities - capabilities parameter
+ * @returns {boolean} Returns boolean
+ * @throws {Error} When validation fails
+ */
+export declare function hasAllCapabilities<T extends Capability & IAggregateCapability>(aggregate: AggregateRoot<unknown>, capabilities: CapabilityConstructor<T>[]): boolean;
+/**
+ * @param {AggregateRoot<unknown>} aggregate - aggregate parameter
+ * @param {CapabilityConstructor<T>[]} capabilities - capabilities parameter
+ * @returns {boolean} Returns boolean
+ * @throws {Error} When validation fails
+ */
+export declare function hasAnyCapability<T extends Capability & IAggregateCapability>(aggregate: AggregateRoot<unknown>, capabilities: CapabilityConstructor<T>[]): boolean;
+/**
+ * @param {AggregateRoot<unknown>} aggregate - aggregate parameter
+ * @throws {Error} When validation fails
+ */
+export declare function getAggregateInfo(aggregate: AggregateRoot<unknown>): {
+    id: unknown;
+    type: string;
+    version: number;
+    hasChanges: boolean;
+    capabilities: string[];
+    events: number;
+};
+/**
+ * @param {AggregateRoot<unknown>} aggregate - Aggregate to create snapshot for
+ * @param {() => TState} serializer - Function to serialize aggregate state
+ * @param {() => unknown} metadataCreator - Optional metadata creator function
+ * @returns {unknown | null} Snapshot object if capability exists, null otherwise
+ */
+export declare function createSnapshotIfCapable<TState>(aggregate: AggregateRoot<unknown>, serializer: () => TState, metadataCreator?: () => unknown): unknown | null;
+/**
+ * @param {AggregateRoot<unknown>} aggregate - aggregate parameter
+ * @param {IAggregateSnapshot<unknown} snapshot - snapshot parameter
+ * @param {(state: TState} deserializer - deserializer parameter
+ * @returns {boolean} Returns boolean
+ * @throws {Error} When validation fails
+ */
+export declare function restoreFromSnapshotIfCapable<TState = unknown>(aggregate: AggregateRoot<unknown>, snapshot: IAggregateSnapshot<unknown, unknown>, deserializer: (state: TState) => void, metadataRestorer?: (metadata: unknown) => void): boolean;
+/**
+ * @param {AggregateRoot<unknown>} aggregate - aggregate parameter
+ * @returns {unknown[]} Returns unknown[]
+ * @throws {Error} When validation fails
+ */
+export declare function getAuditLogIfCapable(aggregate: AggregateRoot<unknown>): unknown[];
+/**
+ * @param {AggregateRoot<unknown>} aggregate - Aggregate to get audit statistics from
+ * @returns {unknown | null} Audit statistics if capability exists, null otherwise
+ */
+export declare function getAuditStatsIfCapable(aggregate: AggregateRoot<unknown>): unknown | null;
+/**
+ * @param {AggregateRoot<unknown>} aggregate - aggregate parameter
+ * @param {string | number} aggregateId - aggregateId parameter
+ * @returns {Promise<boolean>} Returns Promise<boolean>
+ * @throws {Error} When validation fails
+ */
+export declare function loadFromEventStoreIfCapable(aggregate: AggregateRoot<unknown>, aggregateId: string | number): Promise<boolean>;
+/**
+ * @param {AggregateRoot<unknown>} aggregate - aggregate parameter
+ * @returns {Promise<boolean>} Returns Promise<boolean>
+ * @throws {Error} When validation fails
+ */
+export declare function saveToEventStoreIfCapable(aggregate: AggregateRoot<unknown>): Promise<boolean>;
+/**
+ * @param {AggregateRoot<unknown>} aggregate - aggregate parameter
+ * @param {string} eventType - eventType parameter
+ * @param {number} sourceVersion - sourceVersion parameter
+ * @param {{ upcast(payload: TFrom} upcaster - upcaster parameter
+ * @param {unknown} metadata? - metadata? parameter
+ * @returns {TTo }} Returns TTo }
+ * @throws {Error} When validation fails
+ */
+export declare function registerUpcasterIfCapable<TFrom, TTo>(aggregate: AggregateRoot<unknown>, eventType: string, sourceVersion: number, upcaster: {
+    upcast(payload: TFrom, metadata?: unknown): TTo;
+}): boolean;
+/**
+ * @param {AggregateRoot<unknown>} aggregate - Aggregate to get versioning info from
+ * @returns {unknown | null} Versioning information if capability exists, null otherwise
+ */
+export declare function getVersioningInfoIfCapable(aggregate: AggregateRoot<unknown>): unknown | null;
+/**
+ * @throws {Error} When validation fails
+ */
+export declare function processAggregatesWithCapabilities<TId>(aggregates: AggregateRoot<TId>[], processors: {
+    snapshot?: (aggregate: AggregateWithSnapshotCapability<TId>) => void;
+    audit?: (aggregate: AggregateWithAuditCapability<TId>) => void;
+    versioning?: (aggregate: AggregateWithVersioningCapability<TId>) => void;
+    eventSourcing?: (aggregate: AggregateWithEventSourcingCapability<TId>) => Promise<void>;
+}): Promise<void>;
+/**
+ * @throws {Error} When validation fails
+ */
+export declare function cloneAggregateCapabilities<TIdFrom, TIdTo>(sourceAggregate: AggregateRoot<TIdFrom>, targetAggregate: AggregateRoot<TIdTo>, options?: {
+    includeSnapshot?: boolean;
+    includeVersioning?: boolean;
+    includeAudit?: boolean;
+    includeEventSourcing?: boolean;
+}): void;

package/dist/core/entity.d.ts

@@ -0,0 +1,76 @@
+import { EntityId } from '../../../contracts/src/index.ts';
+/**
+ * Base class for domain entities — objects with identity that may be
+ * referenced from other aggregates but are NOT themselves aggregate roots.
+ *
+ * Per Eric Evans (Blue Book, ch. 5):
+ * > Some objects are not defined primarily by their attributes. They
+ * > represent a thread of identity that runs through time and often across
+ * > distinct representations. Sometimes such an object must be matched with
+ * > another object even though attributes differ.
+ *
+ * Use `Entity<TId>` for inner objects of an aggregate that have their own
+ * identity (e.g. `OrderLine` inside `Order`, `Address` inside `Customer`
+ * if addresses are independently identifiable). Use `AggregateRoot<TId>`
+ * for the *root* entity of an aggregate — the transactional boundary.
+ *
+ * Two entities are equal iff they have the same `EntityId<TId>`. Attribute
+ * equality is irrelevant; even if all fields match, two entities with
+ * different ids are different things. Conversely, the same entity at two
+ * points in time may have different attribute values but is still the
+ * same entity.
+ *
+ * VF-CANON-001 (2026-05-09): added to close the canonical Evans/Vernon
+ * gap — competing libraries (NestJS DDD plugins, dddsample-java) ship
+ * a separate Entity base; this library previously only had AggregateRoot.
+ *
+ * **Relationship to `AggregateRoot`:** Conceptually, every aggregate root
+ * is a special kind of entity (per Evans: "the only member of its AGGREGATE
+ * that outside objects are allowed to hold references to"). For backward
+ * compatibility, `AggregateRoot` does NOT extend this `Entity` class — both
+ * carry their own `_id: EntityId<TId>` and `equals()` logic. Treat them as
+ * conceptual siblings: identity-based equality is the same contract, but
+ * the inheritance graph is intentionally flat to avoid breaking existing
+ * `AggregateRoot` consumers. A future major version may unify them.
+ *
+ * @example
+ * ```typescript
+ * import { Entity } from '@vytches/ddd-aggregates';
+ * import { EntityId } from '@vytches/ddd-value-objects';
+ *
+ * class OrderLine extends Entity<string> {
+ *   constructor(
+ *     id: EntityId<string>,
+ *     public readonly sku: string,
+ *     public quantity: number,
+ *   ) {
+ *     super(id);
+ *   }
+ * }
+ *
+ * const a = new OrderLine(EntityId.fromUUID('...'), 'SKU-1', 1);
+ * const b = new OrderLine(EntityId.fromUUID('...'), 'SKU-1', 99);
+ * a.equals(b); // true if ids match — quantity doesn't matter
+ * ```
+ *
+ * @public
+ * @stable
+ * @since 0.25.0
+ */
+export declare abstract class Entity<TId = string> {
+    protected readonly _id: EntityId<TId>;
+    constructor(id: EntityId<TId>);
+    /**
+     * Return this entity's unique identifier.
+     */
+    getId(): EntityId<TId>;
+    /**
+     * Identity-based equality. Two entities are equal iff they have the same
+     * id (compared via the EntityId's own equality). Attribute differences
+     * are ignored.
+     *
+     * @param other - Entity to compare against. May be `null` or `undefined`.
+     * @returns `true` if both entities have the same id; `false` otherwise.
+     */
+    equals(other: Entity<TId> | null | undefined): boolean;
+}

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const T=require("/home/runner/work/ddd/ddd/packages/logging/dist/index.js"),c=require("/home/runner/work/ddd/ddd/packages/domain-primitives/dist/index.js");function D(){return globalThis.crypto.randomUUID()}function I(a,t,e){return{eventName:a,payload:t,metadata:{eventId:D(),timestamp:new Date,...e}}}class p{isType(t){return this.type===t}static get capabilityType(){throw new Error("Capability subclass must override static capabilityType getter")}}class ${constructor(){this.capabilities=new Map}register(t){return this.capabilities.set(t.type,t),this}get(t){const e=t.capabilityType;return this.capabilities.get(e)}getByType(t){return this.capabilities.get(t)}has(t){const e=t.capabilityType;return this.capabilities.has(e)}hasByType(t){return this.capabilities.has(t)}remove(t){const e=t.capabilityType;return this.capabilities.delete(e)}removeByType(t){return this.capabilities.delete(t)}getAll(){return Array.from(this.capabilities.values())}getTypes(){return Array.from(this.capabilities.keys())}clear(){this.capabilities.clear()}get size(){return this.capabilities.size}}class g{constructor(t,e="text"){this.value=t,this.type=e}getValue(){return this.value}getType(){return this.type}validate(t){return t!=null&&t!==void 0}equals(t){return t.getValue()===this.value&&t.getType()===this.type}isType(t){return this.type===t}toString(){return String(this.value)}toJSON(){return JSON.stringify({value:this.value,type:this.type})}static create(){const t="xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g,e=>{const i=Math.random()*16|0;return(e==="x"?i:i&3|8).toString(16)});return new g(t,"uuid")}static createText(t){return new g(t,"text")}static createUuid(t){return new g(t,"uuid")}static createInteger(t){return new g(t.toString(),"integer")}static createBigInt(t){const e=typeof t=="bigint"?t.toString():t;return new g(e,"bigint")}static createWithRandomUUID(){return g.create()}static fromUUID(t){if(!t||typeof t!="string")throw new Error("entity identifier must be provided");if(!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(t))throw new Error("entity identifier must be valid UUID");return new g(t,"uuid")}static fromInteger(t){if(typeof t!="number"||t<0||!Number.isInteger(t))throw new Error("entity identifier must be a non-negative integer");return new g(t.toString(),"integer")}static fromBigInt(t){const e=typeof t=="bigint"?t.toString():t;if(!e||typeof e!="string")throw new Error("entity identifier must be a valid bigint");return new g(e,"bigint")}static fromText(t){if(!t||typeof t!="string")throw new Error("entity identifier must be provided");if(!/^[a-zA-Z0-9_-]+$/.test(t))throw new Error("entity identifier contains invalid characters");return new g(t,"text")}}class o{constructor(t,e,i){this._isSuccess=t,this._value=e,this._error=i}get isSuccess(){return this._isSuccess}get isFailure(){return!this._isSuccess}get value(){if(!this._isSuccess)throw new Error("Cannot get value of a failure result");return this._value}get error(){if(this._isSuccess)throw new Error("Cannot get error of a success result");return this._error}static ok(t){return new o(!0,t)}static empty(){return new o(!0,void 0)}static fail(t){return new o(!1,void 0,t)}static try(t){try{return o.ok(t())}catch(e){return o.fail(e instanceof Error?e:new Error(String(e)))}}map(t){return this.isFailure?o.fail(this.error):o.ok(t(this.value))}flatMap(t){return this.isFailure?o.fail(this.error):t(this.value)}match(t,e){return this.isSuccess?t(this.value):e(this.error)}tap(t){return this.isSuccess&&t(this.value),this}tapError(t){return this.isFailure&&t(this.error),this}mapError(t){return this.isSuccess?o.ok(this.value):o.fail(t(this.error))}static async tryAsync(t){try{const e=await t();return o.ok(e)}catch(e){return o.fail(e instanceof Error?e:new Error(String(e)))}}async mapAsync(t){if(this.isFailure)return o.fail(this.error);try{const e=await t(this.value);return o.ok(e)}catch(e){const i=e instanceof Error?e:new Error(String(e));return o.fail(i)}}async flatMapAsync(t){return this.isFailure?o.fail(this.error):await t(this.value)}}class d extends p{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,r=t.metadata?.targetVersion||i;let s=t;if(i<r&&this.upcasters.has(t.eventName)){const h=this.upcasters.get(t.eventName),m=T.Logger.forContext("VersioningCapability");for(let l=i;l<r;l++){const S=h.get(l);if(!S){m.warn("Missing upcaster for event version — event will be processed without upcast",{eventName:t.eventName,fromVersion:l,toVersion:l+1});continue}const _=S.upcast(s.payload,s.metadata);s={...s,payload:_,metadata:{...s.metadata,version:l+1}}}}const u=e.get(s.eventName);u&&u(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}}class f{constructor(t){this._version=0,this._initialVersion=0,this._domainEvents=[],this._eventHandlers=new Map,this._capabilities=new $,this._id=t.id,this._version=t.version||0,this._initialVersion=t.version||0,this._maxEvents=t.maxEvents}getId(){return this._id}getVersion(){return this._version}getInitialVersion(){return this._initialVersion}hasChanges(){return this._domainEvents.length>0}getDomainEvents(){return[...this._domainEvents]}commit(){this._domainEvents=[],this._initialVersion=this._version}registerEventHandler(t,e){return this._eventHandlers.set(t,e),this}apply(t,e,i){this._version++;let r,s;typeof t=="string"?(r=I(t,e,i),s=r.metadata):(r=t,s=i?{...r.metadata,...i}:r.metadata);const u=f.sanitizeMetadata({...s,aggregateId:this._id.toString(),aggregateType:this.constructor.name,aggregateVersion:this._version,timestamp:s?.timestamp??new Date}),h=Object.assign(Object.create(Object.getPrototypeOf(r)),r,{metadata:u});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.`);this._domainEvents.push(h),this.handleEvent(h)}handleEvent(t){const e=this.getCapability(d);if(e)e.handleVersionedEvent(t,this._eventHandlers);else{const i=this._eventHandlers.get(t.eventName);i&&i(t.payload,t.metadata)}}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){this._version=t.version,this._initialVersion=t.initialVersion,this._domainEvents=[...t.domainEvents]}}class y extends p{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 r=this.originalApply.call(this.aggregate,...i);return this.recordAuditEvent(),r}))}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((r,s)=>{if(t[r.eventName]=(t[r.eventName]||0)+1,s>0){const u=this.auditLog[s-1];if(u){const h=new Date(u.timestamp).getTime(),m=new Date(r.timestamp).getTime();e+=m-h}}});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-${Date.now()}-${Math.random()}`,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 r=new Date(i.timestamp).getTime();return r>=t.getTime()&&r<=e.getTime()})}getFirstEvent(){return this.auditLog[0]||null}getLastEvent(){return this.auditLog[this.auditLog.length-1]||null}}class n extends c.IDomainError{static invalidArguments(t,e){const i={code:c.DomainErrorCode.InvalidParameter,data:e};return new n(t,i)}static versionConflict(t,e,i,r){const s=`Version conflict: Aggregate ${t} with ID ${e} has version ${i}, but expected ${r}`,u={code:c.DomainErrorCode.ValidationFailed,data:{aggregateType:t,aggregateId:e,currentVersion:i,expectedVersion:r}};return new n(s,u)}static featureNotEnabled(t){const e=`Feature '${t}' is not enabled on aggregate`,i={code:c.DomainErrorCode.ValidationFailed,data:{feature:t}};return new n(e,i)}static methodNotImplemented(t,e){const i=`Method '${t}' must be implemented by ${e} to use this feature`,r={code:c.DomainErrorCode.MissingValue,data:{methodName:t,aggregateType:e}};return new n(i,r)}static invalidSnapshot(t,e){const i=`Invalid snapshot for aggregate ${t}${e?`: ${e}`:""}`,r={code:c.DomainErrorCode.InvalidFormat,data:{aggregateType:t,reason:e}};return new n(i,r)}static idMismatch(t,e){const i=`ID mismatch: Snapshot is for ID ${t}, but aggregate has ID ${e}`,r={code:c.DomainErrorCode.ValidationFailed,data:{snapshotId:t,aggregateId:e}};return new n(i,r)}static typeMismatch(t,e){const i=`Aggregate type mismatch: Snapshot is for type ${t}, but trying to load into ${e}`,r={code:c.DomainErrorCode.ValidationFailed,data:{snapshotType:t,aggregateType:e}};return new n(i,r)}static duplicateUpcaster(t,e){const i=`Upcaster for event ${t} version ${e} already exists`,r={code:c.DomainErrorCode.DuplicateEntry,data:{eventType:t,sourceVersion:e}};return new n(i,r)}static missingUpcaster(t,e,i){const r=`Missing upcaster for event ${t} from version ${e} to ${i}`,s={code:c.DomainErrorCode.MissingValue,data:{eventType:t,fromVersion:e,toVersion:i}};return new n(r,s)}static configurationError(t,e){const i=`Configuration error in ${t}: ${e}`,r={code:c.DomainErrorCode.ValidationFailed,data:{aggregateType:t,configurationError:e}};return new n(i,r)}static cannotInterceptApplyMethod(t,e){const i=`Cannot intercept apply method - method not found on aggregate ${t}`,r={code:c.DomainErrorCode.InternalError,data:{aggergateId:t,...e}};return new n(i,r)}static eventStoreNotConfigured(t){const e="Event store not configured",i={code:c.DomainErrorCode.MissingValue,data:t};return new n(e,i)}static aggregateDoesNotSupportReplay(t,e){const i=`Aggregate ${t} does not support event replay`,r={code:c.DomainErrorCode.MethodNotSupported,data:{aggregateType:t,...e}};return new n(i,r)}}class b extends p{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 n.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 n.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 n.configurationError(this.aggregate.constructor.name,"Event store not configured");const i=await this.eventStore.getEventsAfterVersion(t,e),r=this.aggregate;r.loadFromHistory&&i.length>0&&r.loadFromHistory(i)}}class w extends p{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,h={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&&(h.metadata=e()),h}restoreFromSnapshot(t,e,i){if(!t||!t.state)throw n.invalidSnapshot(this.aggregate.constructor.name,"Invalid snapshot");const r=this.aggregate.getId().toString();if(t.aggregateId!==r)throw n.idMismatch(t.aggregateId,r);if(t.aggregateType!==this.aggregate.constructor.name)throw n.typeMismatch(t.aggregateType,this.aggregate.constructor.name);e(t.state),t.metadata&&i&&i(t.metadata);const s=this.aggregate;s._internal_setState&&s._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 g?t.id:new g(t.id,"text"),version:t.version||0};return new v(e)}withSnapshots(){return this.capabilities.push({capability:new w}),this}withVersioning(){return this.capabilities.push({capability:new d}),this}withAudit(){return this.capabilities.push({capability:new y}),this}withEventSourcing(t){const e=new b;return this.capabilities.push({capability:e,configure:i=>{const r=i;t?r.setEventStore(t):this.eventStore&&r.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||f,i=new e(this.params);for(const{capability:r,configure:s}of this.capabilities)i.addCapability(r),s&&s(r);return i}buildWithAllCapabilities(t){return this.withSnapshots().withVersioning().withAudit().withEventSourcing().build(t)}}function N(a){return v.create(a)}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 A(a){return a.hasCapability(w)}function C(a){return a.hasCapability(d)}function x(a){return a.hasCapability(y)}function V(a){return a.hasCapability(b)}function M(a){if(!A(a))throw n.featureNotEnabled("snapshot");return a}function F(a){return A(a)?o.ok(a):o.fail(n.featureNotEnabled("snapshot"))}function L(a){if(!C(a))throw n.featureNotEnabled("versioning");return a}function U(a){return C(a)?o.ok(a):o.fail(n.featureNotEnabled("versioning"))}function k(a){if(!x(a))throw n.featureNotEnabled("audit");return a}function B(a){return x(a)?o.ok(a):o.fail(n.featureNotEnabled("audit"))}function O(a){if(!V(a))throw n.featureNotEnabled("eventSourcing");return a}function j(a){return V(a)?o.ok(a):o.fail(n.featureNotEnabled("eventSourcing"))}function H(a){return a.getCapabilityTypes()}function P(a,t){return t.every(e=>a.hasCapability(e))}exports.AggregateBuilder=v;exports.AggregateError=n;exports.AggregateRoot=f;exports.AuditCapability=y;exports.Entity=E;exports.EventSourcingCapability=b;exports.SnapshotCapability=w;exports.VersioningCapability=d;exports.aggregateBuilder=N;exports.asAuditAggregate=k;exports.asEventSourcingAggregate=O;exports.asSnapshotAggregate=M;exports.asVersioningAggregate=L;exports.getAggregateCapabilities=H;exports.hasAllCapabilities=P;exports.tryAsAuditAggregate=B;exports.tryAsEventSourcingAggregate=j;exports.tryAsSnapshotAggregate=F;exports.tryAsVersioningAggregate=U;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { AggregateRoot } from './core/aggregate-root';
+export { AggregateBuilder, aggregateBuilder } from './core/aggregate-root.builder';
+export { Entity } from './core/entity';
+export { AuditCapability } from './capabilities/audit-capability';
+export { EventSourcingCapability } from './capabilities/event-sourcing-capability';
+export { SnapshotCapability } from './capabilities/snapshot-capability';
+export { VersioningCapability } from './capabilities/versioning-capability';
+export type { IAggregateRoot, IAggregateCapability, IAggregateConstructorParams, IAggregateEventHandler, IAggregateBuilder, } from './aggregate-interfaces';
+export { AggregateError } from './aggregate-errors';
+export type { AggregateWithSnapshotCapability, AggregateWithVersioningCapability, AggregateWithAuditCapability, AggregateWithEventSourcingCapability, } from './core/aggregate-utilities';
+export { asSnapshotAggregate, tryAsSnapshotAggregate, asVersioningAggregate, tryAsVersioningAggregate, asAuditAggregate, tryAsAuditAggregate, asEventSourcingAggregate, tryAsEventSourcingAggregate, getAggregateCapabilities, hasAllCapabilities, } from './core/aggregate-utilities';