Controllers
A controller groups related routes. Mark the class with @ApiController and its methods with a route decorator — @Get, @Post, @Put, @Patch, @Delete.
Basic controller
npx megh make:controller welcomeimport { ApiController, Get } from '@meghjs/core';
@ApiController('/welcome')
export class WelcomeController {
@Get()
sayHello() {
return 'Hello';
}
}Register it on the app:
import { Megh } from '@meghjs/core';
import { WelcomeController } from './controllers/welcome.controller';
const app = Megh.createApplication();
app.useControllers([WelcomeController]);
export default app;@ApiController may be used bare, in which case routes mount at the root:
@ApiController
export class WelcomeController {}Route parameters
| Decorator | Reads from |
|---|---|
@Param('id') | Route path segment |
@Query() | Query string |
@Body() | Request body |
@Header('x-token') | Request header |
@AuthUser() | The authenticated user |
@Get('/:id')
findOne(@Param('id') id: number) {
return { id };
}REST controller with a built-in collection
Collection holds items in memory — useful for prototypes and tests, with no database required.
npx megh make:controller users --model user --restor shorthand
npx megh m:c users -m user -rimport {
ApiController,
Get,
Post,
Put,
Delete,
Param,
Body,
Collection,
HttpExceptions,
} from '@meghjs/core';
import { User } from '../models/user';
@ApiController('/users')
export class UsersController {
private readonly users = Collection.from<User>([
{ id: 1, name: 'test 1', age: 20, active: true },
{ id: 2, name: 'test 2', age: 45, active: true },
{ id: 3, name: 'test 3', age: 38, active: false },
]);
@Get()
findAll() {
return this.users.find();
}
@Get('/:id')
findOne(@Param('id') id: number) {
const user = this.users.findOne((u) => u.id === id);
if (!user) throw HttpExceptions.notFound('User not found');
return user;
}
@Post()
create(@Body() createBody: Partial<User>) {
const lastId = this.users.max('id');
return this.users.add({ ...createBody, id: lastId + 1 });
}
@Put('/:id')
update(@Param('id') id: number, @Body() updateBody: Partial<User>) {
const user = this.users.findOne((u) => u.id === id);
if (!user) throw HttpExceptions.notFound('User not found');
this.users.update((u) => u.id === id, updateBody);
return 'Updated Successfully';
}
@Delete('/:id')
delete(@Param('id') id: number) {
const user = this.users.findOne((u) => u.id === id);
if (!user) throw HttpExceptions.notFound('User not found');
this.users.delete((u) => u.id === id);
return 'Deleted Successfully';
}
}export class User {
id: number;
name: string;
age: number;
active: boolean;
}Collection also offers paginate({ page, perPage }), max, min, sum, avg, updateBy, deleteBy and async variants (findAsync, findOneAsync). paginate returns the same { data, meta } shape as the database paginators; see Pagination.
REST controller with a MeghORM model
With --model the generated controller delegates to a service that queries a MeghORM model, which keeps data access out of the controller. The model, its DTOs and the service are generated too if they don't exist yet; the model's columns are read from the migration that creates its table.
npx megh make:controller users --model user --restor shorthand
npx megh m:c users -m user -rimport {
ApiController,
ApiResponse,
Body,
Delete,
Get,
Paginated,
Param,
Post,
Put,
Query,
} from '@meghjs/core';
import { User } from '../models/user.model';
import { CreateUserDto, ListUsersQuery, UpdateUserDto } from '../dtos/user.dto';
import { UserService } from '../services/user.service';
@ApiController('/users')
export class UsersController {
constructor(private readonly userService: UserService) {}
@Get()
@ApiResponse(200, Paginated(User))
index(@Query() query: ListUsersQuery) {
return this.userService.paginate(query);
}
@Get('/:id')
@ApiResponse(200, User)
@ApiResponse(404)
show(@Param('id') id: number) {
return this.userService.findOrFail(id);
}
@Post()
@ApiResponse(200, User)
create(@Body() body: CreateUserDto) {
return this.userService.create(body);
}
@Put('/:id')
@ApiResponse(200, User)
@ApiResponse(404)
update(@Param('id') id: number, @Body() body: UpdateUserDto) {
return this.userService.update(id, body);
}
@Delete('/:id')
@ApiResponse(200, { type: 'object', properties: { message: { type: 'string' } } })
@ApiResponse(404)
async delete(@Param('id') id: number) {
await this.userService.delete(id);
return { message: 'User deleted.' };
}
}import { AppService, type CreateInput, type PageRequest, type UpdateInput } from '@meghjs/core';
import { User } from '../models/user.model';
@AppService
export class UserService {
findAll() {
return User.query().orderBy('id').get();
}
/** One page of users: `{ data, meta }`. */
paginate(request: PageRequest = {}) {
return User.query().orderBy('id').paginate(request);
}
/** The user with this id; throws a 404 when there is none. */
findOrFail(id: number) {
return User.findOrFail(id);
}
create(input: CreateInput<typeof User>) {
return User.create(input);
}
/** `save()` writes only the columns that changed. */
async update(id: number, changes: UpdateInput<User>) {
const user = await User.findOrFail(id);
// A DTO instance holds `undefined` for every field that was not sent.
const sent = Object.fromEntries(Object.entries(changes).filter(([, value]) => value !== undefined));
return user.fill(sent).save();
}
async delete(id: number) {
const user = await User.findOrFail(id);
await user.delete();
}
}import { Model, Table, PrimaryKey, AutoIncrement, Column, CreatedAt, UpdatedAt } from '@meghjs/core';
@Table('users')
export class User extends Model {
@PrimaryKey()
@AutoIncrement()
id?: number;
@Column()
name!: string;
@Column({ unique: true })
email!: string;
@CreatedAt()
created_at?: Date;
@UpdatedAt()
updated_at?: Date;
}findOrFail throws a 404 on its own, so the controller needs no HttpExceptions.notFound check. See MeghORM for connecting the database, and Queries for what models can do.
Global prefix and versioning
setGlobalPrefix serves every controller and inline route under a prefix. Health routes and the API docs page keep their own paths; exclude leaves more routes alone (paths as declared, or RegExps):
app.setGlobalPrefix('/api', { exclude: ['/status'] });
// @ApiController('/users') @Get('/') → GET /api/usersuseVersioning serves controllers under API versions. Mark a controller or a route with @Version() (or @ApiController({ path, version })); a route's version overrides its controller's:
import { ApiController, Get, Version } from '@meghjs/core';
@Version('2')
@ApiController('/users')
export class UsersV2Controller {
@Get('/')
list() { ... }
@Get('/export')
@Version(['1', '2']) // served for both versions
export() { ... }
}| Option | Requests look like |
|---|---|
{ type: 'uri' } | GET /api/v2/users. prefix changes the v |
{ type: 'header' } | GET /api/users with X-API-Version: 2. header changes the header name |
defaultVersion is the version of controllers without @Version(). With header versioning it is also used when a request sends no version header. Without a default, unversioned controllers keep their plain path.
app.useVersioning({ type: 'uri', defaultVersion: '1' });Inline routes (app.mapGet, ...) get the global prefix but are not versioned.
Throwing errors
HttpExceptions covers the common status codes — notFound, badRequest, unauthorized, forbidden, internalError — and each takes an optional message:
throw HttpExceptions.notFound('User not found');