Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Support for design-time decorators #2900

Open
mhegazy opened this issue Apr 24, 2015 · 43 comments
Open

Add Support for design-time decorators #2900

mhegazy opened this issue Apr 24, 2015 · 43 comments

Comments

@mhegazy
Copy link
Contributor

@mhegazy mhegazy commented Apr 24, 2015

Now that decorators are supported in TypeScript (#2249), consider adding support for ambient/design-time-only decorators:

Ambient decorators can be an extensible way to declare properties on or associate special behavior to declarations; design time tools can leverage these associations to produce errors or produce documentation. For example:

Use cases:

  • Deprecated/Obsolete, to support warning on use of specific API’s:
interface JQuery {  
    /**  
     * A selector representing selector passed to jQuery(), if any, when creating the original set.  
     * version deprecated: 1.7, removed: 1.9  
     */  
    @@deprecated("Property is only maintained to the extent needed for supporting .live() in the jQuery Migrate plugin. It may be removed without notice in a future version.", false)  
    selector: string;  
}
  • Suppress linter warning:
@@suppressWarning("disallow-leading-underscore")   
function __init() {  
}

Proposal

Design-time (Ambient) decorators are:

  • ambient functions
  • have a special name starting with "@"
  • are not emitted in output JS code, but persisted in .d.ts outputs.

Application

  • Applying a design-time can only accept constant values. Variables would not be observable by the compiler at compile time. Here is the set of possible values:
    • string literal,
    • number literal,
    • regexp literal,
    • true keyword,
    • false keyword,
    • null keyword,
    • undefined symbol,
    • const enum members,
    • array literals of one of the previous kinds,
    • object literal with only properties with values of one of the previous kinds
@mhegazy mhegazy added the Suggestion label Apr 24, 2015
@matjaz
Copy link

@matjaz matjaz commented May 12, 2015

@bradolenick
Copy link

@bradolenick bradolenick commented Jun 5, 2015

For this to be useful in our scenario, we need ambient decorators to be preserved in the generated .d.ts.

In our scenario, compiling a set of .ts files produces a library consumed by others via the library's .d.ts (conventional stuff so far). Those who consume the library, compile against it using a custom tool built in terms of the TypeScript compiler APIs. The tool makes use of ambient decorators in the library's .d.ts.

Today, we're prototyping this tool in terms of 1.5beta decorators, but ambient decorators would allow us to expand to decorate non-classes/non-functions.

@kitsonk
Copy link
Contributor

@kitsonk kitsonk commented Dec 24, 2015

I noticed that this is on the roadmap for 2.0.

Would it be another use-case to allow augmentation of other design time features (like typing)? Something like augmenting the reflect meta-data (@rbuckton).

This is part of my never ending quest to be able to get effective design time mixin/trait support while we all wait for TC39 to figure something out.

@mhegazy
Copy link
Contributor Author

@mhegazy mhegazy commented Jan 22, 2016

@kitsonk can you elaborate on your proposal?

@kitsonk
Copy link
Contributor

@kitsonk kitsonk commented Jan 22, 2016

@mhegazy I might not be the best person to expound upon the proposal, as I have only lived in JavaScript land for an extended period of time (and Delphi a long time ago) and some of the Reflection and Type handling that are part of C# and other languages I am not familiar with.

I guess what I am suggesting is that at design time, in these decorators, some of the internal TypeScript constructs would be available. For example, the ability to construct and return a new type, similar to the C# TypeBuilder.CreateType

But I guess from my perspective, if I had some programmatic design time access to types via these design-time decorators, I could implement language features (mixins/traits) without needing syntatical support in typescript. From a "vision" objective, I would see something like this:

function mixin(target: any, ...mixins: any[]): type {
    const typeTarget = typeof target;
    mixins.forEach((mixin) => {
        const typeMixin = typeof mixin;
        for (let t in typeMixin) {
            typeTarget[t] = typeMixin[t];
        }
    });
    return typeTarget;
}

class A {
    foo() { return false; }
}

class B {
    bar() { return 'bar'; }
}

@@mixin(A, B)
class C {
    baz() { return 1; }
}

const c = new C();
console.log(c.foo(), c.bar(), c.baz());

Of course, I could put a lot of different logic in there, but essentially I could perform design-time operations on the types. I don't know the inner workings of the compiler, but I suspect there would be good set of semantics for safely programmatically operating on types.

@mhegazy
Copy link
Contributor Author

@mhegazy mhegazy commented Jan 22, 2016

Just a clarification; this example you still need to mixin A and B into C at runtime as well; so if understand correctly, this is just a design time mutation to allow the compiler to model what will happen at runtime?

@kitsonk
Copy link
Contributor

@kitsonk kitsonk commented Jan 22, 2016

@mhegazy yes... my specific use case would be to mirror run-time operations which are difficult/impossible to currently do in TypeScript. For example:

class A {
    foo: string = '';
}

class B {
    foo() { return 'foo'; };
}

interface GenericClass<T> {
    new (...args: any[]): T;
}

function mixin<T, U>(target: GenericClass<T>, source: GenericClass<U>): GenericClass<T&U> {
    return;
}

const C = mixin(A, B);

const c = new C();

c.foo; // is of type string & (() => string)

Clearly, the intent of my code was not to create a type of string & (() => string) and my mixin function would have resolved that in some way. I could use the same resolution logic at runtime with my decorator and safely resolve the type. Currently, I would typically "overlay" and interface on my final class which resolves any conflicts.

I am sure there are other use cases, where it is difficult/impossible to express the actual run-time types without some advanced design-time logic to mutate those types. extends, union and intersection aren't always sufficient.

@mhegazy
Copy link
Contributor Author

@mhegazy mhegazy commented Jan 23, 2016

Risking to derail this issue, but just wondering if you looked at the proposal in #6502 (comment), and what you think about it.

@kitsonk
Copy link
Contributor

@kitsonk kitsonk commented Jan 23, 2016

No, I had missed it, as I mentioned there, I do think it is related to #3870 (which this is sort of in the same space as well), but I think the challenge comes in that sometimes we can (want/need/desire) to do things at runtime that require us to express some heavy design time logic. I see design time decorators too as a potential way of avoiding introducing some challenging language semantics. For example in #6502, the proposal is to place syntax that would have to both be erased but also add more to the emit, which could easily cause forward incompatibilities with ES. Property initialisers are likely to come to ES (YAY!) but what is the likelyhood that the proposed syntax in #6502 would be aligned? I would expect the TypeScript team to decline that just like #311.

The beauty of design time decorators is that, as the name implies, they would be 100% erasable with almost no need to consider the emit (except when emitting meta data).

@silkentrance
Copy link

@silkentrance silkentrance commented Mar 4, 2016

Design time custom decorators/annotations just as in Java / C# would require the transpiler to examine external sources, which might already have been transpiled, as such these design time decorators/annotations will have already been removed from these sources. So in my personal understanding this is not an option unless one wants to go for bytecode and Java / C# like package constructs.

And as far as my understanding of existing transpilers such as Babel and maybe also TypeScript goes, these only examine a single source file at a time and will rewrite that file, not considering any external files that might be imported, say using the import statement or, more hidden, the require() method.

@kitsonk
Copy link
Contributor

@kitsonk kitsonk commented Mar 4, 2016

Design time custom decorators/annotations just as in Java / C# would require the transpiler to examine external sources

Not necessarily. There is a set of typing meta data that is already inferred by the time the decorator would be invoked. TypeScript makes assumptions about the structure of external files all the time, which is how it accomplishes the intellisense when integrated into IDEs such as VSCode, using a number of different methods (including ambient declarations). This would essentially allow code to interface with that information direction at design time. Most of that is already in TypeScript type structures, since TypeScript is compiled with TypeScript.

@silkentrance
Copy link

@silkentrance silkentrance commented Mar 4, 2016

@kitsonk you are talking about IDE integration here, which is an altogether different thing.

As for decorators, please compare https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/Decorators.md to what is defined in here and you might see that it is actually the same.

As for design time vs. compile time vs. runtime. These are very different things. And just because the typescript compiler is able to compile itself, does not necessarily mean that it is capable of loading external entities and make that part of the AST during compilation.

@kitsonk
Copy link
Contributor

@kitsonk kitsonk commented Mar 4, 2016

@silkentrance @mhegazy is one of the core team working on TypeScript. I am pretty sure he understands the difference between design time and runtime decorators and how decorators work in TypeScript.

Actually IDE integration and how TypeScript compiles and emits code aren't very different. TypeScript gathers a whole lot of information, including transforming to an AST with appropriate typing information to be able to offer up Intellisense or code emitting.

And just because the typescript compiler is able to compile itself, does not necessarily mean that it is capable of loading external entities and make that part of the AST during compilation.

I am afraid it can and it does.

@silkentrance
Copy link

@silkentrance silkentrance commented Mar 4, 2016

@kitsonk so even if typescript was able to infer certain properties from an already transpiled source, it would have to annotate that source by certain means. looking at transpiled sources of typescript, I cannot find such annotations, though, it is still plain javascript.

As such, VCode or whatever the name of the IDE was, requires the original sources by which it is able to infer such idioms of the TypeScript language.

See the compiled source in the PLAYGROUND

@kitsonk
Copy link
Contributor

@kitsonk kitsonk commented Mar 4, 2016

With plain JavaScript (or already compiled TypeScript) TypeScript can understand the structure of those files using ambient declarations via .d.ts files. This is how the DOM and the rest of the built in APIs are typed. There are other tools out there can can generate the appropriate information so people can continue to build on-top of the emitted code. I happen to maintain once such tool. In those cases, TypeScript doesn't even read the source files.

As a side note, there is part of the TypeScript services called Salsa, which gives similar inferred typing information to plain JavaScript code being written in JavaScript. Those services can be enhanced with further data from .d.ts files as well and this is what is starting to power the intellisense in Microsoft Visual Studio Code (that "whatever" IDE I was referring to) when editing JavaScript files in that IDE.

Also, just to point out, this particular issue is part of the TypeScript Roadmap for 2.0 (the Ambient Declarations). So I am pretty sure the TypeScript know what they are talking about.

@silkentrance
Copy link

@silkentrance silkentrance commented Mar 4, 2016

Considering ambient decorators further, there cannot be custom ambient decorators unless they are part of the same source file. As such, these need to be made part of the language. See wycats/javascript-decorators#27

@silkentrance
Copy link

@silkentrance silkentrance commented Mar 4, 2016

@kitsonk you are talking about extraneous files generated by the compiler that are not part of any specification so far as I can see. So while this is a special case/behavior of the typescript compiler, it cannot be made a general feature as requested in wycats/javascript-decorators#27

@felixfbecker
Copy link

@felixfbecker felixfbecker commented Mar 9, 2016

Does this add anything that cannot be done with a jsdoc tag, like @deprecated?

@alexeagle
Copy link
Contributor

@alexeagle alexeagle commented Mar 30, 2016

+1 for a decorator-based suppression mechanism.
Now that tsc has additional control flow checks like --noImplicitFallthrough it would be great to have a general-purpose mechanism for suppression, both for third-party checks like tslint as well as first-party checks shipped with the compiler.
For my use case, I want to enable new static analysis checks globally across a large codebase (eg. angular2) and a suppression mechanism is a good alternative to fixing the problem, in the rare cases where the behavior is expected. (like a test that checks the behavior of implicit fallthroughs)

@alexeagle
Copy link
Contributor

@alexeagle alexeagle commented Apr 6, 2016

cc @chuckjaz
We would also like to treat Angular 2 decorators as 'design time' when we are compiling templates offline in a build step, since any emit for these decorators is dead code. They are fully converted by our codegen step.

@SergeyTeplyakov
Copy link

@SergeyTeplyakov SergeyTeplyakov commented Jul 8, 2016

@mhegazy Our team in TSE would be really grateful if this feature would be implemented.

@cspotcode
Copy link

@cspotcode cspotcode commented Sep 29, 2016

Another use case is enforcing an interface for the static side of a class.

declare function @StaticImplements<T>(t: T): T;
interface Foo { prop: string; }
@@StaticImplements<Foo> class MyClass { static prop = 'hello world'; }
@shlomiassaf
Copy link

@shlomiassaf shlomiassaf commented Jan 26, 2017

@mhegazy I understand why we need to pass constant value but why can't we pass lambda or functions? They are constant after all.

The logical barrier is design time vs run time data, if the function does not access variables outside of it's block it safe.

Seeing the list you specifically mentioned regexp literal I guess you mean that TypeScript will not eval the object that the decorator wraps.

Still, we can let the user code handling the input eval that code...

The first use case I can think of is sending instructions to the Angular AOT compiler, this is not possible at the moment which makes implementing custom decorators of angular DI elements / Components a problem.

Angular can work around that by coupling the core module with all decorators to the AOT compiler and inside declare those.

Another use case for AOT compiler is mixins, where you return a value from a function that gets a class, that class could not be a part of DI unless the AOT compiler can get notified that the type is the param sent to the mixin.

@jods4
Copy link

@jods4 jods4 commented Apr 27, 2017

Now that TS 2.3 has shipped an API for language plugins, I think this should get a priority boost.

Once you start adding framework-specific analyzers or language extensions, the need for additional metadata arises very quickly.

Basic decorators can be used for that, but they have the downside of emitting useless code. Even more so when combined with --emitDecoratorMetadata.

@alexeagle
Copy link
Contributor

@alexeagle alexeagle commented Apr 27, 2017

@jods4
Copy link

@jods4 jods4 commented Apr 27, 2017

(things like angular @Component are stripped before downleveling).
We should totally generalize that as a language service plugin.

Very interesting... It is my understanding that transforming the AST or codegen is explicitly a non-goal of Language Service plugins, so how would you do that?

I am very interested in being able to add/remove stuff from the generated JS code, including when building with tsc, but that seems out of the picture for now.

To the TS team: it's sad that we can't transform TS code, because transforming the downlevel JS code is much harder after types have been erased :(

EDIT: and it's sad we can't even add diagnostics when building with tsc. A plugin for a templating framework (say Angular) can add warnings/errors for incorrect binding expressions in the IDE, but if you then go on to build this in your CI everything is green.
Same for linting: it's great to now have immediate IDE feedback, but why do we need to run it separately on the command line?

@alexeagle
Copy link
Contributor

@alexeagle alexeagle commented May 5, 2017

@brn
Copy link

@brn brn commented Sep 18, 2017

Any update on this issue?
I'm come from Roadmap of wiki that is still written about Design-Time-Decorator.
Is CustomTransformer covered this issue? or continue to investigate this issue?

@Nufflee
Copy link

@Nufflee Nufflee commented May 27, 2018

I'm interested in implementing this (and have already started experimenting with the source code) but I'm not sure what the state of this issue is and if it's worth to open a pull request. I know I'm not supposed to open a pull request unless a issue's milestone is "Community" but in the roadmap it states "Investigate Ambient(, Deprecated, and Conditional) decorators" so I would like some clarification here. This is also mentioned in #20724 as "One day?".

@thetutlage
Copy link

@thetutlage thetutlage commented Mar 19, 2020

I see this issue being mentioned in the roadmap, so I hope this will get some attention soon. Just wanted to check, will design time decorators be able to define custom return types for a function? Example: #4881 (comment)

@kingsimba
Copy link

@kingsimba kingsimba commented May 21, 2020

With this feature, is it possible to write something like:

@@expose({name: "sockFile", since: 2.0})
domainSocketFile: string

It should be kept in .d.ts file. And it tells me that when serialize to JSON, it will be renamed to "sockFile", and it will only be serialized after version 2.0

@shicks
Copy link
Contributor

@shicks shicks commented Sep 15, 2020

I would also like to see this gain some traction. Here are a few use cases that we currently don't have a good solution for:

Part of the opposition to final as a built-in language feature is an argument that it can be implemented as a runtime check outside the language, but we all appreciate that compile-time checks are often preferred. Unfortunately, with ordinary decorators leaving no artifact in the .d.ts emit, it's impossible for a compile-time checker to see that an extended class or overridden method was annotated @final. (In this case, having both a design-time and runtime emit would be ideal, but if I can only get one, the .d.ts emit has much higher value). If we can address the contentious final issue with a design-time decorator, that might significantly decrease the unhappiness of the many people asking for it.

@@checkReturnValue also needs to be visible in the .d.ts since the primary use case is for communicating a library's API to the library's users.

@aminya
Copy link

@aminya aminya commented Nov 14, 2020

My use case for this would be to annotate some of the public methods as "experimental" which means that may change in the future.

class myClass {
	@@experimental("This method is experimental and may change in the future versions")   	
	doSomething() {
	}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet