fragment-ts 1.0.33 → 1.0.35

package/API.md

@@ -1,3 +1,5 @@
+---
+
 # API Reference
 
 ## Core Decorators
@@ -7,6 +9,7 @@
 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
@@ -14,11 +17,12 @@ Application class decorator that configures the web server.
   - `autoScan`: boolean (default: true) - Enable automatic component scanning
 
 **Example:**
+
 ```typescript
 @FragmentApplication({
   port: 8080,
-  host: 'localhost',
-  autoScan: true
+  host: "localhost",
+  autoScan: true,
 })
 export class Application {}
 ```
@@ -28,11 +32,13 @@ export class Application {}
 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')
+@Controller("/users")
 export class UserController {}
 ```
 
@@ -41,6 +47,7 @@ export class UserController {}
 Class decorator that marks a class as a service (singleton-scoped by default).
 
 **Example:**
+
 ```typescript
 @Service()
 export class UserService {}
@@ -51,6 +58,7 @@ export class UserService {}
 Class decorator that marks a class as a repository (singleton-scoped by default).
 
 **Example:**
+
 ```typescript
 @Repository()
 export class UserRepository {}
@@ -61,6 +69,7 @@ export class UserRepository {}
 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 {}
@@ -71,14 +80,111 @@ export class DatabaseAutoConfiguration {}
 Class decorator that marks a class as injectable with a specific scope.
 
 **Parameters:**
+
 - `scope`: "singleton" | "request" | "transient" (default: "singleton")
 
 **Example:**
+
 ```typescript
-@Injectable('transient')
+@Injectable("transient")
 export class RequestLogger {}
 ```
 
+## Enhancement Decorators
+
+### `@FragmentMiddleware(middlewareClass)`
+
+Class or method decorator that applies Express-compatible middleware to controllers or routes.
+
+**Parameters:**
+
+- `middlewareClass`: Class implementing `Middleware` interface
+
+**Example:**
+
+```typescript
+@FragmentMiddleware(AuthMiddleware)
+@Controller("/api")
+export class AppController {}
+
+// Or on a specific route
+@Controller("/api")
+export class AppController {
+  @Get("/health")
+  @FragmentMiddleware(LoggingMiddleware)
+  health() {}
+}
+```
+
+### `@FragmentGuard(guardClass)`
+
+Class or method decorator that applies authorization/activation guards to controllers or routes.
+
+**Parameters:**
+
+- `guardClass`: Class implementing `Guard` interface
+
+**Example:**
+
+```typescript
+@FragmentGuard(AuthGuard)
+@Controller("/secure")
+export class SecureController {}
+
+// Or on a specific route
+@Controller("/api")
+export class AppController {
+  @Get("/admin")
+  @FragmentGuard(AdminGuard)
+  adminData() {}
+}
+```
+
+### `@FragmentInterceptor(interceptorClass)`
+
+Class or method decorator that applies interceptors to transform request/response data.
+
+**Parameters:**
+
+- `interceptorClass`: Class implementing `Interceptor` interface
+
+**Example:**
+
+```typescript
+@FragmentInterceptor(TransformInterceptor)
+@Controller("/api")
+export class DataController {}
+
+// Or on a specific route
+@Controller("/api")
+export class AppController {
+  @Get("/data")
+  @FragmentInterceptor(CacheInterceptor)
+  getData() {}
+}
+```
+
+### `@FragmentExceptionFilter(filterClass)`
+
+Class or method decorator that applies exception filters for error handling.
+
+**Parameters:**
+
+- `filterClass`: Class implementing `ExceptionFilter` interface
+
+**Example:**
+
+```typescript
+@FragmentExceptionFilter(GlobalExceptionFilter)
+@FragmentApplication()
+export class Application {}
+
+// Or on a controller
+@FragmentExceptionFilter(DatabaseExceptionFilter)
+@Controller("/api")
+export class AppController {}
+```
+
 ## Property Decorators
 
 ### `@Autowired()`
@@ -86,6 +192,7 @@ export class RequestLogger {}
 Property decorator that injects a dependency based on its type.
 
 **Example:**
+
 ```typescript
 class MyService {
   @Autowired()
@@ -98,14 +205,16 @@ class MyService {
 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')
+  @Inject("Logger")
   private logger!: Logger;
-  
+
   @Inject(CacheService)
   private cacheService!: CacheService;
 }
@@ -116,9 +225,11 @@ class MyService {
 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 {
@@ -132,16 +243,18 @@ class UserRepository {
 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}')
+  @Value("${PORT:3000}")
   private port!: number;
-  
-  @Value('${DB_HOST:localhost}')
+
+  @Value("${DB_HOST:localhost}")
   private dbHost!: string;
 }
 ```
@@ -151,12 +264,14 @@ class ConfigService {
 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')
+  @Qualifier("creditCard")
   @Autowired()
   private paymentProcessor!: PaymentProcessor;
 }
@@ -167,6 +282,7 @@ class PaymentService {
 Property decorator that marks a dependency as optional (won't throw if not found).
 
 **Example:**
+
 ```typescript
 class FeatureService {
   @Autowired()
@@ -180,6 +296,7 @@ class FeatureService {
 Property decorator that lazily loads a dependency on first access.
 
 **Example:**
+
 ```typescript
 class HeavyService {
   @Lazy()
@@ -195,6 +312,7 @@ class HeavyService {
 Method decorator that marks a method to be called after dependency injection is complete.
 
 **Example:**
+
 ```typescript
 @Service()
 class DatabaseService {
@@ -210,6 +328,7 @@ class DatabaseService {
 Method decorator that marks a method to be called before the bean is destroyed.
 
 **Example:**
+
 ```typescript
 @Service()
 class DatabaseService {
@@ -227,17 +346,19 @@ class DatabaseService {
 Method decorator for GET HTTP endpoints.
 
 **Parameters:**
+
 - `path`: string (optional) - Route path
 
 **Example:**
+
 ```typescript
-@Controller('/users')
+@Controller("/users")
 class UserController {
   @Get()
   findAll() {}
-  
-  @Get('/:id')
-  findById(@Param('id') id: string) {}
+
+  @Get("/:id")
+  findById(@Param("id") id: string) {}
 }
 ```
 
@@ -246,11 +367,13 @@ class UserController {
 Method decorator for POST HTTP endpoints.
 
 **Parameters:**
+
 - `path`: string (optional) - Route path
 
 **Example:**
+
 ```typescript
-@Controller('/users')
+@Controller("/users")
 class UserController {
   @Post()
   create(@Body() createUserDto: CreateUserDto) {}
@@ -262,14 +385,16 @@ class UserController {
 Method decorator for PUT HTTP endpoints.
 
 **Parameters:**
+
 - `path`: string (optional) - Route path
 
 **Example:**
+
 ```typescript
-@Controller('/users')
+@Controller("/users")
 class UserController {
-  @Put('/:id')
-  update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto) {}
+  @Put("/:id")
+  update(@Param("id") id: string, @Body() updateUserDto: UpdateUserDto) {}
 }
 ```
 
@@ -278,14 +403,16 @@ class UserController {
 Method decorator for DELETE HTTP endpoints.
 
 **Parameters:**
+
 - `path`: string (optional) - Route path
 
 **Example:**
+
 ```typescript
-@Controller('/users')
+@Controller("/users")
 class UserController {
-  @Delete('/:id')
-  delete(@Param('id') id: string) {}
+  @Delete("/:id")
+  delete(@Param("id") id: string) {}
 }
 ```
 
@@ -294,14 +421,16 @@ class UserController {
 Method decorator for PATCH HTTP endpoints.
 
 **Parameters:**
+
 - `path`: string (optional) - Route path
 
 **Example:**
+
 ```typescript
-@Controller('/users')
+@Controller("/users")
 class UserController {
-  @Patch('/:id')
-  partialUpdate(@Param('id') id: string, @Body() partialUser: Partial<User>) {}
+  @Patch("/:id")
+  partialUpdate(@Param("id") id: string, @Body() partialUser: Partial<User>) {}
 }
 ```
 
@@ -312,6 +441,7 @@ class UserController {
 Parameter decorator to inject the request body.
 
 **Example:**
+
 ```typescript
 @Post()
 create(@Body() createUserDto: CreateUserDto) {}
@@ -322,9 +452,11 @@ create(@Body() createUserDto: CreateUserDto) {}
 Parameter decorator to inject route parameters.
 
 **Parameters:**
+
 - `name`: string (optional) - Specific parameter name to extract
 
 **Example:**
+
 ```typescript
 @Get('/:id')
 findById(@Param('id') id: string) {}
@@ -338,9 +470,11 @@ findPost(@Param() params: { userId: string, postId: string }) {}
 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) {}
@@ -354,9 +488,11 @@ filter(@Query() queryParams: { category?: string, minPrice?: number }) {}
 Parameter decorator to inject request headers.
 
 **Parameters:**
+
 - `name`: string (optional) - Specific header name to extract
 
 **Example:**
+
 ```typescript
 @Get()
 getWithHeaders(@Header('authorization') authHeader: string) {}
@@ -370,6 +506,7 @@ getInfo(@Header() headers: Record<string, string>) {}
 Parameter decorator to inject the Express Request object.
 
 **Example:**
+
 ```typescript
 @Get()
 handleRequest(@Req() req: Request) {
@@ -382,6 +519,7 @@ handleRequest(@Req() req: Request) {
 Parameter decorator to inject the Express Response object.
 
 **Example:**
+
 ```typescript
 @Get('/file')
 getFile(@Res() res: Response) {
@@ -396,9 +534,11 @@ getFile(@Res() res: Response) {
 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)
@@ -410,9 +550,11 @@ class RedisAutoConfiguration {}
 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)
@@ -424,13 +566,15 @@ class DefaultLoggerService implements LoggerService {}
 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')
+@ConditionalOnProperty("USE_CACHE", "true")
 class CacheService {}
 ```
 
@@ -443,6 +587,7 @@ Returns the singleton instance of the dependency injection container.
 **Returns:** DIContainer
 
 **Example:**
+
 ```typescript
 const container = DIContainer.getInstance();
 ```
@@ -452,11 +597,13 @@ const container = DIContainer.getInstance();
 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());
@@ -467,11 +614,13 @@ container.register(DatabaseService, null, () => new DatabaseService());
 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);
 ```
@@ -481,11 +630,13 @@ const userService = container.resolve(UserService);
 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
@@ -499,6 +650,7 @@ Returns all singleton instances maintained by the container.
 **Returns:** any[]
 
 **Example:**
+
 ```typescript
 const allServices = container.getAllInstances();
 ```
@@ -508,6 +660,7 @@ const allServices = container.getAllInstances();
 Clears all registered tokens and instances from the container.
 
 **Example:**
+
 ```typescript
 container.clear();
 ```
@@ -517,6 +670,7 @@ container.clear();
 Resets the container to its initial state.
 
 **Example:**
+
 ```typescript
 container.reset();
 ```
@@ -528,6 +682,7 @@ container.reset();
 Creates a new instance of the web application.
 
 **Example:**
+
 ```typescript
 const app = new FragmentWebApplication();
 ```
@@ -537,11 +692,13 @@ const app = new FragmentWebApplication();
 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);
 ```
@@ -553,9 +710,10 @@ Returns the underlying Express application instance.
 **Returns:** Express
 
 **Example:**
+
 ```typescript
 const expressApp = app.getExpressApp();
-expressApp.use('/custom', customMiddleware);
+expressApp.use("/custom", customMiddleware);
 ```
 
 ## Metadata Storage API
@@ -567,6 +725,7 @@ Returns the singleton instance of the metadata storage.
 **Returns:** MetadataStorage
 
 **Example:**
+
 ```typescript
 const storage = MetadataStorage.getInstance();
 ```
@@ -576,14 +735,16 @@ const storage = MetadataStorage.getInstance();
 Adds class metadata to storage.
 
 **Parameters:**
+
 - `metadata`: ClassMetadata - Class metadata object
 
 **Example:**
+
 ```typescript
 storage.addClass({
   target: UserService,
-  type: 'service',
-  scope: 'singleton'
+  type: "service",
+  scope: "singleton",
 });
 ```
 
@@ -592,11 +753,13 @@ storage.addClass({
 Retrieves class metadata for the specified target.
 
 **Parameters:**
+
 - `target`: any - Target class
 
 **Returns:** ClassMetadata | undefined
 
 **Example:**
+
 ```typescript
 const metadata = storage.getClass(UserService);
 ```
@@ -608,6 +771,7 @@ Returns all registered class metadata.
 **Returns:** ClassMetadata[]
 
 **Example:**
+
 ```typescript
 const allClasses = storage.getAllClasses();
 ```
@@ -617,9 +781,11 @@ const allClasses = storage.getAllClasses();
 Adds method metadata to storage.
 
 **Parameters:**
+
 - `metadata`: MethodMetadata - Method metadata object
 
 **Example:**
+
 ```typescript
 storage.addMethod({
   target: UserController,
@@ -635,14 +801,16 @@ storage.addMethod({
 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');
+const metadata = storage.getMethod(UserController, "findAll");
 ```
 
 ### `storage.getAllMethods()`
@@ -652,6 +820,7 @@ Returns all registered method metadata.
 **Returns:** MethodMetadata[]
 
 **Example:**
+
 ```typescript
 const allMethods = storage.getAllMethods();
 ```
@@ -661,16 +830,18 @@ const allMethods = storage.getAllMethods();
 Adds parameter metadata to storage.
 
 **Parameters:**
+
 - `metadata`: ParamMetadata - Parameter metadata object
 
 **Example:**
+
 ```typescript
 storage.addParam({
   target: UserController.prototype,
-  propertyKey: 'findById',
+  propertyKey: "findById",
   index: 0,
-  type: 'param',
-  paramName: 'id'
+  type: "param",
+  paramName: "id",
 });
 ```
 
@@ -679,14 +850,16 @@ storage.addParam({
 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');
+const params = storage.getParams(UserController.prototype, "findById");
 ```
 
 ## Interfaces
@@ -707,8 +880,13 @@ interface ApplicationOptions {
 ```typescript
 interface ClassMetadata {
   target: any;
-  type: 'injectable' | 'service' | 'controller' | 'repository' | 'auto-configuration';
-  scope?: 'singleton' | 'request' | 'transient';
+  type:
+    | "injectable"
+    | "service"
+    | "controller"
+    | "repository"
+    | "auto-configuration";
+  scope?: "singleton" | "request" | "transient";
   path?: string;
 }
 ```
@@ -732,21 +910,53 @@ interface ParamMetadata {
   target: any;
   propertyKey: string;
   index: number;
-  type: 'body' | 'param' | 'query' | 'header' | 'req' | 'res';
+  type: "body" | "param" | "query" | "header" | "req" | "res";
   paramName?: string;
 }
 ```
 
+### `Middleware`
+
+```typescript
+interface Middleware {
+  use(req: Request, res: Response, next: NextFunction): void | Promise<void>;
+}
+```
+
+### `Guard`
+
+```typescript
+interface Guard {
+  canActivate(req: Request): boolean | Promise<boolean>;
+}
+```
+
+### `Interceptor`
+
+```typescript
+interface Interceptor {
+  intercept(req: Request, res: Response, result: any): any | Promise<any>;
+}
+```
+
+### `ExceptionFilter`
+
+```typescript
+interface ExceptionFilter {
+  catch(exception: Error, req: Request, res: Response): void;
+}
+```
+
 ## Type Definitions
 
 ### `Scope`
 
 ```typescript
-type Scope = 'singleton' | 'request' | 'transient';
+type Scope = "singleton" | "request" | "transient";
 ```
 
 ### `MetadataKey`
 
 ```typescript
 type MetadataKey = (typeof METADATA_KEYS)[keyof typeof METADATA_KEYS];
-```
+```