Decorators

Reliability Decorators

Define TypeScript retry policies, timeouts, deadlines, circuit breakers, fallbacks, bulkheads and hedging as semantic reliability constraints with AxilJS.

6 min readUpdated DocumentationEdit this page
On this page12

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
TS
1import { tRetry } from '@axiljs/decorator'
2
3@tRetry({
4  attempts: 3,
5  backoff: 'exponential',
6})
7async callPaymentAPI() {}
8
9@tRetry({
10  attempts: 5,
11  delay: 1000,
12  backoff: 'linear',
13  maxDelay: 10_000,
14})
15async syncExternalData() {}

Options

OptionTypeDescription
attemptsnumberTotal attempts, including the first call
delaynumberBase delay in milliseconds
backoff'fixed' | 'linear' | 'exponential'Backoff strategy
maxDelaynumberMaximum delay cap in milliseconds
retryOnstring[]Error names or codes that should trigger a retry

When executed by @axiljs/runtime, unset options fall back to the @axiljs/circuit retry() defaults (delay 1000 ms, backoff 'exponential', maxDelay 30000 ms).

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
TS
1import { tTimeout } from '@axiljs/decorator'
2
3@tTimeout(5000)
4async fetchUserProfile() {}

A runtime consumer can use this metadata to terminate or fail an operation once its execution exceeds the declared timeout. With @axiljs/runtime the call rejects with a TimeoutError, and the deadline applies per attempt when combined with tRetry.

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

@tDeadline

Defines an absolute execution deadline.

TypeScript
TS
1import { tDeadline } from '@axiljs/decorator'
2
3@tDeadline('2025-12-31T23:59:59Z')
4async 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
TS
1import { tCircuitBreaker } from '@axiljs/decorator'
2
3@tCircuitBreaker({
4  threshold: 5,
5  resetTimeout: 30_000,
6})
7async 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

OptionTypeDescription
thresholdnumberNumber of failures before opening the circuit
resetTimeoutnumberTime before transitioning toward half-open, in milliseconds
halfOpenAttemptsnumberNumber 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
TS
1import { tFallback } from '@axiljs/decorator'
2
3@tFallback({ value: [] })
4async getRecommendations() {}

A fallback method can also be specified:

TypeScript
TS
@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
TS
1import { tBulkhead } from '@axiljs/decorator'
2
3@tBulkhead({
4  name: 'payment-provider',
5  concurrency: 20,
6  queue: 100,
7})
8async 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

OptionTypeDescription
namestringBulkhead identifier
concurrencynumberMaximum number of parallel executions
queuenumberMaximum number of queued requests

@tHedge

Speculatively issues an extra attempt when the first one exceeds a latency threshold.

TypeScript
TS
1import { tHedge } from '@axiljs/decorator'
2
3@tHedge({ delay: 100, maxAttempts: 2 })
4async getQuote(symbol: string) {}
OptionTypeDescription
delaynumberMilliseconds to wait before firing another attempt
maxAttemptsnumberMaximum number of parallel attempts

Use hedging only on idempotent operations.

Composing Reliability Semantics

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

TypeScript
TS
1import {
2  tRetry,
3  tTimeout,
4  tCircuitBreaker,
5  tBulkhead,
6  tFallback,
7} from '@axiljs/decorator'
8
9@tRetry({
10  attempts: 3,
11  backoff: 'exponential',
12  maxDelay: 5000,
13})
14@tTimeout(10_000)
15@tCircuitBreaker({
16  threshold: 5,
17  resetTimeout: 30_000,
18})
19@tBulkhead({
20  name: 'payment-provider',
21  concurrency: 20,
22  queue: 100,
23})
24@tFallback({
25  method: 'getCachedPaymentStatus',
26})
27async getPaymentStatus(paymentId: string) {
28  return this.paymentProvider.getStatus(paymentId)
29}

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.

Note

@axiljs/runtime executes tRetry and tTimeout today (interceptor order: tAudit 100, tRetry 200, tTimeout 300; lower runs outer). tCircuitBreaker, tBulkhead, tFallback, tDeadline and tHedge are metadata only. See Interceptors.

Reliability Decorator Reference

DecoratorPurpose
@tRetryDeclares a retry policy
@tTimeoutDefines a maximum execution duration
@tDeadlineDefines an absolute execution deadline
@tCircuitBreakerPrevents repeated calls to a failing dependency
@tFallbackDefines degraded behavior after failure
@tBulkheadIsolates execution capacity and limits concurrency
@tHedgeFires a speculative extra attempt on slow calls

Design Principle

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

For example:

TypeScript
TS
@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.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY