feat(53461): Implement decorator metadata proposal

[a-tarasyuk]

Fixes #53461

[jakebailey]

FYI @rbuckton

[rbuckton]

We need to add Symbol.metadata to the libs, probably under lib/esnext.decorators.d.ts

In lib/decorators.d.ts we can make context.metadata conditional using an approach like this:

// lib.esnext.decorators.d.ts
interface Symbol {
  readonly metadata: unique symbol;
}

// lib.decorators.d.ts
...

type DecoratorMetadata = typeof globalThis extends { Symbol: { readonly metadata: symbol } } ? object : object | undefined;

interface ClassDecoratorContext<...> {
  ...
  readonly metadata: DecoratorMetadat;
  ...
}

...

interface ClassMethodDecoratorContext<...> {
  ...
  readonly metadata: DecoratorMetadat;
  ...
}

... etc. ...

[rbuckton]

Ideally, we can take this for the 5.2 beta which has a deadline of this Friday. Let me know if you need me to help with any part of this PR to get it in this week.

[a-tarasyuk]

@rbuckton Thank you so much for taking the time to review this PR 👍🏻. I have added the esnext.decorators library and made changes related to types and factory helpers. I have noticed that the super call is transformed into Reflect.get in classFields. I'm not entirely sure if this is okay, I will check it tomorrow…

[rbuckton]

It would also help to have evaluation tests that run the some of the examples used in the esDecoratorMetadata tests and verify the expected output (see src\testRunner\unittests\evaluation\esDecorators.ts).

To make that work you would need to shim Symbol.metadata for the evaluation tests, which you can do in src\harness\evaluatorImpl.ts:20. See
https://github.com/microsoft/TypeScript/pull/54505/files?show-viewed-files=true&file-filters%5B%5D=#diff-3b6817a4cdcf825c75e6f9af6cad21356ee6a7cd35bb5d3c92eef8e0985ce910R20-R33 for an example.

[rbuckton]

Some tests are failing and there are merge conflicts. Can you verify baselines and update with main?

[a-tarasyuk]

@rbuckton I've merged changes from the main

[rbuckton]

It looks like one of your evaluation tests is failing.

[rbuckton]

@typescript-bot pack this

[typescript-bot]

Heya @rbuckton, I've started to run the tarball bundle task on this PR at 3515e58. You can monitor the build here.

[a-tarasyuk]

It looks like one of your evaluation tests is failing.

Yes. It due to #54657 (comment)

[typescript-bot]

Hey @rbuckton, I've packed this into an installable tgz. You can install it for testing by referencing it in your package.json like so:

{
    "devDependencies": {
        "typescript": "https://typescript.visualstudio.com/cf7ac146-d525-443c-b23c-0d58337efebc/_apis/build/builds/155600/artifacts?artifactName=tgz&fileId=907D5787AC0EB0691771857360E56A79917C1534F3C1E3FF9382E73F0CF73DCE02&fileName=/typescript-5.2.0-insiders.20230622.tgz"
    }
}

and then running npm install.

---

There is also a playground for this build and an npm module you can use via "typescript": "npm:@typescript-deploys/pr-build@5.2.0-pr-54657-9".;

[rbuckton]

We should also add this to esnext.decorators.d.ts:

interface Function {
  [Symbol.metadata]?: object | null;
}

Sorry, we should add it to src/lib/decorators.d.ts instead, per my other suggestion.

[rbuckton]

This is looking fairly close to ready, once the baselines are reviewed and accepted I'll hopefully be able to take a final pass and approve.

[a-tarasyuk]

@rbuckton What are your thoughts on moving the following types from decorators.d to esnext.decorators.d?

interface Function {
    [Symbol.metadata]: DecoratorMetadata | null;
}

[rbuckton]

It shouldn't be optional since it will already get the | undefined from the DecoratorMetadata type with the definition I suggested. Placing it in esnext.decorators makes sense given the dependence on Symbol.

[a-tarasyuk]

oke, I've moved it to esnext.decorators.d.

[rbuckton]

It shouldn't be optional since it will already get the | undefined from the DecoratorMetadata type with the definition I suggested. Placing it in esnext.decorators makes sense given the dependence on Symbol.

I should have added more detail to this, but it was late. The main reason to not make it an optional property of Function is that we wouldn't be able to make it not optional in esnext (or es2024, etc.). There is a way to do that, but it would have been more complex and employ the same mechanism as DecoratorMetadata already does, i.e.:

type FunctionMetadata =
    typeof globalThis extends { Symbol: { readonly metadata: symbol } } ? {
        [Symbol.metadata]: DecoratorMetadataObject | null;
    } : {
        [Symbol.metadata]?: DecoratorMetadataObject | null;
    };

interface Function extends FunctionMetadata {
}

But I think the approach of just using DecoratorMetadata—which already includes this conditional—and leaving the property as non-optional is fine.