@vytches/ddd-aggregates

@vytches/ddd-aggregates

Aggregate root implementation with event sourcing, optimistic concurrency, and opt-in capabilities.

Installation

pnpm add @vytches/ddd-aggregates

What's included

• AggregateRoot — base class for aggregate roots with identity, versioning, and domain events
• Entity — base class for non-root domain entities (identity-based equality, no event machinery)
• AggregateBuilder / aggregateBuilder — fluent builder for constructing aggregates with capabilities
• Capabilities — AuditCapability, EventSourcingCapability, SnapshotCapability, VersioningCapability
• Utility functions — type-safe capability casting and introspection
• AggregateError — error class for aggregate-specific failures

Usage

import { AggregateRoot } from '@vytches/ddd-aggregates';
import type { IAggregateConstructorParams } from '@vytches/ddd-aggregates';
import { EntityId } from '@vytches/ddd-contracts';

class Order extends AggregateRoot<string> {
  private customerId = '';
  private status: 'pending' | 'confirmed' = 'pending';

  constructor(params: IAggregateConstructorParams<string>) {
    super(params);
    this.registerEventHandler<{ customerId: string }>(
      'OrderCreated',
      payload => {
        this.customerId = payload!.customerId;
      }
    );
    this.registerEventHandler<void>('OrderConfirmed', () => {
      this.status = 'confirmed';
    });
  }

  static create(customerId: string): Order {
    const order = new Order({ id: EntityId.create(), version: 0 });
    order.apply('OrderCreated', { customerId });
    return order;
  }

  confirm(): void {
    if (this.status !== 'pending') throw new Error('Order is not pending');
    this.apply('OrderConfirmed', undefined);
  }

  getCustomerId(): string {
    return this.customerId;
  }
  getStatus(): string {
    return this.status;
  }
}

// Create an order
const order = Order.create('customer-123');
order.confirm();

// Domain events are collected until committed
const events = order.getDomainEvents(); // [OrderCreated, OrderConfirmed]
order.commit(); // clears collected events

With capabilities

import {
  aggregateBuilder,
  AuditCapability,
  SnapshotCapability,
} from '@vytches/ddd-aggregates';

const order = aggregateBuilder(Order)
  .withCapability(AuditCapability)
  .withCapability(SnapshotCapability)
  .build({ id: EntityId.create(), version: 0 });

Utility functions

import {
  asSnapshotAggregate,
  tryAsSnapshotAggregate,
  hasAllCapabilities,
  getAggregateCapabilities,
} from '@vytches/ddd-aggregates';
import { SnapshotCapability, AuditCapability } from '@vytches/ddd-aggregates';

// Type-safe capability access
const snapshotable = asSnapshotAggregate(order); // throws if missing
const maybeSnapshot = tryAsSnapshotAggregate(order); // returns null if missing

// Introspection
const hasAll = hasAllCapabilities(order, [SnapshotCapability, AuditCapability]);
const capabilities = getAggregateCapabilities(order);

Non-root entities

import { Entity } from '@vytches/ddd-aggregates';
import { EntityId } from '@vytches/ddd-contracts';

// Use Entity for inner aggregate objects like OrderLine, Address
class OrderLine extends Entity<string> {
  constructor(
    id: EntityId<string>,
    private sku: string,
    private quantity: number
  ) {
    super({ id });
  }
  getSku(): string {
    return this.sku;
  }
  getQuantity(): number {
    return this.quantity;
  }
}

API Reference

Core Classes

Export	Kind	Description
AggregateRoot<TId>	class	Base aggregate root; provides identity, versioning, event collection and event sourcing reconstitution
Entity<TId>	class	Base class for non-root domain entities; identity-based equality, no events
AggregateBuilder	class	Fluent builder for aggregates with capabilities
aggregateBuilder	function	Factory function shorthand for AggregateBuilder
AggregateError	class	Error thrown for aggregate-specific failures

Capabilities

Export	Kind	Description
AuditCapability	class	Records who created/modified the aggregate and when
EventSourcingCapability	class	Enables event sourcing reconstitution from stored events
SnapshotCapability	class	Enables taking and restoring state snapshots
VersioningCapability	class	Manages optimistic concurrency version tracking

Capability Utilities

Export	Kind	Description
asSnapshotAggregate(agg)	function	Cast to snapshot-capable aggregate; throws if missing
tryAsSnapshotAggregate(agg)	function	Cast to snapshot-capable aggregate; returns null if missing
asVersioningAggregate(agg)	function	Cast to versioning-capable aggregate; throws if missing
tryAsVersioningAggregate(agg)	function	Returns null if versioning capability absent
asAuditAggregate(agg)	function	Cast to audit-capable aggregate; throws if missing
tryAsAuditAggregate(agg)	function	Returns null if audit capability absent
asEventSourcingAggregate(agg)	function	Cast to event-sourcing aggregate; throws if missing
tryAsEventSourcingAggregate(agg)	function	Returns null if event sourcing capability absent
getAggregateCapabilities(agg)	function	Returns all capabilities attached to an aggregate
hasAllCapabilities(agg, caps)	function	Returns true if aggregate has all listed capabilities

Interfaces

Export	Kind	Description
IAggregateRoot	interface	Full contract for aggregate roots
IAggregateCapability	interface	Base capability contract
IAggregateConstructorParams<TId>	interface	Constructor parameter shape for aggregates
IAggregateEventHandler	interface	Event handler registration contract
IAggregateBuilder	interface	Builder contract

Utility Types

Export	Kind	Description
AggregateWithSnapshotCapability	type	Aggregate narrowed to snapshot-capable shape
AggregateWithVersioningCapability	type	Aggregate narrowed to versioning-capable shape
AggregateWithAuditCapability	type	Aggregate narrowed to audit-capable shape
AggregateWithEventSourcingCapability	type	Aggregate narrowed to event-sourcing shape

Package boundaries

@vytches/ddd-aggregates depends on:

• @vytches/ddd-contracts — base interfaces and EntityId
• @vytches/ddd-domain-primitives — error types
• @vytches/ddd-value-objects — enhanced EntityId
• @vytches/ddd-logging — internal logging

License

MIT