fragment-ts 1.0.2 → 1.0.3

package/README.md

@@ -0,0 +1,401 @@
+## README.md
+
+```markdown
+# Fragment Framework
+
+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
+```
+
+## 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
+```
+
+### 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
+```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
+```
+
+## 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
+
+### Application Entry Point
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FragmentApplication, FragmentWebApplication } from 'fragment-ts;
+
+@FragmentApplication({
+  port: 3000,
+  autoScan: true
+})
+class Application {}
+
+async function bootstrap() {
+  const app = new FragmentWebApplication();
+  await app.bootstrap(Application);
+}
+
+bootstrap();
+```
+
+### Creating 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';
+
+@Controller('/users')
+export class UserController {
+  constructor(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
+
+```typescript
+// src/services/user.service.ts
+import { Service } from 'fragment-ts';
+import { UserRepository } from '../repositories/user.repository';
+
+@Service()
+export class UserService {
+  constructor(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
+
+```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' };
+  }
+}
+```
+
+## AI Integration Example
+
+```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
+{
+  "server": {
+    "port": 3000,
+    "host": "0.0.0.0"
+  },
+  "database": {
+    "type": "postgres",
+    "host": "localhost",
+    "port": 5432,
+    "username": "postgres",
+    "password": "password",
+    "database": "myapp",
+    "synchronize": false,
+    "logging": false,
+    "entities": ["dist/**/*.entity.js"],
+    "migrations": ["dist/migrations/**/*.js"]
+  }
+}
+```
+
+### Environment Variables
+
+```env
+NODE_ENV=development
+PORT=3000
+JWT_SECRET=your-secret-key
+DATABASE_URL=postgresql://user:pass@localhost:5432/db
+OPENAI_API_KEY=sk-your-key-here
+```
+
+## Development Workflow
+
+```bash
+# 1. Initialize project
+fragment init my-api --features=auth,database
+cd my-api
+
+# 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
+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
+
+### Docker
+
+```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"]
+```
+
+```bash
+docker build -t my-app .
+docker run -p 3000:3000 my-app
+```
+
+## 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
+
+- **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.
+
+## License
+
+MIT © Fragment Team
+```