Decorators Stage 2 Parsing #587

peey · 2017-06-17T20:38:44Z

Q	A
Bug fix?	no
Breaking change?	no
New feature?	yes
Deprecations?	no
Spec compliancy?	yes
Tests added/pass?	yes
Fixed tickets	#13, #33
License	MIT

Adds a decoratorsStage2 plugin which can be used instead of decorators plugin but both cannot be used together
Does not interop with class fields. This functionality will be added later when the class fields and unified class fields advance
Disallows the following
3.1. Computed key on decorator e.g. @dec[foo]
3.2. Parameter decorators
3.3. Object methods
3.4. export keyword in between of class body and decorators
Allows the following
4.1 Decoration of computed class method names (Decorators on computed class method names #33)
4.2 Decoration of generator functions (Unable to decorate generator functions #13)

In some places, I've chosen to throw custom errors like "Stage 2 decorators do not allow parameter decoration" instead of throwing unexpected token so as to help people migrate and to make these changes explicit and less confusing.

Rationale for PR

The disallowed features are much loved but unfortunately either aren't a part of the proposal yet or have been discarded, therefore there is no clear answer on how to transform them.

This PR and associated plugin for stage-2 decorators is going to be opt-in for those who want to start writing what's currently stage-2 approved in the decorators proposal.

Ping @bakkot - #353; @DrewML - #236

Refer to PR babel#353

Parse stage 0 decorators when "decorators" plugin is active and parse stage 2 decorators when "decorators-stage-2" plugin is active

And add tests to reflect the same

For stage 2 decorators

Add tests for static properties and private properties

codecov · 2017-06-17T20:50:22Z

Codecov Report

Merging #587 into master will decrease coverage by 0.14%.
The diff coverage is 96.66%.

@@           Coverage Diff            @@
##           master   #587      +/-   ##
========================================
- Coverage   98.15%    98%   -0.15%     
========================================
  Files          22     22              
  Lines        3680   3712      +32     
  Branches     1026   1036      +10     
========================================
+ Hits         3612   3638      +26     
- Misses         25     27       +2     
- Partials       43     47       +4

Flag	Coverage Δ
#babel	`79.87% <10%> (-0.84%)`	⬇️
#babylon	`96.79% <96.66%> (-0.03%)`	⬇️

Impacted Files	Coverage Δ
src/parser/expression.js	`96.94% <100%> (+0.01%)`	⬆️
src/parser/lval.js	`98.06% <100%> (+0.02%)`	⬆️
src/index.js	`100% <100%> (ø)`	⬆️
src/parser/statement.js	`99.14% <95.45%> (+0.02%)`	⬆️
src/parser/comments.js	`85.91% <0%> (-8.03%)`	⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e1e2c32...04b4086. Read the comment docs.

nicolo-ribaudo · 2017-06-18T09:23:17Z

I don't like the decoratorsStage2 name for the plugin: what will happen when the decorators proposal reaches stage 3? I think names like decoratorsNew or decorators2 may be good candidates.

peey · 2017-06-18T09:45:51Z

That's a valid point. We could also name it classAndFieldDecorators like it was named in #236 if we don't mind tying it to that feature (then we'll have to put future decorator proposals like parameter decorators under a different plugin name)

hzoo · 2017-06-19T02:47:49Z

@nicolo-ribaudo depends on if stage 3 means more changes. Either way we would need to fork the logic again with a new plugin/name

hzoo · 2017-06-19T04:22:36Z

@vjeux brought up a good point about whether the start position of the class/function part of the decorator should change? https://twitter.com/Vjeux/status/876213458622005249

peey · 2017-06-19T05:07:24Z

@hzoo Though in case stage 3 brings mostly non-breaking changes, we could easily make additions to this new decorators plugin instead of forking logic into a new one.

So we should definitely choose a plugin name that's not tied to stage 2

basicdays · 2017-06-19T16:39:50Z

Would a test to assert the output of the following make sense?

export default @thing
class Stuff { }

peey · 2017-06-19T16:43:33Z

export default @thing
class Stuff { }

@basicdays yep, I think this is the preferred way to do it since decorators and class tail together make up the class, and then you can export that like you export an undecorated class

I will add a test for this

hzoo · 2017-06-19T16:45:47Z

src/index.js

@@ -62,6 +62,10 @@ function getParserClass(pluginsFromOptions: $ReadOnlyArray<string>): Class<Parse
    pluginList.unshift("estree");
  }

+  if (pluginList.indexOf("decorators") >= 0 && pluginList.indexOf("decoratorsStage2") >= 0) {


Don't have to do this now, but we should figure out a better solution to this in the future (regarding multiple versions of the same kind plugin). Same kind of error as TS + Flow

littledan

Huge fan of the design decisions in this patch, to follow the current draft spec, no more no less, and to make a separate flag. To bikeshed about the name, how about "standardDecorators"?

What's your long-term vision for this mode? Ultimately, it would be great if, in Babel 7.0 (or 8.0), this new syntax (and a new matching transform) would be the only decorators implementation, or at least the only one selected by the staged presets, but maybe this is too big of a breaking change.

littledan · 2017-06-19T17:00:51Z

test/fixtures/experimental/decorators-stage-2/no-computed-decorator-member/actual.js

@@ -0,0 +1,6 @@
+class Foo {
+  @bar[bizz]


This is a great test; you could also add tests for cases like @(bar.baz) and @foo().bar, which one might expect to work. The grammar is extremely restrictive here, and you seem to implement the restrictions well (so well that I had to go back to the spec and ask, is it really that restrictive? yes).

existentialism

👍

peey · 2017-06-21T05:10:44Z

@vjeux brought up a good point about whether the start position of the class/function part of the decorator should change? https://twitter.com/Vjeux/status/876213458622005249

@vjeux trying to find the reason for this in the proposals document. Is it because the productions look like

ClassDeclaration[Yield, Default]:
    DecoratorList[?Yield]opt class BindingIdentifier[?Yield] ClassTail[?Yield]
    [+Default]DecoratorList[?Yield]opt class ClassTail[?Yield]

So we'd consider ClassDeclaration to start at the begining of the first decorator? (And similarly for class expression and methods) ??

vjeux · 2017-06-21T15:28:40Z

All the other parent nodes include the location of the children node except for decorators. We use this property in prettier to attach comments by going down the ast looking at ranges, but it breaks for decorators. If you could fix it that would remove one hack we have to do.

hzoo · 2017-06-21T19:32:43Z

Yeah the reason is just that you'd have to backtrack to know the start of the "decorated node"

peey · 2017-06-21T19:52:54Z

@hzoo I've found an easy way to do it though using this.resetStartLocationFromNode method, so it won't be a problem to add this feature. Just debugging flow errors right now before I update the PR!

hzoo · 2017-06-21T20:15:58Z

Cool didn't know about that one 😄

peey · 2017-06-21T20:41:48Z

Latest changes in last 3 commits:

Now all decorated elements (classes and methods) have their start location at the start location of the first decorator
Decide to rename to the plugin to decorators2 instead of other variants because
1. If more backwards-incompatible changes are introduced in future and then a new plugin may be implemented as decorators3
2. Can rename it to standardDecorators at zero cost later when the proposal is at stage 4

These two edits have caused a lot of minor changes to a lot of files so it might be a pain to review. The only logic changes to source folder is by this commit in the file src/parser/statement.js and everything else is renaming / test changes and I don't think would need review.

I also can't figure out how to increase coverage, the uncovered lines aren't making any sense to me (they existed in codebase before this PR). So if that's not a problem then I think we're good to merge (perhaps after latest changes relating to start location have been reviewed?)

Jessidhia

👍

Jessidhia · 2017-06-22T07:54:06Z

src/index.js

@@ -47,6 +47,11 @@ const parserClassCache: { [key: string]: Class<Parser> } = {};

 /** Get a Parser class with plugins applied. */
 function getParserClass(pluginsFromOptions: $ReadOnlyArray<string>): Class<Parser> {
+
+  if (pluginsFromOptions.indexOf("decorators") >= 0 && pluginsFromOptions.indexOf("decorators2") >= 0) {


I'd say to use Array.prototype.includes instead...... but that doesn't work on Node 4 😢

hzoo · 2017-06-22T14:16:37Z

test/fixtures/experimental/decorators-2/no-computed-decorator-member/options.json

@@ -0,0 +1,4 @@
+{
+  "plugins": ["decorators2", "classProperties"],
+  "throws": "Stage 2 decorators may only be used with a class or a class method (2:2)"


Should this error message mention no computed instead?

We will have to explain this in documentation or some other way.

the problem is that with classProperties enabled and due to the fact that the computed property isn't considered a part of the decorator, we can't really tell if the code is trying to access decorator's member or trying to decorate a computed class property.

So in this example it thinks that [bizz] is a class property.

If you disable class properties altogether you will get a syntax error at abc since it is expecting opening bracket right after the method name [bizz]

hzoo · 2017-06-22T14:17:03Z

test/fixtures/experimental/decorators-2/no-export-decorators-on-class/options.json

@@ -0,0 +1,4 @@
+{
+  "sourceType": "module",
+  "throws": "Leading decorators must be attached to a class declaration (2:0)"


is it useful to say: instead of the export? or to explain it via example?

hzoo

Looks awesome! An amazing first PR @peey, having to check the spec, and getting all these reviews!

I think maybe we can work on the error messages still if that's not difficult to change?

hzoo · 2017-06-23T14:42:45Z

Followup PR #590

bakkot and others added 10 commits June 17, 2017 13:23

Update decorator parsing to match current spec

06afa07

Refer to PR babel#353

Let decorator stage 2 parsing be under a new plugin name

a24dc6e

Parse stage 0 decorators when "decorators" plugin is active and parse stage 2 decorators when "decorators-stage-2" plugin is active

Add tests for stage 2 decorators from PR#353

001044f

Throw if both decorators decorators-stage-2 used

162bc90

Disallow in object literals, params, class props

9c63974

And add tests to reflect the same

Disallow exports between decorator & class body

b5e2383

For stage 2 decorators

Reorganize tests; camelCase plugin name

38c417e

Add test case for object properties

b7c1c55

Merge branch 'master' into decorators-stage-2

4f8ac6b

Reorganize tests and add tests

b60ac52

Add tests for static properties and private properties

hzoo requested review from littledan, diervo and bakkot June 17, 2017 20:51

hzoo added Spec: Decorators spec-update spec-new and removed spec-new labels Jun 17, 2017

hzoo requested a review from DrewML June 17, 2017 20:58

hzoo reviewed Jun 19, 2017

View reviewed changes

littledan reviewed Jun 19, 2017

View reviewed changes

bakkot approved these changes Jun 19, 2017

View reviewed changes

hzoo mentioned this pull request Jun 20, 2017

WIP: Add new plugin (classAndFieldDecorators) for Stage-2 decorators proposal #236

Closed

3 tasks

existentialism approved these changes Jun 20, 2017

View reviewed changes

diervo approved these changes Jun 21, 2017

View reviewed changes

Decorated classes/methods start where the decorator starts

e1972ba

peey added 2 commits June 22, 2017 02:00

rename decoratorsStage2 -> decorators2

e5fdb34

renames files

d99618c

jridgewell approved these changes Jun 21, 2017

View reviewed changes

littledan approved these changes Jun 22, 2017

View reviewed changes

Jessidhia approved these changes Jun 22, 2017

View reviewed changes

hzoo reviewed Jun 22, 2017

View reviewed changes

hzoo approved these changes Jun 22, 2017

View reviewed changes

hzoo merged commit f976bdd into babel:master Jun 22, 2017

This was referenced Jun 22, 2017

Unable to decorate generator functions #13

Closed

Decorators on computed class method names #33

Closed

(Discussion): Split Class/Property decorators plugin (Stage 2) from Stage 0 proposal #237

Closed

peey mentioned this pull request Jun 23, 2017

Follow-up on Decorators PR #590

Merged

hzoo added the Tag: New Feature label Jun 27, 2017

hzoo mentioned this pull request Jun 30, 2017

Generator and decorators are not compatible babel/babel#5904

Closed

babel-bot mentioned this pull request Jul 10, 2017

Decorators (Stage 2) babel/proposals#11

Open

2 tasks

existentialism mentioned this pull request Aug 25, 2017

Question on class/method/property location data when it has decorator(s) #694

Closed

hzoo mentioned this pull request Aug 31, 2017

Breaking: Apply location data fix to decorators plugin #699

Merged

babel-bot mentioned this pull request Nov 1, 2017

(Discussion): Split Class/Property decorators plugin (Stage 2) from Stage 0 proposal babel/babel#6711

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Decorators Stage 2 Parsing #587

Decorators Stage 2 Parsing #587

peey commented Jun 17, 2017 •

edited

codecov bot commented Jun 17, 2017 •

edited

nicolo-ribaudo commented Jun 18, 2017

peey commented Jun 18, 2017

hzoo commented Jun 19, 2017

hzoo commented Jun 19, 2017

peey commented Jun 19, 2017

basicdays commented Jun 19, 2017

peey commented Jun 19, 2017

hzoo Jun 19, 2017

littledan left a comment

littledan Jun 19, 2017 •

edited

existentialism left a comment

peey commented Jun 21, 2017

vjeux commented Jun 21, 2017

hzoo commented Jun 21, 2017

peey commented Jun 21, 2017

hzoo commented Jun 21, 2017

peey commented Jun 21, 2017

Jessidhia left a comment

Jessidhia Jun 22, 2017

hzoo Jun 22, 2017

peey Jun 22, 2017 •

edited

hzoo Jun 22, 2017 •

edited

peey Jun 22, 2017

hzoo left a comment

hzoo commented Jun 23, 2017

Decorators Stage 2 Parsing #587

Decorators Stage 2 Parsing #587

Conversation

peey commented Jun 17, 2017 • edited

Rationale for PR

codecov bot commented Jun 17, 2017 • edited

Codecov Report

nicolo-ribaudo commented Jun 18, 2017

peey commented Jun 18, 2017

hzoo commented Jun 19, 2017

hzoo commented Jun 19, 2017

peey commented Jun 19, 2017

basicdays commented Jun 19, 2017

peey commented Jun 19, 2017

hzoo Jun 19, 2017

Choose a reason for hiding this comment

littledan left a comment

Choose a reason for hiding this comment

littledan Jun 19, 2017 • edited

Choose a reason for hiding this comment

existentialism left a comment

Choose a reason for hiding this comment

peey commented Jun 21, 2017

vjeux commented Jun 21, 2017

hzoo commented Jun 21, 2017

peey commented Jun 21, 2017

hzoo commented Jun 21, 2017

peey commented Jun 21, 2017

Jessidhia left a comment

Choose a reason for hiding this comment

Jessidhia Jun 22, 2017

Choose a reason for hiding this comment

hzoo Jun 22, 2017

Choose a reason for hiding this comment

peey Jun 22, 2017 • edited

Choose a reason for hiding this comment

hzoo Jun 22, 2017 • edited

Choose a reason for hiding this comment

peey Jun 22, 2017

Choose a reason for hiding this comment

hzoo left a comment

Choose a reason for hiding this comment

hzoo commented Jun 23, 2017

peey commented Jun 17, 2017 •

edited

codecov bot commented Jun 17, 2017 •

edited

littledan Jun 19, 2017 •

edited

peey Jun 22, 2017 •

edited

hzoo Jun 22, 2017 •

edited