Decorators 2 Transform [WIP] #6107

peey · 2017-08-15T13:31:45Z

Q	A
Fixed Issues	Progress on babel/proposals#11
Patch: Bug Fix?	No
Major: Breaking Change?	No
Minor: New Feature?	Yes
Tests Added/Pass?	Yes
Spec Compliancy?	Yes
License	MIT
Doc PR	No
Any Dependency Changes?	Yes, on decorators2 syntax plugin

Note: I'll use the terms evaluation to mean evaluation of @dec(args) and decoration to mean actual execution of the decorators

Also, note that the decorator proposal introduces the concept of an elementDescriptor, which is distinct from the propertyDescriptor we all know about.

To understand the code, you need to know that an elementDescriptor is an object with the shape:

{
  kind: "property", // I don't know what other values kind can take
  key: <the name of the method>,
  isStatic: true|false,
  descriptor: <the property descriptor of the method>
}

I've implemented the methods decorate, decorateElement, decorateClass, makeElementDescriptor, and mergeDuplicateElements in helpers.js. Out of these, decorateElement and decorateClass correspond to the spec operations DecorateElement, and DecorateClass respectively. mergeDuplicateElements corrseponds to the operation used in step 6 of both DecorateClass and DecorateElement.

The method decorate runs the whole thing. It takes care of the evaluation order (see below) and corrsponds to Runtime Semantics: ClassDefinitionEvaluation step 21 onwards.

The changes in babel-core are from #6058

Assumptions Made: (Please feel free to correct)

evaluation order is as the following: (relevant spec operation)
a. evaluate all method decorators in order [step 21.g. of above spec link] (left to right / outer to inner)
b. (decoration) execute all method decorators in reverse order step 24.a.(right to left / inner to outer)
c. evaluate all class decorators in order step 29. (assuming that DecoratorListEvaluation happens just before this, since it's not explicitly mentioned)
d. (decoration) execute all class decorators in reverse order step 29
the signature of decorators is as follows:

// for member decorator @foo(a,b,c)
function foo(a, b, c) {
   return (descriptor) => {descriptor, extras, finishers};
} 

// for member decorator @foo
function foo(descriptor) {return {descriptor, extras, finishers}}

// for class decorator @foo(a,b,c)
function foo(a,b,c) {
  // elements is an array of  descriptors of all members after running the decorators
  return (ctor, parent, memberDescriptors) => {constructor, elements, finishers}
}

// for class decorator @foo
function (ctor, parent, memberDescriptors) {return {constructor, elements, finishers}}

The spec uses two forms - a finisher attached to the elementDescriptor and explicitly returning finishers array. I've largely ignored the former because it doesn't seem to make any sense.
The spec is clear that elementDescriptor is passed to method decorators and not propertyDescriptor, and that's how I had implemented it in the past. However, I changed it to use propertyDescriptor because using elementDescriptor would imply that the decorator can change the key of the method being decorated, and if it is static or not. I'm not sure if this behaviour is intended or unintended. I need more feedback on this from the spec designers. Changing back to elementDescriptor shouldn't be too much trouble.

TODO / WIP:

tests for heritage
configurability check and error if a decorator tries to configure a non-configurable descriptor
handling undecorated accessors descriptors (getters and setters)
more tests for transformation, optimizing for special cases.

peey · 2017-08-15T14:44:48Z

I accidentally opened this PR with incomplete info. Now that I've edited it to include all details, I'm reopening

littledan · 2017-08-15T15:06:52Z

I'm proposing some changes to the decorator proposal at https://github.com/littledan/proposal-unified-class-features . You can see a summary of the changes in this presentation. The committee and decorators champions seemed to view it positively. I'd be interested to hear what you think.

I don't think this follow-on proposal should affect most of the implementation. I'll review this patch as an implementation of this decorators proposal.

jkrems · 2017-08-15T18:24:41Z

@littledan Does removing finishers from element decorators mean they can no longer safely attach meta data? Especially if finishers can now replace the class completely? I thought this was done explicitly to allow meta data "annotation"-style decorators that are hard or impossible to implement with stage 0?

littledan · 2017-08-15T21:53:39Z

@jkrems You can attach metadata by putting it on the methods in an additional property, or making a WeakMap keyed off of the method. Would that work for you?

jkrems · 2017-08-15T22:01:14Z

@littledan The nice thing about finalizers was that it allowed to the 2nd thing safely - no matter what other decorators would do.

@injectDataSource
class MyResource {
  @deprecated // not 100% sure about evaluation order
  @GET('/users/{id}') // wants to attach meta data to `getUser`
  async getUser(params) { /* ... */ }
}

We're assuming here that:

deprecated wraps the actual function value that GET saw in another function that logs a deprecation warning.
injectDataSource could be something like a redux connect helper. The point being: It wants to wrap the constructor itself.

In the previous stage 2 iteration, @GET could use a finalizer to myWeakMap.set(finalCtor, metaData). If it tries to do the same during its own run, it would get the MyResource class before being wrapped. And the meta data would get lost. If it tries to attach the meta data to the function/property value itself, it will be swallowed by deprecated.

Jessidhia

I just looked at the tests for now; will look at the code later

Jessidhia · 2017-08-16T05:02:58Z

packages/babel-plugin-transform-decorators-2/test/fixtures/examples/logger/exec.js

+function log(message) {
+  return function (descriptor) {
+    let oldFunc = descriptor.value;
+    descriptor.value = function(...args) {


Somewhat unfortunately, there is no way of making this function's name derive from the original function name (instead of "value") other than by calling defineProperty on it afterwards 🤔

Actually, we'll probably be passing the element descriptor to the decorator and not the property descriptor. I just had a doubt on how that'd work when you change the key of the descriptor you've returned and that's why I made the call to implement it like this. Once I get a little clarification on assumption #4 from @littledan or someone, I'll make the desired changes

Jessidhia · 2017-08-16T05:04:34Z

packages/babel-plugin-transform-decorators-2/test/fixtures/examples/overrider/exec.js

+}
+
+class Foo {
+  @overrider(() => 3) method() {


What is this here? Is it the constructor, the outer this, or the newly created instance?

Could be worth having a test for it.

Jessidhia · 2017-08-16T05:05:47Z

packages/babel-plugin-transform-decorators-2/test/fixtures/examples/spare/exec.js

+    const clone = {
+      kind: "property",
+      isStatic: !!isStatic,
+      key: name,


What should happen if the name conflicts? @spare("foo") foo() {}

Currently what I've interpreted from the spec is that it should "merge". By that I mean it will just take on the value of the last property added with the key "foo". See decorateElement step 6. Also see mergeDuplicateElements helper

Jessidhia · 2017-08-16T05:07:42Z

...transform-decorators-2/test/fixtures/transformations/method-and-class-decorators/expected.js

+
+  undecorated() {}
+
+}, [["undecorated"]], [["method", [methDec]]], void 0)([classDec]);


(Having not looked at the decorate implementation yet) Too many arrays? Some of these look like they could be flattened one level, but I'm only guessing at the meaning of each parameter.

currently I'm using const [key, isStatic] = [..] so that's why the inner items of those are arrays (in case of a non static member, I just omit the second array element). We could certainly simplify it further if needed, e.g. if it's static then it'll look like ["method", true] otherwise it'll look like just "method" and not ["method"]

Jessidhia · 2017-08-16T05:09:19Z

packages/babel-plugin-transform-decorators-2/test/fixtures/wip/wip/expected.js

+
+  [calculated + and + undecorated]() {}
+
+}, [["andAnUndecoratedMethod"], [calculated + and + undecorated]], [["m1", [dec]], ["m2", [bar, foo.bar(baz)]], [(_key = 3 + 7), [dec], true]], void 0)([decorator]);


calculated + and + undecorated should be put in a ref as well (could be an impure expression)

I'm using babel's built-in isPure which is why that wasn't put in a ref

You're right, this should have been put in a ref. Nicolo pointed out the error in code and I've fixed it, will push soon

xtuc · 2017-08-16T07:21:21Z

packages/babel-helpers/src/helpers.js

+    }
+
+    // decorate and store in elementDescriptors
+    for (const [key, decorators, isStatic] of memberDecorators) {


Can we ES2015 here?

And a bit later, Array.from will require a polyfill.
It could cause issues like this #5876, right?

I wish we could. But if we can't, I'll refactor it to use ES5, it shouldn't be complex. I'll leave this be till the end though, since the code is functionally correct so for the review we could focus on just that

hzoo · 2017-08-16T15:32:29Z

...m-es2015-parameters/test/fixtures/parameters/rest-member-expression-optimisation/expected.js

@@ -21,6 +21,6 @@ function t() {

 function t() {
  for (var i = 0; i < arguments.length; i++) {
-    return arguments.length <= i ? undefined : arguments[i];


this should be fixed

I'm not sure if this is related to this PR. I'll investigate more

littledan · 2017-08-30T14:36:35Z

packages/babel-helpers/src/helpers.js

+    for (const [key, decorators, isStatic] of memberDecorators) {
+      const target = isStatic ? constructor : prototype;
+      const propertyDescriptor =
+        elementDescriptors.has([key, isStatic]) && elementDescriptors.get([key, isStatic]).descriptor 


This has call will always return false, since ES6 maps are by identity. Since [1, 2] !== [1, 2], calling Map.prototype.has on a fresh array will never do what you're hoping for.

Instead, you could maintain two Sets of keys, or two objects with keys and values, for the static and non-static halves.

littledan · 2017-08-30T15:19:24Z

packages/babel-helpers/src/helpers.js

+
+      finishers = finishers.concat(result.finishers);
+      //TODO: heritage hacks so result.constructor has the correct prototype and instanceof results
+      //TODO: step 38 and 39, what do they mean "initialize"?


"Initialize" was about having methods and the constructor start in some state where they would be unusable, and make them usable later. In my follow-on decorators proposal, I'm suggesting to get rid of this initialized/uninitialized state. I think it's OK to go without it to start, even if it's possible that TC39 will ask to bring it back.

littledan · 2017-08-30T15:26:18Z

packages/babel-helpers/src/helpers.js

+      );
+
+      finishers = finishers.concat(result.finishers);
+      //TODO: heritage hacks so result.constructor has the correct prototype and instanceof results


Heritage is just given as an argument to class decorators; it's the responsibility of the decorators to do the appropriate thing with that, I believe.

And other review suggestions

peey · 2017-09-16T10:01:50Z

Apologies for responding late to the review. Uni workload has started again.

Updates: Now we're merging getters and setters & other things pointed out by littledan in their review

Todo:

Refactor merging so we can merge when adding extras instead of overriding
Look into if other props things like enumerable, configurable, writable & value (in case of data descriptor) are also meant to be merged. @littledan thoughts on this?
Fix the failing test for x instanceof Foo if Foo has been processed by the transform
Incorporate nicolo's Add support for helper dependencies #6254

I had missed extends in the test case but the asserts were expecting it. I thought that tests were failing for more sinister reasons, but thankfully it isn't so

littledan

I've confirmed with @bterlson and @wycats that http://tc39.github.io/proposal-unified-class-features should be considered to subsume http://tc39.github.io/proposal-decorators for the planned spec text.

mobxjs/mobx#1352 babel/babel#6107

peey · 2018-03-12T13:09:04Z

Update: @nicolo-ribaudo asked me if they could take this up, and I told them they could.

The outstanding work on this PR would have been the todo in my previous comment and then any changes between the spec at the time this PR was made and the spec now (I'm not sure about the exact status of this, seems like http://tc39.github.io/proposal-unified-class-features that @littledan's comment specified is dead and http://tc39.github.io/proposal-decorators has been updated)

Since Babel's codebase has changed much (and the proposal may have too), I guess Nicolo's taking the route of reworking this feature and salvaging code from this PR as needed in #7542 . Kudos and good luck!

Here's what might be useful from this PR:

the file babel-plugin-transform-decorators-2/src/index.js houses the transformation logic
changes to helpers.js have the functionally equivalent javascript code to emulate decorators
the test folder has numerous corner cases, and decorator usage examples

nicolo-ribaudo · 2018-06-03T18:37:44Z

Closing in favor #7976. Thank you @peey for your work!

peey added 13 commits July 21, 2017 13:04

Add syntax plugin for decorators2

57cdfaf

WIP decorator transform initial commit

9904b61

Merge branch '7.0' into decorators-2-transform-wip

1d64084

wip commiting code before major changes

f214d1d

Transform works great, move stuff to helpers

edb7ff2

Clean up code

10d763e

Add feature to pass array of deps to a helper

358cf70

Add exec tests

626b92e

Add tests for evaluation order and fix transformation

d8cebba

Add tests for class decorators; minor fixes

ef4eba5

Add test for enumerability decorator

b1092ca

Add examples, & tests for extras, finishers

a55e374

Merge branch '7.0' into decorators-2-transform-wip

5f7bf93

peey closed this Aug 15, 2017

peey changed the title ~~Decorators 2 Transform [WIP~~ Decorators 2 Transform [WIP] Aug 15, 2017

peey reopened this Aug 15, 2017

hzoo requested review from littledan and diervo August 15, 2017 14:45

hzoo added the es-proposal label Aug 15, 2017

babel-bot mentioned this pull request Aug 15, 2017

Decorators (Stage 2) babel/proposals#11

Open

2 tasks

hzoo mentioned this pull request Aug 15, 2017

Create aug-16.md babel/notes#32

Merged

Jessidhia reviewed Aug 16, 2017

View reviewed changes

xtuc reviewed Aug 16, 2017

View reviewed changes

Update versions to make tests pass

8707f4e

hzoo reviewed Aug 16, 2017

View reviewed changes

littledan reviewed Aug 30, 2017

View reviewed changes

danez closed this Aug 31, 2017

danez reopened this Aug 31, 2017

danez changed the base branch from 7.0 to master August 31, 2017 17:00

nicolo-ribaudo mentioned this pull request Sep 13, 2017

does not support decorators and generator babel/babylon#721

Closed

hzoo mentioned this pull request Sep 14, 2017

July 2017 babel/proposals#19

Closed

10 tasks

nicolo-ribaudo mentioned this pull request Sep 15, 2017

Add support for helper dependencies #6254

Merged

peey added 2 commits September 16, 2017 15:19

Merge getters and setters; Map->object in decorate

f86b327

And other review suggestions

Add failing test for instanceof

96f51aa

Fix parentage tests. It's not an issue

76f5d3c

I had missed extends in the test case but the asserts were expecting it. I thought that tests were failing for more sinister reasons, but thankfully it isn't so

littledan reviewed Sep 25, 2017

View reviewed changes

hzoo mentioned this pull request Sep 27, 2017

Create sept-26.md babel/notes#36

Merged

9 tasks

hzoo added Spec: Decorators and removed area: tc39 proposal labels Oct 5, 2017

pzuraq mentioned this pull request Oct 18, 2017

[BUG] not @computed decorators work in file.js but fail in file.ts ember-decorators/ember-decorators#162

Closed

hzoo added the Priority: High label Nov 29, 2017

hzoo added this to the Babel 7.next milestone Dec 27, 2017

mweststrate mentioned this pull request Feb 16, 2018

Support the new Babel 7 decorator implementation mobxjs/mobx#1352

Closed

buschtoens added a commit to buschtoens/acme-v2 that referenced this pull request Feb 28, 2018

fix(babel): use transform-decorators-legacy

7543816

mobxjs/mobx#1352 babel/babel#6107

buschtoens mentioned this pull request Mar 3, 2018

Fix class properties tdz decorator interop #7475

Closed

nicolo-ribaudo mentioned this pull request Mar 10, 2018

Decorators #7542

Closed

2 tasks

nicolo-ribaudo mentioned this pull request May 18, 2018

Add support for the new decorators proposal #7976

Merged

4 tasks

nicolo-ribaudo closed this Jun 3, 2018

lock bot added the outdated A closed issue/PR that is archived due to age. Recommended to make a new issue label Oct 4, 2019

lock bot locked as resolved and limited conversation to collaborators Oct 4, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Decorators 2 Transform [WIP] #6107

Decorators 2 Transform [WIP] #6107

peey commented Aug 15, 2017 •

edited

peey commented Aug 15, 2017

littledan commented Aug 15, 2017

jkrems commented Aug 15, 2017 •

edited

littledan commented Aug 15, 2017

jkrems commented Aug 15, 2017

Jessidhia left a comment

Jessidhia Aug 16, 2017

peey Aug 16, 2017

Jessidhia Aug 16, 2017

Jessidhia Aug 16, 2017

peey Aug 16, 2017

Jessidhia Aug 16, 2017

peey Aug 16, 2017

Jessidhia Aug 16, 2017

peey Aug 16, 2017

peey Aug 20, 2017

xtuc Aug 16, 2017

peey Aug 16, 2017

hzoo Aug 16, 2017

peey Aug 17, 2017

littledan Aug 30, 2017

littledan Aug 30, 2017

littledan Aug 30, 2017

peey commented Sep 16, 2017 •

edited

littledan left a comment

peey commented Mar 12, 2018

nicolo-ribaudo commented Jun 3, 2018 •

edited


		undecorated() {}

		}, [["undecorated"]], [["method", [methDec]]], void 0)([classDec]);


		[calculated + and + undecorated]() {}

		}, [["andAnUndecoratedMethod"], [calculated + and + undecorated]], [["m1", [dec]], ["m2", [bar, foo.bar(baz)]], [(_key = 3 + 7), [dec], true]], void 0)([decorator]);

Decorators 2 Transform [WIP] #6107

Decorators 2 Transform [WIP] #6107

Conversation

peey commented Aug 15, 2017 • edited

Assumptions Made: (Please feel free to correct)

TODO / WIP:

peey commented Aug 15, 2017

littledan commented Aug 15, 2017

jkrems commented Aug 15, 2017 • edited

littledan commented Aug 15, 2017

jkrems commented Aug 15, 2017

Jessidhia left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

peey commented Sep 16, 2017 • edited

littledan left a comment

Choose a reason for hiding this comment

peey commented Mar 12, 2018

nicolo-ribaudo commented Jun 3, 2018 • edited

peey commented Aug 15, 2017 •

edited

jkrems commented Aug 15, 2017 •

edited

peey commented Sep 16, 2017 •

edited

nicolo-ribaudo commented Jun 3, 2018 •

edited