NestJS Enterprise Backend APIs · Урок

Доменные события и AggregateRoot

Создавайте и публикуйте доменные события из корней агрегатов с помощью EventBus и mergeObjectContext.

Урок 3 из 413 шагов

«Доменные события и AggregateRoot» — бесплатный урок NestJS Enterprise Backend APIs на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения NestJS Enterprise Backend APIs, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс NestJS Enterprise Backend APIs содержит 4 уроков всего.

Части этого урока еще не переведены и отображаются на английском.

Why Domain Events?

In an event-driven CQRS system, a domain event records something meaningful that already happened inside your domain: OrderPlaced, PaymentCaptured, UserDeactivated. They are named in the past tense because they are facts, not requests.

Domain events let you decouple side effects from the core write logic. Instead of an order service directly calling email, inventory, and analytics code, it simply emits OrderPlaced, and independent handlers react.

Command: an intent to change state (PlaceOrderCommand).
Event: a record of a change that occurred (OrderPlacedEvent).

NestJS provides first-class support for this through @nestjs/cqrs, the AggregateRoot base class, and the EventBus.

The AggregateRoot Base Class

An aggregate root is the entry point to a cluster of domain objects that change together and must stay consistent. In @nestjs/cqrs, you make a class an aggregate by extending AggregateRoot.

This base class gives you two key methods:

apply(event) — record a domain event that happened in this aggregate.
commit() — publish all recorded events to the EventBus.

The aggregate buffers events internally until you explicitly commit them. This separation lets you mutate state first and publish only after the change is safely persisted.

import { AggregateRoot } from '@nestjs/cqrs';

export class OrderPlacedEvent {
  constructor(
    public readonly orderId: string,
    public readonly total: number,
  ) {}
}

export class Order extends AggregateRoot {
  constructor(public readonly id: string) {
    super();
  }

  place(total: number) {
    // mutate state here, then record the fact
    this.apply(new OrderPlacedEvent(this.id, total));
  }
}

apply() Buffers, commit() Publishes

When you call this.apply(event), the event is pushed onto an internal array on the aggregate. Nothing is published yet.

Only when you call aggregate.commit() does NestJS iterate that buffer and hand each event to the publisher, which forwards them to the EventBus for handlers to consume.

This two-phase flow is intentional:

You can apply several events during one operation.
You persist the new state to the database.
Then you commit so events fire after a successful save, avoiding side effects on a transaction that later rolls back.

The Missing Publisher Problem

There is a catch. If you simply new Order(...) in a command handler and call commit(), nothing happens. The aggregate has no reference to the real EventBus — its default publisher is a no-op.

The aggregate must be wired to a publisher that knows how to push events onto the bus. That wiring is exactly what EventPublisher.mergeObjectContext (and mergeClassContext) provides.

Forgetting this step is the single most common reason newcomers report that their domain events "never fire" in NestJS CQRS.

mergeObjectContext: Wiring the EventBus

EventPublisher.mergeObjectContext(aggregate) takes an existing aggregate instance and injects the real publisher into it, so that a later commit() actually dispatches events to the EventBus.

Use it inside a command handler:

Build or load your aggregate.
Wrap it: const order = this.publisher.mergeObjectContext(rawOrder).
Run domain behavior (which calls apply internally).
Persist, then call order.commit().

Inject EventPublisher from @nestjs/cqrs through the constructor.

import { CommandHandler, ICommandHandler, EventPublisher } from '@nestjs/cqrs';
import { PlaceOrderCommand } from './place-order.command';
import { Order } from './order.aggregate';
import { OrderRepository } from './order.repository';

@CommandHandler(PlaceOrderCommand)
export class PlaceOrderHandler implements ICommandHandler<PlaceOrderCommand> {
  constructor(
    private readonly repository: OrderRepository,
    private readonly publisher: EventPublisher,
  ) {}

  async execute(command: PlaceOrderCommand): Promise<void> {
    const order = this.publisher.mergeObjectContext(
      new Order(command.orderId),
    );

    order.place(command.total); // applies OrderPlacedEvent
    await this.repository.save(order);
    order.commit(); // now events reach the EventBus
  }
}

mergeClassContext for Factories

Sometimes you reconstruct aggregates inside a factory or repository rather than newing them directly in the handler. For that, mergeClassContext returns a publisher-aware subclass.

Every instance created from the merged class is automatically context-bound, so you do not have to call mergeObjectContext on each one.

Use mergeObjectContext for a single instance you already hold; use mergeClassContext when a factory will produce many instances.

import { EventPublisher } from '@nestjs/cqrs';
import { Order } from './order.aggregate';

export class OrderFactory {
  constructor(private readonly publisher: EventPublisher) {}

  create(orderId: string): Order {
    // Order becomes a publisher-aware subclass
    const ContextOrder = this.publisher.mergeClassContext(Order);
    return new ContextOrder(orderId);
  }
}

Defining a Domain Event

A domain event in NestJS is just a plain class — typically implementing the marker interface IEvent. Keep events immutable and carry only the data handlers need.

Use readonly fields populated in the constructor.
Name in past tense: OrderPlacedEvent, not PlaceOrder.
Include identifiers and the minimal payload, not entire entities.

Because events may be serialized (for event sourcing or message brokers), avoid putting behavior or service references on them.

import { IEvent } from '@nestjs/cqrs';

export class OrderPlacedEvent implements IEvent {
  constructor(
    public readonly orderId: string,
    public readonly customerId: string,
    public readonly total: number,
    public readonly occurredAt: Date = new Date(),
  ) {}
}

Handling the Event

An @EventsHandler(OrderPlacedEvent) class subscribes to the event on the bus. Its handle method runs the side effect: sending email, updating a read model, decrementing inventory.

Handlers should be idempotent where possible, because at-least-once delivery (in distributed setups) can replay an event. Keep them small and focused — one handler per concern.

import { EventsHandler, IEventHandler } from '@nestjs/cqrs';
import { OrderPlacedEvent } from './order-placed.event';

@EventsHandler(OrderPlacedEvent)
export class OrderPlacedHandler implements IEventHandler<OrderPlacedEvent> {
  handle(event: OrderPlacedEvent): void {
    // side effect: e.g. enqueue a confirmation email
    console.log(`Order ${event.orderId} placed for ${event.total}`);
  }
}

Wiring the CqrsModule

To use any of this, import CqrsModule and register your handlers and aggregates' collaborators as providers. The module sets up the CommandBus, QueryBus, and EventBus, and exposes EventPublisher for injection.

Add command handlers, event handlers, and factories to providers.
Import CqrsModule in imports.

Without this import, injecting EventPublisher or EventBus fails at startup with an unresolved-dependency error.

import { Module } from '@nestjs/common';
import { CqrsModule } from '@nestjs/cqrs';
import { PlaceOrderHandler } from './place-order.handler';
import { OrderPlacedHandler } from './order-placed.handler';
import { OrderRepository } from './order.repository';

@Module({
  imports: [CqrsModule],
  providers: [PlaceOrderHandler, OrderPlacedHandler, OrderRepository],
})
export class OrdersModule {}

Commit After Persistence, Not Before

Order of operations matters. The recommended pattern is:

1. Merge context onto the aggregate.
2. Execute domain behavior (events are buffered via apply).
3. Persist the aggregate inside a transaction.
4. Call commit() only after the transaction succeeds.

If you commit before saving and the save fails, you have already published events for a state change that never persisted — leaving handlers acting on phantom data. For stronger guarantees, teams adopt the transactional outbox pattern, writing events to an outbox table in the same transaction and relaying them afterward.

Modeling the Buffer-Then-Publish Flow

The core idea — buffer events with apply, flush them with commit — can be reproduced in plain TypeScript to build intuition, with no NestJS at all. Here a tiny aggregate records events and a publisher drains them only when committed.

Run it and watch the handler fire only after commit() is called.

type DomainEvent = { name: string; payload: unknown };

class MiniAggregate {
  private events: DomainEvent[] = [];
  private publish: (e: DomainEvent) => void = () => {};

  setPublisher(fn: (e: DomainEvent) => void) {
    this.publish = fn; // mimics mergeObjectContext
  }

  apply(event: DomainEvent) {
    this.events.push(event); // buffer only
  }

  commit() {
    this.events.forEach((e) => this.publish(e));
    this.events = [];
  }
}

const order = new MiniAggregate();
order.apply({ name: 'OrderPlaced', payload: { id: 'A1', total: 50 } });
console.log('before commit: nothing published yet');

order.setPublisher((e) => console.log('handled:', e.name, e.payload));
order.commit();
console.log('after commit: buffer flushed');

Quick Check

You created an aggregate with new Order(id), called a method that uses this.apply(new OrderPlacedEvent(...)), then called order.commit() — but no event handler ever runs. What is the most likely cause?

Ответь в интерактивном уроке

Recap

You learned how NestJS CQRS turns aggregates into event emitters:

AggregateRoot gives apply() (buffer an event) and commit() (flush to the EventBus).
A direct new uses a no-op publisher — wire the real one with EventPublisher.mergeObjectContext for a single instance, or mergeClassContext for factory-produced instances.
Domain events are immutable past-tense classes implementing IEvent, carrying only the needed payload.
@EventsHandler classes react to events; keep them small and idempotent.
Import CqrsModule and register handlers in providers.
Commit after persistence so events never describe a state that failed to save; consider a transactional outbox for stronger delivery guarantees.

Можно начать бесплатно

Изучай TypeScript с ИИ-репетитором — бесплатно

Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.

Курсы: 20
Уроки: 76

Начать учиться бесплатно Посмотреть полный курс

Часто задаваемые вопросы

Урок «Доменные события и AggregateRoot» бесплатный?

Да — полный текст урока «Доменные события и AggregateRoot» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс NestJS Enterprise Backend APIs, подпишись на CoddyKit PRO. Курс NestJS Enterprise Backend APIs содержит 4 уроков всего.

Чему я научусь в уроке «Доменные события и AggregateRoot»?

Создавайте и публикуйте доменные события из корней агрегатов с помощью EventBus и mergeObjectContext. Ты практикуешь NestJS Enterprise Backend APIs с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать NestJS Enterprise Backend APIs?

Предыдущий опыт не требуется. NestJS Enterprise Backend APIs на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.

Сколько времени занимает урок «Доменные события и AggregateRoot»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке NestJS Enterprise Backend APIs?

Да. Каждый урок NestJS Enterprise Backend APIs включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к NestJS Enterprise Backend APIs