CS2 Discussion: Features: Java-like Annotations

[objectkit]

Hello there. This project looks likes its starting in the right place and has my attention! I'm opening this topic here as a complete stranger, hopefully appropriately, as discussion seems to be the starting point of this project, which strikes me as the right way considering there are so many opinions about CS and its relationship to ECMAScript.

Personally I'd like to see what others would suggest as appropriate language features to adopt, and I hope others would too. Such discussion interrelates strongly with how we define and obtain an AST, and how an AST can be used in pre-compilation, post-compilation and transpilation phases, so hopefully what is said here by contributors will influence or at least shape this choice. Perhaps the most important choice?

My personal offering relates to wanting at least the introduction of `annotations' and to discuss how they can be used, via programmatic AST introspection to shape the output at the tranpilation phase. This way IOC and AOP could be introduced which IMO would save a ton of time. The short version is that I would like this language to introduce something similar to Java annotations with a workflow not dissimilar to Spring Framework. Plus static property references, introduction of the legendary implements keyword, import statement stylistics, super methods....

# some kind of import statement support
import WebService from web/services # slashes?
import app.login.model.UserService # implicit path slash from '.'?
import annotations/ioc/Component
import Inject from annotations.ioc

###
Registering this class as an IOC component via annotation. Construction
would take place in a bespoke container available post compilation? 
###
(Service "loginService")
class LoginService extends WebService implements UserLoginService

    ### 
    An annotation to inject a value from an external file?
    Static properties in keeping with ES2016?
    ###
    (Autowired)
    static LOGIN_SERVICE_ENDPOINT

    constructor: ->
        # implicit reference to static properties?
        super LOGIN_SERVICE_ENDPOINT

    ###
    @param UserProfile userProfile
    @return WebRequest
    ###
    login: (userProfile) -> @post "/login", userProfile

    ###
    @override
    @param String path
    @param Object object
    @return WebRequest
    ###
    post: (path, object) ->
        # referencing super class methods via super?
        super.post path, JSON.stringify object


    ###
    AOP should be defined elsewhere, but for example, associate
    execution of this method when any WebRequest issued by the
    post method above fails...
    ###
    (After "loginService.post.WTF") 
    handleRequestError: (thrown) ->

That is a lot of noise. Over typed, but I hope you see what I'm getting at. Annotation processing would not determine how the annotations are used (they would just be present in the AST metadata), but the AST (or a Reflection api) would know about them, and they could be read and associated with method invocations elsewhere by script injection after the pre-compilation phase? (phases need to be defined). Perhaps annotations are essentially non-executable in-line meta data that show the declaring point?

Unless its completely lost in the noise, I am particularly fond of Spring Framework (and also PicoContainer to some degree). I believe a workflow facilitated by annotations would be immensely useful on the client and the server... To support Annotations in the language specification would be absolutely fantastic. Configuration files external to the implementation used in configuration with "Autowired" or something similar? Yes please!

So with annotations as language feature request out of the way, any one else have an ideal they would like to see in this successor to CoffeeScript? Perhaps we could make this a noise thread which can later be broken up into individual topics if theres enough interest gained?

Anyone else care to throw standalone language feature requests in here?

late night - will tidy later :)

[carlsmith]

Welcome to the discussion @objectkit. We're all pretty loosely knit here at this stage, so you're totally welcome to just weigh in with whatever input you have, as far as I'm concerned anyway.

To summarise your request, are you asking for what Python3 calls gradual typing, using type hints - type annotations that have no defined semantics, and are pure meta for people to use however they like? In Python, the values of the annotations are available at runtime, not just in the AST, which seems helpful, but will inevitably involve introducing properties to the namespace. It's an interesting idea. That said, it looks like we're converging on creating a minimally different language, that just adds ES6 compatibility at first, then adds novel stuff later. CoffeeScript not being able import ES6 modules or extend ES6 classes is beginning to make the language obsolete, so saving CoffeeScript from that fate must be our priority.

Having an open issue for bikeshedding feature requests makes sense. If anything discussed in #5 gains traction, we can open a new issue for that specific feature.

It's worth keeping in mind that we're in a very different situation to when Jeremy designed CoffeeScript. He was trying to fix problems that JS no longer has, and was way ahead of TC39. We're now behind the curve, playing catch up. It would of been silly in 2009, but now there's a case for just following TC39, only implementing features that are in the spec already. We don't have to be religious about it, especially when we're only adding sugar, but we could avoid a lot of problems, like we've had with class incompatibility, if we followed the spec, and always compiled new features to the new JS syntax. If we want a new feature that is more than just syntax, we may be better of contributing to ESDiscuss and pushing TC39 to add it to JS. That approach would add a lot of overhead to getting a new feature accepted, but would also ensure we have a much more robust process for evolving the language.

[rattrayalex]

I'm opening this topic here as a complete stranger, hopefully appropriately

Absolutely!

[rattrayalex]

I don't personally understand Java Annotations, never having worked from them. They do seem unrelated from Type Annotations (à la Flow, PEP484, etc).

@objectkit is it possible that what you'd like to do could be solved by ES7 Decorators? (Either way, that's probably a feature we'll want to include).

I'm not quite sure I understand the underlying benefit of Java Annotations, but it may be that SweetJS macros could provide what you're looking for as well. It's very unlikely that sweetJS support would be included in this project, however.

FWIW, I do have strong interest in supporting Flow annotations, but doubt that it'll be possible without significant changes to the coffee compiler. That belongs in a separate issue.

[rattrayalex]

Having an open issue for bikeshedding feature requests makes sense.

Actually, I think it might be best to separate out proposed language features into separate issues, since github comment threads don't support threading well. Does that sound good to you @carlsmith ?

@objectkit I updated the title to reflect what I understand to be the primary suggestion of this issue – feel free to update it for accuracy!

[carlsmith]

Actually, I think it might be best to separate out proposed language features into separate issues, since github comment threads don't support threading well. Does that sound good to you @carlsmith ?

Yep. Sorry. You're right. Cool.

[objectkit]

@carlsmith @rattrayalex - Great to hear back from you and thanks for the welcome! Changing the title is fine by me - perhaps we adopt Language Feature Proposal : X as a formalism moving forward? That would keep this thread focused on annotations at least :)

What I was suggesting is somewhat similar to ES7 decorators. When I get the time next week, I'd like to provide a gist to depict an example / hypothetical use case focused on annotations and IOC just to make the case for them. I developed a CS tool that parses virtual annotations from comments in order to associate annotations with declaring nodes. The problem is CS AST requiring a two tier compilation cycle (pre-compilation analysis of virtual annotations followed by code injection before recompilation and then transpilation to ES4 using CS 1.10.0).

I will never post from an iPhone again! Hope what I've written here makes sense- looking forward to following the project :)

[objectkit]

I've had some thoughts about annotations in relation to decorators, and I have to say, they are not dissimilar at all! My vote is to go with decorators in the long term, but there are still a number of points about annotations and how they differ from decorators.

To the best of my knowledge, once decorators are declared, they execute immediately. For example, if we had an dependency injection solution that had a @Inject decorator that worked like any of the following:

class Controller
    # using decorators in conjunction with implicit setters derived from a property declaration??
    @inject model: null

class Controller
   # decorating a setter...
   @inject
   set model (@model) ->

In either case, the @Inject decorator would be informed of the class and the property that is being changed. It could look up the model instance assuming there is a DI container with a component named 'model' in it, and the decorator has access to it...

but my understanding is that the decorator would be executed at the time it was declared, so making allowances for asynchronous instantiation in a DI container.... there is no guarantee that is would work unless decorators would work at time of instantiation, e.g., when instantiating a new Controller, as opposed to every instance of Controller having the same injection going on. It could work, but I think annotations should be available as metadata from the AST via a Reflect API, and then and only then, processing of annotations would take place...

I've probably confused things more there, but hope not. Bottom line, decorators are great and bring them in, but as far as I can see, or have failed to see, annotations and decorators are not exactly the same thing.

[objectkit]

Update: application of decorators at class level definition are actually fine - a DI container could use the meta data from a decorator to configure a Factory, when async instatiation is not a problem once all dependencies are met.

I'm feeling like this leaning towards a close, as if decorators are going be implemented then, bar the open question of constructor decorators (needed!), parameter decorators (please) and property decorators (via implicit getters and setters??)... decorators can function as annotations.

Thoughts? Close this and join the decorators thread?

[carlsmith]

+1I'm against special syntax for type hints and annotations. CoffeeScript syntax already allows users to annotate functions with decorators. Anyone disagree??

[carlmathisen]

Here's an example of someone creating a decorator for runtime type checking. https://github.com/jdpedrie/es7-decorator-types

[carlsmith]

@rattrayalex - Shall we put this decision in the wiki? It seems the current consensus is to have no special syntax for annotations, and recommend using decorators instead. We can include @carlmathisen's link too. Even if we end up needing to add special syntax for decorators, we definitely should promote using decorators more. They're meant to be reused, so we can easily share them as gists, and build a page for them in the wiki. I'd be happy to add enough to get it started.

[mrmowgli]

I agree that this sort of thing should not be a language specific "feature" since you can actually do this just fine with comment sections.

I also have personally found that annotations often reduce readability and especially when used as another pre-processor element. It's much harder to deduce the results created by introducing side effect code.

There's nothing keeping you from running code parsers on comment sections, but I think that it doesn't add to the simplicity of the CS syntax by making it a language fixture.

[carlsmith]

I agree, personally, but still, TypeScript is pretty popular, and people do keep asking for some way to enforce types, often just during development. Static types can be useful, but making CoffeeScript statically typed is going way too far, so it was worth looking at type hints.

Just generally, it's important to try and establish some kind of community consensus on these issues if we want to get as many people as possible to see this project as the best way to take CoffeeScript forwards.

The advantage of decorators over comments is that they can wrap the function when it's defined with a function that can check and enforce the types of the arguments and the return value. You don't need a separate parser. They can also bind doc strings to the function when it's defined.

But yeah, we can use decorators well enough that we don't need to add special annotation syntax, which would make CoffeeScript functions much uglier.

[JimPanic]

Maybe someone comes up with a coffeescript-y way of annotating types in an opt-in fashion that we can all agree on in the future. But it's probably best not to give it high priority at this point.

That said, I do like the idea and would love to see this feature in CS at eventually. 👏

[rattrayalex]

I get the feeling we're confusing Type Annotations with Java-style Annotations.

In any case, I think the latter (which this thread is about) can be supported through a combination of comments, decorators (with or without syntactic sugar) and type hints (which could also come through decorators).

@JimPanic AFAICT, you're referring to type annotations there – so I don't see any objection to closing this.

So I'll go ahead and close this issue for now. Don't think we need to add it to the wiki. If my blurry eyes missed some strong support for this feature we can re-open.

[objectkit]

👍

[coffeescriptbot]

This issue was moved to jashkenas/coffeescript#4904