Answer.

In TypeScript, correct typing of this is critically important for supporting the method chaining pattern, where methods return this for consecutive calls. If the return type is not explicitly specified, TypeScript by default assumes the returned object is an instance of the current class, which is incorrect in inheritance scenarios.

To solve this problem, polymorphic this types are used through the returned this:

class Builder {
  value: number = 0;
  setValue(v: number): this {
    this.value = v;
    return this;
  }
}

class AdvancedBuilder extends Builder {
  multiply(factor: number): this {
    this.value *= factor;
    return this;
  }
}

const b = new AdvancedBuilder().setValue(5).multiply(2); // multiply is correctly visible

By returning this, it ensures that the method chain is correctly typed even for subclasses, rather than just the base class.

Trick Question.

Can you just specify the class name instead of using this in the return type (for example, returning Builder)? How will this impact method chains in subclasses?

Answer:

If you return Builder instead of this:

class Builder {
  setValue(v: number): Builder {
    //...
    return this;
  }
}

class AdvancedBuilder extends Builder {
  multiply(factor: number): this {
    // ...
    return this;
  }
}

const a = new AdvancedBuilder().setValue(2).multiply(2); // multiply is not visible!

multiply will be inaccessible after setValue because setValue returns Builder, not AdvancedBuilder. Only using this in the method signature retains the correct typing in the method chain.

Examples of real errors due to lack of understanding the nuances of the topic

---

Story

A fluent API was created in a team of developers for building configuration. The methods returned the type of the base class, considering it a good practice. After the appearance of a subclass in the fluent API, all additional methods became invisible after the chain of standard calls. Result: had to refactor the API to use this, so clients could use the extensions.

---

Story

In an internal library of decorators, specific types of classes were explicitly returned. Users lost access to new methods when using subclasses, receiving "object has no method ...". The error occurred only during integration with new services.

---

Story

A developer, copying methods from an old C# API, rewrote the method chain in TypeScript, returning the class name. Everything looked fine at build time, but new methods were lost in user subclasses. Only strict checking in tsconfig helped quickly identify this issue — and fix it to return this.