Literal types e as const em TypeScript, com exemplos

Um literal type é um tipo com exatamente um valor: "up" é um tipo cujo único membro é a string "up", e 404 é um tipo cujo único membro é o número 404. Sozinhos eles não ajudam muito. Juntos em uma union, dão a você uma variável que aceita um conjunto fixo de valores e nada mais.

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

Sem o comentário @ts-expect-error, a última chamada é um erro de compilação (TS2345). Com ele, o programa compila e a chamada ainda roda e imprime moving north by 1: literal types existem só para o compilador, e em tempo de execução o valor é uma string comum.

Literais de string, number e boolean

Qualquer valor string, number, bigint ou boolean pode ser escrito como tipo. O compilador então aceita só aquele valor exato.

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;

O próprio boolean é só a union true | false, e é por isso que fazer narrowing de um boolean com if (flag) deixa false no else.

Unions de literais

O uso comum é uma union que lista todos os valores permitidos. Dentro da função, o compilador faz o narrowing da union conforme você a verifica, então cada ramo sabe exatamente qual valor tem.

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 ]

Uma union de literais de string é a alternativa usual a um enum no TypeScript. Não custa nada em tempo de execução, os valores são strings comuns que você pode imprimir no log e enviar em JSON, e um erro de digitação é erro de compilação. Mais sobre as vantagens e desvantagens em enums.

Widening: let vs const

Quando o TypeScript infere um tipo a partir de um literal, ele olha se o valor pode mudar. Uma variável const nunca pode ser reatribuída, então mantém o literal type. Uma variável let pode, então o tipo dela é alargado para o tipo geral.

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

Passe o mouse sobre cada nome no editor para ver o tipo inferido. Se você quer um let que só guarde certos valores, anote-o: let mode: "light" | "dark" = "light".

Por que as propriedades de objeto são alargadas

Propriedades de um objeto literal são mutáveis, então também são alargadas, mesmo quando o objeto está guardado em um const. É o jeito mais comum de esbarrar em literal types sem querer:

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

O compilador mostra:

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

req é inferido como { url: string; method: string } porque um código mais adiante poderia rodar req.method = "DELETE". Há três soluções:

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

Uma quarta opção é o satisfies, que verifica o objeto contra um tipo mantendo os literal types das propriedades.

as const

as const é uma const assertion. Coloque depois de uma expressão e o compilador infere o tipo mais estreito possível:

• valores string, number e boolean mantêm os literal types
• propriedades de objeto viram readonly
• literais de array viram tuplas readonly com tamanho fixo

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

A assertion vale só em tempo de compilação. O JavaScript gerado é o mesmo objeto literal sem o as const, então nada impede outro código de alterá-lo em tempo de execução. Se você precisa de uma garantia em tempo de execução, chame também Object.freeze.

Um union type a partir de um array as const

Um padrão frequente é manter os valores permitidos em um array, que você pode percorrer em tempo de execução, e derivar o union type dele. (typeof arr)[number] significa "o tipo de qualquer elemento de 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
}

Sem as const, ROLES seria string[] e Role seria só string. O cast para readonly string[] em isRole é necessário porque includes em uma tupla de literais só aceita esses literais, e o objetivo da função é testar uma string que pode não ser um deles. O mesmo padrão com objeto funciona para mapas de chave e valor: const Status = { Active: "active", Banned: "banned" } as const e depois type Status = (typeof Status)[keyof typeof Status].

const type parameters

Uma função genérica normalmente alarga os literais que você passa. Desde o TypeScript 5.0, você pode marcar um type parameter como const, o que faz o compilador inferir o argumento como se ele tivesse as const, sem pedir que quem chama escreva isso.

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

É principalmente uma ferramenta para autores de bibliotecas: definições de rotas, builders e helpers de schema a usam para que quem chama receba tipos precisos a partir de literais simples.

Os significados de const

A palavra const aparece em quatro lugares diferentes no código TypeScript:

Nenhum deles congela um objeto em tempo de execução. const obj = { a: 1 } ainda permite obj.a = 2; só reatribuir o próprio obj é um erro.