Introduction

TypeScript decorators are a powerful feature that allows developers to modify or annotate classes, methods, properties, and parameters at design time. While decorators are still an experimental feature in TypeScript (as of version 5.x), they provide a clean and declarative way to extend functionality, implement cross-cutting concerns, and enforce patterns like dependency injection, logging, and validation.

In this post, we'll explore how TypeScript decorators work, when to use them, and practical examples that demonstrate their capabilities. Whether you're working with frameworks like Angular or NestJS—or just want to write cleaner, more maintainable code—understanding decorators will level up your TypeScript skills.

---

What Are TypeScript Decorators?

Decorators are special functions prefixed with the @ symbol that can be applied to classes, methods, accessors, properties, or parameters. They are evaluated at runtime but executed during class declaration, allowing you to modify or extend the behavior of the target.

TypeScript implements decorators based on the ECMAScript decorators proposal, though with some differences. To enable decorators in your project, ensure experimentalDecorators is set to true in your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Types of Decorators

1. Class Decorators – Applied to class constructors.
2. Method Decorators – Applied to class methods.
3. Property Decorators – Applied to class properties.
4. Parameter Decorators – Applied to function parameters.

---

Practical Examples of Decorators

1. Logging with Method Decorators

A common use case for decorators is logging method calls for debugging or analytics. Here’s a simple @Log decorator that logs method invocations:

function Log(target: any, key: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function (...args: any[]) {
    console.log(`Calling ${key} with args:`, args);
    const result = originalMethod.apply(this, args);
    console.log(`Method ${key} returned:`, result);
    return result;
  };

  return descriptor;
}

class Calculator {
  @Log
  add(a: number, b: number): number {
    return a + b;
  }
}

const calc = new Calculator();
calc.add(2, 3); // Logs method call and return value

This decorator wraps the original method, adding logging before and after execution.

2. Validation with Property Decorators

Decorators can enforce constraints on properties. Below, @MaxLength validates a string property’s length:

function MaxLength(max: number) {
  return function (target: any, key: string) {
    let value: string;

    const getter = () => value;
    const setter = (newVal: string) => {
      if (newVal.length > max) {
        throw new Error(`${key} must not exceed ${max} characters.`);
      }
      value = newVal;
    };

    Object.defineProperty(target, key, {
      get: getter,
      set: setter,
      enumerable: true,
      configurable: true,
    });
  };
}

class User {
  @MaxLength(20)
  username: string;

  constructor(username: string) {
    this.username = username;
  }
}

const user = new User("valid_username"); // Works
const invalidUser = new User("this_username_is_way_too_long"); // Throws error

---

When Should You Use Decorators?

Decorators shine in scenarios where you need to:

• Add cross-cutting concerns (logging, caching, error handling).
• Enforce validation rules (property constraints, method preconditions).
• Simplify dependency injection (used in frameworks like Angular/NestJS).
• Implement AOP (Aspect-Oriented Programming) by separating concerns like authorization or performance tracking.

However, avoid overusing decorators for simple logic that could be written plainly. Decorators introduce abstraction, which can make debugging harder if misused.

---

Limitations and Best Practices

Limitations

1. Experimental Feature: Decorators may evolve as the TC39 proposal progresses.
2. Performance Overhead: Excessive decorators can impact runtime performance.
3. Debugging Complexity: Decorators modify behavior implicitly, which can be tricky to debug.

Best Practices

• Keep Decorators Simple: Focus on single responsibilities (e.g., logging only).
• Document Behavior: Clearly comment decorators to explain their purpose.
• Test Thoroughly: Ensure decorated methods/properties behave as expected.

---

Conclusion

TypeScript decorators offer a powerful way to enhance classes and methods with reusable, declarative logic. While they’re not yet a finalized JavaScript feature, their utility in frameworks and large-scale applications makes them worth learning. By applying decorators judiciously—for logging, validation, or DI—you can write cleaner, more maintainable code.

Experiment with decorators in your projects, but always weigh their benefits against potential complexity. As the ECMAScript proposal matures, decorators will likely become an even more integral part of the TypeScript ecosystem.