This page lists some of the more advanced ways in which you can model types, it works in tandem with the Utility Types doc which includes types which are included in TypeScript and available globally.
Type Guards and Differentiating Types
Union types are useful for modeling situations when values can overlap in the types they can take on.
What happens when we need to know specifically whether we have a Fish
?
A common idiom in JavaScript to differentiate between two possible values is to check for the presence of a member.
As we mentioned, you can only access members that are guaranteed to be in all the constituents of a union type.
tsTry
letpet =getSmallPet ();// You can use the 'in' operator to checkif ("swim" inpet ) {pet .swim ();}// However, you cannot use property accessif (Property 'fly' does not exist on type 'Fish | Bird'. Property 'fly' does not exist on type 'Fish'.2339Property 'fly' does not exist on type 'Fish | Bird'. Property 'fly' does not exist on type 'Fish'.pet .) { fly Property 'fly' does not exist on type 'Fish | Bird'. Property 'fly' does not exist on type 'Fish'.2339Property 'fly' does not exist on type 'Fish | Bird'. Property 'fly' does not exist on type 'Fish'.pet .(); fly }
To get the same code working via property accessors, we’ll need to use a type assertion:
tsTry
letpet =getSmallPet ();letfishPet =pet asFish ;letbirdPet =pet asBird ;if (fishPet .swim ) {fishPet .swim ();} else if (birdPet .fly ) {birdPet .fly ();}
This isn’t the sort of code you would want in your codebase however.
User-Defined Type Guards
It would be much better if once we performed the check, we could know the type of pet
within each branch.
It just so happens that TypeScript has something called a type guard. A type guard is some expression that performs a runtime check that guarantees the type in some scope.
Using type predicates
To define a type guard, we simply need to define a function whose return type is a type predicate:
tsTry
functionisFish (pet :Fish |Bird ):pet isFish {return (pet asFish ).swim !==undefined ;}
pet is Fish
is our type predicate in this example.
A predicate takes the form parameterName is Type
, where parameterName
must be the name of a parameter from the current function signature.
Any time isFish
is called with some variable, TypeScript will narrow that variable to that specific type if the original type is compatible.
tsTry
// Both calls to 'swim' and 'fly' are now okay.letpet =getSmallPet ();if (isFish (pet )) {pet .swim ();} else {pet .fly ();}
Notice that TypeScript not only knows that pet
is a Fish
in the if
branch;
it also knows that in the else
branch, you don’t have a Fish
, so you must have a Bird
.
You may use the type guard isFish
to filter an array of Fish | Bird
and obtain an array of Fish
:
tsTry
constzoo : (Fish |Bird )[] = [getSmallPet (),getSmallPet (),getSmallPet ()];constunderWater1 :Fish [] =zoo .filter (isFish );// or, equivalentlyconstunderWater2 :Fish [] =zoo .filter <Fish >(isFish );constunderWater3 :Fish [] =zoo .filter <Fish >((pet ) =>isFish (pet ));
Using the in
operator
The in
operator also acts as a narrowing expression for types.
For a n in x
expression, where n
is a string literal or string literal type and x
is a union type, the “true” branch narrows to types which have an optional or required property n
, and the “false” branch narrows to types which have an optional or missing property n
.
tsTry
functionmove (pet :Fish |Bird ) {if ("swim" inpet ) {returnpet .swim ();}returnpet .fly ();}
typeof
type guards
Let’s go back and write the code for a version of padLeft
which uses union types.
We could write it with type predicates as follows:
tsTry
functionisNumber (x : any):x is number {return typeofx === "number";}functionisString (x : any):x is string {return typeofx === "string";}functionpadLeft (value : string,padding : string | number) {if (isNumber (padding )) {returnArray (padding + 1).join (" ") +value ;}if (isString (padding )) {returnpadding +value ;}throw newError (`Expected string or number, got '${padding }'.`);}
However, having to define a function to figure out if a type is a primitive is kind of a pain.
Luckily, you don’t need to abstract typeof x === "number"
into its own function because TypeScript will recognize it as a type guard on its own.
That means we could just write these checks inline.
tsTry
functionpadLeft (value : string,padding : string | number) {if (typeofpadding === "number") {returnArray (padding + 1).join (" ") +value ;}if (typeofpadding === "string") {returnpadding +value ;}throw newError (`Expected string or number, got '${padding }'.`);}
These typeof
type guards are recognized in two different forms: typeof v === "typename"
and typeof v !== "typename"
, where "typename"
can be one of typeof
operator’s return values ("undefined"
, "number"
, "string"
, "boolean"
, "bigint"
, "symbol"
, "object"
, or "function"
).
While TypeScript won’t stop you from comparing to other strings, the language won’t recognize those expressions as type guards.
instanceof
type guards
If you’ve read about typeof
type guards and are familiar with the instanceof
operator in JavaScript, you probably have some idea of what this section is about.
instanceof
type guards are a way of narrowing types using their constructor function.
For instance, let’s borrow our industrial strength string-padder example from earlier:
tsTry
interfacePadder {getPaddingString (): string;}classSpaceRepeatingPadder implementsPadder {constructor(privatenumSpaces : number) {}getPaddingString () {returnArray (this.numSpaces + 1).join (" ");}}classStringPadder implementsPadder {constructor(privatevalue : string) {}getPaddingString () {return this.value ;}}functiongetRandomPadder () {returnMath .random () < 0.5? newSpaceRepeatingPadder (4): newStringPadder (" ");}letpadder :Padder =getRandomPadder ();if (padder instanceofSpaceRepeatingPadder ) {padder ;}if (padder instanceofStringPadder ) {padder ;}
The right side of the instanceof
needs to be a constructor function, and TypeScript will narrow down to:
- the type of the function’s
prototype
property if its type is notany
- the union of types returned by that type’s construct signatures
in that order.
Nullable types
TypeScript has two special types, null
and undefined
, that have the values null and undefined respectively.
We mentioned these briefly in the Basic Types section.
By default, the type checker considers null
and undefined
assignable to anything.
Effectively, null
and undefined
are valid values of every type.
That means it’s not possible to stop them from being assigned to any type, even when you would like to prevent it.
The inventor of null
, Tony Hoare, calls this his “billion dollar mistake”.
The strictNullChecks
flag fixes this: when you declare a variable, it doesn’t automatically include null
or undefined
.
You can include them explicitly using a union type:
tsTry
letexampleString = "foo";Type 'null' is not assignable to type 'string'.2322Type 'null' is not assignable to type 'string'.= null; exampleString letstringOrNull : string | null = "bar";stringOrNull = null;Type 'undefined' is not assignable to type 'string | null'.2322Type 'undefined' is not assignable to type 'string | null'.= stringOrNull undefined ;
Note that TypeScript treats null
and undefined
differently in order to match JavaScript semantics.
string | null
is a different type than string | undefined
and string | undefined | null
.
From TypeScript 3.7 and onwards, you can use optional chaining to simplify working with nullable types.
Optional parameters and properties
With strictNullChecks
, an optional parameter automatically adds | undefined
:
tsTry
functionf (x : number,y ?: number) {returnx + (y ?? 0);}f (1, 2);f (1);f (1,undefined );Argument of type 'null' is not assignable to parameter of type 'number | undefined'.2345Argument of type 'null' is not assignable to parameter of type 'number | undefined'.f (1,null );
The same is true for optional properties:
tsTry
classC {a : number;b ?: number;}letc = newC ();c .a = 12;Type 'undefined' is not assignable to type 'number'.2322Type 'undefined' is not assignable to type 'number'.c .a =undefined ;c .b = 13;c .b =undefined ;Type 'null' is not assignable to type 'number | undefined'.2322Type 'null' is not assignable to type 'number | undefined'.c .b = null;
Type guards and type assertions
Since nullable types are implemented with a union, you need to use a type guard to get rid of the null
.
Fortunately, this is the same code you’d write in JavaScript:
tsTry
functionf (stringOrNull : string | null): string {if (stringOrNull === null) {return "default";} else {returnstringOrNull ;}}
The null
elimination is pretty obvious here, but you can use terser operators too:
tsTry
functionf (stringOrNull : string | null): string {returnstringOrNull ?? "default";}
In cases where the compiler can’t eliminate null
or undefined
, you can use the type assertion operator to manually remove them.
The syntax is postfix !
: identifier!
removes null
and undefined
from the type of identifier
:
tsTry
interfaceUserAccount {id : number;}constuser =getUser ("admin");'user' is possibly 'undefined'.18048'user' is possibly 'undefined'.. user id ;if (user ) {'user.email' is possibly 'undefined'.18048'user.email' is possibly 'undefined'.user .length ;}// Instead if you are sure that these objects or fields exist, the// postfix ! lets you short circuit the nullabilityuser !.length ;
Type Aliases
Type aliases create a new name for a type. Type aliases are sometimes similar to interfaces, but can name primitives, unions, tuples, and any other types that you’d otherwise have to write by hand.
tsTry
typeSecond = number;lettimeInSecond : number = 10;lettime :Second = 10;
Aliasing doesn’t actually create a new type - it creates a new name to refer to that type. Aliasing a primitive is not terribly useful, though it can be used as a form of documentation.
Just like interfaces, type aliases can also be generic - we can just add type parameters and use them on the right side of the alias declaration:
ts
type Container<T> = { value: T };
We can also have a type alias refer to itself in a property:
ts
type Tree<T> = {value: T;left?: Tree<T>;right?: Tree<T>;};
Together with intersection types, we can make some pretty mind-bending types:
tsTry
typeLinkedList <Type > =Type & {next :LinkedList <Type > };interfacePerson {name : string;}letpeople =getDriversLicenseQueue ();people .name ;people .next .name ;people .next .next .name ;people .next .next .next .name ;
Interfaces vs. Type Aliases
As we mentioned, type aliases can act sort of like interfaces; however, there are some subtle differences.
Almost all features of an interface
are available in type
, the key distinction is that a type cannot be re-opened to add new properties vs an interface which is always extendable.
Interface |
Type |
---|---|
Extending an interface
|
Extending a type via intersections
|
Adding new fields to an existing interface
|
A type cannot be changed after being created
|
Because an interface more closely maps how JavaScript objects work by being open to extension, we recommend using an interface over a type alias when possible.
On the other hand, if you can’t express some shape with an interface and you need to use a union or tuple type, type aliases are usually the way to go.
Enum Member Types
As mentioned in our section on enums, enum members have types when every member is literal-initialized.
Much of the time when we talk about “singleton types”, we’re referring to both enum member types as well as numeric/string literal types, though many users will use “singleton types” and “literal types” interchangeably.
Polymorphic this
types
A polymorphic this
type represents a type that is the subtype of the containing class or interface.
This is called F-bounded polymorphism, a lot of people know it as the fluent API pattern.
This makes hierarchical fluent interfaces much easier to express, for example.
Take a simple calculator that returns this
after each operation:
tsTry
classBasicCalculator {public constructor(protectedvalue : number = 0) {}publiccurrentValue (): number {return this.value ;}publicadd (operand : number): this {this.value +=operand ;return this;}publicmultiply (operand : number): this {this.value *=operand ;return this;}// ... other operations go here ...}letv = newBasicCalculator (2).multiply (5).add (1).currentValue ();
Since the class uses this
types, you can extend it and the new class can use the old methods with no changes.
tsTry
classScientificCalculator extendsBasicCalculator {public constructor(value = 0) {super(value );}publicsin () {this.value =Math .sin (this.value );return this;}// ... other operations go here ...}letv = newScientificCalculator (2).multiply (5).sin ().add (1).currentValue ();
Without this
types, ScientificCalculator
would not have been able to extend BasicCalculator
and keep the fluent interface.
multiply
would have returned BasicCalculator
, which doesn’t have the sin
method.
However, with this
types, multiply
returns this
, which is ScientificCalculator
here.
Index types
With index types, you can get the compiler to check code that uses dynamic property names. For example, a common JavaScript pattern is to pick a subset of properties from an object:
js
function pluck(o, propertyNames) {return propertyNames.map((n) => o[n]);}
Here’s how you would write and use this function in TypeScript, using the index type query and indexed access operators:
tsTry
functionpluck <T ,K extends keyofT >(o :T ,propertyNames :K []):T [K ][] {returnpropertyNames .map ((n ) =>o [n ]);}interfaceCar {manufacturer : string;model : string;year : number;}lettaxi :Car = {manufacturer : "Toyota",model : "Camry",year : 2014,};// Manufacturer and model are both of type string,// so we can pluck them both into a typed string arrayletmakeAndModel : string[] =pluck (taxi , ["manufacturer", "model"]);// If we try to pluck model and year, we get an// array of a union type: (string | number)[]letmodelYear =pluck (taxi , ["model", "year"]);
The compiler checks that manufacturer
and model
are actually properties on Car
.
The example introduces a couple of new type operators.
First is keyof T
, the index type query operator.
For any type T
, keyof T
is the union of known, public property names of T
.
For example:
tsTry
letcarProps : keyofCar ;
keyof Car
is completely interchangeable with "manufacturer" | "model" | "year"
.
The difference is that if you add another property to Car
, say ownersAddress: string
, then keyof Car
will automatically update to be "manufacturer" | "model" | "year" | "ownersAddress"
.
And you can use keyof
in generic contexts like pluck
, where you can’t possibly know the property names ahead of time.
That means the compiler will check that you pass the right set of property names to pluck
:
ts
// error, Type '"unknown"' is not assignable to type '"manufacturer" | "model" | "year"'pluck(taxi, ["year", "unknown"]);
The second operator is T[K]
, the indexed access operator.
Here, the type syntax reflects the expression syntax.
That means that taxi["manufacturer"]
has the type Car["manufacturer"]
— which in our example is just string
.
However, just like index type queries, you can use T[K]
in a generic context, which is where its real power comes to life.
You just have to make sure that the type variable K extends keyof T
.
Here’s another example with a function named getProperty
.
ts
function getProperty<T, K extends keyof T>(o: T, propertyName: K): T[K] {return o[propertyName]; // o[propertyName] is of type T[K]}
In getProperty
, o: T
and propertyName: K
, so that means o[propertyName]: T[K]
.
Once you return the T[K]
result, the compiler will instantiate the actual type of the key, so the return type of getProperty
will vary according to which property you request.
tsTry
letmanufacturer : string =getProperty (taxi , "manufacturer");letyear : number =getProperty (taxi , "year");letArgument of type '"unknown"' is not assignable to parameter of type 'keyof Car'.2345Argument of type '"unknown"' is not assignable to parameter of type 'keyof Car'.unknown =getProperty (taxi ,"unknown" );
Index types and index signatures
keyof
and T[K]
interact with index signatures. An index signature parameter type must be ‘string’ or ‘number’.
If you have a type with a string index signature, keyof T
will be string | number
(and not just string
, since in JavaScript you can access an object property either
by using strings (object["42"]
) or numbers (object[42]
)).
And T[string]
is just the type of the index signature:
tsTry
interfaceDictionary <T > {[key : string]:T ;}letkeys : keyofDictionary <number>;letvalue :Dictionary <number>["foo"];
If you have a type with a number index signature, keyof T
will just be number
.
tsTry
interfaceDictionary <T > {[key : number]:T ;}letkeys : keyofDictionary <number>;letnumberValue :Dictionary <number>[42];letProperty 'foo' does not exist on type 'Dictionary<number>'.2339Property 'foo' does not exist on type 'Dictionary<number>'.value :Dictionary <number>["foo" ];
Mapped types
A common task is to take an existing type and make each of its properties optional:
ts
interface PersonSubset {name?: string;age?: number;}
Or we might want a readonly version:
ts
interface PersonReadonly {readonly name: string;readonly age: number;}
This happens often enough in JavaScript that TypeScript provides a way to create new types based on old types — mapped types.
In a mapped type, the new type transforms each property in the old type in the same way.
For example, you can make all properties optional or of a type readonly
.
Here are a couple of examples:
tsTry
typePartial <T > = {[P in keyofT ]?:T [P ];};typeReadonly <T > = {readonly [P in keyofT ]:T [P ];};
And to use it:
tsTry
typePersonPartial =Partial <Person >;typeReadonlyPerson =Readonly <Person >;
Note that this syntax describes a type rather than a member. If you want to add members, you can use an intersection type:
tsTry
// Use this:typePartialWithNewMember <T > = {[P in keyofT ]?:T [P ];} & {newMember : boolean }// This is an error!typeWrongPartialWithNewMember <T > = {[P in keyofT ]?:T [P ];A mapped type may not declare properties or methods.7061A mapped type may not declare properties or methods.: boolean; newMember }
Let’s take a look at the simplest mapped type and its parts:
tsTry
typeKeys = "option1" | "option2";typeFlags = { [K inKeys ]: boolean };
The syntax resembles the syntax for index signatures with a for .. in
inside.
There are three parts:
- The type variable
K
, which gets bound to each property in turn. - The string literal union
Keys
, which contains the names of properties to iterate over. - The resulting type of the property.
In this simple example, Keys
is a hard-coded list of property names and the property type is always boolean
, so this mapped type is equivalent to writing:
tsTry
typeFlags = {option1 : boolean;option2 : boolean;};
Real applications, however, look like Readonly
or Partial
above.
They’re based on some existing type, and they transform the properties in some way.
That’s where keyof
and indexed access types come in:
tsTry
typeNullablePerson = { [P in keyofPerson ]:Person [P ] | null };typePartialPerson = { [P in keyofPerson ]?:Person [P ] };
But it’s more useful to have a general version.
ts
type Nullable<T> = { [P in keyof T]: T[P] | null };type Partial<T> = { [P in keyof T]?: T[P] };
In these examples, the properties list is keyof T
and the resulting type is some variant of T[P]
.
This is a good template for any general use of mapped types.
That’s because this kind of transformation is homomorphic, which means that the mapping applies only to properties of T
and no others.
The compiler knows that it can copy all the existing property modifiers before adding any new ones.
For example, if Person.name
was readonly, Partial<Person>.name
would be readonly and optional.
Here’s one more example, in which T[P]
is wrapped in a Proxy<T>
class:
tsTry
typeProxy <T > = {get ():T ;set (value :T ): void;};typeProxify <T > = {[P in keyofT ]:Proxy <T [P ]>;};functionproxify <T >(o :T ):Proxify <T > {// ... wrap proxies ...}letprops = {rooms : 4 };letproxyProps =proxify (props );
Note that Readonly<T>
and Partial<T>
are so useful, they are included in TypeScript’s standard library along with Pick
and Record
:
ts
type Pick<T, K extends keyof T> = {[P in K]: T[P];};type Record<K extends keyof any, T> = {[P in K]: T;};
Readonly
, Partial
and Pick
are homomorphic whereas Record
is not.
One clue that Record
is not homomorphic is that it doesn’t take an input type to copy properties from:
tsTry
typeThreeStringProps =Record <"prop1" | "prop2" | "prop3", string>;
Non-homomorphic types are essentially creating new properties, so they can’t copy property modifiers from anywhere.
Note that keyof any
represents the type of any value that can be used as an index to an object. In otherwords, keyof any
is currently equal to string | number | symbol
.
Inference from mapped types
Now that you know how to wrap the properties of a type, the next thing you’ll want to do is unwrap them. Fortunately, that’s pretty easy:
tsTry
functionunproxify <T >(t :Proxify <T >):T {letresult = {} asT ;for (constk int ) {result [k ] =t [k ].get ();}returnresult ;}letoriginalProps =unproxify (proxyProps );
Note that this unwrapping inference only works on homomorphic mapped types. If the mapped type is not homomorphic you’ll have to give an explicit type parameter to your unwrapping function.
Conditional Types
A conditional type selects one of two possible types based on a condition expressed as a type relationship test:
ts
T extends U ? X : Y
The type above means when T
is assignable to U
the type is X
, otherwise the type is Y
.
A conditional type T extends U ? X : Y
is either resolved to X
or Y
, or deferred because the condition depends on one or more type variables.
When T
or U
contains type variables, whether to resolve to X
or Y
, or to defer, is determined by whether or not the type system has enough information to conclude that T
is always assignable to U
.
As an example of some types that are immediately resolved, we can take a look at the following example:
tsTry
declare functionf <T extends boolean>(x :T ):T extends true ? string : number;// Type is 'string | number'letx =f (Math .random () < 0.5);
Another example would be the TypeName
type alias, which uses nested conditional types:
tsTry
typeTypeName <T > =T extends string? "string":T extends number? "number":T extends boolean? "boolean":T extends undefined? "undefined":T extendsFunction ? "function": "object";typeT0 =TypeName <string>;typeT1 =TypeName <"a">;typeT2 =TypeName <true>;typeT3 =TypeName <() => void>;typeT4 =TypeName <string[]>;
But as an example of a place where conditional types are deferred - where they stick around instead of picking a branch - would be in the following:
tsTry
interfaceFoo {propA : boolean;propB : boolean;}declare functionf <T >(x :T ):T extendsFoo ? string : number;functionfoo <U >(x :U ) {// Has type 'U extends Foo ? string : number'leta =f (x );// This assignment is allowed though!letb : string | number =a ;}
In the above, the variable a
has a conditional type that hasn’t yet chosen a branch.
When another piece of code ends up calling foo
, it will substitute in U
with some other type, and TypeScript will re-evaluate the conditional type, deciding whether it can actually pick a branch.
In the meantime, we can assign a conditional type to any other target type as long as each branch of the conditional is assignable to that target.
So in our example above we were able to assign U extends Foo ? string : number
to string | number
since no matter what the conditional evaluates to, it’s known to be either string
or number
.
Distributive conditional types
Conditional types in which the checked type is a naked type parameter are called distributive conditional types.
Distributive conditional types are automatically distributed over union types during instantiation.
For example, an instantiation of T extends U ? X : Y
with the type argument A | B | C
for T
is resolved as (A extends U ? X : Y) | (B extends U ? X : Y) | (C extends U ? X : Y)
.
Example
tsTry
typeT5 =TypeName <string | (() => void)>;typeT6 =TypeName <string | string[] | undefined>;typeT7 =TypeName <string[] | number[]>;
In instantiations of a distributive conditional type T extends U ? X : Y
, references to T
within the conditional type are resolved to individual constituents of the union type (i.e. T
refers to the individual constituents after the conditional type is distributed over the union type).
Furthermore, references to T
within X
have an additional type parameter constraint U
(i.e. T
is considered assignable to U
within X
).
Example
tsTry
typeBoxedValue <T > = {value :T };typeBoxedArray <T > = {array :T [] };typeBoxed <T > =T extends any[] ?BoxedArray <T [number]> :BoxedValue <T >;typeT1 =Boxed <string>;typeT2 =Boxed <number[]>;typeT3 =Boxed <string | number[]>;
Notice that T
has the additional constraint any[]
within the true branch of Boxed<T>
and it is therefore possible to refer to the element type of the array as T[number]
. Also, notice how the conditional type is distributed over the union type in the last example.
The distributive property of conditional types can conveniently be used to filter union types:
tsTry
// Remove types from T that are assignable to UtypeDiff <T ,U > =T extendsU ? never :T ;// Remove types from T that are not assignable to UtypeFilter <T ,U > =T extendsU ?T : never;typeT1 =Diff <"a" | "b" | "c" | "d", "a" | "c" | "f">;typeT2 =Filter <"a" | "b" | "c" | "d", "a" | "c" | "f">; // "a" | "c"typeT3 =Diff <string | number | (() => void),Function >; // string | numbertypeT4 =Filter <string | number | (() => void),Function >; // () => void// Remove null and undefined from TtypeNotNullable <T > =Diff <T , null | undefined>;typeT5 =NotNullable <string | number | undefined>;typeT6 =NotNullable <string | string[] | null | undefined>;functionf1 <T >(x :T ,y :NotNullable <T >) {x =y ;Type 'T' is not assignable to type 'Diff<T, null | undefined>'.2322Type 'T' is not assignable to type 'Diff<T, null | undefined>'.= y x ;}functionf2 <T extends string | undefined>(x :T ,y :NotNullable <T >) {x =y ;Type 'T' is not assignable to type 'Diff<T, null | undefined>'. Type 'string | undefined' is not assignable to type 'Diff<T, null | undefined>'. Type 'undefined' is not assignable to type 'Diff<T, null | undefined>'.2322Type 'T' is not assignable to type 'Diff<T, null | undefined>'. Type 'string | undefined' is not assignable to type 'Diff<T, null | undefined>'. Type 'undefined' is not assignable to type 'Diff<T, null | undefined>'.= y x ;lets1 : string =x ;lets2 : string =y ;}
Conditional types are particularly useful when combined with mapped types:
tsTry
typeFunctionPropertyNames <T > = {[K in keyofT ]:T [K ] extendsFunction ?K : never;}[keyofT ];typeFunctionProperties <T > =Pick <T ,FunctionPropertyNames <T >>;typeNonFunctionPropertyNames <T > = {[K in keyofT ]:T [K ] extendsFunction ? never :K ;}[keyofT ];typeNonFunctionProperties <T > =Pick <T ,NonFunctionPropertyNames <T >>;interfacePart {id : number;name : string;subparts :Part [];updatePart (newName : string): void;}typeT1 =FunctionPropertyNames <Part >;typeT2 =NonFunctionPropertyNames <Part >;typeT3 =FunctionProperties <Part >;typeT4 =NonFunctionProperties <Part >;
Note, conditional types are not permitted to reference themselves recursively. For example the following is an error.
Example
tsTry
typeElementType <T > =T extends any[] ?ElementType <T [number]> :T ; // Error
Type inference in conditional types
Within the extends
clause of a conditional type, it is now possible to have infer
declarations that introduce a type variable to be inferred.
Such inferred type variables may be referenced in the true branch of the conditional type.
It is possible to have multiple infer
locations for the same type variable.
For example, the following extracts the return type of a function type:
tsTry
typeReturnType <T > =T extends (...args : any[]) => inferR ?R : any;
Conditional types can be nested to form a sequence of pattern matches that are evaluated in order:
tsTry
typeUnpacked <T > =T extends (inferU )[]?U :T extends (...args : any[]) => inferU ?U :T extendsPromise <inferU >?U :T ;typeT0 =Unpacked <string>;typeT1 =Unpacked <string[]>;typeT2 =Unpacked <() => string>;typeT3 =Unpacked <Promise <string>>;typeT4 =Unpacked <Promise <string>[]>;typeT5 =Unpacked <Unpacked <Promise <string>[]>>;
The following example demonstrates how multiple candidates for the same type variable in co-variant positions causes a union type to be inferred:
tsTry
typeFoo <T > =T extends {a : inferU ;b : inferU } ?U : never;typeT1 =Foo <{a : string;b : string }>;typeT2 =Foo <{a : string;b : number }>;
Likewise, multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred:
tsTry
typeBar <T > =T extends {a : (x : inferU ) => void;b : (x : inferU ) => void }?U : never;typeT1 =Bar <{a : (x : string) => void;b : (x : string) => void }>;typeT2 =Bar <{a : (x : string) => void;b : (x : number) => void }>;
When inferring from a type with multiple call signatures (such as the type of an overloaded function), inferences are made from the last signature (which, presumably, is the most permissive catch-all case). It is not possible to perform overload resolution based on a list of argument types.
tsTry
declare functionfoo (x : string): number;declare functionfoo (x : number): string;declare functionfoo (x : string | number): string | number;typeT1 =ReturnType <typeoffoo >;
It is not possible to use infer
declarations in constraint clauses for regular type parameters:
tsTry
type'infer' declarations are only permitted in the 'extends' clause of a conditional type.Cannot find name 'R'.1338ReturnedType <T extends (...args : any[]) => inferR > =; R
2304'infer' declarations are only permitted in the 'extends' clause of a conditional type.Cannot find name 'R'.
However, much the same effect can be obtained by erasing the type variables in the constraint and instead specifying a conditional type:
tsTry
typeAnyFunction = (...args : any[]) => any;typeReturnType <T extendsAnyFunction > =T extends (...args : any[]) => inferR ?R : any;
Predefined conditional types
TypeScript adds several predefined conditional types, you can find the full list and examples in Utility Types.