Forem: Tochukwu Nwosa

Role vs Permission: Why Your RBAC Shouldn't Use Role Checks

Tochukwu Nwosa — Thu, 11 Dec 2025 13:45:06 +0000

You're building a multi-user app. You add an admin who can delete products and a sales rep who can't. Your code looks like this:

// Bad approach - checking roles directly
if (user.role === 'admin') {
  await deleteProduct(id);
} else {
  throw new ForbiddenException('Only admins can delete');
}

This works... until your client asks: "Can I add a Manager role? They should delete products but not manage users."

Now you're stuck. Your code checks roles, not permissions. Time to refactor everything.

I learned this the hard way building Mytreda, and here's what I wish I knew from day one.

Why Role Checks Break Down

Problem 1: Role Explosion

You start with 2 roles: Admin, Sales Rep. Clean and simple.

Then the client wants: Manager, Accountant, Warehouse Staff. Each role needs slightly different permissions.

Your code becomes:

if (role === 'admin' || role === 'manager' || role === 'accountant') {
  // delete product
}

Now imagine 10 roles. 50 endpoints. Good luck.

Problem 2: Hard to Change

Business logic is scattered across controllers. Want to let Sales Reps update products?

You'll search the entire codebase for user.role === 'sales_rep' checks. Every change risks breaking something else.

Problem 3: No Granular Control

"Can sales reps view reports but not delete sales?"

Roles are too broad. Permissions are specific. That's the difference.

The Solution: Permission-Based Access Control

Stop asking "What's your role?" Start asking "Do you have permission to do this?"

Step 1: Define Permissions (Not Roles)

// constants/permissions.ts
export enum Permission {
  // Products
  VIEW_PRODUCTS = 'VIEW_PRODUCTS',
  CREATE_PRODUCT = 'CREATE_PRODUCT',
  UPDATE_PRODUCT = 'UPDATE_PRODUCT',
  DELETE_PRODUCT = 'DELETE_PRODUCT',

  // Sales
  VIEW_SALES = 'VIEW_SALES',
  CREATE_SALE = 'CREATE_SALE',
  DELETE_SALE = 'DELETE_SALE',

  // Admin
  INVITE_USERS = 'INVITE_USERS',
  VIEW_ACTIVITY_LOGS = 'VIEW_ACTIVITY_LOGS',
}

Key insight: These are actions, not identities. Anyone can have any combination of these.

Step 2: Map Roles to Permissions

export const ROLE_PERMISSIONS: Record<UserRole, Permission[]> = {
  admin: [
    // Admins get everything
    Permission.VIEW_PRODUCTS,
    Permission.CREATE_PRODUCT,
    Permission.UPDATE_PRODUCT,
    Permission.DELETE_PRODUCT,
    Permission.VIEW_SALES,
    Permission.CREATE_SALE,
    Permission.DELETE_SALE,
    Permission.INVITE_USERS,
    Permission.VIEW_ACTIVITY_LOGS,
  ],

  sales_rep: [
    // Sales reps are limited
    Permission.VIEW_PRODUCTS,
    Permission.CREATE_PRODUCT,
    Permission.VIEW_SALES,
    Permission.CREATE_SALE,
  ],
};

// Helper function
export function hasPermission(role: UserRole, permission: Permission): boolean {
  return ROLE_PERMISSIONS[role]?.includes(permission) ?? false;
}

Now roles are just bundles of permissions. Want to add a Manager? Just create a new bundle. No code changes.

Step 3: Check Permissions, Not Roles

// Before (role check)
if (user.role === 'admin') {
  await deleteProduct(id);
}

// After (permission check)
if (hasPermission(user.role, Permission.DELETE_PRODUCT)) {
  await deleteProduct(id);
}

Implementing in NestJS

You can wrap this in a guard + decorator for clean controller code:

// common/guards/permissions.guard.ts
@Injectable()
export class PermissionsGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredPermissions = this.reflector.get<Permission[]>(
      'permissions',
      context.getHandler(),
    );

    if (!requiredPermissions) return true;

    const { user } = context.switchToHttp().getRequest();

    return requiredPermissions.every(permission =>
      hasPermission(user.role, permission)
    );
  }
}

Now your controllers look like this:

@Controller('products')
@UseGuards(JwtAuthGuard, PermissionsGuard)
export class ProductsController {

  @Post()
  @RequirePermission(Permission.CREATE_PRODUCT)
  create(@Body() dto: CreateProductDto) {
    return this.productsService.create(dto);
  }

  @Delete(':id')
  @RequirePermission(Permission.DELETE_PRODUCT) // Only admins have this
  remove(@Param('id') id: string) {
    return this.productsService.remove(id);
  }
}

Self-documenting code. You know exactly what each endpoint requires.

Why This is Better

1. Add New Roles in One Place

Client: "Add a Manager role."

You: Update one file.

manager: [
  Permission.VIEW_PRODUCTS,
  Permission.UPDATE_PRODUCT,
  Permission.DELETE_PRODUCT,
  Permission.VIEW_SALES,
],

Done. No controller changes. No grep'ing the codebase.

2. Change Permissions Without Touching Controllers

Client: "Sales reps should update products now."

You: Add Permission.UPDATE_PRODUCT to the sales_rep array.

No code refactor. No testing 50 endpoints. Just update the map.

3. Easy Testing

it('should allow admin to delete product', () => {
  const canDelete = hasPermission('admin', Permission.DELETE_PRODUCT);
  expect(canDelete).toBe(true);
});

it('should deny sales_rep from deleting product', () => {
  const canDelete = hasPermission('sales_rep', Permission.DELETE_PRODUCT);
  expect(canDelete).toBe(false);
});

Your authorization logic is now testable in isolation. Beautiful.

When to Use Each Approach

Use Role Checks When:

You have 1-2 fixed roles that will NEVER change
Very simple app (todo list, personal blog)
Prototype/MVP (but plan to refactor)

Use Permission Checks When:

Business requirements might change (they always do)
More than 2 roles
Enterprise/production apps
Client might ask: "Can we add a new role?"

If you're not sure, use permissions. It's easier to start with permissions than to refactor from roles later.

TL;DR

❌ Don't do this:

if (user.role === 'admin') { /* do thing */ }

✅ Do this:

if (hasPermission(user.role, Permission.DO_THING)) { /* do thing */ }

Why:

Define permissions (VIEW, CREATE, UPDATE, DELETE)
Map roles to permissions in ONE place
Check permissions, not roles
New role? Just update the permissions map

Your turn: Look at your current codebase. How many places do you check user.role === 'something'? That's how many places will break when you add a new role.

Refactor now, thank yourself later.

Questions? Drop a comment below.

Want to connect?

Portfolio: tochukwu-nwosa.vercel.app
Twitter/X: @tochukwudev
GitHub: tochukwunwosa
LinkedIn: nwosa-tochukwu

I'm building a SaaS for Nigerian traders. Here's what broke me.

Tochukwu Nwosa — Sun, 07 Dec 2025 06:03:25 +0000

I started building MyTreda this month. Alone. Me and Claude Code.

MyTreda is a free inventory and debt management app for Nigerian traders — the kiosk owner, the one-shop guy, the woman selling at Balogun Market who's been tracking her stock in an exercise book for 15 years. That's my user. Not a startup founder. Not a tech bro. Someone who just needs to know what they have, who owes them money, and whether they made profit today.

I'm a frontend developer learning backend. NestJS, MongoDB, TypeScript. And I have to say — the tutorials will teach you how to build. They won't teach you what to build for.

Here's what I mean.

The monorepo broke me first

Before I could write a single line of real business logic, I spent what felt like forever just trying to set up the project structure. Monorepo, NestJS, MongoDB, shared types across packages.

Every tutorial assumes you already know the other thing. NestJS tutorials assume you know monorepos. Monorepo tutorials assume you know NestJS. MongoDB integration tutorials assume both. I was new to all of it.

The shared types were the worst part. You want your frontend and backend to speak the same language — same enums, same interfaces. In theory, clean. In practice, I was getting circular dependency errors I didn't understand, module resolution issues that made no sense, and TypeScript screaming at me for reasons I couldn't explain.

I'm not going to pretend I solved it elegantly. I broke it, fixed it, broke it again, Googled the same error four different ways, and eventually — it worked. I don't know exactly what made it click. That's just the honest version of the story.

WhatsApp isn't a feature. It's infrastructure.

When I was designing the registration flow, my instinct (from tutorials) was: email + password, maybe phone number as optional.

Then I thought about my actual user. The woman at Balogun. How does she contact customers who owe her money? WhatsApp. How does her supplier send the new price list? WhatsApp. How does she confirm delivery? WhatsApp.

Email is almost irrelevant. WhatsApp is the business phone line, the invoicing system, the customer relationship tool — all in one.

So I made WhatsApp number a core registration field. Not optional settings. Not "add later." Right there during onboarding.

@IsString()
@Matches(/^(\+234|0)[789]\d{9}$/, {
  message: 'Invalid Nigerian phone number format (e.g., +2348012345678 or 08012345678)',
})
whatsappNumber?: string;

Nigerian numbers come in two formats — +2348012345678 or 08012345678. The regex handles both. Small thing. But if I'd copied a Western tutorial's phone validation, it would have rejected half my users at the door.

"Retail" is not a business type

Most SaaS apps let you pick: Retail. Services. E-commerce.

That's useless to me.

The guy selling motor parts in Ladipo Market has completely different inventory needs from the cosmetics seller in Balogun. Motor parts guy needs car model, part number, compatibility. Cosmetics girl needs shades, expiry dates, batch tracking. "Retail" covers both and helps neither.

So I built six specific business types:

export enum BusinessType {
  COSMETICS = "cosmetics",
  MOTOR_PARTS = "motorParts",
  BUILDING_MATERIALS = "buildingMaterials",
  FASHION = "fashion",
  ELECTRONICS = "electronics",
  FOODSTUFF = "foodstuff"
}

Cosmetics, Motor Parts, Building Materials, Fashion, Electronics, Foodstuff. These are the six most common business types you'll see in Lagos markets. Not arbitrary. I walked through this in my head market by market.

The plan is that when you pick your business type, the product form adapts — Motor Parts gets part number and compatible car models, Cosmetics gets shade and expiry date. Not there yet. But the foundation is set.

Nigerian internet will humble you

Standard MongoDB setup from every tutorial:

MongooseModule.forRoot(uri)

That's it. Connect and go.

Except Nigerian internet is... unpredictable. Even in Lagos. You'll get a 2-second drop in the middle of a transaction and suddenly your app can't talk to your database and you have no idea why.

So I added retry logic:

retryAttempts: 3,
retryDelay: 1000,

And connection event logging:

connection.on('disconnected', () => {
  console.warn('[MongoDB] Disconnected');
});
connection.on('error', (error: Error) => {
  console.error('[MongoDB] Connection error:', error.message);
});

When a user messages me "app not working," I want to know — was it a connection drop? A retry that failed? Did it recover? Without this, I'm debugging blind.

Performance optimization is a luxury. Connection resilience is a requirement.

Error messages should not require a CS degree

MongoDB throws this when there's a duplicate email:

E11000 duplicate key error collection: mytreda.users index: email_1 dup key: { email: "test@test.com" }

My users are traders. Some of them don't own a laptop. That error message might as well be in Latin.

So I catch it and translate it:

private handleDuplicateKeyError(exception: any) {
  const field = Object.keys(exception.keyPattern || {})[0];
  const value = (exception.keyValue || {})[field];
  const message = field
    ? `${this.formatFieldName(field)} '${value}' already exists`
    : 'Duplicate entry detected';
  return { status: HttpStatus.CONFLICT, message };
}

Now they see: "Email 'test@test.com' already exists."

Clear. Actionable. No jargon. That's the standard I hold every error message to.

One thing that frustrates me about building from Lagos

We give 100% to everything we build here. The Nigerian developer community is genuinely talented — I see it every day on Twitter, on GitHub, in communities. But because of where we're from, there's this ceiling. The country's reputation outside makes it feel like we have to work twice as hard just to be taken seriously.

I'm not building MyTreda to prove anything to anyone outside Nigeria. I'm building it because the woman at Balogun Market deserves software that was actually built for her — not adapted from something built for a Shopify merchant in Toronto.

That's enough reason for me.

Where MyTreda is right now

Auth is done. Products module is next.

The app is live and free at mytreda.com — works offline, runs on any Android or iPhone, no app download needed. If you know a Nigerian trader who's still using exercise books or scattered WhatsApp messages to track their business, send them the link.

I'm building this in public. If you're building something for African markets and you've hit walls the tutorials don't cover — I'd genuinely love to hear about it in the comments.

Find me here:

Twitter/X: @tochukwudev
GitHub: github.com/tochukwunwosa
LinkedIn: linkedin.com/in/nwosa-tochukwu
The app: mytreda.com

NestJS Week 3: Why Your User Update Endpoint Shouldn't Do Everything

Tochukwu Nwosa — Wed, 26 Nov 2025 16:19:22 +0000

Catching Up

If you've been following my NestJS journey, you know I've covered:

This week brought another "aha moment" that completely changed how I think about API design.

The Mistake I Almost Made

While building user management for my project, I was about to create this:

// ❌ One endpoint to rule them all
@Patch('users/:id')
updateUser(@Param('id') id: string, @Body() updateDto: UpdateUserDto) {
  // Update anything: profile, password, email, role, account status...
  return this.usersService.update(id, updateDto);
}

Seemed efficient, right? One endpoint, one DTO, one service method. Very DRY.

Then I learned about two principles that made me rethink everything.

Two Principles That Changed My Approach

1. Single Responsibility Principle (SRP)

Remember from Week 2 how we used exception filters to separate error handling from business logic? Same concept here.

Each endpoint should have ONE reason to exist.

When one endpoint handles profile updates, password changes, email verification, AND admin operations:

Changing password logic forces you to touch profile update code
Adding email verification affects password flows
Admin operations are mixed with user self-service
Testing becomes a nightmare

2. Principle of Least Privilege

Give the minimum permissions necessary. Nothing more.

With one big update endpoint:

Users might change their own role to admin
Password changes might not require old password verification
Email changes could bypass verification flows
You can't properly separate user actions from admin actions

The Better Way: Separate Endpoints

// Profile updates (businessName, whatsappNumber)
@Patch(':id')
@UseGuards(AuthGuard)
updateUserProfile(
  @Param('id') id: string,
  @Body() dto: UpdateUserDto
) {
  return this.usersService.updateProfile(id, dto);
}

// Password changes (requires old password verification)
@Post('auth/change-password')
@UseGuards(AuthGuard)
changePassword(@Body() dto: ChangePasswordDto) {
  return this.authService.changePassword(dto);
}

// Email changes (requires email verification)
@Post('auth/change-email')
@UseGuards(AuthGuard)
changeEmail(@Body() dto: ChangeEmailDto) {
  return this.authService.changeEmail(dto);
}

// Admin operations (isActive, role changes)
@Patch(':id/status')
@UseGuards(AuthGuard, AdminGuard)
updateUserStatus(
  @Param('id') id: string,
  @Body() dto: UpdateUserStatusDto
) {
  return this.usersService.updateStatus(id, dto);
}

Each endpoint has:
✅ ONE specific purpose
✅ Minimal permissions needed
✅ Clear security boundaries
✅ Its own validation logic

DTOs That Match Operations

Remember from Week 1 how we used DTOs to define data structure? Now we're using them for security too.

// UpdateUserDto.ts - Profile info only
import { IsOptional, IsString } from 'class-validator';

export class UpdateUserDto {
  @IsOptional()
  @IsString()
  businessName?: string;

  @IsOptional()
  @IsString()
  whatsappNumber?: string;

  // Notice: NO password, email, role, or isActive
}

// ChangePasswordDto.ts - Requires verification
import { IsString, MinLength } from 'class-validator';

export class ChangePasswordDto {
  @IsString()
  @MinLength(8)
  oldPassword: string; // Must verify they know current password

  @IsString()
  @MinLength(8)
  newPassword: string;
}

// ChangeEmailDto.ts - Requires verification
import { IsEmail, IsString } from 'class-validator';

export class ChangeEmailDto {
  @IsEmail()
  newEmail: string;

  @IsString()
  verificationCode: string; // Sent to old email
}

// UpdateUserStatusDto.ts - Admin operations only
import { IsOptional, IsBoolean, IsEnum } from 'class-validator';

export class UpdateUserStatusDto {
  @IsOptional()
  @IsBoolean()
  isActive?: boolean;

  @IsOptional()
  @IsEnum(UserRole)
  role?: UserRole;

  // Notice: NO personal user data
}

Each DTO has only the fields relevant to its operation. This enforces the principle of least privilege at the validation layer.

Service Layer Implementation

In your service, keep the logic separate too:

// users.service.ts
@Injectable()
export class UsersService {

  // Profile updates - anyone can update their own profile
  async updateProfile(id: string, dto: UpdateUserDto) {
    const user = await this.findOne(id);

    if (!user) {
      throw new NotFoundException('User not found');
    }

    // Only update allowed fields
    return this.userRepository.update(id, {
      businessName: dto.businessName,
      whatsappNumber: dto.whatsappNumber,
    });
  }

  // Status updates - admin only
  async updateStatus(id: string, dto: UpdateUserStatusDto) {
    const user = await this.findOne(id);

    if (!user) {
      throw new NotFoundException('User not found');
    }

    return this.userRepository.update(id, {
      isActive: dto.isActive,
      role: dto.role,
    });
  }
}

// auth.service.ts
@Injectable()
export class AuthService {

  async changePassword(dto: ChangePasswordDto) {
    // Verify old password
    const isValid = await this.verifyPassword(dto.oldPassword);

    if (!isValid) {
      throw new UnauthorizedException('Current password is incorrect');
    }

    // Hash and update new password
    const hashedPassword = await bcrypt.hash(dto.newPassword, 10);
    return this.updatePassword(hashedPassword);
  }

  async changeEmail(dto: ChangeEmailDto) {
    // Verify the code sent to old email
    const isValid = await this.verifyEmailCode(dto.verificationCode);

    if (!isValid) {
      throw new UnauthorizedException('Invalid verification code');
    }

    // Update email
    return this.updateEmail(dto.newEmail);
  }
}

Notice how:

Profile updates are in UsersService
Auth operations are in AuthService
Each method has ONE responsibility
Verification logic is built into each operation

Guards for Access Control

Just like we used exception filters in Week 2, guards enforce security at the endpoint level:

// Basic auth guard - must be logged in
@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    return !!request.user; // Has user session
  }
}

// Admin guard - must be admin
@Injectable()
export class AdminGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    return request.user?.role === 'admin';
  }
}

Then apply them:

// Anyone logged in can update their profile
@Patch(':id')
@UseGuards(AuthGuard)
updateProfile() {}

// Only admins can change user status
@Patch(':id/status')
@UseGuards(AuthGuard, AdminGuard)
updateStatus() {}

Real-World Benefits

After restructuring my endpoints:

Security improved drastically
- Users can't accidentally change their role
- Password changes require verification
- Admin operations are clearly separated
Code is way clearer
- I know exactly what each endpoint does
- New developers can understand it instantly
- No "god method" doing 10 different things
Testing became simpler
- Test profile updates separately from password changes
- Mock only what each endpoint needs
- No complex conditional testing
Maintenance is easier
- Changing password logic doesn't touch profile updates
- Adding email verification doesn't affect admin operations
- Each feature can evolve independently

Common Questions

Q: Isn't this more code?
A: Yes, but it's better code. Would you rather have one confusing file or three clear ones?

Q: What about code duplication?
A: You're not duplicating logic—you're separating concerns. Big difference.

Q: When should I use one endpoint?
A: When operations are truly the same thing. Example: updating different fields in a blog post title/content. But user profile vs. password? Different operations.

Connecting the Dots

This week's lessons build on everything from previous weeks:

Week 1: DTOs define structure → Now they also define security boundaries
Week 2: Exception filters centralize errors → Separate endpoints reduce error complexity
Week 3: SRP and Least Privilege → Make your API secure by design

Each principle reinforces the others. That's what makes NestJS powerful—it encourages good architecture from the start.

Key Takeaways

✅ One endpoint = one responsibility - Don't mix operations
✅ Least privilege = better security - Minimum permissions needed
✅ Separate DTOs for separate concerns - Validation IS security
✅ Guards enforce boundaries - Use them liberally
✅ Service methods should be focused - Each does ONE thing well

What's Next?

Next week, I'll be diving into:

Database integration with Mongoose
Relationships between entities
Migration strategies

What I'm Building

I'm documenting my journey from frontend to full-stack while building Tech Linkup, a tech events platform for Nigerian cities. Every mistake, every lesson, every breakthrough—shared publicly.

Let's connect:

Portfolio: tochukwu-nwosa.vercel.app
GitHub: @tochukwunwosa
Twitter: @tochukwudev
LinkedIn: nwosa-tochukwu

Have you made similar mistakes in API design? Or do you have a different approach? Let's discuss in the comments! 👇

P.S. - If you're also learning NestJS, check out my previous posts in this series. I'm documenting everything—the good, the bad, and the "why didn't anyone tell me this earlier?" moments.

NestJS Week 2: Exception Filters, Query Params, and Why You Should Stop Using Try-Catch Everywhere

Tochukwu Nwosa — Tue, 11 Nov 2025 15:35:29 +0000

Welcome back! If you missed Part 1 of my NestJS journey, I covered the basics: modules, controllers, services, DTOs, and validation.

Now we're getting into the good stuff—the patterns that separate messy code from clean, scalable backends.

What I learned this week:

Global exception filters
Environment configuration with ConfigService
The difference between @ Param, @ Query, and @ Body (Have to add space to the names because I noticed some users have them as their username)
Building flexible filtering logic for APIs

Let's dive in.

Day 7: Global Exception Filters - Stop Repeating Yourself

The Problem with Try-Catch Everywhere

When I first started, my controllers looked like this:

@Get(':id')
async findOne(@Param('id') id: string) {
  try {
    return await this.productsService.findOne(id);
  } catch (error) {
    if (error instanceof NotFoundException) {
      return { statusCode: 404, message: 'Product not found' };
    }
    return { statusCode: 500, message: 'Something went wrong' };
  }
}

This is scattered, repetitive, and hard to maintain. Every endpoint needs the same error handling logic copy-pasted.

The Solution: Global Exception Filters

NestJS has a better way. Exception filters catch all thrown errors in one place and format responses consistently.

Here's how I set it up:

Step 1: Create the Exception Filter

// global-filters/http-exception-filter.ts
import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  Logger,
} from '@nestjs/common';
import { Response } from 'express';
import { ConfigService } from '@nestjs/config';

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(HttpExceptionFilter.name);

  constructor(private configService: ConfigService) {}

  private buildErrorResponse(
    status: number,
    errorResponse: any,
    includeStack: boolean,
    stack?: string,
  ) {
    const base = {
      success: false,
      statusCode: status,
      error: errorResponse,
      timestamp: new Date().toISOString(),
    };
    return includeStack ? { ...base, stackTrace: stack } : base;
  }

  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const status = exception.getStatus();
    const errorResponse = exception.getResponse();

    const isProduction =
      this.configService.get<string>('NODE_ENV') === 'production';

    this.logger.error(
      `Status ${status} Error Response: ${JSON.stringify(errorResponse)}`,
    );

    response.status(status).json(
      isProduction
        ? this.buildErrorResponse(status, errorResponse, false)
        : this.buildErrorResponse(status, errorResponse, true, exception.stack),
    );
  }
}

What's happening here?

@Catch(HttpException) - This filter only catches HTTP exceptions
Logger - Logs errors to console (can extend to log files/Sentry later)
ConfigService - Reads environment variables
Environment-based responses:
- Development: Shows full stack traces for debugging
- Production: Hides sensitive details

Step 2: Set Up Environment Variables

Install the config package:

npm i --save @nestjs/config

Create a .env file:

NODE_ENV=development
APP_PORT=3000

Update app.module.ts:

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }), // Makes .env available everywhere
    // ... other modules
  ],
})
export class AppModule {}

Step 3: Apply the Filter Globally

In main.ts:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe } from '@nestjs/common';
import { HttpExceptionFilter } from './global-filters/http-exception-filter';
import { ConfigService } from '@nestjs/config';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const configService = app.get<ConfigService>(ConfigService);

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
    }),
  );

  app.useGlobalFilters(new HttpExceptionFilter(configService));

  const port = configService.get<number>('APP_PORT') || 3000;
  await app.listen(port);
}
bootstrap();

Now Your Controllers Are Clean AF

@Get(':id')
findOne(@Param('id') id: string) {
  return this.productsService.findOne(+id);
}

That's it. No try-catch. If the service throws a NotFoundException, the filter catches it and returns:

Development response:

{
  "success": false,
  "statusCode": 404,
  "error": "Product not found",
  "timestamp": "2025-11-11T10:30:00.000Z",
  "stackTrace": "Error: Product not found\n    at ProductsService.findOne..."
}

Production response:

{
  "success": false,
  "statusCode": 404,
  "error": "Product not found",
  "timestamp": "2025-11-11T10:30:00.000Z"
}

Why This Approach Wins

Centralized error handling - One place to manage all errors
Cleaner code - Controllers focus on business logic
Consistent API responses - Frontend devs will love you
Better debugging - Errors are logged and formatted properly
Scalability - Add error tracking (Sentry, Datadog) in one place

Note: This doesn't mean you'll never use try-catch in NestJS. But for standard HTTP exceptions, filters handle it better.

Days 8-12: WordPress Side Quest

Real talk—I worked on my 9-5 WordPress project these days. Learning NestJS doesn't pay the bills yet. 😅

But I kept the concepts fresh by thinking about how I'd structure the WordPress project if it were NestJS (spoiler: it would be way cleaner).

Day 13: Mastering @ Param, @ Query, and @ Body

Time to understand how to extract data from incoming requests properly.

The Three Decorators

Decorator	Used For	Example URL
`@Body()`	POST/PUT request body	N/A
`@Param()`	Route parameters	`/products/:id`
`@Query()`	Query strings	`/products?name=shirt&type=clothing`

@ Body - Extracting Request Body

Used for creating or updating resources:

@Post()
create(@Body() createProductDto: CreateProductDto) {
  return this.productsService.create(createProductDto);
}

Request body:

{
  "productName": "Laptop",
  "productType": "electronics",
  "price": 50000
}

@ Param - Extracting Route Parameters

Used for identifying specific resources:

@Get(':id')
findOne(@Param('id') id: string) {
  return this.productsService.findOne(+id);
}

URL: http://localhost:3000/products/5

You can extract multiple params:

@Get(':category/:id')
findByCategory(
  @Param('category') category: string,
  @Param('id') id: string,
) {
  return this.productsService.findByCategoryAndId(category, +id);
}

URL: http://localhost:3000/products/electronics/5

@Query - Building Flexible Filters

This is where things get interesting. Query parameters are optional and perfect for filtering.

Step 1: Create a Query DTO

// dto/find-product-query.dto.ts
import { IsOptional, IsString } from 'class-validator';

export class FindProductQueryDto {
  @IsOptional()
  @IsString()
  productName?: string;

  @IsOptional()
  @IsString()
  productType?: string;
}

The @IsOptional() decorator means these fields don't have to be present.

Step 2: Use It in the Controller

@Get()
findAll(@Query() query: FindProductQueryDto) {
  return this.productsService.findAll(query);
}

Step 3: Implement Filtering Logic in the Service

findAll(query?: FindProductQueryDto) {
  // If no query params, return all products
  if (!query || Object.keys(query).length === 0) {
    return {
      message: 'All products fetched successfully',
      data: this.products,
    };
  }

  // Filter based on query params
  const filtered = this.products.filter((prod) => {
    const matchesName = query.productName
      ? prod.productName.toLowerCase().includes(query.productName.toLowerCase())
      : true;

    const matchesType = query.productType
      ? prod.productType.toLowerCase() === query.productType.toLowerCase()
      : true;

    return matchesName && matchesType; // Both conditions must match
  });

  return {
    message: 'Filtered products',
    data: filtered,
  };
}

How It Works

Request: GET /products?productName=laptop&productType=electronics

Logic:

Check if productName matches (case-insensitive, partial match)
Check if productType matches (case-insensitive, exact match)
Return products that match both conditions

Using && vs ||:

&& (AND) - Narrows the search (must match all filters)
|| (OR) - Broadens the search (matches any filter)

I used && because I wanted to narrow down results progressively.

When to Use What?

Use @Query for:

Optional filtering (/products?name=laptop&sort=asc)
Pagination (/products?page=1&limit=10)
Search functionality

Use @ Param for:

Required identifiers (/products/:id)
Hierarchical resources (/users/:userId/orders/:orderId)

Use @ Body for:

Creating resources (POST)
Updating resources (PUT/PATCH)

Key Takeaways from Week 2

Global exception filters > try-catch everywhere
ConfigService makes environment management clean
@Query is perfect for flexible, optional filtering
@ Param is for required identifiers in the URL
DTOs with @IsOptional() make query validation easy

What's Next?

Now that I've got the fundamentals down, it's time to level up:

Database integration (Mongoose + MongoDB)
Authentication with JWT
Guards and middleware
Database relations (User → Products → Orders)

If you're following along, let me know what you'd like me to cover next!

Connect With Me

I'm documenting my transition from frontend to full-stack. Let's connect and learn together!

🌐 Portfolio: tochukwu-nwosa.vercel.app

🚀 Latest Project: Tech Linkup - Discover tech events in Nigerian cities

💼 LinkedIn: nwosa-tochukwu

🐙 GitHub: @tochukwunwosa

🐦 Twitter/X: @tochukwudev

📝 Dev.to: @tochukwu_dev

Drop a comment if you're also learning NestJS or have tips for backend beginners! 👇

This is part of my #LearningInPublic series where I document my journey from frontend to full-stack development. Follow along for more!

My First Week Learning NestJS (Coming from Frontend)

Tochukwu Nwosa — Mon, 03 Nov 2025 07:25:20 +0000

Why NestJS?

As a frontend developer, I decided to dive into backend development, and NestJS caught my attention. It's a Node.js framework inspired by Angular, designed to build scalable and maintainable server-side applications. Coming from React, the structured approach felt familiar yet different.

Let me share what I learned in my first week.

Day 1: Getting Started

What is NestJS?

NestJS is a TypeScript-first Node.js framework that uses:

OOP (Object-Oriented Programming)
FP (Functional Programming)
FRP (Functional Reactive Programming)

Under the hood, it uses Express by default, but you can configure Fastify too.

Setting Up

# Install NestJS CLI globally
npm i -g @nestjs/cli

# Create new project
nest new project-name

# Start development server (with hot reload)
npm run start:dev

The development server runs on http://localhost:3000 by default.

Project Structure

When you create a new project, you get this structure:

src/
├── app.controller.ts       # Basic controller with routes
├── app.controller.spec.ts  # Unit tests
├── app.module.ts           # Root module
├── app.service.ts          # Basic service
└── main.ts                 # Entry point (bootstraps the app)

Key insight: The main.ts file runs the bootstrap() method which calls NestFactory to create your app instance.

Creating Your First Module

# Generate a module
nest g module shops

# Generate a controller for that module
nest g controller shops

The CLI automatically updates app.module.ts and creates the necessary files.

Basic Controller Example

import { Controller, Get } from '@nestjs/common';

@Controller('shops')
export class ShopsController {
  @Get()
  findAll(): string {
    return 'This action returns all shops';
  }
}

Test it with Postman at http://localhost:3000/shops

Day 2: Controllers & Services

Understanding Controllers

Controllers handle incoming requests and outgoing responses. They're the messengers between your client and your business logic.

Routes are created by combining:

The controller prefix: @Controller('shops')
The HTTP method decorator: @Get('branch')
Result: localhost:3000/shops/branch

Response Methods in NestJS

NestJS offers two ways to send responses:

Standard (recommended): Automatic status codes (200 for most, 201 for POST)
Library-specific: Using Express-like syntax with @Res()

Services: Where the Logic Lives

Services are providers that handle business logic and data operations. They can be injected into multiple controllers.

# Generate a service
nest g service shops

Or create manually:

import { Injectable } from '@nestjs/common';

@Injectable()
export class ShopsService {
  getAllShops() {
    // Business logic here
  }
}

Injecting Services into Controllers

@Controller('shops')
export class ShopsController {
  constructor(private shopsService: ShopsService) {}

  @Get()
  getAllShops() {
    return this.shopsService.getAllShops();
  }

  @Post()
  createShop(@Body() body) {
    return this.shopsService.createShop(body.shopName);
  }
}

The private keyword declares and initializes the service in one line—super clean!

Don't Forget the Module Configuration

@Module({
  controllers: [ShopsController],
  providers: [ShopsService], // ⚠️ IMPORTANT: Add this or you'll get errors
})
export class ShopsModule {}

Without adding the service to providers, you'll get:

UnknownDependenciesException: Nest can't resolve dependencies...

The Flow

HTTP Request → Controller → Service → Data Access Layer

Key Takeaways

Separation of concerns: Logic stays in services, HTTP handling in controllers
Dependency Injection: NestJS handles this automatically by checking the providers array
Singletons: Services are singleton by default (one instance shared across the app)
Benefits: Maintainable code, easy testing with mocks, reduced coupling

The @Injectable() decorator marks a class as a provider that can be injected.

Day 3: DTOs & Validation

What are DTOs?

Data Transfer Objects (DTOs) define the structure of data sent over the network.

Why use classes over interfaces?

Classes are part of JavaScript ES6 and remain intact after compilation. NestJS can reference them at runtime, unlike TypeScript interfaces.

Creating a DTO

Create a file: create-shop.dto.ts

export class CreateShopDto {
  name: string;
  location: string;
}

Pro tip: Create a dto folder inside your module to keep things organized.

Update DTO with PartialType

import { PartialType } from '@nestjs/mapped-types';
import { CreateShopDto } from './create-shop.dto';

export class UpdateShopDto extends PartialType(CreateShopDto) {}

This makes all fields optional. You'll need to install:

npm install @nestjs/mapped-types -D

Using DTOs in Controllers

@Post()
createShop(@Body() createShopDto: CreateShopDto) {
  return this.shopsService.createShop(createShopDto);
}

Adding Validation

DTOs define structure, but don't validate yet. Enter class-validator!

npm install class-validator class-transformer

Update your DTO:

import { IsString, IsNotEmpty } from 'class-validator';

export class CreateShopDto {
  @IsString()
  @IsNotEmpty()
  name: string;

  @IsString()
  @IsNotEmpty()
  location: string;
}

Enable Validation Globally

In main.ts:

import { ValidationPipe } from '@nestjs/common';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe()); // Validation enabled globally here
  await app.listen(3000);
}
bootstrap();

Now validation runs automatically on all requests!

Handling Errors with HTTP Exceptions

When looking up a shop by ID that doesn't exist, return a proper error:

import { NotFoundException } from '@nestjs/common';

getShopById(id: string) {
  const shop = this.shops.find(shop => shop.id === id);
  if (!shop) {
    throw new NotFoundException(`Shop with ID ${id} not found`);
  }
  return shop;
}

Key Concepts

DTO = Structure definition
Validation = Data integrity before it hits your logic
Pipes = Execute on arguments before route handlers

Days 4-6: Building a CRUD API

I spent these days practicing full CRUD operations, and honestly—NestJS makes it more straightforward than Express.

Having services, controllers, and modules all in one folder keeps everything organized and easier to maintain. The structure just makes sense.

My Thoughts After Week 1

What I Love:

Clear structure - Everything has its place
TypeScript integration - Type safety is a game-changer
CLI tools - Generating modules/controllers/services is instant
Dependency injection - No more messy imports everywhere
Familiar patterns - Coming from frontend, decorators feel natural

What Took Time:

Understanding the module system
Getting used to decorators everywhere
Setting up validation (but worth it!)

Next Steps:

Connect to a real database (MongoDB/PostgreSQL)
Learn about middleware and guards
Explore authentication with JWT
Database relations and TypeORM

Resources That Helped

If you're a frontend developer curious about backend, I'd say give NestJS a shot. The learning curve is gentler than raw Express, especially if you're already comfortable with TypeScript and modern frameworks.

What's your backend journey been like? Drop your experiences in the comments! 👇

Connect With Me

I'm building in public and would love to connect!

🌐 Portfolio: tochukwu-nwosa.vercel.app
🚀 Latest Project: Tech Linkup - Discover tech events and connect with innovators in Nigerian cities
💼 LinkedIn: nwosa-tochukwu
🐙 GitHub: @tochukwunwosa
🐦 Twitter/X: @tochukwudev

This is part of my #LearningInPublic series where I document my transition from frontend to full-stack development. Follow along for more!