Awaited
Version: 4.5This type is meant to model operations like await in async functions, or the .then() method on Promises - specifically, the way that they recursively unwrap Promises.
1type A = Awaited<Promise<string>>;
2
3type B = Awaited<Promise<Promise<number>>>;
4
5type C = Awaited<boolean | Promise<number>>;
6Partial
Version: 2.1Constructs a type with all properties of Type set to optional. This utility will return a type that represents all subsets of a given type.
1interface Todo {
2 title: string;
3 description: string;
4}
5
6function updateTodo(todo: Todo, fieldsToUpdate: Partial<Todo>) {
7 return { ...todo, ...fieldsToUpdate };
8}
9
10const todo1 = {
11 title: 'organize desk',
12 description: 'clear clutter'
13};
14
15const todo2 = updateTodo(todo1, {
16 description: 'throw out trash'
17});
18Required
Version: 2.8Constructs a type consisting of all properties of Type set to required. The opposite of Partial.
1interface Props {
2 a?: number;
3 b?: string;
4}
5
6const obj: Props = { a: 5 };
7
8const obj2: Required<Props> = { a: 5 };
9Readonly
Version: 2.1Constructs a type with all properties of Type set to readonly, meaning the properties of the constructed type cannot be reassigned.ExampleThis 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
1interface Todo {
2 title: string;
3}
4
5const todo: Readonly<Todo> = {
6 title: 'Delete inactive users'
7};
8
9todo.title = 'Hello';
10function freeze<Type>(obj: Type): Readonly<Type>;
11Record
Version: 2.1Constructs 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.
1type CatName = 'miffy' | 'boris' | 'mordred';
2
3interface CatInfo {
4 age: number;
5 breed: string;
6}
7
8const cats: Record<CatName, CatInfo> = {
9 miffy: { age: 10, breed: 'Persian' },
10 boris: { age: 5, breed: 'Maine Coon' },
11 mordred: { age: 16, breed: 'British Shorthair' }
12};
13
14cats.boris;
15Pick
Version: 2.1Constructs a type by picking the set of properties Keys (string literal or union of string literals) from Type.
1interface Todo {
2 title: string;
3 description: string;
4 completed: boolean;
5}
6
7type TodoPreview = Pick<Todo, 'title' | 'completed'>;
8
9const todo: TodoPreview = {
10 title: 'Clean room',
11 completed: false
12};
13
14todo;
15Omit
Version: 3.5Constructs a type by picking all properties from Type and then removing Keys (string literal or union of string literals). The opposite of Pick.
1interface Todo {
2 title: string;
3 description: string;
4 completed: boolean;
5 createdAt: number;
6}
7
8type TodoPreview = Omit<Todo, 'description'>;
9
10const todo: TodoPreview = {
11 title: 'Clean room',
12 completed: false,
13 createdAt: 1615544252770
14};
15
16todo;
17
18type TodoInfo = Omit<Todo, 'completed' | 'createdAt'>;
19
20const todoInfo: TodoInfo = {
21 title: 'Pick up kids',
22 description: 'Kindergarten closes at 5pm'
23};
24
25todoInfo;
26Exclude
Version: 2.8Constructs a type by excluding from UnionType all union members that are assignable to ExcludedMembers.
1type T0 = Exclude<'a' | 'b' | 'c', 'a'>;
2type T1 = Exclude<'a' | 'b' | 'c', 'a' | 'b'>;
3type T2 = Exclude<string | number | (() => void), Function>;
4
5type Shape =
6 | { kind: 'circle'; radius: number }
7 | { kind: 'square'; x: number }
8 | { kind: 'triangle'; x: number; y: number };
9
10type T3 = Exclude<Shape, { kind: 'circle' }>;
11Extract
Version: 2.8Constructs a type by extracting from Type all union members that are assignable to Union.
1type T0 = Extract<'a' | 'b' | 'c', 'a' | 'f'>;
2type T1 = Extract<string | number | (() => void), Function>;
3
4type Shape =
5 | { kind: 'circle'; radius: number }
6 | { kind: 'square'; x: number }
7 | { kind: 'triangle'; x: number; y: number };
8
9type T2 = Extract<Shape, { kind: 'circle' }>;
10NonNullable
Version: 2.8Constructs a type by excluding null and undefined from Type.
1type T0 = NonNullable<string | number | undefined>;
2type T1 = NonNullable<string[] | null | undefined>;
3Parameters
Version: 3.1Constructs 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.
1declare function f1(arg: { a: number; b: string }): void;
2
3type T0 = Parameters<() => string>;
4type T1 = Parameters<(s: string) => void>;
5type T2 = Parameters<<T>(arg: T) => T>;
6type T3 = Parameters<typeof f1>;
7type T4 = Parameters<any>;
8type T5 = Parameters<never>;
9type T6 = Parameters<string>;
10type T7 = Parameters<Function>;
11ConstructorParameters
Version: 3.1Constructs 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).
1type T0 = ConstructorParameters<ErrorConstructor>;
2type T1 = ConstructorParameters<FunctionConstructor>;
3type T2 = ConstructorParameters<RegExpConstructor>;
4class C {
5 constructor(a: number, b: string) {}
6}
7type T3 = ConstructorParameters<typeof C>;
8type T4 = ConstructorParameters<any>;
9
10type T5 = ConstructorParameters<Function>;
11ReturnType
Version: 2.8Constructs 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.
1declare function f1(): { a: number; b: string };
2
3type T0 = ReturnType<() => string>;
4type T1 = ReturnType<(s: string) => void>;
5type T2 = ReturnType<<T>() => T>;
6type T3 = ReturnType<<T extends U, U extends number[]>() => T>;
7type T4 = ReturnType<typeof f1>;
8type T5 = ReturnType<any>;
9type T6 = ReturnType<never>;
10type T7 = ReturnType<string>;
11type T8 = ReturnType<Function>;
12InstanceType
Version: 2.8Constructs a type consisting of the instance type of a constructor function in Type.
1class C {
2 x = 0;
3 y = 0;
4}
5
6type T0 = InstanceType<typeof C>;
7type T1 = InstanceType<any>;
8type T2 = InstanceType<never>;
9type T3 = InstanceType<string>;
10type T4 = InstanceType<Function>;
11NoInfer
Version: 5.4Blocks inferences to the contained type. Other than blocking inferences, NoInfer<Type> is identical to Type.
1function createStreetLight<C extends string>(
2 colors: C[],
3 defaultColor?: NoInfer<C>
4) {
5 // ...
6}
7
8createStreetLight(['red', 'yellow', 'green'], 'red'); // OK
9createStreetLight(['red', 'yellow', 'green'], 'blue'); // Error
10ThisParameterType
Version: 3.3Extracts the type of the this parameter for a function type, or unknown if the function type has no this parameter.
1function toHex(this: Number) {
2 return this.toString(16);
3}
4
5function numberToString(n: ThisParameterType<typeof toHex>) {
6 return toHex.apply(n);
7}
8OmitThisParameter
Version: 3.3Removes 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.
1function toHex(this: Number) {
2 return this.toString(16);
3}
4
5const fiveToHex: OmitThisParameter<typeof toHex> = toHex.bind(5);
6
7console.log(fiveToHex());
8ThisType
Version: 2.3This 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.ExampleIn 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.
1type ObjectDescriptor<D, M> = {
2 data?: D;
3 methods?: M & ThisType<D & M>; // Type of 'this' in methods is D & M
4};
5
6function makeObject<D, M>(desc: ObjectDescriptor<D, M>): D & M {
7 let data: object = desc.data || {};
8 let methods: object = desc.methods || {};
9 return { ...data, ...methods } as D & M;
10}
11
12let obj = makeObject({
13 data: { x: 0, y: 0 },
14 methods: {
15 moveBy(dx: number, dy: number) {
16 this.x += dx; // Strongly typed this
17 this.y += dy; // Strongly typed this
18 }
19 }
20});
21
22obj.x = 10;
23obj.y = 20;
24obj.moveBy(5, 5);
25