Add InstanceType tip in Classes.md

[bdombro]

I personally have a hard time finding this type helper (InstanceType) and would love for it to be in the official docs on Classes.

[jakebailey]

This isn't correct, see: Playground Link

A variable annotated like const x: Point is already a value of the instance type of Point. InstanceType works on the actual type of the class itself, and that's pretty rare.

I don't think that this part of the page is what should mention InstanceType; we haven't even established what a class can contain or how to use it, let along what an instance is.

[bdombro]

Oh yeah you caught a typo thanks @jakebailey, should be:

type PointInstance = InstanceType<typeof Point>

Here is how it's useful: Playground LInk

Not sure I understand why not to include it in docs though --is InstanceType an unstable feature? Assuming it is stable, shouldn't we document it somewhere? And would be great to have it on the page with Classes imho

[jakebailey]

Not sure I understand why not to include it in docs though --is InstanceType an unstable feature? Assuming it is stable, shouldn't we document it somewhere? And would be great to have it on the page with Classes imho

It's certainly stable, yes. It's defined as:

/**
 * Obtain the return type of a constructor function type
 */
type InstanceType<T extends abstract new (...args: any) => any>
	= T extends abstract new (...args: any) => infer R ? R : any;

I'm not against documenting it, but I'm just saying that if we do, it shouldn't come right at the top; we haven't even introduced what classes are and how they work, let alone that they're objects with a new signature. The first (and only) mention of the new signature is down at the bottom.

[bdombro]

good points. Should we maybe add it at the bottom of Constructor section (link), since InstanceOf returns the type of a constructor function?

[jakebailey]

I think better would be a section about constructor signatures, placed at least before the mention of new () in the abstract constructor signature section. Whether or not that's a full section, or just a part of the constructor section, I'm not sure. I feel like its own section is preferable.

[bdombro]

Sure! I updated the PR.

[bdombro]

@microsoft-github-policy-service agree

[jakebailey]

I'm not quite sure what the right wording is, but I don't think that "calling" is the right one as that can imply Point(1, 2) works (not new Point(1, 2)), even though those are two things. Potentially our docs already describe it as new-ing? Or as just instantiation?

Potentially what this section should be is a description of construct signatures? Or, just a link to https://www.typescriptlang.org/docs/handbook/2/functions.html#construct-signatures

Of course, it's unfortunate that classes and functions are described separately but have this intertwining behavior.

[bdombro]

how about I change it to "Instantiating a class returns a class instance, ..."?

[bdombro]

Hey @jakebailey -- following up on this question please

[orta]

Personally I think "Instantiating a class" is the right call probably, there isn't really language like this in the spec nor in MDN with that term, but it's such a globally used term in many languages that I think it fits.

Calling it something like a newable function is a bit more accurate but I think moves too far into 'abstract but correct' terminology

[jakebailey]

If anything I'd go for "instantiating a class produces a class instance", or "The new operator instantiates a class ...", etc.

So like:

Classes are instantiated with new. Given the type of a class itself, the InstanceType utility type will model this operation.

But, I'm a little iffy on this whole PR just from the point of view that it's duplicating content by describing both new (whose docs I linked to), but then also InstanceType, which is described on the utility type page. If anything, I think providing links to each section may be most helpful.

[bdombro]

I'm okay with dropping it if y'all don't want it. Honestly at this point I'm a little exhausted with all the back and forth.

[jakebailey]

Sorry about that.

If you want something concrete to finish this, then I would probably just use a variation of my text then use []() links to point the word "constructor" to /docs/handbook/2/functions.html#construct-signatures and `InstanceType` to /docs/handbook/utility-types.html#instancetypetype.

You could even just skip the code sample and let those sections speak for themselves.

[bdombro]

Okay! How about now? I accepted your suggestion and tweaked a little to better match those links you shared

[jakebailey]

Thanks for bearing with this.