How ES Decorators Simplify Reuse and Consistency in Large JavaScript Libraries

Reuse and consistency are timeless challenges in software design. The latest ES proposal introduces decorators syntax, which offers a convenient way to apply these concepts, especially in large libraries.

Decorator Pattern

The classic decorator pattern lets you add extra functionality without modifying the original code, effectively wrapping the original method.

Typical scenarios include:

Recording method start and end execution.

Providing additional caching capabilities.

Marking methods as deprecated.

Other cross‑cutting concerns.

Writing a Decorator

A decorator can accept an original function and return a wrapped version. For example, a performance‑timing decorator records execution time:

function performanceTimingDecorator(func) {
  return function(...args) {
    const start = Date.now();
    func(...args);
    const end = Date.now();
    const t = end - start;
    console.log(`${func.name} performed ${t}ms.`);
  };
}

function func() {}
const funcWrapped = performanceTimingDecorator(func);
funcWrapped();

Using ES Decorators

When many decorators are needed, the ES decorator syntax provides a cleaner, annotation‑like form ( @xxx) that improves readability and converges definition and invocation.

function performanceTiming(...args) {
  return function(target, key, descriptor) {
    // ...implementation
  };
}

class MyClass {
  @performanceTiming
  func() {}
}

The new syntax resembles Java annotations but is implemented differently; it is inspired by Python decorators.

Consistent API Architecture

In large, multi‑developer projects, maintaining consistent APIs is crucial. Decorators help enforce:

Uniform public utilities across modules.

Consistent implementation and invocation patterns.

Overall API style consistency.

Both points 1 and 2 can be achieved by introducing ES decorators.

Practical Demonstration

Example decorators from the @ali/universal-decorator package: @deprecated – marks a method as deprecated and logs a warning. @moduleLevel – enforces a static member indicating whether a module is an app or page level component.

Applying them:

import { deprecated } from '@ali/universal-decorator';

class Tracker {
  @deprecated('This method is moved to universal-goldlog.', { url: 'http://web.npm.alibaba-inc.com/package/@ali/universal-goldlog' })
  report() {
    // ...implementation
  }
}

Calling report() now triggers a deprecation warning, ensuring all libraries adopt the same API behavior.

Another example constrains class static fields:

import { moduleLevel } from '@ali/universal-decorator';

@moduleLevel('page')
class MyModule1 {}

@moduleLevel('other')
class MyModule2 {}

The @moduleLevel decorator adds a static moduleLevel member and validates the value, warning if it is not 'page' or 'app'.

Using ES decorators creates declarative code that is easier to analyze statically, enabling early validation, conditional compilation, and other advanced tooling.

References

Exploring EcmaScript Decorators

Illustration: a Christmas tree decorated with colorful ornaments, a common metaphor for decorators.