HTTP Decorators

AxilJS HTTP decorators define the HTTP contract of an operation without coupling application code to a specific web framework or router.

They describe:

• HTTP methods and routes
• Path and query parameters
• Request bodies
• Headers and cookies
• File uploads
• Server-Sent Events (SSE)
• Response status codes
• Redirects

The HTTP runtime reads this metadata and maps it to the underlying server implementation.

@tHttp#

@tHttp declares an HTTP endpoint.

AxilJS uses a single HTTP decorator instead of separate decorators such as @Get(), @Post(), or @Delete().

import { tHttp } from '@axiljs/decorator'
 
@tHttp({ method: 'GET', path: '/users' })
async findAll() {}
 
@tHttp({ method: 'POST', path: '/users' })
async create() {}
 
@tHttp({ method: 'DELETE', path: '/users/:id' })
async remove(id: string) {}

Options#

For example:

@tHttp({
  method: 'POST',
  path: '/users',
  version: '2'
})
async create() {}

The HTTP consumer can expose this as a versioned endpoint such as /v2/users.

@tParam#

@tParam binds a URL path parameter to a handler argument.

@tHttp({
  method: 'GET',
  path: '/users/:userId/posts/:postId'
})
async findPost(
  @tParam('userId') userId: string,
  @tParam('postId') postId: string
) {}

Use it when a value is part of the resource path.

For example:

/users/42/posts/100

Here, userId is 42 and postId is 100.

@tQuery#

@tQuery binds a query-string parameter to a handler argument.

@tHttp({
  method: 'GET',
  path: '/users'
})
async findAll(
  @tQuery('page') page: number,
  @tQuery('sort') sort: string
) {}

For a request such as:

/users?page=2&sort=name

the parameters are available directly through the decorated arguments.

@tBody#

@tBody binds the request body to a handler argument.

Use it for complete request DTOs:

@tHttp({
  method: 'POST',
  path: '/users'
})
async create(
  @tBody() dto: CreateUserDto
) {}

It can also bind a specific field:

@tHttp({
  method: 'POST',
  path: '/email'
})
async send(
  @tBody('to') to: string
) {}

@tHeader#

@tHeader binds a request header to a handler argument.

async request(
  @tHeader('authorization') authorization: string,
  @tHeader('x-tenant-id') tenantId: string
) {}

This is useful for values such as:

• Authorization tokens
• Tenant identifiers
• Correlation IDs
• Custom client headers

@tCookie#

@tCookie binds a cookie value.

async getSession(
  @tCookie('session_id') sessionId: string
) {}

The application receives the selected cookie without depending directly on the underlying HTTP request object.

@tFile#

@tFile declares a file upload and its constraints.

@tHttp({
  method: 'POST',
  path: '/avatar'
})
async upload(
  @tFile({
    maxSize: 5_000_000,
    mimeTypes: ['image/*']
  })
  file: UploadedFile
) {}

Options#

The upload constraints remain part of the endpoint metadata and can be consumed by the HTTP layer.

@tSse#

@tSse marks an HTTP endpoint as a Server-Sent Events (SSE) stream.

@tHttp({
  method: 'GET',
  path: '/live-feed'
})
@tSse()
async liveFeed() {
  return this.eventService.stream()
}

This allows the HTTP runtime to treat the endpoint as a streaming response rather than a standard request-response operation.

Typical use cases include:

• Live notifications
• Progress updates
• AI response streaming
• Real-time application events
• Long-running operation status

@tStatus#

@tStatus explicitly defines the HTTP response status code.

@tHttp({
  method: 'POST',
  path: '/users'
})
@tStatus(202)
async create() {}

For a successful deletion:

@tHttp({
  method: 'DELETE',
  path: '/users/:id'
})
@tStatus(204)
async remove() {}

This keeps response semantics explicit in the endpoint declaration.

@tRedirect#

@tRedirect declares a redirect response.

@tHttp({
  method: 'GET',
  path: '/old'
})
@tRedirect({
  url: '/new',
  status: 301
})
async oldRoute() {}

The decorator defines both the redirect destination and HTTP status.

Composing HTTP Decorators#

HTTP decorators can be combined with semantic decorators from other AxilJS domains.

For example:

@tHttp({
  method: 'POST',
  path: '/orders'
})
@tAuth({ required: true })
@tRateLimit({
  limit: 10,
  window: '1m'
})
@tTransaction()
@tAudit({
  action: 'order.created'
})
@tStatus(201)
async createOrder(
  @tBody() dto: CreateOrderDto
) {
  return this.orderService.create(dto)
}

Each decorator represents a separate concern:

The decorators do not need to know about one another. Each writes its semantic metadata to the AxilJS metadata registry, where the appropriate consumer can process it.

HTTP Metadata and Consumers#

The HTTP metadata can be consumed by different parts of the AxilJS ecosystem.

For example:

@tHttp
   │
   ├── HTTP Runtime
   │      └── Route registration
   │
   ├── OpenAPI Generator
   │      └── API specification
   │
   └── ORM Studio
          └── API Explorer

This keeps the HTTP contract separate from the implementation of the underlying router.

Complete Example#

A complete endpoint can combine route declaration, request parameters, authentication, rate limiting, transactions, auditing, and response semantics:

import {
  tHttp,
  tParam,
  tBody,
  tAuth,
  tRateLimit,
  tTransaction,
  tAudit,
  tStatus
} from '@axiljs/decorator'
 
@tHttp({
  method: 'POST',
  path: '/users/:id/orders'
})
@tAuth({ required: true })
@tRateLimit({
  limit: 10,
  window: '1m'
})
@tTransaction()
@tAudit({
  action: 'order.created'
})
@tStatus(201)
async createOrder(
  @tParam('id') userId: string,
  @tBody() dto: CreateOrderDto
) {
  return this.orderService.create(userId, dto)
}

The endpoint declaration communicates the HTTP contract and its operational requirements without introducing framework-specific controller or route classes.

HTTP Decorator Reference#