TypeScript
Síntesis del modelo mental de TypeScript: valores y tipos, inferencia, narrowing, contratos, generics, emisión, runtime y límites del sistema.
TypeScript es una capa de análisis sobre JavaScript. Observa valores, expresiones y flujo para comprobar contratos antes de que el programa se ejecute.
código TypeScript
↓ parsear
programa y símbolos
↓ comprobar
relaciones de tipos
↓ emitir o no emitir
JavaScript + declarations
↓ ejecutar
runtime de JavaScriptconst product = {
id: "p1",
price: 100,
};En runtime siguen existiendo:
TypeScript describe cómo esperas utilizarlos.
type Status = "idle" | "loading" | "success";Un tipo representa qué valores son posibles y qué operaciones son seguras.
string | numberpermite cualquiera de ambos, pero antes del narrowing solo puedes usar miembros comunes.
type Named = {
name: string;
};
const developer = {
name: "Nicolás",
role: "frontend",
};
const named: Named = developer;La compatibilidad depende de la forma, no del nombre del tipo.
Clases con private/protected, unique symbols y brands pueden introducir relaciones más nominales.
const price = 100;TypeScript infiere number. No necesitas escribir:
const price: number = 100;Anota cuando proteges una frontera, API pública o intención que la inferencia no expresa.
let status = "idle";Puede ampliarse a string porque el binding es mutable.
const status = "idle";Conserva el literal.
as const, satisfies y const type parameters controlan precisión bajo contratos distintos.
any → deja de comprobar
unknown → obliga a demostrarUna frontera externa debería comenzar normalmente como unknown.
const value: unknown = await response.json();
const product = parseProduct(value);Product | undefinedcomunica ausencia posible. strictNullChecks, optional properties y flags exactos hacen visible dónde puede faltar un valor.
! no valida; solo silencia al checker.
type Loader = (
id: ProductId,
) => Promise<Product>;Los callbacks reciben contextual typing. Overloads, unions y generics resuelven relaciones diferentes.
Una firma no cambia el comportamiento runtime de arrows, methods o this.
if (typeof value === "string") {
value.toUpperCase();
}TypeScript sigue condiciones, retornos, throws y asignaciones.
Type guards personalizados y assertion functions son promesas del autor: pueden mentir si la lógica no comprueba suficiente.
type RequestState<T> =
| { status: "loading" }
| { status: "success"; data: T }
| { status: "error"; error: Error };Cada estado contiene solo sus datos válidos. never permite exhaustividad.
type → cualquier tipo, composición cerrada
interface → formas abiertas y declaration mergingAmbos describen objetos estructuralmente. Interfaces pueden contener métodos e implementarse mediante clases u objetos.
function first<T>(values: readonly T[]): T | undefined;T conecta entrada y salida. No significa “cualquier cosa” ni valida runtime.
Constraints limitan capacidades; defaults e inferencia determinan type arguments.
keyof T
T[K]
typeof valueEvitan duplicar nombres y mantienen relaciones entre claves y valores.
type ReadonlyVersion<T> = {
readonly [K in keyof T]: T[K];
};type Element<T> =
T extends readonly (infer TItem)[]
? TItem
: never;Son programación estática. No recorren objetos ni validan strings durante ejecución.
type ToArray<T> = T extends unknown ? T[] : never;Sobre A | B produce A[] | B[]. Encerrar T en tuples permite tratar la union completa.
La complejidad type-level también consume tiempo del checker.
Partial<T>
Readonly<T>
Pick<T, K>
Omit<T, K>No crean defaults, no congelan objetos y no eliminan propiedades runtime al serializar.
type Instance = ProductService;
type Constructor = typeof ProductService;TypeScript añade private/protected, abstract, implements, override y parameter properties.
#private pertenece a JavaScript; private de TypeScript es principalmente estático.
import type { Product } from "./product.js";
import { createProduct } from "./product.js";El primer import desaparece. El segundo debe existir en runtime.
verbatimModuleSyntax vuelve explícita esa intención.
NodeNext → reglas modernas de Node
Bundler → resolvedor del bundlerpaths solo informa al checker; no configura automáticamente el runtime.
export function createClient(
options: ClientOptions,
): Client;No crea la función. Las declarations deben coincidir con el JavaScript publicado.
Ambient declarations, global augmentation y module augmentation también pueden mentir si el runtime no ofrece la capacidad.
No todas las construcciones de TypeScript se borran igual.
moderno → value + context
legacy → experimentalDecorators + firmas antiguasParameter decorators y emitDecoratorMetadata pertenecen al modelo legacy.
implicit any
nullability
function variance
class initialization
index access
optional propertiesActivar un flag y responder con assertions no crea seguridad. La migración necesita contratos y validación reales.
// @ts-expect-error invalid price
createProduct({ name: "Keyboard", price: "100" });También prueba usos válidos, inferencia y el package construido.
Runtime tests y type tests responden preguntas diferentes.
export interface Client {
request<T>(
input: RequestInput,
parser: Parser<T>,
): Promise<T>;
}Oculta implementation details, conserva inferencia y obliga a validar entradas externas mediante un parser.
editor
compiler
linter
transpiler
bundler
test runnerDeben coincidir en versión, módulos y decorators. Un transpiler puede eliminar syntax sin comprobar tipos.
keyof T?.d.ts?Notas de nivel Esencial en orden.
Notas Aplicado con ejemplos propios y un proyecto pequeño.
Notas Avanzado cuando diseñes librerías, tooling o APIs genéricas complejas.
unknown en un modelo validado..d.ts y exports.@ts-check y JSDoc.Para cualquier tipo o herramienta, pregunta:
¿Qué valores representa?
¿Qué relación conserva?
¿Qué operación permite?
¿Qué se borra o emite?
¿Qué puede ocurrir en runtime?
¿Qué debe validar una frontera?
¿Qué verá quien consume la API?
¿Qué costo añade al checker?Cuando un error de TypeScript parezca extraño, vuelve a estas preguntas:
¿Qué tipo fue inferido?
¿Se amplió un literal?
¿Qué variantes siguen posibles?
¿Qué constraint limita el generic?
¿La clave está relacionada con el valor?
¿Estoy en type space o value space?
¿La construcción existe en runtime?
¿El module resolver imita al host?
¿Una declaration está prometiendo algo inexistente?
¿Estoy arreglando el contrato o silenciando el checker?Responderlas convierte TypeScript en un sistema de relaciones comprensible, no en una lista de errores que se resuelven con as.