eviterstudio-framework-core

Core utilities for EviterStudio Standard Framework providing essential building blocks for modern TypeScript applications.

📋 Table of Contents

• Features
• Installation
• Quick Start
• Modules
  • Pagination
  • Response
  • Validation
  • Common Types
• API Reference
• Examples
• Development
• Contributing
• License

✨ Features

• 🔍 Pagination System - Comprehensive pagination with sorting, filtering, and search
• 📦 Response Builder - Standardized API response formatting
• ✅ Validation Framework - Powerful validation with decorators and rules
• 🏗️ Type Utilities - Common TypeScript types and interfaces
• 🎯 Type-Safe - Full TypeScript support with strict typing
• 🧪 Well-Tested - Comprehensive test coverage
• 📚 Decorator Support - Class-validator integration

📦 Installation

npm install eviterstudio-framework-core

Peer Dependencies

npm install reflect-metadata

🚀 Quick Start

import {
  PaginationService,
  ResponseBuilder,
  ValidationService,
  CommonValidators
} from 'eviterstudio-framework-core';

// Initialize services
const paginationService = new PaginationService();
const validationService = new ValidationService();

// Create paginated response
const paginatedData = paginationService.createPaginatedResult(
  data,
  totalCount,
  { page: 1, limit: 10 }
);

const response = ResponseBuilder.paginated(
  paginatedData.data,
  paginatedData.meta
);

📚 Modules

Pagination

Comprehensive pagination system with advanced features:

import { PaginationService, PaginationDto } from 'eviterstudio-framework-core';

const service = new PaginationService();

// Create pagination query
const query = service.createPaginationQuery({
  page: 1,
  limit: 10,
  sortBy: 'createdAt',
  sortOrder: 'DESC',
  search: 'john',
  searchFields: ['name', 'email'],
  filters: {
    status: 'active',
    role: ['admin', 'user']
  }
});

// Create pagination metadata
const meta = service.createPaginationMeta(totalItems, options);

// Create paginated result
const result = service.createPaginatedResult(data, totalItems, options);

Features:

• Flexible Pagination - Page-based with customizable limits
• Advanced Sorting - Multi-field sorting with direction control
• Smart Search - Multi-field search with insensitive matching
• Dynamic Filtering - Complex filtering with various data types
• Query Building - ORM-agnostic query construction

Response

Standardized API response formatting system:

import { ResponseBuilder, HttpStatus } from 'eviterstudio-framework-core';

// Success responses
const success = ResponseBuilder.success(data, 'Operation successful');
const created = ResponseBuilder.created(newUser, 'User created');
const paginated = ResponseBuilder.paginated(users, paginationMeta);

// Error responses
const badRequest = ResponseBuilder.badRequest('Invalid input', errors);
const notFound = ResponseBuilder.notFound('User not found');
const unauthorized = ResponseBuilder.unauthorized();

// Custom responses
const custom = ResponseBuilder.success(data, 'Custom message', HttpStatus.OK, metadata);

Features:

• Consistent Structure - Standardized response format
• HTTP Status Codes - Built-in status code management
• Error Handling - Comprehensive error response formatting
• Metadata Support - Flexible metadata inclusion
• Validation Integration - Seamless validation error formatting

Validation

Powerful validation framework with multiple approaches:

Class-based Validation (Decorators)

import { IsEmail, IsString, MinLength } from 'class-validator';
import { IsStrongPassword, Match } from 'eviterstudio-framework-core';

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(2)
  name: string;

  @IsStrongPassword()
  password: string;

  @Match('password')
  confirmPassword: string;
}

// Validate DTO
const result = await validationService.validateDto(userData, CreateUserDto);

Schema-based Validation

import { CommonValidators, StringValidators, NumberValidators } from 'eviterstudio-framework-core';

const userSchema = {
  email: [CommonValidators.required(), CommonValidators.email()],
  name: [StringValidators.minLength(2), StringValidators.maxLength(50)],
  age: [NumberValidators.min(18), NumberValidators.max(120)]
};

const result = await validationService.validateSchema(userData, userSchema);

Available Validators

Common Validators:

• required() - Field is required
• email() - Valid email format
• url() - Valid URL format
• pattern(regex) - Custom regex pattern
• in(values) - Value in allowed list
• notIn(values) - Value not in forbidden list
• custom(fn, message) - Custom validation function

String Validators:

• minLength(min) - Minimum string length
• maxLength(max) - Maximum string length
• lengthBetween(min, max) - Length within range
• alpha() - Only alphabetic characters
• alphanumeric() - Only alphanumeric characters
• phone() - Phone number format
• uuid(version?) - UUID format validation

Number Validators:

• min(min) - Minimum value
• max(max) - Maximum value
• between(min, max) - Value within range
• integer() - Integer validation
• positive() - Positive number
• negative() - Negative number
• divisibleBy(divisor) - Divisible by value

Date Validators:

• after(date) - Date after specified date
• before(date) - Date before specified date
• between(start, end) - Date within range
• past() - Date in the past
• future() - Date in the future
• today() - Date is today
• minAge(age) - Minimum age validation

Custom Decorators:

• @IsStrongPassword() - Strong password validation
• @IsPhoneNumber(locale?) - Phone number validation
• @Match(property) - Field matching validation
• @ValidateIf(condition) - Conditional validation
• @ArrayUnique() - Unique array values

Common Types

Utility types and interfaces for common patterns:

import {
  ID,
  Nullable,
  Optional,
  DeepPartial,
  Constructor,
  BaseEntity,
  SoftDeleteEntity,
  Status,
  SortDirection
} from 'eviterstudio-framework-core';

// Use common types
type UserId = ID; // string | number
type User = Nullable<UserData>; // UserData | null
type PartialUser = DeepPartial<User>; // Deep partial type

// Base entity interface
interface User extends BaseEntity {
  name: string;
  email: string;
  status: Status;
}

// Soft delete entity
interface Post extends SoftDeleteEntity {
  title: string;
  content: string;
}

Available Types:

• ID - Generic ID type (string | number)
• Nullable<T> - T | null
• Optional<T> - T | undefined
• DeepPartial<T> - Deep partial type
• Constructor<T> - Constructor type
• Unpacked<T> - Extract array type
• RequireAtLeastOne<T, K> - Require at least one property

Available Interfaces:

• BaseEntity - Base entity with id, createdAt, updatedAt
• SoftDeleteEntity - Soft delete with deletedAt, isDeleted
• Timestamped - Created and updated timestamps
• KeyValue<T> - Key-value pair interface

Available Enums:

• Status - Common status values
• SortDirection - ASC/DESC sorting

🔧 Development

Setup

# Clone repository
git clone <repository-url>
cd eviterstudio-framework-core

# Install dependencies
npm install

# Build project
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

Project Structure

src/
├── index.ts                 # Main exports
├── pagination/              # Pagination module
│   ├── index.ts
│   ├── pagination.interface.ts
│   ├── pagination.service.ts
│   └── pagination.dto.ts
├── response/                # Response module
│   ├── index.ts
│   ├── response.interface.ts
│   ├── response.builder.ts
│   └── response.enum.ts
├── validation/              # Validation module
│   ├── index.ts
│   ├── validation.interface.ts
│   ├── validation.service.ts
│   ├── validators/          # Built-in validators
│   │   ├── index.ts
│   │   ├── common.validator.ts
│   │   ├── string.validator.ts
│   │   ├── number.validator.ts
│   │   └── date.validator.ts
│   └── decorators/          # Custom decorators
│       ├── index.ts
│       └── validation.decorator.ts
└── types/                   # Common types
    ├── index.ts
    └── common.types.ts

Scripts

• npm run build - Build TypeScript to JavaScript
• npm run dev - Watch mode for development
• npm test - Run Jest tests
• npm run lint - ESLint code checking

📖 API Reference

PaginationService

| Method | Description | Parameters | Returns | |--------|-------------|------------|---------| | createPaginationQuery(options) | Create database query parameters | PaginationOptions | PaginationQuery | | createPaginationMeta(total, options) | Create pagination metadata | number, PaginationOptions | PaginationMeta | | createPaginatedResult(data, total, options) | Create paginated result | T[], number, PaginationOptions | PaginatedResult<T> | | parsePaginationParams(query) | Parse query string parameters | any | PaginationOptions |

ResponseBuilder

| Method | Description | Parameters | Returns | |--------|-------------|------------|---------| | success(data?, message?, status?, meta?) | Create success response | T?, string?, number?, any? | ApiResponse<T> | | error(message, status?, errors?, stack?) | Create error response | string, number?, ValidationError[]?, string? | ErrorResponse | | paginated(data, meta, message?) | Create paginated response | T[], PaginationMeta, string? | ApiResponse<T[]> | | created(data, message?) | Create 201 response | T, string? | ApiResponse<T> | | badRequest(message, errors?) | Create 400 response | string, ValidationError[]? | ErrorResponse | | unauthorized(message?) | Create 401 response | string? | ErrorResponse | | forbidden(message?) | Create 403 response | string? | ErrorResponse | | notFound(message?) | Create 404 response | string? | ErrorResponse |

ValidationService

| Method | Description | Parameters | Returns | |--------|-------------|------------|---------| | validateDto(dto, dtoClass, options?) | Validate using class decorators | any, Constructor, ValidatorOptions? | Promise<ValidationResult> | | validateSchema(data, schema) | Validate using schema | any, ValidationSchema | Promise<ValidationResult> | | validateValue(value, validators) | Validate single value | any, Function[] | string[] | | sanitize(data, allowedFields) | Sanitize input data | any, string[] | Partial<T> |

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

For support, email [email protected] or create an issue in the repository.

Made with ❤️ by EviterStudio