bootifyjs 0.0.2 → 0.1.0

package/README.md

@@ -1,567 +1,173 @@
-# 🚀 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
-
-```bash
-# Clone the repository
-git clone <repository-url>
-cd typescript-fastify-framework
-
-# Install dependencies for all packages
-npm install
-
-# Build all packages
-npm run build
-```
+A Spring Boot inspired Node.js framework with TypeScript, Dependency Injection, and Validation.
 
-### 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
-```
-
-### Database Setup
-
-```bash
-# Navigate to commons package
-cd packages/commons
-
-# Create database
-npm run db:create
-
-# Run migrations
-npm run db:migrate
-
-# Seed with sample data (optional)
-npm run db:seed
+npm install bootifyjs
 ```
 
-### Start Development Server
-
-```bash
-# From root directory
-npm run dev
-```
-
-🎉 **Your API is now running at `http://localhost:3000`**
-
-## 📚 Core Concepts
-
-### 1. Controllers - HTTP Entry Points
+## Quick Start
 
 ```typescript
-import { Controller, Get, Post, Put, Delete } from '@monorepo/core';
-import { inject } from 'inversify';
-
-@Controller('/api/users')
-export class UserController {
-  constructor(
-    @inject(UserService) private userService: UserService
-  ) {}
-
-  @Get('/')
-  async getAllUsers() {
-    return this.userService.findAllUsers();
-  }
+import { createBootifyApp, Controller, Get, Service } from 'bootifyjs';
 
-  @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);
+@Service()
+class GreetingService {
+  getGreeting(name: string) {
+    return `Hello, ${name}!`;
   }
 }
-```
 
-### 2. Services - Business Logic Layer
-
-```typescript
-import { Service, Timed, Logger } from '@monorepo/core';
-import { inject } from 'inversify';
-
-@Service('singleton')
-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;
+@Controller('/api')
+class GreetingController {
+  constructor(private greetingService: GreetingService) {}
+  
+  @Get('/hello')
+  sayHello() {
+    return { message: this.greetingService.getGreeting('World') };
   }
 }
-```
-
-### 3. Repositories - Data Access Layer
-
-```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']
-    });
-  }
-
-  // Custom methods with automatic caching
-  async findByEmail(email: string): Promise<User | null> {
-    return this.findOne({ where: { email } });
-  }
 
-  async findActiveUsers(): Promise<User[]> {
-    return this.findAll({ where: { isActive: true } });
-  }
+async function main() {
+  const { start } = await createBootifyApp({
+    port: 3000,
+    controllers: [GreetingController],
+    enableSwagger: true
+  });
+  
+  await start();
+  console.log('Server running at http://localhost:3000');
 }
-```
-
-### 4. Application Bootstrap
 
-```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
-  }
-});
-
-// Register controllers
-app.registerControllers([
-  UserController,
-  OrderController,
-  HealthController
-]);
-
-await app.start();
+main().catch(console.error);
 ```
 
-## 🔧 Configuration Options
-
-### Application Configuration
-
-```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
-}
-```
-
-### 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
-```
+## Simple Configuration Management
 
-## 📊 Built-in Features
+The framework provides a very simple configuration management system that automatically maps environment variables to nested configuration properties.
 
-### Automatic API Documentation
-Visit `http://localhost:3000/docs` when `enableSwagger: true`
+### How It Works
 
-### Health Checks
-- `GET /health` - Application health
-- `GET /health/ready` - Readiness probe
+1. **Single Configuration Class**: Define one `AppConfig` class with your configuration structure
+2. **Automatic Mapping**: Environment variables with `BOOTIFY_` prefix are automatically mapped to nested properties
+3. **Type Conversion**: Values are automatically converted to numbers and booleans when possible
 
-### Metrics & Monitoring
-- `GET /metrics` - Prometheus metrics (when enabled)
-- Automatic request timing and counting
-- Error rate monitoring
+### Usage
 
-### Structured Logging
+**1. Define Your Configuration Structure:**
 ```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"
-}
-
-# Update user
-PUT /api/users/:id
-{
-  "firstName": "Jane"
+import { Config } from '../core/config';
+
+@Config('BOOTIFY')
+export class AppConfig {
+  SERVICE_NAME: string = 'bootifyjs-app';
+  
+  server: {
+    port: number;
+    host: string;
+    name?: string;
+  } = {
+    port: 3000,
+    host: 'localhost'
+  };
+  
+  database: {
+    host: string;
+    port: number;
+    name: string;
+  } = {
+    host: 'localhost',
+    port: 5432,
+    name: 'myapp'
+  };
 }
-
-# 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
+**2. Set Environment Variables:**
 ```bash
-# Health check
-GET /health
+# Maps to appConfig.SERVICE_NAME
+BOOTIFY_SERVICE_NAME=my-awesome-app
 
-# Readiness check
-GET /health/ready
+# Maps to appConfig.server.port  
+BOOTIFY_SERVER_PORT=8080
 
-# Metrics (if enabled)
-GET /metrics
-```
+# Maps to appConfig.server.host
+BOOTIFY_SERVER_HOST=0.0.0.0
 
-## 🔄 Development Workflow
+# Maps to appConfig.server.name
+BOOTIFY_SERVER_NAME=my-server
 
-### Adding a New Feature
+# Maps to appConfig.database.host
+BOOTIFY_DATABASE_HOST=postgres-server
 
-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;
-}
+# Maps to appConfig.database.port
+BOOTIFY_DATABASE_PORT=5432
 ```
 
-2. **Create Repository**
+**3. Access Configuration:**
 ```typescript
-// packages/commons/src/repositories/ProductRepository.ts
-@Repository('singleton')
-export class ProductRepository extends AppRepository<Product> {
-  constructor() {
-    super(Product, { cacheTTL: 1800 });
-  }
-}
-```
+import { getConfigInstance } from './core/config';
+import { AppConfig } from './config/app.config';
 
-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);
-  }
-}
-```
+const appConfig = getConfigInstance(AppConfig);
 
-4. **Create Controller**
-```typescript
-// packages/cms-apis/src/controllers/ProductController.ts
-@Controller('/api/products')
-export class ProductController {
-  constructor(
-    @inject(ProductService) private productService: ProductService
-  ) {}
-
-  @Post('/')
-  async createProduct(request: FastifyRequest) {
-    return this.productService.createProduct(request.body);
-  }
-}
+console.log(appConfig.SERVICE_NAME);     // 'my-awesome-app'
+console.log(appConfig.server.port);      // 8080
+console.log(appConfig.server.host);      // '0.0.0.0'
+console.log(appConfig.database.host);    // 'postgres-server'
 ```
 
-5. **Register Controller**
+**4. Inject into Services:**
 ```typescript
-// packages/cms-apis/src/index.ts
-app.registerControllers([
-  UserController,
-  ProductController, // Add new controller
-  HealthController
-]);
-```
-
-## 🧪 Testing
-
-```bash
-# Run all tests
-npm run test
-
-# Run tests for specific package
-npm run test --workspace=packages/core
-
-# Run tests in watch mode
-npm run test:watch
-```
-
-## 📦 Building & Deployment
-
-### Development
-```bash
-npm run dev
-```
-
-### Production Build
-```bash
-npm run build
-npm run start
-```
-
-### 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"]
-```
-
-## 🔧 Advanced Usage
-
-### Custom Decorators
-```typescript
-// Create custom validation decorator
-export function ValidateUser(): MethodDecorator {
-  return (target, propertyKey, descriptor) => {
-    // Custom validation logic
-  };
-}
-
-// Usage
-@Controller('/api/users')
-export class UserController {
-  @Post('/')
-  @ValidateUser()
-  async createUser(request: FastifyRequest) {
-    // Method implementation
+import { InjectConfig } from './core/decorators';
+
+@Service()
+export class MyService {
+  constructor(@InjectConfig(AppConfig) private config: AppConfig) {}
+  
+  doSomething() {
+    console.log(`Service: ${this.config.SERVICE_NAME}`);
+    console.log(`Running on port: ${this.config.server.port}`);
   }
 }
 ```
 
-### Custom Middleware
-```typescript
-const app = new Application({
-  // ... other config
-});
-
-// Add custom middleware
-app.getServer().addHook('preHandler', async (request, reply) => {
-  // Custom logic before request handling
-});
-```
+### Environment Variable Mapping Rules
 
-### 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 };
-  }
-}
-```
+The system automatically converts environment variable names to nested property paths:
 
-## 🤝 Contributing
+- `BOOTIFY_SERVICE_NAME` → `appConfig.SERVICE_NAME`
+- `BOOTIFY_SERVER_PORT` → `appConfig.server.port`
+- `BOOTIFY_SERVER_HOST` → `appConfig.server.host`
+- `BOOTIFY_DATABASE_HOST` → `appConfig.database.host`
+- `BOOTIFY_DATABASE_PORT` → `appConfig.database.port`
 
-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
+### Automatic Type Conversion
 
-## 📄 License
+- **Numbers**: `"8080"` → `8080`
+- **Booleans**: `"true"` → `true`, `"false"` → `false`
+- **Strings**: Everything else remains as string
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+### Getting Started
 
-## 🆘 Support
+1. Copy `example.env` to `.env` and modify values
+2. Set your environment variables following the `BOOTIFY_*` pattern
+3. Access your configuration using `getConfigInstance(AppConfig)`
 
-- 📖 **Documentation**: [Link to full docs]
-- 💬 **Discord**: [Community chat]
-- 🐛 **Issues**: [GitHub Issues]
-- 📧 **Email**: support@yourframework.com
+That's it! No complex setup, no manual property mapping - just define your structure and set your environment variables.
 
-## 🗺️ Roadmap
+## Features
 
-- [ ] GraphQL support
-- [ ] WebSocket integration
-- [ ] Message queue integration (RabbitMQ, Kafka)
-- [ ] Microservices communication patterns
-- [ ] Advanced caching strategies
-- [ ] Performance optimization tools
-- [ ] CLI for scaffolding
+- **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
 
----
+## Documentation
 
-**Built with ❤️ for the Node.js community**
+For more detailed documentation, please visit our [GitHub repository](https://github.com/bootifyjs/bootifyjs).