Type alias w TypeScript: słowo kluczowe type z przykładami

Alias typu nadaje typowi nazwę. Piszesz type Name = ... i od tej chwili Name można używać wszędzie tam, gdzie oczekiwany jest typ. W przeciwieństwie do interfejsu alias może nazywać zupełnie dowolny typ, nie tylko kształty obiektów.

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

Aliasy istnieją tylko w czasie kompilacji. Wyemitowany JavaScript nie zawiera żadnej z tych linii type.

Składnia

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

Zwyczajowo nazwy zapisuje się w PascalCase. Po prawej stronie stoi dowolne wyrażenie typu, a alias może używać innych aliasów, także samego siebie (zobacz typy rekurencyjne niżej). Alias jest dostępny w całym zasięgu, w którym go zadeklarowano, nawet nad linią deklaracji, bo typy są sprawdzane w czasie kompilacji, a nie wykonywane po kolei jak const czy let.

Typy obiektów

Dla kształtu obiektu alias i interfejs zapisuje się niemal tak samo. Alias używa = i zwykle kończy się średnikiem.

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 *

Alias nie może używać extends, tę rolę pełni przecięcie &. Sprawdzanie nadmiarowych właściwości oraz właściwości opcjonalne i readonly działają dokładnie tak jak w interfejsach. To, którą z dwóch form wybrać dla kształtów obiektów, omawia strona interface vs type.

Unie, krotki i funkcje

To przypadki, które da się nazwać tylko aliasem, i główny powód istnienia type. Alias unii wymienia możliwe warianty, alias krotki ustala długość i typy elementów tablicy, a alias funkcji opisuje sygnaturę.

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

W scale parametry nie potrzebują adnotacji: typy dostarcza alias Transform. Składnię krotek omawia strona o krotkach, a zawężanie unii strona o typach unii.

Generyczne aliasy typów

Parametry typu sprawiają, że jeden alias działa dla wielu typów. Mogą mieć wartości domyślne, tak jak parametry funkcji.

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> używa domyślnego E = string. Małe generyczne aliasy, takie jak type Nullable<T> = T | null albo type Dict<T> = Record<string, T>, są częste w prawdziwym kodzie. Wbudowane typy narzędziowe (Partial<T>, Pick<T, K>, ReturnType<F>) to też generyczne aliasy, zadeklarowane w bibliotece standardowej.

Aliasy to nazwy, a nie nowe typy

Alias nie tworzy odrębnego typu. To druga nazwa typu z prawej strony, a kompilator traktuje oba jako identyczne. Dwa aliasy string są w pełni wymienne:

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

To wypisuje cancelling u_42 bez żadnego błędu, a to właśnie ten błąd, przed którym alias nie chroni. Alias nadal pomaga czytelnikom (parametr typu OrderId mówi więcej niż string), ale jeśli pomylenie dwóch identyfikatorów ma być błędem kompilacji, użyj branded type, takiego jak string & { readonly __brand: "OrderId" }.

Rekurencyjne aliasy typów

Alias może odwoływać się do samego siebie i tak opisuje się drzewa, zagnieżdżone listy i 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}}

Alias Json odrzuca wartości, których JSON nie potrafi przedstawić: { when: new Date() } albo { f: undefined } przypisane do Json to błędy kompilacji (TS2322).

Typy z wartości: typeof

Gdy wartość już istnieje, możesz nazwać jej typ, zamiast go wypisywać. Operator typu typeof odczytuje typ zmiennej i łączy się z innymi operatorami:

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 }

Wartość pozostaje jedynym źródłem prawdy: dodaj właściwość do defaults, a Options za nią podąży. Więcej na stronie o typeof.

Eksportowanie i importowanie aliasów

Aliasy eksportuje się i importuje tak jak wartości. import type jawnie mówi, że importowany jest tylko typ, więc import zawsze znika z wyjściowego JavaScriptu:

// 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 };