Decorators

Execution Decorators

Declare TypeScript execution semantics with AxilJS: atomic operations, pure functions, explicit side effects and required or provided backend capabilities.

6 min readUpdated DocumentationEdit this page
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.

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

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

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

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

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

TypeScript
TS
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 database and payments capabilities.
  • It provides the order.created capability 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:

TypeScript
TS
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 ...'
Terminal
❯axil decorator check src/services/broken.ts

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

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

DecoratorTargetsRecordsPurpose
@tAtomicmethod{}Declares all-or-nothing execution
@tPuremethod{}Declares a side-effect-free computation
@tSideEffectmethod{ kind: string }Declares an explicit side effect
@tRequiresmethod, class{ capabilities: string[] }Lists required backend capabilities
@tProvidesmethod, 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:

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

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY