bootifyjs 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,567 @@
+# 🚀 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
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    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
+```
+
+### Environment Setup
+
+```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
+```
+
+### 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
+
+```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();
+  }
+
+  @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);
+  }
+}
+```
+
+### 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;
+  }
+}
+```
+
+### 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 } });
+  }
+}
+```
+
+### 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();
+```
+
+## 🔧 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
+```
+
+## 📊 Built-in Features
+
+### Automatic API Documentation
+Visit `http://localhost:3000/docs` when `enableSwagger: true`
+
+### Health Checks
+- `GET /health` - Application health
+- `GET /health/ready` - Readiness probe
+
+### 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"
+}
+
+# Update user
+PUT /api/users/:id
+{
+  "firstName": "Jane"
+}
+
+# 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
+```
+
+## 🔄 Development Workflow
+
+### Adding a New Feature
+
+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;
+}
+```
+
+2. **Create Repository**
+```typescript
+// packages/commons/src/repositories/ProductRepository.ts
+@Repository('singleton')
+export class ProductRepository extends AppRepository<Product> {
+  constructor() {
+    super(Product, { cacheTTL: 1800 });
+  }
+}
+```
+
+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);
+  }
+}
+```
+
+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);
+  }
+}
+```
+
+5. **Register Controller**
+```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
+  }
+}
+```
+
+### Custom Middleware
+```typescript
+const app = new Application({
+  // ... other config
+});
+
+// Add custom middleware
+app.getServer().addHook('preHandler', async (request, reply) => {
+  // Custom logic before request handling
+});
+```
+
+### 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 };
+  }
+}
+```
+
+## 🤝 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
+
+---
+
+**Built with ❤️ for the Node.js community**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bootifyjs",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Spring Boot inspired framework fro Node.js built on top of fastify and express",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",