Tipos literales y as const en TypeScript, con ejemplos

Un tipo literal es un tipo con exactamente un valor: "up" es un tipo cuyo único miembro es el string "up", y 404 es un tipo cuyo único miembro es el número 404. Por sí solos no son muy útiles. Unidos en una unión, te dan una variable que acepta un conjunto fijo de valores y nada más.

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

Sin el comentario @ts-expect-error, la última llamada es un error en tiempo de compilación (TS2345). Con él, el programa compila y la llamada se ejecuta igualmente e imprime moving north by 1: los tipos literales solo existen para el compilador, y en tiempo de ejecución el valor es un string normal.

Literales de string, number y boolean

Cualquier valor string, number, bigint o boolean se puede escribir como tipo. El compilador acepta entonces solo ese valor exacto.

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 en sí es solo la unión true | false, y por eso estrechar un boolean con if (flag) deja false en la rama else.

Uniones de literales

El uso habitual es una unión que enumera todos los valores permitidos. Dentro de la función, el compilador estrecha la unión a medida que la compruebas, así que cada rama sabe exactamente qué valor tiene.

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 ]

Una unión de literales de string es la alternativa habitual a un enum en TypeScript. No cuesta nada en tiempo de ejecución, los valores son strings normales que puedes escribir en logs y enviar por JSON, y una errata es un error de compilación. Hay más sobre las ventajas e inconvenientes en enums.

Ensanchamiento: let frente a const

Cuando TypeScript infiere un tipo a partir de un literal, mira si el valor puede cambiar. Una variable const no se puede reasignar nunca, así que conserva el tipo literal. Una variable let sí, así que su tipo se ensancha al tipo general.

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

Pasa el cursor por cada nombre en el editor para ver el tipo inferido. Si quieres un let que solo guarde ciertos valores, anótalo: let mode: "light" | "dark" = "light".

Por qué se ensanchan las propiedades de los objetos

Las propiedades de un objeto literal son mutables, así que también se ensanchan, aunque el objeto esté guardado en una const. Es la forma más habitual de toparse con los tipos literales sin 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);

El compilador informa:

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

req se infiere como { url: string; method: string } porque más adelante algún código podría ejecutar req.method = "DELETE". Hay tres soluciones:

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 cuarta opción es satisfies, que comprueba el objeto contra un tipo conservando los tipos literales de sus propiedades.

as const

as const es una const assertion. Ponla después de una expresión y el compilador infiere el tipo más estrecho que puede:

• los valores string, number y boolean conservan sus tipos literales
• las propiedades de los objetos pasan a ser readonly
• los arrays literales pasan a ser tuplas readonly de longitud fija

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

La aserción solo existe en tiempo de compilación. El JavaScript generado es el mismo objeto literal sin el as const, así que nada impide que otro código lo modifique en tiempo de ejecución. Si necesitas una garantía en tiempo de ejecución, llama también a Object.freeze.

Un tipo unión a partir de un array as const

Un patrón frecuente es guardar los valores permitidos en un array, que puedes recorrer en tiempo de ejecución, y derivar de él el tipo unión. (typeof arr)[number] significa «el tipo de cualquier 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
}

Sin as const, ROLES sería string[] y Role sería simplemente string. El cast a readonly string[] en isRole hace falta porque includes sobre una tupla de literales solo acepta esos literales, y lo que quiere la función es comprobar un string que podría no ser uno de ellos. El mismo patrón con objetos funciona para mapas de clave y valor: const Status = { Active: "active", Banned: "banned" } as const, y después type Status = (typeof Status)[keyof typeof Status].

Parámetros de tipo const

Una función genérica normalmente ensancha los literales que le pasas. Desde TypeScript 5.0 puedes marcar un parámetro de tipo como const, lo que hace que el compilador infiera el argumento como si llevara as const, sin pedirle a quien llama que lo escriba.

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

Es sobre todo una herramienta para autores de librerías: las definiciones de rutas, los builders y las funciones auxiliares de esquemas lo usan para que quien llama obtenga tipos precisos a partir de literales normales.

Los significados de const

La palabra clave const aparece en cuatro sitios distintos del código TypeScript:

Ninguno de ellos congela un objeto en tiempo de ejecución. const obj = { a: 1 } sigue permitiendo obj.a = 2; solo es un error reasignar obj en sí.