Clarify class property initializer behavior

The problem

Briefly, if a class property isn't initialized with the declaration, it will be initialized as undefined, no matter how you initialize it in constructor. This will lead to v8 performance issue because of property type transition in many cases.

So I think it's very important to mention the behavior difference in documentation.

Documentation difference

In Class field declarations proposal from TC39, it's very clearly mentioned that "Fields without initializers are set to undefined."

Thus in TS handbook, there is nowhere mentioned how the field declaration without initializer will be handled. Actually the documentation lead us to believe it's the same result to initialize a property in declaration or in constructor. E.G., in the Classes default example, it says:

In the last line we construct an instance of the Greeter class using new. This calls into the constructor we defined earlier, creating a new object with the Greeter shape, and running the constructor to initialize it.

But actually it's like the TC39 proposal, if you don't assign a default value in declaration, the property will be initialized as undefined in constructor (before your actual initialize code).

Take a look at a simple example

class Test {
    x: number;
    constructor(x: number) {
        this.x = x;
    }
}

With tsc, this will be generated as the following js

"use strict";
var Test = /** @class */ (function () {
    function Test(x) {
        Object.defineProperty(this, "x", {
            enumerable: true,
            configurable: true,
            writable: true,
            value: void 0
        });
        this.x = x;
    }
    return Test;
}());

As you can see, property this.x is firstly defined with void 0 (undefined) and then assigned with x parameter.

Why should we care

In the previous example, there is a type transition for the property x which is sadly not a good idea in v8. I assume it cause the Test instances to be polymorphic or it cause the Test instances generate a new hidden class. Anyway, the property access performance drops significantly after the construction.

Test case:
index.js.zip

From the simple test case with a loop of Vec3 calculations, we can see the performance difference

1. Initialize in declaration(Vec3_104): 4-5ms
2. Initialize in constructor(Vec3_110): 28-32ms

From more complexe use case in our engine's particle system simulation, the fps drops from 60fps to 30fps.

Conclusion

I'd like to suggest a very clear description of different initializer behaviors in TypeScript documentation, so that developers know that they really need to initialize in declaration.

If possible, we'd like TSC to improve the logic:

If developers are using constructor to initialize properties, then use that value for defineProperty directly, or use a type compatible value for defineProperty.

We have also submit an issue to babel which have similar behavior.

Start with the TypeScript Handbook Classes page linked in the issue, then compare its class initialization explanation with the TC39 class fields proposal and the emitted JavaScript example. Done means documenting the difference between declaration and constructor initialization, including the undefined initialization behavior and the performance concern described here.