Add Support for design-time decorators

[mhegazy]

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

[matjaz]

what is the benefit of using ngdoc @deprecated https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation

[bradolenick]

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]

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]

@kitsonk can you elaborate on your proposal?

[kitsonk]

@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]

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]

@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]

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

[kitsonk]

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).