---
url: https://node-ts.github.io/bus/api/bus-core/interfaces/HandlerContext.md
---
[API reference](../../index.md) / [@node-ts/bus-core](../index.md) / HandlerContext

# Interface: HandlerContext

Defined in: [packages/bus-core/src/handler/handler-context.ts:30](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/handler/handler-context.ts#L30)

Passed to every handler and workflow handler as the context of the message being handled. It's bound to the
bus that received the message, so a handler can send, publish, fail or return the message without capturing
the bus in a closure or resolving it from a container.

`send` and `publish` behave like `bus.send` and `bus.publish` inside a handler: messages are buffered until the
handler resolves and dropped if it fails, and they carry the `correlationId` and `stickyAttributes` of the
message being handled. Inside a workflow handler they also carry the workflow id, so replies route back to the
same workflow instance.

It's an interface so a handler can be unit tested by calling it with a plain object.

## Example

```ts
const placeOrderHandler = handlerFor(PlaceOrder, async (message, _attributes, ctx) => {
  await ctx.publish(new OrderPlaced(message.orderId))
})

// In a test
const published: Event[] = []
const ctx: HandlerContext = {
  correlationId: 'test',
  send: async () => {},
  publish: async event => { published.push(event) },
  failMessage: async () => {},
  returnMessage: async () => {}
}
await placeOrderHandler.messageHandler(new PlaceOrder('1'), attributes, ctx)
```

## Extends

* [`BusSender`](BusSender.md)

## Extended by

* [`WorkflowContext`](WorkflowContext.md)

## Properties

| Property | Modifier | Type | Description | Defined in |
| ------ | ------ | ------ | ------ | ------ |
| <a id="property-correlationid"></a> `correlationId` | `readonly` | `string` | `undefined` | The correlation id of the message being handled, which is also put on every message sent or published from this context. `undefined` only when a message from outside the bus arrived without one. | [packages/bus-core/src/handler/handler-context.ts:35](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/handler/handler-context.ts#L35) |

## Methods

### failMessage()

```ts
failMessage(): Promise<void>;
```

Defined in: [packages/bus-core/src/handler/handler-context.ts:41](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/handler/handler-context.ts#L41)

Routes the message being handled straight to the dead letter queue, without further retries. The handler
should return after calling this.

#### Returns

`Promise`<`void`>

***

### publish()

```ts
publish<TEvent>(event, messageAttributes?): Promise<void>;
```

Defined in: [packages/bus-core/src/handler/bus-sender.ts:37](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/handler/bus-sender.ts#L37)

Publishes an event to the transport. Inside a handler, the event is buffered and only published once the
handler resolves, and is dropped if the handler fails.

#### Type Parameters

| Type Parameter |
| ------ |
| `TEvent` *extends* [`Event`](../../bus-messages/classes/Event.md) |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `TEvent` | The event to publish |
| `messageAttributes?` | `Partial`<[`MessageAttributes`](../../bus-messages/interfaces/MessageAttributes.md)<[`MessageAttributeMap`](../../bus-messages/interfaces/MessageAttributeMap.md), [`MessageAttributeMap`](../../bus-messages/interfaces/MessageAttributeMap.md)>> | Attributes to attach to the outgoing message. The `correlationId` and `stickyAttributes` of the message being handled are added when published from a handler. |

#### Returns

`Promise`<`void`>

#### Inherited from

[`BusSender`](BusSender.md).[`publish`](BusSender.md#publish)

***

### returnMessage()

```ts
returnMessage(): Promise<void>;
```

Defined in: [packages/bus-core/src/handler/handler-context.ts:47](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/handler/handler-context.ts#L47)

Returns the message being handled to the queue so that it's retried, without failing the handler. When the
message came from a `Receiver`, it's reported to the receiver host as failed so the host doesn't delete it.

#### Returns

`Promise`<`void`>

***

### send()

```ts
send<TCommand>(command, messageAttributes?): Promise<void>;
```

Defined in: [packages/bus-core/src/handler/bus-sender.ts:25](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/handler/bus-sender.ts#L25)

Sends a command to the transport. Inside a handler, the command is buffered and only sent once the handler
resolves, and is dropped if the handler fails.

#### Type Parameters

| Type Parameter |
| ------ |
| `TCommand` *extends* [`Command`](../../bus-messages/classes/Command.md) |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `TCommand` | The command to send |
| `messageAttributes?` | `Partial`<[`MessageAttributes`](../../bus-messages/interfaces/MessageAttributes.md)<[`MessageAttributeMap`](../../bus-messages/interfaces/MessageAttributeMap.md), [`MessageAttributeMap`](../../bus-messages/interfaces/MessageAttributeMap.md)>> | Attributes to attach to the outgoing message. The `correlationId` and `stickyAttributes` of the message being handled are added when sent from a handler. |

#### Returns

`Promise`<`void`>

#### Inherited from

[`BusSender`](BusSender.md).[`send`](BusSender.md#send)