Decorators

AxilJS Decorators

Explore the 119 semantic TypeScript decorators in @axiljs/decorator for HTTP, data, security, reliability, messaging, caching, AI and more.

6 min readUpdated DocumentationEdit this page
On this page27

@axiljs/decorator provides 119 semantic TypeScript decorators for describing backend behavior, system constraints, and application capabilities.

Unlike framework-specific decorators that define controllers, modules, providers, or framework lifecycle behavior, AxilJS decorators describe what your code needs to do.

Describe the behavior. Let the runtime handle the complexity.

What Are Semantic Decorators?

A semantic decorator expresses the intent or capability of a piece of application code.

For example, instead of coupling business logic to a specific framework, you can declare that an operation:

  • Handles an HTTP request
  • Writes to a database
  • Requires a transaction
  • Retries on failure
  • Is idempotent
  • Publishes an event
  • Requires authorization
  • Must be audited
  • Uses distributed-system guarantees
  • Requires AI token limits
  • Belongs to a tenant boundary

The decorator records this information in the AxilJS metadata system. Independent consumers can then interpret that metadata.

TypeScript
TS
1import {
2  tHttp,
3  tDatabase,
4  tRetry,
5  tAudit,
6} from '@axiljs/decorator'
7
8@tHttp({ method: 'POST', path: '/payments' })
9@tDatabase({ operation: 'write' })
10@tRetry({ attempts: 3, backoff: 'exponential' })
11@tAudit({ action: 'payment.processed' })
12async processPayment(data: PaymentDto) {
13  // Business logic
14}

The application code describes the required behavior without implementing the infrastructure behind it.

Note

Decorators only record metadata. Today @axiljs/runtime executes tAudit, tRetry and tTimeout (via wire() / wireAll()) and applies tRedact / tSensitive redaction; see Runtime. Other decorators are read through the metadata registry, the axil decorator CLI, or your own consumers.

Why Semantic Decorators?

Traditional backend frameworks often use decorators to describe framework structure.

For example:

Output
TXT
@Controller()
@Module()
@Injectable()
@UseGuards()
@UseInterceptors()

These decorators are useful inside their respective frameworks, but they also make application architecture dependent on framework concepts.

AxilJS takes a different approach:

Application Code
Semantic Decorators
Metadata Registry
Independent Consumers
RuntimeDatabaseQueueSecurityAIObservability

The decorator describes the requirement. A consumer decides how that requirement is implemented.

Framework Architecture vs. System Behavior

The distinction is simple.

Framework-orientedSemantic
ControllerHTTP behavior
ModuleCapability
GuardAuthorization policy
InterceptorRuntime behavior
ProviderDependency requirement
MiddlewareRequest/system concern
Framework lifecycleApplication lifecycle
Framework-specific metadataPortable metadata

AxilJS focuses on the second column.

Backend Capabilities

AxilJS decorators cover common backend and distributed-system concerns.

HTTP

Define HTTP behavior without tying business logic to a specific web framework.

  • tHttp
  • tParam
  • tQuery
  • tBody
  • tHeader
  • tCookie
  • tFile
  • tSse
  • tRedirect
  • tStatus

Database

Declare persistence and database requirements.

  • tDatabase
  • tTransaction
  • tIsolation
  • tConsistent
  • tReadOnly
  • tEntity
  • tColumn
  • tPrimaryKey
  • tRelation
  • tTenantIsolated

Reliability

Declare how an operation should behave when dependencies fail or become slow.

  • tRetry
  • tTimeout
  • tDeadline
  • tCircuitBreaker
  • tFallback
  • tBulkhead
  • tHedge
  • tIdempotent

Distributed Systems

Define patterns commonly required by distributed applications.

  • tSaga
  • tStep
  • tCompensate
  • tOutbox
  • tInbox
  • tCheckpoint
  • tResume
  • tDedupe

These decorators allow distributed-system behavior to become explicit metadata instead of being hidden inside infrastructure code.

Concurrency

Describe concurrency and coordination requirements.

  • tConcurrency
  • tLock
  • tMutex
  • tDedupe
  • tThrottle
  • tDebounce

Messaging and Events

Define event-driven behavior independently from a specific messaging implementation.

  • tOnEvent
  • tEmit
  • tOnce
  • tMessage
  • tDeadLetter
  • tQueue
  • tJob
  • tEnqueue

Caching

Declare caching behavior and cache lifecycle requirements.

  • tCache
  • tCachePut
  • tCacheEvict
  • tCacheInvalidate
  • tCacheStampede

Security

Express authentication, authorization, and security constraints.

  • tAuth
  • tRole
  • tPermission
  • tPolicy
  • tRateLimit
  • tCsrf
  • tSanitize
  • tIpAllowList
  • tVerifiedEmail

Multi-Tenancy

Make tenant isolation and cross-tenant operations explicit.

  • tTenant
  • tTenantIsolated
  • tTenantBoundary
  • tCrossTenant

Observability

Declare operational and monitoring requirements.

  • tTrace
  • tMetric
  • tLog
  • tHealthCheck
  • tSlo
  • tCritical
  • tSample

Audit and Data Governance

Describe how sensitive or regulated data should be handled.

  • tAudit
  • tSensitive
  • tRedact
  • tRetention

API Contracts

Define API-level expectations and compatibility requirements.

  • tContract
  • tConsumes
  • tProduces
  • tPaginated
  • tDeprecated

AI

Declare AI capabilities and constraints without coupling application code to a specific AI provider.

  • tAIComplete
  • tAIEmbed
  • tAIRAG
  • tAIGuard
  • tAIModel
  • tAITokenBudget

Workflows

Describe long-running and resumable application workflows.

  • tWorkflow
  • tStep
  • tCompensate
  • tCheckpoint
  • tResume

Execution Semantics

Describe properties and requirements of application operations.

  • tAtomic
  • tPure
  • tSideEffect
  • tRequires
  • tProvides
  • tReadOnly

Feature Delivery and Resources

Declare feature gating, experiments, quotas and resource needs.

  • tFeatureFlag
  • tExperiment
  • tRollout
  • tQuota
  • tResource

Validation

Declare DTO property constraints.

  • tString
  • tNumber
  • tBoolean
  • tEmail
  • tUrl
  • tUuid
  • tOptional
  • tArray
  • tMin
  • tMax
  • tMinLength
  • tMaxLength
  • tPattern
  • tEnum
  • tNested
  • tCustom

Scheduling

Declare when and how operations should execute.

  • tSchedule
  • tInterval
  • tDelay
  • tRunAt

A Different Approach to Backend Architecture

AxilJS does not attempt to replace your application framework.

Instead, it provides a semantic metadata layer that can sit above your infrastructure.

AxilJS
Semantic Metadata
HTTPDatabaseReliabilityEventsQueuesSecurityAIObservabilityMulti-Tenancy

Different runtimes and infrastructure components can consume the same metadata.

Framework Independent

The goal is to keep semantic declarations separate from framework implementation.

Your business logic should not need to know whether the underlying system uses:

  • Express
  • Fastify
  • NestJS
  • PostgreSQL
  • Redis
  • Kafka
  • RabbitMQ
  • AWS
  • another runtime or infrastructure provider

The consumer determines how the declared behavior is implemented.

From Implementation to Declaration

A conventional implementation may require infrastructure code for retries, transactions, auditing, idempotency, caching, and distributed workflows.

With semantic decorators, the intent becomes explicit:

What should happen?
Declare the behavior
Store semantic metadata
Consumer interprets metadata
Infrastructure executes it

This creates a separation between application intent and infrastructure implementation.

Built for Modern Backend Systems

AxilJS focuses on backend concerns that become increasingly important as systems grow:

  • Distributed transactions
  • Event-driven architecture
  • Fault tolerance
  • Concurrency control
  • Multi-tenant systems
  • API contracts
  • Observability
  • Data governance
  • AI workloads
  • Workflow orchestration
  • Reliability engineering

The objective is not to create more framework abstractions.

The objective is to make system behavior explicit, composable, and machine-readable.

Core Principle

Decorators should describe system behavior — not framework structure.

AxilJS is building a semantic layer for modern TypeScript backends where application code declares capabilities and independent runtimes decide how those capabilities are executed.

List, search and inspect every decorator from the terminal with axil decorator list, axil decorator info <name> and axil decorator search <query>.

Explore the decorator CLI commands →

View AxilJS on GitHub →

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY