Literal types e as const in TypeScript, con esempi

Un literal type è un tipo con un solo valore: "up" è un tipo il cui unico membro è la stringa "up", e 404 è un tipo il cui unico membro è il numero 404. Da soli non sono molto utili. Uniti in un'unione, ti danno una variabile che accetta un insieme fisso di valori e nient'altro.

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

Senza il commento @ts-expect-error, l'ultima chiamata è un errore in fase di compilazione (TS2345). Con il commento, il programma compila e la chiamata viene comunque eseguita e stampa moving north by 1: i literal types esistono solo per il compilatore, e a runtime il valore è una stringa normale.

Letterali stringa, numerici e booleani

Qualsiasi valore stringa, numerico, bigint o booleano si può scrivere come tipo. Il compilatore accetta poi solo quel valore esatto.

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 stesso non è altro che l'unione true | false, ed è per questo che restringere un boolean con if (flag) lascia false nel ramo else.

Unioni di letterali

L'uso comune è un'unione che elenca tutti i valori ammessi. Dentro la funzione il compilatore restringe l'unione man mano che la controlli, quindi ogni ramo sa esattamente quale valore ha.

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 ]

Un'unione di letterali stringa è l'alternativa abituale a un enum in TypeScript. Non costa niente a runtime, i valori sono stringhe normali che puoi stampare nei log e inviare in JSON, e un errore di battitura è un errore di compilazione. Trovi di più su pro e contro in enums.

Widening: let vs const

Quando TypeScript deduce un tipo da un letterale, guarda se il valore può cambiare. Una variabile const non può mai essere riassegnata, quindi mantiene il literal type. Una variabile let sì, quindi il suo tipo viene allargato al tipo generale.

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

Passa il mouse su ogni nome nell'editor per vedere il tipo dedotto. Se vuoi un let che contenga solo certi valori, annotalo: let mode: "light" | "dark" = "light".

Perché le proprietà degli oggetti vengono allargate

Le proprietà di un oggetto letterale sono modificabili, quindi vengono allargate anche loro, pure quando l'oggetto è memorizzato in una const. È il modo più comune di imbattersi per caso nei literal types:

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

Il compilatore segnala:

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

req viene dedotto come { url: string; method: string } perché più avanti del codice potrebbe eseguire req.method = "DELETE". Ci sono tre soluzioni:

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

Una quarta opzione è satisfies, che controlla l'oggetto rispetto a un tipo mantenendo i literal types delle sue proprietà.

as const

as const è una const assertion. Mettila dopo un'espressione e il compilatore deduce il tipo più stretto possibile:

• i valori stringa, numerici e booleani mantengono i loro literal types
• le proprietà degli oggetti diventano readonly
• gli array letterali diventano tuple readonly di lunghezza fissa

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

L'asserzione vale solo in fase di compilazione. Il JavaScript emesso è lo stesso oggetto letterale senza as const, quindi niente impedisce ad altro codice di modificarlo a runtime. Se ti serve una garanzia a runtime, chiama anche Object.freeze.

Un tipo unione da un array as const

Un pattern frequente è tenere i valori ammessi in un solo array, su cui puoi iterare a runtime, e ricavarne il tipo unione. (typeof arr)[number] significa "il tipo di un elemento qualsiasi di 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
}

Senza as const, ROLES sarebbe string[] e Role sarebbe una semplice string. Il cast a readonly string[] in isRole serve perché includes su una tupla di letterali accetta solo quei letterali, e lo scopo della funzione è testare una stringa che potrebbe non esserlo. Lo stesso pattern con un oggetto funziona per le mappe chiave/valore: const Status = { Active: "active", Banned: "banned" } as const, poi type Status = (typeof Status)[keyof typeof Status].

const type parameters

Una funzione generica di norma allarga i letterali che le passi. Da TypeScript 5.0 puoi marcare un parametro di tipo come const, e il compilatore dedurrà l'argomento come se avesse as const, senza chiedere a chi chiama di scriverlo.

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

È soprattutto uno strumento per chi scrive librerie: definizioni di route, builder e helper per schemi lo usano perché chi chiama ottenga tipi precisi da semplici letterali.

I significati di const

La parola chiave const compare in quattro posti diversi nel codice TypeScript:

Nessuno di questi congela un oggetto a runtime. const obj = { a: 1 } permette ancora obj.a = 2; è un errore solo riassegnare obj stesso.