Execution Decorators
Declare TypeScript execution semantics with AxilJS: atomic operations, pure functions, explicit side effects and required or provided backend capabilities.
On this page9
AxilJS execution decorators describe how an operation behaves when it runs: whether it must appear atomic, whether it is free of side effects, which side effects it performs, and which backend capabilities it needs or provides.
They make implicit execution properties explicit. A static analyzer, a runtime validator or Studio can read the declarations to reason about memoization, auditing and the dependency graph of a system without inferring it from the code.
The execution decorators are:
@tAtomic@tPure@tSideEffect@tRequires@tProvides
All five belong to the Execution category (axil decorator list --category Execution).
@tAtomic
Declares that an operation must appear atomic to its consumer.
1import { tAtomic, tTransaction } from '@axiljs/decorator'
2
3class WalletService {
4 @tAtomic()
5 @tTransaction({ isolation: 'serializable' })
6 async transfer(fromId: string, toId: string, amount: number) {}
7}tAtomic() takes no arguments and records an empty object under the tAtomic key; its presence is the signal.
tAtomic describes the guarantee seen from the outside (all-or-nothing). tTransaction, tIdempotent or tLock describe the mechanism that provides it, which is why they compose.
When to use: on operations that must be all-or-nothing from the outside.
Composes with: tTransaction, tIdempotent, tLock.
@tPure
Declares that a method is side-effect free.
1import { tPure, tCache } from '@axiljs/decorator'
2
3class PricingService {
4 @tPure()
5 calculatePrice(base: number, taxRate: number, discount: number) {
6 return Math.round(base * (1 + taxRate) * (1 - discount) * 100) / 100
7 }
8
9 @tPure()
10 @tCache({ key: 'shipping-matrix', ttl: 3_600_000 })
11 async shippingMatrix() {}
12}tPure() takes no arguments and records an empty object under the tPure key.
A pure method has no observable side effects outside its return value and depends only on its inputs. That is what makes aggressive memoization and parallelization safe.
When to use: on computations that only depend on their inputs.
When not to use: on any operation that reads mutable state or performs I/O.
Composes with: tMemoize, tCache.
Conflicts with: tSideEffect.
Warning
tPure lists tMemoize as a composition partner, but @axiljs/decorator does not export a tMemoize decorator. Use tCache for result caching.
@tSideEffect
Explicitly declares a side effect the operation performs.
1import { tSideEffect, tRetry, tAudit } from '@axiljs/decorator'
2
3class PaymentNotifier {
4 @tSideEffect('external-api')
5 @tRetry({ attempts: 3, backoff: 'exponential' })
6 @tAudit({ action: 'payment.notify' })
7 async notifyPaymentProvider(paymentId: string) {}
8}
9
10class ExportService {
11 @tSideEffect('filesystem')
12 async writeExport(path: string, data: string) {}
13}tSideEffect(kind: string) records { kind } under the tSideEffect key. The kind is a free-form string; the catalog examples use 'external-api' and 'filesystem'.
Each decorator name holds one value per method, so applying tSideEffect twice to the same method does not record two side effects: the decorator applied last (the one written highest) overwrites the other. Use a single, broader kind if a method touches several systems.
When to use: on operations touching external systems or shared state.
Composes with: tAudit, tRetry.
Conflicts with: tPure.
@tRequires
Declares the backend capabilities an operation or class depends on.
1import { tRequires } from '@axiljs/decorator'
2
3@tRequires(['database'])
4class CheckoutService {
5 @tRequires(['database', 'redis', 'payments'])
6 async checkout(cartId: string) {}
7}tRequires(capabilities: string[]) takes a single array (not rest arguments) and records { capabilities }. It targets methods and classes: on a method it is method metadata, on a class it is class metadata on the constructor. The two levels are stored separately and are not merged.
Capability names are free-form strings. Pick a stable vocabulary (for example database, redis, payments) so that tooling can match requirements against providers.
When to use: on operations depending on identifiable capabilities. Capability graphs replace hidden module coupling.
Composes with: tProvides.
@tProvides
Declares a capability that an operation or class provides.
1import { tProvides, tRequires } from '@axiljs/decorator'
2
3class PaymentService {
4 @tProvides('payment.completed')
5 @tRequires(['payments'])
6 async processPayment(orderId: string) {}
7}
8
9@tProvides('search')
10class SearchIndexer {}tProvides(capability: string) takes one capability name and records { capability }. Like tRequires it targets methods and classes, and one value is kept per target, so a method that provides several capabilities can only declare one of them with this decorator.
When to use: on operations that fulfill a named system capability.
Composes with: tRequires.
Composing Execution Semantics
Execution decorators are usually combined with the decorators that implement the guarantee they describe.
1import {
2 tAtomic,
3 tTransaction,
4 tIdempotent,
5 tSideEffect,
6 tRequires,
7 tProvides,
8} from '@axiljs/decorator'
9
10class OrderService {
11 @tAtomic()
12 @tTransaction()
13 @tIdempotent({ key: 'request.id', ttl: 86_400_000 })
14 @tSideEffect('database')
15 @tRequires(['database', 'payments'])
16 @tProvides('order.created')
17 async placeOrder(cartId: string) {}
18}The resulting metadata describes:
- The order is created all-or-nothing.
- The database work belongs to a transaction.
- Repeated calls with the same idempotency key are safe.
- The operation writes to the database.
- It needs the
databaseandpaymentscapabilities. - It provides the
order.createdcapability to the rest of the system.
Detecting Conflicts
tPure and tSideEffect declare each other in conflictsWith. Both validateComposition() and axil decorator check report the combination:
1import { tPure, tSideEffect, validateComposition } from '@axiljs/decorator'
2
3class Broken {
4 @tPure()
5 @tSideEffect('external-api')
6 async fetchRate() {}
7}
8
9const result = validateComposition(Broken.prototype, 'fetchRate')
10// result.valid === false
11// result.errors includes 'Conflict: @tPure cannot be combined with @tSideEffect ...'Note
Execution decorators only record metadata. Their catalog entries name a "Runtime", a "Static Analyzer" and @axiljs/studio as consumers, but nothing in AxilJS reads them today: @axiljs/runtime executes only tAudit, tRetry and tTimeout and applies tRedact / tSensitive redaction. tAtomic does not open a transaction, tPure does not memoize, and tRequires does not check that a capability exists. Read the declarations with getMetadata(), validate them with validateComposition(), or inspect them with the axil decorator commands. See Runtime.
Reading Execution Metadata
1import { getMetadata } from '@axiljs/decorator'
2
3getMetadata('tAtomic', OrderService.prototype, 'placeOrder')
4// {}
5
6getMetadata<{ kind: string }>('tSideEffect', OrderService.prototype, 'placeOrder')
7// { kind: 'database' }
8
9getMetadata<{ capabilities: string[] }>('tRequires', CheckoutService)
10// { capabilities: ['database'] } (class-level)
11
12getMetadata<{ capability: string }>('tProvides', PaymentService.prototype, 'processPayment')
13// { capability: 'payment.completed' }Walking every class with tRequires and tProvides gives you a capability graph: an edge from each requirement to the operations that provide it, and a list of requirements no one provides.
Execution Decorator Reference
| Decorator | Targets | Records | Purpose |
|---|---|---|---|
@tAtomic | method | {} | Declares all-or-nothing execution |
@tPure | method | {} | Declares a side-effect-free computation |
@tSideEffect | method | { kind: string } | Declares an explicit side effect |
@tRequires | method, class | { capabilities: string[] } | Lists required backend capabilities |
@tProvides | method, class | { capability: string } | Declares a provided backend capability |
Design Principle
Execution decorators state properties of an operation that are otherwise only implied by its implementation.
For example:
@tSideEffect('external-api')
async notifyPaymentProvider() {}does not change how the method runs. It makes the side effect visible to reviewers, analyzers and tooling, and it lets a contradiction such as declaring the same method tPure be caught before it ships. See the decorator overview for how metadata is stored and consumed.
Was this page helpful?