Tipos branded: distinguir un string de un email verificado

Hay una clase de bug que ningún modelado de casos evita, porque no nace de un estado imposible sino de una confusión entre valores que el compilador considera idénticos. Pasas el identificador del pedido donde se esperaba el del usuario y compila; guardas en el estado una cadena que el usuario acaba de teclear en un campo llamado correo y todo el código que la consume asume, sin ninguna base, que es un correo válido; insertas en el DOM un texto que creías saneado y resulta que la función de saneamiento se aplicaba en otra rama. Los tres accidentes comparten causa: TypeScript compara tipos por su estructura, y bajo ese criterio un identificador, un correo verificado y un fragmento de HTML seguro son exactamente lo mismo, una secuencia de caracteres. Esta lección enseña a introducir en el sistema de tipos la distinción que la estructura no puede ver, y a colocar esa distinción donde importa: en la frontera entre el dato que alguien afirmó y el dato que alguien comprobó.

Por qué el compilador no distingue lo que tú distingues

TypeScript adopta tipificación estructural: dos tipos son compatibles si su forma lo es, sin importar cómo se llamen ni de dónde vengan. Es una decisión deliberada y acertada para un lenguaje que describe JavaScript, donde los objetos se crean sobre la marcha y nadie declara pertenencias.

El efecto colateral aparece en cuanto usas alias. Declarar type UsuarioId = string y type PedidoId = string no crea dos tipos: crea dos nombres para el mismo tipo, y por tanto una función que recibe uno acepta el otro sin una sola queja.

type UsuarioId = string;
type PedidoId = string;

function cancelar(pedido: PedidoId) { /* ... */ }

const usuario: UsuarioId = "u_42";
cancelar(usuario); // compila: para el compilador ambos son string

El alias documenta la intención y no la defiende, que es la peor combinación posible: da la sensación de seguridad sin la seguridad, y esa sensación es la que hace que nadie revise esa línea en el pull request.

El caso de los identificadores es el más citado y no es el más grave. El grave es el de los valores que han pasado por una comprobación, porque ahí la información que se pierde no es de qué entidad viene el dato, sino si ya se hizo un trabajo sobre él.

Una cadena que salió de un formulario y una cadena que superó una validación de correo son ambas string, así que el tipo no puede recordar la diferencia y el recuerdo se traslada a la memoria del equipo. En consecuencia, cada consumidor toma una de dos decisiones malas: o vuelve a validar por si acaso, y la validación se dispersa y se desincroniza, o confía sin base, y ese consumidor será el que falle.

Ese es el punto conceptual de la lección, y conviene enunciarlo antes de ver la sintaxis. Una validación es trabajo hecho, y el trabajo hecho debe quedar registrado en el tipo del resultado; si no lo queda, se pierde en cuanto el valor cruza una función y alguien tendrá que rehacerlo o suponerlo.

La marca fantasma

La técnica consiste en intersectar el tipo base con un objeto que declara una propiedad que ningún valor real tendrá jamás, y que sirve únicamente para que la comparación estructural falle.

declare const marca: unique symbol;

type Marcado<T, Nombre extends string> = T & {
  readonly [marca]: Nombre;
};

type UsuarioId = Marcado<string, "UsuarioId">;
type PedidoId = Marcado<string, "PedidoId">;
type Email = Marcado<string, "Email">;

Lee con cuidado la primera línea, porque es la que hace el truco honesto. La palabra declare afirma la existencia del símbolo ante el compilador sin generar ninguna línea de JavaScript, de modo que la marca no existe en ejecución: un UsuarioId es, en tiempo de ejecución, una cadena y nada más, sin envoltorio, sin coste de memoria y sin sorpresas al serializar.

Que el símbolo sea unique y esté fuera del alcance de otros módulos impide además que alguien fabrique la propiedad por su cuenta. Y como la marca lleva un nombre distinto en cada tipo, UsuarioId y PedidoId tampoco son compatibles entre sí, que era el otro accidente que queríamos cerrar.

La consecuencia es asimétrica y esa asimetría es exactamente la deseada. Un Email se puede usar en cualquier sitio donde se espere un string, porque lo es y todas las operaciones de cadena siguen funcionando sobre él.

Pero un string cualquiera no se puede usar donde se espera un Email, porque le falta la marca y no hay manera legítima de inventarla. La marca funciona, en la práctica, como una firma que solo puede estampar quien tiene la validación.

El constructor inteligente

La marca por sí sola no garantiza nada; garantiza quien controla cómo se obtiene. El patrón se llama constructor inteligente y consiste en exportar el tipo pero no la forma de crearlo, dejando una única función que valida y, solo si la validación pasa, devuelve el valor marcado.

const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

export type Email = Marcado<string, "Email">;

export function crearEmail(bruto: string): Email | null {
  const limpio = bruto.trim().toLowerCase();
  return EMAIL.test(limpio) ? (limpio as Email) : null;
}

export function enviarBienvenida(destino: Email) {
  // aquí no se valida nada: el tipo ya lo prueba
}

Hay una única conversión forzada en todo el diseño, dentro del constructor, y ese es el punto: la técnica no elimina la aserción de tipo, la concentra en una línea auditable en lugar de dispersarla por todo el código.

Fíjate también en que el constructor no solo comprueba, también normaliza: recorta espacios y baja a minúsculas antes de marcar. Así la marca no significa únicamente que el valor es válido, sino que está en forma canónica, y todas las comparaciones posteriores dejan de necesitar normalización previa.

El efecto sobre el resto del programa es el que perseguíamos desde la primera línea de la lección. La función que envía el correo de bienvenida ya no comprueba nada, y no por descuido, sino porque su firma exige una prueba de que la comprobación ocurrió antes.

Esa transformación tiene un nombre reconocible: en lugar de validar —comprobar y devolver un booleano que se olvida en cuanto acaba el if— se analiza, que es comprobar y devolver un valor cuyo tipo recuerda el resultado. La diferencia entre las dos es que la primera reparte la responsabilidad entre todos los consumidores y la segunda la retiene en un punto.

flowchart LR
B[string bruto sin garantias] --> C[crearEmail valida y normaliza]
C -- no cumple --> N[null y el error se trata aqui]
C -- cumple --> E[Email marcado]
E --> U[funciones que ya no comprueban]
style B fill:#f38ba8,color:#11111b
style C fill:#cba6f7,color:#11111b
style E fill:#a6e3a1,color:#11111b
style U fill:#89b4fa,color:#11111b

Conviene además hacer explícito el resultado del fallo. Devolver null sirve para casos simples, pero en un formulario querrás saber por qué falló, y ahí el constructor devuelve una unión discriminada como las de la primera lección, con un miembro de éxito que lleva el valor marcado y otro de error que lleva el motivo.

Las dos técnicas del nivel encajan de forma natural: la unión modela el resultado de la comprobación y la marca viaja dentro del miembro que triunfó.

Qué marcar, qué no, y qué se paga

La técnica es barata pero no gratuita, y aplicarla a todo produce código ceremonioso que la gente acaba esquivando. Los tres tipos de valor que la merecen casi siempre son reconocibles.

El primero, los identificadores de entidades distintas que comparten representación, porque confundirlos produce fallos silenciosos que llegan hasta la base de datos. El segundo, los valores que han superado una comprobación cara o crítica: correo verificado, HTML saneado, ruta normalizada, token con firma comprobada. El tercero, las magnitudes con unidad, donde sumar milisegundos con segundos o céntimos con euros es un error de dominio que el tipo number no ve.

Los costes también conviene nombrarlos sin adornos. El primero es que los límites del sistema no conocen la marca: lo que llega de una API o del localStorage es texto sin marcar y hay que hacerlo pasar por el constructor, que es precisamente el trabajo de la lección siguiente.

El segundo es que las operaciones que producen un valor nuevo pierden la marca, y con razón: concatenar dos Email no produce un Email, así que el resultado vuelve a ser string y debe repasar el constructor si quiere recuperar la marca. El tercero es cultural: la marca solo garantiza mientras nadie use una conversión forzada para saltársela, y por eso el constructor debe ser la única salida pública del módulo y las conversiones deben quedar prohibidas fuera de él.