Alias de tipo en TypeScript: la palabra clave type con ejemplos

Un alias de tipo da nombre a un tipo. Escribes type Name = ..., y a partir de ahí Name se puede usar en cualquier sitio donde se espere un tipo. A diferencia de una interfaz, un alias puede nombrar cualquier tipo, no solo formas de objeto.

type UserId = string;                         // a primitive
type Point = { x: number; y: number };        // an object shape
type Status = "active" | "banned";            // a union of literals
type Pair = [string, number];                 // a tuple
type Formatter = (value: number) => string;   // a function

const id: UserId = "u_42";
const start: Point = { x: 0, y: 0 };
const current: Status = "active";
const entry: Pair = ["score", 90];
const money: Formatter = (v) => `$${v.toFixed(2)}`;

console.log(id, start, current, entry, money(3.5));
// u_42 { x: 0, y: 0 } active [ 'score', 90 ] $3.50

Los alias solo existen en tiempo de compilación. El JavaScript generado no contiene ninguna de estas líneas type.

Sintaxis

type Name = SomeType;
type Name<T> = SomeTypeUsing<T>;       // generic
export type Name = SomeType;           // exported from a module

Los nombres van en PascalCase por convención. El lado derecho es cualquier expresión de tipo, y un alias puede usar otros alias, incluido él mismo (ver los tipos recursivos más abajo). El alias está disponible en todo el ámbito donde se declara, incluso por encima de la línea de declaración, porque los tipos se comprueban en tiempo de compilación y no se ejecutan en orden como const o let.

Tipos objeto

Para una forma de objeto, un alias y una interfaz se escriben casi igual. El alias usa = y normalmente termina en punto y coma.

type User = {
  id: number;
  name: string;
  email?: string;           // optional
  readonly createdAt: string; // cannot be reassigned
};

type Admin = User & { permissions: string[] }; // extend with an intersection

const root: Admin = {
  id: 1,
  name: "root",
  createdAt: "2024-03-15",
  permissions: ["*"],
};

console.log(`${root.name} can do ${root.permissions.join(", ")}`); // root can do *

Un alias no puede usar extends; la intersección & cumple esa función. La comprobación de propiedades de más y las propiedades opcionales y readonly funcionan exactamente igual que en las interfaces. Cuál de los dos elegir para formas de objeto se explica en la página de interface frente a type.

Uniones, tuplas y funciones

Son los casos que solo un alias puede nombrar, y la razón principal de que exista type. Un alias de unión enumera las alternativas, un alias de tupla fija la longitud y los tipos de los elementos de un array, y un alias de función describe una firma.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

type Span = [start: number, end: number]; // labeled tuple elements

type Transform = (shape: Shape, factor: number) => Shape;

const scale: Transform = (shape, factor) =>
  shape.kind === "circle"
    ? { kind: "circle", radius: shape.radius * factor }
    : { kind: "rect", width: shape.width * factor, height: shape.height * factor };

const r: Span = [10, 20];
console.log(scale({ kind: "circle", radius: 2 }, 3)); // { kind: 'circle', radius: 6 }
console.log(r[1] - r[0]);                              // 10

En scale, los parámetros no necesitan anotaciones: el alias Transform aporta sus tipos. La sintaxis de las tuplas se explica en tuplas, y el estrechamiento de uniones en la página de tipos unión.

Alias de tipo genéricos

Los parámetros de tipo hacen que un alias funcione con muchos tipos. Pueden tener valores por defecto, igual que los parámetros de una función.

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0
    ? { ok: true, value: n }
    : { ok: false, error: `not an age: ${text}` };
}

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? `age ${r.value}` : r.error);
}
// age 36
// not an age: abc

Result<number> usa el valor por defecto E = string. Los alias genéricos pequeños como type Nullable<T> = T | null o type Dict<T> = Record<string, T> son habituales en código real. Los utility types integrados (Partial<T>, Pick<T, K>, ReturnType<F>) también son alias genéricos, declarados en la librería estándar.

Los alias son nombres, no tipos nuevos

Un alias no crea un tipo distinto. Es un segundo nombre para el tipo de la derecha, y el compilador trata los dos como idénticos. Dos alias de string son totalmente intercambiables:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: UserId and OrderId are both just string

Esto imprime cancelling u_42 sin ningún error, que es justo el bug que un alias no puede evitar. El alias sigue ayudando a quien lee (un parámetro tipado OrderId dice más que string), pero si confundir dos ids tiene que ser un error de compilación, usa un branded type como string & { readonly __brand: "OrderId" }.

Alias de tipo recursivos

Un alias puede referirse a sí mismo, y así se describen árboles, listas anidadas y JSON:

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | { [key: string]: Json };

type TreeNode = {
  value: number;
  children: TreeNode[];
};

function sum(node: TreeNode): number {
  return node.value + node.children.reduce((total, child) => total + sum(child), 0);
}

const tree: TreeNode = {
  value: 1,
  children: [
    { value: 2, children: [] },
    { value: 3, children: [{ value: 4, children: [] }] },
  ],
};

const payload: Json = { ok: true, items: [1, "two", null], meta: { page: 1 } };

console.log(sum(tree));               // 10
console.log(JSON.stringify(payload)); // {"ok":true,"items":[1,"two",null],"meta":{"page":1}}

El alias Json rechaza los valores que JSON no puede representar: { when: new Date() } o { f: undefined } asignados a Json son errores de compilación (TS2322).

Tipos a partir de valores: typeof

Cuando un valor ya existe, puedes nombrar su tipo en lugar de escribirlo. El operador de tipo typeof lee el tipo de una variable, y se combina con otros operadores:

const defaults = { retries: 3, verbose: false, level: "info" };

type Options = typeof defaults;
// { retries: number; verbose: boolean; level: string }

type OptionKey = keyof typeof defaults;
// "retries" | "verbose" | "level"

function start(port: number) {
  return { port, startedAt: new Date() };
}
type Server = ReturnType<typeof start>;
// { port: number; startedAt: Date }

El valor sigue siendo la única fuente de verdad: añade una propiedad a defaults y Options la sigue. Hay más sobre esto en typeof.

Exportar e importar alias

Los alias se exportan e importan igual que los valores. import type deja claro que solo se importa un tipo, así que el import siempre se elimina de la salida en JavaScript:

// shapes.ts
export type Point = { x: number; y: number };
export type Shape = { kind: "circle"; center: Point; radius: number };

// main.ts
import type { Point, Shape } from "./shapes.js";

const p: Point = { x: 1, y: 2 };