docs: update cqrs chapter

Author: kamilmysliwiec

content/recipes/cqrs.md

@@ -1,13 +1,20 @@
 ### CQRS
 
-The flow of simple [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) (Create, Read, Update and Delete) applications can be described using the following steps:
+The flow of simple [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) (Create, Read, Update and Delete) applications can be described as follows:
 
-1. The **controllers** layer handles HTTP requests and delegates tasks to the services layer.
-2. The **services layer** is where most of the business logic lives.
-3. Services use **repositories / DAOs** to change / persist entities.
+1. The controllers layer handles HTTP requests and delegates tasks to the services layer.
+2. The services layer is where most of the business logic lives.
+3. Services use repositories / DAOs to change / persist entities.
 4. Entities act as containers for the values, with setters and getters.
 
-In most cases, for small and medium-sized applications, this pattern is sufficient. However, when our requirements become more complex, the **CQRS** model may be more appropriate and scalable. To facilitate that model, Nest provides a lightweight [CQRS module](https://github.com/nestjs/cqrs). This chapter describes how to use it.
+While this pattern is usually sufficient for small and medium-sized applications, it may not be the best choice for larger, more complex applications. In such cases, the **CQRS** (Command and Query Responsibility Segregation) model may be more appropriate and scalable (depending on the application's requirements). Benefits of this model include:
+
+- **Separation of concerns**. The model separates the read and write operations into separate models.
+- **Scalability**. The read and write operations can be scaled independently.
+- **Flexibility**. The model allows for the use of different data stores for read and write operations.
+- **Performance**. The model allows for the use of different data stores optimized for read and write operations.
+
+To facilitate that model, Nest provides a lightweight [CQRS module](https://github.com/nestjs/cqrs). This chapter describes how to use it.
 
 #### Installation
 
@@ -19,7 +26,7 @@ $ npm install --save @nestjs/cqrs
 
 #### Commands
 
-In this model, each action is called a **Command**. When a command is dispatched, the application reacts to it. Commands can be dispatched from the services layer, or directly from controllers/gateways. Commands are consumed by **Command Handlers**.
+Commands are used to change the application state. They should be task-based, rather than data centric. When a command is dispatched, it is handled by a corresponding **Command Handler**. The handler is responsible for updating the application state.
 
 ```typescript
 @@filename(heroes-game.service)
@@ -49,7 +56,7 @@ export class HeroesGameService {
 }
 ```
 
-Here's a sample service that dispatches `KillDragonCommand`. Let's see how the command looks:
+In the code snippet above, we instantiate the `KillDragonCommand` class and pass it to the `CommandBus`'s `execute()` method. This is the demonstrated command class:
 
 ```typescript
 @@filename(kill-dragon.command)
@@ -68,7 +75,9 @@ export class KillDragonCommand {
 }
 ```
 
-The `CommandBus` is a **stream** of commands. It delegates commands to the equivalent handlers. Each command must have a corresponding **Command Handler**:
+The `CommandBus` represents a **stream** of commands. It is responsible for dispatching commands to the appropriate handlers. The `execute()` method returns a promise, which resolves to the value returned by the handler.
+
+Let's create a handler for the `KillDragonCommand` command.
 
 ```typescript
 @@filename(kill-dragon.handler)
@@ -102,11 +111,19 @@ export class KillDragonHandler {
 }
 ```
 
-With this approach, every application state change is driven by the occurrence of a **Command**. The logic is encapsulated in handlers. With this approach, we can simply add behavior like logging or persisting commands in the database (e.g., for diagnostics purposes).
+This handler retrieves the `Hero` entity from the repository, calls the `killEnemy()` method, and then persists the changes. The `KillDragonHandler` class implements the `ICommandHandler` interface, which requires the implementation of the `execute()` method. The `execute()` method receives the command object as an argument.
+
+#### Queries
+
+Queries are used to retrieve data from the application state. They should be data centric, rather than task-based. When a query is dispatched, it is handled by a corresponding **Query Handler**. The handler is responsible for retrieving the data.
+
+The `QueryBus` follows the same pattern as the `CommandBus`. Query handlers should implement the `IQueryHandler` interface and be annotated with the `@QueryHandler()` decorator.
 
 #### Events
 
-Command handlers neatly encapsulate logic. While beneficial, the application structure is still not flexible enough, not **reactive**. To remedy this, we also introduce **events**.
+Events are used to notify other parts of the application about changes in the application state. They are dispatched by **models** or directly using the `EventBus`. When an event is dispatched, it is handled by corresponding **Event Handlers**. Handlers can then, for example, update the read model.
+
+For demonstration purposes, let's create an event class:
 
 ```typescript
 @@filename(hero-killed-dragon.event)
@@ -125,7 +142,7 @@ export class HeroKilledDragonEvent {
 }
 ```
 
-Events are asynchronous. They are dispatched either by **models** or directly using `EventBus`. In order to dispatch events, models have to extend the `AggregateRoot` class.
+Now while events can be dispatched directly using the `EventBus.publish()` method, we can also dispatch them from the model. Let's update the `Hero` model to dispatch the `HeroKilledDragonEvent` event when the `killEnemy()` method is called.
 
 ```typescript
 @@filename(hero.model)
@@ -135,7 +152,7 @@ export class Hero extends AggregateRoot {
   }
 
   killEnemy(enemyId: string) {
-    // logic
+    // Business logic
     this.apply(new HeroKilledDragonEvent(this.id, enemyId));
   }
 }
@@ -147,13 +164,13 @@ export class Hero extends AggregateRoot {
   }
 
   killEnemy(enemyId) {
-    // logic
+    // Business logic
     this.apply(new HeroKilledDragonEvent(this.id, enemyId));
   }
 }
 ```
 
-The `apply()` method does not dispatch events yet because there's no relationship between the model and the `EventPublisher` class. How do we associate the model and the publisher? By using a publisher `mergeObjectContext()` method inside our command handler.
+The `apply()` method is used to dispatch events. It accepts an event object as an argument. However, since our model is not aware of the `EventBus`, we need to associate it with the model. We can do that by using the `EventPublisher` class.
 
 ```typescript
 @@filename(kill-dragon.handler)
@@ -193,14 +210,29 @@ export class KillDragonHandler {
 }
 ```
 
-Now everything works as expected. Notice that we need to `commit()` events since they're not being dispatched immediately. Obviously, an object doesn't have to exist up front. We can easily merge type context as well:
+The `EventPublisher#mergeObjectContext` method merges the event publisher into the provided object, which means that the object will now be able to publish events to the events stream.
+
+Notice that in this example we also call the `commit()` method on the model. This method is used to dispatch any outstanding events. To automatically dispatch events, we can set the `autoCommit` property to `true`:
+
+```typescript
+export class Hero extends AggregateRoot {
+  constructor(private id: string) {
+    super();
+    this.autoCommit = true;
+  }
+}
+```
+
+In case we want to merge the event publisher into a non-existing object, but rather into a class, we can use the `EventPublisher#mergeClassContext` method:
 
 ```typescript
 const HeroModel = this.publisher.mergeClassContext(Hero);
-new HeroModel('id');
+const hero = new HeroModel('id'); // <-- HeroModel is a class
 ```
 
-Now the model has the ability to publish events. Additionally, we can emit events manually using `EventBus`:
+Now every instance of the `HeroModel` class will be able to publish events without using `mergeObjectContext()` method.
+
+Additionally, we can emit events manually using `EventBus`:
 
 ```typescript
 this.eventBus.publish(new HeroKilledDragonEvent());
@@ -217,24 +249,25 @@ export class HeroKilledDragonHandler implements IEventHandler<HeroKilledDragonEv
   constructor(private repository: HeroRepository) {}
 
   handle(event: HeroKilledDragonEvent) {
-    // logic
+    // Business logic
   }
 }
 ```
 
-Now we can move the **write logic** into the event handlers.
-
 > info **Hint** Be aware that when you start using event handlers you get out of the traditional HTTP web context.
+>
 > - Errors in `CommandHandlers` can still be caught by built-in [Exception filters](/exception-filters).
 > - Errors in `EventHandlers` can't be caught by Exception filters: you will have to handle them manually. Either by a simple `try/catch`, using [Sagas](/recipes/cqrs#sagas) by triggering a compensating event, or whatever other solution you choose.
 > - HTTP Responses in `CommandHandlers` can still be sent back to the client.
 > - HTTP Responses in `EventHandlers` cannot. If you want to send information to the client you could use [WebSocket](/websockets/gateways), [SSE](/techniques/server-sent-events), or whatever other solution you choose.
 
 #### Sagas
 
-This type of **Event-Driven Architecture** improves application **reactiveness and scalability**. Now, when we have events, we can simply react to them in various ways. **Sagas** are the final building block from an architectural point of view.
+Saga is a long-running process that listens to events and may trigger new commands. It is usually used to manage complex workflows in the application. For example, when a user signs up, a saga may listen to the `UserRegisteredEvent` and send a welcome email to the user.
+
+Sagas are an extremely powerful feature. A single saga may listen for 1..\* events. Using the [RxJS](https://github.com/ReactiveX/rxjs) library, we can filter, map, fork, and merge event streams to create sophisticated workflows. Each saga returns an Observable which produces a command instance. This command is then dispatched **asynchronously** by the `CommandBus`.
 
-Sagas are an extremely powerful feature. A single saga may listen for 1..\* events. Using the [RxJS](https://github.com/ReactiveX/rxjs) library, it can combine, merge, filter or apply other `RxJS` operators on the event stream. Each saga returns an Observable which contains a command. This command is dispatched **asynchronously**.
+Let's create a saga that listens to the `HeroKilledDragonEvent` and dispatches the `DropAncientItemCommand` command.
 
 ```typescript
 @@filename(heroes-game.saga)
@@ -263,15 +296,13 @@ export class HeroesGameSagas {
 
 > info **Hint** The `ofType` operator and the `@Saga()` decorator are exported from the `@nestjs/cqrs` package.
 
-We declared a rule - when any hero kills the dragon, the ancient item should be dropped. With this in place, `DropAncientItemCommand` will be dispatched and processed by the appropriate handler.
+The `@Saga()` decorator marks the method as a saga. The `events$` argument is an Observable stream of all events. The `ofType` operator filters the stream by the specified event type. The `map` operator maps the event to a new command instance.
 
-#### Queries
-
-The `CqrsModule` can also be used for handling queries. The `QueryBus` follows the same pattern as the `CommandsBus`. Query handlers should implement the `IQueryHandler` interface and be marked with the `@QueryHandler()` decorator.
+In this example, we map the `HeroKilledDragonEvent` to the `DropAncientItemCommand` command. The `DropAncientItemCommand` command is then auto-dispatched by the `CommandBus`.
 
 #### Setup
 
-Finally, let's look at how to set up the whole CQRS mechanism.
+To wrap up, we need to register all command handlers, event handlers, and sagas in the `HeroesGameModule`:
 
 ```typescript
 @@filename(heroes-game.module)
@@ -292,9 +323,73 @@ export const EventHandlers =  [HeroKilledDragonHandler, HeroFoundItemHandler];
 export class HeroesGameModule {}
 ```
 
-#### Summary
+#### Unhandled exceptions
+
+Event handlers are executed in the asynchronous manner. This means they should always handle all exceptions to prevent application from entering the inconsistent state. However, if an exception is not handled, the `EventBus` will create the `UnhandledExceptionInfo` object and push it to the `UnhandledExceptionBus` stream. This stream is an `Observable` which can be used to process unhandled exceptions.
 
-`CommandBus`, `QueryBus` and `EventBus` are **Observables**. This means that you can easily subscribe to the whole stream and enrich your application with **Event Sourcing**.
+```typescript
+private destroy$ = new Subject<void>();
+
+constructor(private unhandledExceptionsBus: UnhandledExceptionBus) {
+  this.unhandledExceptionsBus
+    .pipe(takeUntil(this.destroy$))
+    .subscribe((exceptionInfo) => {
+      // Handle exception here
+      // e.g. send it to external service, terminate process, or publish a new event
+    });
+}
+
+onModuleDestroy() {
+  this.destroy$.next();
+  this.destroy$.complete();
+}
+```
+
+To filter out exceptions, we can use the `ofType` operator, as follows:
+
+```typescript
+this.unhandledExceptionsBus.pipe(takeUntil(this.destroy$), UnhandledExceptionBus.ofType(TransactionNotAllowedException)).subscribe((exceptionInfo) => {
+  // Handle exception here
+});
+```
+
+Where `TransactionNotAllowedException` is the exception we want to filter out.
+
+The `UnhandledExceptionInfo` object contains the following properties:
+
+```typescript
+export interface UnhandledExceptionInfo<Cause = IEvent | ICommand, Exception = any> {
+  /**
+   * The exception that was thrown.
+   */
+  exception: Exception;
+  /**
+   * The cause of the exception (event or command reference).
+   */
+  cause: Cause;
+}
+```
+
+#### Subscribing to all events
+
+`CommandBus`, `QueryBus` and `EventBus` are all **Observables**. This means that we can subscribe to the entire stream and, for example, process all events. For example, we can log all events to the console, or save them to the event store.
+
+```typescript
+private destroy$ = new Subject<void>();
+
+constructor(private eventBus: EventBus) {
+  this.eventBus
+    .pipe(takeUntil(this.destroy$))
+    .subscribe((event) => {
+      // Save events to database
+    });
+}
+
+onModuleDestroy() {
+  this.destroy$.next();
+  this.destroy$.complete();
+}
+```
 
 #### Example