@vytches/ddd-aggregates 0.26.0

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

@@ -0,0 +1,113 @@
+import { IAggregateSnapshot, ISnapshotCapability, Capability } from '../../../contracts/src/index.ts';
+/**
+ * Capability that enables snapshot creation and restoration on an aggregate
+ * — a performance optimization for event-sourced aggregates with long
+ * event histories. Instead of replaying all events to reconstitute state,
+ * load a recent snapshot and replay only events after it.
+ *
+ * Attach via {@link AggregateBuilder} (preferred) or directly with
+ * `aggregate.addCapability(new SnapshotCapability())`. The capability
+ * stores its state inside the aggregate's `CapabilityRegistry` — there is
+ * no separate persistence; *you* serialize/deserialize the aggregate's
+ * fields via callbacks.
+ *
+ * Two operations:
+ *
+ * - {@link createSnapshot} — produce an `IAggregateSnapshot<TState, TMeta>`
+ *   capturing version, type, id, and a state slice you choose. Hand off to
+ *   your snapshot store (database, blob, file).
+ * - {@link restoreFromSnapshot} — load a snapshot, validate id/type match,
+ *   and restore the aggregate's version + reset uncommitted events. The
+ *   `deserializer` callback is responsible for putting state back into
+ *   the aggregate's private fields.
+ *
+ * @example Creating a snapshot from inside the aggregate
+ * ```typescript
+ * import {
+ *   AggregateRoot,
+ *   AggregateBuilder,
+ *   SnapshotCapability,
+ * } from '@vytches/ddd-aggregates';
+ *
+ * interface OrderState { amount: number; customerId: string; }
+ *
+ * class Order extends AggregateRoot<string> {
+ *   private amount = 0;
+ *   private customerId = '';
+ *
+ *   takeSnapshot(): IAggregateSnapshot<OrderState> {
+ *     const cap = this.getCapability(SnapshotCapability)!;
+ *     return cap.createSnapshot<OrderState>(() => ({
+ *       amount: this.amount,
+ *       customerId: this.customerId,
+ *     }));
+ *   }
+ *
+ *   restore(snap: IAggregateSnapshot<OrderState>): void {
+ *     const cap = this.getCapability(SnapshotCapability)!;
+ *     cap.restoreFromSnapshot(snap, state => {
+ *       this.amount = state.amount;
+ *       this.customerId = state.customerId;
+ *     });
+ *   }
+ * }
+ *
+ * const order = AggregateBuilder
+ *   .create({ id: EntityId.create() })
+ *   .withSnapshots()
+ *   .build(Order);
+ *
+ * const snap = order.takeSnapshot();
+ * await snapshotStore.save(snap);
+ * ```
+ *
+ * @remarks
+ * `restoreFromSnapshot` calls the aggregate's `_internal_setState` —
+ * this is intentional and required, but means snapshots must be the
+ * very first restoration step before any subsequent event replay.
+ *
+ * @public
+ * @stable
+ * @since 0.1.0
+ */
+export declare class SnapshotCapability<TState = unknown, TMeta = unknown> extends Capability<'snapshot'> implements ISnapshotCapability<TState, TMeta> {
+    readonly type: "snapshot";
+    static get capabilityType(): string;
+    private aggregate;
+    private _snapshot;
+    /**
+     * @param {unknown} aggregate - Aggregate to attach this capability to
+     */
+    attach(aggregate: unknown): void;
+    detach?(): void;
+    /**
+     * @param {() => TState} serializer - Function to serialize aggregate state
+     * @param {() => TMeta} metadataCreator - Optional function to create snapshot metadata
+     * @returns {IAggregateSnapshot<TState, TMeta>} Created snapshot with state and metadata
+     */
+    createSnapshot(serializer: () => TState, metadataCreator?: () => TMeta): IAggregateSnapshot<TState, TMeta>;
+    /**
+     * @param {IAggregateSnapshot<TState, TMeta>} snapshot - Snapshot to restore from
+     * @param {(state: TState) => void} deserializer - Function to deserialize state into aggregate
+     * @param {(metadata: TMeta) => void} metadataRestorer - Optional function to restore metadata
+     * @throws {AggregateError} When snapshot is invalid or IDs don't match
+     */
+    restoreFromSnapshot(snapshot: IAggregateSnapshot<TState, TMeta>, deserializer: (state: TState) => void, metadataRestorer?: (metadata: TMeta) => void): void;
+    /**
+     * @param {TState} state - State to save temporarily
+     */
+    saveTemporaryState?(state: TState): void;
+    /**
+     * @returns {Date | null} Timestamp of last snapshot or null if none exists
+     */
+    getLastSnapshotTimestamp?(): Date | null;
+    /**
+     * @param {() => TState} serializer - Function to serialize aggregate state
+     * @param {() => TMeta} metadataCreator - Optional metadata creator function
+     */
+    saveSnapshot(serializer: () => TState, metadataCreator?: () => TMeta): void;
+    /**
+     * @returns {IAggregateSnapshot<TState, TMeta> | null} Previous snapshot state if exists
+     */
+    getPreviousState(): IAggregateSnapshot<TState, TMeta> | null;
+}

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

@@ -0,0 +1,93 @@
+import { Capability, IVersioningCapability, IDomainEvent, IEventUpcaster } from '../../../contracts/src/index.ts';
+import { IAggregateEventHandler } from '../aggregate-interfaces';
+/**
+ * Capability that handles **event schema evolution** — when a stored event
+ * shape changes between releases, register an `IEventUpcaster` to migrate
+ * old payloads forward at replay time.
+ *
+ * Pattern: each event has an implicit version (default 1). Newer aggregate
+ * code expects newer-version payload shape. Old events from history are
+ * passed through registered upcasters in version order until they reach
+ * the current version, then the regular event handler runs.
+ *
+ * Without versioning, you must keep old event handlers around forever or
+ * write migration scripts. With versioning, code stays clean and history
+ * stays immutable.
+ *
+ * @example Adding a field with a default
+ * ```typescript
+ * import {
+ *   AggregateBuilder,
+ *   VersioningCapability,
+ * } from '@vytches/ddd-aggregates';
+ *
+ * // v1 payload had no "currency"; v2 requires it.
+ * const order = AggregateBuilder
+ *   .create({ id })
+ *   .withVersioning()
+ *   .build(Order);
+ *
+ * const versioning = order.getCapability(VersioningCapability)!;
+ * versioning.registerUpcaster('OrderCreated', 1, oldPayload => ({
+ *   ...oldPayload,
+ *   currency: 'USD',  // sane default for legacy events
+ * }));
+ * ```
+ *
+ * @example Renaming a field
+ * ```typescript
+ * versioning.registerUpcaster('CustomerUpdated', 1, oldPayload => {
+ *   const { fullName, ...rest } = oldPayload as { fullName: string };
+ *   return { ...rest, displayName: fullName };
+ * });
+ * ```
+ *
+ * @public
+ * @stable
+ * @since 0.1.0
+ */
+export declare class VersioningCapability extends Capability<'versioning'> implements IVersioningCapability {
+    readonly type: "versioning";
+    static get capabilityType(): string;
+    private aggregate;
+    private upcasters;
+    /**
+     * @param {unknown} aggregate - Aggregate to attach this capability to
+     */
+    attach(aggregate: unknown): void;
+    detach?(): void;
+    /**
+     * @param {string} eventType - Type of event to register upcaster for
+     * @param {number} sourceVersion - Source version number to upcast from
+     * @param {IEventUpcaster<TFrom, TTo>} upcaster - Upcaster instance to transform events
+     */
+    registerUpcaster<TFrom = unknown, TTo = unknown>(eventType: string, sourceVersion: number, upcaster: IEventUpcaster<TFrom, TTo>): void;
+    /**
+     * @param {IDomainEvent} event - Event to process with version handling
+     * @param {Map<string, IAggregateEventHandler>} handlers - Map of event handlers
+     */
+    handleVersionedEvent(event: IDomainEvent, handlers: Map<string, IAggregateEventHandler>): void;
+    /**
+     * @returns {string[]} Array of event types that have registered upcasters
+     */
+    getRegisteredEventTypes(): string[];
+    /**
+     * @param {string} eventType - Event type to check
+     * @param {number} version - Version number to check for upcaster
+     * @returns {boolean} True if upcaster exists for specified event type and version
+     */
+    hasUpcaster(eventType: string, version: number): boolean;
+    /**
+     * @param {string} eventType - Event type to get upcasters for
+     * @returns {Map<number, IEventUpcaster> | undefined} Map of upcasters by version or undefined
+     */
+    getUpcastersForType(eventType: string): Map<number, IEventUpcaster> | undefined;
+    /**
+     * @param {string} eventType - Event type to clear upcasters for
+     */
+    clearUpcastersForType(eventType: string): void;
+    /**
+     * @returns {number} Total count of all registered upcasters across all event types
+     */
+    getTotalUpcasterCount(): number;
+}

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

@@ -0,0 +1,110 @@
+import { Capability, IEventStore, EntityId } from '../../../contracts/src/index.ts';
+import { IAggregateCapability, IAggregateConstructorParams } from '../aggregate-interfaces';
+import { AggregateRoot } from './aggregate-root';
+/**
+ * Fluent builder for assembling an aggregate root with a custom mix of
+ * capabilities (snapshots, audit, versioning, event sourcing) — without
+ * inheritance chains or constructor explosion.
+ *
+ * Why a builder? Capabilities have order-sensitive setup (audit must
+ * intercept `apply()` before any events are recorded) and many aggregates
+ * use only some of them. Hard-coding a base class with all four capabilities
+ * pulls in machinery you may not need; manual wiring is error-prone. The
+ * builder makes order correct by construction.
+ *
+ * @example Single capability
+ * ```typescript
+ * import { AggregateBuilder } from '@vytches/ddd-aggregates';
+ * import { EntityId } from '@vytches/ddd-value-objects';
+ *
+ * const order = AggregateBuilder
+ *   .create({ id: EntityId.create() })
+ *   .withSnapshots()
+ *   .build(Order);
+ * ```
+ *
+ * @example Multiple capabilities, ordered automatically
+ * ```typescript
+ * const order = AggregateBuilder
+ *   .create({ id: EntityId.create() })
+ *   .withVersioning()
+ *   .withAudit()
+ *   .withSnapshots()
+ *   .withEventSourcing(myEventStore)
+ *   .build(Order);
+ * ```
+ *
+ * @example Shorthand — all four built-in capabilities
+ * ```typescript
+ * const order = AggregateBuilder
+ *   .create({ id })
+ *   .buildWithAllCapabilities(Order);
+ * ```
+ *
+ * @example Reconstituting from history with capabilities pre-attached
+ * ```typescript
+ * const order = AggregateBuilder
+ *   .create({ id, version: 0 })
+ *   .withAudit()
+ *   .build(Order);
+ * order.loadFromHistory(eventsFromStore);
+ * ```
+ *
+ * @public
+ * @stable
+ * @since 0.1.0
+ */
+export declare class AggregateBuilder<TId = string> {
+    private params;
+    private capabilities;
+    private eventStore?;
+    private constructor();
+    /**
+     * @returns Aggregate
+     */
+    static create<TId = string>(params: {
+        id: TId | EntityId<TId>;
+        version?: number;
+    }): AggregateBuilder<TId>;
+    withSnapshots(): this;
+    /**
+     * @returns {this} Builder instance for method chaining
+     */
+    withVersioning(): this;
+    /**
+     * @returns {this} Builder instance for method chaining
+     */
+    withAudit(): this;
+    /**
+     * @param {IEventStore} [eventStore] - Optional event store for event sourcing
+     * @returns {this} Builder instance for method chaining
+     */
+    withEventSourcing(eventStore?: IEventStore): this;
+    /**
+     * @param {T} capability - Custom capability instance to add
+     * @param {(cap: T) => void} configure - Optional configuration function for the capability
+     * @returns {this} Builder instance for method chaining
+     */
+    withCapability<T extends Capability & IAggregateCapability>(capability: T, configure?: (cap: T) => void): this;
+    /**
+     * @param {IEventStore} eventStore - Event store instance for event sourcing capability
+     * @returns {this} Builder instance for method chaining
+     */
+    setEventStore(eventStore: IEventStore): this;
+    build<TAgg extends AggregateRoot<TId> = AggregateRoot<TId>>(AggregateClass?: new (params: IAggregateConstructorParams<TId>) => TAgg): TAgg;
+    /**
+     * @param {new (params: IAggregateConstructorParams<TId>) => TAgg} AggregateClass - Optional aggregate class constructor
+     * @returns {TAgg} Fully configured aggregate with all standard capabilities
+     */
+    buildWithAllCapabilities<TAgg extends AggregateRoot<TId> = AggregateRoot<TId>>(AggregateClass?: new (params: IAggregateConstructorParams<TId>) => TAgg): TAgg;
+}
+/**
+ * @param {object} params - Parameters for creating aggregate builder
+ * @param {TId | EntityId<TId>} params.id - Entity identifier
+ * @param {number} [params.version] - Optional version number
+ * @returns {AggregateBuilder<TId>} New aggregate builder instance
+ */
+export declare function aggregateBuilder<TId = string>(params: {
+    id: TId | EntityId<TId>;
+    version?: number;
+}): AggregateBuilder<TId>;

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

@@ -0,0 +1,201 @@
+import { IAggregateCapability, IAggregateConstructorParams, IAggregateEventHandler, IAggregateRoot } from '../aggregate-interfaces';
+import { Capability, CapabilityConstructor, EntityId, IDomainEvent, IEventMetadata } from '../../../contracts/src/index.ts';
+/**
+ * Base class for aggregate roots — the *transactional consistency boundary*
+ * of a Domain-Driven Design model. Per Eric Evans (Blue Book, ch. 6):
+ *
+ * > An AGGREGATE is a cluster of associated objects that we treat as a unit
+ * > for the purpose of data changes. Each AGGREGATE has a root and a
+ * > boundary. The root is a single, specific ENTITY contained in the
+ * > AGGREGATE. The root is the only member of the AGGREGATE that outside
+ * > objects are allowed to hold references to.
+ *
+ * `AggregateRoot<TId>` provides:
+ *
+ * - **Identity** via `EntityId<TId>` (`getId()`)
+ * - **Versioning** for optimistic locking (`getVersion()`,
+ *   `getInitialVersion()`)
+ * - **Event emission** via `apply()` — append a `DomainEvent`, increment
+ *   version, run the registered handler to mutate state
+ * - **Event sourcing reconstitution** via `loadFromHistory()` — replay
+ *   events without accumulating new ones
+ * - **Capabilities** — composable, opt-in features (snapshots, audit,
+ *   versioning, event-sourcing) attached without inheritance chains
+ *   (see {@link AggregateBuilder})
+ *
+ * Two state-mutation rules:
+ *
+ * 1. **Never assign fields directly.** All state changes flow through
+ *    `apply(eventType, payload)` so they are recorded as events. Direct
+ *    assignment bypasses event recording and version tracking — the
+ *    aggregate becomes inconsistent with its event stream.
+ * 2. **Register handlers BEFORE applying events.** Wire every event name
+ *    in the constructor via `registerEventHandler('EventName', payload =>
+ *    {...})` before any `apply()` call. Missing handlers do not throw —
+ *    the event is recorded but state remains stale.
+ *
+ * For non-root domain entities (`OrderLine` inside `Order`), use
+ * {@link Entity} — it has identity but no version/event machinery.
+ *
+ * @example Minimal event-sourced aggregate
+ * ```typescript
+ * import { AggregateRoot } from '@vytches/ddd-aggregates';
+ * import { EntityId } from '@vytches/ddd-contracts';
+ *
+ * interface OrderCreatedPayload {
+ *   customerId: string;
+ *   amount: number;
+ * }
+ *
+ * class Order extends AggregateRoot<string> {
+ *   private customerId = '';
+ *   private amount = 0;
+ *
+ *   constructor(params: IAggregateConstructorParams<string>) {
+ *     super(params);
+ *     this.registerEventHandler<OrderCreatedPayload>('OrderCreated', payload => {
+ *       this.customerId = payload!.customerId;
+ *       this.amount = payload!.amount;
+ *     });
+ *   }
+ *
+ *   static create(customerId: string, amount: number): Order {
+ *     const order = new Order({ id: EntityId.create(), version: 0 });
+ *     order.apply('OrderCreated', { customerId, amount });
+ *     return order;
+ *   }
+ * }
+ *
+ * const order = Order.create('c-1', 500);
+ * order.getVersion();         // 1
+ * order.getDomainEvents();    // [{ eventName: 'OrderCreated', ... }]
+ * order.commit();             // clear after persisting
+ * order.hasChanges();         // false
+ * ```
+ *
+ * @example Reconstituting from event history
+ * ```typescript
+ * class Order extends AggregateRoot<string> {
+ *   static fromEvents(id: EntityId<string>, events: IDomainEvent[]): Order {
+ *     const order = new Order({ id, version: 0 });
+ *     order.loadFromHistory(events);  // replays events, no new ones recorded
+ *     return order;
+ *   }
+ * }
+ * ```
+ *
+ * @example Bounded uncommitted-event count (REL-007 guard)
+ * ```typescript
+ * const order = new Order({
+ *   id: EntityId.create(),
+ *   version: 0,
+ *   maxEvents: 1000,  // throw if uncommitted events exceed 1000
+ * });
+ * ```
+ *
+ * @public
+ * @stable
+ * @since 0.1.0
+ */
+export declare class AggregateRoot<TId = string> implements IAggregateRoot<TId> {
+    private readonly _id;
+    private _version;
+    private _initialVersion;
+    private _domainEvents;
+    private _eventHandlers;
+    private _capabilities;
+    /**
+     * REL-007 (2026-05-08): optional advisory limit on uncommitted events.
+     * Undefined = no limit (default, backward-compat). When set, `apply()`
+     * throws if pushing would exceed the limit — guards against runaway
+     * loops or malicious replay payloads.
+     */
+    private readonly _maxEvents;
+    constructor(params: IAggregateConstructorParams<TId>);
+    /**
+     * Get the unique identifier of this aggregate
+     */
+    getId(): EntityId<TId>;
+    /**
+     *
+     * @returns {number} Current version number for optimistic locking
+     */
+    getVersion(): number;
+    /**
+     *
+     * @returns {number} Initial version when aggregate was loaded
+     */
+    getInitialVersion(): number;
+    /**
+     *
+     * @returns {boolean} True if aggregate has uncommitted domain events
+     */
+    hasChanges(): boolean;
+    /**
+     *
+     * @returns {ReadonlyArray<IDomainEvent>} Array of uncommitted domain events
+     */
+    getDomainEvents(): ReadonlyArray<IDomainEvent>;
+    /**
+     * Clear all uncommitted domain events and update initial version
+     */
+    commit(): void;
+    /**
+     * @param {string} eventType - Event type to register handler for
+     * @param {IAggregateEventHandler<T>} handler - Event handler function
+     * @returns {this} The aggregate instance for method chaining
+     */
+    protected registerEventHandler<T>(eventType: string, handler: IAggregateEventHandler<T>): this;
+    /**
+     * Apply domain event to aggregate and add to pending events
+     * @param {string | IDomainEvent<P>} eventTypeOrEvent - Event type string or complete event object
+     * @param {P} payload - Event payload data
+     * @param {Partial<IEventMetadata>} metadata - Optional event metadata
+     */
+    protected apply<P = unknown>(eventTypeOrEvent: string | IDomainEvent<P>, payload?: P, metadata?: Partial<IEventMetadata>): void;
+    private handleEvent;
+    /**
+     * Reconstruct aggregate state from historical domain events
+     * @param {IDomainEvent[]} events - Array of events to replay for state reconstruction
+     */
+    protected loadFromHistory(events: IDomainEvent[]): void;
+    /**
+     * Add capability to enhance aggregate functionality
+     * @param {T} capability - Capability instance to add to the aggregate
+     * @returns {this} The aggregate instance for method chaining
+     */
+    addCapability<T extends Capability & IAggregateCapability>(capability: T): this;
+    /**
+     * @param {CapabilityConstructor<T>} CapabilityClass - Constructor of the capability to retrieve
+     * @returns {T | undefined} The capability instance or undefined if not found
+     */
+    getCapability<T extends Capability & IAggregateCapability>(CapabilityClass: CapabilityConstructor<T>): T | undefined;
+    /**
+     * @param {CapabilityConstructor<T>} CapabilityClass - Constructor of the capability to check
+     * @returns {boolean} True if the capability is present
+     */
+    hasCapability<T extends Capability & IAggregateCapability>(CapabilityClass: CapabilityConstructor<T>): boolean;
+    /**
+     * @param {CapabilityConstructor<T>} CapabilityClass - Constructor of the capability to remove
+     * @returns {this} The aggregate instance for method chaining
+     */
+    removeCapability<T extends Capability & IAggregateCapability>(CapabilityClass: CapabilityConstructor<T>): this;
+    /**
+     * @returns {Capability[]} Array of all registered capabilities
+     */
+    getAllCapabilities(): Capability[];
+    /**
+     * @returns {string[]} Array of capability type names
+     */
+    getCapabilityTypes(): string[];
+    private static sanitizeMetadata;
+    /**
+     * Internal method for capabilities to access private state
+     * Should only be used by capabilities, not directly by domain code
+     */
+    _internal_setState(state: {
+        version: number;
+        initialVersion: number;
+        domainEvents: IDomainEvent[];
+    }): void;
+}