Typing this

The fake first parameter

Why does TypeScript need a special mechanism for this at all? Because this is the one value in JavaScript that is not determined by the function’s definition — it is set anew at every call site, which means the compiler cannot infer it from the source location alone.

JavaScript functions receive an implicit receiver: the this value, determined by how the function is called, not where it is defined. TypeScript lets you type that receiver with a special first parameter named this. It looks like a parameter but it is not one — it is erased at emit and never appears in the call’s argument list.

interface Card { suit: string; value: number }

function describe(this: Card): string {
  return `${this.value} of ${this.suit}`;
}

const card: Card = { suit: "hearts", value: 10 };
describe.call(card); // ok — `this` is supplied via .call
describe();
// Error: The 'this' context of type 'void' is not assignable
//        to method's 'this' of type 'Card'.

The emitted JavaScript is just function describe() { return this.value + ...; } — the this: Card annotation has vanished. Its only job was to type-check the receiver at every call site. Under --noImplicitThis (included in strict), a this used inside a function with no annotation and no inferable container is flagged as an implicit any, forcing you to declare it.

Methods carry an inferred this — and lose it when detached

Inside an object method or a class method, TypeScript infers this to be the containing object/instance. The problem appears when you detach the method — assign it to a variable or pass it as a callback — because the binding is set by the caller, not the definition.

class Counter {
  count = 0;
  inc(this: Counter) {     // explicit this for safety
    this.count++;
  }
}

const c = new Counter();
c.inc();          // ok — receiver is `c`
const f = c.inc;  // detached
f();
// Error: The 'this' context of type 'void' is not assignable
//        to method's 'this' of type 'Counter'.

This is the lost-this problem. Under the strictBindCallApply and method-this checks, TypeScript flags the unbound call. The runtime fixes are the usual ones — c.inc.bind(c), or an arrow-function field inc = () => { this.count++ } whose this is lexically the instance — but the type system is what surfaces the bug before it ships.

this-based type guards and polymorphic this

Two this-typed features power real APIs. First, a method can return this is Derived — a this-based type guard that narrows the receiver itself in the calling scope:

class FileNode {
  isDir(): this is DirNode {   // narrows `this`, not a parameter
    return "children" in this;
  }
}
class DirNode extends FileNode {
  children: FileNode[] = [];
}

declare const node: FileNode;
if (node.isDir()) {
  node.children;
  //   ^? FileNode[]   — node narrowed to DirNode inside the branch
}

Second, polymorphic this makes a method’s return type “whatever the current class is”, which keeps fluent builders correctly typed across inheritance:

class Query {
  where(cond: string): this {   // returns the concrete subclass, not Query
    return this;
  }
}
class UserQuery extends Query {
  byEmail(e: string): this { return this; }
}

new UserQuery().where("active").byEmail("a@b.com");
//                                ^^^^^^^ ok — where() returned UserQuery, not Query

If where had returned Query instead of this, the chain would break at .byEmail because Query has no such method. Polymorphic this is the type-level mechanism behind chainable builders. ThisType<T> is the related contextual-typing marker the standard library uses to type this inside object-literal method bags (the Vue-2 options object, mixins, fluent config), so methods inside the literal see the full assembled object as their this.