Reliability Decorators

AxilJS reliability decorators describe how operations should behave when dependencies fail, become slow, or experience resource pressure.

They express resilience requirements at the callsite as semantic metadata. The runtime or infrastructure consumer is responsible for implementing the underlying reliability mechanisms.

`@tRetry`

Declares a retry policy for a failed operation.

typescript

import { tRetry } from '@axiljs/decorator'
 
@tRetry({
  attempts: 3,
  backoff: 'exponential',
})
async callPaymentAPI() {}
 
@tRetry({
  attempts: 5,
  delay: 1000,
  backoff: 'linear',
  maxDelay: 10_000,
})
async syncExternalData() {}

Options

Option	Type	Description
`attempts`	`number`	Maximum number of retry attempts
`delay`	`number`	Base delay in milliseconds
`backoff`	`'fixed' \| 'linear' \| 'exponential'`	Backoff strategy
`maxDelay`	`number`	Maximum delay cap in milliseconds
`retryOn`	`string[]`	Error types that should trigger a retry

retryOn should be used to avoid retrying failures that are deterministic or non-transient.

For example, a payment integration may retry temporary network failures while avoiding retries for validation or authorization errors.

`@tTimeout`

Defines the maximum execution time for an operation.

typescript

import { tTimeout } from '@axiljs/decorator'
 
@tTimeout(5000)
async fetchUserProfile() {}

A runtime consumer can use this metadata to terminate or fail an operation once its execution exceeds the declared timeout.

Timeouts are useful for preventing slow dependencies from consuming resources indefinitely.

`@tDeadline`

Defines an absolute execution deadline.

typescript

import { tDeadline } from '@axiljs/decorator'
 
@tDeadline('2025-12-31T23:59:59Z')
async endOfYearReport() {}

Unlike a relative timeout, a deadline represents an absolute point in time.

This is useful for time-bounded workflows where the operation must not continue beyond a specific deadline.

`@tCircuitBreaker`

Declares circuit-breaker behavior for an unreliable dependency.

typescript

import { tCircuitBreaker } from '@axiljs/decorator'
 
@tCircuitBreaker({
  threshold: 5,
  resetTimeout: 30_000,
})
async callPaymentGateway() {}

A circuit breaker can stop calls to a failing dependency and allow recovery before traffic is resumed. This helps prevent repeated failures from propagating through a distributed system.

Options

Option	Type	Description
`threshold`	`number`	Number of failures before opening the circuit
`resetTimeout`	`number`	Time before transitioning toward half-open, in milliseconds
`halfOpenAttempts`	`number`	Number of test requests allowed while half-open

The decorator defines the circuit policy; the runtime consumer manages circuit state and execution.

`@tFallback`

Declares a fallback value or method to use when an operation fails.

typescript

import { tFallback } from '@axiljs/decorator'
 
@tFallback({ value: [] })
async getRecommendations() {}

A fallback method can also be specified:

typescript

@tFallback({ method: 'getCachedData' })
async getLiveData() {}

Fallbacks are useful when degraded behavior is preferable to propagating an otherwise recoverable failure.

`@tBulkhead`

Defines an isolated resource capacity for an operation.

typescript

import { tBulkhead } from '@axiljs/decorator'
 
@tBulkhead({
  name: 'payment-provider',
  concurrency: 20,
  queue: 100,
})
async chargeCard() {}

Bulkheads prevent one workload or dependency from consuming all available execution capacity.

This is particularly useful for external providers, expensive operations, and shared infrastructure where uncontrolled concurrency can cause cascading resource exhaustion.

Options

Option	Type	Description
`name`	`string`	Bulkhead identifier
`concurrency`	`number`	Maximum number of parallel executions
`queue`	`number`	Maximum number of queued requests

Composing Reliability Semantics

Reliability decorators can be combined to describe multiple constraints for the same operation.

typescript

import {
  tRetry,
  tTimeout,
  tCircuitBreaker,
  tBulkhead,
  tFallback,
} from '@axiljs/decorator'
 
@tRetry({
  attempts: 3,
  backoff: 'exponential',
  maxDelay: 5000,
})
@tTimeout(10_000)
@tCircuitBreaker({
  threshold: 5,
  resetTimeout: 30_000,
})
@tBulkhead({
  name: 'payment-provider',
  concurrency: 20,
  queue: 100,
})
@tFallback({
  method: 'getCachedPaymentStatus',
})
async getPaymentStatus(paymentId: string) {
  return this.paymentProvider.getStatus(paymentId)
}

The resulting metadata describes the intended reliability policy:

Retry transient failures with exponential backoff.
Stop execution after the configured timeout.
Open the circuit after repeated failures.
Limit concurrent executions.
Queue a bounded number of additional requests.
Use a fallback when the operation cannot complete normally.

The infrastructure layer can then translate these semantics into the appropriate runtime mechanisms.

Reliability Decorator Reference

Decorator	Purpose
`@tRetry`	Declares a retry policy
`@tTimeout`	Defines a maximum execution duration
`@tDeadline`	Defines an absolute execution deadline
`@tCircuitBreaker`	Prevents repeated calls to a failing dependency
`@tFallback`	Defines degraded behavior after failure
`@tBulkhead`	Isolates execution capacity and limits concurrency

Design Principle

AxilJS reliability decorators are declarations of intent, not implementations of resilience mechanisms.

For example:

typescript

@tRetry({ attempts: 3 })
async callService() {}

does not require the business method to contain retry loops, timers, or dependency-specific resilience code. The decorator provides the semantic contract; a runtime, middleware, proxy, or infrastructure consumer can interpret that contract and implement the behavior.

This keeps resilience policy close to the operation while separating business logic from infrastructure mechanics.