Buenas prácticas de TypeScript: 8 reglas con antes y después

Las reglas de abajo son las que evitan más bugs en código TypeScript real. Cada una muestra primero la versión habitual y después la mejor, en código que puedes ejecutar. La primera regla es la más importante: deja de usar any.

Usa unknown en lugar de any

any desactiva la comprobación de tipos de un valor y de todo lo que se calcula a partir de él. unknown también acepta cualquier valor, pero tienes que comprobarlo antes de usarlo, lo que sitúa la comprobación donde los datos entran en tu programa:

// Before: any switches off checking for everything it touches.
function totalAny(items: any): number {
  return items.reduce((sum: number, item: any) => sum + item.price, 0);
}
console.log(totalAny([{ price: 2 }, { cost: 3 }])); // NaN, no error anywhere

// After: take unknown, check once at the boundary, then work with real types.
interface Item {
  price: number;
}

function isItems(value: unknown): value is Item[] {
  return Array.isArray(value) && value.every((i) => typeof i?.price === "number");
}

function total(input: unknown): number {
  if (!isItems(input)) throw new Error("Expected a list of items with prices");
  return input.reduce((sum, item) => sum + item.price, 0);
}

console.log(total([{ price: 2 }, { price: 3 }])); // 5
try {
  total([{ price: 2 }, { cost: 3 }]);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Expected a list of items with prices
}

Las fronteras son los lugares donde los tipos dejan de estar garantizados: JSON.parse, las respuestas de fetch, localStorage, los datos de formularios, las variables de entorno y los mensajes de otros procesos. Valida ahí con un type guard o una librería de esquemas, y el resto del código podrá fiarse de sus tipos.

Mantén strict activado

strict es el valor por defecto en TypeScript 7; no lo desactives. Añade las comprobaciones que deja fuera y que detectan más bugs:

{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noImplicitOverride": true,
        "noFallthroughCasesInSwitch": true
    }
}

noUncheckedIndexedAccess hace que arr[i] y record[key] incluyan undefined, que es lo que devuelven para un índice que no existe. noImplicitOverride obliga a que un método de una subclase indique override, y noFallthroughCasesInSwitch rechaza un case que continúa en el siguiente.

Deja trabajar a la inferencia

Anota lo que TypeScript no puede saber: los parámetros de las funciones y los tipos de retorno de las funciones que usan otros módulos. Deja las variables locales y los parámetros de los callbacks a la inferencia. Una anotación innecesaria no es solo ruido; puede hacer que un tipo sea más amplio que el valor:

type Status = "active" | "banned";

function setStatus(status: Status): string {
  return `status set to ${status}`;
}

const annotated: string = "active"; // annotation widens the type to string
// @ts-expect-error string is not assignable to Status
setStatus(annotated);

const inferred = "active"; // inferred as the literal type "active"
console.log(setStatus(inferred)); // status set to active

const users = [{ id: 1, name: "Ada" }, { id: 2, name: "Lin" }];
const ids = users.map((u) => u.id); // inferred: number[]
console.log(ids); // [ 1, 2 ]

Sin el comentario @ts-expect-error, setStatus(annotated) es el error TS2345. La const inferida conserva el tipo literal "active", así que se acepta. Pasa el cursor por una variable en tu editor para ver qué se infirió antes de añadir un tipo.

Prefiere los tipos unión a los enums

Una unión de literales de string da autocompletado y comprobaciones exhaustivas sin código generado. Cuando también necesitas la lista de valores en tiempo de ejecución, deriva el tipo de un array as const:

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function canEdit(role: Role): boolean {
  return role !== "viewer";
}

console.log(canEdit("editor"));     // true
console.log(ROLES.filter(canEdit)); // [ 'admin', 'editor' ]

canEdit("owner"); // error TS2345: Argument of type '"owner"' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

Un enum Role { Admin, Viewer } compila a un objeto con mapeo inverso, y un parámetro de enum numérico acepta cualquier variable number, incluso una con un valor que el enum no incluye. Los enums tampoco funcionan con el type stripping de Node (TypeScript enum is not supported in strip-only mode). Las ventajas e inconvenientes se comparan en la página de enums.

Comprueba los objetos de configuración con satisfies

Anotar un objeto con un tipo amplio como Record<string, Route> comprueba sus valores pero olvida sus claves. satisfies comprueba lo mismo y conserva el tipo exacto:

interface Route {
  path: string;
  auth: boolean;
}

// Annotated: every string key is allowed, so typos are not caught.
const loose: Record<string, Route> = {
  home: { path: "/", auth: false },
};
console.log(loose.hmoe); // undefined, and no compile error

// satisfies: checked against Route, but the exact keys are kept.
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;

console.log(routes.admin.path); // /admin
// @ts-expect-error Property 'hmoe' does not exist
routes.hmoe;

Usa una anotación cuando la variable deba tener exactamente el tipo declarado (un parámetro de función, un valor que vas a reasignar). Usa satisfies para tablas de búsqueda, mapas de rutas, tokens de tema y otros objetos constantes.

Modela el estado con uniones discriminadas

Un único objeto con campos opcionales permite estados que no pueden darse: loading: true junto con un error, o que falte data tras un éxito. Una unión de objetos con una etiqueta compartida solo permite los estados reales, y cada rama ve únicamente sus propios campos:

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; message: string };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", "); // data exists only here
    case "error":
      return `Error: ${state.message}`;
    default: {
      const unreachable: never = state; // fails if a case is missing
      return unreachable;
    }
  }
}

console.log(render({ status: "success", data: ["a", "b"] })); // a, b
console.log(render({ status: "error", message: "timeout" }));  // Error: timeout

La línea con never es la comprobación exhaustiva. Cuando alguien añade un estado y se olvida de manejarlo, la compilación falla en esa línea:

// This does not compile: a new state was added but not handled.
type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "cancelled" };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", ");
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
}

console.log(render({ status: "loading" }));

El error es index.ts(14,13): error TS2322: Type '{ status: "cancelled"; }' is not assignable to type 'never'. Nombra el caso sin manejar. Añade case "cancelled": y compila.

Evita ! y as

La aserción non-null x! y la aserción de tipo x as T le dicen al compilador que deje de comprobar. Ninguna cambia el valor en tiempo de ejecución, así que una aserción equivocada se convierte más tarde en un fallo, lejos de su causa:

interface User {
  name: string;
}

const users = new Map<string, User>([["ada", { name: "Ada" }]]);

// Before: ! and as silence the compiler, and the crash moves to run time.
try {
  console.log(users.get("bob")!.name);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Cannot read properties of undefined (reading 'name')
}
const fake = {} as User;
console.log(fake.name); // undefined, typed as string

// After: handle the missing case where it can happen.
const bob = users.get("bob");
console.log(bob?.name ?? "unknown user"); // unknown user

Sustituye ! por ?., ??, un return temprano o un error lanzado con un mensaje útil. Sustituye as por un type guard que compruebe de verdad el valor. La única aserción siempre segura es as const, porque solo hace un tipo más estrecho y de solo lectura. Una buena configuración de lint (las reglas no-non-null-assertion y no-explicit-any de typescript-eslint) marca el resto.

Haz los datos readonly

Marca como readonly las propiedades y los arrays que el código no debe cambiar. El compilador rechaza entonces push, sort y las asignaciones, y las funciones devuelven valores nuevos en lugar de modificar sus entradas:

interface Settings {
  readonly theme: "light" | "dark";
  readonly tags: readonly string[];
}

function withTag(settings: Settings, tag: string): Settings {
  // settings.tags.push(tag) would not compile
  return { ...settings, tags: [...settings.tags, tag] };
}

const before: Settings = { theme: "dark", tags: ["a"] };
const after = withTag(before, "b");
console.log(before.tags, after.tags); // [ 'a' ] [ 'a', 'b' ]

// @ts-expect-error Cannot assign to 'theme' because it is a read-only property.
before.theme = "light";

readonly solo se comprueba en tiempo de compilación y solo a un nivel de profundidad: no congela el objeto en tiempo de ejecución. Aun así basta para detectar la modificación accidental de estado compartido, que es lo que causa la mayoría de estos bugs.