fragment-ts 1.0.31 → 1.0.32

package/src/core/decorators/guard.decorator.ts

@@ -0,0 +1,20 @@
+import { Guard } from "../../web/interfaces";
+import { METADATA_KEYS } from "../metadata/metadata-keys";
+import { MetadataStorage } from "../metadata/metadata-storage";
+
+/**
+ * @Guard - Apply authorization/activation guard
+ */
+export function Guard(guardClass: new () => any): ClassDecorator & MethodDecorator {
+  return (target: any, propertyKey?: string | symbol) => {
+    if (propertyKey === undefined) {
+      Reflect.defineMetadata(METADATA_KEYS.USE_GUARDS, guardClass, target);
+      const storage = MetadataStorage.getInstance();
+      storage.addClassMetadata?.(target, 'guard', guardClass);
+    } else {
+      Reflect.defineMetadata(METADATA_KEYS.USE_GUARDS, guardClass, target, propertyKey);
+      const storage = MetadataStorage.getInstance();
+      storage.addMethodMetadata?.(target.constructor, propertyKey.toString(), 'guard', guardClass);
+    }
+  };
+}

package/src/core/decorators/interceptor.decorator.ts

@@ -0,0 +1,20 @@
+import { Interceptor } from "../../web/interfaces";
+import { METADATA_KEYS } from "../metadata/metadata-keys";
+import { MetadataStorage } from "../metadata/metadata-storage";
+
+/**
+ * @Interceptor - Intercept and transform request/response
+ */
+export function Interceptor(interceptorClass: new () => any): ClassDecorator & MethodDecorator {
+  return (target: any, propertyKey?: string | symbol) => {
+    if (propertyKey === undefined) {
+      Reflect.defineMetadata(METADATA_KEYS.USE_INTERCEPTORS, interceptorClass, target);
+      const storage = MetadataStorage.getInstance();
+      storage.addClassMetadata?.(target, 'interceptor', interceptorClass);
+    } else {
+      Reflect.defineMetadata(METADATA_KEYS.USE_INTERCEPTORS, interceptorClass, target, propertyKey);
+      const storage = MetadataStorage.getInstance();
+      storage.addMethodMetadata?.(target.constructor, propertyKey.toString(), 'interceptor', interceptorClass);
+    }
+  };
+}

package/src/core/decorators/middleware.decorator.ts

@@ -0,0 +1,25 @@
+import { Middleware } from "../../web/interfaces";
+import { METADATA_KEYS } from "../metadata/metadata-keys";
+import { MetadataStorage } from "../metadata/metadata-storage";
+
+/**
+ * @Middleware - Apply Express-compatible middleware at class or method level
+ * Usage:
+ *   @Middleware(AuthMiddleware) class MyController { }
+ *   @Middleware(AuthMiddleware) @Get('/') handler() { }
+ */
+export function Middleware(middlewareClass: new () => any): ClassDecorator & MethodDecorator {
+  return (target: any, propertyKey?: string | symbol) => {
+    if (propertyKey === undefined) {
+      // Class-level
+      Reflect.defineMetadata(METADATA_KEYS.USE_MIDDLEWARE, middlewareClass, target);
+      const storage = MetadataStorage.getInstance();
+      storage.addClassMetadata?.(target, 'middleware', middlewareClass);
+    } else {
+      // Method-level
+      Reflect.defineMetadata(METADATA_KEYS.USE_MIDDLEWARE, middlewareClass, target, propertyKey);
+      const storage = MetadataStorage.getInstance();
+      storage.addMethodMetadata?.(target.constructor, propertyKey.toString(), 'middleware', middlewareClass);
+    }
+  };
+}

package/src/core/metadata/metadata-keys.ts

@@ -33,6 +33,7 @@ export const METADATA_KEYS = {
   CONDITIONAL_ON_BEAN: "fragment:conditional-on-bean",
 
   // Middleware & Guards
+  USE_MIDDLEWARE: "fragment:use-middleware",
   USE_GUARDS: "fragment:use-guards",
   USE_INTERCEPTORS: "fragment:use-interceptors",
   USE_FILTERS: "fragment:use-filters",

package/src/core/metadata/metadata-storage.ts

@@ -35,6 +35,20 @@ export interface PropertyInjectionMetadata {
   metadata?: any;
 }
 
+export interface ExtendedClassMetadata extends ClassMetadata {
+  middlewares: any[];
+  guards: any[];
+  interceptors: any[];
+  exceptionFilters: any[];
+}
+
+export interface ExtendedMethodMetadata extends MethodMetadata {
+  middlewares?: any[];
+  guards?: any[];
+  interceptors?: any[];
+  exceptionFilters?: any[];
+}
+
 export class MetadataStorage {
   private static instance: MetadataStorage;
   private classes: Map<any, ClassMetadata> = new Map();
@@ -42,6 +56,8 @@ export class MetadataStorage {
   private params: Map<string, ParamMetadata[]> = new Map();
   private propertyInjections: Map<string, PropertyInjectionMetadata[]> =
     new Map();
+  private extendedClasses: Map<any, ExtendedClassMetadata> = new Map();
+  private extendedMethods: Map<string, ExtendedMethodMetadata> = new Map();
 
   static getInstance(): MetadataStorage {
     if (!MetadataStorage.instance) {
@@ -125,4 +141,102 @@ export class MetadataStorage {
 
     return injections;
   }
+
+  addClassMetadata(target: any, type: string, value: any): void {
+    let meta = this.extendedClasses.get(target);
+
+    if (!meta) {
+      const base = this.classes.get(target);
+      if (!base) {
+        // If no base ClassMetadata exists (e.g., decorator used on non-@Controller/@Service class),
+        // we cannot safely create ExtendedClassMetadata — skip or warn.
+        console.warn(
+          `⚠️ @${type} applied to ${target.name}, but it's not registered as a known component (missing @Controller, @Service, etc.). Ignoring.`,
+        );
+        return;
+      }
+
+      // Clone base and add enhancement arrays
+      meta = {
+        ...base,
+        middlewares: [],
+        guards: [],
+        interceptors: [],
+        exceptionFilters: [],
+      };
+    }
+
+    switch (type) {
+      case "middleware":
+        meta.middlewares.push(value);
+        break;
+      case "guard":
+        meta.guards.push(value);
+        break;
+      case "interceptor":
+        meta.interceptors.push(value);
+        break;
+      case "exceptionFilter":
+        meta.exceptionFilters.push(value);
+        break;
+      default:
+        console.warn(`Unknown metadata type: ${type}`);
+        return;
+    }
+
+    this.extendedClasses.set(target, meta);
+  }
+
+  addMethodMetadata(
+    target: any,
+    propertyKey: string,
+    type: string,
+    value: any,
+  ): void {
+    const key = `${target.name}.${propertyKey}`;
+    let meta = this.extendedMethods.get(key);
+    if (!meta) {
+      const base = this.methods.get(key);
+      meta = {
+        ...(base || {
+          target,
+          propertyKey,
+          method: "",
+          path: "",
+          paramMetadata: [],
+        }),
+        middlewares: [],
+        guards: [],
+        interceptors: [],
+        exceptionFilters: [],
+      };
+    }
+    switch (type) {
+      case "middleware":
+        meta.middlewares!.push(value);
+        break;
+      case "guard":
+        meta.guards!.push(value);
+        break;
+      case "interceptor":
+        meta.interceptors!.push(value);
+        break;
+      case "exceptionFilter":
+        meta.exceptionFilters!.push(value);
+        break;
+    }
+    this.extendedMethods.set(key, meta);
+  }
+
+  getExtendedClass(target: any): ExtendedClassMetadata | undefined {
+    return this.extendedClasses.get(target);
+  }
+
+  getExtendedMethod(
+    target: any,
+    propertyKey: string,
+  ): ExtendedMethodMetadata | undefined {
+    const key = `${target.name}.${propertyKey}`;
+    return this.extendedMethods.get(key);
+  }
 }

package/src/web/application.ts

@@ -9,6 +9,16 @@ import { MetadataStorage } from "../core/metadata/metadata-storage";
 import { METADATA_KEYS } from "../core/metadata/metadata-keys";
 import { ComponentScanner } from "../core/scanner/component-scanner";
 import { TypeORMModule } from "../typeorm/typeorm-module";
+import {
+  MiddlewareClass,
+  GuardClass,
+  InterceptorClass,
+  ExceptionFilterClass,
+  Middleware,
+  Guard,
+  Interceptor,
+  ExceptionFilter,
+} from "./interfaces";
 
 export class FragmentWebApplication {
   private app: Express;
@@ -286,6 +296,27 @@ export class FragmentWebApplication {
         const controller = this.container.resolve(controllerMetadata.target);
         const basePath = controllerMetadata.path || "";
 
+        // Get controller-level enhancements
+        const controllerMiddlewares = (Reflect.getMetadata(
+          METADATA_KEYS.USE_MIDDLEWARE,
+          controllerMetadata.target,
+        ) || []) as MiddlewareClass[];
+
+        const controllerGuards = (Reflect.getMetadata(
+          METADATA_KEYS.USE_GUARDS,
+          controllerMetadata.target,
+        ) || []) as GuardClass[];
+
+        const controllerInterceptors = (Reflect.getMetadata(
+          METADATA_KEYS.USE_INTERCEPTORS,
+          controllerMetadata.target,
+        ) || []) as InterceptorClass[];
+
+        const controllerFilters = (Reflect.getMetadata(
+          METADATA_KEYS.USE_FILTERS,
+          controllerMetadata.target,
+        ) || []) as ExceptionFilterClass[];
+
         const methods = this.metadataStorage
           .getAllMethods()
           .filter((m) => m.target === controllerMetadata.target);
@@ -307,10 +338,78 @@ export class FragmentWebApplication {
 
           totalRoutes++;
 
+          // Collect method-level enhancements
+          const methodMiddlewares = (Reflect.getMetadata(
+            METADATA_KEYS.USE_MIDDLEWARE,
+            controllerMetadata.target.prototype,
+            methodMetadata.propertyKey,
+          ) || []) as MiddlewareClass[];
+
+          const methodGuards = (Reflect.getMetadata(
+            METADATA_KEYS.USE_GUARDS,
+            controllerMetadata.target.prototype,
+            methodMetadata.propertyKey,
+          ) || []) as GuardClass[];
+
+          const methodInterceptors = (Reflect.getMetadata(
+            METADATA_KEYS.USE_INTERCEPTORS,
+            controllerMetadata.target.prototype,
+            methodMetadata.propertyKey,
+          ) || []) as InterceptorClass[];
+
+          const methodFilters = (Reflect.getMetadata(
+            METADATA_KEYS.USE_FILTERS,
+            controllerMetadata.target.prototype,
+            methodMetadata.propertyKey,
+          ) || []) as ExceptionFilterClass[];
+
+          // Combine: controller + method
+          const allMiddlewares = [
+            ...controllerMiddlewares,
+            ...methodMiddlewares,
+          ];
+          const allGuards = [...controllerGuards, ...methodGuards];
+          const allInterceptors = [
+            ...controllerInterceptors,
+            ...methodInterceptors,
+          ];
+          const allFilters = [...controllerFilters, ...methodFilters];
+
+          // Resolve via DI container
+          const resolvedMiddlewares = allMiddlewares.map(
+            (M) => this.container.resolve(M) as Middleware,
+          );
+          const resolvedGuards = allGuards.map(
+            (G) => this.container.resolve(G) as Guard,
+          );
+          const resolvedInterceptors = allInterceptors.map(
+            (I) => this.container.resolve(I) as Interceptor,
+          );
+
+          // Build Express route handler with pipeline
           (this.app as any)[httpMethod](
             fullPath,
+            // Middleware stack (Express-compatible)
+            ...resolvedMiddlewares.map(
+              (mw) => (req: Request, res: Response, next: NextFunction) =>
+                Promise.resolve(mw.use(req, res, next)).catch(next),
+            ),
+            // Final unified handler
             async (req: Request, res: Response, next: NextFunction) => {
               try {
+                // ➤ Step 1: Guards
+                for (const guard of resolvedGuards) {
+                  const canActivate = await Promise.resolve(
+                    guard.canActivate(req),
+                  );
+                  if (!canActivate) {
+                    const error = new Error("Forbidden");
+                    (error as any).status = 403;
+                    throw error;
+                  }
+                }
+
+                // ➤ Step 2: Resolve parameters
                 const args = this.resolveMethodParameters(
                   methodMetadata,
                   req,
@@ -320,18 +419,54 @@ export class FragmentWebApplication {
                 console.log(
                   `\n🔍 Handling ${httpMethod.toUpperCase()} ${fullPath}`,
                 );
-                // console.log(`  Parameters:`, args);
 
-                const result = await (controller as any)[
-                  methodMetadata.propertyKey
-                ](...args);
+                // ➤ Step 3: Interceptors (wrap handler)
+                let result: any;
+                if (resolvedInterceptors.length > 0) {
+                  // First, call the real handler
+                  const rawResult = await (controller as any)[
+                    methodMetadata.propertyKey
+                  ](...args);
+
+                  // Then pass result through interceptors in reverse order (or forward — your choice)
+                  result = rawResult;
+                  for (const interceptor of resolvedInterceptors) {
+                    // Allow interceptor to transform the result
+                    result = await Promise.resolve(
+                      interceptor.intercept(req, res, result),
+                    );
+                  }
+                } else {
+                  result = await (controller as any)[
+                    methodMetadata.propertyKey
+                  ](...args);
+                }
 
+                // ➤ Step 4: Send response
                 if (!res.headersSent) {
                   res.json(result);
                 }
               } catch (error) {
-                console.error(`❌ Error handling route ${fullPath}:`, error);
-                next(error);
+                // ➤ Step 5: Exception Filters (method + controller level)
+                let handled = false;
+                for (const FilterClass of allFilters) {
+                  const filter = this.container.resolve(
+                    FilterClass,
+                  ) as ExceptionFilter;
+                  try {
+                    const err =
+                      error instanceof Error ? error : new Error(String(error));
+                    filter.catch(err, req, res);
+                    handled = true;
+                    break;
+                  } catch (e) {
+                    console.error(`❌ Exception filter failed:`, e);
+                  }
+                }
+
+                if (!handled) {
+                  next(error);
+                }
               }
             },
           );

package/src/web/interfaces.ts

@@ -1,4 +1,4 @@
-import { Request, Response, NextFunction } from 'express';
+import { Request, Response, NextFunction } from "express";
 
 export interface Middleware {
   use(req: Request, res: Response, next: NextFunction): void | Promise<void>;
@@ -9,9 +9,18 @@ export interface Guard {
 }
 
 export interface Interceptor {
-  intercept(req: Request, res: Response, next: NextFunction): void | Promise<void>;
+  intercept(
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ): void | Promise<void>;
 }
 
 export interface ExceptionFilter {
   catch(exception: Error, req: Request, res: Response): void;
 }
+
+export type MiddlewareClass = new () => Middleware;
+export type GuardClass = new () => Guard;
+export type InterceptorClass = new () => Interceptor;
+export type ExceptionFilterClass = new () => ExceptionFilter;