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 · 39 comments

Comments

Projects
None yet
@mhegazy
Contributor

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

This comment has been minimized.

matjaz commented May 12, 2015

@bradolenick

This comment has been minimized.

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

This comment has been minimized.

Contributor

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

This comment has been minimized.

Contributor

mhegazy commented Jan 22, 2016

@kitsonk can you elaborate on your proposal?

@kitsonk

This comment has been minimized.

Contributor

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

This comment has been minimized.

Contributor

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

This comment has been minimized.

Contributor

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

This comment has been minimized.

Contributor

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

This comment has been minimized.

Contributor

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

This comment has been minimized.

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

This comment has been minimized.

Contributor

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

This comment has been minimized.

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

This comment has been minimized.

Contributor

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

This comment has been minimized.

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

This comment has been minimized.

Contributor

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

felixfbecker commented Mar 9, 2016

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

@alexeagle

This comment has been minimized.

Contributor

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

This comment has been minimized.

Contributor

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.

@alexeagle

This comment has been minimized.

Contributor

alexeagle commented May 9, 2016

Yes, thanks for the corrections, and yes Java's annotation retention is
part of my background as well.
We could already do this ourselves, I think the point of this issue is to
search for a design which serves our needs as well as other TypeScript
users. Perhaps this means a tsc option which allows any meta-decorated
decorator to have static annotation-style emit.
Will sync with Misko and give a more complete proposal...

On Mon, May 9, 2016 at 1:13 PM Carsten Klein notifications@github.com
wrote:

@alexeagle https://github.com/alexeagle Why do you not just decorate
the decorators of your framework, and for which you will generate code for,
with a specific decorator?

In Java, there are annotations which have a specific retention policy,
e.g.

https://deors.wordpress.com/2011/10/08/annotation-processors/

https://docs.oracle.com/javase/7/docs/api/java/lang/annotation/RetentionPolicy.html

So my best guess would be to annotate your decorators with for example

// Strawman
//@ambient
function AngularDecorator
{}

@AngularDecorator
function ComponentFactory() {}

And then check in your code emitter whether the decorator has been
decorated using the @AngularDecorator.


You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#2900 (comment)

@silkentrance

This comment has been minimized.

silkentrance commented May 9, 2016

@alexeagle here you lost me 😁

@alexeagle

This comment has been minimized.

Contributor

alexeagle commented May 9, 2016

For our special decorators, we don't drop them altogether, we just emit
code that looks like static annotations (the metadata is attached directly
as properties on the function{

On Mon, May 9, 2016 at 1:42 PM Carsten Klein notifications@github.com
wrote:

@alexeagle https://github.com/alexeagle here you lost me [image: 😁]


You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#2900 (comment)

@unional

This comment has been minimized.

Contributor

unional commented Jun 5, 2016

Should we consider using this in place of directive to solve the interop problem?
#7398

@SergeyTeplyakov

This comment has been minimized.

SergeyTeplyakov commented Jul 8, 2016

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

@cspotcode

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

Contributor

alexeagle commented Apr 27, 2017

@jods4

This comment has been minimized.

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

This comment has been minimized.

Contributor

alexeagle commented May 5, 2017

@brn

This comment has been minimized.

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

This comment has been minimized.

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?".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment