> For the complete documentation index, see [llms.txt](https://docs.nestjstools.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nestjstools.com/components/lifecycle-hooks.md).

# Lifecycle Hooks

Messaging lifecycle hooks allow you to tap into different stages of message processing — from raw input to final handler execution.

They are useful for cross-cutting concerns like logging, tracing, validation, metrics, or custom transformations.

> **Important:** every processed object is treated as **immutable**.\
> Each stage works on a **new instance**, rather than mutating the previous one in place.

> **Important:** not every hook is guaranteed to run.\
> Some hooks may be skipped depending on the flow, for example when no handler is registered, processing stops early, or message handling fails before later stages are reached.

***

### Example hook

```typescript
import {
  HookMessage,
  LifecycleHook,
  MessagingLifecycleHook,
  MessagingLifecycleHookListener,
} from '@nestjstools/messaging';
import { Injectable, Logger } from '@nestjs/common';

@Injectable()
@MessagingLifecycleHook(LifecycleHook.AFTER_MESSAGE_HANDLER_EXECUTION)
export class AfterDenormalizeHook implements MessagingLifecycleHookListener {
  constructor(private readonly logger: Logger) {
  }

  hook(message: HookMessage): Promise<void> {
    this.logger.log(`💡 Here I can do some action ON HOOK | ${message.routingKey}`);
    return Promise.resolve();
  }
}

```

### Lifecycle Overview

```mermaid
flowchart TB
    A[Dispatch message]

    B(BEFORE_MESSAGE_NORMALIZATION)
    N[/Normalizer/]
    C(AFTER_MESSAGE_NORMALIZATION)
    DN[/Denormalizer/]
    D(AFTER_MESSAGE_DENORMALIZED)

    E(BEFORE_MESSAGE_HANDLER)
    M[/Middlewares/]
    H[/Handler/]

    X{THROW EXCEPTION}

    S(AFTER_MESSAGE_HANDLER_EXECUTION)
    ERR(ON_FAILED_MESSAGE_CONSUMER)

    A --> B --> N --> C --> DN --> D --> E --> M --> H --> X

    X -->|NO| S
    X -->|YES| ERR

    %% styles
    classDef hook fill:#000000,stroke:#ffffff,color:#ffffff,stroke-width:2px;
    classDef component fill:#5fa8ff,stroke:#1e88e5,color:#000000,stroke-width:2px;
    classDef middleware fill:#26c6da,stroke:#00838f,color:#000000,stroke-width:2px;
    classDef decision fill:#ff9800,stroke:#e65100,color:#ffffff,stroke-width:2px;

    class B,C,D,E,S,OK,ERR hook;
    class N,DN,H,A component;
    class M middleware;
    class X decision;
```

***

### Available Hooks

#### `BEFORE_MESSAGE_NORMALIZATION`

Executed before the raw incoming message is normalized into the internal messaging format.

Use this hook when you want to:

* inspect raw transport data,
* log the original payload,
* attach tracing or diagnostic metadata before normalization starts.

At this point, the message is still in its original external form.

***

#### `AFTER_MESSAGE_NORMALIZATION`

Executed after the raw message has been normalized into the internal messaging representation.

Use this hook when you want to:

* inspect the normalized structure,
* validate normalized metadata,
* enrich processing context based on the normalized message.

At this stage, the system has already transformed the transport payload into the unified internal format.

***

#### `AFTER_MESSAGE_DENORMALIZED`

Executed after the normalized message has been denormalized into the target application object.

Use this hook when you want to:

* inspect the final typed message object,
* perform additional validation on the resolved message instance,
* log the exact object that will be passed further into the pipeline.

This is usually the first point where you work with the final application-level message object instead of transport or normalized data.

***

#### `BEFORE_MESSAGE_HANDLER`

Executed right before the handler is invoked.

Use this hook when you want to:

* run last-step checks before handling,
* prepare contextual logging,
* inspect the message object that is about to be processed by the handler.

This hook is triggered after denormalization and before middleware / handler execution begins.

***

#### `AFTER_MESSAGE_HANDLER_EXECUTION`

Executed after the handler finishes successfully.

Use this hook when you want to:

* log successful processing,
* measure execution results,
* trigger post-processing actions after handler completion.

This hook is only executed when the handler completes without throwing an exception.

***

#### `ON_CONSUMER_HANDLED_MESSAGE`

Executed when a consumer has successfully handled the message.

Use this hook when you want to:

* emit success metrics,
* store processing audit entries,
* mark the message as fully processed.

This is a success-only hook and is typically one of the last lifecycle points in the handling flow.

***

#### `ON_FAILED_MESSAGE_CONSUMER`

Executed when message consumption fails due to an exception during processing.

Use this hook when you want to:

* log failures,
* send alerts,
* store error details,
* trigger retry or dead-letter related logic.

This hook is only executed for failed processing paths.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nestjstools.com/components/lifecycle-hooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.