Deep Dive into NestJS Decorators: Internals, Usage, and Custom Implementations

// Decorator factory - returns the actual decorator function
function Log() {
    // The actual decorator function
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        const originalMethod = descriptor.value;

        // Replace the original method with a new one that includes logging
        descriptor.value = function (...args: any[]) {
            console.log(`Calling ${propertyKey} with`, args);
            return originalMethod.apply(this, args);
        };
    };
}

class User {
    @Log()
    getUser(name: string) {
        return `User: ${name}`;
    }
}

const user = new User();
user.getUser("Tejas"); // Logs: "Calling getUser with ["Tejas"]" then returns "User: Tejas"

// Simplified compiled output
var User = (function () {
    function User() {}

    // Original method
    User.prototype.getUser = function (name) {
        return "User: " + name;
    };

    // Apply decorator
    User.prototype.getUser = (function (originalMethod) {
        return function (...args) {
            console.log("Calling getUser with", args);
            return originalMethod.apply(this, args);
        };
    })(User.prototype.getUser);

    return User;
})();

import "reflect-metadata"; // Must be imported once at the application entry point

// Create a metadata key
const META_KEY = "role";

// Decorator factory
function Role(role: string) {
    // The actual decorator
    return function (target: Object, key?: string | symbol) {
        // Store metadata on the target
        Reflect.defineMetadata(META_KEY, role, target, key);
    };
}

class User {
    @Role("admin")
    accessDashboard() {
        // Method implementation
    }
}

// Later, retrieve the metadata
const user = new User();
const role = Reflect.getMetadata(META_KEY, User.prototype, "accessDashboard");
console.log(role); // Output: 'admin'

   @Controller("users")
   export class UserController {
    // Controller methods
   }

   // Simplified version of what NestJS does internally
   function Controller(prefix?: string): ClassDecorator {
    return (target: object) => {
        Reflect.defineMetadata("path", prefix || "", target);
        Reflect.defineMetadata("__isController", true, target);
    };
   }

   // Conceptual example of what happens internally
   const isController = Reflect.getMetadata("__isController", UserController);
   if (isController) {
    const path = Reflect.getMetadata("path", UserController);
    // Register the controller with the path 'users'
   }

// Your code
@Injectable()
export class UserService {
    constructor(private databaseService: DatabaseService) {}
}

// What NestJS does internally (simplified)
function Injectable(): ClassDecorator {
    return (target: object) => {
        Reflect.defineMetadata("__injectable", true, target);

        // Get parameter types from TypeScript
        const types = Reflect.getMetadata("design:paramtypes", target) || [];

        // Store dependency types for later injection
        Reflect.defineMetadata("__paramtypes", types, target);
    };
}

// During application startup, NestJS creates instances
const paramTypes = Reflect.getMetadata("__paramtypes", UserService);
// paramTypes would be [DatabaseService]

// NestJS would then:
// 1. Create/find an instance of DatabaseService
// 2. Create UserService passing in the DatabaseService instance
const databaseService = container.get(DatabaseService);
const userService = new UserService(databaseService);

import { SetMetadata } from "@nestjs/common";

// NestJS provides SetMetadata to make decorator creation easier
export const Permissions = (...permissions: string[]) => SetMetadata("permissions", permissions);

import { Controller, Get } from "@nestjs/common";
import { Permissions } from "./permissions.decorator";

@Controller("users")
export class UserController {
    @Get()
    @Permissions("read:users", "write:users")
    getUsers() {
        return "Users List";
    }
}

import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";
import { Reflector } from "@nestjs/core";

@Injectable()
export class PermissionsGuard implements CanActivate {
    constructor(private reflector: Reflector) {}

    canActivate(context: ExecutionContext): boolean {
        // Get the permissions required for this endpoint
        const requiredPermissions = this.reflector.get<string[]>("permissions", context.getHandler());

        if (!requiredPermissions) {
            return true; // No permissions required
        }

        const request = context.switchToHttp().getRequest();
        const user = request.user;

        // Check if user has all required permissions
        return requiredPermissions.every((permission) => user?.permissions?.includes(permission));
    }
}

import { createParamDecorator, ExecutionContext } from "@nestjs/common";

// Create a decorator that extracts a specific user property
export const UserProperty = createParamDecorator((data: string, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user;

    // data is the property name passed to the decorator
    return data ? user?.[data] : user;
});

// Usage in a controller
@Controller("users")
export class UserController {
    @Get("profile")
    getProfile(@UserProperty("id") userId: string) {
        return `User ID: ${userId}`;
    }
}

import { applyDecorators, Get, UseGuards } from "@nestjs/common";
import { PermissionsGuard } from "./permissions.guard";
import { Permissions } from "./permissions.decorator";

// Create a combined decorator
export function SecureEndpoint(path: string, ...permissions: string[]) {
    return applyDecorators(Get(path), Permissions(...permissions), UseGuards(PermissionsGuard));
}

// Usage
@Controller("users")
export class UserController {
    @SecureEndpoint("admin", "read:users", "manage:users")
    getAdminDashboard() {
        return "Admin Dashboard";
    }
}

// This might not work as expected
@Controller("users")
class UserController {}

@Controller("users")
export class UserController {}

// This might produce unexpected results
@UseGuards(AuthGuard)
@Permissions('admin')
@Get()
method() {}

@Get()
@Permissions('admin')
@UseGuards(AuthGuard)
method() {}

// At your application entry point
import "reflect-metadata";

console.log(Reflect.getMetadataKeys(target));
console.log(Reflect.getMetadata("key", target));

  // Instead of this in a hot path
  const permissions = this.reflector.get('permissions', handler);

  // Do this
  private readonly handlerPermissionsMap = new Map();

  getPermissions(handler) {
    if (!this.handlerPermissionsMap.has(handler)) {
      const permissions = this.reflector.get('permissions', handler);
      this.handlerPermissionsMap.set(handler, permissions);
    }
    return this.handlerPermissionsMap.get(handler);
  }

  function ExpensiveOperation() {
    let result;
    return (target, key, descriptor) => {
      const original = descriptor.value;
      descriptor.value = function(...args) {
        // Only calculate once
        if (!result) {
          result = /* expensive calculation */;
        }
        return original.apply(this, [...args, result]);
      };
    };
  }