API reference / @node-ts/bus-core / HandlerContext

Interface: HandlerContext

Defined in: packages/bus-core/src/handler/handler-context.ts:30

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

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

Extended by

• WorkflowContext

Properties

Property	Modifier	Type	Description	Defined in
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

Methods

failMessage()

failMessage(): Promise<void>;

Defined in: packages/bus-core/src/handler/handler-context.ts:41

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()

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

Defined in: packages/bus-core/src/handler/bus-sender.ts:37

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

Parameters

Parameter	Type	Description
event	TEvent	The event to publish
messageAttributes?	Partial<MessageAttributes<MessageAttributeMap, MessageAttributeMap>>	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.publish

---

returnMessage()

returnMessage(): Promise<void>;

Defined in: packages/bus-core/src/handler/handler-context.ts:47

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()

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

Defined in: packages/bus-core/src/handler/bus-sender.ts:25

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

Parameters

Parameter	Type	Description
command	TCommand	The command to send
messageAttributes?	Partial<MessageAttributes<MessageAttributeMap, MessageAttributeMap>>	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.send