platform-express

@lunafw/platform-express

HTTP adapter for the Luna framework, built on Express.

Installation

npm install @lunafw/core @lunafw/common @lunafw/platform-express

Add to tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

---

Quick start

// main.ts
import { LunaFactory } from '@lunafw/common'
import { ExpressAdapter } from '@lunafw/platform-express'
import { AppModule } from './app.module'

const bootstrap = async () => {
  const adapter = new ExpressAdapter({ port: 3000 })
  const app = await LunaFactory.createApplication(AppModule, adapter)
  await app.start()
  console.log(`HTTP server on :${adapter.getPort()}`)
}
bootstrap()

---

Routing

Routes are declared with @Controller (prefix) and @On (HTTP method + path). The method must be lowercase.

import { Injectable } from '@lunafw/core'
import { Body, Controller, NotFoundException, On, Param, Query } from '@lunafw/common'

@Injectable()
@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  // GET /users?page=1&limit=20
  @On('get', '/')
  findAll(@Query('page') page = '1', @Query('limit') limit = '20') {
    return this.usersService.paginate(Number(page), Number(limit))
  }

  // GET /users/:id
  @On('get', '/:id')
  findOne(@Param('id') id: string) {
    const user = this.usersService.findOne(id)
    if (!user) throw new NotFoundException(`User ${id} not found`)
    return user
  }

  // POST /users
  @On('post', '/')
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto)
  }

  // PATCH /users/:id
  @On('patch', '/:id')
  update(@Param('id') id: string, @Body() dto: UpdateUserDto) {
    return this.usersService.update(id, dto)
  }

  // DELETE /users/:id
  @On('delete', '/:id')
  async remove(@Param('id') id: string) {
    await this.usersService.remove(id)
    return { deleted: true }
  }
}

Route building

Routes are assembled as /<prefix><path>:

@Controller	@On	Final route
'users'	'get', '/'	GET /users/
'users'	'get', '/:id'	GET /users/:id
'posts'	'post', '/'	POST /posts/
''	'get', '/health'	GET /health

Parameter decorators

Decorator	Resolves to
@Body()	Full message.payload (request body)
@Body('field')	message.payload.field
@Param('name')	message.metadata.params.name (URL parameter)
@Query('name')	message.metadata.query.name (query string)
@Headers('name')	message.metadata.headers.name
@Message()	Full LunaMessage

When no decorators are used, the handler receives the full LunaMessage as its first argument.

---

HTTP Exceptions

Throw any exception subclass from a handler — or from a guard, pipe, or interceptor — and the adapter maps it to the correct HTTP status automatically.

import {
  BadRequestException,          // 400
  UnauthorizedException,        // 401
  ForbiddenException,           // 403
  NotFoundException,            // 404
  MethodNotAllowedException,    // 405
  RequestTimeoutException,      // 408
  ConflictException,            // 409
  GoneException,                // 410
  UnprocessableEntityException, // 422
  TooManyRequestsException,     // 429
  InternalServerErrorException, // 500
  NotImplementedException,      // 501
  ServiceUnavailableException,  // 503
} from '@lunafw/common'

// All constructors accept an optional custom message:
throw new NotFoundException('Product SKU-42 not found')
// → 404 { "statusCode": 404, "message": "Product SKU-42 not found" }

throw new ConflictException('Email address already registered')
// → 409 { "statusCode": 409, "message": "Email address already registered" }

Custom HTTP exceptions

Extend HttpException to define application-specific status codes:

import { HttpException } from '@lunafw/common'

export class PaymentRequiredException extends HttpException {
  constructor(message = 'Payment Required') {
    super(402, message)
  }
}

export class EnhanceYourCalmException extends HttpException {
  constructor(message = 'Too many requests — slow down') {
    super(420, message)
  }
}

---

Request flow for HTTP

Express receives request
        │
        ▼
  Body parsed as JSON (express.json middleware)
        │
        ▼
  Luna builds LunaMessage:
    context: 'http'
    payload: req.body
    metadata: { params, query, headers }
        │
        ▼
  Guards → Pipes → Interceptors → Handler
        │                  (exception filters wrap each stage)
        ▼
  response.json(result)   // handler return value
  response.status(N).json({ statusCode, message })  // on HttpException

---

Guards (HTTP example)

import { Injectable } from '@lunafw/core'
import { LunaGuard, LunaMessage, UnauthorizedException } from '@lunafw/common'

@Injectable()
export class JwtGuard implements LunaGuard {
  canActivate(message: LunaMessage): boolean {
    const headers = message.metadata.headers as Record<string, string>
    const token = headers['authorization']?.replace('Bearer ', '')
    if (!token) throw new UnauthorizedException('Token missing')
    return this.verifyToken(token)
  }

  private verifyToken(token: string): boolean {
    // your JWT verification logic
    return token.startsWith('valid.')
  }
}

import { UseGuards } from '@lunafw/common'

@UseGuards(JwtGuard)
@Controller('profile')
export class ProfileController { ... }

---

Validation (with class-validator)

Install the optional peer dependencies:

npm install class-validator class-transformer

Define a DTO with validation decorators:

import { IsEmail, IsString, MinLength } from 'class-validator'

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  name: string

  @IsEmail()
  email: string
}

Apply the built-in ValidationPipe:

import { ValidationPipe } from '@lunafw/common'

@On('post', '/')
@UsePipes(new ValidationPipe(CreateUserDto))
create(@Body() dto: CreateUserDto) {
  return this.usersService.create(dto)
}

Invalid body:

{ "name": "X" }

Response:

{ "statusCode": 400, "message": "name must be longer than or equal to 2 characters; email must be an email" }

---

API

new ExpressAdapter(options)

Option	Type	Description
port	number	Port to listen on. Pass 0 to let the OS assign a free port.

adapter.getPort(): number

Returns the TCP port the server is currently bound to. Useful when port: 0 was passed:

const adapter = new ExpressAdapter({ port: 0 })
await app.start()
console.log(`Listening on :${adapter.getPort()}`)  // e.g. 54321

---

License

MIT