fragment-ts 1.0.31 → 1.0.32

package/README.md

@@ -1,418 +1,155 @@
-## README.md
+# Fragment TS - A Modern TypeScript Framework
 
-````markdown
-# Fragment Framework
+[![npm version](https://img.shields.io/npm/v/fragment-ts)](https://www.npmjs.com/package/fragment-ts)
+[![License](https://img.shields.io/npm/l/fragment-ts)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 
-A Spring Boot-style framework for TypeScript with Express and TypeORM.
-
-## Installation
-
-```bash
-npm install -g fragment-ts
-```
-````
-
-## Quick Start
-
-```bash
-# Create a new project (in current directory)
-fragment init .
-
-# Or create a new directory
-fragment init my-app
-cd my-app
-
-# Start development server with hot reload
-fragment serve
-
-# Build for production
-fragment build
-
-# Start production server
-npm start
-```
+Fragment TS is a lightweight, dependency injection-based framework for building scalable TypeScript applications with minimal configuration. Inspired by Spring and NestJS, it provides a clean architecture with powerful decorators for controllers, services, repositories, and more.
 
 ## Features
 
-- 🎯 **Decorator-based API** - Clean, intuitive syntax inspired by Spring Boot
-- 💉 **Dependency Injection** - Automatic resolution of dependencies
-- 🗄️ **TypeORM Integration** - Full database support with migrations
-- 🔐 **Built-in Authentication** - JWT tokens, password hashing, role guards
-- 🤖 **AI Integrations** - OpenAI, Ollama, and custom AI providers
-- 🔌 **Plugin System** - Extensible architecture
-- 🧪 **Testing Framework** - Built-in test runner
-- 📦 **All-in-One Package** - No complex setup required
-- 🔄 **Hot Reload** - Automatic server restart on file changes
-- 🎨 **Code Generation** - CLI tools for rapid development
-
-## CLI Commands
-
-### Project Management
-
-```bash
-fragment init [dir]              # Initialize new project (use . for current directory)
-fragment init . --features=auth  # Initialize with specific features
-fragment serve                   # Start development server with hot reload
-fragment serve --port=4000       # Start on custom port
-fragment build                   # Build for production
-```
-
-### Code Generation
-
-```bash
-fragment generate controller <name>   # Generate controller
-fragment generate service <name>      # Generate service with optional repository
-fragment generate entity <name>       # Generate TypeORM entity
-fragment generate resource <name>     # Generate complete CRUD resource
-fragment generate dto <name>          # Generate Data Transfer Object
-fragment generate repository <name>   # Generate repository
-```
-
-**Examples:**
-
-```bash
-fragment generate resource product    # Creates controller, service, entity, DTO, repository
-fragment g controller users           # Shorthand: g = generate
-```
+- 🚀 **Dependency Injection**: Automatic wiring of components with `@Autowired` and other decorators
+- 🎮 **REST Controllers**: Define routes with familiar decorators like `@Get()`, `@Post()`
+- 💾 **TypeORM Integration**: Seamless repository pattern with `@InjectRepository`
+- ⚙️ **Modular Architecture**: Organize code into services, controllers, and repositories
+- 🔧 **Auto-configuration**: Smart component scanning and registration
+- 🧪 **Testable Design**: Easily mock dependencies for unit testing
+- 📦 **Production Ready**: Works with compiled JavaScript and TypeScript source
 
-### Database Operations
-
-```bash
-fragment migrate                     # Run all pending migrations
-fragment migrate:create <name>       # Create a new migration
-fragment migrate:run                 # Run migrations
-fragment migrate:revert              # Revert last migration
-fragment migrate:refresh             # Drop all and re-run migrations
-fragment migrate:status              # Show migration status
-fragment schema:sync                 # Sync database schema (dev only)
-fragment schema:drop                 # Drop all database tables
-fragment seed                        # Run database seeds
-fragment seed:create <name>          # Create a new seed file
-```
-
-### Diagnostics & Debugging
+## Installation
 
 ```bash
-fragment routes                      # List all registered routes
-fragment routes --env=dev            # List routes from TypeScript source
-fragment routes --env=prod           # List routes from compiled dist/
-fragment beans                       # List all registered beans
-fragment beans --tree                # Show beans as tree structure
-fragment info                        # Show application information
-fragment config                      # Show current configuration
-fragment version                     # Show Fragment version
+npm install fragment-ts reflect-metadata typeorm mysql2
+# or
+yarn add fragment-ts reflect-metadata typeorm mysql2
 ```
 
-## Project Structure
-
-```
-my-app/
-├── src/
-│   ├── controllers/          # HTTP controllers
-│   ├── services/             # Business logic
-│   ├── repositories/         # Data access layer
-│   ├── entities/             # TypeORM entities
-│   ├── dto/                  # Data transfer objects
-│   ├── middlewares/          # Express middlewares
-│   ├── config/               # Configuration files
-│   └── main.ts               # Application entry point
-├── dist/                     # Compiled JavaScript (after build)
-├── test/                     # Test files
-├── fragment.json             # Fragment configuration
-├── tsconfig.json             # TypeScript configuration
-└── package.json
-```
-
-## Basic Example
+## Quick Start
 
-### Application Entry Point
+### 1. Create your application entry point:
 
 ```typescript
-// src/main.ts
+// src/app.ts
 import 'reflect-metadata';
-import { FragmentApplication, FragmentWebApplication } from 'fragment-ts;
+import { FragmentApplication, DIContainer } from 'fragment-ts';
 
 @FragmentApplication({
   port: 3000,
   autoScan: true
 })
-class Application {}
+export class Application {
+  constructor() {
+    console.log('Application starting...');
+  }
+}
 
 async function bootstrap() {
   const app = new FragmentWebApplication();
   await app.bootstrap(Application);
 }
 
-bootstrap();
+bootstrap().catch(console.error);
 ```
 
-### Creating a Controller
+### 2. Create a controller:
 
 ```typescript
-// src/controllers/users.controller.ts
-import { Controller, Get, Post, Put, Delete, Body, Param } from "fragment-ts";
-import { UserService } from "../services/user.service";
+// src/controllers/user.controller.ts
+import { Controller, Get, Autowired } from 'fragment-ts';
+import { UserService } from '../services/user.service';
 
-@Controller("/users")
+@Controller('/users')
 export class UserController {
-  constructor(private userService: UserService) {}
+  @Autowired()
+  private userService!: UserService;
 
   @Get()
   async findAll() {
     return this.userService.findAll();
   }
-
-  @Get("/:id")
-  async findOne(@Param("id") id: string) {
-    return this.userService.findOne(id);
-  }
-
-  @Post()
-  async create(@Body() body: any) {
-    return this.userService.create(body);
-  }
-
-  @Put("/:id")
-  async update(@Param("id") id: string, @Body() body: any) {
-    return this.userService.update(id, body);
-  }
-
-  @Delete("/:id")
-  async delete(@Param("id") id: string) {
-    return this.userService.delete(id);
-  }
 }
 ```
 
-### Creating a Service
+### 3. Create a service:
 
 ```typescript
 // src/services/user.service.ts
-import { Service } from "fragment-ts";
-import { UserRepository } from "../repositories/user.repository";
+import { Service, Autowired } from 'fragment-ts';
+import { UserRepository } from '../repositories/user.repository';
 
 @Service()
 export class UserService {
-  constructor(private userRepository: UserRepository) {}
-
+  @Autowired()
+  private userRepository!: UserRepository;
+  
   async findAll() {
     return this.userRepository.findAll();
   }
-
-  async findOne(id: string) {
-    return this.userRepository.findById(parseInt(id));
-  }
-
-  async create(data: any) {
-    return this.userRepository.create(data);
-  }
-
-  async update(id: string, data: any) {
-    return this.userRepository.update(parseInt(id), data);
-  }
-
-  async delete(id: string) {
-    return this.userRepository.delete(parseInt(id));
-  }
 }
 ```
 
-## Authentication Example
+### 4. Create a repository:
 
 ```typescript
-import { Controller, Post, Body } from "fragment-ts";
-import { AuthModule } from "fragment-ts";
-
-@Controller("/auth")
-export class AuthController {
-  @Post("/login")
-  async login(@Body() body: any) {
-    // Verify user credentials...
-    const token = AuthModule.generateToken({
-      userId: "123",
-      email: body.email,
-      roles: ["user"],
-    });
-    return { token };
-  }
-
-  @Post("/register")
-  async register(@Body() body: any) {
-    const hashedPassword = await AuthModule.hashPassword(body.password);
-    // Save user...
-    return { message: "User registered successfully" };
+// src/repositories/user.repository.ts
+import { Repository, InjectRepository } from 'fragment-ts';
+import { User } from '../entities/user.entity';
+import { Repository as TypeOrmRepository } from 'typeorm';
+
+@Repository()
+export class UserRepository {
+  @InjectRepository(User)
+  private repo!: TypeOrmRepository<User>;
+  
+  async findAll() {
+    return this.repo.find();
   }
 }
 ```
 
-## AI Integration Example
+### 5. Configure TypeORM:
 
 ```typescript
-import { Service } from "fragment-ts";
-import { AIModule } from "fragment-ts";
-
-@Service()
-export class ChatService {
-  private aiModule: AIModule;
-
-  constructor() {
-    this.aiModule = new AIModule({
-      openaiKey: process.env.OPENAI_API_KEY,
-    });
-  }
-
-  async chat(message: string) {
-    return this.aiModule.complete([
-      { role: "system", content: "You are a helpful assistant." },
-      { role: "user", content: message },
-    ]);
-  }
-}
-```
-
-## Configuration
-
-### fragment.json
-
-```json
+// fragment.json
 {
-  "server": {
-    "port": 3000,
-    "host": "0.0.0.0"
-  },
-  "database": {
-    "type": "postgres",
-    "host": "${DB_HOST}",
-    "port": ${DB_PORT},
-    "username": "${DB_USERNAME}",
-    "password": "${DB_PASSWORD}",
-    "database": "${DB_NAME}",
-    "synchronize": false,
-    "logging": false,
-    "entities": ["dist/**/*.entity.js"],
-    "migrations": ["dist/migrations/**/*.js"]
-  }
+  "type": "mysql",
+  "host": "localhost",
+  "port": 3306,
+  "username": "root",
+  "password": "password",
+  "database": "my_db",
+  "entities": ["dist/entities/**/*.js"],
+  "synchronize": true
 }
-
-```
-
-### Environment Variables
-
-```env
-NODE_ENV=development
-PORT=3000
-JWT_SECRET=${JWT_SECRET}
-DATABASE_URL=postgresql://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}
-DB_HOST=localhost
-DB_PORT=5432
-DB_USERNAME=postgres
-DB_PASSWORD=password
-DB_NAME=myapp
-OPENAI_API_KEY=${OPENAI_API_KEY}
 ```
 
-## Development Workflow
+## Running the Application
 
 ```bash
-# 1. Initialize project
-fragment init my-api --features=auth,database
-cd my-api
+# Development (TypeScript)
+npx ts-node src/app.ts
 
-# 2. Generate resources
-fragment generate resource user
-fragment generate resource product
-
-# 3. Create and run migrations
-fragment migrate:create InitialSchema
-fragment migrate:run
-
-# 4. Start development server
-fragment serve
-
-# 5. List routes to verify
-fragment routes
-
-# 6. Build for production
-fragment build
-
-# 7. Start production server
+# Production (compiled JavaScript)
 npm start
 ```
 
-## Testing
-
-```typescript
-// test/user.spec.ts
-import { describe, it, expect } from "fragment-ts";
-
-describe("UserService", () => {
-  it("should create a user", async () => {
-    const user = await userService.create({
-      email: "test@example.com",
-      name: "Test User",
-    });
-
-    expect(user.email).toBe("test@example.com");
-  });
-});
-```
-
-```bash
-# Run tests
-fragment test
-```
-
-## Production Deployment
+## Configuration
 
-### Docker
+Fragment automatically detects whether you're running in development (TypeScript) or production (compiled JavaScript) mode:
 
-```dockerfile
-FROM node:18-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --only=production
-COPY . .
-RUN npm run build
-EXPOSE 3000
-CMD ["npm", "start"]
-```
+- **Development Mode**: Scans `src/` directory for `.ts` files
+- **Production Mode**: Scans `dist/` directory for `.js` files
 
+You can explicitly set the mode with the environment variable:
 ```bash
-docker build -t my-app .
-docker run -p 3000:3000 my-app
+FRAGMENT_DEV_MODE=true node dist/app.js
 ```
 
-## Examples
-
-Check out the [examples](./examples) directory for complete working applications:
-
-- REST API
-- Authentication System
-- AI Chat Application
-- E-commerce Backend
-
-## Documentation
-
-For comprehensive guides and API reference, visit:
-
-- **Full Documentation**: [https://fragment.digitwhale.com](https://fragment.digitwhale.com)
-- **Use Cases & Examples**: [USECASES.md](./USECASES.md)
-- **API Reference**: [https://fragment.digitwhale.com/api](https://fragment.digitwhale.com/api)
-
-## Community
+## Support
 
-- **GitHub**: [https://github.com/fragment/framework](https://github.com/fragment/framework)
-- **Discord**: [https://discord.gg/fragment](https://discord.gg/fragment)
-- **Twitter**: [@FragmentJS](https://twitter.com/FragmentJS)
-
-## Contributing
-
-We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+For issues and feature requests, please [open an issue](https://github.com/yourusername/fragment-ts/issues).
 
 ## License
 
-MIT © Fragment Team
-
-```
-
-```
+MIT © [Your Name]
+```