Messaging Decorators
Define TypeScript event subscriptions, event publication, queues, background jobs, enqueueing, dead-letter handling, and message processing with AxilJS.
AxilJS messaging decorators describe event-driven and queue-based behavior as semantic metadata.
They define what an operation consumes, produces, queues, or processes without coupling application code to a specific message broker or queue implementation.
The core messaging decorators are:
@tOnEvent@tEmit@tOnce@tQueue@tJob@tEnqueue@tDeadLetter@tMessage
@tOnEvent
Subscribes a method to events matching a specified event name or pattern.
1import { tOnEvent } from '@axiljs/decorator'
2
3@tOnEvent('user.created')
4async sendWelcomeEmail(event: UserCreatedEvent) {}
5
6@tOnEvent('order.*')
7async onAnyOrder(event: OrderEvent) {}Event patterns allow a handler to subscribe to a family of related events.
Options
| Option | Type | Description |
|---|---|---|
async | boolean | Run the handler asynchronously |
priority | number | Handler priority; higher values execute first |
1@tOnEvent('payment.failed', {
2 async: true,
3 priority: 10,
4})
5async handlePaymentFailure(event: PaymentFailedEvent) {}The decorator describes the subscription. The event consumer determines how the subscription is registered with the underlying messaging infrastructure.
@tEmit
Declares that an event should be published after a method completes successfully.
The method's return value can become the event payload.
1import { tEmit } from '@axiljs/decorator'
2
3@tEmit('order.created')
4async createOrder(dto: OrderDto) {
5 return this.orders.create(dto)
6}This allows event publication to remain separate from broker-specific publishing code.
For operations that modify persistent state, @tEmit can also be combined with transactional messaging semantics such as @tOutbox.
1@tTransaction()
2@tOutbox()
3@tEmit('order.created')
4async createOrder(dto: OrderDto) {
5 return this.orders.create(dto)
6}@tOnce
Declares a one-time event subscription.
1import { tOnce } from '@axiljs/decorator'
2
3@tOnce('app.ready')
4async warmUpCache() {}The subscription is removed after the first invocation.
This is useful for initialization, startup tasks, and one-time application events.
@tQueue
Declares a class as a queue processor.
1import {
2 tQueue,
3 tJob,
4} from '@axiljs/decorator'
5
6@tQueue('emails', {
7 concurrency: 5,
8})
9class EmailWorker {
10 @tJob('send-welcome', {
11 attempts: 3,
12 })
13 async sendWelcome(job: Job<WelcomeData>) {}
14}The queue metadata defines the processing context, while individual job decorators define the work performed within that queue.
@tJob
Declares a background job handler within a queue.
1import { tJob } from '@axiljs/decorator'
2
3@tJob('process-image', {
4 attempts: 3,
5 backoff: 'exponential',
6 timeout: 30_000,
7})
8async processImage(job: Job<ImageData>) {}Job configuration can describe retry behavior, backoff strategy, and execution timeout.
The queue consumer interprets this metadata and maps it to the underlying job-processing infrastructure.
@tEnqueue
Declares that a job should be enqueued after an operation completes.
1import { tEnqueue } from '@axiljs/decorator'
2
3@tEnqueue('emails', 'send-welcome')
4async createUser(dto: CreateUserDto) {
5 return this.users.create(dto)
6}This separates the business operation from direct interaction with the queue implementation.
For example, creating a user can declare that a welcome-email job should be queued without importing a broker-specific queue client into the business service.
@tDeadLetter
Declares dead-letter handling for terminally failed messages.
1import { tDeadLetter } from '@axiljs/decorator'
2
3@tDeadLetter({
4 channel: 'failed-payments',
5 maxAttempts: 5,
6})
7async processPayment(job: Job) {}After the configured failure policy is exhausted, the messaging consumer can route the message to the declared dead-letter channel.
Dead-letter semantics are useful for isolating messages that require investigation or manual recovery.
@tMessage
Declares a handler for a messaging channel.
This semantic is distinct from event pub/sub and is intended for direct message-channel processing.
1import { tMessage } from '@axiljs/decorator'
2
3@tMessage({ channel: 'payments', contentType: 'application/json' })
4async processPayment(message: PaymentMessage) {
5 // Message processing
6}The messaging consumer determines how the channel is connected to the underlying broker.
Event-Driven Example
A typical event-driven flow can combine event publication and subscription:
1import {
2 tEmit,
3 tOnEvent,
4} from '@axiljs/decorator'
5
6class OrderService {
7 @tEmit('order.created')
8 async createOrder(dto: CreateOrderDto) {
9 return this.orders.create(dto)
10 }
11}
12
13class NotificationService {
14 @tOnEvent('order.created')
15 async sendOrderConfirmation(event: OrderCreatedEvent) {
16 await this.email.sendConfirmation(event.payload)
17 }
18}The producer declares the event it emits, while the consumer declares the event it handles.
Neither service needs to encode broker-specific subscription or publication logic into the semantic declaration.
Queue Processing Example
Queue-based workloads can be expressed through a queue, job, and dead-letter policy:
1import {
2 tQueue,
3 tJob,
4 tDeadLetter,
5} from '@axiljs/decorator'
6
7@tQueue('payments', {
8 concurrency: 10,
9})
10class PaymentWorker {
11 @tJob('process-payment', {
12 attempts: 5,
13 backoff: 'exponential',
14 timeout: 30_000,
15 })
16 @tDeadLetter({
17 channel: 'failed-payments',
18 maxAttempts: 5,
19 })
20 async processPayment(job: Job<PaymentData>) {
21 return this.paymentService.process(job.data)
22 }
23}The metadata describes:
- The queue being processed.
- The maximum processing concurrency.
- The job identity.
- Retry behavior.
- Execution timeout.
- Terminal failure routing.
The queue infrastructure can implement these policies independently of the worker's business logic.
Combining Messaging and Distributed Semantics
Messaging decorators can be combined with distributed-system decorators when reliable event processing is required.
Producer:
1@tTransaction()
2@tOutbox()
3async createOrder(dto: CreateOrderDto) {
4 const order = await this.orders.create(dto)
5
6 return {
7 order,
8 events: [
9 {
10 type: 'order.created',
11 payload: order,
12 },
13 ],
14 }
15}Consumer:
1@tInbox({
2 ttl: 86_400_000,
3})
4@tOnEvent('order.created')
5async handleOrder(event: OrderCreatedEvent) {
6 await this.fulfillment.create(event.payload)
7}This separates:
- Database transaction semantics.
- Reliable event publication.
- Event subscription.
- Duplicate-message handling.
- Business processing.
Messaging Decorator Reference
| Decorator | Purpose |
|---|---|
@tOnEvent | Subscribes to an event or event pattern |
@tEmit | Publishes an event after successful execution |
@tOnce | Handles an event exactly once |
@tQueue | Declares a queue processor |
@tJob | Declares a background job handler |
@tEnqueue | Declares job enqueueing |
@tDeadLetter | Defines terminal failure routing |
@tMessage | Declares a messaging-channel handler |
These decorators form the messaging and queue category in the AxilJS decorator system.
Design Principle
Messaging decorators describe messaging intent rather than broker implementation.
For example:
@tOnEvent('order.created')
async handleOrder(event: OrderCreatedEvent) {}The method declares what it consumes. It does not need to know whether the underlying infrastructure uses Kafka, RabbitMQ, Redis Streams, an in-process event bus, or another messaging system.
The consumer is responsible for translating the semantic metadata into the appropriate messaging infrastructure.
This preserves the AxilJS principle of independent consumers: decorators declare behavior, while infrastructure components implement it. The documentation describes this consumer model explicitly for AxilJS metadata.
Was this page helpful?