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

Class: BusInstance<TTransportMessage>

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:129

A bus built by Bus.configure().build(). It sends and publishes messages, and unless it's send-only, receives them and dispatches them to handlers.

Type Parameters

Type Parameter	Default type
TTransportMessage	object

Implements

• BusSender

Constructors

Constructor

new BusInstance<TTransportMessage>(
   transport, 
   concurrency, 
   workflowRegistry, 
   coreDependencies, 
   messageReadMiddleware, 
   handlerRegistry, 
   container, 
   sendOnly, 
   receiver, 
   messageHandlingContext
): BusInstance<TTransportMessage>;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:188

Parameters

Parameter	Type
transport	Transport<TTransportMessage>
concurrency	number
workflowRegistry	WorkflowRegistry
coreDependencies	CoreDependencies
messageReadMiddleware	MiddlewareDispatcher<TransportMessage<any>>
handlerRegistry	HandlerRegistry
container	ContainerAdapter | undefined
sendOnly	boolean
receiver	| Receiver<unknown, TransportMessage<unknown>, unknown> | undefined
messageHandlingContext	MessageHandlingContext

Returns

BusInstance<TTransportMessage>

Properties

Property	Modifier	Type	Description	Defined in
afterDispatch	readonly	TypedEmitter<AfterDispatch>	Emitted after a message has been dispatched and completed all handler invocations	packages/bus-core/src/service-bus/bus-instance.ts:175
afterPublish	readonly	TypedEmitter<AfterPublish>	Emitted after an event has been published to the transport	packages/bus-core/src/service-bus/bus-instance.ts:151
afterReceive	readonly	TypedEmitter<AfterReceive<TTransportMessage>>	Emitted immediately after a message has been received from the transport	packages/bus-core/src/service-bus/bus-instance.ts:163
afterSend	readonly	TypedEmitter<AfterSend>	Emitted after a command has been sent to the transport	packages/bus-core/src/service-bus/bus-instance.ts:145
beforeDispatch	readonly	TypedEmitter<BeforeDispatch>	Emitted before a message is dispatched to handlers	packages/bus-core/src/service-bus/bus-instance.ts:169
beforePublish	readonly	TypedEmitter<BeforePublish>	Emitted before an event is published to the transport	packages/bus-core/src/service-bus/bus-instance.ts:139
beforeSend	readonly	TypedEmitter<BeforeSend>	Emitted before a command is sent to the transport	packages/bus-core/src/service-bus/bus-instance.ts:133
onError	readonly	TypedEmitter<OnError<TTransportMessage>>	Emitted when an error occurs during message handling	packages/bus-core/src/service-bus/bus-instance.ts:157

Accessors

state

Get Signature

get state(): BusState;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:524

Gets the current state of a message-handling bus

Returns

BusState

Methods

dispatchMessageToHandler()

dispatchMessageToHandler(
   message, 
   attributes, 
   handler
): Promise<void>;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:781

Parameters

Parameter	Type
message	Message
attributes	MessageAttributes
handler	HandlerDefinition<Message>

Returns

Promise<void>

---

dispose()

dispose(): Promise<void>;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:502

Stops and disposes all resources allocated to the bus, as well as removing all handler registrations.

The bus instance can not be used after this has been called. If the bus is already stopping, this waits for that stop to complete rather than stopping again.

Returns

Promise<void>

---

failMessage()

failMessage(): Promise<void>;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:371

Instructs the bus that the current message being handled cannot be processed even with retries and instead should immediately be routed to the dead letter queue

Returns

Promise<void>

Throws

FailMessageOutsideHandlingContext if called outside a message handling context of this bus, including while another bus is handling a message

---

getHandlingContext()

getHandlingContext(): 
  | TransportMessage<unknown>
  | undefined;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:406

Gets the message this bus is handling in the current async stack, such as from read middleware, a lifecycle listener or code called by a handler. Handlers get the same details from their handler context.

Returns

| TransportMessage<unknown> | undefined

the transport message being handled, or undefined outside a message handling context of this bus, including while another bus is handling a message

---

initialize()

initialize(): Promise<void>;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:280

Initializes the bus with the provided configuration. This must be called before .start()

Returns

Promise<void>

Throws

InvalidOperation if the bus has already been initialized

Throws

MessageTypesMissing if the bus receives messages, but a handled message or a workflow state has no entry in the message types passed to withMessageTypes()

---

publish()

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

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:325

Publishes an event to the transport.

When called from inside a handler, the event is buffered and only published once the handler resolves, and is dropped if the handler fails. Anywhere else (outside a handler, in read middleware or lifecycle listeners, or after the handler has already resolved) it's published straight away. afterPublish is emitted once the transport has published it.

Type Parameters

Type Parameter
TEvent extends Event

Parameters

Parameter	Type	Description
event	TEvent	An event to publish
messageAttributes	Partial<MessageAttributes>	A set of attributes to attach to the outgoing message when published

Returns

Promise<void>

Implementation of

BusSender.publish

---

receive()

receive<TReceiveResult>(message): Promise<TReceiveResult>;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:222

Receive one or more messages to dispatch directly to handlers. This can only be called when a Receiver has been configured using Bus.configure().withReceiver()

Type Parameters

Type Parameter	Default type
TReceiveResult	void

Parameters

Parameter	Type	Description
message	unknown	The message, or batch of messages, received by the host (e.g. a Lambda event)

Returns

Promise<TReceiveResult>

Nothing, unless the receiver implements toReceiveResult, in which case its result is returned

Throws

InvalidOperation if no Receiver has been configured

Throws

the handling error of a failed message, unless the receiver implements toReceiveResult

Throws

ReceivedMessageReturnedToQueue if a handler called returnMessage(), unless the receiver implements toReceiveResult, which then gets it as a failure

Example

// Receiver that reports partial batch failures
const response = await bus.receive<SQSBatchResponse>(event)

---

returnMessage()

returnMessage(): Promise<void>;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:386

Instructs that the current message should be returned to the queue for retry. When the message came from a Receiver, it's also reported to the receiver host as failed so the host doesn't delete it.

Returns

Promise<void>

Throws

ReturnMessageOutsideHandlingContext if called outside a message handling context of this bus, including while another bus is handling a message

---

send()

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

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:350

Sends a command to the transport.

When called from inside a handler, the command is buffered and only sent once the handler resolves, and is dropped if the handler fails. Anywhere else (outside a handler, in read middleware or lifecycle listeners, or after the handler has already resolved) it's sent straight away. afterSend is emitted once the transport has sent it.

Type Parameters

Type Parameter
TCommand extends Command

Parameters

Parameter	Type	Description
command	TCommand	A command to send
messageAttributes	Partial<MessageAttributes>	A set of attributes to attach to the outgoing message when sent

Returns

Promise<void>

Implementation of

BusSender.send

---

start()

start(): Promise<void>;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:419

Instructs the bus to start reading messages from the underlying service queue and dispatching to message handlers.

Returns

Promise<void>

Throws

InvalidOperation if the bus is configured to be send-only

Throws

InvalidOperation if the bus has not been initialized

Throws

InvalidOperation if the bus has a receiver set

Throws

InvalidBusState if the bus is already started or in a starting state

---

stop()

stop(): Promise<void>;

Defined in: packages/bus-core/src/service-bus/bus-instance.ts:475

Stops a bus that has been started by .start(). This will wait for all running workers to complete their current message handling contexts before returning.

Returns

Promise<void>

Throws

InvalidBusState if the bus is already stopped or stopping