Implement decorator metadata proposal

[justinfagnani]

Suggestion

Implement decorator metadata

🔍 Search Terms

decorator metadata

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Now that decorators are shipping in TypeScript and decorator metadata has reached consensus on the approach needed for it to proceed to Stage 3, it seems like it may be time to implement metadata.

📃 Motivating Example

There are examples on the metadata repo, but a quick one is storing information about a class member to be used by the class's base class. Here we generate a custom element's observedAttributes by decorating fields:

// Library code:
const attributes = new WeakMap<typeof BaseElement, Array<string>>();
class BaseElement {
  static get observedAttributes() {
    // real code would get attributes from super-classes too
    return attributes.get(this[Symbol.metadata]);
  }
}
const attribute = (_, {name, metadata}) => {
  attributes.set(metadata, (attributes.get(metadata) ?? []).push(name));
}

// Usage:
class MyElement extends BaseElement {
  @attribute
  foo?: string;
}

💻 Use Cases

There are many use cases in the various decorators repositories and documents. Generally any time that some other API besides the decorated one needs information about the decorated items, you will need metadata.

It's worth noting that many libraries can't use decorators until metadata is implemented.

[MartinJohns]

[x] This feature would agree with the rest of TypeScript's Design Goals.

I don't know the current position of the team on this, but it does violate non-goal 5. The current experimental metadata support comes from the early dark times before this design goal document.

Nevermind, you refer to an actual ES proposal. But that is only stage 2, usually the team waits for at least stage 3.

[justinfagnani]

@MartinJohns

But that is only stage 2, usually the team waits for at least stage 3.

Yes, but like I mentioned the metadata proposal just got consensus on the approach to enable it to go to Stage 3 very soon. An issue like this can be used to track some work even before that work could be done or shipped.

[DanielRosenwasser]

Tentatively scheduling for TypeScript 5.2. Luckily, that's not too far off anyway.

[EisenbergEffect]

Please. Please. Please. Please. Please. Please. Please.

@DanielRosenwasser I will send your team a cake. Or, if you like other tasties, let me know. Clearly I'm not above bribery when it comes to decorator metadata 🤣

/cc @chrisdholt

[EisenbergEffect]

Stage 3 is official!!! 🎊

[rbuckton]

The downlevel emit for this is fairly simple, and should work with the existing helpers. When I wrote the __esDecorate, the intent was for it to easily support metadata a well.

given

@dec
class C {
}

we used to emit

let C = (() => {
    let _classDecorators = [dec];
    let _classDescriptor;
    let _classExtraInitializers = [];
    let _classThis;
    var C = class {
        static {
            __esDecorate(null, _classDescriptor = { value: this }, _classDecorators, { kind: "class", name: this.name }, null, _classExtraInitializers);
            C = _classThis = _classDescriptor.value;
            __runInitializers(_classThis, _classExtraInitializers);
        }
    };
    return C = _classThis;
})();

But in the future, we will emit this instead:

let C = (() => {
    let _classDecorators = [dec];
    let _classDescriptor;
    let _classExtraInitializers = [];
    let _classThis;
    var C = class {
        static {
            const metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : undefined;
            __esDecorate(null, _classDescriptor = { value: this }, _classDecorators, { kind: "class", name: this.name, metadata }, null, _classExtraInitializers);
            C = _classThis = _classDescriptor.value;
            if (metadata) Object.defineProperty(C, Symbol.metadata, { configurable: true, writable: true, value: metadata });
            __runInitializers(_classThis, _classExtraInitializers);
        }
    };
    return C = _classThis;
})();

Metadata availability will be conditional on the presence of Symbol.metadata, so as not to break existing users.