Events
An event is a message emitted by the system when "something" happens. Again this could be a technical task being completed such as a DatabaseBackedUp, LoadBalancerScaledOut or as a result of changes in your business CreditCardCharged, UserRegistered, PackageShipped.
Use natural language in the past-tense when naming an event since it represents a historic fact has taken place. This also helps improve the readability of your code, as the history of your application can be discussed in terms of the order of events.

Creating an Event

Events are class definitions that extend from Event, eg:
1
import { Event } from '@node-ts/bus-messages'
2
​
3
export class CreditCardCharged extends Event {
4
/**
5
* A unique name that identifies the message. This should be done in namespace style syntax,
6
* ie: organisation/domain/event-name
7
*/
8
$name = 'my-app/accounts/credit-card-charged'
9
​
10
/**
11
* The contract version of this message. This can be incremented if this message changes the
12
* number of properties etc to maintain backwards compatibility
13
*/
14
$version = 1
15
​
16
/**
17
* A credit card was successfully charged
18
* @param creditCardToken Identifies the card that was charged
19
* @param amount The amount, in USD, that the card was charged for
20
*/
21
constructor (
22
readonly creditCardToken: string,
23
readonly amount: number
24
) {
25
}
26
}
Copied!
It's useful to declare all of your messages in a central package that can be shared amongst your publisher and subscriber services.

Publishing an Event

Events can have 0-to-many different subscribers, who are generally interested in performing a next action as a result of the event being raised.
Use .publish() to publish an event:
1
const creditCardCharged = new CreditCardCharged('abc', 123)
2
​
3
// Publish a message. All subscribers will receive a copy
4
await bus.publish(creditCardCharged)
5
​
6
// Publish a message along with a set of attributes
7
await bus.publish(
8
creditCardCharged,
9
{ correlationId: 'tok-1adsfas-df1' }
10
)
Copied!

Handling an Event

Events get processed by a Handler. This is a function or a class function that receives the message as a parameter and performs an operation. When the handler returns the message is deleted from the queue.
Implementing a function based handler
1
import { handlerFor } from '@node-ts/bus-core'
2
​
3
// Function based handler
4
const creditCardChargedHandler = handlerFor(
5
CreditCardCharged,
6
async (event: CreditCardCharged) => {
7
// ...
8
}
9
)
Copied!
Implementing a class based handler
1
import { Handler } from '@node-ts/bus-core'
2
​
3
// Class based handler
4
class CreditCardChargedHandler implements Handler<CreditCardCharged> {
5
messageType = CreditCardCharged
6
7
async handle (event: CreditCardCharged) {
8
// ...
9
}
10
}
Copied!
Register the handler with the bus configuration
1
const bus = await Bus.configure()
2
.withHandler(chargeCreditCardHandler) // Function based handler
3
.withHandler(ChargeCreditCardHandler) // Class function based handler
4
.initialize()
Copied!
Remember to .start() the bus to start handling messages
1
await bus.start()
Copied!