TypeScript Typalias: das Schlüsselwort type mit Beispielen

Ein Typalias gibt einem Typ einen Namen. Du schreibst type Name = ..., und von da an lässt sich Name überall verwenden, wo ein Typ erwartet wird. Anders als ein Interface kann ein Alias jeden beliebigen Typ benennen, nicht nur Objektformen.

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

Aliasse existieren nur beim Kompilieren. Das erzeugte JavaScript enthält keine dieser type-Zeilen.

Syntax

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

Namen werden per Konvention in PascalCase geschrieben. Die rechte Seite ist ein beliebiger Typausdruck, und ein Alias kann andere Aliasse verwenden, auch sich selbst (siehe rekursive Typen unten). Der Alias ist im ganzen Scope verfügbar, in dem er deklariert ist, sogar oberhalb der Deklarationszeile, denn Typen werden beim Kompilieren geprüft und nicht der Reihe nach ausgeführt wie const oder let.

Objekttypen

Für eine Objektform werden Alias und Interface fast gleich geschrieben. Der Alias verwendet = und endet meist mit einem Semikolon.

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 *

Ein Alias kann kein extends verwenden; die Intersection mit & übernimmt diese Rolle. Excess Property Checks, optionale und readonly Eigenschaften funktionieren genau wie bei Interfaces. Welche der beiden Formen du für Objektformen wählst, behandelt die Seite interface vs type.

Unions, Tupel und Funktionen

Das sind die Fälle, die nur ein Alias benennen kann, und der Hauptgrund, warum es type gibt. Ein Union-Alias listet die Alternativen auf, ein Tupel-Alias legt Länge und Elementtypen eines Arrays fest, und ein Funktionsalias beschreibt eine Signatur.

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

In scale brauchen die Parameter keine Annotationen: Der Alias Transform liefert ihre Typen. Die Syntax von Tupeln steht unter Tupel, das Einengen von Unions auf der Seite zu Union-Typen.

Generische Typaliasse

Typparameter lassen einen Alias für viele Typen funktionieren. Sie können Standardwerte haben, genau wie Funktionsparameter.

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> verwendet den Standardwert E = string. Kleine generische Aliasse wie type Nullable<T> = T | null oder type Dict<T> = Record<string, T> sind in echtem Code verbreitet. Auch die eingebauten Utility Types (Partial<T>, Pick<T, K>, ReturnType<F>) sind generische Aliasse, deklariert in der Standardbibliothek.

Aliasse sind Namen, keine neuen Typen

Ein Alias erzeugt keinen eigenständigen Typ. Er ist ein zweiter Name für den Typ auf der rechten Seite, und der Compiler behandelt beide als identisch. Zwei Aliasse von string sind vollständig austauschbar:

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

Das gibt cancelling u_42 ohne Fehler aus, und genau diesen Bug kann ein Alias nicht verhindern. Der Alias hilft trotzdem beim Lesen (ein als OrderId typisierter Parameter sagt mehr als string), aber wenn das Verwechseln zweier IDs ein Compilerfehler sein muss, nimm einen Branded Type wie string & { readonly __brand: "OrderId" }.

Rekursive Typaliasse

Ein Alias kann auf sich selbst verweisen, und so beschreibst du Bäume, verschachtelte Listen und 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}}

Der Alias Json lehnt Werte ab, die JSON nicht darstellen kann: { when: new Date() } oder { f: undefined } einer Variablen vom Typ Json zuzuweisen sind Compilerfehler (TS2322).

Typen aus Werten: typeof

Wenn ein Wert schon existiert, kannst du seinen Typ benennen, statt ihn auszuschreiben. Der Typoperator typeof liest den Typ einer Variablen, und er lässt sich mit anderen Operatoren kombinieren:

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 }

Der Wert bleibt die einzige Quelle der Wahrheit: Füge defaults eine Eigenschaft hinzu, und Options folgt. Mehr dazu unter typeof.

Aliasse exportieren und importieren

Aliasse werden wie Werte exportiert und importiert. import type macht ausdrücklich, dass nur ein Typ importiert wird, sodass der Import immer aus der JavaScript-Ausgabe entfernt wird:

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