What is “new.target”?

Question

The ECMAScript 2015 specification mention the keyword (or words?) new.target exactly 3 times - 1 time in 14.2.3:

Normally, Contains does not look inside most function forms However, Contains is used to detect new.target, this, and super usage within an ArrowFunction.

and twice in 14.2.16:

An ArrowFunction does not define local bindings for arguments, super, this, or new.target. Any reference to arguments, super, this, or new.target within an ArrowFunction must resolve to a binding in a lexically enclosing environment

MDN mentions it, but is very vague and the page is incomplete.

Babel doesn't seem to support it. I got syntax errors when trying to use new.target in a function (arrow or others).

What is it, and how is it supposed to be used?

Answer 1

You didn't find it in the spec because in the syntax definitions it is written with blanks, as new . target. The name of the expression is NewTarget, and you'll find that term a few times around.

NewTarget is the first of the so-called meta properties and can be found in §12.3.8.

Its sole purpose is to retrieve the current value of the [[NewTarget]] value of the current (non-arrow) function environment. It is a value that is set when a function is called (very much like the this binding), and according to §8.1.1.3 Function Environment Records:

If this Environment Record was created by the [[Construct]] internal method, [[NewTarget]] is the value of the [[Construct]] newTarget parameter. Otherwise, its value is undefined.

So, for one thing, finally enables us to detect whether a function was called as a constructor or not.

But that's not its real purpose. So what is it then? It is part of the way how ES6 classes are not only syntactic sugar, and how they allow us inheriting from builtin objects. When you call a class constructor via new X, the this value is not yet initialised - the object is not yet created when the constructor body is entered. It does get created by the super constructor during the super() call (which is necessary when internal slots are supposed to be created). Still, the instance should inherit from the .prototype of the originally called constructor, and that's where newTarget comes into the play. It does hold the "outermost" constructor that received the new call during super() invocations. You can follow it all the way down in the spec, but basically it always is the newTarget not the currently executed constructor that does get passed into the OrdinaryCreateFromConstructor procedure - for example in step 5 of §9.2.2 [[Construct]] for user-defined functions.

Long text, maybe an example is better suited:

class Parent {
    constructor() {
        // implicit (from the `super` call)
        //    new.target = Child;
        // implicit (because `Parent` doesn't extend anything):
        //    this = Object.create(new.target.prototype);
        console.log(new.target) // Child!
    }
}
class Child extends Parent {
    constructor() {
        // `this` is uninitialised (and would throw if accessed)
        // implicit (from the `new` call):
        //    new.target = Child 
        super(); // this = Reflect.construct(Parent, [], new.target);
        console.log(this);
    }
}
new Child;

Answer 2

It's primarily intended as a better way to detect when a constructor is called without new.

From http://www.2ality.com/2015/02/es6-classes-final.html:

new.target is an implicit parameter that all functions have. It is to constructor calls what this is to method calls.

So I can write:

function Foo() {
  if (!new.target) throw "Foo() must be called with new";
  ...
}

There are more details to how this works, and more contexts in which it is useful, but we'll leave it here.

For some meeting notes regarding new.target, see https://esdiscuss.org/notes/2015-01-27.