Union types are useful for modeling situations when values can overlap in the types they can take on.\nWhat happens when we need to know specifically whether we have a Fish?\nA common idiom in JavaScript to differentiate between two possible values is to check for the presence of a member.\nAs we mentioned, you can only access members that are guaranteed to be in all the constituents of a union type.
\ntslet pet = getSmallPet();\n\n// Each of these property accesses will cause an error\nif (pet.swim) {\n pet.swim();\n} else if (pet.fly) {\n pet.fly();\n}
To get the same code working, we’ll need to use a type assertion:
\n\ntslet pet = getSmallPet();\n\nif ((pet as Fish).swim) {\n (pet as Fish).swim();\n} else if ((pet as Bird).fly) {\n (pet as Bird).fly();\n}
Notice that we had to use type assertions several times.\nIt 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.\nA type guard is some expression that performs a runtime check that guarantees the type in some scope.
\nTo define a type guard, we simply need to define a function whose return type is a type predicate:
\n\ntsfunction isFish(pet: Fish | Bird): pet is Fish {\n return (pet as Fish).swim !== undefined;\n}
pet is Fish is our type predicate in this example.\nA 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.
\nts// Both calls to 'swim' and 'fly' are now okay.\n\nif (isFish(pet)) {\n pet.swim();\n} else {\n pet.fly();\n}
Notice that TypeScript not only knows that pet is a Fish in the if branch;\nit also knows that in the else branch, you don’t have a Fish, so you must have a Bird.
in operatorThe in operator now 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.
\ntsfunction move(pet: Fish | Bird) {\n if (\"swim\" in pet) {\n return pet.swim();\n }\n return pet.fly();\n}
typeof type guardsLet’s go back and write the code for the version of padLeft that uses union types.\nWe could write it with type predicates as follows:
\ntsfunction isNumber(x: any): x is number {\n return typeof x === \"number\";\n}\n\nfunction isString(x: any): x is string {\n return typeof x === \"string\";\n}\n\nfunction padLeft(value: string, padding: string | number) {\n if (isNumber(padding)) {\n return Array(padding + 1).join(\" \") + value;\n }\n if (isString(padding)) {\n return padding + value;\n }\n throw new Error(`Expected string or number, got '${padding}'.`);\n}
However, having to define a function to figure out if a type is a primitive is kind of a pain.\nLuckily, 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.\nThat means we could just write these checks inline.
\ntsfunction padLeft(value: string, padding: string | number) {\n if (typeof padding === \"number\") {\n return Array(padding + 1).join(\" \") + value;\n }\n if (typeof padding === \"string\") {\n return padding + value;\n }\n throw new Error(`Expected string or number, got '${padding}'.`);\n}
These typeof type guards are recognized in two different forms: typeof v === \"typename\" and typeof v !== \"typename\", where \"typename\" must be \"number\", \"string\", \"boolean\", or \"symbol\".\nWhile TypeScript won’t stop you from comparing to other strings, the language won’t recognize those expressions as type guards.
instanceof type guardsIf 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.\nFor instance, let’s borrow our industrial string-padder example from earlier:
\ntsinterface Padder {\n getPaddingString(): string;\n}\n\nclass SpaceRepeatingPadder implements Padder {\n constructor(private numSpaces: number) {}\n getPaddingString() {\n return Array(this.numSpaces + 1).join(\" \");\n }\n}\n\nclass StringPadder implements Padder {\n constructor(private value: string) {}\n getPaddingString() {\n return this.value;\n }\n}\n\nfunction getRandomPadder() {\n return Math.random() < 0.5\n ? new SpaceRepeatingPadder(4)\n : new StringPadder(\" \");\n}\n\n// Type is 'SpaceRepeatingPadder | StringPadder'\nlet padder: Padder = getRandomPadder();\n\nif (padder instanceof SpaceRepeatingPadder) {\n padder; // type narrowed to 'SpaceRepeatingPadder'\n}\nif (padder instanceof StringPadder) {\n padder; // type narrowed to 'StringPadder'\n}
The right side of the instanceof needs to be a constructor function, and TypeScript will narrow down to:
prototype property if its type is not anyin that order.
\nTypeScript has two special types, null and undefined, that have the values null and undefined respectively.\nWe mentioned these briefly in the Basic Types section.\nBy default, the type checker considers null and undefined assignable to anything.\nEffectively, null and undefined are valid values of every type.\nThat means it’s not possible to stop them from being assigned to any type, even when you would like to prevent it.\nThe 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.\nYou can include them explicitly using a union type:
\ntslet s = \"foo\";\ns = null; // error, 'null' is not assignable to 'string'\nlet sn: string | null = \"bar\";\nsn = null; // ok\n\nsn = undefined; // error, 'undefined' is not assignable to 'string | null'
Note that TypeScript treats null and undefined differently in order to match JavaScript semantics.\nstring | 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.
\nWith --strictNullChecks, an optional parameter automatically adds | undefined:
\ntsfunction f(x: number, y?: number) {\n return x + (y || 0);\n}\nf(1, 2);\nf(1);\nf(1, undefined);\nf(1, null); // error, 'null' is not assignable to 'number | undefined'
The same is true for optional properties:
\n\ntsclass C {\n a: number;\n b?: number;\n}\nlet c = new C();\nc.a = 12;\nc.a = undefined; // error, 'undefined' is not assignable to 'number'\nc.b = 13;\nc.b = undefined; // ok\nc.b = null; // error, 'null' is not assignable to 'number | undefined'
Since nullable types are implemented with a union, you need to use a type guard to get rid of the null.\nFortunately, this is the same code you’d write in JavaScript:
\ntsfunction f(sn: string | null): string {\n if (sn == null) {\n return \"default\";\n } else {\n return sn;\n }\n}
The null elimination is pretty obvious here, but you can use terser operators too:
\ntsfunction f(sn: string | null): string {\n return sn || \"default\";\n}
In cases where the compiler can’t eliminate null or undefined, you can use the type assertion operator to manually remove them.\nThe syntax is postfix !: identifier! removes null and undefined from the type of identifier:
\ntsfunction broken(name: string | null): string {\n function postfix(epithet: string) {\n return name.charAt(0) + \". the \" + epithet; // error, 'name' is possibly null\n }\n name = name || \"Bob\";\n return postfix(\"great\");\n}\n\nfunction fixed(name: string | null): string {\n function postfix(epithet: string) {\n return name!.charAt(0) + \". the \" + epithet; // ok\n }\n name = name || \"Bob\";\n return postfix(\"great\");\n}
The example uses a nested function here because the compiler can’t eliminate nulls inside a nested function (except immediately-invoked function expressions).\nThat’s because it can’t track all calls to the nested function, especially if you return it from the outer function.\nWithout knowing where the function is called, it can’t know what the type of name will be at the time the body executes.
Type aliases create a new name for a type.\nType 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.
\n\ntstype Name = string;\ntype NameResolver = () => string;\ntype NameOrResolver = Name | NameResolver;\nfunction getName(n: NameOrResolver): Name {\n if (typeof n === \"string\") {\n return n;\n } else {\n return n();\n }\n}
Aliasing doesn’t actually create a new type - it creates a new name to refer to that type.\nAliasing a primitive is not terribly useful, though it can be used as a form of documentation.
\nJust 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:
\n\ntstype Container<T> = { value: T };
We can also have a type alias refer to itself in a property:
\n\ntstype Tree<T> = {\n value: T;\n left: Tree<T>;\n right: Tree<T>;\n};
Together with intersection types, we can make some pretty mind-bending types:
\n\ntstype LinkedList<T> = T & { next: LinkedList<T> };\n\ninterface Person {\n name: string;\n}\n\nvar people: LinkedList<Person>;\nvar s = people.name;\nvar s = people.next.name;\nvar s = people.next.next.name;\nvar s = people.next.next.next.name;
However, it’s not possible for a type alias to appear anywhere else on the right side of the declaration:
\n\ntstype Yikes = Array<Yikes>; // error
As we mentioned, type aliases can act sort of like interfaces; however, there are some subtle differences.
\nOne difference is that interfaces create a new name that is used everywhere.\nType aliases don’t create a new name — for instance, error messages won’t use the alias name.\nIn the code below, hovering over interfaced in an editor will show that it returns an Interface, but will show that aliased returns object literal type.
\ntstype Alias = { num: number };\ninterface Interface {\n num: number;\n}\ndeclare function aliased(arg: Alias): Alias;\ndeclare function interfaced(arg: Interface): Interface;
In older versions of TypeScript, type aliases couldn’t be extended or implemented from (nor could they extend/implement other types). As of version 2.7, type aliases can be extended by creating a new intersection type e.g. type Cat = Animal & { purrs: true }.
Because an ideal property of software is being open to extension, you should always use an interface over a type alias if possible.
\nOn 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.
\nString literal types allow you to specify the exact value a string must have.\nIn practice string literal types combine nicely with union types, type guards, and type aliases.\nYou can use these features together to get enum-like behavior with strings.
\n\ntstype Easing = \"ease-in\" | \"ease-out\" | \"ease-in-out\";\nclass UIElement {\n animate(dx: number, dy: number, easing: Easing) {\n if (easing === \"ease-in\") {\n // ...\n } else if (easing === \"ease-out\") {\n } else if (easing === \"ease-in-out\") {\n } else {\n // error! should not pass null or undefined.\n }\n }\n}\n\nlet button = new UIElement();\nbutton.animate(0, 0, \"ease-in\");\nbutton.animate(0, 0, \"uneasy\"); // error: \"uneasy\" is not allowed here
You can pass any of the three allowed strings, but any other string will give the error
\nArgument of type '\"uneasy\"' is not assignable to parameter of type '\"ease-in\" | \"ease-out\" | \"ease-in-out\"'\nString literal types can be used in the same way to distinguish overloads:
\n\ntsfunction createElement(tagName: \"img\"): HTMLImageElement;\nfunction createElement(tagName: \"input\"): HTMLInputElement;\n// ... more overloads ...\nfunction createElement(tagName: string): Element {\n // ... code goes here ...\n}
TypeScript also has numeric literal types.
\n\ntsfunction rollDice(): 1 | 2 | 3 | 4 | 5 | 6 {\n // ...\n}
These are seldom written explicitly, but they can be useful when narrowing issues and can catch bugs:
\n\ntsfunction foo(x: number) {\n if (x !== 1 || x !== 2) {\n // ~~~~~~~\n // Operator '!==' cannot be applied to types '1' and '2'.\n }\n}
In other words, x must be 1 when it gets compared to 2, meaning that the above check is making an invalid comparison.
As mentioned in our section on enums, enum members have types when every member is literal-initialized.
\nMuch 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.
\nYou can combine singleton types, union types, type guards, and type aliases to build an advanced pattern called discriminated unions, also known as tagged unions or algebraic data types.\nDiscriminated unions are useful in functional programming.\nSome languages automatically discriminate unions for you; TypeScript instead builds on JavaScript patterns as they exist today.\nThere are three ingredients:
\n\ntsinterface Square {\n kind: \"square\";\n size: number;\n}\ninterface Rectangle {\n kind: \"rectangle\";\n width: number;\n height: number;\n}\ninterface Circle {\n kind: \"circle\";\n radius: number;\n}
First we declare the interfaces we will union.\nEach interface has a kind property with a different string literal type.\nThe kind property is called the discriminant or tag.\nThe other properties are specific to each interface.\nNotice that the interfaces are currently unrelated.\nLet’s put them into a union:
\ntstype Shape = Square | Rectangle | Circle;
Now let’s use the discriminated union:
\n\ntsfunction area(s: Shape) {\n switch (s.kind) {\n case \"square\":\n return s.size * s.size;\n case \"rectangle\":\n return s.height * s.width;\n case \"circle\":\n return Math.PI * s.radius ** 2;\n }\n}
We would like the compiler to tell us when we don’t cover all variants of the discriminated union.\nFor example, if we add Triangle to Shape, we need to update area as well:
\ntstype Shape = Square | Rectangle | Circle | Triangle;\nfunction area(s: Shape) {\n switch (s.kind) {\n case \"square\":\n return s.size * s.size;\n case \"rectangle\":\n return s.height * s.width;\n case \"circle\":\n return Math.PI * s.radius ** 2;\n }\n // should error here - we didn't handle case \"triangle\"\n}
There are two ways to do this.\nThe first is to turn on --strictNullChecks and specify a return type:
\ntsfunction area(s: Shape): number {\n // error: returns number | undefined\n switch (s.kind) {\n case \"square\":\n return s.size * s.size;\n case \"rectangle\":\n return s.height * s.width;\n case \"circle\":\n return Math.PI * s.radius ** 2;\n }\n}
Because the switch is no longer exhaustive, TypeScript is aware that the function could sometimes return undefined.\nIf you have an explicit return type number, then you will get an error that the return type is actually number | undefined.\nHowever, this method is quite subtle and, besides, --strictNullChecks does not always work with old code.
The second method uses the never type that the compiler uses to check for exhaustiveness:
\ntsfunction assertNever(x: never): never {\n throw new Error(\"Unexpected object: \" + x);\n}\nfunction area(s: Shape) {\n switch (s.kind) {\n case \"square\":\n return s.size * s.size;\n case \"rectangle\":\n return s.height * s.width;\n case \"circle\":\n return Math.PI * s.radius ** 2;\n default:\n return assertNever(s); // error here if there are missing cases\n }\n}
Here, assertNever checks that s is of type never — the type that’s left after all other cases have been removed.\nIf you forget a case, then s will have a real type and you will get a type error.\nThis method requires you to define an extra function, but it’s much more obvious when you forget it.
this typesA polymorphic this type represents a type that is the subtype of the containing class or interface.\nThis is called F-bounded polymorphism.\nThis makes hierarchical fluent interfaces much easier to express, for example.\nTake a simple calculator that returns this after each operation:
\ntsclass BasicCalculator {\n public constructor(protected value: number = 0) {}\n public currentValue(): number {\n return this.value;\n }\n public add(operand: number): this {\n this.value += operand;\n return this;\n }\n public multiply(operand: number): this {\n this.value *= operand;\n return this;\n }\n // ... other operations go here ...\n}\n\nlet v = new BasicCalculator(2)\n .multiply(5)\n .add(1)\n .currentValue();
Since the class uses this types, you can extend it and the new class can use the old methods with no changes.
\ntsclass ScientificCalculator extends BasicCalculator {\n public constructor(value = 0) {\n super(value);\n }\n public sin() {\n this.value = Math.sin(this.value);\n return this;\n }\n // ... other operations go here ...\n}\n\nlet v = new ScientificCalculator(2)\n .multiply(5)\n .sin()\n .add(1)\n .currentValue();
Without this types, ScientificCalculator would not have been able to extend BasicCalculator and keep the fluent interface.\nmultiply would have returned BasicCalculator, which doesn’t have the sin method.\nHowever, with this types, multiply returns this, which is ScientificCalculator here.
With index types, you can get the compiler to check code that uses dynamic property names.\nFor example, a common JavaScript pattern is to pick a subset of properties from an object:
\n\njsfunction pluck(o, propertyNames) {\n return propertyNames.map(n => o[n]);\n}
Here’s how you would write and use this function in TypeScript, using the index type query and indexed access operators:
\n\ntsfunction pluck<T, K extends keyof T>(o: T, propertyNames: K[]): T[K][] {\n return propertyNames.map(n => o[n]);\n}\n\ninterface Car {\n manufacturer: string;\n model: string;\n year: number;\n}\nlet taxi: Car = {\n manufacturer: \"Toyota\",\n model: \"Camry\",\n year: 2014\n};\n\n// Manufacturer and model are both of type string,\n// so we can pluck them both into a typed string array\nlet makeAndModel: string[] = pluck(taxi, [\"manufacturer\", \"model\"]);\n\n// If we try to pluck model and year, we get an\n// array of a union type: (string | number)[]\nlet modelYear = pluck(taxi, [\"model\", \"year\"]);
The compiler checks that manufacturer and model are actually properties on Car.\nThe example introduces a couple of new type operators.\nFirst is keyof T, the index type query operator.\nFor any type T, keyof T is the union of known, public property names of T.\nFor example:
\ntslet carProps: keyof Car; // the union of ('manufacturer' | 'model' | 'year')
keyof Car is completely interchangeable with 'manufacturer' | 'model' | 'year'.\nThe 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'.\nAnd you can use keyof in generic contexts like pluck, where you can’t possibly know the property names ahead of time.\nThat means the compiler will check that you pass the right set of property names to pluck:
\nts// error, 'unknown' is not in 'manufacturer' | 'model' | 'year'\npluck(taxi, ['year', 'unknown']); /
The second operator is T[K], the indexed access operator.\nHere, the type syntax reflects the expression syntax.\nThat means that person['name'] has the type Person['name'] — which in our example is just string.\nHowever, just like index type queries, you can use T[K] in a generic context, which is where its real power comes to life.\nYou just have to make sure that the type variable K extends keyof T.\nHere’s another example with a function named getProperty.
\ntsfunction getProperty<T, K extends keyof T>(o: T, propertyName: K): T[K] {\n return o[propertyName]; // o[propertyName] is of type T[K]\n}
In getProperty, o: T and propertyName: K, so that means o[propertyName]: T[K].\nOnce 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.
\ntslet name: string = getProperty(taxi, \"manufacturer\");\nlet year: number = getProperty(taxi, \"year\");\n\n// error, 'unknown' is not in 'manufacturer' | 'model' | 'year'\nlet unknown = getProperty(taxi, \"unknown\");
keyof and T[K] interact with index signatures. An index signature parameter type must be ‘string’ or ‘number’.\nIf you have a type with a string index signature, keyof T will be string | number\n(and not just string, since in JavaScript you can access an object property either\nby using strings (object['42']) or numbers (object[42])).\nAnd T[string] is just the type of the index signature:
\ntsinterface Dictionary<T> {\n [key: string]: T;\n}\nlet keys: keyof Dictionary<number>; // string | number\nlet value: Dictionary<number>[\"foo\"]; // number
If you have a type with a number index signature, keyof T will just be number.
\ntsinterface Dictionary<T> {\n [key: number]: T;\n}\nlet keys: keyof Dictionary<number>; // number\nlet value: Dictionary<number>[\"foo\"]; // Error, Property 'foo' does not exist on type 'Dictionary<number>'.\nlet value: Dictionary<number>[42]; // number
A common task is to take an existing type and make each of its properties optional:
\n\ntsinterface PersonPartial {\n name?: string;\n age?: number;\n}
Or we might want a readonly version:
\n\ntsinterface PersonReadonly {\n readonly name: string;\n readonly age: number;\n}
This happens often enough in JavaScript that TypeScript provides a way to create new types based on old types — mapped types.\nIn a mapped type, the new type transforms each property in the old type in the same way.\nFor example, you can make all properties of a type readonly or optional.\nHere are a couple of examples:
\ntstype Readonly<T> = {\n readonly [P in keyof T]: T[P];\n};\ntype Partial<T> = {\n [P in keyof T]?: T[P];\n};
And to use it:
\n\ntstype PersonPartial = Partial<Person>;\ntype ReadonlyPerson = Readonly<Person>;
Note that this syntax describes a type rather than a member.\nIf you want to add members, you can use an intersection type:
\n\nts// Use this:\ntype PartialWithNewMember<T> = {\n [P in keyof T]?: T[P];\n} & { newMember: boolean }\n\n// **Do not** use the following!\n// This is an error!\ntype PartialWithNewMember<T> = {\n [P in keyof T]?: T[P];\n newMember: boolean;\n}
Let’s take a look at the simplest mapped type and its parts:
\n\ntstype Keys = \"option1\" | \"option2\";\ntype Flags = { [K in Keys]: boolean };
The syntax resembles the syntax for index signatures with a for .. in inside.\nThere are three parts:
K, which gets bound to each property in turn.Keys, which contains the names of properties to iterate over.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:
\ntstype Flags = {\n option1: boolean;\n option2: boolean;\n};
Real applications, however, look like Readonly or Partial above.\nThey’re based on some existing type, and they transform the properties in some way.\nThat’s where keyof and indexed access types come in:
\ntstype NullablePerson = { [P in keyof Person]: Person[P] | null };\ntype PartialPerson = { [P in keyof Person]?: Person[P] };
But it’s more useful to have a general version.
\n\ntstype Nullable<T> = { [P in keyof T]: T[P] | null };\ntype 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].\nThis is a good template for any general use of mapped types.\nThat’s because this kind of transformation is homomorphic, which means that the mapping applies only to properties of T and no others.\nThe compiler knows that it can copy all the existing property modifiers before adding any new ones.\nFor 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:
\ntstype Proxy<T> = {\n get(): T;\n set(value: T): void;\n};\ntype Proxify<T> = {\n [P in keyof T]: Proxy<T[P]>;\n};\nfunction proxify<T>(o: T): Proxify<T> {\n // ... wrap proxies ...\n}\nlet proxyProps = 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:
\ntstype Pick<T, K extends keyof T> = {\n [P in K]: T[P];\n};\ntype Record<K extends keyof any, T> = {\n [P in K]: T;\n};
Readonly, Partial and Pick are homomorphic whereas Record is not.\nOne clue that Record is not homomorphic is that it doesn’t take an input type to copy properties from:
\ntstype ThreeStringProps = Record<\"prop1\" | \"prop2\" | \"prop3\", string>;
Non-homomorphic types are essentially creating new properties, so they can’t copy property modifiers from anywhere.
\nNow that you know how to wrap the properties of a type, the next thing you’ll want to do is unwrap them.\nFortunately, that’s pretty easy:
\n\ntsfunction unproxify<T>(t: Proxify<T>): T {\n let result = {} as T;\n for (const k in t) {\n result[k] = t[k].get();\n }\n return result;\n}\n\nlet originalProps = unproxify(proxyProps);
Note that this unwrapping inference only works on homomorphic mapped types.\nIf the mapped type is not homomorphic you’ll have to give an explicit type parameter to your unwrapping function.
\nTypeScript 2.8 introduces conditional types which add the ability to express non-uniform type mappings.\nA conditional type selects one of two possible types based on a condition expressed as a type relationship test:
\n\ntsT 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.\nWhen 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:
\n\ntsdeclare function f<T extends boolean>(x: T): T extends true ? string : number;\n\n// Type is 'string | number'\nlet x = f(Math.random() < 0.5);
Another example would be the TypeName type alias, which uses nested conditional types:
\ntstype TypeName<T> = T extends string\n ? \"string\"\n : T extends number\n ? \"number\"\n : T extends boolean\n ? \"boolean\"\n : T extends undefined\n ? \"undefined\"\n : T extends Function\n ? \"function\"\n : \"object\";\n\ntype T0 = TypeName<string>; // \"string\"\ntype T1 = TypeName<\"a\">; // \"string\"\ntype T2 = TypeName<true>; // \"boolean\"\ntype T3 = TypeName<() => void>; // \"function\"\ntype T4 = TypeName<string[]>; // \"object\"
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:
\n\ntsinterface Foo {\n propA: boolean;\n propB: boolean;\n}\n\ndeclare function f<T>(x: T): T extends Foo ? string : number;\n\nfunction foo<U>(x: U) {\n // Has type 'U extends Foo ? string : number'\n let a = f(x);\n\n // This assignment is allowed though!\n let b: string | number = a;\n}
In the above, the variable a has a conditional type that hasn’t yet chosen a branch.\nWhen 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.\nSo 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.
Conditional types in which the checked type is a naked type parameter are called distributive conditional types.\nDistributive conditional types are automatically distributed over union types during instantiation.\nFor 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).
\ntstype T10 = TypeName<string | (() => void)>; // \"string\" | \"function\"\ntype T12 = TypeName<string | string[] | undefined>; // \"string\" | \"object\" | \"undefined\"\ntype T11 = TypeName<string[] | number[]>; // \"object\"
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).\nFurthermore, references to T within X have an additional type parameter constraint U (i.e. T is considered assignable to U within X).
\ntstype BoxedValue<T> = { value: T };\ntype BoxedArray<T> = { array: T[] };\ntype Boxed<T> = T extends any[] ? BoxedArray<T[number]> : BoxedValue<T>;\n\ntype T20 = Boxed<string>; // BoxedValue<string>;\ntype T21 = Boxed<number[]>; // BoxedArray<number>;\ntype T22 = Boxed<string | number[]>; // BoxedValue<string> | BoxedArray<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:
\n\ntstype Diff<T, U> = T extends U ? never : T; // Remove types from T that are assignable to U\ntype Filter<T, U> = T extends U ? T : never; // Remove types from T that are not assignable to U\n\ntype T30 = Diff<\"a\" | \"b\" | \"c\" | \"d\", \"a\" | \"c\" | \"f\">; // \"b\" | \"d\"\ntype T31 = Filter<\"a\" | \"b\" | \"c\" | \"d\", \"a\" | \"c\" | \"f\">; // \"a\" | \"c\"\ntype T32 = Diff<string | number | (() => void), Function>; // string | number\ntype T33 = Filter<string | number | (() => void), Function>; // () => void\n\ntype NonNullable<T> = Diff<T, null | undefined>; // Remove null and undefined from T\n\ntype T34 = NonNullable<string | number | undefined>; // string | number\ntype T35 = NonNullable<string | string[] | null | undefined>; // string | string[]\n\nfunction f1<T>(x: T, y: NonNullable<T>) {\n x = y; // Ok\n y = x; // Error\n}\n\nfunction f2<T extends string | undefined>(x: T, y: NonNullable<T>) {\n x = y; // Ok\n y = x; // Error\n let s1: string = x; // Error\n let s2: string = y; // Ok\n}
Conditional types are particularly useful when combined with mapped types:
\n\ntstype FunctionPropertyNames<T> = {\n [K in keyof T]: T[K] extends Function ? K : never;\n}[keyof T];\ntype FunctionProperties<T> = Pick<T, FunctionPropertyNames<T>>;\n\ntype NonFunctionPropertyNames<T> = {\n [K in keyof T]: T[K] extends Function ? never : K;\n}[keyof T];\ntype NonFunctionProperties<T> = Pick<T, NonFunctionPropertyNames<T>>;\n\ninterface Part {\n id: number;\n name: string;\n subparts: Part[];\n updatePart(newName: string): void;\n}\n\ntype T40 = FunctionPropertyNames<Part>; // \"updatePart\"\ntype T41 = NonFunctionPropertyNames<Part>; // \"id\" | \"name\" | \"subparts\"\ntype T42 = FunctionProperties<Part>; // { updatePart(newName: string): void }\ntype T43 = NonFunctionProperties<Part>; // { id: number, name: string, subparts: Part[] }
Similar to union and intersection types, conditional types are not permitted to reference themselves recursively.\nFor example the following is an error.
\n\ntstype ElementType<T> = T extends any[] ? ElementType<T[number]> : T; // Error
Within the extends clause of a conditional type, it is now possible to have infer declarations that introduce a type variable to be inferred.\nSuch inferred type variables may be referenced in the true branch of the conditional type.\nIt is possible to have multiple infer locations for the same type variable.
For example, the following extracts the return type of a function type:
\n\ntstype ReturnType<T> = T extends (...args: any[]) => infer R ? R : any;
Conditional types can be nested to form a sequence of pattern matches that are evaluated in order:
\n\ntstype Unpacked<T> = T extends (infer U)[]\n ? U\n : T extends (...args: any[]) => infer U\n ? U\n : T extends Promise<infer U>\n ? U\n : T;\n\ntype T0 = Unpacked<string>; // string\ntype T1 = Unpacked<string[]>; // string\ntype T2 = Unpacked<() => string>; // string\ntype T3 = Unpacked<Promise<string>>; // string\ntype T4 = Unpacked<Promise<string>[]>; // Promise<string>\ntype T5 = Unpacked<Unpacked<Promise<string>[]>>; // string
The following example demonstrates how multiple candidates for the same type variable in co-variant positions causes a union type to be inferred:
\n\ntstype Foo<T> = T extends { a: infer U; b: infer U } ? U : never;\ntype T10 = Foo<{ a: string; b: string }>; // string\ntype T11 = Foo<{ a: string; b: number }>; // string | number
Likewise, multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred:
\n\ntstype Bar<T> = T extends { a: (x: infer U) => void; b: (x: infer U) => void }\n ? U\n : never;\ntype T20 = Bar<{ a: (x: string) => void; b: (x: string) => void }>; // string\ntype T21 = Bar<{ a: (x: string) => void; b: (x: number) => void }>; // string & number
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).\nIt is not possible to perform overload resolution based on a list of argument types.
\n\ntsdeclare function foo(x: string): number;\ndeclare function foo(x: number): string;\ndeclare function foo(x: string | number): string | number;\ntype T30 = ReturnType<typeof foo>; // string | number
It is not possible to use infer declarations in constraint clauses for regular type parameters:
\ntstype ReturnType<T extends (...args: any[]) => infer R> = R; // Error, not supported
However, much the same effect can be obtained by erasing the type variables in the constraint and instead specifying a conditional type:
\n\ntstype AnyFunction = (...args: any[]) => any;\ntype ReturnType<T extends AnyFunction> = T extends (...args: any[]) => infer R\n ? R\n : any;
TypeScript 2.8 adds several predefined conditional types to lib.d.ts:
Exclude<T, U> — Exclude from T those types that are assignable to U.Extract<T, U> — Extract from T those types that are assignable to U.NonNullable<T> — Exclude null and undefined from T.ReturnType<T> — Obtain the return type of a function type.InstanceType<T> — Obtain the instance type of a constructor function type.\ntstype T00 = Exclude<\"a\" | \"b\" | \"c\" | \"d\", \"a\" | \"c\" | \"f\">; // \"b\" | \"d\"\ntype T01 = Extract<\"a\" | \"b\" | \"c\" | \"d\", \"a\" | \"c\" | \"f\">; // \"a\" | \"c\"\n\ntype T02 = Exclude<string | number | (() => void), Function>; // string | number\ntype T03 = Extract<string | number | (() => void), Function>; // () => void\n\ntype T04 = NonNullable<string | number | undefined>; // string | number\ntype T05 = NonNullable<(() => string) | string[] | null | undefined>; // (() => string) | string[]\n\nfunction f1(s: string) {\n return { a: 1, b: s };\n}\n\nclass C {\n x = 0;\n y = 0;\n}\n\ntype T10 = ReturnType<() => string>; // string\ntype T11 = ReturnType<(s: string) => void>; // void\ntype T12 = ReturnType<<T>() => T>; // {}\ntype T13 = ReturnType<<T extends U, U extends number[]>() => T>; // number[]\ntype T14 = ReturnType<typeof f1>; // { a: number, b: string }\ntype T15 = ReturnType<any>; // any\ntype T16 = ReturnType<never>; // never\ntype T17 = ReturnType<string>; // Error\ntype T18 = ReturnType<Function>; // Error\n\ntype T20 = InstanceType<typeof C>; // C\ntype T21 = InstanceType<any>; // any\ntype T22 = InstanceType<never>; // never\ntype T23 = InstanceType<string>; // Error\ntype T24 = InstanceType<Function>; // Error
\n","headings":[{"value":"Type Guards and Differentiating Types","depth":1},{"value":"User-Defined Type Guards","depth":2},{"value":"Using type predicates","depth":3},{"value":"Using the in operator","depth":3},{"value":"typeof type guards","depth":2},{"value":"instanceof type guards","depth":2},{"value":"Nullable types","depth":1},{"value":"Optional parameters and properties","depth":2},{"value":"Type guards and type assertions","depth":2},{"value":"Type Aliases","depth":1},{"value":"Interfaces vs. Type Aliases","depth":2},{"value":"String Literal Types","depth":1},{"value":"Numeric Literal Types","depth":1},{"value":"Enum Member Types","depth":1},{"value":"Discriminated Unions","depth":1},{"value":"Exhaustiveness checking","depth":2},{"value":"Polymorphic this types","depth":1},{"value":"Index types","depth":1},{"value":"Index types and index signatures","depth":2},{"value":"Mapped types","depth":1},{"value":"Inference from mapped types","depth":2},{"value":"Conditional Types","depth":1},{"value":"Distributive conditional types","depth":2},{"value":"Example","depth":3},{"value":"Example","depth":3},{"value":"Example","depth":3},{"value":"Type inference in conditional types","depth":2},{"value":"Predefined conditional types","depth":2},{"value":"Example","depth":3}],"frontmatter":{"permalink":"/docs/handbook/advanced-types.html","title":"Advanced Types"}}},"pageContext":{"slug":"/docs/handbook/advanced-types.html","next":null,"isOldHandbook":true}}}Note: The
\nExcludetype is a proper implementation of theDifftype suggested here. We’ve used the nameExcludeto avoid breaking existing code that defines aDiff, plus we feel that name better conveys the semantics of the type.