fragment-ts 1.0.30 → 1.0.32

package/API.md

@@ -0,0 +1,752 @@
+# API Reference
+
+## Core Decorators
+
+### `@FragmentApplication(options?)`
+
+Application class decorator that configures the web server.
+
+**Parameters:**
+- `options` (ApplicationOptions, optional):
+  - `port`: number (default: 3000) - Server port
+  - `host`: string (default: "0.0.0.0") - Server host
+  - `configPath`: string (default: "fragment.json") - TypeORM config path
+  - `autoScan`: boolean (default: true) - Enable automatic component scanning
+
+**Example:**
+```typescript
+@FragmentApplication({
+  port: 8080,
+  host: 'localhost',
+  autoScan: true
+})
+export class Application {}
+```
+
+### `@Controller(path?)`
+
+Class decorator that marks a class as an HTTP controller.
+
+**Parameters:**
+- `path`: string (optional) - Base route path for all methods in this controller
+
+**Example:**
+```typescript
+@Controller('/users')
+export class UserController {}
+```
+
+### `@Service()`
+
+Class decorator that marks a class as a service (singleton-scoped by default).
+
+**Example:**
+```typescript
+@Service()
+export class UserService {}
+```
+
+### `@Repository()`
+
+Class decorator that marks a class as a repository (singleton-scoped by default).
+
+**Example:**
+```typescript
+@Repository()
+export class UserRepository {}
+```
+
+### `@AutoConfiguration()`
+
+Class decorator that marks a class as an auto-configuration component. These are loaded automatically and can conditionally register beans.
+
+**Example:**
+```typescript
+@AutoConfiguration()
+export class DatabaseAutoConfiguration {}
+```
+
+### `@Injectable(scope?)`
+
+Class decorator that marks a class as injectable with a specific scope.
+
+**Parameters:**
+- `scope`: "singleton" | "request" | "transient" (default: "singleton")
+
+**Example:**
+```typescript
+@Injectable('transient')
+export class RequestLogger {}
+```
+
+## Property Decorators
+
+### `@Autowired()`
+
+Property decorator that injects a dependency based on its type.
+
+**Example:**
+```typescript
+class MyService {
+  @Autowired()
+  private userService!: UserService;
+}
+```
+
+### `@Inject(token)`
+
+Property decorator that injects a dependency by token (string or class).
+
+**Parameters:**
+- `token`: string | Function - Token to resolve the dependency
+
+**Example:**
+```typescript
+class MyService {
+  @Inject('Logger')
+  private logger!: Logger;
+  
+  @Inject(CacheService)
+  private cacheService!: CacheService;
+}
+```
+
+### `@InjectRepository(entity)`
+
+Property decorator that injects a TypeORM repository for the specified entity.
+
+**Parameters:**
+- `entity`: Function - Entity class for which to get the repository
+
+**Example:**
+```typescript
+@Repository()
+class UserRepository {
+  @InjectRepository(User)
+  private repo!: Repository<User>;
+}
+```
+
+### `@Value(expression)`
+
+Property decorator that injects configuration values from environment variables or config.
+
+**Parameters:**
+- `expression`: string - Configuration expression (e.g., "${PORT:3000}")
+
+**Example:**
+```typescript
+@Service()
+class ConfigService {
+  @Value('${PORT:3000}')
+  private port!: number;
+  
+  @Value('${DB_HOST:localhost}')
+  private dbHost!: string;
+}
+```
+
+### `@Qualifier(name)`
+
+Property decorator that specifies which bean to inject when multiple implementations exist.
+
+**Parameters:**
+- `name`: string - Qualifier name to match
+
+**Example:**
+```typescript
+class PaymentService {
+  @Qualifier('creditCard')
+  @Autowired()
+  private paymentProcessor!: PaymentProcessor;
+}
+```
+
+### `@Optional()`
+
+Property decorator that marks a dependency as optional (won't throw if not found).
+
+**Example:**
+```typescript
+class FeatureService {
+  @Autowired()
+  @Optional()
+  private experimentalService?: ExperimentalService;
+}
+```
+
+### `@Lazy()`
+
+Property decorator that lazily loads a dependency on first access.
+
+**Example:**
+```typescript
+class HeavyService {
+  @Lazy()
+  @Autowired()
+  private resourceIntensiveService!: ResourceIntensiveService;
+}
+```
+
+## Method Decorators
+
+### `@PostConstruct()`
+
+Method decorator that marks a method to be called after dependency injection is complete.
+
+**Example:**
+```typescript
+@Service()
+class DatabaseService {
+  @PostConstruct()
+  init() {
+    // Initialize connections
+  }
+}
+```
+
+### `@PreDestroy()`
+
+Method decorator that marks a method to be called before the bean is destroyed.
+
+**Example:**
+```typescript
+@Service()
+class DatabaseService {
+  @PreDestroy()
+  cleanup() {
+    // Close connections
+  }
+}
+```
+
+## HTTP Route Decorators
+
+### `@Get(path?)`
+
+Method decorator for GET HTTP endpoints.
+
+**Parameters:**
+- `path`: string (optional) - Route path
+
+**Example:**
+```typescript
+@Controller('/users')
+class UserController {
+  @Get()
+  findAll() {}
+  
+  @Get('/:id')
+  findById(@Param('id') id: string) {}
+}
+```
+
+### `@Post(path?)`
+
+Method decorator for POST HTTP endpoints.
+
+**Parameters:**
+- `path`: string (optional) - Route path
+
+**Example:**
+```typescript
+@Controller('/users')
+class UserController {
+  @Post()
+  create(@Body() createUserDto: CreateUserDto) {}
+}
+```
+
+### `@Put(path?)`
+
+Method decorator for PUT HTTP endpoints.
+
+**Parameters:**
+- `path`: string (optional) - Route path
+
+**Example:**
+```typescript
+@Controller('/users')
+class UserController {
+  @Put('/:id')
+  update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto) {}
+}
+```
+
+### `@Delete(path?)`
+
+Method decorator for DELETE HTTP endpoints.
+
+**Parameters:**
+- `path`: string (optional) - Route path
+
+**Example:**
+```typescript
+@Controller('/users')
+class UserController {
+  @Delete('/:id')
+  delete(@Param('id') id: string) {}
+}
+```
+
+### `@Patch(path?)`
+
+Method decorator for PATCH HTTP endpoints.
+
+**Parameters:**
+- `path`: string (optional) - Route path
+
+**Example:**
+```typescript
+@Controller('/users')
+class UserController {
+  @Patch('/:id')
+  partialUpdate(@Param('id') id: string, @Body() partialUser: Partial<User>) {}
+}
+```
+
+## Parameter Decorators
+
+### `@Body()`
+
+Parameter decorator to inject the request body.
+
+**Example:**
+```typescript
+@Post()
+create(@Body() createUserDto: CreateUserDto) {}
+```
+
+### `@Param(name?)`
+
+Parameter decorator to inject route parameters.
+
+**Parameters:**
+- `name`: string (optional) - Specific parameter name to extract
+
+**Example:**
+```typescript
+@Get('/:id')
+findById(@Param('id') id: string) {}
+
+@Get('/:userId/posts/:postId')
+findPost(@Param() params: { userId: string, postId: string }) {}
+```
+
+### `@Query(name?)`
+
+Parameter decorator to inject query parameters.
+
+**Parameters:**
+- `name`: string (optional) - Specific query parameter name to extract
+
+**Example:**
+```typescript
+@Get()
+search(@Query('q') query: string, @Query('page') page: number) {}
+
+@Get('/filter')
+filter(@Query() queryParams: { category?: string, minPrice?: number }) {}
+```
+
+### `@Header(name?)`
+
+Parameter decorator to inject request headers.
+
+**Parameters:**
+- `name`: string (optional) - Specific header name to extract
+
+**Example:**
+```typescript
+@Get()
+getWithHeaders(@Header('authorization') authHeader: string) {}
+
+@Get('/info')
+getInfo(@Header() headers: Record<string, string>) {}
+```
+
+### `@Req()`
+
+Parameter decorator to inject the Express Request object.
+
+**Example:**
+```typescript
+@Get()
+handleRequest(@Req() req: Request) {
+  return { ip: req.ip, userAgent: req.get('user-agent') };
+}
+```
+
+### `@Res()`
+
+Parameter decorator to inject the Express Response object.
+
+**Example:**
+```typescript
+@Get('/file')
+getFile(@Res() res: Response) {
+  res.download('/path/to/file.pdf');
+}
+```
+
+## Conditional Decorators
+
+### `@ConditionalOnClass(classRef)`
+
+Class decorator that registers the component only if the specified class is available.
+
+**Parameters:**
+- `classRef`: any - Reference to the class to check for
+
+**Example:**
+```typescript
+@AutoConfiguration()
+@ConditionalOnClass(Redis)
+class RedisAutoConfiguration {}
+```
+
+### `@ConditionalOnMissingBean(token)`
+
+Class decorator that registers the component only if no bean of the specified type is already registered.
+
+**Parameters:**
+- `token`: any - Token or class to check for
+
+**Example:**
+```typescript
+@Service()
+@ConditionalOnMissingBean(LoggerService)
+class DefaultLoggerService implements LoggerService {}
+```
+
+### `@ConditionalOnProperty(key, expectedValue?)`
+
+Class decorator that registers the component only if the specified environment property exists (and optionally matches a value).
+
+**Parameters:**
+- `key`: string - Environment variable key to check
+- `expectedValue`: any (optional) - Expected value of the environment variable
+
+**Example:**
+```typescript
+@Service()
+@ConditionalOnProperty('USE_CACHE', 'true')
+class CacheService {}
+```
+
+## Container API
+
+### `DIContainer.getInstance()`
+
+Returns the singleton instance of the dependency injection container.
+
+**Returns:** DIContainer
+
+**Example:**
+```typescript
+const container = DIContainer.getInstance();
+```
+
+### `container.register(token, instance?, factory?)`
+
+Registers a token with an instance or factory function.
+
+**Parameters:**
+- `token`: any - Token to register
+- `instance`: any (optional) - Instance to register
+- `factory`: () => any (optional) - Factory function to create instances
+
+**Example:**
+```typescript
+container.register(LoggerService, new ConsoleLogger());
+container.register(DatabaseService, null, () => new DatabaseService());
+```
+
+### `container.resolve<T>(token)`
+
+Resolves and returns an instance for the specified token.
+
+**Parameters:**
+- `token`: any - Token to resolve
+
+**Returns:** T - Resolved instance
+
+**Example:**
+```typescript
+const userService = container.resolve(UserService);
+```
+
+### `container.has(token)`
+
+Checks if a token has been registered with the container.
+
+**Parameters:**
+- `token`: any - Token to check
+
+**Returns:** boolean
+
+**Example:**
+```typescript
+if (container.has(UserService)) {
+  // Service is registered
+}
+```
+
+### `container.getAllInstances()`
+
+Returns all singleton instances maintained by the container.
+
+**Returns:** any[]
+
+**Example:**
+```typescript
+const allServices = container.getAllInstances();
+```
+
+### `container.clear()`
+
+Clears all registered tokens and instances from the container.
+
+**Example:**
+```typescript
+container.clear();
+```
+
+### `container.reset()`
+
+Resets the container to its initial state.
+
+**Example:**
+```typescript
+container.reset();
+```
+
+## Application API
+
+### `new FragmentWebApplication()`
+
+Creates a new instance of the web application.
+
+**Example:**
+```typescript
+const app = new FragmentWebApplication();
+```
+
+### `app.bootstrap(appClass)`
+
+Bootstraps the application with the specified application class.
+
+**Parameters:**
+- `appClass`: any - Application class decorated with `@FragmentApplication`
+
+**Returns:** Promise<void>
+
+**Example:**
+```typescript
+await app.bootstrap(Application);
+```
+
+### `app.getExpressApp()`
+
+Returns the underlying Express application instance.
+
+**Returns:** Express
+
+**Example:**
+```typescript
+const expressApp = app.getExpressApp();
+expressApp.use('/custom', customMiddleware);
+```
+
+## Metadata Storage API
+
+### `MetadataStorage.getInstance()`
+
+Returns the singleton instance of the metadata storage.
+
+**Returns:** MetadataStorage
+
+**Example:**
+```typescript
+const storage = MetadataStorage.getInstance();
+```
+
+### `storage.addClass(metadata)`
+
+Adds class metadata to storage.
+
+**Parameters:**
+- `metadata`: ClassMetadata - Class metadata object
+
+**Example:**
+```typescript
+storage.addClass({
+  target: UserService,
+  type: 'service',
+  scope: 'singleton'
+});
+```
+
+### `storage.getClass(target)`
+
+Retrieves class metadata for the specified target.
+
+**Parameters:**
+- `target`: any - Target class
+
+**Returns:** ClassMetadata | undefined
+
+**Example:**
+```typescript
+const metadata = storage.getClass(UserService);
+```
+
+### `storage.getAllClasses()`
+
+Returns all registered class metadata.
+
+**Returns:** ClassMetadata[]
+
+**Example:**
+```typescript
+const allClasses = storage.getAllClasses();
+```
+
+### `storage.addMethod(metadata)`
+
+Adds method metadata to storage.
+
+**Parameters:**
+- `metadata`: MethodMetadata - Method metadata object
+
+**Example:**
+```typescript
+storage.addMethod({
+  target: UserController,
+  propertyKey: 'findAll',
+  method: 'GET',
+  path: '/',
+  paramMeta []
+});
+```
+
+### `storage.getMethod(target, propertyKey)`
+
+Retrieves method metadata for the specified target and property key.
+
+**Parameters:**
+- `target`: any - Target class
+- `propertyKey`: string - Method name
+
+**Returns:** MethodMetadata | undefined
+
+**Example:**
+```typescript
+const metadata = storage.getMethod(UserController, 'findAll');
+```
+
+### `storage.getAllMethods()`
+
+Returns all registered method metadata.
+
+**Returns:** MethodMetadata[]
+
+**Example:**
+```typescript
+const allMethods = storage.getAllMethods();
+```
+
+### `storage.addParam(metadata)`
+
+Adds parameter metadata to storage.
+
+**Parameters:**
+- `metadata`: ParamMetadata - Parameter metadata object
+
+**Example:**
+```typescript
+storage.addParam({
+  target: UserController.prototype,
+  propertyKey: 'findById',
+  index: 0,
+  type: 'param',
+  paramName: 'id'
+});
+```
+
+### `storage.getParams(target, propertyKey)`
+
+Retrieves parameter metadata for the specified target and property key.
+
+**Parameters:**
+- `target`: any - Target class
+- `propertyKey`: string - Method name
+
+**Returns:** ParamMetadata[]
+
+**Example:**
+```typescript
+const params = storage.getParams(UserController.prototype, 'findById');
+```
+
+## Interfaces
+
+### `ApplicationOptions`
+
+```typescript
+interface ApplicationOptions {
+  port?: number;
+  host?: string;
+  configPath?: string;
+  autoScan?: boolean;
+}
+```
+
+### `ClassMetadata`
+
+```typescript
+interface ClassMetadata {
+  target: any;
+  type: 'injectable' | 'service' | 'controller' | 'repository' | 'auto-configuration';
+  scope?: 'singleton' | 'request' | 'transient';
+  path?: string;
+}
+```
+
+### `MethodMetadata`
+
+```typescript
+interface MethodMetadata {
+  target: any;
+  propertyKey: string;
+  method: string;
+  path: string;
+  paramMeta ParamMetadata[];
+}
+```
+
+### `ParamMetadata`
+
+```typescript
+interface ParamMetadata {
+  target: any;
+  propertyKey: string;
+  index: number;
+  type: 'body' | 'param' | 'query' | 'header' | 'req' | 'res';
+  paramName?: string;
+}
+```
+
+## Type Definitions
+
+### `Scope`
+
+```typescript
+type Scope = 'singleton' | 'request' | 'transient';
+```
+
+### `MetadataKey`
+
+```typescript
+type MetadataKey = (typeof METADATA_KEYS)[keyof typeof METADATA_KEYS];
+```