Need documentation for InstanceType

[ffxsam]

I've been banging my head against the wall for hours trying to figure out how to extract a type/interface for an object, and someone clued me into InstanceType which is apparently not documented.

It would be awesome if some TS wiz could add this to the official docs.

[mhegazy]

If you hover on the declaration in your IDE you should see the docs:

[mhegazy]

You should also find them documented in the release notes: http://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#predefined-conditional-types

[ffxsam]

Both of those routes are insufficient. It should be documented in the handbook main docs (not release notes). The point is, I never knew about InstanceType until someone told me about it, and it was something I really needed. I would've known about it if it were in the documentation.

[mhegazy]

We do not document all the types in the standard library in the handbook. for instance ReadonlyArray is not there, nor is ReadonlySet, IterableIterator, Promise, etc..

[ffxsam]

Interesting. But then how is one supposed to learn about these? Where can I read up on what IterableIterator or ReadonlySet do, along with examples of usage?

[mhegazy]

We have relied on editor interaction for these. the types usually will have a JSDoc comment on them explaining what they do.

[ffxsam]

That's useful for sure. But the point I think you're missing is that nobody going through the docs would've learned about InstanceType. And you would have to know about it before looking for it via autocomplete in an editor like VS Code.

The TypeScript docs need a comprehensive API reference in the website docs, IMO. And I'd be happy to contribute, of course, but I'm too new to TypeScript.

[Praveen-Rai]

@ffxsam I am totally agreed with you, i've been into the same situation.
@mhegazy I think TypeScript must have an api reference document, and not just the getting started one. Not everybody is from JS background, infact people ( like me ) would be taking up TS just to avoid JS, as JS is conceptually very different from a language like C# and is not very well supported by Visual Studio.

[MicahZoltu]

@mhegazy I believe the difference between something like Promise and InstanceType is that Promise is well document as part of ES. As a developer, I know that I can use anything that is part of ES, and there is probably type information for those things that I can discovery through my editor (e.g., look at the return type of Promise.resolve(...)).

However, for something like InstanceType, this is purely a type system construct and not mentioned or hinted at anywhere in any ES documentation such as MDN. There is no way for me to discover this construct other than reading the release notes or having someone tell me about it.

I'm of the opinion that constructs that are unique to TypeScript and don't have any hints coming from ES should be documented in the TypeScript handbook. I tend to agree with you though that it is unnecessary to document all of the standard library stuff that derive from ES things.

[csantos42]

“Utility Types”, including InstanceType are documented in the Utility Types page in the Handbook, but it’s hard to find as it’s only accessible through GitHub and not the site. There are two open issues requesting that it be added to the sidebar:

microsoft/TypeScript-Handbook#945
microsoft/TypeScript-Handbook#914

[ducin]

What is the usecase of the InstanceType? Given class X, whatever it is, we've already got X as a type. InstanceType<typeof X> // X - so what's the meaning of this type? All other four conditional built-in types make perfect sense to me.

[ffxsam]

It's true, InstanceType seems kind of pointless now that I have a bit more time with TypeScript.

const spot1: InstanceType<typeof Dog> = new Dog('Spot');
const spot2: Dog = new Dog('Spot Evil Clone');

spot1.bark();
spot2.bark();

These types are exactly the same in the end.

[dragomirtitian]

@ducin @ffxsam Usually you don't need InstanceType. If the class is a regular class declaration you can just use the class name to get the instance type. There are however use-cases for InstanceType. Sometimes either the class declaration is not itself accessible (with mixins for example) or is unknown (when using generics) or is a class expression. Here are two code snippets where InstanceType is very much needed:

Mixins:

function mixin<T extends new (...a: any[])=> any>(baseClass: T) {
    class Extended extends baseClass {
        public extendedMethod() {}
    }
    return Extended;
}

let FinalClass = mixin(class {
    method() {}
})
let o: FinalClass // error FinalClass is not a type, it's just a value
let oo: InstanceType<typeof FinalClass>;
// Usually for convienence I would just add a type alias, so as to mimic a regular type declaration
// type FinalClass = InstanceType<typeof FinalClass>; // remove comment to remove error on o declaration

Factory Function:

declare function create<T extends new () => any>(c: T): InstanceType<T>

class A { }
class B { }
let a = create(A) // A
let b = create(B) // B