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

Class: BusConfiguration

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:62

Constructors

Constructor

new BusConfiguration(): BusConfiguration;

Returns

BusConfiguration

Methods

asSendOnly()

asSendOnly(): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:162

Configure the bus to only send messages and not receive them. No queues or subscriptions will be created for this service.

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

---

build()

build(): BusInstance;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:91

Constructs an instance of a bus from the configuration

Returns

BusInstance

Throws

BusAlreadyInitialized if the bus has already been built

Throws

ContainerNotRegistered if a class handler's constructor takes arguments and no container is registered

Throws

TransportAlreadyInUse if the transport is already used by another bus

Throws

MessageTypesConflict if the message types passed to withMessageTypes() define a $name or type differently

Throws

MessageTypeReferenceNotFound if message types passed to withMessageTypes() refer to a type they don't define

---

withConcurrency()

withConcurrency(concurrency): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:356

Sets the message handling concurrency beyond the default value of 1, which will increase the number of messages handled in parallel.

Parameters

Parameter	Type
concurrency	number

Returns

this

Default

1

Throws

BusAlreadyInitialized if called after the bus has been built

---

withContainer()

withContainer(container): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:377

Use a local dependency injection/IoC container to resolve handlers and workflows.

Parameters

Parameter	Type	Description
container	ContainerAdapter	An adapter to an existing DI container to fetch class instances from

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

---

withCustomHandler()

withCustomHandler<MessageType>(messageHandler, customResolver): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:226

Registers a custom handler that receives messages from external systems, or messages that don't implement the Message interface from @node-ts/bus-messages

Type Parameters

Type Parameter
MessageType

Parameters

Parameter	Type	Description
messageHandler	HandlerDefinition<MessageType>	A handler that receives the custom message
customResolver	CustomResolver<MessageType>	A discriminator that determines if an incoming message should be mapped to this handler.

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

---

withHandler()

Call Signature

withHandler(...classHandler): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:180

Register a handler for a specific message type. When Bus is initialized it will configure the transport to subscribe to this type of message and upon receipt will forward the message through to the provided message handler

Parameters

Parameter	Type
...classHandler	ClassConstructor<Handler<MessageBase, MessageAttributes<MessageAttributeMap, MessageAttributeMap>>>[]

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

Call Signature

withHandler<MessageType, TMessageAttributes>(...functionHandler): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:181

Register a handler for a specific message type. When Bus is initialized it will configure the transport to subscribe to this type of message and upon receipt will forward the message through to the provided message handler

Type Parameters

Type Parameter	Default type
MessageType extends Message	-
TMessageAttributes extends MessageAttributes<MessageAttributeMap, MessageAttributeMap>	MessageAttributes<MessageAttributeMap, MessageAttributeMap>

Parameters

Parameter	Type
...functionHandler	object[]

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

---

withInterruptSignals()

withInterruptSignals(signals): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:432

Sets the process signals that gracefully stop the bus, replacing the defaults. Pass an empty array to listen for none, so a host such as NestJS or AWS Lambda can own shutdown and call bus.stop() or bus.dispose() itself. Send-only buses never listen for signals.

Parameters

Parameter	Type	Description
signals	Signals[]	The signals that stop the bus

Returns

this

Default

['SIGINT', 'SIGTERM']

Throws

BusAlreadyInitialized if called after the bus has been built

Examples

// Let the host handle SIGINT and SIGTERM
Bus.configure().withInterruptSignals([])

// Also stop on SIGUSR2
Bus.configure().withInterruptSignals(['SIGINT', 'SIGTERM', 'SIGUSR2'])

---

withLogger()

withLogger(loggerFactory): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:282

Configures Bus to use a different logging provider than the default console logger

Parameters

Parameter	Type
loggerFactory	LoggerFactory

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

---

withMessageReadMiddleware()

withMessageReadMiddleware<TransportMessageType>(messageReadMiddleware): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:392

Register optional middlewares that will run for each message that is polled from the transport Note these middlewares only run when polling successfully pulls a message off the Transports queue After all the user defined middlewares have registered.

Type Parameters

Type Parameter	Default type
TransportMessageType	unknown

Parameters

Parameter	Type
messageReadMiddleware	Middleware<TransportMessage<TransportMessageType>>

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

---

withMessageTypes()

withMessageTypes(...messageTypes): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:327

Gives the bus the message types generated by bus generate-message-types (from @node-ts/bus-cli), which say how to restore the Dates, Maps, Sets, bigints and classes of each message and workflow state it receives. Pass the messageTypes export of every generated file whose messages the bus handles. Calling this again adds to the message types already passed.

A bus that receives messages must have message types for every message it handles and every workflow state it persists, or initialize() throws MessageTypesMissing. Send-only buses don't need them.

Parameters

Parameter	Type	Description
...messageTypes	MessageTypes[]	the message types of one or more generated files

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

Example

import { messageTypes as orderMessageTypes } from '@my-org/order-messages'
import { messageTypes } from './message-types.generated'

const bus = Bus.configure()
  .withMessageTypes(orderMessageTypes, messageTypes)
  .withHandler(orderPlacedHandler)
  .build()

---

withPersistence()

withPersistence(persistence): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:341

Configures Bus to use a different persistence provider than the default InMemoryPersistence provider. This is used to persist workflow data and is unused if not using workflows.

Parameters

Parameter	Type
persistence	Persistence

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

---

withReceiver()

withReceiver(receiver): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:453

Register a receiving mechanism that will be used to receive messages and deliver them to the dispatcher.

Usually the bus will connect to a transport and receive messages directly. However a different receiver plugin can be used that will become responsible for this instead.

Once the bus is configured, messages can be received by passing the received message into bus.receive().

Parameters

Parameter	Type	Description
receiver	| Receiver<unknown, TransportMessage<unknown>, unknown> | undefined	The receiver mechanism to use, or undefined to use the default behaviour

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

---

withRetryStrategy()

withRetryStrategy(retryStrategy): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:409

Configure @node-ts/bus to use a different retry strategy that determines delays between retrying failed messages.

Parameters

Parameter	Type
retryStrategy	RetryStrategy

Returns

this

Default

DefaultRetryStrategy

Throws

BusAlreadyInitialized if called after the bus has been built

---

withSerializer()

withSerializer(serializer): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:299

Configures Bus to use a different serialization provider. The provider is responsible for transforming messages to/from a serialized representation, as well as ensuring all object properties are a strong type. The bus passes its message types (see withMessageTypes()) to the serializer each time it restores an object, so one serializer can be shared by several buses.

Parameters

Parameter	Type
serializer	Serializer

Returns

this

Default

JsonSerializer

Throws

BusAlreadyInitialized if called after the bus has been built

---

withTransport()

withTransport(transportConfiguration): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:269

Configures Bus to use a different transport than the default MemoryQueue. A transport instance holds one queue and one connection, so each bus needs its own instance.

Parameters

Parameter	Type
transportConfiguration	Transport

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

---

withWorkflow()

withWorkflow(...workflow): this;

Defined in: packages/bus-core/src/service-bus/bus-configuration.ts:248

Register a workflow definition so that all of the messages it depends on will be subscribed to and forwarded to the handlers inside the workflow

Parameters

Parameter	Type	Description
...workflow	( | FunctionWorkflow<WorkflowState> | ClassConstructor<Workflow<WorkflowState>>)[]	Classes that extend Workflow, or workflows declared with defineWorkflow

Returns

this

Throws

BusAlreadyInitialized if called after the bus has been built

Throws

WorkflowNotRecognized if a workflow is neither a class that extends Workflow nor declared with defineWorkflow

Example

Bus.configure().withWorkflow(OrderWorkflow, defineWorkflow(ShippingState).startedBy(OrderPaid, ...))