Add support for Python-like decorators

[csnover]

Copied from CodePlex#1369

The current ES6 and TypeScript syntax for classes makes it difficult to perform any meaningful modifications to a function that is a member of a class without extreme effort. Libraries such as ember.js added additional properties to the Function prototype to augment the function with additional capabilities, but this is not feasible in the class syntax.

Something like Python decorators provide a possible mechanism to solve this problem. As per PEP-318, decorators allow you to define a function that can be applied to another function in place. For example, a naïve logging decorator might look like this:

// decorator
function log(fn: Function, metadata: DecoratorMetadata) {
  return function(...args: any[]) {
    console.log(metadata.name);
    return fn.apply(this, args);
  }
}

class A {
  // decorator application
  @log foo() {
  }
}

// execution
var a = new A();
a.foo(); // LOG: foo 

This provides a capability that allows for very expressive development against the class syntax that is far beyond C#-style attributes and allows for a number of uses including (but not limited to): logging, binding, composition, testing, control over ES5 property descriptors, AOP-like join-points, etc.

In addition to the general syntax borrowed from Python, a TypeScript decorator would accept an additional piece of metadata in the form of a DecoratorMetadata object, which contains contextual information about the target that is being decorated (such as a function, class, method, getter, setter, or even fields and parameters).

[danquirk]

One big concern here is ES compatibility. There's some discussion on a decorator feature in ES7 for example http://esdiscuss.org/topic/decorators-vs-annotations-was-april-10-2014-meeting-notes. We would need to make sure we align with that in the future.

On the type system side what do you expect the decorator to be able to do? Right now I think you'd find it difficult to type some of the things you'd want to do. Using Function above as the type gives you very little insight into fn.

[csnover]

Sorry for the delay!

On the type system side what do you expect the decorator to be able to do?

Optional compiler enhancements like @override (to warn when shadowing properties/methods), or @mixin (to …use mixins), or @deprecated (to warn when a deprecated method call is seen, and/or to augment generated documentation at the same time)

Something operating purely on the generated output would even be a great start. There are many use cases that are more annoying than they need to be right now because one cannot wrap class methods from within the class declaration. (You end up needing to wrap the prototype—and of course the type system starts getting in the way if any of the members aren’t public.)

[JeroMiya]

If we're going to provide an implementation, we should work with the Traceur folks to converge on a de-facto standard annotation/decorator spec and make sure it aligns with the actual standard going forward. Traceur's implementation is probably going to gain a lot of traction from AngularJS 2.0's use of it for dependency injection, so that would be a great place to start.

[csnover]

OK, I don’t know why this issue was never referenced from #1557 (or used instead) but apparently that one is the one that got all the attention so I’m closing this.

[DanielRosenwasser]

Sorry about that @csnover. I think it was distinct in that annotations are not necessarily the same as decorators, which is why we didn't file it as a duplicate.

[csnover]

No worries. Python decorators were mentioned in the first comment on that one so it seemed like there’s no reason to have it in two places. I talked to @mhegazy a few weeks ago and he described exactly what’s needed, so I know you guys know what’s what. :)