Controller Decorators

/**
 * Marks a class as a controller with the specified route path
 * @param path - Base path for all routes in this controller
 * @param middleware - Optional middleware to apply to all routes in this controller
 */
function controller(path: string, ...middleware: Middleware[]): ClassDecorator;

import { controller, httpGet, BaseHttpController } from "inversify-express-utils";

@controller("/users")
class UserController extends BaseHttpController {
  // Routes will be prefixed with /users
}

@controller("/api/products", authMiddleware, loggingMiddleware)
class ProductController extends BaseHttpController {
  // Routes prefixed with /api/products and protected by middleware
}

/**
 * Defines a GET endpoint
 * @param path - Route path relative to controller
 * @param middleware - Optional middleware for this specific route
 */
function httpGet(path: string, ...middleware: Middleware[]): MethodDecorator;

/**
 * Defines a POST endpoint
 * @param path - Route path relative to controller
 * @param middleware - Optional middleware for this specific route
 */
function httpPost(path: string, ...middleware: Middleware[]): MethodDecorator;

/**
 * Defines a PUT endpoint
 * @param path - Route path relative to controller
 * @param middleware - Optional middleware for this specific route
 */
function httpPut(path: string, ...middleware: Middleware[]): MethodDecorator;

/**
 * Defines a PATCH endpoint
 * @param path - Route path relative to controller
 * @param middleware - Optional middleware for this specific route
 */
function httpPatch(path: string, ...middleware: Middleware[]): MethodDecorator;

/**
 * Defines a DELETE endpoint
 * @param path - Route path relative to controller
 * @param middleware - Optional middleware for this specific route
 */
function httpDelete(path: string, ...middleware: Middleware[]): MethodDecorator;

/**
 * Defines a HEAD endpoint
 * @param path - Route path relative to controller
 * @param middleware - Optional middleware for this specific route
 */
function httpHead(path: string, ...middleware: Middleware[]): MethodDecorator;

/**
 * Defines an OPTIONS endpoint
 * @param path - Route path relative to controller
 * @param middleware - Optional middleware for this specific route
 */
function httpOptions(path: string, ...middleware: Middleware[]): MethodDecorator;

/**
 * Defines an endpoint that responds to all HTTP methods
 * @param path - Route path relative to controller
 * @param middleware - Optional middleware for this specific route
 */
function all(path: string, ...middleware: Middleware[]): MethodDecorator;

/**
 * Generic HTTP method decorator
 * @param method - HTTP verb enum value
 * @param path - Route path relative to controller
 * @param middleware - Optional middleware for this specific route
 */
function httpMethod(
  method: HTTP_VERBS_ENUM,
  path: string,
  ...middleware: Middleware[]
): MethodDecorator;

@controller("/users")
class UserController extends BaseHttpController {
  @httpGet("/:id")
  getUser(@requestParam("id") id: string) {
    return this.ok({ id, name: "John Doe" });
  }

  @httpPost("/", validationMiddleware)
  createUser(@requestBody() userData: any) {
    return this.created("/users/123", userData);
  }

  @httpPut("/:id")
  updateUser(@requestParam("id") id: string, @requestBody() userData: any) {
    return this.ok({ id, ...userData });
  }

  @httpDelete("/:id", adminOnlyMiddleware)
  deleteUser(@requestParam("id") id: string) {
    return this.ok();
  }
}

/**
 * Injects the entire Express request object
 */
function request(): ParameterDecorator;

/**
 * Injects the entire Express response object
 */
function response(): ParameterDecorator;

/**
 * Injects Express next function
 */
function next(): ParameterDecorator;

/**
 * Injects route parameters
 * @param paramName - Specific parameter name to extract, or omit for all params
 */
function requestParam(paramName?: string): ParameterDecorator;

/**
 * Injects query string parameters
 * @param queryParamName - Specific query parameter name to extract, or omit for all query params
 */
function queryParam(queryParamName?: string): ParameterDecorator;

/**
 * Injects the request body
 */
function requestBody(): ParameterDecorator;

/**
 * Injects request headers
 * @param headerName - Specific header name to extract, or omit for all headers
 */
function requestHeaders(headerName?: string): ParameterDecorator;

/**
 * Injects cookies
 * @param cookieName - Specific cookie name to extract, or omit for all cookies
 */
function cookies(cookieName?: string): ParameterDecorator;

/**
 * Injects the authenticated user principal
 */
function principal(): ParameterDecorator;

/**
 * Generic parameter decorator factory
 * @param type - Parameter type enum value
 * @param parameterName - Optional parameter name
 */
function params(type: PARAMETER_TYPE, parameterName?: string | symbol): ParameterDecorator;

@controller("/users")
class UserController extends BaseHttpController {
  @httpGet("/:id")
  getUser(
    @requestParam("id") userId: string,
    @queryParam("include") include: string,
    @requestHeaders("authorization") auth: string
  ) {
    return this.ok({ userId, include, isAuthenticated: !!auth });
  }

  @httpPost("/")
  createUser(
    @requestBody() userData: CreateUserDto,
    @principal() user: Principal,
    @request() req: Request
  ) {
    console.log("Creating user:", userData);
    console.log("Current user:", user.details);
    return this.created(`/users/${Date.now()}`, userData);
  }

  @httpGet("/")
  getUsers(
    @queryParam() query: any,
    @requestHeaders() headers: any,
    @cookies("session") sessionId: string
  ) {
    return this.ok({ 
      filters: query, 
      userAgent: headers["user-agent"],
      session: sessionId 
    });
  }
}

/**
 * Applies middleware to a controller class or method
 * @param middleware - Middleware functions or service identifiers to apply
 */
function withMiddleware(...middleware: Middleware[]): ClassDecorator | MethodDecorator;

@controller("/admin")
@withMiddleware(authMiddleware, adminMiddleware)
class AdminController extends BaseHttpController {
  @httpGet("/users")
  @withMiddleware(cacheMiddleware)
  getUsers() {
    return this.ok(["user1", "user2"]);
  }
}

/**
 * Injects HTTP context into controller properties or method parameters
 */
const injectHttpContext: <T = unknown>(
  target: DecoratorTarget,
  targetKey?: string | symbol,
  indexOrPropertyDescriptor?: number | TypedPropertyDescriptor<T>
) => void;

@controller("/context")
class ContextController {
  @injectHttpContext 
  private httpContext: HttpContext;

  @httpGet("/info")
  getContextInfo() {
    return {
      hasContainer: !!this.httpContext.container,
      userAuthenticated: this.httpContext.user.isAuthenticated(),
      requestPath: this.httpContext.request.path
    };
  }
}

type HandlerDecorator = (
  target: DecoratorTarget,
  key: string,
  value: unknown
) => void;

type DecoratorTarget<T = unknown> = ConstructorFunction<T> | Prototype<T>;

type Middleware = interfaces.ServiceIdentifier | RequestHandler;