TypeScript 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.\nWhether to resolve or defer is determined as follows:
T' and U' that are instantiations of T and U where all occurrences of type parameters are replaced with any, if T' is not assignable to U', the conditional type is resolved to Y. Intuitively, if the most permissive instantiation of T is not assignable to the most permissive instantiation of U, we know that no instantiation will be and we can just resolve to Y.infer (more later) declaration within U collect a set of candidate types by inferring from T to U (using the same inference algorithm as type inference for generic functions). For a given infer type variable V, if any candidates were inferred from co-variant positions, the type inferred for V is a union of those candidates. Otherwise, if any candidates were inferred from contra-variant positions, the type inferred for V is an intersection of those candidates. Otherwise, the type inferred for V is never.T'' that is an instantiation of T where all infer type variables are replaced with the types inferred in the previous step, if T'' is definitely assignable to U, the conditional type is resolved to X. The definitely assignable relation is the same as the regular assignable relation, except that type variable constraints are not considered. Intuitively, when a type is definitely assignable to another type, we know that it will be assignable for all instantiations of those types.\ntstype TypeName<T> =\n T extends string ? \"string\" :\n T extends number ? \"number\" :\n T extends boolean ? \"boolean\" :\n T extends undefined ? \"undefined\" :\n T extends Function ? \"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\"
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> = { [K in keyof T]: T[K] extends Function ? K : never }[keyof T];\ntype FunctionProperties<T> = Pick<T, FunctionPropertyNames<T>>;\n\ntype NonFunctionPropertyNames<T> = { [K in keyof T]: T[K] extends Function ? never : K }[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> =\n T extends (infer U)[] ? U :\n T extends (...args: any[]) => infer U ? U :\n T extends Promise<infer U> ? 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 } ? U : 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 ? R : 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>; // any\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>; // any\ntype T23 = InstanceType<string>; // Error\ntype T24 = InstanceType<Function>; // Error
\n\nNote: 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. We did not include theOmit<T, K>type because it is trivially written asPick<T, Exclude<keyof T, K>>.
Mapped types support adding a readonly or ? modifier to a mapped property, but they did not provide support the ability to remove modifiers.\nThis matters in homomorphic mapped types which by default preserve the modifiers of the underlying type.
TypeScript 2.8 adds the ability for a mapped type to either add or remove a particular modifier.\nSpecifically, a readonly or ? property modifier in a mapped type can now be prefixed with either + or - to indicate that the modifier should be added or removed.
\ntstype MutableRequired<T> = { -readonly [P in keyof T]-?: T[P] }; // Remove readonly and ?\ntype ReadonlyPartial<T> = { +readonly [P in keyof T]+?: T[P] }; // Add readonly and ?
A modifier with no + or - prefix is the same as a modifier with a + prefix. So, the ReadonlyPartial<T> type above corresponds to
\ntstype ReadonlyPartial<T> = { readonly [P in keyof T]?: T[P] }; // Add readonly and ?
Using this ability, lib.d.ts now has a new Required<T> type.\nThis type strips ? modifiers from all properties of T, thus making all properties required.
\ntstype Required<T> = { [P in keyof T]-?: T[P] };
Note that in --strictNullChecks mode, when a homomorphic mapped type removes a ? modifier from a property in the underlying type it also removes undefined from the type of that property:
\ntstype Foo = { a?: string }; // Same as { a?: string | undefined }\ntype Bar = Required<Foo>; // Same as { a: string }
keyof with intersection typesWith TypeScript 2.8 keyof applied to an intersection type is transformed to a union of keyof applied to each intersection constituent.\nIn other words, types of the form keyof (A & B) are transformed to be keyof A | keyof B.\nThis change should address inconsistencies with inference from keyof expressions.
\ntstype A = { a: string };\ntype B = { b: string };\n\ntype T1 = keyof (A & B); // \"a\" | \"b\"\ntype T2<T> = keyof (T & B); // keyof T | \"b\"\ntype T3<U> = keyof (A & U); // \"a\" | keyof U\ntype T4<T, U> = keyof (T & U); // keyof T | keyof U\ntype T5 = T2<A>; // \"a\" | \"b\"\ntype T6 = T3<B>; // \"a\" | \"b\"\ntype T7 = T4<A, B>; // \"a\" | \"b\"
.js filesTypeScript 2.8 adds support for understanding more namespace patterns in .js files.\nEmpty object literals declarations on top level, just like functions and classes, are now recognized as as namespace declarations in JavaScript.
\njsvar ns = {}; // recognized as a declaration for a namespace `ns`\nns.constant = 1; // recognized as a declaration for var `constant`
Assignments at the top-level should behave the same way; in other words, a var or const declaration is not required.
\njsapp = {}; // does NOT need to be `var app = {}`\napp.C = class {\n};\napp.f = function() {\n};\napp.prop = 1;
An IIFE returning a function, class or empty object literal, is also recognized as a namespace:
\n\njsvar C = (function () {\n function C(n) {\n this.p = n;\n }\n return C;\n})();\nC.staticProperty = 1;
“Defaulted declarations” allow initializers that reference the declared name in the left side of a logical or:
\n\njsmy = window.my || {};\nmy.app = my.app || {};
You can assign an object literal directly to the prototype property. Individual prototype assignments still work too:
\n\ntsvar C = function (p) {\n this.p = p;\n};\nC.prototype = {\n m() {\n console.log(this.p);\n }\n};\nC.prototype.q = function(r) {\n return this.p === r;\n};
Nesting works to any level now, and merges correctly across files. Previously neither was the case.
\n\njsvar app = window.app || {};\napp.C = class { };
TypeScript 2.8 adds support for a per-file configurable JSX factory name using @jsx dom pragma.\nJSX factory can be configured for a compilation using --jsxFactory (default is React.createElement). With TypeScript 2.8 you can override this on a per-file-basis by adding a comment to the beginning of the file.
\nts/** @jsx dom */\nimport { dom } from \"./renderer\"\n<h></h>
Generates:
\n\njsvar renderer_1 = require(\"./renderer\");\nrenderer_1.dom(\"h\", null);
JSX type checking is driven by definitions in a JSX namespace, for instance JSX.Element for the type of a JSX element, and JSX.IntrinsicElements for built-in elements.\nBefore TypeScript 2.8 the JSX namespace was expected to be in the global namespace, and thus only allowing one to be defined in a project.\nStarting with TypeScript 2.8 the JSX namespace will be looked under the jsxNamespace (e.g. React) allowing for multiple jsx factories in one compilation.\nFor backward compatibility the global JSX namespace is used as a fallback if none was defined on the factory function.\nCombined with the per-file @jsx pragma, each file can have a different JSX factory.
--emitDeclarationOnly--emitDeclarationOnly allows for only generating declaration files; .js/.jsx output generation will be skipped with this flag. The flag is useful when the .js output generation is handled by a different transpiler like Babel.