Annotation of `this` in function declarations

[jussi-kalliokoski]

Currently it seems that you can only annotate the this magic reference by putting the function as a method in a class declaration.

However, in the light of the new bind syntax proposal, it would make sense to be able to annotate functions that take in this as data, e.g.

function head (count) {
    return this.slice(0, count);
}

[1,2,3]::head(2) // [1,2]

could be annotated something like:

function head <T> Array<T> -> (count : number) : Array<T> {
  ...
}

[samwgoldman]

Flow is (mostly) smart about this already without annotations. I'm not clear what this new bind syntax is (do you have a link to a spec?), but I imagine flow will support it the same way that flow currently supports bind, call, and apply.

/* @flow */

function head(count) {
  return this.slice(0, count);
}

head.bind([]) // OK
head.bind(1) // bad

[jussi-kalliokoski]

I'm not clear what this new bind syntax is (do you have a link to a spec?)

Ah, sorry, forgot the link, fixed.

Flow is (mostly) smart about this already without annotations

Yes, but it would be nice to be able to annotate this instead, for documentational purposes (easier to understand at a glance and also allows for better error messages, as well as documentation generation), but also for standalone definitions.

[jussi-kalliokoski]

Having thought about this a bit more, a simpler syntax would actually be to allow specifying this as a parameter, as so:

function add (this : number, b : number) : number {
  return this + b;
}

function add (/*: this : number, */ b /*: number */) /*: number */ {
  return this + b;
}

/*: (this : number, b: number) => number */
function add (b) {
  return this + b;
}

[avikchaudhuri]

Agree that we should support this to be annotated as a parameter. This requires some parser work too, btw, since this is not a valid identifier everywhere.

We need this whenever methods are exported, by the way. It's true Flow is good in inferring this types, but it sucks that this information is lost across modules.

Related: constructor functions can be annotated as of 618186a

[Artazor]

Hi guys! what about the following examples: microsoft/TypeScript#1985 (comment)
Are they too complex/ugly?

[izaakschroeder]

+1

[danvk]

Pulling in some material from #968: an example, and a link to how Google Closure does this.

---

There's an error (marked with <---) in this snippet which Flow could potentially catch:

class RemoteFile {
  url: string;
...
  promiseXHR(xhr: XMLHttpRequest): Q.Promise<[any, Event]> {
    var url = this.url;
    var deferred = Q.defer();
    xhr.addEventListener('load', function(e) {
      if (this.status >= 400) {
        deferred.reject(this.status + ' ' + this.statusText);
      } else {
        deferred.resolve([this.response, e]);
      }
    });
    xhr.addEventListener('error', function(e) {
      deferred.reject(`Request for ${this.url} failed: ${this.status}`);  // <---
    });
    this.numNetworkRequests++;
    xhr.send();
    return deferred.promise;
  }
}

The problem is that this inside the addEventListener callback refers to the XMLHttpRequest object (I believe) and not the RemoteFile class. The latter has a url property but not a status property, whereas the former has status but not url. Clearly this code isn't right!

Flow doesn't complain, though. It thinks this has type any in the event listener.

Where possible, the DOM declarations should indicate the type of this in callbacks to prevent this sort of mistake.

For example, Google's Closure Compiler provides an @this annotation. You can see an example of this in action in the declaration for Array.prototype.find.