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

Interface: WorkflowContext<TWorkflowState, TMessageAttributes>

Defined in: packages/bus-core/src/workflow/workflow-context.ts:18

Passed to every handler of a workflow declared with defineWorkflow. It's the HandlerContext of the message being handled, plus the message's attributes and the functions that end the workflow.

Messages sent or published from it carry the workflow id in their sticky attributes, so replies are routed back to the same workflow instance.

It's an interface so a workflow handler can be unit tested by calling it with a plain object, such as one from workflowContext().

Example

const ctx = workflowContext<OrderState>({ send: async command => { sent.push(command) } })

Extends

• HandlerContext

Type Parameters

Type Parameter	Default type
TWorkflowState extends WorkflowState	-
TMessageAttributes extends MessageAttributes	MessageAttributes

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
attributes	readonly	TMessageAttributes	The attributes of the message being handled	-	packages/bus-core/src/workflow/workflow-context.ts:25
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.	HandlerContext.correlationId	packages/bus-core/src/handler/handler-context.ts:35

Methods

complete()

complete(workflowState?): WorkflowStateChange<TWorkflowState>;

Defined in: packages/bus-core/src/workflow/workflow-context.ts:35

Ends the workflow. Return its result from the handler. The workflow instance is no longer activated by later messages.

Parameters

Parameter	Type	Description
workflowState?	Partial<TWorkflowState>	Final changes to the workflow state to save with it

Returns

WorkflowStateChange<TWorkflowState>

The changes to return from the handler

Example

.when(CardCharged, (_message, _state, ctx) => ctx.complete({ charged: true }))

---

discard()

discard(): WorkflowStateChange<TWorkflowState>;

Defined in: packages/bus-core/src/workflow/workflow-context.ts:48

Drops the changes of this handler, so nothing is saved. Returned from a startedBy handler, it stops the workflow from starting. Return its result from the handler.

Returns

WorkflowStateChange<TWorkflowState>

The result to return from the handler

Example

.startedBy(DocumentUploaded, (message, _state, ctx) =>
  message.path.startsWith('/documents') ? { path: message.path } : ctx.discard()
)

---

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>

Inherited from

HandlerContext.failMessage

---

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

HandlerContext.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>

Inherited from

HandlerContext.returnMessage

---

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

HandlerContext.send