TypeScript$Type-Value-UtilityTypes

为了更方便的“创造”类型，TypeScript 提供了一些工具类型。本文和官方文档的内容几乎一样，只是加了分类和说明。

1. 对象类型属性的属性调整

1.1 Partial<Type>

局部。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.

interface Todo {
  title: string;
  description: string;
}
 
function updateTodo(todo: Todo, fieldsToUpdate: Partial<Todo>) {
  return { ...todo, ...fieldsToUpdate };
}
 
const todo1 = {
  title: "organize desk",
  description: "clear clutter",
};
 
const todo2 = updateTodo(todo1, {
  description: "throw out trash",
});
const todo3 = updateTodo(todo1, {});

1.2 Required<Type>

所有。Constructs a type consisting of all properties of Type set to required. The opposite of Partial.

interface Props {
  a?: number;
  b?: string;
}
 
const obj: Props = { a: 5 };
 
const obj2: Required<Props> = { a: 5 };
// error, Property 'b' is missing in type '{ a: number; }' but required in type 'Required<Props>'.

1.3 Readonly<Type>

只读。Constructs a type with all properties of Type set to readonly, meaning the properties of the constructed type cannot be reassigned.

interface Todo {
  title: string;
}
 
const todo: Readonly<Todo> = {
  title: "Delete inactive users",
};
 
todo.title = "Hello";
// error, Cannot assign to 'title' because it is a read-only property.

This utility is useful for representing assignment expressions that will fail at runtime (i.e. when attempting to reassign properties of a frozen object).

function freeze<Type>(obj: Type): Readonly<Type>;

2. 对象类型属性的增减和拼凑

2.1 Record<Keys, Type>

键值对-拼凑。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.

type CatName = "miffy" | "boris" | "mordred";
 
interface CatInfo {
  age: number;
  breed: string;
}
 
const cats: Record<CatName, CatInfo> = {
  miffy: { age: 10, breed: "Persian" },
  boris: { age: 5, breed: "Maine Coon" },
  mordred: { age: 16, breed: "British Shorthair" },
};
 
cats.boris;
 // const cats: Record<CatName, CatInfo>

2.2 Pick<Type, Keys>

筛选 keys。Constructs a type by picking the set of properties Keys (string literal or union of string literals) from Type.

interface Todo {
  title: string;
  description: string;
  completed: boolean;
}
 
type TodoPreview = Pick<Todo, "title" | "completed">;
 
const todo: TodoPreview = {
  title: "Clean room",
  completed: false,
};
 
todo;
 // const todo: TodoPreview

2.3 Omit<Type, Keys>

忽略 keys。Constructs a type by picking all properties from Type and then removing Keys (string literal or union of string literals). The opposite of Pick.

interface Todo {
  title: string;
  description: string;
  completed: boolean;
  createdAt: number;
}
 
type TodoPreview = Omit<Todo, "description">;
 
const todo: TodoPreview = {
  title: "Clean room",
  completed: false,
  createdAt: 1615544252770,
};
 
todo;
 // const todo: TodoPreview
 
type TodoInfo = Omit<Todo, "completed" | "createdAt">;
 
const todoInfo: TodoInfo = {
  title: "Pick up kids",
  description: "Kindergarten closes at 5pm",
};
 
todoInfo;
   // const todoInfo: TodoInfo

3. 集合类型的处理

3.1 Exclude<UnionType, ExcludedMembers>

减。Constructs a type by excluding from UnionType all union members that are assignable to ExcludedMembers. 注意，Exclude<string, 'name'> 不好用。

type T0 = Exclude<"a" | "b" | "c", "a">;
     // type T0 = "b" | "c"
type T1 = Exclude<"a" | "b" | "c", "a" | "b">;
     // type T1 = "c"
type T2 = Exclude<string | number | (() => void), Function>;
     // type T2 = string | number
 
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; x: number }
  | { kind: "triangle"; x: number; y: number };
 
type T3 = Exclude<Shape, { kind: "circle" }>
     /* type T3 = {
    kind: "square";
    x: number;
} | {
    kind: "triangle";
    x: number;
    y: number;
} */

3.2 Extract<Type, Union>

抽。Constructs a type by extracting from Type all union members that are assignable to Union.

type T0 = Extract<"a" | "b" | "c", "a" | "f">;
     // type T0 = "a"
type T1 = Extract<string | number | (() => void), Function>;
     // type T1 = () => void
 
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; x: number }
  | { kind: "triangle"; x: number; y: number };
 
type T2 = Extract<Shape, { kind: "circle" }>
     /* type T2 = {
    kind: "circle";
    radius: number;
} */

3.3 NonNullable<Type>

非空。Constructs a type by excluding null and undefined from Type.

type T0 = NonNullable<string | number | undefined>;
     // type T0 = string | number
type T1 = NonNullable<string[] | null | undefined>;
     // type T1 = string[]

4. 函数类型的处理

4.1 Parameters<Type>

参数。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.

declare function f1(arg: { a: number; b: string }): void;
 
type T0 = Parameters<() => string>;
     // type T0 = []
type T1 = Parameters<(s: string) => void>;
     // type T1 = [s: string]
type T2 = Parameters<<T>(arg: T) => T>;
     // type T2 = [arg: unknown]
type T3 = Parameters<typeof f1>;
     /* type T3 = [arg: {
    a: number;
    b: string; */
}]
type T4 = Parameters<any>;
     // type T4 = unknown[]
type T5 = Parameters<never>;
     // type T5 = never
type T6 = Parameters<string>;
// error, Type 'string' does not satisfy the constraint '(...args: any) => any'.
     // type T6 = never
type T7 = Parameters<Function>;
/* error, Type 'Function' does not satisfy the constraint '(...args: any) => any'.
  Type 'Function' provides no match for the signature '(...args: any): any'. */
     // type T7 = never

4.2 ConstructorParameters<Type>

构造器参数。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).

type T0 = ConstructorParameters<ErrorConstructor>;
     // type T0 = [message?: string]
type T1 = ConstructorParameters<FunctionConstructor>;
     // type T1 = string[]
type T2 = ConstructorParameters<RegExpConstructor>;
     // type T2 = [pattern: string | RegExp, flags?: string]
class C {
  constructor(a: number, b: string) {}
}
type T3 = ConstructorParameters<typeof C>;
     // type T3 = [a: number, b: string]
type T4 = ConstructorParameters<any>;
     // type T4 = unknown[]
 
type T5 = ConstructorParameters<Function>;
/* Type 'Function' does not satisfy the constraint 'abstract new (...args: any) => any'.
  Type 'Function' provides no match for the signature 'new (...args: any): any'. */
     // type T5 = never

4.3 ReturnType<Type>

返回值。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.

declare function f1(): { a: number; b: string };
 
type T0 = ReturnType<() => string>;
     // type T0 = string
type T1 = ReturnType<(s: string) => void>;
     // type T1 = void
type T2 = ReturnType<<T>() => T>;
     // type T2 = unknown
type T3 = ReturnType<<T extends U, U extends number[]>() => T>;
     // type T3 = number[]
type T4 = ReturnType<typeof f1>;
     /* type T4 = {
    a: number;
    b: string;
} */
type T5 = ReturnType<any>;
     // type T5 = any
type T6 = ReturnType<never>;
     // type T6 = never
type T7 = ReturnType<string>;
// error, Type 'string' does not satisfy the constraint '(...args: any) => any'.
     // type T7 = any
type T8 = ReturnType<Function>;
/* Type 'Function' does not satisfy the constraint '(...args: any) => any'.
  Type 'Function' provides no match for the signature '(...args: any): any'. */
     // type T8 = any

4.4 InstanceType<Type>

实例。Constructs a type consisting of the instance type of a constructor function in Type.

class C {
  x = 0;
  y = 0;
}
 
type T0 = InstanceType<typeof C>;
     // type T0 = C
type T1 = InstanceType<any>;
     // type T1 = any
type T2 = InstanceType<never>;
     // type T2 = never
type T3 = InstanceType<string>;
// error, Type 'string' does not satisfy the constraint 'abstract new (...args: any) => any'.
     // type T3 = any
type T4 = InstanceType<Function>;
/* Type 'Function' does not satisfy the constraint 'abstract new (...args: any) => any'.
  Type 'Function' provides no match for the signature 'new (...args: any): any'. */
     // type T4 = any

4.5.1ThisParameterType<Type>

this。Extracts the type of the this parameter for a function type, or unknown if the function type has no this parameter.

function toHex(this: Number) {
  return this.toString(16);
}
 
function numberToString(n: ThisParameterType<typeof toHex>) {
  return toHex.apply(n);
}

4.5.2OmitThisParameter<Type>

忽略 this。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.

function toHex(this: Number) {
  return this.toString(16);
}
 
const fiveToHex: OmitThisParameter<typeof toHex> = toHex.bind(5);
 
console.log(fiveToHex());

4.5.3ThisType<Type>

声明 this。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. 下面的代码如果没有声明 & ThisType<D & M>，moveBy 里的 this 就找不到 this.x，但是因为声明了，且D 中有 x，所以就不报错了。所以 ThisType<Type> 像是显示地告诉 this 的类型。

type ObjectDescriptor<D, M> = {
  data?: D;
  methods?: M & ThisType<D & M>; // Type of 'this' in methods is D & M
};
 
function makeObject<D, M>(desc: ObjectDescriptor<D, M>): D & M {
  let data: object = desc.data || {};
  let methods: object = desc.methods || {};
  return { ...data, ...methods } as D & M;
}
 
let obj = makeObject({
  data: { x: 0, y: 0 },
  methods: {
    moveBy(dx: number, dy: number) {
      this.x += dx; // Strongly typed this
      this.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.

5. Intrinsic String Manipulation Types

Uppercase<StringType>

Lowercase<StringType>

Capitalize<StringType>

Uncapitalize<StringType>

6. Awaited<Type>

type A = Awaited<Promise<string>>;
    // type A = string
type B = Awaited<Promise<Promise<number>>>;
    // type B = number
type C = Awaited<boolean | Promise<number>>;
    // type C = number | boolean

7. NoInfer<Type>

Blocks inferences to the contained type. Other than blocking inferences, NoInfer<Type> is identical to Type.

function createStreetLight<C extends string>(
  colors: C[],
  defaultColor?: NoInfer<C>,
) {
  // ...
}
createStreetLight(["red", "yellow", "green"], "red");  // OK
createStreetLight(["red", "yellow", "green"], "blue");  // Error

Links

TypeScriptUtilityTypes