bootifyjs 0.0.3 → 0.1.1

package/README.md

@@ -1,567 +1,423 @@
-# 🚀 BootifyJs
-
-A production-ready, Spring Boot-inspired TypeScript framework built on top of Fastify and express, designed for building scalable enterprise applications with modern development practices.
-
-## 🎯 Why This Framework?
-
-### The Problem
-Building enterprise-grade Node.js applications often involves:
-- ⚡ Repetitive boilerplate code for common patterns
-- 🔧 Manual setup of logging, caching, validation, and error handling
-- 📦 Inconsistent project structure across teams
-- 🏗️ Lack of standardized dependency injection
-- 🔄 Manual configuration of database connections and migrations
-- 📊 Missing observability and monitoring out-of-the-box
-
-### The Solution
-Our framework provides:
-- 🎨 **Spring Boot-style decorators** (`@Controller`, `@Service`, `@Repository`)
-- 🏗️ **Dependency Injection** with Inversify
-- 🚀 **High-performance** Fastify web server
-- 📊 **Built-in observability** (logging, metrics, tracing)
-- 💾 **Integrated caching** with Redis
-- 🗄️ **Database abstraction** with Sequelize ORM
-- 🔧 **Zero-config setup** for common enterprise patterns
-- 📦 **Monorepo structure** for scalable team development
-
-## 🏗️ Architecture Overview
+# BootifyJS
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Application Layer                        │
-│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
-│  │   CMS APIs      │  │  Consumer APIs  │  │  Admin APIs  │ │
-│  │   @Controller   │  │   @Controller   │  │  @Controller │ │
-│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
-└─────────────────────────────────────────────────────────────┘
-┌─────────────────────────────────────────────────────────────┐
-│                     Service Layer                          │
-│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
-│  │   UserService   │  │  OrderService   │  │ EmailService │ │
-│  │    @Service     │  │    @Service     │  │   @Service   │ │
-│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
-└─────────────────────────────────────────────────────────────┘
-┌─────────────────────────────────────────────────────────────┐
-│                   Repository Layer                         │
-│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
-│  │ UserRepository  │  │ OrderRepository │  │EmailTemplate │ │
-│  │  @Repository    │  │  @Repository    │  │ @Repository  │ │
-│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
-└─────────────────────────────────────────────────────────────┘
-┌─────────────────────────────────────────────────────────────┐
-│                      Core Framework                        │
-│     Fastify + Decorators + DI + Caching + Logging         │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## 📦 Package Structure
-
-### `core` - Framework Foundation
-- 🎯 **Application bootstrapping** with configurable features
-- 🏗️ **Dependency injection** container with decorators
-- 🌐 **HTTP decorators** (`@Get`, `@Post`, `@Put`, `@Delete`)
-- ⚡ **Performance decorators** (`@Timed`, `@Cache`)
-- 📊 **Structured logging** (Application, Audit, Event logs)
-- 🔄 **Transaction management** with `@Transactional`
-
-### `commons` - Shared Components
-- 🗄️ **Database clients** (Sequelize, Redis)
-- 📋 **Base repository** with caching and pagination
-- 🔧 **Database migrations** and seeders
-- 🏷️ **Shared models** and interfaces
-
-### `@monorepo/cms-apis` - Example Application
-- 🎮 **Controllers** using framework decorators
-- 💼 **Business logic** with service layer
-- 📊 **Complete CRUD** operations with caching
-
-## 🚀 Quick Start
-
-### Prerequisites
-- Node.js 18+ 
-- PostgreSQL 12+
-- Redis 6+ (optional, for caching)
-
-### Installation
+A Spring Boot inspired Node.js framework with TypeScript, Dependency Injection, and Validation.
 
-```bash
-# Clone the repository
-git clone <repository-url>
-cd typescript-fastify-framework
-
-# Install dependencies for all packages
-npm install
+## Features
 
-# Build all packages
-npm run build
-```
+- **Dependency Injection**: Automatic constructor injection with `@Injectable`, `@Service`, and `@Repository` decorators
+- **REST API**: Easy controller definition with `@Controller`, `@Get`, `@Post`, etc.
+- **Validation**: Request validation with Zod schemas
+- **Configuration**: Environment-based configuration with automatic mapping
+- **OpenAPI**: Automatic OpenAPI documentation generation
+- **Logging**: Comprehensive logging system with context tracking
+- **Event System**: Type-safe event system with middleware support
 
-### Environment Setup
+## Installation
 
 ```bash
-# Copy environment template
-cp packages/cms-apis/.env.example packages/cms-apis/.env
-
-# Edit with your configuration
-nano packages/cms-apis/.env
+npm install bootifyjs
 ```
 
-### Database Setup
+## Quick Start
 
-```bash
-# Navigate to commons package
-cd packages/commons
-
-# Create database
-npm run db:create
+```typescript
+import { createBootifyApp, Controller, Get, Service } from 'bootifyjs';
 
-# Run migrations
-npm run db:migrate
+@Service()
+class GreetingService {
+  getGreeting(name: string) {
+    return `Hello, ${name}!`;
+  }
+}
 
-# Seed with sample data (optional)
-npm run db:seed
-```
+@Controller('/api')
+class GreetingController {
+  constructor(private greetingService: GreetingService) {}
+  
+  @Get('/hello')
+  sayHello() {
+    return { message: this.greetingService.getGreeting('World') };
+  }
+}
 
-### Start Development Server
+async function main() {
+  const { start } = await createBootifyApp({
+    port: 3000,
+    controllers: [GreetingController],
+    enableSwagger: true
+  });
+  
+  await start();
+  console.log('Server running at http://localhost:3000');
+}
 
-```bash
-# From root directory
-npm run dev
+main().catch(console.error);
 ```
 
-🎉 **Your API is now running at `http://localhost:3000`**
+## Core Concepts
 
-## 📚 Core Concepts
+### Controllers
 
-### 1. Controllers - HTTP Entry Points
+Controllers handle HTTP requests and define your API endpoints.
 
 ```typescript
-import { Controller, Get, Post, Put, Delete } from '@monorepo/core';
-import { inject } from 'inversify';
+import { Controller, Get, Post, Put, Delete, Param, Body, Query } from 'bootifyjs';
 
-@Controller('/api/users')
+@Controller('/users')
 export class UserController {
-  constructor(
-    @inject(UserService) private userService: UserService
-  ) {}
-
+  constructor(private userService: UserService) {}
+  
   @Get('/')
-  async getAllUsers() {
-    return this.userService.findAllUsers();
+  getAllUsers(@Query('limit') limit?: string) {
+    return this.userService.getAllUsers(limit ? parseInt(limit) : undefined);
   }
-
-  @Post('/', {
-    schema: {
-      body: {
-        type: 'object',
-        required: ['email', 'firstName', 'lastName'],
-        properties: {
-          email: { type: 'string', format: 'email' },
-          firstName: { type: 'string', minLength: 1 },
-          lastName: { type: 'string', minLength: 1 }
-        }
-      }
-    }
-  })
-  async createUser(request: FastifyRequest<CreateUserRequest>) {
-    return this.userService.createUser(request.body);
+  
+  @Get('/:id')
+  getUserById(@Param('id') id: string) {
+    return this.userService.getUserById(id);
+  }
+  
+  @Post('/')
+  createUser(@Body() userData: CreateUserDto) {
+    return this.userService.createUser(userData);
+  }
+  
+  @Put('/:id')
+  updateUser(@Param('id') id: string, @Body() userData: UpdateUserDto) {
+    return this.userService.updateUser(id, userData);
+  }
+  
+  @Delete('/:id')
+  deleteUser(@Param('id') id: string) {
+    return this.userService.deleteUser(id);
   }
 }
 ```
 
-### 2. Services - Business Logic Layer
+### Services
+
+Services contain your business logic and can be injected into controllers or other services.
 
 ```typescript
-import { Service, Timed, Logger } from '@monorepo/core';
-import { inject } from 'inversify';
+import { Service } from 'bootifyjs';
 
-@Service('singleton')
+@Service()
 export class UserService {
-  constructor(
-    @inject(UserRepository) private userRepository: UserRepository
-  ) {}
-
-  @Timed() // Automatically logs execution time
-  async createUser(userData: CreateUserData): Promise<User> {
-    Logger.info(`Creating user: ${userData.email}`);
-    
-    // Business logic here
-    const user = await this.userRepository.create(userData);
-    
-    // Audit logging
-    AuditLogger.info({
-      userId: 'system',
-      action: 'CREATE_USER',
-      resources: ['users'],
-      data: { userId: user.id, email: user.email }
-    });
-    
-    return user;
+  constructor(private userRepository: UserRepository) {}
+  
+  getAllUsers(limit?: number) {
+    return this.userRepository.findAll(limit);
+  }
+  
+  getUserById(id: string) {
+    return this.userRepository.findById(id);
   }
+  
+  // More methods...
 }
 ```
 
-### 3. Repositories - Data Access Layer
+### Repositories
 
-```typescript
-import { Repository, AppRepository } from '@monorepo/core';
-
-@Repository('singleton')
-export class UserRepository extends AppRepository<User> {
-  constructor() {
-    super(User, {
-      cacheTTL: 3600, // 1 hour cache
-      defaultFields: ['id', 'email', 'firstName', 'lastName', 'isActive']
-    });
-  }
+Repositories handle data access and can be injected into services.
 
-  // Custom methods with automatic caching
-  async findByEmail(email: string): Promise<User | null> {
-    return this.findOne({ where: { email } });
+```typescript
+import { Repository } from 'bootifyjs';
+
+@Repository()
+export class UserRepository {
+  private users = []; // In a real app, this would be a database connection
+  
+  findAll(limit?: number) {
+    if (limit) {
+      return this.users.slice(0, limit);
+    }
+    return this.users;
   }
-
-  async findActiveUsers(): Promise<User[]> {
-    return this.findAll({ where: { isActive: true } });
+  
+  findById(id: string) {
+    return this.users.find(user => user.id === id);
   }
+  
+  // More methods...
 }
 ```
 
-### 4. Application Bootstrap
+### Validation
+
+Use Zod schemas to validate request data.
 
 ```typescript
-import { Application, Logger } from '@monorepo/core';
-
-const app = new Application({
-  port: 3000,
-  enableCors: true,
-  enableSwagger: true,
-  enableMetrics: true,
-  corsOptions: {
-    origin: ['http://localhost:3000', 'https://yourdomain.com'],
-    credentials: true
-  }
-});
+import { z } from 'zod';
+import { Controller, Post, Body, ValidateBody } from 'bootifyjs';
 
-// Register controllers
-app.registerControllers([
-  UserController,
-  OrderController,
-  HealthController
-]);
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+  age: z.number().min(18).optional()
+});
 
-await app.start();
+@Controller('/users')
+export class UserController {
+  @Post('/')
+  @ValidateBody(createUserSchema)
+  createUser(@Body() userData: z.infer<typeof createUserSchema>) {
+    // userData is now validated and typed
+    return this.userService.createUser(userData);
+  }
+}
 ```
 
-## 🔧 Configuration Options
+### Configuration
 
-### Application Configuration
+Define your configuration structure and automatically map environment variables.
 
 ```typescript
-interface FastifyServerConfig {
-  port?: number;                    // Server port (default: 3000)
-  host?: string;                    // Server host (default: '0.0.0.0')
-  enableCors?: boolean;             // Enable CORS (default: true)
-  enableSwagger?: boolean;          // Enable API docs (default: false)
-  enableLogging?: boolean;          // Enable request logging (default: true)
-  enableErrorHandling?: boolean;    // Global error handler (default: true)
-  enableMetrics?: boolean;          // Prometheus metrics (default: false)
-  enableCookie?: boolean;           // Cookie support (default: false)
-  enableAuth?: boolean;             // Authentication middleware (default: false)
-  corsOptions?: CorsOptions;        // CORS configuration
-  swaggerOptions?: SwaggerOptions;  // Swagger configuration
+import { Config, getConfigInstance } from 'bootifyjs';
+
+@Config('APP')
+export class AppConfig {
+  SERVICE_NAME: string = 'my-service';
+  
+  server: {
+    port: number;
+    host: string;
+  } = {
+    port: 3000,
+    host: 'localhost'
+  };
+  
+  database: {
+    url: string;
+    poolSize: number;
+  } = {
+    url: 'postgres://localhost:5432/mydb',
+    poolSize: 10
+  };
 }
-```
-
-### Environment Variables
 
-```bash
-# Database Configuration
-DB_NAME=your_database
-DB_USER=postgres
-DB_PASS=password
-DB_HOST=localhost
-DB_PORT=5432
-DB_DIALECT=postgres
-
-# Redis Configuration (optional)
-REDIS_HOST=localhost
-REDIS_PORT=6379
-REDIS_PASSWORD=
-
-# Application Configuration
-APP_PORT=3000
-NODE_ENV=development
-LOG_LEVEL=info
+// Environment variables like APP_SERVER_PORT=8080 will be automatically mapped
+const config = getConfigInstance(AppConfig);
+console.log(config.server.port); // 8080
 ```
 
-## 📊 Built-in Features
-
-### Automatic API Documentation
-Visit `http://localhost:3000/docs` when `enableSwagger: true`
+### Event System
 
-### Health Checks
-- `GET /health` - Application health
-- `GET /health/ready` - Readiness probe
+Create a type-safe event system for decoupled communication.
 
-### Metrics & Monitoring
-- `GET /metrics` - Prometheus metrics (when enabled)
-- Automatic request timing and counting
-- Error rate monitoring
-
-### Structured Logging
 ```typescript
-// Application logs
-Logger.info('User created successfully');
-
-// Audit logs
-AuditLogger.info({
-  userId: 'user123',
-  action: 'CREATE_ORDER',
-  resources: ['orders'],
-  data: { orderId: 'order456' }
-});
-
-// Event logs
-EventLogger.info({
-  eventName: 'USER_SIGNUP',
-  status: 'SUCCESS',
-  metadata: { source: 'web', campaign: 'summer2024' }
-});
-```
-
-## 🎯 Available APIs (CMS Example)
-
-### User Management
-```bash
-# Get all users
-GET /api/users
-
-# Get user by ID
-GET /api/users/:id
-
-# Get user by email
-GET /api/users/email/:email
-
-# Create user
-POST /api/users
-{
-  "email": "john@example.com",
-  "firstName": "John",
-  "lastName": "Doe"
+import { Event, EventEmitter, EventListener, EventHandler } from 'bootifyjs';
+
+// Define an event
+@Event('user.created')
+class UserCreatedEvent {
+  id: string;
+  email: string;
+  timestamp: Date = new Date();
 }
 
-# Update user
-PUT /api/users/:id
-{
-  "firstName": "Jane"
+// Emit events from services
+@Service()
+@EventEmitter()
+class UserService {
+  private eventBus; // Injected by @EventEmitter
+  
+  async createUser(userData) {
+    const user = await this.userRepository.create(userData);
+    
+    // Emit event
+    await this.eventBus.emit('user.created', {
+      id: user.id,
+      email: user.email
+    });
+    
+    return user;
+  }
 }
 
-# Delete user (soft delete)
-DELETE /api/users/:id
-
-# Get user statistics
-GET /api/users/stats
-
-# Paginated users
-GET /api/users/paginate?page=1&limit=10
-```
-
-### System Health
-```bash
-# Health check
-GET /health
-
-# Readiness check
-GET /health/ready
-
-# Metrics (if enabled)
-GET /metrics
+// Handle events
+@EventListener()
+class UserEventHandlers {
+  @EventHandler('user.created')
+  async onUserCreated(event: UserCreatedEvent) {
+    console.log(`User created: ${event.email}`);
+    // Send welcome email, update analytics, etc.
+  }
+}
 ```
 
-## 🔄 Development Workflow
+### Logging
 
-### Adding a New Feature
+Comprehensive logging system with context tracking.
 
-1. **Create Model** (if needed)
 ```typescript
-// packages/commons/src/models/Product.ts
-export class Product extends Model {
-  public id!: number;
-  public name!: string;
-  public price!: number;
-}
-```
+import { Logger, Log } from 'bootifyjs';
 
-2. **Create Repository**
-```typescript
-// packages/commons/src/repositories/ProductRepository.ts
-@Repository('singleton')
-export class ProductRepository extends AppRepository<Product> {
-  constructor() {
-    super(Product, { cacheTTL: 1800 });
+@Service()
+@Logger('UserService')
+export class UserService {
+  private logger; // Injected by @Logger
+  
+  @Log({ logArgs: true, logDuration: true })
+  async createUser(userData) {
+    this.logger.info('Creating new user', { email: userData.email });
+    
+    // Business logic...
+    
+    this.logger.info('User created successfully');
+    return user;
   }
 }
 ```
 
-3. **Create Service**
-```typescript
-// packages/commons/src/services/ProductService.ts
-@Service('singleton')
-export class ProductService {
-  constructor(
-    @inject(ProductRepository) private productRepo: ProductRepository
-  ) {}
-
-  @Timed()
-  async createProduct(data: CreateProductData): Promise<Product> {
-    return this.productRepo.create(data);
-  }
-}
-```
+## Bootstrapping Your Application
 
-4. **Create Controller**
-```typescript
-// packages/cms-apis/src/controllers/ProductController.ts
-@Controller('/api/products')
-export class ProductController {
-  constructor(
-    @inject(ProductService) private productService: ProductService
-  ) {}
+There are two ways to bootstrap your application:
 
-  @Post('/')
-  async createProduct(request: FastifyRequest) {
-    return this.productService.createProduct(request.body);
-  }
-}
-```
+### 1. Using createBootifyApp (Recommended)
 
-5. **Register Controller**
 ```typescript
-// packages/cms-apis/src/index.ts
-app.registerControllers([
-  UserController,
-  ProductController, // Add new controller
-  HealthController
-]);
+import { createBootifyApp } from 'bootifyjs';
+import { UserController } from './controllers/user.controller';
+
+async function main() {
+  const { app, start, stop } = await createBootifyApp({
+    port: 3000,
+    controllers: [UserController],
+    enableSwagger: true,
+    enableCors: true
+  });
+  
+  await start();
+  console.log('Server running at http://localhost:3000');
+  console.log('API docs available at http://localhost:3000/api-docs');
+}
+
+main().catch(console.error);
 ```
 
-## 🧪 Testing
+### 2. Manual Bootstrap
 
-```bash
-# Run all tests
-npm run test
-
-# Run tests for specific package
-npm run test --workspace=packages/core
+```typescript
+import { 
+  Application, 
+  configureLogging, 
+  configureEventSystem,
+  corsMiddleware,
+  contextMiddleware,
+  createRequestLoggingMiddleware,
+  swaggerMiddleware,
+  OpenAPIGenerator
+} from 'bootifyjs';
+import { UserController } from './controllers/user.controller';
+
+async function bootstrap() {
+  // Initialize logging
+  const { logger, startupLogger } = configureLogging();
+  
+  // Initialize event system
+  const eventBus = configureEventSystem();
+  
+  // Generate OpenAPI documentation
+  const openApiGenerator = new OpenAPIGenerator({
+    title: 'My API',
+    version: '1.0.0',
+    description: 'My API description'
+  });
+  
+  const controllers = [UserController];
+  openApiGenerator.addControllers(controllers);
+  const openApiSpec = openApiGenerator.getSpec();
+  
+  // Create application
+  const app = new Application({
+    controllers,
+    middlewares: [
+      contextMiddleware,
+      corsMiddleware,
+      createRequestLoggingMiddleware(),
+      swaggerMiddleware(openApiSpec)
+    ],
+    port: 3000,
+    hostname: 'localhost'
+  });
+  
+  await app.start();
+  logger.info('Server started');
+}
 
-# Run tests in watch mode
-npm run test:watch
+bootstrap().catch(console.error);
 ```
 
-## 📦 Building & Deployment
+## Middleware
 
-### Development
-```bash
-npm run dev
-```
+Create custom middleware to handle cross-cutting concerns.
 
-### Production Build
-```bash
-npm run build
-npm run start
+```typescript
+import { Middleware } from 'bootifyjs';
+
+export const loggingMiddleware: Middleware = async (req, res, next) => {
+  const start = Date.now();
+  console.log(`${req.method} ${req.url} - Request started`);
+  
+  await next();
+  
+  const duration = Date.now() - start;
+  console.log(`${req.method} ${req.url} - Request completed in ${duration}ms`);
+};
 ```
 
-### Docker Deployment
-```dockerfile
-FROM node:18-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --only=production
-COPY dist/ ./dist/
-EXPOSE 3000
-CMD ["npm", "start"]
-```
+## OpenAPI Documentation
 
-## 🔧 Advanced Usage
+BootifyJS automatically generates OpenAPI documentation for your API.
 
-### Custom Decorators
 ```typescript
-// Create custom validation decorator
-export function ValidateUser(): MethodDecorator {
-  return (target, propertyKey, descriptor) => {
-    // Custom validation logic
-  };
-}
+import { Controller, Get, ApiTags, ApiOperation, ApiResponse } from 'bootifyjs';
 
-// Usage
-@Controller('/api/users')
-export class UserController {
-  @Post('/')
-  @ValidateUser()
-  async createUser(request: FastifyRequest) {
-    // Method implementation
+@Controller('/health')
+@ApiTags('Health')
+export class HealthController {
+  @Get('/')
+  @ApiOperation({
+    summary: 'Health check',
+    description: 'Check if the API is running'
+  })
+  @ApiResponse(200, {
+    description: 'API is healthy',
+    schema: healthResponseSchema
+  })
+  health() {
+    return { status: 'OK', timestamp: new Date().toISOString() };
   }
 }
 ```
 
-### Custom Middleware
-```typescript
-const app = new Application({
-  // ... other config
-});
+## Error Handling
 
-// Add custom middleware
-app.getServer().addHook('preHandler', async (request, reply) => {
-  // Custom logic before request handling
-});
-```
+BootifyJS provides built-in error classes for common HTTP errors.
 
-### Database Transactions
 ```typescript
-@Service('singleton')
-export class OrderService {
-  @Transactional()
-  async createOrderWithItems(orderData: CreateOrderData, transaction?: Transaction) {
-    // All database operations will use the same transaction
-    const order = await this.orderRepo.create(orderData, { transaction });
-    const items = await this.orderItemRepo.bulkCreate(orderData.items, { transaction });
-    
-    // Transaction automatically committed on success
-    // or rolled back on error
-    return { order, items };
+import { NotFoundError, ValidationError } from 'bootifyjs';
+
+@Service()
+export class UserService {
+  getUserById(id: string) {
+    const user = this.userRepository.findById(id);
+    if (!user) {
+      throw new NotFoundError(`User with id ${id} not found`);
+    }
+    return user;
+  }
+  
+  createUser(userData) {
+    if (!userData.email) {
+      throw new ValidationError('Email is required');
+    }
+    // ...
   }
 }
 ```
 
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add 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](LICENSE) file for details.
-
-## 🆘 Support
-
-- 📖 **Documentation**: [Link to full docs]
-- 💬 **Discord**: [Community chat]
-- 🐛 **Issues**: [GitHub Issues]
-- 📧 **Email**: support@yourframework.com
-
-## 🗺️ Roadmap
-
-- [ ] GraphQL support
-- [ ] WebSocket integration
-- [ ] Message queue integration (RabbitMQ, Kafka)
-- [ ] Microservices communication patterns
-- [ ] Advanced caching strategies
-- [ ] Performance optimization tools
-- [ ] CLI for scaffolding
-
----
+## License
 
-**Built with ❤️ for the Node.js community**
+MIT