DTOs ni nini katika NestJS?

Question

Accepted Answer

**DTO (Data Transfer Object)** ni class inayofafanua **umbo la data** linalotumwa kwenda au kutoka kwa API yako — kwa kawaida muundo wa request body. DTOs hutoa usalama wa aina (type safety), hutumika kama mkataba wazi kwa endpoints, na (pamoja na validation decorators) huwezesha validation ya input kiotomatiki.

## Kufafanua DTO

```ts
import { IsEmail, IsString, MinLength, IsOptional, IsInt, Min } from "class-validator";

export class CreateUserDto {
  @IsEmail()                    // must be a valid email
  email: string;

@IsString()
  @MinLength(8)                 // password at least 8 chars
  password: string;

@IsOptional()                 // optional field
  @IsInt()
  @Min(0)
  age?: number;
}
```

DTO ni class ya kawaida inayoelezea data inayotarajiwa, ikiwa na **validation decorators** (kutoka `class-validator`) zinazobainisha kanuni ambazo kila field lazima itimize.

## Kutumia DTO ndani ya controller

```ts
@Post()
create(@Body() dto: CreateUserDto) {     // the body is typed AND validated as CreateUserDto
  // dto is guaranteed to be valid here (with the validation pipe enabled)
  return this.usersService.create(dto);
}
```

`@Body() dto: CreateUserDto` huweka aina kwa request body na — pamoja na validation pipe ikiwa imewashwa — huithibitisha (validate) kiotomatiki kabla ya handler yako kuendeshwa.

## Kuwezesha validation kiotomatiki

```ts
// main.ts — turn on the global validation pipe
app.useGlobalPipes(new ValidationPipe({
  whitelist: true,              // strip properties NOT in the DTO (security)
  forbidNonWhitelisted: true,   // reject requests with extra unknown properties
  transform: true,              // auto-transform payloads to DTO instances + convert types
}));
```

Kwa `ValidationPipe`, NestJS huthibitisha bodies zinazoingia dhidi ya decorators za DTO kiotomatiki — ikirudisha kosa la 400 lenye maelezo iwapo validation itashindikana, kabla ya code yako kuendeshwa.

## DTOs dhidi ya Entities

```text
DTO    → the shape of data crossing the API boundary (request/response contract)
Entity → the database model (e.g. a TypeORM entity / Prisma model)
→ Keep them SEPARATE: the API contract shouldn't be coupled to the DB schema.
  (A CreateUserDto has password+email; the User entity has id, timestamps, etc.)
```

DTOs hutofautiana kwa makusudi na database entities — huwakilisha kile API inachopokea/kurudisha, kikiwa kimetenganishwa na uhifadhi wa ndani.

## Tofauti na utumiaji tena

```ts
import { PartialType } from "@nestjs/mapped-types";
// derive an UpdateUserDto where all fields are optional — no duplication
export class UpdateUserDto extends PartialType(CreateUserDto) {}
```

## Kwa nini ni muhimu

DTOs ni muundo muhimu wa NestJS unaoleta usalama wa aina, mikataba wazi ya API, na validation kiotomatiki kwa endpoints zako.

Hufafanua hasa data ambayo endpoint hupokea (umbo la request), ikikupa typing ya wakati wa kukusanya (compile-time) na kutumika kama mikataba inayojielezea yenyewe.

Muhimu zaidi, zikiunganishwa na decorators za `class-validator` na `ValidationPipe`, huwezesha **validation ya input kiotomatiki** — requests zenye makosa au zenye nia ovu hukataliwa kwa makosa wazi *kabla* ya kufika kwenye business logic yako, jambo ambalo ni muhimu kwa usalama na uimara (chaguo la `whitelist` pia huondoa properties zisizotarajiwa).

Kuelewa DTOs, jinsi ya kuongeza kanuni za validation, jinsi ya kuwezesha validation pipe, na kanuni muhimu ya **kuweka DTOs tofauti na database entities** (kutenganisha mkataba wa API na uhifadhi wa ndani) ni msingi kwa kujenga API za NestJS salama, zilizopangwa vizuri, na zinazoweza kudumishwa.

DTOs huonekana karibu katika kila endpoint inayopokea input, jambo linalozifanya kuwa maarifa ya kila siku na ya msingi.