Polymorphic this & Fluent APIs

## Where the chain collapses ```ts class QueryBuilder { where(sql: string): QueryBuilder { /* ... */ return this; } } class UserQuery extends QueryBuilder { withRoles(): UserQuery { return this; } } new UserQuery().where('id = 1').withRoles(); // error: Property 'withRoles' does not exist on type 'QueryBuilder'. ``` At runtime this works perfectly — `where` returns the same `UserQuery` object, which certainly has `withRoles` on its prototype chain. The failure is a modelling failure: the declared signature says `QueryBuilder`, and the checker reasons from the declaration, not from what the body happens to do. Once the expression's type is `QueryBuilder`, every subclass member is invisible for the rest of the chain, no matter what order the calls come in. ## `this` in type position TypeScript lets you write `this` where a type is expected. That is the **polymorphic `this` type**, and it is a different thing from the `this` value inside the body. Think of it as an implicit type parameter that every class declaration carries, constrained by the class itself, and instantiated with the type of the receiver at each call site: ```ts class QueryBuilder { private parts: string[] = []; where(sql: string): this { this.parts.push(`WHERE ${sql}`); return this; } } ``` Called on a `QueryBuilder`, `where` returns `QueryBuilder`. Called on a `UserQuery`, the very same declaration returns `UserQuery`. One signature, inherited unchanged, that stays accurate for every subclass anyone writes later — including subclasses that did not exist when the base was written. ## Walking the fixed example ```ts class UserQuery extends QueryBuilder { withRoles(): this { return this.where('role IS NOT NULL'); } } new UserQuery().where('id = 1').withRoles(); // ok ``` `new UserQuery()` has type `UserQuery`; `where` therefore yields `UserQuery`; `withRoles` is found. Note the subclass method also returns `this` rather than `UserQuery` — that keeps the chain intact for anyone who subclasses `UserQuery` in turn. And note that `this.where(...)` inside `withRoles` type-checks: it returns `this`, which is exactly what the signature promises. ## Assignability runs one way Because `this` is bounded by the declaring class, `this` is assignable to `QueryBuilder` — a `this` value is always at least a `QueryBuilder`. The reverse is not true: a plain `QueryBuilder` is **not** assignable to `this`, since `this` might stand for some subclass with extra members. That asymmetry is the whole reason the type is useful, and it is also why a method typed `(): this` cannot simply hand back a freshly constructed base instance. ## You usually get it for free If the body is just `return this;` and you leave the return type off, the compiler infers `this` on its own. In real code the collapsed chain almost always traces back to someone helpfully writing the class name by hand, or to a `.d.ts` written that way. Reviewing a fluent class, the question to ask is not "is the return type annotated?" but "does the annotation say `this`?" ## Interfaces and abstract members The polymorphic `this` type is not limited to class bodies: ```ts interface Resettable { reset(): this; } class Session implements Resettable { reset(): this { return this; } } ``` Each implementer instantiates `this` with its own type, so an interface can describe a fluent contract without knowing any of the classes that will satisfy it. ## The promise it makes `(): this` claims the returned value *is* the receiver's own type. That holds trivially when the body returns `this`. It does not hold for a method that builds a new object, and the compiler will say so — a separate problem worth knowing about before you reach for `this` on a copy-on-write API. ## Erasure Swapping `QueryBuilder` for `this` in the annotation changes the emitted JavaScript not at all. There is no runtime marker, no helper, no reflection: the subclass came back either way, and the only difference is whether the checker was willing to admit it.