Decorators

Distributed System Decorators

Define TypeScript Saga workflows, compensation, transactional outbox and inbox processing, checkpoints, and resumable distributed operations with AxilJS.

6 min readUpdated DocumentationEdit this page
On this page7

Distributed decorators describe workflows and transactional messaging patterns that span multiple services or execution boundaries.

AxilJS expresses these requirements as semantic metadata rather than coupling application code to a specific workflow engine, message broker, or distributed transaction implementation.

The core distributed decorators are:

  • @tSaga
  • @tStep
  • @tCompensate
  • @tOutbox
  • @tInbox
  • @tCheckpoint

@tSaga

Declares a class as a distributed Saga workflow.

A Saga models a sequence of operations that may execute across services. If a later step cannot complete, previously completed work can be compensated.

TypeScript
TS
1import {
2  tSaga,
3  tStep,
4  tCompensate,
5} from '@axiljs/decorator'
6
7@tSaga('checkout')
8class CheckoutWorkflow {
9  @tStep('reserve-inventory')
10  async reserveInventory() {}
11
12  @tStep('charge-payment')
13  async chargePayment() {}
14
15  @tStep('create-order')
16  async createOrder() {}
17
18  @tCompensate('charge-payment')
19  async refundPayment() {}
20}

The Saga decorator identifies the workflow while its step and compensation metadata describe the individual execution units. tSaga is a class decorator and takes (name, { version?, timeout? }).

A Saga is particularly useful when a traditional database transaction cannot span the complete operation because the workflow crosses service or infrastructure boundaries.

@tStep

Declares an ordered step within a Saga or durable workflow.

TypeScript
TS
1import { tStep } from '@axiljs/decorator'
2
3@tStep('reserve-inventory', {
4  order: 1,
5})
6async reserve() {}
7
8@tStep('charge-payment', {
9  order: 2,
10})
11async charge() {}

The step metadata defines the workflow structure without embedding orchestration logic directly into the method.

Step Options

OptionTypeDescription
ordernumberExecution order of the step

order is the only step option.

@tCompensate

Declares a compensating action for a previously completed workflow step.

TypeScript
TS
1import { tCompensate } from '@axiljs/decorator'
2
3@tCompensate('charge-payment')
4async refundPayment() {}

If a later workflow step fails, the workflow consumer can use the compensation metadata to determine which action should reverse or compensate the affected step.

Compensation is a central part of Saga-based distributed transactions because the original operation may no longer be reversible through a single database rollback.

@tOutbox

Declares transactional event publication using the Outbox pattern.

TypeScript
TS
1import {
2  tTransaction,
3  tOutbox,
4} from '@axiljs/decorator'
5
6@tTransaction()
7@tOutbox()
8async createOrder(dto: OrderDto) {
9  const order = await this.orders.create(dto)
10
11  return {
12    order,
13    events: [
14      {
15        type: 'order.created',
16        payload: order,
17      },
18    ],
19  }
20}

The Outbox pattern coordinates event publication with the database transaction so that database state and the corresponding event are persisted consistently.

The source describes @tOutbox as providing at-least-once event delivery.

A typical implementation can persist the event in an outbox store as part of the transaction and publish it asynchronously afterward.

@tInbox

Declares processed-message tracking for incoming events.

TypeScript
TS
1import {
2  tInbox,
3  tOnEvent,
4} from '@axiljs/decorator'
5
6@tInbox({
7  ttl: 86_400_000,
8})
9@tOnEvent('order.created')
10async handleOrder(event: OrderEvent) {}

The Inbox pattern tracks processed message identifiers so duplicate deliveries can be detected.

The source describes @tInbox as providing at-most-once event consumption by tracking processed message IDs.

This is useful when message brokers provide redelivery or at-least-once delivery semantics.

@tCheckpoint

Marks a resumable point in a long-running workflow.

TypeScript
TS
1import { tCheckpoint } from '@axiljs/decorator'
2
3@tCheckpoint('after-index')
4async indexDocument() {}

If a workflow fails after reaching a checkpoint, a workflow consumer can resume from the checkpoint instead of restarting the entire workflow.

This is particularly useful for long-running processing pipelines where earlier steps are expensive or have already produced durable results.

Full Saga Example

The distributed decorators can be composed with other AxilJS semantics.

TypeScript
TS
1import {
2  tSaga,
3  tStep,
4  tCompensate,
5  tCheckpoint,
6  tTimeout,
7} from '@axiljs/decorator'
8
9@tSaga('document-processing')
10class DocumentWorkflow {
11  @tStep('extract', {
12    order: 1,
13  })
14  @tTimeout(30_000)
15  async extract(documentId: string) {}
16
17  @tStep('classify', {
18    order: 2,
19  })
20  @tCheckpoint('after-classify')
21  async classify(documentId: string) {}
22
23  @tStep('index', {
24    order: 3,
25  })
26  async index(documentId: string) {}
27
28  @tCompensate('index')
29  async removeFromIndex(documentId: string) {}
30
31  @tCompensate('classify')
32  async clearClassification(documentId: string) {}
33}

This workflow describes:

  1. Extract the document.
  2. Classify the document.
  3. Persist the indexing result.
  4. Create a checkpoint after classification.
  5. Remove the index if the indexing step must be compensated.
  6. Clear classification if that step must be compensated.

The source uses this same pattern to demonstrate Saga steps, checkpoints, timeouts, and compensation working together.

Transactional Messaging

Distributed applications commonly need to coordinate database state and message publication.

Consider an order creation operation:

TypeScript
TS
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}

The semantic declarations communicate two distinct requirements:

  • The database mutation belongs to a transaction.
  • The resulting event must participate in transactional outbox processing.

This allows the implementation to handle persistence and event delivery without forcing the business method to manage broker-specific mechanics.

Outbox and Inbox Together

For a distributed workflow, Outbox and Inbox semantics can be used on opposite sides of a message boundary.

Producer:

TypeScript
TS
1@tTransaction()
2@tOutbox()
3async createOrder(dto: OrderDto) {
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:

TypeScript
TS
1@tInbox({
2  ttl: 86_400_000,
3})
4@tOnEvent('order.created')
5async handleOrder(event: OrderEvent) {
6  await this.fulfillment.create(event.payload)
7}

The producer expresses reliable event publication while the consumer expresses duplicate-message handling.

Together, these semantics provide a declarative foundation for reliable asynchronous communication.

Workflow Resumption

Long-running workflows can combine steps and checkpoints:

TypeScript
TS
1@tSaga('video-processing')
2class VideoWorkflow {
3  @tStep('transcode', {
4    order: 1,
5  })
6  async transcode(videoId: string) {}
7
8  @tStep('analyze', {
9    order: 2,
10  })
11  @tCheckpoint('after-analysis')
12  async analyze(videoId: string) {}
13
14  @tStep('publish', {
15    order: 3,
16  })
17  async publish(videoId: string) {}
18}

If the workflow fails during publication, a workflow consumer can use the checkpoint metadata to avoid repeating completed processing.

@tWorkflow and @tResume

The Workflow category adds a class-level workflow declaration and a resume point:

TypeScript
TS
1import { tWorkflow, tStep, tCheckpoint, tResume } from '@axiljs/decorator'
2
3@tWorkflow('video-processing', { version: '2', resumable: true })
4class VideoPipeline {
5  @tStep('transcode', { order: 1 })
6  @tCheckpoint('after-transcode')
7  async transcode(videoId: string) {}
8
9  @tResume({ from: 'after-transcode' })
10  async resume(videoId: string) {}
11}

tWorkflow(name, { version?, resumable? }) targets classes; tResume({ from? }) targets methods.

Distributed Decorator Reference

DecoratorPurpose
@tSagaDeclares a distributed Saga workflow
@tStepDefines an ordered workflow step
@tCompensateDefines compensation for a workflow step
@tOutboxDeclares transactional event publication
@tInboxTracks processed message identifiers
@tCheckpointDefines a resumable workflow point
@tWorkflowDeclares a durable workflow class
@tResumeDeclares where a workflow resumes

These decorators form the distributed transaction category in AxilJS.

Design Principle

Distributed decorators should describe workflow intent, not implement the workflow engine.

For example:

TypeScript
TS
1@tSaga('checkout')
2class CheckoutWorkflow {
3  // ...
4}

The decorator does not need to know whether the workflow is ultimately executed by a database-backed orchestrator, a state machine, or another workflow runtime.

The workflow engine is a separate consumer: Temporal, a custom state machine or a database-driven orchestrator could all execute the same metadata.

This separation keeps business code focused on domain operations while allowing infrastructure implementations to evolve independently.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY