TypeScript
Uso de branded y opaque types para distinguir valores estructuralmente iguales, representar identificadores y evitar mezclar dominios incompatibles.
TypeScript es estructural: dos aliases de siguen siendo compatibles. Un añade una marca estática para distinguir valores con la misma representación runtime.
stringdeclare const userIdBrand: unique symbol;
type UserId = string & {
readonly [userIdBrand]: "UserId";
};type UserId = string;
type ProductId = string;
function loadUser(userId: UserId) {}
const productId: ProductId = "p1";
loadUser(productId);Es válido porque ambos son string.
declare const productIdBrand: unique symbol;
type ProductId = string & {
readonly [productIdBrand]: true;
};Las propiedades no existen necesariamente en el valor runtime; son una marca en el sistema de tipos.
function parseUserId(value: unknown): UserId {
if (
typeof value !== "string" ||
!value.startsWith("usr_")
) {
throw new TypeError("Invalid user id");
}
return value as UserId;
}La assertion queda encapsulada después de validar la regla.
Peligroso:
const id = value as UserId;Cualquier string puede “convertirse” sin demostrar el formato.
Expón una función o schema que sea la única puerta de construcción.
const emailBrand: unique symbol = Symbol();
export type Email = string & {
readonly [emailBrand]: never;
};
export function parseEmail(value: unknown): Email {
// validar
return value as Email;
}Si el símbolo no se exporta, consumidores no pueden reproducir la propiedad fácilmente mediante acceso nominal, aunque todavía pueden forzar assertions porque TypeScript no es una frontera de seguridad.
Cuando necesitas comportamiento o invariantes persistentes, un wrapper real puede ser mejor.
class Email {
private constructor(
readonly value: string,
) {}
static parse(value: unknown): Email {
if (typeof value !== "string" || !value.includes("@")) {
throw new TypeError("Invalid email");
}
return new Email(value);
}
}Ahora existe identidad y validación runtime.
declare const centsBrand: unique symbol;
declare const percentageBrand: unique symbol;
type Cents = number & {
readonly [centsBrand]: "Cents";
};
type Percentage = number & {
readonly [percentageBrand]: "Percentage";
};Evita mezclar unidades accidentalmente.
type NonEmptyString = string & {
readonly __brand: "NonEmptyString";
};La marca representa una propiedad demostrada, no un nuevo valor runtime.
const serialized = JSON.stringify(userId);Se serializa como string porque el brand se borra. Al leer debes validar y reconstruir el tipo.
Un branded primitive puede perder precisión en ciertas operaciones:
const copied = `${userId}`;
// stringEl resultado es un string nuevo; ya no debe asumirse que conserva la validación exacta sin revisar la operación.
declare const brand: unique symbol;
type Brand<T, TName extends string> = T & {
readonly [brand]: TName;
};
type UserId = Brand<string, "UserId">;
type ProductId = Brand<string, "ProductId">;Un brand no impide que un atacante envíe otro ID. La autorización continúa en runtime y servidor.
type Cents = Brand<number, "Cents">;
function createCents(value: number): Cents {
if (!Number.isSafeInteger(value)) {
throw new TypeError("Cents must be a safe integer");
}
return value as Cents;
}
function addCents(first: Cents, second: Cents): Cents {
return createCents(first + second);
}as Brand en cualquier lugar.__brand público fácil de imitar sin necesidad.¿Por qué un UserId debe validarse nuevamente después de leerlo desde JSON?
Porque JSON solo contiene el string. La marca existe únicamente en el sistema de tipos y se elimina durante ejecución y serialización.
Generics inicia el bloque de tipos parametrizados y transformaciones.