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

# Class: BusInstance\<TTransportMessage>

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:129](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L129)

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`](../interfaces/BusSender.md)

## Constructors

### Constructor

```ts
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](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L188)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `transport` | [`Transport`](../interfaces/Transport.md)<`TTransportMessage`> |
| `concurrency` | `number` |
| `workflowRegistry` | `WorkflowRegistry` |
| `coreDependencies` | [`CoreDependencies`](../interfaces/CoreDependencies.md) |
| `messageReadMiddleware` | [`MiddlewareDispatcher`](MiddlewareDispatcher.md)<[`TransportMessage`](../interfaces/TransportMessage.md)<`any`>> |
| `handlerRegistry` | [`HandlerRegistry`](../interfaces/HandlerRegistry.md) |
| `container` | [`ContainerAdapter`](../interfaces/ContainerAdapter.md) | `undefined` |
| `sendOnly` | `boolean` |
| `receiver` | | [`Receiver`](../interfaces/Receiver.md)<`unknown`, [`TransportMessage`](../interfaces/TransportMessage.md)<`unknown`>, `unknown`> | `undefined` |
| `messageHandlingContext` | `MessageHandlingContext` |

#### Returns

`BusInstance`<`TTransportMessage`>

## Properties

| Property | Modifier | Type | Description | Defined in |
| ------ | ------ | ------ | ------ | ------ |
| <a id="property-afterdispatch"></a> `afterDispatch` | `readonly` | [`TypedEmitter`](TypedEmitter.md)<[`AfterDispatch`](../interfaces/AfterDispatch.md)> | Emitted after a message has been dispatched and completed all handler invocations | [packages/bus-core/src/service-bus/bus-instance.ts:175](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L175) |
| <a id="property-afterpublish"></a> `afterPublish` | `readonly` | [`TypedEmitter`](TypedEmitter.md)<[`AfterPublish`](../interfaces/AfterPublish.md)> | Emitted after an event has been published to the transport | [packages/bus-core/src/service-bus/bus-instance.ts:151](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L151) |
| <a id="property-afterreceive"></a> `afterReceive` | `readonly` | [`TypedEmitter`](TypedEmitter.md)<[`AfterReceive`](../interfaces/AfterReceive.md)<`TTransportMessage`>> | Emitted immediately after a message has been received from the transport | [packages/bus-core/src/service-bus/bus-instance.ts:163](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L163) |
| <a id="property-aftersend"></a> `afterSend` | `readonly` | [`TypedEmitter`](TypedEmitter.md)<[`AfterSend`](../interfaces/AfterSend.md)> | Emitted after a command has been sent to the transport | [packages/bus-core/src/service-bus/bus-instance.ts:145](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L145) |
| <a id="property-beforedispatch"></a> `beforeDispatch` | `readonly` | [`TypedEmitter`](TypedEmitter.md)<[`BeforeDispatch`](../interfaces/BeforeDispatch.md)> | Emitted before a message is dispatched to handlers | [packages/bus-core/src/service-bus/bus-instance.ts:169](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L169) |
| <a id="property-beforepublish"></a> `beforePublish` | `readonly` | [`TypedEmitter`](TypedEmitter.md)<[`BeforePublish`](../interfaces/BeforePublish.md)> | Emitted before an event is published to the transport | [packages/bus-core/src/service-bus/bus-instance.ts:139](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L139) |
| <a id="property-beforesend"></a> `beforeSend` | `readonly` | [`TypedEmitter`](TypedEmitter.md)<[`BeforeSend`](../interfaces/BeforeSend.md)> | Emitted before a command is sent to the transport | [packages/bus-core/src/service-bus/bus-instance.ts:133](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L133) |
| <a id="property-onerror"></a> `onError` | `readonly` | [`TypedEmitter`](TypedEmitter.md)<[`OnError`](../interfaces/OnError.md)<`TTransportMessage`>> | Emitted when an error occurs during message handling | [packages/bus-core/src/service-bus/bus-instance.ts:157](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L157) |

## Accessors

### state

#### Get Signature

```ts
get state(): BusState;
```

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:524](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L524)

Gets the current state of a message-handling bus

##### Returns

[`BusState`](../enumerations/BusState.md)

## Methods

### dispatchMessageToHandler()

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:781](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L781)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | [`Message`](../../bus-messages/classes/Message.md) |
| `attributes` | [`MessageAttributes`](../../bus-messages/interfaces/MessageAttributes.md) |
| `handler` | [`HandlerDefinition`](../type-aliases/HandlerDefinition.md)<[`Message`](../../bus-messages/classes/Message.md)> |

#### Returns

`Promise`<`void`>

***

### dispose()

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:502](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L502)

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

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:371](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L371)

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

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:406](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L406)

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`](../interfaces/TransportMessage.md)<`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()

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:280](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L280)

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

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:325](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L325)

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`](../../bus-messages/classes/Event.md) |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `TEvent` | An event to publish |
| `messageAttributes` | `Partial`<[`MessageAttributes`](../../bus-messages/interfaces/MessageAttributes.md)> | A set of attributes to attach to the outgoing message when published |

#### Returns

`Promise`<`void`>

#### Implementation of

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

***

### receive()

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:222](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L222)

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

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

***

### returnMessage()

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:386](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L386)

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

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:350](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L350)

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`](../../bus-messages/classes/Command.md) |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `TCommand` | A command to send |
| `messageAttributes` | `Partial`<[`MessageAttributes`](../../bus-messages/interfaces/MessageAttributes.md)> | A set of attributes to attach to the outgoing message when sent |

#### Returns

`Promise`<`void`>

#### Implementation of

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

***

### start()

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:419](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L419)

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

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

Defined in: [packages/bus-core/src/service-bus/bus-instance.ts:475](https://github.com/node-ts/bus/blob/2e6cf65c27833b707ae31ee623cfb6343770f434/packages/bus-core/src/service-bus/bus-instance.ts#L475)

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