TypeScript Decorators

Also Known As

TL;DR

Explanation

TypeScript decorators (TC39 Stage 3 in 2024) annotate classes and members with @Decorator syntax. Class decorators modify or replace the class. Method decorators wrap methods. Property decorators define metadata on properties. Parameter decorators annotate constructor/method parameters. Decorator metadata: reflect-metadata stores type information accessed at runtime, enabling dependency injection (NestJS @Injectable), ORM mapping (TypeORM @Entity, @Column), and validation (class-validator @IsEmail). TypeScript 5.0 implements the TC39 decorator proposal; legacy decorators (experimentalDecorators) differ.

Common Misconception

Why It Matters

Common Mistakes

• Not enabling emitDecoratorMetadata and experimentalDecorators in tsconfig for legacy decorators.
• Forgetting to import reflect-metadata at the entry point for metadata decorators.
• Using legacy decorators (experimentalDecorators) with TS 5.0 new decorators — they are incompatible.
• Decorators that have side effects during class definition — decorators run at class definition time, not instantiation.

Code Examples

// Manual DI wiring without decorators — verbose:
const userService = new UserService(new UserRepository(new Database()));
const orderService = new OrderService(userService, new OrderRepository(new Database()));
// Every constructor dependency must be manually wired

// NestJS decorators — declarative DI:
@Injectable()
export class UserService {
    constructor(private readonly userRepo: UserRepository) {}
}

@Entity('users')
export class User {
    @PrimaryGeneratedColumn()
    id: number;

    @Column({ unique: true })
    @IsEmail()
    email: string;
}

@Controller('users')
export class UserController {
    constructor(private readonly userService: UserService) {}

    @Get(':id')
    findOne(@Param('id') id: number): Promise<User> {
        return this.userService.findById(id);
    }
}

References

• ↗ https://www.typescriptlang.org/docs/handbook/decorators.html

Tags

Related Terms