Proposal: Allow client code to intercept the decoration process

[Download]

TL;DR;
Allow client code to intercept the decoration process by defining a well-known Symbol.decoratorCall. When the runtime detects a property on a decorator with this symbol as it's name and a function as it's value, the runtime will invoke that function i.s.o. the decorator function itself to perform the decoration.

Background

There has been a lot of discussion around the way decorators are used and how the spec allows us to write code for these scenarios. Mostly, there are two ways to use decorators that are used a lot:

@deco  // <-- no parentheses
class Subject {}

@deco('argument')
class Subject

So far so good, but what happens if the decorator accepts an optional argument? We find that whether we supply parentheses or not makes a difference. In other words, these two uses of decorators are not equivalent:

@deco
class Subject
// not equivalent to
@deco()
class Subject

The big difference is that in the first scenario deco is invoked as a decorator and is expected to return the decoration target (e.g. the class in this example), whereas in the second scenario, deco will first be called without any arguments and is expected to return a function, which will then be invoked as the decorator. We will call this a decorator factory.

Many authors have expressed the desire to have @deco and @deco() have the same outcome: The target is decorated with deco without any arguments. This can be achieved with an if inside the decorator that uses duck typing to determine whether the function is invoked as a decorator or as a decorator factory:

function deco(arg) {
  if (typeof arg == 'function') {
    // decorator
    arg.decorated = true;
    return arg;
  } else {
    return target => {
      target.decorated = arg;
      return target;
    }
  }
}

This function will handle all scenarios described above. I will refer to functions that work this way as 'universal decorators'. They are convenient. But this code contains some problems:

1. The check in the if is brittle. What if we want to write a class decorator that optionally accepts a function as an argument? In some cases, it may be impossible to distinguish between decorator and decorator factory invocations.
2. This code contains much redundancy. Basically we are writing the decorator twice: once for the decorator invocation and once for the decorator factory invocation. We can of course factor out some code into a sub function but it all makes our decorator needlessly complex.

The discussion around this topic has spawned some interesting ideas for solutions, the most extreme of which would break all existing decorators. This proposal attempts to formulate a solution to these problems that is fully backwards compatible.

Hooking into the decoration process

The if in our universal decorator example above is really what is causing us all our grief. It splits our code in two and worse, the condition it is checking is brittle and will often have to change depending on what arguments our function accepts. What if we could get rid of this if altogether?
Turns out we could. And best of all, we could do it without breaking backward compatibility. As a bonus we would be creating a generic mechanism that could support other scenarios besides writing universal decorators. We can allow authors to hook into the decoration process itself.

Symbol.decoratorCall

In Javascript, functions are objects. Which means they can have properties. We can use this to allow authors to set a property on a decorator function in such a way that they can trap the decoration process. Given a well-known symbol Symbol.decoratorCall, authors could set a property on their decorator using this symbol to set a function to be called by the runtime instead of the decorator function itself. As authors, we now have an extra tool that can help us rewrite our universal decorator to something much simpler:

function deco(arg = true) {
  return target => {
    target.decorated = arg;
    return target;
  }
}
deco[Symbol.decoratorCall] = function(...args) {
  return deco()(...args);
};

Notice how the function assigned to the Symbol.decoratorCall property is completely generic. We as authors can take advantage of this fact to implement our own tooling for universal decorators:

function universalDecorator(factory) {
  factory[Symbol.decoratorCall] = function(...args) {
    return factory()(...args);
  }
  return factory;
}

Then, we could write only the decorator factory and let the tooling turn it into a universal decorator for us:

const deco = universalDecorator(function deco(arg = true) {
  return target => {
    target.decorated = arg;
    return target;
  }
});

If we ever get decorators on functions, we can make it even nicer :)

Conclusion

Although this proposal was born out of the desire to be able to write universal decorators more easily and to avoid duck typing, I think that being able to intercept the decoration process will actually open up options to deal with other issues as well.

Advantages:

1. Fully backwards compatible. This change should not break any existing decorators.
2. Meshes well with how other runtime features can be hooked into using Symbol. E.g. Symbol.iterator which can make our object work with the for ... of loop.
3. Opt-in. Only people that care about universal decorators need to do something to make use of this proposal. All other authors could happily ignore it and never be the wiser.

Disadvantages:

1. Opt-in. From the perspective of authors using decorators, they still need to figure out per decorator whether the use of parentheses matters for that decorator, and which form to use.
2. Requires a new well-known symbol.

[Download]

@silkentrance @lukescott @isiahmeadows @alexbyk @jayphelps
Would you guys support this proposal?

[jayphelps]

Will stew on it. One minor typo:

deco.call(ctx, ...args) {
  return deco().call(ctx, ...args);
}

// should be

deco.call = function (ctx, ...args) {
  return deco().call(ctx, ...args);
};

[dead-claudia]

@Download Maybe Symbol.call or similar? Otherwise, you're interfering with Function.prototype.call. Other than that, I'm fine with it, as long as there's a runtime check to ensure that method exists before falling back to the default of just using the function directly.

// Original
class Foo {
  @decorator
  bar() {}
}

// My proposed desugaring, where $variables are purely internal:
class Foo {
  bar() {}
}

let $hasCall = Object.prototype.hasOwnProperty.call(decorator, Symbol.call);
let $desc = Object.getOwnPropertyDescriptor(Foo.prototype, "bar");
let $ref = $hasCall ?
    decorator[Symbol.call](Foo.prototype, "bar", $desc) :
    decorator(Foo.prototype, "bar", $desc);
Object.defineProperty(Foo.prototype, "bar", $ref !== undefined ? $ref : $desc);

[lukescott]

call is a built in function. Overriding it in this fashion is confusing. Symbol.call is for making a class callable without 'new'. At that point why not make it a class?

As I've said before I believe backwards compatibility is an unreasonable constraint just because people jumped the gun on a stage 0/1 proposal. I would rather do this right then be limited by bad decisions.

[dead-claudia]

@lukescott I'm not that tied to Symbol.call (I said "or similar"). I just want it to be something that doesn't conflict with Function prototype methods (e.g. Function.prototype.call). And symbols are a great way to avoid this.

[Download]

@isiahmeadows
Can you enlighten me on how using call in this way conflicts with Function.prototype.call? It's not like we are overriding .call on every function.

Note that we can already override .call on any function right now (and indeed that is what my example does). So again, this is about letting the client code decide whether to hook into the process this way or not. All the runtime needs to do is give the client code this ability.

I'm trying to look for a scenario where just always invoking .call i.s.o. checking whether the function hasOwnProperty first would make a practical difference. Remember, this would only happen during a decoration call (e.g. what the runtime does when it encounters @), so there won't (shouldn't) be much code affected in any case. I think we would be looking at the edge case of an edge case, so to say. Do you have a scenario in mind?

@lukescott The decorators proposal is defining a whole new symbol with @. If we end up specifying it's behavior as 'evaluates the expression to the right hand side of the @ symbol and if it's a function, invokes it's call method', I (personally) don't think that's very confusing at all. It does not change the definition of what call is or what it does in any way.

Again, overriding call is already possible right now and this will remain so in the foreseeable future. Some people don't like this part of Javascript where anything goes, but it is what it is. My proposal does not touch that in any way. At the most it could be seen as promoting a bad practice, but I think that's a pretty subjective viewpoint.

@jayphelps
Fixed the typo, thanks for pointing it out!

[silkentrance]

@Download please see the proposal #66 and you might want to comment on that.

[dead-claudia]

@Download I think I see where you're going with this, but what's this? Also, FWIW, I missed the key detail that you're being careful in that it's always similar to Function.prototype.call.

For others that overlook some of the more minute details of this idea, it's the difference between this (%variables are internal):

// Original
class C {
  @decorator
  method() {}
}

// Transpiled now
class C {
  method() {}
}

var %func = decorator
var %desc = Object.getOwnPropertyDescriptor(C.prototype, "method")
%desc = %func(C.prototype, "method", %desc) || %desc
Object.defineProperty(C.prototype, "method", %desc)

// Proposed here
class C {
  method() {}
}

var %func = decorator
var %desc = Object.getOwnPropertyDescriptor(C.prototype, "method")
%desc = %func.call(C.prototype, "method", %desc) || %desc // Here's the difference
Object.defineProperty(C.prototype, "method", %desc)

---

My main concern is with TypeScript, which might result in type conflicts once variadic generics are implemented (it's a beast).

interface Function<R, T, ...A> {
  call(thisArg: T, args: [...A]): R;
}

type MethodDecorator<T> = (target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void

interface Decorator<T, ...A> extends (...args: [...A]) => MethodDecorator<T> {
  // inherited with [...A] = [Object, string | symbol, TypedPropertyDescriptor<T>]:
  // call(thisArg: any, arg0: Object, arg1: string | symbol, arg2: TypedPropertyDescriptor<T>): MethodDecorator<T>
  call(thisArg: any, arg0: Object, arg1: string | symbol, arg2: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T> | void
}

That return type will fail to check, because the types are wholly incompatible. That's my greater concern, since decorators are of equally large interest to the TypeScript community (they're looking into integrating them more deeply than even JS proper, if you look at their roadmap).

---

To be honest, TypeScript compatibility is probably the only reason I can't support this idea.

[Download]

@isiahmeadows Yes the way your example transpiles is exactly what I had in mind.
About the TypeScript compatibility I have to admit I never though about it, because I've never programmed with TypeScript.

Would there be a way around the issue you are describing?

what's this?

If you mean what this would be bound to inside the decorator function, I reckon we should make sure it behaves the same as it does now.

[dead-claudia]

@Download

Would there be a way around the issue you are describing?

Why I suggested a symbol. TypeScript understands those perfectly, and it's very easy to check for the existence of such a symbol (hasOwnProperty check). I personally suggested Symbol.call, but I have no personal attachment to the name. Babel and TypeScript can always generate a new helper to simplify this.

This also is more behaviorally and logically consistent with the rest of ES2015+, where magic methods and values are all denoted by symbols (like Symbol.iterator and Symbol.hasInstance).

What it would desugar to, then, is this:

// Original
@Class
class C {
  @Method
  foo() {}
}

// New
function %decorateClass(target, decorator) {
  if (Object.prototype.hasOwnProperty.call(decorator, Symbol.call)) {
    decorator = decorator[Symbol.call]()
  }
  return decorator(target) || target
}

function %decorateProperty(target, property, decorator) {
  if (Object.prototype.hasOwnProperty.call(decorator, Symbol.call)) {
    decorator = decorator[Symbol.call]()
  }
  const desc = Object.getOwnPropertyDescriptor(target, property)
  Object.defineProperty(target, property, decorator(target, property, desc) || desc)
}

class C {
  method() {}
}

%decorateClass(C, Class)
%decorateProperty(C.prototype, "foo", Method)

If you mean what this would be bound to inside the decorator function, I reckon we should make sure it behaves the same as it does now.

This is pretty much what I expected. I was just double-checking.

---

// I like the idea of this:
function universal(wrapper) {
  wrapper[Symbol.call] = wrapper
  return wrapper
}

const Injectable = universal((opts = {}) => (target, prop, desc) => {
  // do things...
})

// Or if you *really* need a class...and no, inheritance doesn't work.
function decorator(D) {
  function decorator(opts = {}) {
    const d = new D(opts)
    d[Symbol.call] = function () {
      return (...args) => this.apply(...args)
    }
    return d
  }
  Object.setPrototypeOf(decorator, D)
  decorator.prototype = D.prototype
  decorator[Symbol.call] = () => new D()[Symbol.call]()
  Object.defineProperty(decorator, "name",
    Object.getOwnPropertyDescriptor(D, "name"))
  return decorator
}

@decorator
class Injectable {
  constructor(opts) {
    this.opts = opts
  }

  apply(target, prop, desc) {
    // do things...
  }
}

[Download]

@isiahmeadows Those are some cool ideas.

I have nothing against using a symbol. I just did not see any need for it. It seems like a relatively small change. As long as the end result is that we can intercept the decoration call I would be very happy with it.

A bit off-topic, but why would you write it like this:

Object.prototype.hasOwnProperty.call(decorator, Symbol.call)

...and not like this?

decorator.hasOwnProperty(Symbol.call)

EDIT: had some trouble finding relevant info on Symbol.call... Symbol and call are both used a lot in other contexts. :) The term 'well-known' helps. Anyway I think I found the relevant section of the draft spec, but alas Symbol.call is not in the list... Does anyone have a better link?

[dead-claudia]

@Download This. 😄

// Totally valid JS:
decorator.hasOwnProperty = function (what, the, heck) {
  return what + the + heck
}

decorator.hasOwnProperty("somethingThatDoesn'tExist") === "somethingThatDoesn'tExistundefinedundefined"

Or in all seriousness, the object can define its own variant, and thus it no longer actually checks what you think it is.

---

As for Symbol.call being used, I think it might be used in some sort of ES strawman somewhere, but an initial Google search is failing me here. And no, this symbol doesn't yet exist in anything stage 1 or higher. But I'm suggesting adding a new well-known symbol @@call, which would be referred to by Symbol.call.