Controllers

In OzeanJs, a Controller’s main responsibility is to receive incoming HTTP requests from the client, process them, and send back an HTTP response. A Controller acts as the “front line” that connects the outside world to your application’s business logic.

The structure of a Controller is designed to be clear and modular, using Decorators to define routing and handle data.

Creating a Controller

We create a Controller by creating a TypeScript class and attaching the @Controller() decorator.

• @Controller('/prefix'): This decorator defines a “base path” or URL prefix for all routes defined within this class. For example, if you define @Controller('/users'), all routes in this controller will start with /users.

Defining Route Handlers

Inside a Controller, we create various methods that act as “Route Handlers”. They are bound to specific HTTP Methods and sub-paths using Decorators:

• @Get('/path'): For handling GET requests.
• @Post('/path'): For handling POST requests.
• @Put('/path'): For handling PUT requests.
• @Delete('/path'): For handling DELETE requests.
• @Patch('/path'): For handling PATCH requests.

Accessing Request Data (Parameter Decorators)

OzeanJs provides Parameter Decorators that help you easily extract data from various parts of the request into your handler methods:

• @Param('key'): Extracts a value from the URL parameter (e.g., from the route /users/:id).
• @Query('key'): Extracts a value from the URL’s query string (e.g., from /users?role=admin).
• @Body(): Extracts the entire request body (typically used with POST, PUT, PATCH).

Usage Example: UsersController

Here is a complete example of a UsersController that demonstrates all these concepts working together.

src/users/users.service.ts

import { Injectable } from 'ozean';

// Assume we have a UsersService that handles user-related logic
@Injectable()
export class UsersService {
  private users = [{ id: 1, name: 'John Doe' }];

  findAll() {
    return this.users;
  }

  findOne(id: number) {
    return this.users.find((user) => user.id === id);
  }

  create(userData: { name: string }) {
    const newUser = { id: this.users.length + 1, ...userData };
    this.users.push(newUser);
    return newUser;
  }
}

// src/users/users.controller.ts
import { Controller, Get, Post, Param, Body } from 'ozean';
import { UsersService } from './users.service';

@Controller('/users') // All routes in here will be prefixed with /users
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  // Handles GET requests to /users
  @Get()
  getAllUsers() {
    return this.usersService.findAll();
  }

  // Handles GET requests to /users/:id (e.g., /users/1)
  @Get('/:id')
  getUserById(@Param('id') id: string) {
    const user = this.usersService.findOne(parseInt(id, 10));
    if (!user) {
      // You can return a Response object directly to set a custom status code
      return new Response('User not found', { status: 404 });
    }
    return user; // Will be automatically converted to a JSON response
  }

  // Handles POST requests to /users
  @Post()
  createUser(@Body() userData: { name: string }) {
    return this.usersService.create(userData);
  }
}

Registering the Controller in a Module

Finally, don’t forget to register the UsersController you created in the controllers array of the relevant module (e.g., UsersModule) so that OzeanJs recognizes it and creates the routes automatically.

src/users/users.module.ts

import { Module } from 'ozean';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

With this structure, the logic for handling HTTP requests is clearly separated within the Controller, making your code cleaner and easier to maintain.