This implements support for the Stage 3 Decorators proposal targetingESNext throughES5 (except where it depends on functionality not available in a specific target, such as WeakMaps for down-level private names).

The following items arenot currently supported:

• --emitDecoratorMetadata, as metadata is currently under discussion inhttps://github.com/tc39/proposal-decorator-metadata and has not yet reached Stage 3.
• Decorators on adeclare field.
• Parameter decorators will not be supported until a follow-on proposal has been adopted and has advanced to Stage 3.
  • SeeParameter decorators tc39/proposal-decorators#47 for additional information.
• Decorators may not change the type of the member or class they decorate. If we decide to allow this capability, we will do so in a later PR. This is under discussion in the following two issues:
  • Allow decorators to apply type guards to arguments of the method/function they decorate #50159
  • Support to method decorator that change the method signature #49229

With that out of the way, the following items are whatis supported, or is new or changed for Decorators support in the Stage 3 proposal:

• The--experimentalDecorators flag will continue to opt-in to the legacy decorator support (which still continues to support--emitDecoratorMetadata and parameter decorators).
• ES Decorators are now supportedwithout the--experimentalDecorators flag.
• 🆕 ES Decorators will be transformed when the target is less thanESNext (or at least, until such time as the proposal reaches Stage 4).
• 🆕 ES Decorators now accept exactly two arguments:target andcontext:
  • target — A value representing the element being decorated:
    • Classes, Methods,get accessors, andset accessors: This will be the function for that element.
    • Auto-Accessor fields (i.e.,accessor x): This will be an object withget andset properties.
    • Fields: This will always beundefined.
  • context — An object containing additional context information about the decorated element such as:
    • kind - The kind of element ("class","method","getter","setter","field","accessor").
    • name - The name of the element (either astring orsymbol).
    • private - Whether the element has a private name.
    • static - Whether the element was declaredstatic.
    • access - An object with either aget property, aset property, or both, that is used to read and write to the underlying value on an object.
    • addInitializer - A function that can be called to register a callback that is evaluated either when the class is defined or when an instance is created:
      • For static member decorators, initializers run after class decorators have been applied but before static fields are initialized.
      • For Class Decorators, initializers run after all static initializers.
      • For non-static member decorators, initializers run in the constructor before all field initializers are evaluated.
• 🆕 ES Decorators can decorateprivate fields.
• 🆕 ES Decorators can decorateclass expressions.
• ‼️ ES Accessor Decorators (i.e., forget andset declarations)no longer receive the combined property descriptor. Instead, they receive the accessorfunction they decorate.
  • A stage 1 proposal that expands upon auto-accessors to allow you to decorateget/set pairs can be found athttps://github.com/tc39/proposal-grouped-and-auto-accessors.
• ‼️ ES Member Decorators (i.e., for accessors, fields, and methods)no longer have immediate access to the constructor/prototype the member is defined on.
  • If you need access to the class constructor from astatic member, you can use:

    context.addInitializer(function(){this/*constructor reference*/});

  • If you need access to theinstance (not the prototype) from a non-static member, you can use:

    context.addInitializer(function(){this/*instance reference*/});

  • Non-static members currently have no way to access the constructor or prototype during class definition.
  • This behavior is under discussion atSuggestion: Allow member decorators to add both static and instance *extra* initializers. tc39/proposal-decorators#465.
• ‼️ ES Member Decorators can no longer set theenumerable,configurable, orwritable properties as they do not receive the property descriptor. You can partially achieve this viacontext.addInitializer, but with the caveat that initializers added by non-static member decorators will run duringevery instance construction.
• When the name of the class is inferred from an assignment, we will now explicitly set the name of the classin some cases.
  This is not currently consistent in all cases and is only set when transforming native ES Decorators or class fields. While we generally have not strictly aligned with the ECMA-262 spec with respect to assigned names when downleveling classes and functions (sometimes your class will end up with an assigned name ofclass_1 ordefault_1), I opted to include this becausename is one of the few keys available to a class decorator's context object, making it more important to support correctly.

Type Checking

When a decorator is applied to a class or class member, we check that the decorator can be invoked with the appropriatetarget anddecorator context, and that its return value is consistent with its target. To do this, we check the decorator against a synthetic call signature, not unlike the following:

typeSyntheticDecorator<T,C,R>=(target:T,context:C)=>R|void;

The types we use forT,C, andR depend on the target of the decorator:

• T — The type for the decorationtarget. This does not always correspond to the type of a member.
  • For a class decorator, this will be the class constructor type.
  • For a method decorator, this will be the function type of the method.
  • For a getter decorator, this will be the function type of theget method,not the type of the resulting property.
  • For a setter decorator, this will be the function type of theset method,not the type of the resulting property.
  • For an auto-accessor field decorator, this will be a{ get, set } object corresponding to the generatedget method andset method signatures.
  • For a normal field decorator, this will always beundefined.
• C — The type for thedecorator context. A context type based on the kind of decoration type, intersected with an object type consisting of the target'sname,placement, andvisibility (see below).
• R — The allowed type for the decorator's return value. Note that any decorator may returnvoid/undefined.
  • For a class, method, getter, or setter decorator, this will beT.
  • For an auto-accessor field decorator, this will be a{ get?, set?, init? } whoseget andset correspond to the generatedget method andset method signatures. The optionalinit member can be used to
    inject aninitializer mutator function.
  • For a normal field decorator, this can be aninitializer mutator function.

Method Decorators

classMyClass{m():void{ ...}}

Amethod decorator applied tom(): void would use the types

typeT=(this:MyClass)=>void;typeC=&ClassMethodDecoratorContext<MyClass,(this:MyClass)=>void>&{name:"m",private:false,static:false};typeR=(this:MyClass)=>void;

resulting in a call signature like

typeExpectedSignature=(target:(this:MyClass)=>void,context:&ClassMethodDecoratorContext<MyClass,(this:MyClass)=>void>&{name:"m",private:false,static:false},)=>((this:MyClass)=>void)|void;

Here, we specify atarget type (T) of(this: MyClass) => void. We don't normally traffic around thethis type for methods, but in this case it is important that we do. When a decoratorreplaces a method, it is fairly common to invoke the method you are replacing:

functionlog<T,Aextendsany[],R>(target:(this:T, ...args:A)=>R,context:ClassMethodDecoratorContext<T,(this:T, ...args:A)=>R>){returnfunction(this:T, ...args:A):R{        console.log(`${context.name.toString()}: enter`);try{// need the appropriate `this`returntarget.call(this, ...args);}finally{console.log(`${context.name.toString()}: exit`);}};}

You may also notice that we intersect a common context type, in this caseClassMethodDecoratorContext, with a type literal. This type literal contains information specific to the member, allowing you to write decorators that are restricted to members with a certain name, placement, or accessibility. For example, you may have a decorator that is intended to only be used on theSymbol.iterator method

functioniteratorWrap<T,V>(target:(this:T)=>Iterable<V>,context:ClassMethodDecoratorContext<T,(this:T)=>Iterable<V>>&{name:Symbol.iterator}){    ...}

, or one that is restricted tostatic fields

functionlazyStatic<T,V>(target:undefined,context:ClassFieldDecoratorContext<T,V>&{static:true}){    ...}

, or one that prohibits usage on private members

functionpublicOnly(target:unknown,context:ClassMemberDecoratorContext&{private:false}){    ...}

We've chosen to perform an intersection here rather than add additional type parameters to each*DecoratorContext type for several reasons. The type literal allows for a convenient way to introduce a restriction in your decorator code without needing to fuss over type parameter order. Additionally, in the future we may opt to allow a decorator to replace thetype of its decoration target. This means we may need to flow additional type information into the context to support theaccess property, which acts on thefinal type of the decorated element. The type literal allows us to be flexible with future changes.

Getter and Setter Decorators

classMyClass{getx():string{ ...}setx(value:string){ ...}}

Agetter decorator applied toget x(): string above would have the types

typeT=(this:MyClass)=>string;typeC=ClassGetterDecoratorContext<MyClass,string>&{name:"x",private:false,static:false};typeR=(this:MyClass)=>string;

resulting in a call signature like

typeExpectedSignature=(target:(this:MyClass)=>string,context:ClassGetterDecoratorContext<MyClass,string>&{name:"x",private:false,static:false},)=>((this:MyClass)=>string)|void;

, while asetter decorator applied toset x(value: string) would have the types

typeT=(this:MyClass,value:string)=>void;typeC=ClassSetterDecoratorContext<MyClass,string>{name:"x",private:false,static:false};typeR=(this:MyClass,value:string)=>void;

resulting in a call signature like

typeExpectedSignature=(target:(this:MyClass,value:string)=>void,context:ClassSetterDecoratorContext<MyClass,string>&{name:"x",private:false,static:false},)=>((this:MyClass,value:string)=>void)|void;

Getter andsetter decorators in the Stage 3 decorators proposal differ significantly from TypeScript's legacy decorators. Legacy decorators operated on aPropertyDescriptor, giving you access to both theget andset functions as properties of the descriptor. Stage 3 decorators, however, operate directly on theget andset methods themselves.

Field Decorators

classMyClass{    #x:string= ...;}

Afield decorator applied to a field like#x: string above (i.e., one that does not have a leadingaccessor keyword) would have the types

typeT=undefined;typeC=ClassFieldDecoratorContext<MyClass,string>&{name:"#x",private:true,static:false};typeR=(this:MyClass,value:string)=>string;

resulting in a call signature like

typeExpectedSignature=(target:undefined,context:ClassFieldDecoratorContext<MyClass,string>&{name:"#x",private:true,static:false},)=>((this:MyClass,value:string)=>string)|void;

Thetarget of afield decorator is alwaysundefined, as there is nothing installed on the class or prototype during declaration evaluation. Non-static fields are installed only when an instance is created, whilestatic fields are installed only after all decorators have been evaluated. This means that you cannot replace a field in the same way that you can replace a method or accessor. Instead, you can return aninitializer mutator function — a callback that can observe, and potentially replace, the field's initialized value prior to the field being defined on the object:

functionaddOne<T>(target:undefined,context:ClassFieldDecoratorContext<T,number>){returnfunction(this:T,value:number){returnvalue+1;};}classC{    @addOne    @addOnex=1;}newC().x;// 3

This essentially behaves as if the following happened instead:

letf1,f2;classC{static{f1=addOne(undefined,{ ...});f2=addOne(undefined,{ ...})}x=f1.call(this,f2.call(this,1));}

Auto-Accessor Decorators

Stage 3 decorators introduced a new class element known as an "Auto-Accessor Field". This is a field that is transposed into pair ofget/set methods of the same name, backed by a private field. This is not only a convenient way to represent a simple accessor pair, but also helps to avoid issus that occur if a decorator author were to attempt to replace an instance field with an accessor on the prototype, since an ECMAScript instance field would shadow the accessor when it is installed on the instance.

classMyClass{    accessory:number;}

Anauto-accessor decorator applied to a field likeaccessor y: string above would have the types

typeT=ClassAccessorDecoratorTarget<MyClass,string>;typeC=ClassAccessorDecoratorContext<MyClass,string>&{name:"y",private:false,static:false};typeR=ClassAccessorDecoratorResult<MyClass,string>;

resulting in a call signature like

typeExpectedSignature=(target:undefined,context:ClassFieldDecoratorContext<MyClass,string>&{name:"#x",private:true,static:false},)=>((this:MyClass,value:string)=>string)|void;

Note thatT in the example above is essentially the same as

typeT={get:(this:MyClass)=>string,set:(this:MyClass,value:string)=>void};

, whileR is essentially the same as

typeR={get?:(this:MyClass)=>string,set?:(this:MyClass,value:string)=>void,init?:(this:MyClass,value:string)=>string};

The return value (R) is designed to permit replacement of theget andset methods, as well as injecting aninitializer mutator function like you can with a field.

Class Decorators

classMyClass{m():void{ ...}getx():string{ ...}setx(value:string){ ...}    #x:string;    accessory:number;}

Aclass decorator applied toclass MyClass would use the types

typeT=typeofMyClass;typeC=ClassDecoratorContext<typeofMyClass>&{name:"MyClass"};typeR=typeofMyClass;

resulting in a call signature like

typeExpectedSignature=(target:typeofMyClass,context:ClassDecoratorContext<typeofMyClass>&{name:"MyClass"})=>typeofMyClass|void;

Fixes#48885