eviterstudio-framework-nestjs

NestJS adapter for EviterStudio Framework providing decorators, interceptors, and base classes for rapid API development.

Features

• 🎯 Smart Decorators: @Paginate, @ApiResponse, @Validate, @Public, @User
• 🔄 Powerful Interceptors: Response formatting, pagination, logging, timeout, transformation
• 🏗️ Base Classes: Extensible controllers, services, repositories, and entities
• 🔒 Security: Built-in authentication guards and validation
• 📊 Pagination: Automatic pagination with search and filtering
• ✅ Validation: Integrated class-validator with framework response formatting

Installation

npm install eviterstudio-framework-nestjs eviterstudio-framework-core

Quick Start

1. Setup Core Module

import { Module } from '@nestjs/common';
import { CoreModule } from 'eviterstudio-framework-nestjs';

@Module({
  imports: [CoreModule],
})
export class AppModule {}

2. Create Prisma Service (using PrismaBaseService)

import { Injectable } from '@nestjs/common';
import { PrismaService } from './prisma.service'; // Your Prisma service
import { PrismaBaseService, PaginationService } from 'eviterstudio-framework-nestjs';
import { User } from './user.entity';

@Injectable()
export class UserService extends PrismaBaseService<User> {
  constructor(
    private prismaService: PrismaService,
    paginationService: PaginationService,
  ) {
    super(
      prismaService, // Prisma client
      'user', // Model name in schema
      paginationService,
      'User' // Entity name for errors
    );
  }

  // All CRUD operations are automatically available
  // Add custom business logic as needed
}

3. Create a Simple Controller

import { Controller } from '@nestjs/common';
import { BaseController } from 'eviterstudio-framework-nestjs';
import { User } from './user.entity';
import { UserService } from './user.service';

@Controller('users')
export class UserController extends BaseController<User> {
  constructor(private userService: UserService) {
    super(userService); // No paginationService needed with PrismaBaseService
  }

  // Inherits all CRUD operations:
  // GET /users (with pagination)
  // GET /users/:id
  // POST /users
  // PUT /users/:id
  // DELETE /users/:id
  // GET /users/search/:query
  // GET /users/_count
}

4. Custom Endpoints

@Controller('users')
export class UserController extends BaseController<User> {
  @Get('profile')
  @ApiResponse()
  async getProfile(@User() user: any) {
    return this.userService.findOne(user.id);
  }

  @Get('public-info')
  @Public()
  @ApiResponse()
  async getPublicInfo() {
    return { message: 'This is public information' };
  }

  @Post('register')
  @Public()
  @Validate()
  @ApiResponse()
  async register(@Body() registerDto: RegisterDto) {
    return this.userService.register(registerDto);
  }
}

Decorators

@Paginate()

Enables automatic pagination for endpoints:

@Get()
@Paginate()
async findAll(@PaginationParams() pagination: PaginationOptions) {
  return this.service.findAll(pagination);
}

Query parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 10, max: 100)
• sortBy - Sort field (default: 'id')
• sortOrder - Sort direction: ASC|DESC (default: ASC)
• search - Search query
• filter_* - Filter by field (e.g., filter_status=active)

@ApiResponse()

Formats responses according to framework standards:

@Get(':id')
@ApiResponse()
async findOne(@Param('id') id: string) {
  return this.service.findOne(id);
}

Response format:

{
  "status": "success",
  "statusCode": 200,
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00.000Z",
  "path": "/api/users/123"
}

@Validate()

Enables request validation with class-validator:

@Post()
@Validate()
async create(@Body() createDto: CreateUserDto) {
  return this.service.create(createDto);
}

@Public()

Marks endpoints as publicly accessible (bypasses auth):

@Get('public')
@Public()
async getPublicData() {
  return { message: 'Public data' };
}

@User()

Extracts current user from request:

@Get('me')
async getCurrentUser(@User() user: any) {
  return user;
}

@Get('profile')
async getProfile(@User('id') userId: string) {
  return this.service.findOne(userId);
}

Base Classes

BaseController

Provides standard CRUD operations:

export class UserController extends BaseController<User, CreateUserDto, UpdateUserDto> {
  constructor(
    userService: UserService,
    paginationService: PaginationService,
  ) {
    super(userService, paginationService);
  }
}

BaseService

Abstract service class:

export class UserService extends BaseService<User> {
  constructor(
    private userRepository: UserRepository,
    paginationService: PaginationService,
  ) {
    super(paginationService, 'User');
  }

  async findAll(pagination: PaginationOptions): Promise<PaginatedResult<User>> {
    return this.userRepository.findAll(pagination);
  }

  // Implement other abstract methods...
}

BaseRepository

Repository interface and base implementation:

export class UserRepository extends BaseRepository<User> {
  constructor(private prisma: PrismaService) {
    super('User');
  }

  async findAll(pagination: PaginationQuery): Promise<{ data: User[]; total: number }> {
    const [data, total] = await Promise.all([
      this.prisma.user.findMany({
        skip: pagination.skip,
        take: pagination.take,
        orderBy: pagination.orderBy,
        where: pagination.where,
      }),
      this.prisma.user.count({ where: pagination.where }),
    ]);

    return { data, total };
  }

  // Implement other methods...
}

Interceptors

The framework provides several built-in interceptors:

• ResponseInterceptor: Formats all responses
• PaginationInterceptor: Handles pagination logic
• LoggingInterceptor: Logs requests and responses
• TimeoutInterceptor: Handles request timeouts
• TransformInterceptor: Transforms responses to DTOs

Example Usage

// app.module.ts
import { Module } from '@nestjs/common';
import { CoreModule } from 'eviterstudio-framework-nestjs';
import { UserModule } from './user/user.module';

@Module({
  imports: [
    CoreModule,
    UserModule,
  ],
})
export class AppModule {}

// user.controller.ts
@Controller('users')
export class UserController extends BaseController<User> {
  @Get('active')
  @Paginate()
  @ApiResponse()
  async getActiveUsers(@PaginationParams() pagination: PaginationOptions) {
    return this.service.findBy({ status: 'active' }, pagination);
  }

  @Post(':id/activate')
  @ApiResponse()
  async activateUser(@Param('id') id: string, @User() currentUser: any) {
    return this.service.activate(id, currentUser.id);
  }
}

Integration with Core

This adapter integrates seamlessly with eviterstudio-framework-core:

• Uses PaginationService for pagination logic
• Uses ResponseBuilder for response formatting
• Uses ValidationService for input validation
• Extends core interfaces and types

License

MIT