Reliability Decorators
Define TypeScript retry policies, timeouts, deadlines, circuit breakers, fallbacks, bulkheads and hedging as semantic reliability constraints with AxilJS.
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.
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
| Option | Type | Description |
|---|---|---|
attempts | number | Total attempts, including the first call |
delay | number | Base delay in milliseconds |
backoff | 'fixed' | 'linear' | 'exponential' | Backoff strategy |
maxDelay | number | Maximum delay cap in milliseconds |
retryOn | string[] | 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.
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.
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.
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
| 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.
1import { tFallback } from '@axiljs/decorator'
2
3@tFallback({ value: [] })
4async getRecommendations() {}A fallback method can also be specified:
@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.
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
| Option | Type | Description |
|---|---|---|
name | string | Bulkhead identifier |
concurrency | number | Maximum number of parallel executions |
queue | number | Maximum number of queued requests |
@tHedge
Speculatively issues an extra attempt when the first one exceeds a latency threshold.
1import { tHedge } from '@axiljs/decorator'
2
3@tHedge({ delay: 100, maxAttempts: 2 })
4async getQuote(symbol: string) {}| Option | Type | Description |
|---|---|---|
delay | number | Milliseconds to wait before firing another attempt |
maxAttempts | number | Maximum 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.
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
| 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 |
@tHedge | Fires a speculative extra attempt on slow calls |
Design Principle
AxilJS reliability decorators are declarations of intent, not implementations of resilience mechanisms.
For example:
@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?