TypeScript Literaltypen und as const, mit Beispielen

Ein Literaltyp ist ein Typ mit genau einem Wert: "up" ist ein Typ, dessen einziger Member der String "up" ist, und 404 ist ein Typ, dessen einziger Member die Zahl 404 ist. Allein sind sie nicht sehr nützlich. Zu einer Union verbunden, geben sie dir eine Variable, die eine feste Menge von Werten akzeptiert und sonst nichts.

type Direction = "up" | "down" | "left" | "right";

function move(dir: Direction, steps: number) {
  console.log(`moving ${dir} by ${steps}`);
}

move("up", 3);
move("left", 1);

// @ts-expect-error: Argument of type '"north"' is not assignable to parameter of type 'Direction'.
move("north", 1);

Ohne den Kommentar @ts-expect-error ist der letzte Aufruf ein Fehler beim Kompilieren (TS2345). Mit ihm kompiliert das Programm, und der Aufruf läuft trotzdem und gibt moving north by 1 aus: Literaltypen existieren nur für den Compiler, und zur Laufzeit ist der Wert ein gewöhnlicher String.

String-, Zahl- und Boolean-Literale

Jeder String, jede Zahl, jeder Bigint und jeder Boolean-Wert lässt sich als Typ schreiben. Der Compiler akzeptiert dann nur genau diesen Wert.

let method: "GET" = "GET";
let code: 404 = 404;
let ok: true = true;
let big: 10n = 10n;

type Port = 80 | 443 | 8080;
const port: Port = 443;

boolean selbst ist nur die Union true | false, deshalb bleibt beim Einengen eines boolean mit if (flag) im else-Zweig false übrig.

Unions aus Literalen

Der übliche Einsatz ist eine Union, die jeden erlaubten Wert aufführt. In der Funktion engt der Compiler die Union ein, während du sie prüfst, sodass jeder Zweig genau weiß, welchen Wert er hat.

type Size = "sm" | "md" | "lg";

function padding(size: Size): number {
  if (size === "sm") return 4;
  if (size === "md") return 8;
  return 16; // size is "lg" here
}

const sizes: Size[] = ["sm", "md", "lg"];
console.log(sizes.map(padding)); // [ 4, 8, 16 ]

Eine Union aus String-Literalen ist die übliche Alternative zu einem Enum in TypeScript. Sie kostet zur Laufzeit nichts, die Werte sind einfache Strings, die du loggen und per JSON senden kannst, und ein Tippfehler ist ein Compilerfehler. Mehr zu den Abwägungen unter Enums.

Widening: let vs const

Wenn TypeScript einen Typ aus einem Literal ableitet, schaut es, ob sich der Wert ändern kann. Eine const-Variable kann nie neu zugewiesen werden, also behält sie den Literaltyp. Eine let-Variable kann es, also wird ihr Typ zum allgemeinen Typ erweitert.

const a = "hello"; // type: "hello"
let b = "hello";   // type: string
b = "bye";         // fine, b is a string

const n = 42;      // type: 42
let m = 42;        // type: number

let c = a;         // type: string (copying a literal into a let widens it)

console.log(a, b, n, m, c); // hello bye 42 42 hello

Fahre im Editor mit der Maus über jeden Namen, um den abgeleiteten Typ zu sehen. Willst du eine let, die nur bestimmte Werte enthält, annotiere sie: let mode: "light" | "dark" = "light".

Warum Objekteigenschaften erweitert werden

Eigenschaften eines Objektliterals sind veränderbar, also werden sie ebenfalls erweitert, selbst wenn das Objekt in einer const liegt. So begegnet man Literaltypen am häufigsten unabsichtlich:

// This does not compile: req.method is string, not "GET" | "POST"
function send(url: string, method: "GET" | "POST") {
  console.log(method, url);
}

const req = { url: "/users", method: "GET" };
send(req.url, req.method);

Der Compiler meldet:

index.ts(7,15): error TS2345: Argument of type 'string' is not assignable to parameter of type '"GET" | "POST"'.

req wird als { url: string; method: string } abgeleitet, weil später Code req.method = "DELETE" ausführen könnte. Es gibt drei Lösungen:

type Method = "GET" | "POST";

function send(url: string, method: Method) {
  console.log(method, url);
}

// 1. Annotate the object (or the property)
const r1: { url: string; method: Method } = { url: "/users", method: "GET" };

// 2. as const on the whole object: every property becomes readonly and literal
const r2 = { url: "/posts", method: "POST" } as const;

// 3. as const on one property only
const r3 = { url: "/tags", method: "GET" as const };

send(r1.url, r1.method);
send(r2.url, r2.method);
send(r3.url, r3.method);

Eine vierte Möglichkeit ist satisfies, das das Objekt gegen einen Typ prüft und dabei seine literalen Eigenschaftstypen behält.

as const

as const ist eine Const Assertion. Setze sie hinter einen Ausdruck, und der Compiler leitet den engsten möglichen Typ ab:

• String, Zahl und Boolean-Werte behalten ihre Literaltypen
• Objekteigenschaften werden readonly
• Array-Literale werden zu readonly Tupeln mit fester Länge

const config = {
  env: "production",
  retries: 3,
  hosts: ["a.example.com", "b.example.com"],
} as const;
// type: { readonly env: "production"; readonly retries: 3;
//         readonly hosts: readonly ["a.example.com", "b.example.com"] }

// @ts-expect-error: Cannot assign to 'env' because it is a read-only property.
config.env = "staging";

const point = [3, 4] as const; // type: readonly [3, 4]
const [x, y] = point;
console.log(config.retries, x + y); // 3 7

Die Assertion gilt nur beim Kompilieren. Das erzeugte JavaScript ist dasselbe Objektliteral ohne as const, also hindert nichts anderen Code daran, es zur Laufzeit zu verändern. Brauchst du eine Garantie zur Laufzeit, rufe zusätzlich Object.freeze auf.

Ein Union-Typ aus einem as const Array

Ein häufiges Muster: Die erlaubten Werte liegen in einem Array, über das du zur Laufzeit iterieren kannst, und der Union-Typ wird daraus abgeleitet. (typeof arr)[number] bedeutet „der Typ eines beliebigen Elements von arr“.

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function isRole(value: string): value is Role {
  return (ROLES as readonly string[]).includes(value);
}

for (const input of ["editor", "owner"]) {
  console.log(input, isRole(input)); // editor true, then owner false
}

Ohne as const wäre ROLES ein string[] und Role einfach string. Der Cast zu readonly string[] in isRole ist nötig, weil includes auf einem Tupel aus Literalen nur diese Literale akzeptiert, und der Sinn der Funktion ist, einen String zu prüfen, der vielleicht keines ist. Dasselbe Objektmuster funktioniert für Zuordnungen von Schlüsseln zu Werten: const Status = { Active: "active", Banned: "banned" } as const, dann type Status = (typeof Status)[keyof typeof Status].

const-Typparameter

Eine generische Funktion erweitert normalerweise die Literale, die du ihr übergibst. Seit TypeScript 5.0 kannst du einen Typparameter als const markieren, dann leitet der Compiler das Argument ab, als stünde as const daran, ohne dass der Aufrufer es schreiben muss.

function plain<T>(value: T) {
  return value;
}

function exact<const T>(value: T) {
  return value;
}

const a = plain({ kind: "circle", sizes: [1, 2] });
// type: { kind: string; sizes: number[] }

const b = exact({ kind: "circle", sizes: [1, 2] });
// type: { readonly kind: "circle"; readonly sizes: readonly [1, 2] }

console.log(a.kind === b.kind); // true

Das ist vor allem ein Werkzeug für Bibliotheksautoren: Routendefinitionen, Builder und Schema-Helfer nutzen es, damit Aufrufer aus einfachen Literalen genaue Typen bekommen.

Die Bedeutungen von const

Das Schlüsselwort const taucht in TypeScript-Code an vier verschiedenen Stellen auf:

Keins davon friert ein Objekt zur Laufzeit ein. const obj = { a: 1 } erlaubt weiterhin obj.a = 2; nur obj selbst neu zuzuweisen ist ein Fehler.