CS2 Discussion: Output: Classes

[rattrayalex]

This is a core feature that we should rally around submitting to jashhkenas/coffeescript in the near term.

Does anyone know of current leading efforts to accomplish this in the community? Perhaps we can lend a hand there.

[kirly-af]

This is discussed in jashkenas/coffeescript#4233 (and probably many others I'm not aware of).

Also, I just discovered this Redux PR thanks to @GeoffreyBooth which looks REALLY promising.

[GeoffreyBooth]

So it appears that someone has actually already implemented CoffeeScript class to ES2015 class—in decaffeinate. Check it out!

[DomVinyard]

I think there's probably a larger conversation to be had about decaffeinate specifically, how and where it intersects with this project, what can be borrowed, what can be adapted, etc.

[alangpierce]

Hi, I'm a decaffeinate contributor. While decaffeinate does have basic support for classes, full support is one of the main missing features right now. I'm hoping to improve it over the next few weeks, but it's definitely a challenge, since my understanding is CoffeeScript allows arbitrary code in class bodies, while ES2015 classes only allow methods. Decaffeinate also compiles CoffeeScript class fields to the public class fields proposed feature (currently stage 2), but even that has pretty significant semantic differences that have caused bugs for me (CS class fields are on the prototype, JS class fields are assigned to the instance once the constructor finishes). Anything other than methods or fields causes decaffeinate to crash.

[GeoffreyBooth]

Thanks @alangpierce. Yeah, after looking at it more I think the better solution is to redefine the class syntax in CoffeeScript to be something that translates directly into ES2015 classes, dropping support for ES2015-unsupported features like code in class bodies. This would be a breaking change in CoffeeScript, probably one that’s opt-in via a flag, but necessary if CoffeeScript is going to keep up with new features introduced by ECMAScript.

While the immediate focus is on adding support to CoffeeScript for missing vital ES2015 features (modules, classes), the longer-term goal especially of coffeescript6 is to update CoffeeScript’s output to use more of the latest standards. This essentially means we would be doing the work that decaffeinate is doing, but within the main CoffeeScript compiler. I skimmed through the decaffeinate repo, hoping to find some commits that highlight what differences it had from the main CoffeeScript compiler, but I couldn’t make sense of it. Do you mind giving whatever overview you can of how decaffeinate works, and where I should look for code that might be useful to repurpose in the main CoffeeScript compiler? For example, where is the code that generates an ES2015 class?

[mrmowgli]

I would love to see some way of extending the current class functionality to generate the ES2015 code, and then decorate with everything else. I guess I don't really understand what actually breaks and where yet though. I am assuming that ES classes have extra restrictions, ie that they aren't just objects with prototypes set in a specific pattern?

From the Babel overview:

ES2015 classes are a simple sugar over the prototype-based OO pattern. Having a single convenient declarative form makes class patterns easier to use, and encourages interoperability. Classes support prototype-based inheritance, super calls, instance and static methods and constructors.

So I would think we could construct functions only, then decorate with everything else?

[alangpierce]

@GeoffreyBooth Yep, dropping support for code in class bodies makes a lot of sense for your case.

Sure, I can give a quick overview of how decaffeinate works:

Unfortunately, I think the short answer is that decaffeinate's approach is pretty different from the CoffeeScript compiler, so you may not be able to use much code/logic. From my reading of the CoffeeScript compiler, it parses the input to an AST, then calls the recursive compileNode method (and related methods) to generate a big JavaScript string that becomes the output file. Decaffeinate works by parsing the input into an AST (and a token sequence), then using that AST to inform targeted transformations on the code (inserts, removes, and replacements) using the magic-string library. For example, to compile a b, it uses the AST to see that it's a function call, looks at the tokens to see that there's no open-paren or close-paren, and replaces the space with a ( and inserts a ) after the b (code here). This approach makes sense given decaffeinate's goal: it doesn't want to rewrite all of your code, it wants to tweak it (sometimes significantly) to be valid JavaScript, maintain formatting and comments as much as possible. But really, this approach ends up being a big pain sometimes, and transforming the code to a JavaScript AST would probably be more robust in a lot of ways (but would lose formatting).

A little more information on how decaffeinate is structured: it consists of five "stages" (one CoffeeScript -> CoffeeScript, one CoffeeScript -> JavaScript, and three JavaScript -> JavaScript), the most important of which is the CoffeeScript -> JavaScript stage, which is called MainStage. For that stage, every type of AST node corresponds to a Patcher class. Each Patcher is a class that knows what kind of modifications to make to transform that type of CoffeeScript node to JavaScript.

Here's a repl link that has some examples of what happens in different stages. You can change the "run to stage" selection to see the intermediate result after each stage (or intermediate lexer/parser results).

I actually haven't worked with the class generation code, but was able to mostly figure out how things work. If you look at the decaffeinate-parser output for your example, you can see that the main AST hierarchy is Class > Block > ClassProtoAssignOp > Function. From the node name to patcher class mapping, (or by just looking at the names), you can see that they map to the classes ClassPatcher, BlockPatcher, ClassAssignOpPatcher, and FunctionPatcher. The methods patchAsStatement and patchAsExpression are generally the most important ones. As one example, ClassAssignOpPatcher extends ObjectBodyMemberPatcher, which calls this.expression.patch with the method flag set appropriately. On the FunctionPatcher side, it knows that it should skip the function keyword if the function is being patched as a method.

Also, here's a writeup with some more details:
https://github.com/decaffeinate/decaffeinate/blob/master/docs/contribution-guide.md

Hope that helps!

[GeoffreyBooth]

I don’t think we can simply redefine the class keyword, even behind a flag. That would be too drastic a breaking change for current projects to handle, including the CoffeeScript compiler codebase itself (which uses class extensively). I think we need to provide a clear and easy upgrade path, especially if we’re adding ESNext class support to the original compiler.

How about this approach: we create a new CoffeeScript keyword, esclass, that has different syntax than the current class. It only allows things that can be output into an ESNext class, and it compiles into ES output (so class is in the generated JavaScript, not function).

With esclass, a CoffeeScript project could contain both new compile-to-ESNext-class classes and legacy old compile-to-function classes. People could convert a project gradually, or pick and choose which type of classes they want to use (for example, esclass could be used when extending a class imported from another library, with class used for all classes particular to your project). Having two types of classes would also let us keep the CoffeeScript compiler codebase intact without major changes.

Introducing a new keyword that wasn’t previously reserved is a breaking change, so we would need to introduce a flag. I think since esclass is so obscure a string, it’s unlikely that there are many (if any) projects out there using it already as a symbol; so maybe we could get away with shipping it reserved by default, so that the vast majority of projects need not do anything to take advantage. For the 0.001% of projects using esclass already as a variable or function name (and who don’t want to refactor), they would need to set the flag to force legacy support. The flag could work something like this:

• Default, no flag: The class keyword would retain its current syntax, and esclass would become a new reserved word that introduces a new syntax that compiles into ESNext classes.
• --legacy-classes: The current behavior. class is unchanged, and esclass is not a reserved word.

We could even add support for making class an alias for esclass and csclass an alias for the current class, if we want to let people use the class keyword for the new syntax; but I’m concerned that it’s probably a bad idea to not be able to look at code and know how it will get compiled, if you don’t know what flag will be set in the compiler.

Conversely, it might be a good idea to introduce csclass as a new reserved word that always aliases to the current class syntax, so that people could use esclass and csclass exclusively, leaving no ambiguity about what their intentions are.

What do you all think? @lydell, @rattrayalex, @JimPanic, others . . .

[JimPanic]

I like the idea of csclass & esclass although we might want to find better names. I also am not sure yet what the differences in semantics are. It seems there is a bit more to it than just syntactic sugar as the ES201x class does not allow data properties, has different grammatical rules than object literals and cannot be called without new (if I read that correctly).

Apart from that, I think the only solution to introduce this to users is a) with conversion tools and b) through a process of deprecation warnings, deprecation and removal over several releases. This is something we have to plan, no matter what keywords we use in the end.

The only thing that could be dangerous is to keep the class keyword to stay semantically different from the one in ES201x. Its meaning has to change eventually.

[lydell]

Here's my vote:

Add esclass for ES2015+ classes. Make no other changes whatsoever.

Release it by bumping the middle version number, keeping CoffeeScript's current versioning scheme of bumping the middle number when there are new features an slightly-but-not-very breaking changes. (As @GeoffreyBooth it is very unlikely that this will cause any trouble for anyone.)

No csclass. Do we want csin, csof, csfor etc. too?

CoffeeScript 2.0.0: Remove old class, rename esclass into class (and do similar things for other ES2015+ features) and switch to semver.

[GeoffreyBooth]

I guess we probably don’t need a flag if we’re simply adding esclass (or whatever people decide to name it) and leaving class alone. It would be a breaking change to anyone who was already using esclass as a symbol, but maybe rather than giving them a flag to opt out we should just recommend they simply don’t upgrade (or that they refactor). It’s a very minor refactor to find and replace all instances of esclass with something else, we wouldn’t need to provide migration tools for that.

My god, did we just come up with a way to implement classes without a flag? 😛

[JimPanic]

I think we did, yes. 🤔 I'm also very much in favour of implementing semver.

[greghuc]

I like the idea of a separate esclass as a 'least breakage' way forward. However, I'm less comfortable with how the eventual replacement of Coffeescript's class with esclass could pan out.

At present class let's me do some nice things: instance functions, static functions, private static functions and 'constants'. I've written a short example class below. If esclass doesn't eventually support these class capabilities, then this is a step backwards for Coffeescript. Though you could argue that if ES2015+ classes can't handle this, then that's a step backwards too!

Example:

  class ClassExample

    CONSTANT_EXAMPLE = 'I am a constant example'

    constructor: -> console.log 'I am a constructor'

    instanceFunction: ->
      console.log '[start] I am an instance function'
      console.log CONSTANT_EXAMPLE
      privateStaticFunction()
      @constructor.staticFunction()
      console.log '[end] I am an instance function'

    @staticFunction: ->
      console.log '[start] I am a static function'
      console.log CONSTANT_EXAMPLE
      privateStaticFunction()
      console.log '[end] I am a static function'

    privateStaticFunction = -> console.log 'I am a private static function'

  # Example calls
  #ClassExample.staticFunction()
  (new ClassExample).instanceFunction()