JavaScript Annotation: How Decorators Will Add Annotation Syntax to Classes

1. Annotations Before Decorators Proposal
2. a Primer on Decorators
3. Syntax of a Decorator
4. the Evaluation of a Decorator
5. Calling Decorators
6. an Example of Decorators

This article explains what annotations look like in current JavaScript. We say annotations because they are not like classical annotations in a language like Java.

However, as of April 24, 2022, Decorators is still a Stage 3 proposal. This means Decorators are not yet available in JavaScript.

However, when they become available, they’ll provide a way to add annotation syntax for class declarations.

Annotations Before Decorators Proposal

Before the proposals for Decorators in JavaScript, the thing closest to an annotation is the "use script" directive. For example:

(function() {
'use strict';
// code in strict mode
})();

In the code above, the "use strict" directive causes strict mode execution within the function.

a Primer on Decorators

From the Decorators proposal, decorators are functions that you can use for metaprogramming and adding functionality to a value without changing its external behavior. They’ll work on the following.

1. Classes
2. Class methods
3. Class fields
4. Class accessors
5. Class auto accessors

After calling a decorator on these elements, a Decorator can do the following:

1. A decorator can replace a method with another method or a class with another class.
2. Decorators can provide access to the value decorated via accessor functions.
3. Decorators can initialize the value that you want to decorate.

Syntax of a Decorator

The Decorators proposal is currently at Stage 3; however, it uses the syntax from Stage 2. Therefore, the following applies to the syntax of a decorator.

1. Their expressions are restricted to a chain of variables. Also, you do property access with dot notation and not square bracket notation.

   However, you can use @(expression) if you’d like an arbitrary expression.

2. You can decorate class expressions and class declarations.

3. Class decorators come after export and default.

the Evaluation of a Decorator

The evaluation of a decorator follows the following steps.

1. Decorator expressions are evaluated with computed property names.
2. Decorators are called functions during class definition. This happens after evaluating the methods but before the prototype and constructor.
3. Decorators mutate the constructor and prototypes at once.

Calling Decorators

When you call decorators, they receive two parameters. These parameters are:

1. The value you want to decorate. This value is undefined in the case of class fields.
2. A context object that contains information about the value being decorated.

an Example of Decorators

The following is a sample code inspired by a similar code from the Decorator proposal.

export function log(target) {
  if (typeof target.descriptor.value === 'function') {
    const original = target.descriptor.value;
    target.descriptor.value = function(...args) {
      console.log('arguments: ', args);
      const result = original.apply(this, args);
      console.log('result: ', result);
      return result;
    }
  }
  return target;
}

Afterward, the Decorator will work as such:

import {log} from './decorators.js';

export default class DogSounds {
  @log
  barkSound() {
    console.log('woof');
  }

  @log
  say(to_say) {
    console.log(to_say)
    return 'The dog said ' + to_say
  }
}

From the code above, you can tell that the application of the Decorator via the @ symbol is similar to annotation from a language like Java.

1. Can we use Decorators in JavaScript?

   No. Because as of April 2022, it’s still a Stage 3 ECMA proposal.

2. When can we use Decorators in JavaScript?

   You can use Decorators in JavaScript when the Decorators proposal reaches Stage 4 and is included in the next edition of ECMAScript.