@vytches/ddd-aggregates 0.26.0

package/dist/aggregate-errors.d.ts

@@ -0,0 +1,58 @@
+import { DomainErrorOptions, IDomainError } from '@vytches/ddd-domain-primitives';
+/**
+ * Comprehensive error classes for aggregate-specific domain errors
+ */
+export declare class AggregateError extends IDomainError {
+    /**
+     * Error for invalid arguments provided to the aggregate
+     */
+    static invalidArguments(message: string, data?: DomainErrorOptions): AggregateError;
+    /**
+     * Error for version conflicts in the aggregate
+     */
+    static versionConflict(aggregateType: string, aggregateId: string | number, currentVersion: number, expectedVersion: number): AggregateError;
+    /**
+     * Error for when a required feature is not enabled
+     */
+    static featureNotEnabled(feature: string): AggregateError;
+    /**
+     * Error for when a required method is not implemented
+     */
+    static methodNotImplemented(methodName: string, aggregateType: string): AggregateError;
+    /**
+     * Error for invalid snapshot
+     */
+    static invalidSnapshot(aggregateType: string, reason?: string): AggregateError;
+    /**
+     * Error for ID mismatch during snapshot restoration
+     */
+    static idMismatch(snapshotId: string | number, aggregateId: string | number): AggregateError;
+    /**
+     * Error for type mismatch during snapshot restoration
+     */
+    static typeMismatch(snapshotType: string, aggregateType: string): AggregateError;
+    /**
+     * Error for duplicate upcaster registration
+     */
+    static duplicateUpcaster(eventType: string, sourceVersion: number): AggregateError;
+    /**
+     * Error for missing upcaster
+     */
+    static missingUpcaster(eventType: string, fromVersion: number, toVersion: number): AggregateError;
+    /**
+     * Error for configuration problems
+     */
+    static configurationError(aggregateType: string, message: string): AggregateError;
+    /**
+     * Error for when apply method interception fails (e.g. method not found)
+     */
+    static cannotInterceptApplyMethod(aggergateId: string, data?: DomainErrorOptions): AggregateError;
+    /**
+     * Error for when event store is not configured
+     */
+    static eventStoreNotConfigured(data?: DomainErrorOptions): AggregateError;
+    /**
+     * Error for when aggregate does not support event replay
+     */
+    static aggregateDoesNotSupportReplay(aggregateType: string, data?: DomainErrorOptions): AggregateError;
+}

package/dist/aggregate-interfaces.d.ts

@@ -0,0 +1,398 @@
+import { Capability, CapabilityConstructor, EntityId, IAggregateSnapshot, IAuditEvent, IDomainEvent, IEventMetadata, IEventStore, IEventUpcaster } from '@vytches/ddd-contracts';
+/**
+ * Core interface for aggregate root functionality.
+ * Provides the foundation for domain aggregates with event sourcing, versioning, and capability management.
+ */
+export interface IAggregateRoot<TId = string> {
+    /**
+     * Returns the aggregate identifier
+     * @returns The unique identifier for this aggregate
+     */
+    getId(): EntityId<TId>;
+    /**
+     * Returns the current version of the aggregate
+     * @returns Current version number for optimistic locking
+     */
+    getVersion(): number;
+    /**
+     * Returns the initial version when the aggregate was loaded
+     * @returns Initial version number when loaded from storage
+     */
+    getInitialVersion(): number;
+    /**
+     * Checks if the aggregate has uncommitted changes
+     * @returns True if there are uncommitted domain events
+     */
+    hasChanges(): boolean;
+    /**
+     * Returns uncommitted domain events
+     * @returns Readonly array of uncommitted domain events
+     */
+    getDomainEvents(): ReadonlyArray<IDomainEvent>;
+    /**
+     * Clears all uncommitted domain events and updates initial version
+     */
+    commit(): void;
+    /**
+     * Adds a capability to the aggregate
+     * @param capability - The capability instance to add
+     * @returns The aggregate instance for method chaining
+     */
+    addCapability<T extends Capability & IAggregateCapability>(capability: T): this;
+    /**
+     * Gets a specific capability by its constructor
+     * @param CapabilityClass - Constructor of the capability to retrieve
+     * @returns The capability instance or undefined if not found
+     */
+    getCapability<T extends Capability & IAggregateCapability>(CapabilityClass: CapabilityConstructor<T>): T | undefined;
+    /**
+     * Checks if aggregate has a specific capability
+     * @param CapabilityClass - Constructor of the capability to check
+     * @returns True if the capability is present
+     */
+    hasCapability<T extends Capability & IAggregateCapability>(CapabilityClass: CapabilityConstructor<T>): boolean;
+    /**
+     * Removes a capability from the aggregate
+     * @param {CapabilityClass} - Constructor of the capability to remove
+     * @returns The aggregate instance for method chaining
+     */
+    removeCapability<T extends Capability & IAggregateCapability>(CapabilityClass: CapabilityConstructor<T>): this;
+}
+/**
+ * Parameters for aggregate construction.
+ * Defines the minimal required data to create an aggregate instance.
+ */
+export interface IAggregateConstructorParams<TId = string> {
+    /** Unique identifier for the aggregate */
+    id: EntityId<TId>;
+    /** Initial version number, defaults to 0 */
+    version?: number;
+    /**
+     * Optional advisory limit on uncommitted domain events. If `apply()` is
+     * called when `_domainEvents.length >= maxEvents`, an error is thrown.
+     *
+     * Use to guard against runaway loops or replays of corrupted/malicious
+     * event streams that could allocate unbounded memory. A typical value is
+     * 10_000 — high enough that legitimate aggregates never hit it, low
+     * enough that a bug allocates seconds of memory, not gigabytes.
+     *
+     * REL-007 (2026-05-08): added as a defensive default-off safeguard.
+     * Leave undefined for "no limit" (preserves backward compatibility).
+     */
+    maxEvents?: number;
+}
+/**
+ * Base interface for all aggregate capabilities.
+ * Capabilities extend aggregate functionality with features like snapshots, versioning, and event sourcing.
+ */
+export interface IAggregateCapability {
+    /**
+     * Called when capability is attached to an aggregate
+     * @param aggregate The aggregate to attach to
+     */
+    attach(aggregate: IAggregateRoot<unknown>): void;
+    /**
+     * Called when capability is detached from an aggregate
+     */
+    detach?(): void;
+}
+/**
+ * Capability for creating and restoring aggregate snapshots.
+ * Enables performance optimization by periodically saving aggregate state.
+ */
+export interface ISnapshotCapability<TState = unknown, TMeta = unknown> extends IAggregateCapability {
+    /**
+     * Creates a snapshot of the current aggregate state
+     */
+    createSnapshot(serializer: () => TState, metadataCreator?: () => TMeta): IAggregateSnapshot<TState, TMeta>;
+    /**
+     * Restores aggregate state from a snapshot
+     */
+    restoreFromSnapshot(snapshot: IAggregateSnapshot<TState, TMeta>, deserializer: (state: TState) => void, metadataRestorer?: (metadata: TMeta) => void): void;
+    /**
+     * Saves current state temporarily (for audit purposes)
+     */
+    saveSnapshot(serializer: () => TState, metadataCreator?: () => TMeta): void;
+    /**
+     * Gets and clears the previous state
+     */
+    getPreviousState(): unknown | null;
+}
+/**
+ * Capability for handling event versioning and upcasting.
+ * Enables backward compatibility when event schemas evolve.
+ */
+export interface IVersioningCapability extends IAggregateCapability {
+    /**
+     * Registers an upcaster for a specific event type and version
+     */
+    registerUpcaster<TFrom = unknown, TTo = unknown>(eventType: string, sourceVersion: number, upcaster: IEventUpcaster<TFrom, TTo>): this;
+    /**
+     * Handles versioned event processing
+     */
+    handleVersionedEvent(event: IDomainEvent, handlers: Map<string, IAggregateEventHandler>): void;
+}
+/**
+ * Capability for event store integration.
+ * Enables loading and saving aggregates from/to event stores.
+ */
+export interface IEventSourcingCapability extends IAggregateCapability {
+    /**
+     * Loads aggregate from event store
+     */
+    loadFromEventStore(aggregateId: unknown): Promise<void>;
+    /**
+     * Saves aggregate events to event store
+     */
+    saveToEventStore(): Promise<void>;
+    /**
+     * Replays events to rebuild aggregate state
+     */
+    replayEvents(events: IDomainEvent[]): void;
+}
+/**
+ * Capability for maintaining audit logs of aggregate changes.
+ * Tracks all modifications for compliance and debugging purposes.
+ */
+export interface IAuditCapability extends IAggregateCapability {
+    /**
+     * Gets the audit log for this aggregate
+     */
+    getAuditLog(): ReadonlyArray<IAuditEvent>;
+    /**
+     * Clears the audit log
+     */
+    clearAuditLog(): void;
+}
+/**
+ * Capability for adding middleware to event processing pipeline.
+ * Enables cross-cutting concerns like validation, logging, and transformation.
+ */
+export interface IMiddlewareCapability extends IAggregateCapability {
+    /**
+     * Adds middleware to the event processing pipeline
+     */
+    use(middleware: EventAggregateMiddleware): this;
+}
+/**
+ * Builder interface for creating aggregates with capabilities.
+ * Provides fluent API for configuring aggregate features before construction.
+ */
+export interface IAggregateBuilder<TId> {
+    /**
+     * Adds snapshot capability
+     */
+    withSnapshots<TState = unknown, TMeta = unknown>(): this;
+    /**
+     * Adds versioning capability
+     */
+    withVersioning(): this;
+    /**
+     * Adds event sourcing capability
+     */
+    withEventSourcing(eventStore?: IEventStore): this;
+    /**
+     * Adds audit capability
+     */
+    withAudit(): this;
+    /**
+     * Adds custom capability
+     */
+    withCustomCapability<T extends IAggregateCapability>(name: string, capability: T): this;
+    /**
+     * Builds the aggregate with all configured capabilities
+     */
+    build(): IAggregateRoot<TId>;
+}
+/**
+ * Handler function for processing aggregate events.
+ * Used internally by aggregates to handle domain events.
+ */
+export interface IAggregateEventHandler<T = unknown> {
+    (payload: T, metadata?: IEventMetadata): void;
+}
+/**
+ * Middleware function for event processing pipeline.
+ * Enables interception and modification of events before they are handled.
+ */
+export type EventAggregateMiddleware<T = unknown> = (event: IDomainEvent<T>, next: (event: IDomainEvent<T>) => void) => void;
+/**
+ * @deprecated Use capability constructors directly instead of string names
+ * Constants for standard capability names.
+ */
+export declare const CAPABILITY_NAMES: {
+    readonly SNAPSHOT: "snapshot";
+    readonly VERSIONING: "versioning";
+    readonly EVENT_SOURCING: "eventSourcing";
+    readonly AUDIT: "audit";
+    readonly MIDDLEWARE: "middleware";
+};
+/**
+ * @deprecated Use capability constructors directly instead of string names
+ * Union type of all standard capability names.
+ */
+export type CapabilityName = (typeof CAPABILITY_NAMES)[keyof typeof CAPABILITY_NAMES];
+/**
+ * Utility type to extract the ID type from an aggregate type.
+ */
+export type AggregateIdType<T> = T extends IAggregateRoot<infer TId> ? TId : never;
+/**
+ * @deprecated Use capability constructors directly instead of string-based capabilities
+ * Utility type for aggregates with specific capabilities.
+ */
+export type AggregateWithCapabilities<TId, TCapabilities extends CapabilityName[]> = IAggregateRoot<TId> & {
+    [K in TCapabilities[number] as `getCapability`]: (name: K) => K extends 'snapshot' ? ISnapshotCapability : K extends 'versioning' ? IVersioningCapability : K extends 'eventSourcing' ? IEventSourcingCapability : K extends 'audit' ? IAuditCapability : K extends 'middleware' ? IMiddlewareCapability : IAggregateCapability;
+};
+/**
+ * Factory interface for creating and rebuilding aggregates.
+ * Provides standard methods for aggregate lifecycle management.
+ * @template TId - The type of the aggregate ID value (string, number, etc.)
+ */
+export interface IAggregateFactory<TId = string, TAggregate extends IAggregateRoot<TId> = IAggregateRoot<TId>> {
+    /**
+     * Creates a new aggregate instance
+     */
+    create(id: EntityId<TId>, ...args: unknown[]): TAggregate;
+    /**
+     * Rebuilds aggregate from events
+     */
+    fromEvents(id: EntityId<TId>, events: IDomainEvent[]): TAggregate;
+    /**
+     * Rebuilds aggregate from snapshot and subsequent events
+     */
+    fromSnapshot<TState, TMeta>(snapshot: IAggregateSnapshot<TState, TMeta>, events: IDomainEvent[]): TAggregate;
+}
+/**
+ * Interface for validating aggregate state and operations.
+ * Enables business rule validation at the aggregate level.
+ */
+export interface IAggregateValidator<TAggregate extends IAggregateRoot<unknown>> {
+    /**
+     * Validates aggregate state
+     */
+    validate(aggregate: TAggregate): ValidationResult;
+    /**
+     * Validates aggregate before applying event
+     */
+    validateBeforeEvent(aggregate: TAggregate, event: IDomainEvent): ValidationResult;
+}
+/**
+ * Result of aggregate validation operation.
+ * Contains validation status and any error details.
+ */
+export interface ValidationResult {
+    /** Whether the validation passed */
+    isValid: boolean;
+    /** List of validation errors if any */
+    errors: IValidationError[];
+}
+/**
+ * Represents a single validation error.
+ * Provides details about what failed validation and why.
+ */
+export interface IValidationError {
+    /** The field or property that failed validation */
+    field: string;
+    /** Human-readable error message */
+    message: string;
+    /** Optional error code for programmatic handling */
+    code?: string;
+}
+/**
+ * Capability for caching aggregate data.
+ * Provides key-value storage with TTL support for performance optimization.
+ */
+export interface ICachingCapability extends IAggregateCapability {
+    /**
+     * Gets cached value
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Sets cached value
+     */
+    set<T>(key: string, value: T, ttl?: number): void;
+    /**
+     * Clears all cached values
+     */
+    clear(): void;
+    /**
+     * Invalidates specific cached value
+     */
+    invalidate(key: string): void;
+}
+/**
+ * Capability for collecting aggregate metrics.
+ * Enables monitoring and observability of aggregate operations.
+ */
+export interface IMetricsCapability extends IAggregateCapability {
+    /**
+     * Records a metric
+     */
+    record(name: string, value: number, tags?: Record<string, string>): void;
+    /**
+     * Increments a counter
+     */
+    increment(name: string, tags?: Record<string, string>): void;
+    /**
+     * Records timing information
+     */
+    timing(name: string, duration: number, tags?: Record<string, string>): void;
+    /**
+     * Gets recorded metrics
+     */
+    getMetrics(): MetricData[];
+}
+/**
+ * Represents a single metric data point.
+ * Contains metric information with optional tags and timestamp.
+ */
+export interface MetricData {
+    /** Metric name */
+    name: string;
+    /** Metric value */
+    value: number;
+    /** Type of metric */
+    type: 'counter' | 'gauge' | 'timing';
+    /** Optional tags for metric categorization */
+    tags?: Record<string, string>;
+    /** When the metric was recorded */
+    timestamp: Date;
+}
+/**
+ * Capability for security features like encryption and authorization.
+ * Provides security controls for sensitive aggregate operations.
+ */
+export interface ISecurityCapability extends IAggregateCapability {
+    /**
+     * Encrypts sensitive data
+     */
+    encrypt(data: unknown): string;
+    /**
+     * Decrypts sensitive data
+     */
+    decrypt(encryptedData: string): unknown;
+    /**
+     * Checks if user has permission to perform action
+     */
+    hasPermission(action: string, user?: unknown): boolean;
+    /**
+     * Logs security events
+     */
+    logSecurityEvent(event: SecurityEvent): void;
+}
+/**
+ * Represents a security-related event.
+ * Used for audit trails and security monitoring.
+ */
+export interface SecurityEvent {
+    /** Type of security event */
+    type: 'access' | 'modification' | 'failure';
+    /** Action that was performed */
+    action: string;
+    /** User who performed the action */
+    user?: unknown;
+    /** When the event occurred */
+    timestamp: Date;
+    /** Additional event metadata */
+    metadata?: Record<string, unknown>;
+}

package/dist/capabilities/audit-capability.d.ts

@@ -0,0 +1,95 @@
+import { Capability, IAuditCapability, IAuditEvent, IDomainEvent } from '../../../contracts/src/index.ts';
+/**
+ * Capability that records every domain event applied to the aggregate as
+ * an `IAuditEvent`. Useful for compliance, debugging, behavior analytics,
+ * and "what happened" forensics — without polluting the aggregate's
+ * domain logic with cross-cutting audit concerns.
+ *
+ * Mechanism: on attach, intercepts the aggregate's `apply()` method. Every
+ * subsequent `apply(eventName, payload)` call records an `IAuditEvent`
+ * containing the aggregate id, type, version at time of event, original
+ * payload, and an actor (read from `metadata.userId` if present). The
+ * intercepted `apply` is restored on `detach()`.
+ *
+ * **Order matters.** Add this capability *before* any `apply()` calls —
+ * audit only captures events applied after attachment. The recommended
+ * way is via {@link AggregateBuilder} which guarantees correct order.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   AggregateBuilder,
+ *   AuditCapability,
+ *   asAuditAggregate,
+ * } from '@vytches/ddd-aggregates';
+ *
+ * const order = AggregateBuilder
+ *   .create({ id: EntityId.create() })
+ *   .withAudit()
+ *   .build(Order);
+ *
+ * order.apply('OrderCreated', { customerId: 'c-1' }, { userId: 'u-42' });
+ * order.apply('OrderConfirmed', undefined, { userId: 'u-42' });
+ *
+ * const audit = asAuditAggregate(order).getCapability(AuditCapability)!;
+ * audit.getAuditLog();         // [{ eventName: 'OrderCreated', actor: 'u-42', ... }, ...]
+ * audit.getEventsByName('OrderCreated');
+ * audit.getAuditStatistics(); // { totalEvents: 2, eventsByType: {...}, averageTimeBetweenEvents }
+ * ```
+ *
+ * @public
+ * @stable
+ * @since 0.1.0
+ */
+export declare class AuditCapability extends Capability<'audit'> implements IAuditCapability {
+    readonly type: "audit";
+    static get capabilityType(): string;
+    private aggregate;
+    private auditLog;
+    private originalApply?;
+    /**
+     * @param {unknown} aggregate - Aggregate to attach this capability to
+     */
+    attach(aggregate: unknown): void;
+    detach?(): void;
+    /**
+     * @returns {IAuditEvent[]} Copy of the current audit log
+     */
+    getAuditLog(): IAuditEvent[];
+    clearAuditLog(): void;
+    /**
+     * @returns {{totalEvents: number, eventsByType: Record<string, number>, averageTimeBetweenEvents: number}} Audit statistics summary
+     */
+    getAuditStatistics(): {
+        totalEvents: number;
+        eventsByType: Record<string, number>;
+        averageTimeBetweenEvents: number;
+    };
+    /**
+     * Record an audit event when domain events are added
+     */
+    private recordAuditEvent;
+    /**
+     * @param {IDomainEvent} event - Domain event to record in audit log
+     */
+    recordEvent(event: IDomainEvent): void;
+    /**
+     * @param {string} eventName - Name of events to filter by
+     * @returns {IAuditEvent[]} Array of audit events matching the specified name
+     */
+    getEventsByName(eventName: string): IAuditEvent[];
+    /**
+     * @param {Date} startDate - Start date for time range filter
+     * @param {Date} endDate - End date for time range filter
+     * @returns {IAuditEvent[]} Array of audit events within the specified time range
+     */
+    getEventsByTimeRange(startDate: Date, endDate: Date): IAuditEvent[];
+    /**
+     * @returns {IAuditEvent | null} First audit event in chronological order or null if none exists
+     */
+    getFirstEvent(): IAuditEvent | null;
+    /**
+     * @returns {IAuditEvent | null} Last audit event in chronological order or null if none exists
+     */
+    getLastEvent(): IAuditEvent | null;
+}

package/dist/capabilities/event-sourcing-capability.d.ts

@@ -0,0 +1,79 @@
+import { IEventSourcingCapability, IEventStore, Capability } from '../../../contracts/src/index.ts';
+/**
+ * Capability that integrates an aggregate with an external `IEventStore` —
+ * the persistence boundary for an event-sourced system. Allows the
+ * aggregate to load its own state from history and persist new events
+ * without coupling domain code to the storage adapter.
+ *
+ * **Important**: this library is dependency-free and ships *no* concrete
+ * `IEventStore` implementation. Provide your own (in-memory, EventStoreDB,
+ * Postgres + JSONB, Kafka topic, etc.) and pass it via
+ * {@link setEventStore}.
+ *
+ * @example Wiring up with a custom store
+ * ```typescript
+ * import {
+ *   AggregateBuilder,
+ *   EventSourcingCapability,
+ * } from '@vytches/ddd-aggregates';
+ *
+ * const eventStore: IEventStore = new MyPostgresEventStore(pool);
+ *
+ * const order = AggregateBuilder
+ *   .create({ id })
+ *   .withEventSourcing()
+ *   .build(Order);
+ *
+ * const es = order.getCapability(EventSourcingCapability)!;
+ * es.setEventStore(eventStore);
+ *
+ * await es.saveToStore();          // persists uncommitted events, increments version
+ * await es.loadFromStore();        // hydrates aggregate from stream
+ * ```
+ *
+ * @public
+ * @stable
+ * @since 0.1.0
+ */
+export declare class EventSourcingCapability extends Capability<'eventSourcing'> implements IEventSourcingCapability {
+    readonly type: "eventSourcing";
+    static get capabilityType(): string;
+    private aggregate;
+    private eventStore;
+    /**
+     * @param {unknown} aggregate - Aggregate to attach this capability to
+     */
+    attach(aggregate: unknown): void;
+    detach?(): void;
+    /**
+     * @param {IEventStore} eventStore - Event store instance to use for persistence
+     */
+    setEventStore(eventStore: IEventStore): void;
+    /**
+     * @returns {IEventStore | null} Currently configured event store or null
+     */
+    getEventStore(): IEventStore | null;
+    /**
+     * @param {string | number} aggregateId - ID of aggregate to load events for
+     * @throws {AggregateError} When event store is not configured
+     */
+    loadFromEventStore(aggregateId: string | number): Promise<void>;
+    /**
+     * @throws {AggregateError} When event store is not configured
+     */
+    saveToEventStore(): Promise<void>;
+    /**
+     * @returns {boolean} True if event store is configured
+     */
+    hasEventStore(): boolean;
+    /**
+     * @returns {string} Stream name combining aggregate type and ID
+     */
+    getStreamName(): string;
+    /**
+     * @param {string | number} aggregateId - ID of aggregate to load events for
+     * @param {number} fromVersion - Version number to start loading from
+     * @throws {AggregateError} When event store is not configured
+     */
+    loadFromVersion(aggregateId: string | number, fromVersion: number): Promise<void>;
+}

package/dist/capabilities/index.d.ts

@@ -0,0 +1,4 @@
+export * from './snapshot-capability';
+export * from './event-sourcing-capability';
+export * from './audit-capability';
+export * from './versioning-capability';