Typy literałowe i as const w TypeScript, z przykładami

Typ literałowy to typ z dokładnie jedną wartością: "up" to typ, którego jedynym elementem jest string "up", a 404 to typ, którego jedynym elementem jest liczba 404. Same w sobie nie są zbyt przydatne. Połączone w unię dają zmienną, która przyjmuje stały zestaw wartości i nic poza nim.

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);

Bez komentarza @ts-expect-error ostatnie wywołanie to błąd kompilacji (TS2345). Z komentarzem program się kompiluje, a wywołanie i tak się wykonuje i wypisuje moving north by 1: typy literałowe istnieją tylko dla kompilatora, a w czasie działania wartość to zwykły string.

Literały string, number i boolean

Każdą wartość typu string, number, bigint albo boolean można zapisać jako typ. Kompilator przyjmuje wtedy tylko tę dokładną wartość.

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;

Sam boolean to po prostu unia true | false, dlatego zawężenie boolean przez if (flag) zostawia false w gałęzi else.

Unie literałów

Typowe zastosowanie to unia, która wymienia każdą dozwoloną wartość. Wewnątrz funkcji kompilator zawęża unię w miarę sprawdzania, więc każda gałąź dokładnie wie, jaką ma wartość.

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 ]

Unia literałów stringowych to typowa w TypeScript alternatywa dla enuma. Nic nie kosztuje w czasie działania, wartości to zwykłe stringi, które można logować i wysyłać w JSON-ie, a literówka jest błędem kompilacji. Więcej o zaletach i wadach na stronie o enumach.

Poszerzanie: let kontra const

Gdy TypeScript wnioskuje typ z literału, patrzy, czy wartość może się zmienić. Zmiennej const nigdy nie da się przypisać na nowo, więc zachowuje typ literałowy. Zmienną let da się, więc jej typ zostaje poszerzony do typu ogólnego.

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

Najedź kursorem na każdą nazwę w edytorze, żeby zobaczyć wywnioskowany typ. Jeśli chcesz, żeby let przechowywało tylko określone wartości, oznacz jego typ: let mode: "light" | "dark" = "light".

Dlaczego właściwości obiektów się poszerzają

Właściwości literału obiektowego są modyfikowalne, więc też się poszerzają, nawet gdy obiekt jest zapisany w const. To najczęstszy sposób, w jaki trafia się na typy literałowe przypadkiem:

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

Kompilator zgłasza:

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

req ma wywnioskowany typ { url: string; method: string }, bo późniejszy kod mógłby wykonać req.method = "DELETE". Są trzy rozwiązania:

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);

Czwarta opcja to satisfies, które sprawdza obiekt względem typu, a jednocześnie zachowuje literałowe typy jego właściwości.

as const

as const to const assertion. Umieść je po wyrażeniu, a kompilator wywnioskuje najwęższy możliwy typ:

• wartości string, number i boolean zachowują typy literałowe
• właściwości obiektów stają się readonly
• literały tablic stają się krotkami readonly o stałej długości

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

Asercja działa tylko w czasie kompilacji. Wygenerowany JavaScript to ten sam literał obiektowy bez as const, więc nic nie powstrzyma innego kodu przed modyfikacją go w czasie działania. Jeśli potrzebujesz gwarancji w czasie działania, wywołaj też Object.freeze.

Typ unii z tablicy as const

Częsty wzorzec to trzymanie dozwolonych wartości w jednej tablicy, po której można iterować w czasie działania, i wyprowadzanie z niej typu unii. (typeof arr)[number] oznacza „typ dowolnego elementu 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
}

Bez as const ROLES miałoby typ string[], a Role byłoby zwykłym string. Rzutowanie na readonly string[] w isRole jest potrzebne, bo includes na krotce literałów przyjmuje tylko te literały, a funkcja ma właśnie sprawdzić string, który może nie być żadnym z nich. Ten sam wzorzec z obiektem działa dla map klucz/wartość: const Status = { Active: "active", Banned: "banned" } as const, a potem type Status = (typeof Status)[keyof typeof Status].

Parametry typu const

Funkcja generyczna zwykle poszerza przekazane jej literały. Od TypeScript 5.0 można oznaczyć parametr typu jako const, dzięki czemu kompilator wnioskuje argument tak, jakby miał as const, bez proszenia wywołującego o dopisanie tego.

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

To głównie narzędzie dla autorów bibliotek: definicje tras, buildery i funkcje pomocnicze do schematów korzystają z niego, żeby wywołujący dostawali dokładne typy ze zwykłych literałów.

Znaczenia const

Słowo kluczowe const pojawia się w kodzie TypeScript w czterech różnych miejscach:

Żadne z nich nie zamraża obiektu w czasie działania. const obj = { a: 1 } nadal pozwala na obj.a = 2; błędem jest tylko ponowne przypisanie samego obj.