fragment-ts 1.0.17 → 1.0.18

package/SETUP.md

@@ -0,0 +1,570 @@
+# Fragment Framework - Complete Setup Guide
+
+## Overview
+
+Fragment is a TypeScript framework inspired by Spring Boot that provides:
+- Dependency Injection with decorators
+- TypeORM integration
+- RESTful API support
+- Built-in testing framework
+- CLI tools for development
+
+## Installation
+
+```bash
+npm install fragment-ts reflect-metadata typeorm
+```
+
+## Project Setup
+
+### 1. Initialize Project
+
+```bash
+fragment init
+```
+
+This creates:
+```
+project/
+├── src/
+│   ├── app.ts
+│   ├── controllers/
+│   ├── services/
+│   ├── repositories/
+│   └── entities/
+├── fragment.json
+├── tsconfig.json
+└── package.json
+```
+
+### 2. Configure tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### 3. Configure fragment.json
+
+```json
+{
+  "port": 3000,
+  "host": "0.0.0.0",
+  "database": {
+    "type": "postgres",
+    "host": "${DB_HOST:localhost}",
+    "port": 5432,
+    "username": "${DB_USER:postgres}",
+    "password": "${DB_PASSWORD}",
+    "database": "${DB_NAME:myapp}",
+    "entities": ["dist/**/*.entity.js"],
+    "synchronize": false,
+    "logging": false
+  }
+}
+```
+
+### 4. Create .env file
+
+```bash
+DB_HOST=localhost
+DB_USER=postgres
+DB_PASSWORD=secret
+DB_NAME=myapp
+EMAIL_FROM=noreply@example.com
+EMAIL_ENABLED=true
+MAX_USERS=1000
+```
+
+## Available Decorators
+
+### Class Decorators
+
+#### @FragmentApplication
+Application entry point decorator.
+
+```typescript
+@FragmentApplication({
+  port: 3000,
+  host: '0.0.0.0',
+})
+export class App {}
+```
+
+#### @Controller
+Defines a REST controller.
+
+```typescript
+@Controller('/api/users')
+export class UserController {
+  // Routes defined here
+}
+```
+
+#### @Service
+Business logic layer.
+
+```typescript
+@Service()
+export class UserService {
+  // Service methods
+}
+```
+
+#### @Repository
+Data access layer.
+
+```typescript
+@Repository()
+export class UserRepository {
+  @InjectRepository(User)
+  private repo!: Repository<User>;
+}
+```
+
+#### @Injectable
+General purpose injectable component.
+
+```typescript
+@Injectable()
+export class EmailService {
+  // Utility methods
+}
+```
+
+#### @AutoConfiguration
+Auto-configuration component (conditional beans).
+
+```typescript
+@AutoConfiguration()
+@ConditionalOnProperty('REDIS_ENABLED', 'true')
+export class RedisConfig {
+  // Redis setup
+}
+```
+
+### Property Decorators
+
+#### @Autowired
+Automatic dependency injection by type.
+
+```typescript
+@Service()
+export class UserService {
+  @Autowired()
+  private userRepository!: UserRepository;
+  
+  @Autowired()
+  private emailService!: EmailService;
+}
+```
+
+#### @InjectRepository
+Inject TypeORM repository.
+
+```typescript
+@Repository()
+export class UserRepository {
+  @InjectRepository(User)
+  private userRepo!: Repository<User>;
+}
+```
+
+#### @Value
+Inject configuration values from environment.
+
+```typescript
+@Service()
+export class AppService {
+  @Value('${PORT:3000}')
+  private port!: number;
+  
+  @Value('${API_KEY}')
+  private apiKey!: string;
+}
+```
+
+#### @Inject
+Inject dependency by token.
+
+```typescript
+@Service()
+export class MyService {
+  @Inject('DATABASE_CONNECTION')
+  private db!: DatabaseConnection;
+}
+```
+
+#### @Qualifier
+Specify which bean to inject.
+
+```typescript
+@Service()
+export class MyService {
+  @Qualifier('primary')
+  @Autowired()
+  private cache!: CacheService;
+}
+```
+
+### Method Decorators
+
+#### HTTP Method Decorators
+Route handlers: `@Get`, `@Post`, `@Put`, `@Delete`, `@Patch`
+
+```typescript
+@Controller('/api/users')
+export class UserController {
+  @Get('/')
+  getAllUsers() {
+    return { users: [] };
+  }
+  
+  @Get('/:id')
+  getUserById(@Param('id') id: string) {
+    return { id };
+  }
+  
+  @Post('/')
+  createUser(@Body() data: any) {
+    return { created: true };
+  }
+}
+```
+
+#### @PostConstruct
+Called after dependency injection.
+
+```typescript
+@Service()
+export class MyService {
+  @PostConstruct()
+  init() {
+    console.log('Service initialized');
+  }
+}
+```
+
+#### @PreDestroy
+Called before bean destruction.
+
+```typescript
+@Service()
+export class MyService {
+  @PreDestroy()
+  cleanup() {
+    console.log('Cleaning up resources');
+  }
+}
+```
+
+### Parameter Decorators
+
+#### @Body
+Extract request body.
+
+```typescript
+@Post('/')
+createUser(@Body() userData: CreateUserDto) {
+  // userData contains request body
+}
+```
+
+#### @Param
+Extract route parameter.
+
+```typescript
+@Get('/:id')
+getUser(@Param('id') id: string) {
+  // id from route parameter
+}
+```
+
+#### @Query
+Extract query parameter.
+
+```typescript
+@Get('/')
+getUsers(@Query('page') page: string, @Query('limit') limit: string) {
+  // page and limit from query string
+}
+```
+
+#### @Header
+Extract header value.
+
+```typescript
+@Get('/')
+getData(@Header('authorization') auth: string) {
+  // auth from Authorization header
+}
+```
+
+#### @Req, @Res
+Access raw request/response objects.
+
+```typescript
+@Get('/')
+getData(@Req() req: Request, @Res() res: Response) {
+  // Full Express request/response
+}
+```
+
+## CLI Commands
+
+### Development
+
+```bash
+# Start development server (watches TypeScript files)
+fragment serve
+
+# Or with specific host/port
+fragment serve --host 0.0.0.0 --port 3000
+```
+
+### Build
+
+```bash
+# Compile TypeScript to JavaScript
+fragment build
+
+# Build and watch for changes
+fragment build --watch
+```
+
+### Testing
+
+```bash
+# Run all tests
+fragment test
+
+# Run tests in watch mode
+fragment test --watch
+
+# Run specific test pattern
+fragment test --pattern "**/*.spec.ts"
+
+# Run tests in production mode (compiled)
+fragment test --env prod
+```
+
+### Database Migrations
+
+```bash
+# Generate migration
+fragment migrate:generate CreateUsers
+
+# Run migrations
+fragment migrate:run
+
+# Revert last migration
+fragment migrate:revert
+
+# Show migration status
+fragment migrate:show
+```
+
+### Diagnostics
+
+```bash
+# List all routes
+fragment routes
+
+# List all beans (components)
+fragment beans
+
+# Show as tree
+fragment beans --tree
+
+# Show application info
+fragment info
+
+# Show configuration
+fragment config
+
+# Show version
+fragment version
+```
+
+### Code Generation
+
+```bash
+# Generate controller
+fragment generate controller User
+
+# Generate service
+fragment generate service User
+
+# Generate repository
+fragment generate repository User
+
+# Generate entity
+fragment generate entity User
+
+# Generate complete CRUD module
+fragment generate module User
+```
+
+## Testing Guide
+
+### Writing Tests
+
+Create test files with `.spec.ts` extension:
+
+```typescript
+// user.service.spec.ts
+import 'reflect-metadata';
+import { UserService } from './user.service';
+import { DIContainer } from 'fragment-ts';
+
+describe('UserService', () => {
+  let service: UserService;
+  let container: DIContainer;
+
+  beforeEach(() => {
+    container = DIContainer.getInstance();
+    container.reset();
+    service = container.resolve(UserService);
+  });
+
+  it('should create user', async () => {
+    const user = await service.createUser({
+      name: 'Test',
+      email: 'test@example.com'
+    });
+
+    expect(user.name).toBe('Test');
+    expect(user.email).toBe('test@example.com');
+  });
+});
+```
+
+### Test Functions
+
+- `describe(name, fn)` - Test suite
+- `it(name, fn)` - Test case
+- `expect(value)` - Assertion
+  - `.toBe(expected)` - Strict equality
+  - `.toEqual(expected)` - Deep equality
+  - `.toBeTruthy()` - Truthy check
+  - `.toBeFalsy()` - Falsy check
+  - `.toThrow()` - Function throws
+  - `.toBeInstanceOf(class)` - Instance check
+  - `.toContain(value)` - Array/string contains
+  - `.toHaveProperty(prop, value?)` - Object has property
+  - `.toBeNull()` - Null check
+  - `.toBeUndefined()` - Undefined check
+  - `.toHaveLength(n)` - Length check
+
+## Troubleshooting
+
+### @Autowired not working
+
+**Problem:** Properties are undefined after injection.
+
+**Solution:**
+1. Ensure `emitDecoratorMetadata: true` in tsconfig.json
+2. Import `reflect-metadata` at app entry point
+3. Make sure the dependency is registered in DI container
+4. Check that decorators are applied in correct order
+
+```typescript
+import 'reflect-metadata'; // Add this at the top of main file
+
+@Service() // Must be before class
+export class MyService {
+  @Autowired() // Property decorator
+  private dep!: MyDependency; // Use ! for definite assignment
+}
+```
+
+### TypeORM Repository not injected
+
+**Problem:** Repository is undefined in @Repository classes.
+
+**Solution:**
+1. Make sure TypeORM is initialized before app bootstrap
+2. Use @InjectRepository with the entity class
+3. Entity must be decorated with @Entity
+
+```typescript
+@Entity()
+export class User {
+  @PrimaryGeneratedColumn()
+  id!: number;
+}
+
+@Repository()
+export class UserRepository {
+  @InjectRepository(User) // Pass entity class
+  private repo!: Repository<User>;
+}
+```
+
+### Tests not running
+
+**Problem:** `fragment test` finds no tests.
+
+**Solution:**
+1. Test files must end with `.spec.ts`
+2. Place tests in `src/` directory
+3. Use correct test pattern: `--pattern "**/*.spec.ts"`
+
+### Environment variables not loading
+
+**Problem:** @Value decorator returns empty string.
+
+**Solution:**
+1. Create `.env` file in project root
+2. Use correct syntax: `${VAR_NAME}` or `${VAR_NAME:default}`
+3. Install dotenv: `npm install dotenv`
+
+## Best Practices
+
+1. **Single Responsibility** - Each service should have one clear purpose
+2. **Dependency Injection** - Use @Autowired instead of creating instances
+3. **Type Safety** - Always define types for method parameters and returns
+4. **Error Handling** - Use try-catch blocks in controllers
+5. **Testing** - Write tests for all services and repositories
+6. **Environment Config** - Never hardcode secrets, use .env files
+7. **Migrations** - Always use migrations, never synchronize in production
+
+## Example Project Structure
+
+```
+my-app/
+├── src/
+│   ├── app.ts                    # Application entry
+│   ├── entities/
+│   │   └── user.entity.ts       # TypeORM entities
+│   ├── repositories/
+│   │   └── user.repository.ts   # Data access layer
+│   ├── services/
+│   │   ├── user.service.ts      # Business logic
+│   │   └── email.service.ts     # Utilities
+│   ├── controllers/
+│   │   └── user.controller.ts   # REST endpoints
+│   └── __tests__/
+│       └── user.service.spec.ts # Tests
+├── dist/                         # Compiled output
+├── migrations/                   # Database migrations
+├── .env                         # Environment variables
+├── fragment.json                # Framework config
+├── tsconfig.json                # TypeScript config
+└── package.json                 # Dependencies
+```