Proposal: Annotations (alignment with Traceur/AtScript)

[JeroMiya]

Summary

• Implement annotations in TypeScript.
• Align with Traceur and AtScript on syntax and ES5 representation.
• Implement feature similarly to modules, with the following settings for output representation:
  • -annotations=none (default) - Annotations not supported by default. Produce compiler errors when used.
  • -annotations=atscript - Annotations encoded in the style of traceur/atscript (this proposal)
  • (future) -annotations=ecmascript - Hypothetically, if ES.Vnext were to adopt annotations, this would represent them using the approved ES7 annotation syntax, whatever that would be, as a bridge while TypeScript aligns with the official syntax (similar to how TS modules will transition).
• In the long term, align with ECMAScript, if an annotation proposal is accepted.

Prior Art/Reference

• Traceur and by extension AtScript (this proposal)
  • https://docs.google.com/document/d/11YUzC-1d0V1-Q3V0fQ7KSit97HnZoKVygDxpWzEYW0U/mobilebasic?viewopt=127
• Ember decorators
  • Uses "- decoratorName(decoratorArgs, ...) decoratorTarget"
  • Decorators can mutate the target class/field/argument(?). This proposal involves only inert metadata.
• tc-39 April 10 2014 Meeting Notes
  • https://github.com/rwaldron/tc39-notes/blob/master/es6/2014-04/apr-10.md#decorators-for-es7

Motivation

• This proposal improves alignment between TypeScript and AtScript (and Traceur), improving interoperability between TypeScript code and code using these features of those compilers.
• Annotations are useful in certain scenarios like dependency injection, domain driven design, decorator pattern, and more.

Differences from AtScript/Traceur

• Run-time type metadata, runtime type checking, etc... is beyond the scope of this proposal.

Syntax and ES6 Representation

I am proposing the AtScript/Traceur syntax and ES6 representations, necessarily verbatim (minus the type annotations). An annotation can be applied to a function, a class, the constructor of a class, a field of a class, or a function argument:

function:

@MyAnnotation('argument')
function func() {}

// ES6 representation
function func() {}
func.annotate = [ new MyAnnotation('argument')];

A class:

• Same representation as a function, of course.

@MyAnnotation('argument')
class MyClass {}

// ES6 representation
class MyClass {}
MyClass.annotate = [ new MyAnnotation('argument') ];

A constructor of a class:

• Note: exactly the same as annotations on the class. Constructors are listed last in the list in the ES6 representation, after class annotations.

@MyClassAnnotation('argument')
class MyClass {
   @MyConstructorAnnotation('argument')
   constructor() {}
}

// ES6 representation
class MyClass {
  constructor() {}
}
MyClass.annotate = [ new MyClassAnnotation('argument'), new MyConstructorAnnotation('argument') ];

A field of a class:

• Note: in AtScript/Traceur, the objects to the right of the field name also have an 'is' field at the same level as the 'annotate' field. I have omitted the 'is' fields below (RTTI is out-of-scope for this proposal).

class MyClass<T> {
  @MyFieldAnnotation('argument')
  field: T = null;
}

// ES6 representation:
class MyClass {
  field = null;
}
MyClass.properties = {
  'field': { annotate: [ new MyFieldAnnotation('argument') ] }
};

Arguments to a function:

• Including arguments to constructors.
• Note: In Traceur/AtScript, objects in the parameters array also have an 'is' field which is a reference to the type of the argument. That is omitted from the following examples (RTTI is out-of-scope for this proposal).

function func<T>(@MyFuncArgumentAnnotation('argument') arg: T): void {}

class MyClass<T> {
  constructor(@MyConstructorArgumentAnnotation('argument') arg: T) {}
}

// ES6 representation
function func(arg) {}
func.parameters = [ { annotate: [ new MyFuncArgumentAnnotation('argument') ] }];

class MyClass {
  constructor(arg) {}
}
MyClass.parameters = [ { annotate: [ new MyConstructorArgumentAnnotation('argument') ] }];

Extensions to lib.d.ts to support typing of annotations

• e.g. adding 'properties', 'annotate', and 'parameters' field typings to Function interface.
• Can be done by a third party/DT/etc... without changes to the compiler.

[spion]

My 2c: as they're defined in AtScript now, annotations have a couple of nasty problems

1. They don't compose. If you need to add 10 annotations to 5 fields, and they only differ sligtly by one parameter, you will need to copy-paste all 10 fields, 5 times. You can't abstract them behind a single annotation.
2. They use new. A factory function is more appropriate - that way they wont have to be defined as classes.
3. They're passive and therefore limited in power. The standard practice in JS is to wrap functions/objects/properties using other functions, e.g.

Item.prototype.method = wrapper(function() { 
    //... 
});

Angular, Ember and other frameworks already do this kind of wrapping (e.g. see angularModule.factory or ember computed properties, etc). If annotations were added to the language, I'd think they should reflect this. Its quite easy to implement passive annotations on top of it.

One of the TC39 proposals mentioned in the document above works like this. Its similar to Python's and I think thats what AtScript, TypeScript and ES7 should aim for.

[JeroMiya]

As an aside, using new with a factory function will work as expected. The return value of the factory function will be used. However, I concede that it isn't idiomatic javascript, and causes an unnecessary object creation.

That being said, I think I can address 1 and 2 in one or two ways (one would require the ES6 splat operator, the other wouldn't):

With just the proposed syntax above, note that you can still set annotations directly, giving you control over composition and factory vs new:

function getCommonAnnotations() {
  return [new A1(), new A2(), a3FactoryFunc()];
}
function annotationFactoryFunc() { etc... }
class MyClass {
    // I'm using the spread operator here, but I could have just created a wrapper func
    static annotations = [...getCommonAnnotations(), annotationFactoryFunc()];
}

Or, if you really want composition in the syntax, then I would propose the following alternate array syntax, which would require the ES6 spread operator. The following would be equivalent to the above sample:

@[...getCommonAnnotations(), annotationFactoryFunc()]
class MyClass {}

I think either of these is sufficient to overcome concerns 1 and 2. With respect to your third comment, I specifically avoided "decorators" in this proposal. First of all, you don't really need new syntax for decorators - as you said, function wrappers give you everything you need, and the syntax is already about as concise as it could possibly be.

Secondly, mutating decorators have implications for typing. If a decorator modifies the prototype of the class it is applied to, say adding a set of functions, how does TypeScript know? You could annotate the class with an interface, but you'd have to stub everything that the decorator adds to your class first, because the TypeScript compiler can't tell that a decorator added implementation for the interface. And even if you stubbed the fields out, the interface check is effectively turned off, because you can't enforce that the decorator is adding fields/methods that match the interface anyway. In those kinds of cases, I think using the type system for that kind of type augmentation is a superior option, especially if we support mixins.

Finally, I think there really should be a separation between decorators and annotations. Decorator functions/wrappers are good candidates for being consumers of the metadata. Making annotations inert also improves their reliability - It would cause a lot of confusion to have to track down issues related to mutating annotations. There's no way to document to the type system (and thus the programmer), what it is that the mutating annotation is doing to your type, field, function argument, or method. Thus, I propose a more conservative passive approach to annotations.

[spion]

Yes, its important that all language features compose easily so that we don't end up with something like this. The spread operator solution would be okay but it kinda breaks the abstraction barrier. The developer should not have to know whether the annotation they're using is composite or not.

First of all, you don't really need new syntax for decorators - as you said, function wrappers give you everything you need, and the syntax is already about as concise as it could possibly be.

New syntax is necessary mostly because they are not allowed inside class definitions in ES6. This is also why Yehuda proposed them when they switched Ember to ES6 (iirc - i can't find the right esdiscuss thread)

Secondly, mutating decorators have implications for typing. If a decorator modifies the prototype of the class it is applied to, say adding a set of functions, how does TypeScript know? You could annotate the class with an interface, but you'd have to stub everything that the decorator adds to your class first, because the TypeScript compiler can't tell that a decorator added implementation for the interface. And even if you stubbed the fields out, the interface check is effectively turned off, because you can't enforce that the decorator is adding fields/methods that match the interface anyway. In those kinds of cases, I think using the type system for that kind of type augmentation is a superior option, especially if we support mixins.

You're right that there would be type problems with decorators. Mutation would be tricky to model. Maybe decorators could always return new values instead mutating them, and intersection types (similar to union but using &) could be used to model augmentation. Or maybe the mixin mechanism will be able to help there...

I agree with most of the benefits of inert/passive annotations that you mentioned.

Overall, I feel it may be too early to add annotations to TS. The proposal is (barely?) in the strawman stage for ES7+. Angular/AtScript are just now starting to experiment with what annotations would mean - it may still turn out that their design is flawed...

[JeroMiya]

We can't make too many assumptions about how application code will consume annotations, but, assuming it checks for matching constructors recursively up the prototype chain - couldn't we just use the type system to compose annotations to avoid the situation you linked? It would of course require mixins (specifically, mixins which rewrite the prototype chain in a linear fashion, using a linearization algorithm as is done in scala), but you could just create sub-type annotations that mix in the aggregation of common annotations. You wouldn't then need the spread operator, explicit, or alternate array syntax to make it work.

class A {}
class B {}
class C {
  constructor(private value: string) {}
}

// compose!
// note: hypothetical syntax for mixins
class CompositeAnnotation with A, B, C {
  constructor() {
    // note: hypothetical mixin base class initialization syntax
    super<B>('specialized value');
  }
}

@CompositeAnnotation
class MyClass {}

Also, third party libraries could provide their own composition functionality for attributes, say with an aggregate annotation that takes an array of annotations.

[sophiajt]

Good stuff! Annotations are definitely something we're interested in for TypeScript. I'm going to ping @mhegazy, who has been working on an annotations proposal, too. This would be right up his alley.

[EisenbergEffect]

It should be noted that there is broad experience with annotations. This feature is based on Java annotations and C# attributes and the use cases are similar. Additionally, the Angular and Aurelia teams have been using them successfully for at least a year now and the usage patterns are pretty well known. Aurelia has a metadata abstraction library that handles location of annotations and manipulation including inheritance chains.

I don't see composition as being essential. It's not something people did on other platforms and the Angular and Aurelia teams haven't needed that. Adding and reusing massive amounts of annotations doesn't seem like something common. I think the spread operator can handle this nicely in the very few number of cases where it comes up.

I see decorators as a fundamentally different concept. Annotations are about having a standard way to associate metadata with functions and class members, that's pretty much it.

Note: I'm not sure if AtScript/Tracuer is up to date with the current spec they have published. If you try it out on the online REPL it generates the older syntax. Probably should check with them to see what the status of that is and why it doesn't match their proposal.

[spion]

@EisenbergEffect As long as a single library is the consumer (e.g. the framework), I agree. However when there are multiple consumers, things might quickly get out of control.

FWIW the example I linked contains the following code:

@XmlElementWrapper(name="orders")
@XmlJavaTypeAdapter(OrderJaxbAdapter.class)
@XmlElements({
   @XmlElement(name="order_2",type=Order2.class),
   @XmlElement(name="old_order",type=OldOrder.class)
})
@JsonIgnore
@JsonProperty
@NotNull
@ManyToMany
@Fetch(FetchMode.SUBSELECT)
@JoinTable(
    name = "customer_order",
    joinColumns = {
        @JoinColumn(name = "customer_id", referencedColumnName = "id")
    },
    inverseJoinColumns = {
        @JoinColumn(name = "order_id", referencedColumnName = "id")
    }
)
private List orders;

and composition is important because it would be great if it was possible to reduce it to something at the same level of abstraction e.g.

@SerializableTo(name="orders");
@BelongsTo('customer')
private List orders;

[EisenbergEffect]

@spion I agree that we don't want to see that. Personally, I would choose to solve this issue at the framework level by making something like @SerializableTo internally aggregate the other annotations. Something like @JeroMiya shows would also be interesting, especially since Mixins would be a nice feature in their own right.

That said, I would be willing to concede to the decorator approach, especially if that looked like the direction that TC39 was going to move in. Since I'm still interested in metadata mostly, it would be pretty easy for me to author a set of decorators that simply put data in a location that my framework knows to look. I could publish that library as a simple ES6 module and then developers working with languages that support it could simply import the library and use them. The more I think about it....I'm liking this decorator approach. It would provide a lot more flexibility in the end.

[EisenbergEffect]

@spion How would the decorator proposal handle constructor parameters and class fields? It seems that it breaks down in those scenarios... (I don't personally have an interest in that...mostly methods and accessors, but just curious.)