From 359c8459ec93424f1d75e92b253e0b53fa410055 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kamil=20My=C5=9Bliwiec?= <mail@kamilmysliwiec.com>
Date: Mon, 21 Oct 2024 09:14:28 +0200
Subject: [PATCH] docs: add docs on event emitter readiness watcher

---
 content/techniques/events.md | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/content/techniques/events.md b/content/techniques/events.md
index d08dbca0e8..e903aefcac 100644
--- a/content/techniques/events.md
+++ b/content/techniques/events.md
@@ -50,7 +50,7 @@ EventEmitterModule.forRoot({
 });
 ```
 
-#### Dispatching Events
+#### Dispatching events
 
 To dispatch (i.e., fire) an event, first inject `EventEmitter2` using standard constructor injection:
 
@@ -72,7 +72,7 @@ this.eventEmitter.emit(
 );
 ```
 
-#### Listening to Events
+#### Listening to events
 
 To declare an event listener, decorate a method with the `@OnEvent()` decorator preceding the method definition containing the code to be executed, as follows:
 
@@ -85,11 +85,10 @@ handleOrderCreatedEvent(payload: OrderCreatedEvent) {
 
 > warning **Warning** Event subscribers cannot be request-scoped.
 
-The first argument can be a `string` or `symbol` for a simple event emitter and a `string | symbol | Array<string | symbol>` in a case of a wildcard emitter.  
+The first argument can be a `string` or `symbol` for a simple event emitter and a `string | symbol | Array<string | symbol>` in a case of a wildcard emitter.
 
 The second argument (optional) is a listener options object as follows:
 
-
 ```typescript
 export type OnEventOptions = OnOptions & {
   /**
@@ -103,7 +102,7 @@ export type OnEventOptions = OnOptions & {
 
   /**
    * If "true", the onEvent callback will not throw an error while handling the event. Otherwise, if "false" it will throw an error.
-   * 
+   *
    * @default true
    */
   suppressErrors?: boolean;
@@ -142,6 +141,22 @@ handleEverything(payload: any) {
 
 > info **Hint** `EventEmitter2` class provides several useful methods for interacting with events, like `waitFor` and `onAny`. You can read more about them [here](https://github.com/EventEmitter2/EventEmitter2).
 
+#### Preventing event loss
+
+Events triggered before or during the `onApplicationBootstrap` lifecycle hook—such as those from module constructors or the `onModuleInit` method—may be missed because the `EventSubscribersLoader` might not have finished setting up the listeners.
+
+To avoid this issue, you can use the `waitUntilReady` method of the `EventEmitterReadinessWatcher`, which returns a promise that resolves once all listeners have been registered. This method can be called in the `onApplicationBootstrap` lifecycle hook of a module to ensure that all events are properly captured.
+
+```typescript
+await this.eventEmitterReadinessWatcher.waitUntilReady();
+await this.eventEmitter.emit(
+  'order.created',
+  new OrderCreatedEvent({ orderId: 1, payload: {} }),
+);
+```
+
+> info **Note** This is only necessary for events emitted before the `onApplicationBootstrap` lifecycle hook is complete.
+
 #### Example
 
 A working example is available [here](https://github.com/nestjs/nest/tree/master/sample/30-event-emitter).