Improve branding on descriptors about proposal-decorators

[rbuckton]

Is it possible that the term "Descriptor" here will be confused/conflate with a "Property Descriptor", such as from Object.getOwnPropertyDescriptor? Should we consider a different term or is there enough distinction between a "Method Descriptor" and a "Property Descriptor" that adds a method?

I'm also slightly concerned with the term "Method Descriptor", given that another decorator could add an "extra" descriptor that adds a { value: "foo" } property. Perhaps "Member Descriptor" or "Property Descriptor" would be more appropriate (aside from the "Descriptor" terminology concern above).

Otherwise, I'm fine with this.

[littledan]

Any other suggestions for what we should call these things? It would also be useful to use that term internally in the spec as well as in documentation.

[rbuckton]

Honestly? I think an @@toStringTag of "Property Descriptor" for the thing that adds a property descriptor isn't terrible, as a "Field Descriptor" would be the thing that adds a field, but I'm still concerned they would be conflated.

Other possibilities (though by no means an exhaustive list):

• "Description" (e.g. "Class Description", "Member Description", etc.)
• "Info" (e.g. "Class Info", "Member Info", etc.)
  • This is similar to the terms used in C# reflection (e.g. ClassInfo, MethodInfo, FieldInfo, etc.)
• "Meta" (e.g. "Class Meta", etc.)
• "Meta Descriptor" (e.g. "Class Meta Descriptor").
• Nothing (e.g. "Class", "Member", etc.).

Please note that this is by no means a blocking concern for me, I just wanted to signal that there is a possible source of confusion. I will add that it does seem a bit strange to have a custom @@toStringTag without a related prototype to attach it to, but I don't think these objects should use a shared prototype.

A final option would be to forgo the @@toStringTag and add a reflection API that does the necessary tests against an object to determine if it is a class, method, or field descriptor.

[ajklein]

The linked issue this is meant to solve is quite long, so I'm curious if you can provide an answer to a high-level question: why is duck-typing/introspection of the descriptor's properties not sufficient to meet this branding need?

[littledan]

@ajklein With duck-typing/introspection, I'd imagine you might decide that something is a class decorator by reading the kind property and seeing that it's one of the legal values. However, we don't really have a system-wide convention that this is a safe operation--some objects may have a side-effecting getter with this name. By contrast, @@toStringTag is a JS-wide convention for a type tag; recent discussions in TC39 about the Type.isType proposal seemed to point to @@toStringTag as a model for future branding.

The linked issue is all about cases where you would want to have a single class decorator which is overloaded between being able to use as @foo(function() { bar; }) class baz { } and @foo class bing { }. In the Stage 1 decorators proposal, it was hard to tell the difference between these cases since the semantics of a class decorator was based on passing the class to the decorator as an argument. The current proposal is richer, and based on passing a descriptor, so this particular kind of overloading should be pretty easy just using typeof. (You can debate how ergonomic that is, but I don't see how it's less ergonomic than the rest of the decorators API for decorator authors.)

What do others on this thread think? Is it overkill to add this additional brand?

[ljharb]

(ftr, toStringTag’s flaw is that it’s a string instead of a function, which makes it not robust to rely on; the isType discussions amount to “toStringTag but functions that return a string instead”)

[littledan]

@ljharb When Type.isType was proposed, my understanding was the objection was raised that nothing should be added that is more robust than toStringTag. I don't quite understand the rationale, but toStringTag might give us a good enough brand for the use cases while being consistent with that goal.

[ljharb]

Hmm, I don't recall that objection. Either way, toStringTag is fine for these objects.

[ajklein]

@littledan Do we need a system-wide convention? It appears from your patch in #63 that there is always a kind own data property available in any object that would be checked via this @@toStringTag, so at least for such objects, it's "safe" to switch based on kind. I can think of at least one other place where the language exposed an unbranded plain object : the iteration protocol. In that case, objects are expected to have value and done properties, but there's no brand associated.

[littledan]

You're right that this information is pretty redundant with the kind. However, I don't think the iteration protocol is quite the same: I can't think of a situation when you want to have a function which is overloaded between IterationResult and non-iteration result values.

On the other hand, the original bug at tc39/proposal-decorators-previous#24 , there were cases presented where a decorator would want to differentiate between a descriptor and other objects (namely, if a function may be used both as decorator directly as well as a decorator factory).

@wycats told me that he experimented with writing decorators that do this kind of overloading with the current system, and it was fairly awkward to do a good job without some more solid mechanism.

Let's make sure to discuss this in the TC39 presentation. I don't think duck typing by kind would be the end of the world, if the rest of the committee leans that way.

[rbuckton]

If we are choosing to auto-insert parentheses, then I would advise against this branding as it then becomes unnecessary. If all decorators must effectively be decorator factories (i.e. function A() { return function B(descriptor) {}; }, then the argument descriptor passed to B should always be either a class, method, or field descriptor which can be distinguished by its kind property.

While less of a concern for TC39, this would also cut down on the overhead for emit helpers in downlevel code as transpilers like TypeScript or Babel would no longer be concerned with having to add additional lines of code like if (typeof Symbol === "function" && Symbol.toStringTag) o[Symbol.toStringTag] = "Method Descriptor";.

[ljharb]

I'd imagine you might decide that something is a class decorator by reading the kind property and seeing that it's one of the legal values. However, we don't really have a system-wide convention that this is a safe operation--some objects may have a side-effecting getter with this name.

How is that altered by the choice of auto-inserting parens or not?

[littledan]

@ljharb The original motivation for the improved branding was so that you can make a decorator which is overloaded between the case of getting an argument and the case of being used directly. Auto-inserting parens is another way of getting at the same time.

In the March 2018 TC39 meeting, the committee decided to go with this auto-insertion of parentheses. If it's always pretty clear whether you are working with a class/element descriptor or not, it seems unnecessary to have @@toStringTag to me. As @ajklein pointed out, there is no system-wide convention that everything has @@toStringTag, for example property descriptors do not.

For this reason, I think we should revert #63 once we put in the paren auto-insertion logic.

[ljharb]

I think it’d be reasonable to add toStringTag to property descriptors, at which point they’d belong on the decorator descriptor as well - but that’s something that should happen unrelated to this proposal.

[littledan]

OK, we've decided not to auto-insert the parentheses, and we've discussed @@toStringTag and tweaks to it (namely, it's all "Descriptor" now) at a few TC39 meetings without concerns being raised. I think we can close this issue and conclude that we have a solution landed to the branding question. Please file a new issue if you have additional concerns with it.