TypeScript Decorators: A Practical Guide

Decorators modify classes and their members at design time. Here's how to use them effectively.

Enabling Decorators#

// tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Class Decorators#

// Simple class decorator
function Sealed(constructor: Function) {
  Object.seal(constructor);
  Object.seal(constructor.prototype);
}

@Sealed
class User {
  name: string;

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

// Class decorator factory
function Entity(tableName: string) {
  return function <T extends { new (...args: any[]): {} }>(constructor: T) {
    return class extends constructor {
      static tableName = tableName;
    };
  };
}

@Entity('users')
class User {
  id: string;
  name: string;
}

console.log((User as any).tableName); // 'users'

// Decorator that adds methods
function Timestamped<T extends { new (...args: any[]): {} }>(Base: T) {
  return class extends Base {
    createdAt = new Date();
    updatedAt = new Date();

    touch() {
      this.updatedAt = new Date();
    }
  };
}

@Timestamped
class Post {
  title: string;

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

const post = new Post('Hello');
console.log(post.createdAt); // Date

Method Decorators#

// Log method calls
function Log(
  target: any,
  propertyKey: string,
  descriptor: PropertyDescriptor
) {
  const original = descriptor.value;

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

  return descriptor;
}

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

// Measure execution time
function Measure(
  target: any,
  propertyKey: string,
  descriptor: PropertyDescriptor
) {
  const original = descriptor.value;

  descriptor.value = async function (...args: any[]) {
    const start = performance.now();
    const result = await original.apply(this, args);
    const duration = performance.now() - start;
    console.log(`${propertyKey} took ${duration.toFixed(2)}ms`);
    return result;
  };

  return descriptor;
}

class DataService {
  @Measure
  async fetchData(): Promise<Data[]> {
    // Fetch data...
  }
}

// Memoization decorator
function Memoize(
  target: any,
  propertyKey: string,
  descriptor: PropertyDescriptor
) {
  const cache = new Map<string, any>();
  const original = descriptor.value;

  descriptor.value = function (...args: any[]) {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key);
    }

    const result = original.apply(this, args);
    cache.set(key, result);
    return result;
  };

  return descriptor;
}

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

Property Decorators#

// Validation decorator
function MinLength(length: number) {
  return function (target: any, propertyKey: string) {
    let value: string;

    const getter = () => value;
    const setter = (newVal: string) => {
      if (newVal.length < length) {
        throw new Error(
          `${propertyKey} must be at least ${length} characters`
        );
      }
      value = newVal;
    };

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

class User {
  @MinLength(3)
  name: string;

  @MinLength(8)
  password: string;
}

// Observable property
function Observable(target: any, propertyKey: string) {
  const privateKey = `_${propertyKey}`;
  const callbacksKey = `_${propertyKey}Callbacks`;

  Object.defineProperty(target, propertyKey, {
    get() {
      return this[privateKey];
    },
    set(value: any) {
      const oldValue = this[privateKey];
      this[privateKey] = value;

      if (this[callbacksKey]) {
        this[callbacksKey].forEach((cb: Function) => cb(value, oldValue));
      }
    },
  });

  target.observe = function (prop: string, callback: Function) {
    const key = `_${prop}Callbacks`;
    if (!this[key]) {
      this[key] = [];
    }
    this[key].push(callback);
  };
}

class Store {
  @Observable
  count: number = 0;
}

const store = new Store();
store.observe('count', (newVal: number) => console.log('Count:', newVal));
store.count = 5; // Logs: Count: 5

Parameter Decorators#

import 'reflect-metadata';

const requiredMetadataKey = Symbol('required');

function Required(
  target: any,
  propertyKey: string,
  parameterIndex: number
) {
  const existingRequired: number[] =
    Reflect.getOwnMetadata(requiredMetadataKey, target, propertyKey) || [];
  existingRequired.push(parameterIndex);
  Reflect.defineMetadata(
    requiredMetadataKey,
    existingRequired,
    target,
    propertyKey
  );
}

function Validate(
  target: any,
  propertyKey: string,
  descriptor: PropertyDescriptor
) {
  const method = descriptor.value;

  descriptor.value = function (...args: any[]) {
    const requiredParams: number[] =
      Reflect.getOwnMetadata(requiredMetadataKey, target, propertyKey) || [];

    for (const index of requiredParams) {
      if (args[index] === undefined || args[index] === null) {
        throw new Error(`Parameter at index ${index} is required`);
      }
    }

    return method.apply(this, args);
  };
}

class UserService {
  @Validate
  createUser(@Required name: string, age?: number) {
    return { name, age };
  }
}

Accessor Decorators#

function Readonly(
  target: any,
  propertyKey: string,
  descriptor: PropertyDescriptor
) {
  descriptor.writable = false;
  return descriptor;
}

class Config {
  private _apiKey: string;

  constructor(apiKey: string) {
    this._apiKey = apiKey;
  }

  @Readonly
  get apiKey() {
    return this._apiKey;
  }
}

// Lazy initialization
function Lazy(
  target: any,
  propertyKey: string,
  descriptor: PropertyDescriptor
) {
  const getter = descriptor.get!;
  const key = Symbol(`lazy_${propertyKey}`);

  descriptor.get = function () {
    if (!this[key]) {
      this[key] = getter.call(this);
    }
    return this[key];
  };

  return descriptor;
}

class ExpensiveService {
  @Lazy
  get connection() {
    console.log('Creating connection...');
    return createConnection();
  }
}

Real-World Patterns#

// Dependency injection
const Injectable = (): ClassDecorator => {
  return (target) => {
    Reflect.defineMetadata('injectable', true, target);
  };
};

const Inject = (token: string): ParameterDecorator => {
  return (target, propertyKey, parameterIndex) => {
    const existingInjections =
      Reflect.getMetadata('injections', target) || [];
    existingInjections.push({ index: parameterIndex, token });
    Reflect.defineMetadata('injections', existingInjections, target);
  };
};

@Injectable()
class UserService {
  constructor(
    @Inject('Database') private db: Database,
    @Inject('Logger') private logger: Logger
  ) {}
}

// Route decorators (like Express)
function Controller(basePath: string): ClassDecorator {
  return (target) => {
    Reflect.defineMetadata('basePath', basePath, target);
  };
}

function Get(path: string): MethodDecorator {
  return (target, propertyKey, descriptor) => {
    Reflect.defineMetadata('route', { method: 'GET', path }, target, propertyKey);
  };
}

function Post(path: string): MethodDecorator {
  return (target, propertyKey, descriptor) => {
    Reflect.defineMetadata('route', { method: 'POST', path }, target, propertyKey);
  };
}

@Controller('/users')
class UserController {
  @Get('/')
  getAll() {
    return this.userService.findAll();
  }

  @Get('/:id')
  getOne(id: string) {
    return this.userService.findById(id);
  }

  @Post('/')
  create(data: CreateUserDto) {
    return this.userService.create(data);
  }
}

Best Practices#

Design:
✓ Keep decorators focused
✓ Use factories for configuration
✓ Compose multiple decorators
✓ Document decorator behavior

Performance:
✓ Avoid heavy computation in decorators
✓ Use lazy initialization
✓ Cache metadata lookups
✓ Consider runtime cost

Testing:
✓ Test decorated and undecorated
✓ Mock decorator effects
✓ Test decorator combinations
✓ Verify metadata

Decorators provide powerful metaprogramming capabilities in TypeScript. Use them for cross-cutting concerns like logging, validation, and dependency injection. Keep decorators simple and composable, and remember they run at class definition time, not instantiation.