Псевдонимы типов в TypeScript: ключевое слово type

Псевдоним типа даёт имя типу. Вы пишете type Name = ..., и с этого момента Name можно использовать везде, где ожидается тип. В отличие от интерфейса, псевдоним может назвать вообще любой тип, а не только структуры объектов.

type UserId = string;                         // a primitive
type Point = { x: number; y: number };        // an object shape
type Status = "active" | "banned";            // a union of literals
type Pair = [string, number];                 // a tuple
type Formatter = (value: number) => string;   // a function

const id: UserId = "u_42";
const start: Point = { x: 0, y: 0 };
const current: Status = "active";
const entry: Pair = ["score", 90];
const money: Formatter = (v) => `$${v.toFixed(2)}`;

console.log(id, start, current, entry, money(3.5));
// u_42 { x: 0, y: 0 } active [ 'score', 90 ] $3.50

Псевдонимы существуют только при компиляции. В сгенерированном JavaScript нет ни одной из этих строк type.

Синтаксис

type Name = SomeType;
type Name<T> = SomeTypeUsing<T>;       // generic
export type Name = SomeType;           // exported from a module

Имена по соглашению пишутся в PascalCase. Правая часть это любое выражение типа, и псевдоним может использовать другие псевдонимы, включая самого себя (см. рекурсивные типы ниже). Псевдоним доступен во всей области видимости, где он объявлен, даже выше строки объявления, потому что типы проверяются при компиляции, а не выполняются по порядку, как const или let.

Объектные типы

Для структуры объекта псевдоним и интерфейс записываются почти одинаково. Псевдоним использует = и обычно завершается точкой с запятой.

type User = {
  id: number;
  name: string;
  email?: string;           // optional
  readonly createdAt: string; // cannot be reassigned
};

type Admin = User & { permissions: string[] }; // extend with an intersection

const root: Admin = {
  id: 1,
  name: "root",
  createdAt: "2024-03-15",
  permissions: ["*"],
};

console.log(`${root.name} can do ${root.permissions.join(", ")}`); // root can do *

Псевдоним не может использовать extends; эту роль играет пересечение &. Проверка лишних свойств, необязательные и readonly свойства работают точно так же, как у интерфейсов. Что из двух выбрать для структур объектов, разобрано на странице interface или type.

Объединения, кортежи и функции

Это случаи, которые может назвать только псевдоним, и главная причина существования type. Псевдоним объединения перечисляет варианты, псевдоним кортежа фиксирует длину и типы элементов массива, а псевдоним функции описывает сигнатуру.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

type Span = [start: number, end: number]; // labeled tuple elements

type Transform = (shape: Shape, factor: number) => Shape;

const scale: Transform = (shape, factor) =>
  shape.kind === "circle"
    ? { kind: "circle", radius: shape.radius * factor }
    : { kind: "rect", width: shape.width * factor, height: shape.height * factor };

const r: Span = [10, 20];
console.log(scale({ kind: "circle", radius: 2 }, 3)); // { kind: 'circle', radius: 6 }
console.log(r[1] - r[0]);                              // 10

В scale параметрам не нужны аннотации: их типы задаёт псевдоним Transform. Синтаксис кортежей описан в разделе кортежи, а сужение объединений на странице о типах объединения.

Обобщённые псевдонимы типов

Параметры типа позволяют одному псевдониму работать со многими типами. У них могут быть значения по умолчанию, как у параметров функций.

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0
    ? { ok: true, value: n }
    : { ok: false, error: `not an age: ${text}` };
}

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? `age ${r.value}` : r.error);
}
// age 36
// not an age: abc

Result<number> использует значение по умолчанию E = string. Небольшие обобщённые псевдонимы вроде type Nullable<T> = T | null или type Dict<T> = Record<string, T> часто встречаются в реальном коде. Встроенные служебные типы (Partial<T>, Pick<T, K>, ReturnType<F>) тоже обобщённые псевдонимы, объявленные в стандартной библиотеке.

Псевдонимы это имена, а не новые типы

Псевдоним не создаёт отдельный тип. Это второе имя для типа справа, и компилятор считает их идентичными. Два псевдонима для string полностью взаимозаменяемы:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: UserId and OrderId are both just string

Этот код печатает cancelling u_42 без ошибки, и это как раз та ошибка, которую псевдоним не может предотвратить. Псевдоним всё равно помогает читателю (параметр с типом OrderId говорит больше, чем string), но если перепутать два идентификатора должно быть ошибкой компиляции, используйте брендированный тип, например string & { readonly __brand: "OrderId" }.

Рекурсивные псевдонимы типов

Псевдоним может ссылаться на себя; так описывают деревья, вложенные списки и JSON:

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | { [key: string]: Json };

type TreeNode = {
  value: number;
  children: TreeNode[];
};

function sum(node: TreeNode): number {
  return node.value + node.children.reduce((total, child) => total + sum(child), 0);
}

const tree: TreeNode = {
  value: 1,
  children: [
    { value: 2, children: [] },
    { value: 3, children: [{ value: 4, children: [] }] },
  ],
};

const payload: Json = { ok: true, items: [1, "two", null], meta: { page: 1 } };

console.log(sum(tree));               // 10
console.log(JSON.stringify(payload)); // {"ok":true,"items":[1,"two",null],"meta":{"page":1}}

Псевдоним Json отвергает значения, которые JSON не может представить: { when: new Date() } или { f: undefined }, присвоенные в Json, это ошибки компиляции (TS2322).

Типы из значений: typeof

Если значение уже существует, можно назвать его тип, а не выписывать его. Оператор типа typeof читает тип переменной и сочетается с другими операторами:

const defaults = { retries: 3, verbose: false, level: "info" };

type Options = typeof defaults;
// { retries: number; verbose: boolean; level: string }

type OptionKey = keyof typeof defaults;
// "retries" | "verbose" | "level"

function start(port: number) {
  return { port, startedAt: new Date() };
}
type Server = ReturnType<typeof start>;
// { port: number; startedAt: Date }

Значение остаётся единственным источником истины: добавьте свойство в defaults, и Options последует за ним. Подробнее в разделе typeof.

Экспорт и импорт псевдонимов

Псевдонимы экспортируются и импортируются как значения. import type явно показывает, что импортируется только тип, поэтому такой импорт всегда удаляется из вывода JavaScript:

// shapes.ts
export type Point = { x: number; y: number };
export type Shape = { kind: "circle"; center: Point; radius: number };

// main.ts
import type { Point, Shape } from "./shapes.js";

const p: Point = { x: 1, y: 2 };