TypeScript provides several utility types to facilitate common type transformations. These utilities are available globally.
Awaited<Type>
Released: 4.5
This type is meant to model operations like await
in async
functions, or the
.then()
method on Promise
s - specifically, the way that they recursively
unwrap Promise
s.
Example
tsTry
typeA =Awaited <Promise <string>>;typeB =Awaited <Promise <Promise <number>>>;typeC =Awaited <boolean |Promise <number>>;
Partial<Type>
Released:
2.1
Constructs a type with all properties of Type
set to optional. This utility will return a type that represents all subsets of a given type.
Example
tsTry
interfaceTodo {title : string;description : string;}functionupdateTodo (todo :Todo ,fieldsToUpdate :Partial <Todo >) {return { ...todo , ...fieldsToUpdate };}consttodo1 = {title : "organize desk",description : "clear clutter",};consttodo2 =updateTodo (todo1 , {description : "throw out trash",});
Required<Type>
Released:
2.8
Constructs a type consisting of all properties of Type
set to required. The opposite of Partial
.
Example
tsTry
interfaceProps {a ?: number;b ?: string;}constobj :Props = {a : 5 };constProperty 'b' is missing in type '{ a: number; }' but required in type 'Required<Props>'.2741Property 'b' is missing in type '{ a: number; }' but required in type 'Required<Props>'.: obj2 Required <Props > = {a : 5 };
Readonly<Type>
Released:
2.1
Constructs a type with all properties of Type
set to readonly
, meaning the properties of the constructed type cannot be reassigned.
Example
tsTry
interfaceTodo {title : string;}consttodo :Readonly <Todo > = {title : "Delete inactive users",};Cannot assign to 'title' because it is a read-only property.2540Cannot assign to 'title' because it is a read-only property.todo .= "Hello"; title
This utility is useful for representing assignment expressions that will fail at runtime (i.e. when attempting to reassign properties of a frozen object).
Object.freeze
ts
function freeze<Type>(obj: Type): Readonly<Type>;
Record<Keys, Type>
Released:
2.1
Constructs an object type whose property keys are Keys
and whose property values are Type
. This utility can be used to map the properties of a type to another type.
Example
tsTry
interfaceCatInfo {age : number;breed : string;}typeCatName = "miffy" | "boris" | "mordred";constcats :Record <CatName ,CatInfo > = {miffy : {age : 10,breed : "Persian" },boris : {age : 5,breed : "Maine Coon" },mordred : {age : 16,breed : "British Shorthair" },};cats .boris ;
Adding Element to Record
Suppose we have a Record
set up like this: let myRecord = Record<string, Set<string>>
. We would end up failing if we
attempt to add an element to a set inside the record in the following way
typescript
let key = "key";let stringToAdd = "stringToAdd";myRecord[key].add(stringToAdd);
Instead, we should use the square brackets []
and an assignment to add elements to the record.
typescript
let mySet: Set<string> = new Set();mySet.add("stringToAdd");let myRecord: Record<string, Set<string>> = {};myRecord["key"] = mySet; // <--- Like this
Pick<Type, Keys>
Released:
2.1
Constructs a type by picking the set of properties Keys
(string literal or union of string literals) from Type
.
Example
tsTry
interfaceTodo {title : string;description : string;completed : boolean;}typeTodoPreview =Pick <Todo , "title" | "completed">;consttodo :TodoPreview = {title : "Clean room",completed : false,};todo ;
Omit<Type, Keys>
Released:
3.5
Constructs a type by picking all properties from Type
and then removing Keys
(string literal or union of string literals). The opposite of Pick
.
Example
tsTry
interfaceTodo {title : string;description : string;completed : boolean;createdAt : number;}typeTodoPreview =Omit <Todo , "description">;consttodo :TodoPreview = {title : "Clean room",completed : false,createdAt : 1615544252770,};todo ;typeTodoInfo =Omit <Todo , "completed" | "createdAt">;consttodoInfo :TodoInfo = {title : "Pick up kids",description : "Kindergarten closes at 5pm",};todoInfo ;
Exclude<UnionType, ExcludedMembers>
Released:
2.8
Constructs a type by excluding from UnionType
all union members that are assignable to ExcludedMembers
.
Example
tsTry
typeT0 =Exclude <"a" | "b" | "c", "a">;typeT1 =Exclude <"a" | "b" | "c", "a" | "b">;typeT2 =Exclude <string | number | (() => void),Function >;typeShape =| {kind : "circle";radius : number }| {kind : "square";x : number }| {kind : "triangle";x : number;y : number };typeT3 =Exclude <Shape , {kind : "circle" }>
Extract<Type, Union>
Released:
2.8
Constructs a type by extracting from Type
all union members that are assignable to Union
.
Example
tsTry
typeT0 =Extract <"a" | "b" | "c", "a" | "f">;typeT1 =Extract <string | number | (() => void),Function >;typeShape =| {kind : "circle";radius : number }| {kind : "square";x : number }| {kind : "triangle";x : number;y : number };typeT2 =Extract <Shape , {kind : "circle" }>
NonNullable<Type>
Released:
2.8
Constructs a type by excluding null
and undefined
from Type
.
Example
tsTry
typeT0 =NonNullable <string | number | undefined>;typeT1 =NonNullable <string[] | null | undefined>;
Parameters<Type>
Released:
3.1
Constructs a tuple type from the types used in the parameters of a function type Type
.
For overloaded functions, this will be the parameters of the last signature; see Inferring Within Conditional Types.
Example
tsTry
declare functionf1 (arg : {a : number;b : string }): void;typeT0 =Parameters <() => string>;typeT1 =Parameters <(s : string) => void>;typeT2 =Parameters <<T >(arg :T ) =>T >;typeT3 =Parameters <typeoff1 >;typeT4 =Parameters <any>;typeT5 =Parameters <never>;typeType 'string' does not satisfy the constraint '(...args: any) => any'.2344Type 'string' does not satisfy the constraint '(...args: any) => any'.T6 =Parameters <string >;typeType 'Function' does not satisfy the constraint '(...args: any) => any'. Type 'Function' provides no match for the signature '(...args: any): any'.2344Type 'Function' does not satisfy the constraint '(...args: any) => any'. Type 'Function' provides no match for the signature '(...args: any): any'.T7 =Parameters <>; Function
ConstructorParameters<Type>
Released:
3.1
Constructs a tuple or array type from the types of a constructor function type. It produces a tuple type with all the parameter types (or the type never
if Type
is not a function).
Example
tsTry
typeT0 =ConstructorParameters <ErrorConstructor >;typeT1 =ConstructorParameters <FunctionConstructor >;typeT2 =ConstructorParameters <RegExpConstructor >;classC {constructor(a : number,b : string) {}}typeT3 =ConstructorParameters <typeofC >;typeT4 =ConstructorParameters <any>;typeType 'Function' does not satisfy the constraint 'abstract new (...args: any) => any'. Type 'Function' provides no match for the signature 'new (...args: any): any'.2344Type 'Function' does not satisfy the constraint 'abstract new (...args: any) => any'. Type 'Function' provides no match for the signature 'new (...args: any): any'.T5 =ConstructorParameters <>; Function
ReturnType<Type>
Released:
2.8
Constructs a type consisting of the return type of function Type
.
For overloaded functions, this will be the return type of the last signature; see Inferring Within Conditional Types.
Example
tsTry
declare functionf1 (): {a : number;b : string };typeT0 =ReturnType <() => string>;typeT1 =ReturnType <(s : string) => void>;typeT2 =ReturnType <<T >() =>T >;typeT3 =ReturnType <<T extendsU ,U extends number[]>() =>T >;typeT4 =ReturnType <typeoff1 >;typeT5 =ReturnType <any>;typeT6 =ReturnType <never>;typeType 'string' does not satisfy the constraint '(...args: any) => any'.2344Type 'string' does not satisfy the constraint '(...args: any) => any'.T7 =ReturnType <string >;typeType 'Function' does not satisfy the constraint '(...args: any) => any'. Type 'Function' provides no match for the signature '(...args: any): any'.2344Type 'Function' does not satisfy the constraint '(...args: any) => any'. Type 'Function' provides no match for the signature '(...args: any): any'.T8 =ReturnType <>; Function
InstanceType<Type>
Released:
2.8
Constructs a type consisting of the instance type of a constructor function in Type
.
Example
tsTry
classC {x = 0;y = 0;}typeT0 =InstanceType <typeofC >;typeT1 =InstanceType <any>;typeT2 =InstanceType <never>;typeType 'string' does not satisfy the constraint 'abstract new (...args: any) => any'.2344Type 'string' does not satisfy the constraint 'abstract new (...args: any) => any'.T3 =InstanceType <string >;typeType 'Function' does not satisfy the constraint 'abstract new (...args: any) => any'. Type 'Function' provides no match for the signature 'new (...args: any): any'.2344Type 'Function' does not satisfy the constraint 'abstract new (...args: any) => any'. Type 'Function' provides no match for the signature 'new (...args: any): any'.T4 =InstanceType <>; Function
ThisParameterType<Type>
Released:
3.3
Extracts the type of the this parameter for a function type, or unknown if the function type has no this
parameter.
Example
tsTry
functiontoHex (this :Number ) {return this.toString (16);}functionnumberToString (n :ThisParameterType <typeoftoHex >) {returntoHex .apply (n );}
OmitThisParameter<Type>
Released:
3.3
Removes the this
parameter from Type
. If Type
has no explicitly declared this
parameter, the result is simply Type
. Otherwise, a new function type with no this
parameter is created from Type
. Generics are erased and only the last overload signature is propagated into the new function type.
Example
tsTry
functiontoHex (this :Number ) {return this.toString (16);}constfiveToHex :OmitThisParameter <typeoftoHex > =toHex .bind (5);console .log (fiveToHex ());
ThisType<Type>
Released:
2.3
This utility does not return a transformed type. Instead, it serves as a marker for a contextual this
type. Note that the noImplicitThis
flag must be enabled to use this utility.
Example
tsTry
typeObjectDescriptor <D ,M > = {data ?:D ;methods ?:M &ThisType <D &M >; // Type of 'this' in methods is D & M};functionmakeObject <D ,M >(desc :ObjectDescriptor <D ,M >):D &M {letdata : object =desc .data || {};letmethods : object =desc .methods || {};return { ...data , ...methods } asD &M ;}letobj =makeObject ({data : {x : 0,y : 0 },methods : {moveBy (dx : number,dy : number) {this.x +=dx ; // Strongly typed thisthis.y +=dy ; // Strongly typed this},},});obj .x = 10;obj .y = 20;obj .moveBy (5, 5);
In the example above, the methods
object in the argument to makeObject
has a contextual type that includes ThisType<D & M>
and therefore the type of this in methods within the methods
object is { x: number, y: number } & { moveBy(dx: number, dy: number): void }
. Notice how the type of the methods
property simultaneously is an inference target and a source for the this
type in methods.
The ThisType<T>
marker interface is simply an empty interface declared in lib.d.ts
. Beyond being recognized in the contextual type of an object literal, the interface acts like any empty interface.
Intrinsic String Manipulation Types
Uppercase<StringType>
Lowercase<StringType>
Capitalize<StringType>
Uncapitalize<StringType>
To help with string manipulation around template string literals, TypeScript includes a set of types which can be used in string manipulation within the type system. You can find those in the Template Literal Types documentation.