HTTP Decorators
Define TypeScript HTTP endpoints, parameter bindings, request bodies, headers, file uploads, SSE, status codes and redirects with AxilJS decorators.
On this page16
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().
1import { tHttp } from '@axiljs/decorator'
2
3@tHttp({ method: 'GET', path: '/users' })
4async findAll() {}
5
6@tHttp({ method: 'POST', path: '/users' })
7async create() {}
8
9@tHttp({ method: 'DELETE', path: '/users/:id' })
10async remove(id: string) {}Options
| Option | Type | Description |
|---|---|---|
method | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'ALL' | HTTP method |
path | string | Endpoint path. Supports :param segments |
version | string | API version |
prefix | string | Route prefix override |
For example:
1@tHttp({
2 method: 'POST',
3 path: '/users',
4 version: '2'
5})
6async 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.
1@tHttp({
2 method: 'GET',
3 path: '/users/:userId/posts/:postId'
4})
5async findPost(
6 @tParam('userId') userId: string,
7 @tParam('postId') postId: string
8) {}Use it when a value is part of the resource path.
For example:
/users/42/posts/100Here, userId is 42 and postId is 100.
@tQuery
@tQuery binds a query-string parameter to a handler argument.
1@tHttp({
2 method: 'GET',
3 path: '/users'
4})
5async findAll(
6 @tQuery('page') page: number,
7 @tQuery('sort') sort: string
8) {}For a request such as:
/users?page=2&sort=namethe parameters are available directly through the decorated arguments.
@tBody
@tBody binds the request body to a handler argument.
Use it for complete request DTOs:
1@tHttp({
2 method: 'POST',
3 path: '/users'
4})
5async create(
6 @tBody() dto: CreateUserDto
7) {}It can also bind a specific field:
1@tHttp({
2 method: 'POST',
3 path: '/email'
4})
5async send(
6 @tBody('to') to: string
7) {}@tHeader
@tHeader binds a request header to a handler argument.
1async request(
2 @tHeader('authorization') authorization: string,
3 @tHeader('x-tenant-id') tenantId: string
4) {}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.
1@tHttp({
2 method: 'POST',
3 path: '/avatar'
4})
5async upload(
6 @tFile({
7 maxSize: 5_000_000,
8 mimeTypes: ['image/*']
9 })
10 file: UploadedFile
11) {}Options
| Option | Type | Description |
|---|---|---|
maxSize | number | Maximum file size in bytes |
mimeTypes | string[] | Allowed MIME types |
required | boolean | Whether a file is required |
multiple | boolean | Whether multiple files are accepted |
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.
1@tHttp({
2 method: 'GET',
3 path: '/live-feed'
4})
5@tSse()
6async liveFeed() {
7 return this.eventService.stream()
8}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.
1@tHttp({
2 method: 'POST',
3 path: '/users'
4})
5@tStatus(202)
6async create() {}For a successful deletion:
1@tHttp({
2 method: 'DELETE',
3 path: '/users/:id'
4})
5@tStatus(204)
6async remove() {}This keeps response semantics explicit in the endpoint declaration.
@tRedirect
@tRedirect declares a redirect response.
1@tHttp({
2 method: 'GET',
3 path: '/old'
4})
5@tRedirect({
6 url: '/new',
7 status: 301
8})
9async 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:
1@tHttp({
2 method: 'POST',
3 path: '/orders'
4})
5@tAuth({ required: true })
6@tRateLimit({
7 limit: 10,
8 window: '1m'
9})
10@tTransaction()
11@tAudit({
12 action: 'order.created'
13})
14@tStatus(201)
15async createOrder(
16 @tBody() dto: CreateOrderDto
17) {
18 return this.orderService.create(dto)
19}Each decorator represents a separate concern:
| Decorator | Concern |
|---|---|
tHttp | HTTP endpoint |
tAuth | Authentication |
tRateLimit | Request rate control |
tTransaction | Database transaction |
tAudit | Audit event |
tStatus | HTTP response status |
tBody | Request body binding |
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:
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:
1import {
2 tHttp,
3 tParam,
4 tBody,
5 tAuth,
6 tRateLimit,
7 tTransaction,
8 tAudit,
9 tStatus
10} from '@axiljs/decorator'
11
12@tHttp({
13 method: 'POST',
14 path: '/users/:id/orders'
15})
16@tAuth({ required: true })
17@tRateLimit({
18 limit: 10,
19 window: '1m'
20})
21@tTransaction()
22@tAudit({
23 action: 'order.created'
24})
25@tStatus(201)
26async createOrder(
27 @tParam('id') userId: string,
28 @tBody() dto: CreateOrderDto
29) {
30 return this.orderService.create(userId, dto)
31}The endpoint declaration communicates the HTTP contract and its operational requirements without introducing framework-specific controller or route classes.
HTTP Decorator Reference
| Decorator | Purpose |
|---|---|
tHttp | Declare an HTTP endpoint |
tParam | Bind a path parameter |
tQuery | Bind a query parameter |
tBody | Bind request body data |
tHeader | Bind a request header |
tCookie | Bind a cookie |
tFile | Bind and constrain file uploads |
tSse | Declare an SSE endpoint |
tStatus | Define the HTTP response status |
tRedirect | Define a redirect response |
Was this page helpful?