TypeScript Property Decorators

Property decorators in TypeScript are used to modify or augment the behavior of a class property. These decorators can be applied to instance properties, static properties, or accessors (getter and setter). Property decorators allow you to perform tasks such as logging, validation, or transformation of property values.

 

What is a Property Decorator?

A property decorator is a function that is applied to the property of a class. It takes two arguments:

1. The prototype of the class (for instance properties) or the constructor function (for static properties).
2. The name of the property being decorated.

Property decorators can be used for various tasks such as validation, auto-generation of values, and property transformation.

 

Enabling Property Decorators in TypeScript

To use decorators in TypeScript, the experimentalDecorators option must be enabled in the tsconfig.json file.

Example: Enabling Property Decorators

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

• The experimentalDecorators flag is essential for enabling the decorator feature in TypeScript.

Syntax of Property Decorators

A property decorator is a function that takes two parameters:

1. target: The prototype of the class (for instance properties) or the constructor function (for static properties).
2. propertyKey: The name of the property being decorated.

function PropertyDecorator(target: any, propertyKey: string) {
  console.log(target, propertyKey);
}

 

Applying Property Decorators

To apply a property decorator, place the decorator above the property in the class.

Example: Applying a Simple Property Decorator

function LogProperty(target: any, propertyKey: string) {
  console.log(`Property ${propertyKey} is being initialized`);
}

class Example {
  @LogProperty
  name: string;
}

const example = new Example();
example.name = "John";  // Output: Property name is being initialized

• The @LogProperty decorator logs a message every time the name property is initialized.

 

Modifying Property Behavior with Decorators

You can use property decorators to modify or extend the behavior of properties. For example, you can transform property values before they are set or log changes to them.

Example: Modifying Property Behavior

function UpperCase(target: any, propertyKey: string) {
  let value: string;

  const getter = () => value;
  const setter = (newValue: string) => {
    value = newValue.toUpperCase();
  };

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

class Example {
  @UpperCase
  name: string;
}

const example = new Example();
example.name = "john";
console.log(example.name);  // Output: JOHN

• The @UpperCase decorator modifies the name property so that any value assigned to it is automatically converted to uppercase.

 

Property Decorators with Parameters

You can also create property decorators that accept parameters, allowing you to customize their behavior.

Example: Property Decorator with Parameters

function MaxLength(length: number) {
  return function(target: any, propertyKey: string) {
    let value: string;

    const getter = () => value;
    const setter = (newValue: string) => {
      if (newValue.length > length) {
        console.log(`Value too long for ${propertyKey}`);
      } else {
        value = newValue;
      }
    };

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

class Example {
  @MaxLength(5)
  name: string;
}

const example = new Example();
example.name = "John"; // Value is set
console.log(example.name);  // Output: John

example.name = "Jonathan"; // Output: Value too long for name

• The @MaxLength decorator ensures that the value assigned to the name property does not exceed the specified length.

 

Using Property Decorators for Validation

Property decorators can also be used to validate property values before they are set. This can be useful for ensuring that properties meet certain criteria before they are stored.

Example: Property Decorator for Validation

function ValidateAge(target: any, propertyKey: string) {
  let value: number;

  const getter = () => value;
  const setter = (newValue: number) => {
    if (newValue < 0 || newValue > 120) {
      throw new Error(`Invalid age value for ${propertyKey}`);
    }
    value = newValue;
  };

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

class Person {
  @ValidateAge
  age: number;
}

const person = new Person();
person.age = 25;  // Valid age
console.log(person.age);  // Output: 25

person.age = -5;  // Throws error: Invalid age value for age

• The @ValidateAge decorator ensures that the age property is always a valid value between 0 and 120.

 

Using Property Decorators with Accessors

Property decorators can also be used with getter and setter methods. This allows you to control how the property is accessed and set.

Example: Property Decorators with Accessors

function UpperCase(target: any, propertyKey: string) {
  let value: string;

  const getter = () => value;
  const setter = (newValue: string) => {
    value = newValue.toUpperCase();
  };

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

class Example {
  private _name: string;

  @UpperCase
  get name() {
    return this._name;
  }

  set name(value: string) {
    this._name = value;
  }
}

const example = new Example();
example.name = "john";
console.log(example.name);  // Output: JOHN

• In this case, the name property has a getter and setter, and the @UpperCase decorator modifies its behavior, ensuring that the value is always stored in uppercase.

 

Summary

• Property decorators in TypeScript are used to modify the behavior of class properties.
• They are applied above the property declaration and allow tasks such as validation, transformation, and logging of property values.
• Property decorators can modify property descriptors and use Object.defineProperty to create custom getter and setter behavior.
• Decorators can be customized with parameters to allow for more dynamic behavior.
• Property decorators are powerful tools for implementing additional functionality on class properties without modifying the underlying code.