Decorators

The 150 Endpoints That Needed Logging

Tuesday morning standup. Product manager: "We need request logging on all API endpoints. For debugging and analytics."

I looked at our codebase: 150 REST API endpoints across 23 controllers. Manual logging would mean:

// Before - Manual logging everywhere
class UserController {
  async getUser(id: string) {
    console.log(`[${new Date().toISOString()}] GET /users/${id}`);
    const startTime = Date.now();
    
    try {
      const user = await this.userService.findById(id);
      console.log(`[${new Date().toISOString()}] GET /users/${id} - ${Date.now() - startTime}ms`);
      return user;
    } catch (error) {
      console.error(`[${new Date().toISOString()}] GET /users/${id} - ERROR:`, error);
      throw error;
    }
  }
  
  // ... repeat for 149 more endpoints!
}

Estimated time: 2 weeks of tedious copy-paste. High risk of inconsistency and bugs.

Then I discovered decorators:

function Log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  
  descriptor.value = async function(...args: any[]) {
    const timestamp = new Date().toISOString();
    console.log(`[${timestamp}] ${propertyKey}(${JSON.stringify(args)})`);
    const startTime = Date.now();
    
    try {
      const result = await originalMethod.apply(this, args);
      console.log(`[${timestamp}] ${propertyKey} - ${Date.now() - startTime}ms`);
      return result;
    } catch (error) {
      console.error(`[${timestamp}] ${propertyKey} - ERROR:`, error);
      throw error;
    }
  };
  
  return descriptor;
}

// After - One decorator, all endpoints logged
class UserController {
  @Log
  async getUser(id: string) {
    return this.userService.findById(id);
  }
  
  @Log
  async createUser(data: CreateUserDto) {
    return this.userService.create(data);
  }
  
  @Log
  async updateUser(id: string, data: UpdateUserDto) {
    return this.userService.update(id, data);
  }
}

Result: Added logging to 150 endpoints in 3 hours. Consistent. Maintainable. DRY.

This article covers TypeScript decorators - the meta-programming feature that saves you from repetitive boilerplate.

Enabling Decorators

Decorators are experimental. Enable in tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

Class Decorators

Modify or replace class definitions.

Basic Class Decorator

function Injectable(constructor: Function) {
  console.log(`Injecting: ${constructor.name}`);
}

@Injectable
class UserService {
  getUser(id: string) {
    return { id, name: 'John' };
  }
}
// Output: "Injecting: UserService"

Adding Properties

function Timestamped<T extends { new(...args: any[]): {} }>(constructor: T) {
  return class extends constructor {
    createdAt = new Date();
  };
}

@Timestamped
class User {
  constructor(public name: string) {}
}

const user = new User('John');
console.log((user as any).createdAt);  // Current date

Sealed Class

function Sealed(constructor: Function) {
  Object.seal(constructor);
  Object.seal(constructor.prototype);
}

@Sealed
class ImmutableService {
  getData() {
    return 'data';
  }
}

Method Decorators

Modify method behavior.

Basic Method Decorator

function Log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  
  descriptor.value = function(...args: any[]) {
    console.log(`Calling ${propertyKey} with:`, args);
    const result = originalMethod.apply(this, args);
    console.log(`Result:`, result);
    return result;
  };
  
  return descriptor;
}

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

const calc = new Calculator();
calc.add(5, 3);
// Output:
// Calling add with: [5, 3]
// Result: 8

Measure Performance

function Measure(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  
  descriptor.value = async function(...args: any[]) {
    const start = Date.now();
    const result = await originalMethod.apply(this, args);
    const duration = Date.now() - start;
    console.log(`${propertyKey} took ${duration}ms`);
    return result;
  };
  
  return descriptor;
}

class DataService {
  @Measure
  async fetchData(): Promise<string[]> {
    await new Promise(resolve => setTimeout(resolve, 100));
    return ['data1', 'data2'];
  }
}

Memoization Decorator

function Memoize(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  const cache = new Map<string, any>();
  
  descriptor.value = function(...args: any[]) {
    const key = JSON.stringify(args);
    
    if (cache.has(key)) {
      console.log(`Cache hit for ${propertyKey}`);
      return cache.get(key);
    }
    
    const result = originalMethod.apply(this, args);
    cache.set(key, result);
    return result;
  };
  
  return descriptor;
}

class ExpensiveCalculator {
  @Memoize
  fibonacci(n: number): number {
    if (n <= 1) return n;
    return this.fibonacci(n - 1) + this.fibonacci(n - 2);
  }
}

Property Decorators

Modify property definitions.

Basic Property Decorator

function Min(min: number) {
  return function(target: any, propertyKey: string) {
    let value: number;
    
    const getter = function() {
      return value;
    };
    
    const setter = function(newValue: number) {
      if (newValue < min) {
        throw new Error(`${propertyKey} must be at least ${min}`);
      }
      value = newValue;
    };
    
    Object.defineProperty(target, propertyKey, {
      get: getter,
      set: setter,
      enumerable: true,
      configurable: true
    });
  };
}

class Product {
  @Min(0)
  price: number = 0;
  
  @Min(0)
  stock: number = 0;
}

const product = new Product();
product.price = 99;  // OK
// product.price = -10;  // Throws: price must be at least 0

Parameter Decorators

Mark parameters for special handling.

Basic Parameter Decorator

function Required(target: any, propertyKey: string, parameterIndex: number) {
  console.log(`Parameter ${parameterIndex} of ${propertyKey} is required`);
}

class UserService {
  createUser(@Required name: string, @Required email: string) {
    return { name, email };
  }
}
// Metadata registration - often used with DI frameworks

Decorator Factories

Create decorators with custom parameters.

Parameterized Decorator

function MinLength(length: number) {
  return function(target: any, propertyKey: string) {
    let value: string;
    
    Object.defineProperty(target, propertyKey, {
      get: () => value,
      set: (newValue: string) => {
        if (newValue.length < length) {
          throw new Error(`${propertyKey} must be at least ${length} characters`);
        }
        value = newValue;
      }
    });
  };
}

class User {
  @MinLength(3)
  username: string = '';
  
  @MinLength(8)
  password: string = '';
}

Retry Decorator

function Retry(times: number) {
  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    
    descriptor.value = async function(...args: any[]) {
      for (let i = 0; i < times; i++) {
        try {
          return await originalMethod.apply(this, args);
        } catch (error) {
          if (i === times - 1) throw error;
          console.log(`Retry ${i + 1}/${times} for ${propertyKey}`);
        }
      }
    };
    
    return descriptor;
  };
}

class ApiService {
  @Retry(3)
  async fetchData(url: string): Promise<any> {
    const response = await fetch(url);
    if (!response.ok) throw new Error('Failed to fetch');
    return response.json();
  }
}

Decorator Composition

Multiple decorators on one target.

Execution Order

function First() {
  console.log('First(): factory');
  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    console.log('First(): decorator');
  };
}

function Second() {
  console.log('Second(): factory');
  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    console.log('Second(): decorator');
  };
}

class Example {
  @First()
  @Second()
  method() {}
}
// Output:
// First(): factory
// Second(): factory
// Second(): decorator
// First(): decorator

Execution order:

Factories: top to bottom
Decorators: bottom to top

Real-World Patterns

1. Authorization Decorator

function RequireAuth(roles: string[]) {
  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    
    descriptor.value = function(req: any, ...args: any[]) {
      if (!req.user) {
        throw new Error('Unauthorized');
      }
      
      if (!roles.some(role => req.user.roles.includes(role))) {
        throw new Error('Forbidden');
      }
      
      return originalMethod.apply(this, [req, ...args]);
    };
    
    return descriptor;
  };
}

class AdminController {
  @RequireAuth(['admin'])
  deleteUser(req: Request, userId: string) {
    // Only admins can execute
  }
  
  @RequireAuth(['admin', 'moderator'])
  banUser(req: Request, userId: string) {
    // Admins or moderators can execute
  }
}

2. Validation Decorator

function Validate(schema: any) {
  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    
    descriptor.value = function(...args: any[]) {
      const [data] = args;
      
      // Simple validation (use Joi/Zod in real apps)
      if (!schema.validate(data)) {
        throw new Error('Validation failed');
      }
      
      return originalMethod.apply(this, args);
    };
    
    return descriptor;
  };
}

class UserService {
  @Validate({ 
    email: (v: string) => v.includes('@'),
    age: (v: number) => v >= 18
  })
  createUser(data: { email: string; age: number }) {
    // Data is validated
  }
}

3. Caching Decorator

function Cache(ttl: number) {
  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;
    const cache = new Map<string, { value: any; expiry: number }>();
    
    descriptor.value = async function(...args: any[]) {
      const key = JSON.stringify(args);
      const cached = cache.get(key);
      
      if (cached && Date.now() < cached.expiry) {
        console.log(`Cache hit: ${propertyKey}`);
        return cached.value;
      }
      
      const result = await originalMethod.apply(this, args);
      cache.set(key, {
        value: result,
        expiry: Date.now() + ttl
      });
      
      return result;
    };
    
    return descriptor;
  };
}

class DataService {
  @Cache(60000)  // Cache for 1 minute
  async getUserData(userId: string) {
    // Expensive operation
    return await database.find(userId);
  }
}

Common Mistakes

1. Forgetting to Enable

// tsconfig.json - Missing this causes errors
{
  "experimentalDecorators": true
}

2. Arrow Function Methods

class Example {
  @Log
  method = () => {  // ✗ Decorators don't work on arrow functions
    // ...
  }
}

// Use regular methods
class Example {
  @Log
  method() {  // ✓ Works
    // ...
  }
}

3. Not Returning Descriptor

function BadDecorator(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  descriptor.value = function() {
    // Modified
  };
  // ✗ Forgot to return descriptor!
}

function GoodDecorator(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  descriptor.value = function() {
    // Modified
  };
  return descriptor;  // ✓ Return it
}

Your Challenge

Build a request timing and logging system with decorators:

// TODO: Create decorators for:

// 1. @Timing - measure method execution time
// 2. @Log - log method calls with arguments
// 3. @Cache - cache method results
// 4. @Retry - retry on failure
// 5. @RateLimit - limit call frequency

// Apply to this API controller:

class ApiController {
  @Timing
  @Log
  @Cache(30000)
  @Retry(3)
  async getUser(id: string) {
    // Implementation
  }
  
  @Timing
  @RateLimit(10, 60000)  // 10 calls per minute
  async createUser(data: any) {
    // Implementation
  }
}

// Requirements:
// 1. Composable decorators
// 2. Async-aware
// 3. Proper error handling
// 4. Type-safe
// 5. Configurable via parameters

Key Takeaways

Decorators - meta-programming for classes and methods
Enable in tsconfig - experimentalDecorators: true
Method decorators - modify behavior without changing code
Decorator factories - parameterized decorators
Composition - stack multiple decorators
Real use cases - logging, caching, auth, validation
Execution order - bottom to top
Return descriptor - don't forget!

What I Learned

Adding logging to 150 endpoints manually would have taken 2 weeks. Error-prone. Inconsistent. Unmaintainable.

One decorator took 3 hours:

@Log
async getUser(id: string) {
  return this.userService.findById(id);
}

Decorators turn cross-cutting concerns (logging, auth, validation, caching) into reusable, composable annotations.

Before decorators, every endpoint had logging boilerplate. After decorators, logging is declared once, applied everywhere.

Decorators are DRY on steroids. They let you write the behavior once and sprinkle it where needed.

The lesson: Repetitive code is a signal. If you're copy-pasting the same pattern, you need abstraction. Decorators are that abstraction.

Make your code declarative. Let decorators handle the repetition.

Next: TypeScript with Frameworks

In the next article, we'll explore TypeScript with React, Express, and other frameworks. You'll learn how proper typing caught a critical React state bug before users noticed.

PreviousType Assertions and Narrowing NextTypeScript with Popular Frameworks

Last updated 1 month ago

hashtagThe 150 Endpoints That Needed Logging

hashtagEnabling Decorators

hashtagClass Decorators

hashtagBasic Class Decorator

hashtagAdding Properties

hashtagSealed Class

hashtagMethod Decorators

hashtagBasic Method Decorator

hashtagMeasure Performance

hashtagMemoization Decorator

hashtagProperty Decorators

hashtagBasic Property Decorator

hashtagParameter Decorators

hashtagBasic Parameter Decorator

hashtagDecorator Factories

hashtagParameterized Decorator

hashtagRetry Decorator

hashtagDecorator Composition

hashtagExecution Order

hashtagReal-World Patterns

hashtag1. Authorization Decorator

hashtag2. Validation Decorator

hashtag3. Caching Decorator

hashtagCommon Mistakes

hashtag1. Forgetting to Enable

hashtag2. Arrow Function Methods

hashtag3. Not Returning Descriptor

hashtagYour Challenge

hashtagKey Takeaways

hashtagWhat I Learned