Tipos branded/opacos para evitar confusiones entre unidades
Evite confusiones entre unidades o etiquetas intersectando tipos base con propiedades de marca fantasma; construya valores únicamente mediante funciones de fábrica.
Tipos branded/opacos para evitar confusiones entre unidades es una lección gratuita de TypeScript Academy en CoddyKit. Esta es la lección 1 de 3. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de TypeScript Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de TypeScript Academy incluye 3 lecciones en total.
Introducción
Objetivo: Separe valores parecidos en el nivel de tipos. Un number simple no puede distinguir metros de segundos; un marcador de marca sí puede hacerlo.
- Sin sobrecoste en tiempo de ejecución
- API y refactorizaciones más seguras
- Creación únicamente mediante fábricas
Marcar unidades primitivas
Los marcadores de marca mantienen separadas las unidades durante la compilación; el orden incorrecto de los argumentos falla en la comprobación de tipos.
type Meter = number & { readonly __brand: "meter" }
type Second = number & { readonly __brand: "second" }
function meter(n: number): Meter { return n as Meter }
function second(n: number): Second { return n as Second }
const d = meter(100)
const t = second(9)
function speed(dist: Meter, time: Second) { return (dist as number) / (time as number) }
// speed(t, d) // compile error: brands do not matchAyudante genérico de marcas
Utilice un ayudante genérico Brand en distintos dominios: IDs tipados, tokens, cursores, etc.
type Brand<Tag extends string, T> = T & { readonly __brand: Tag }
type UserId = Brand<"UserId", string>
type OrderId = Brand<"OrderId", string>
function userId(x: string): UserId { return x as UserId }
function orderId(x: string): OrderId { return x as OrderId }
function findUser(id: UserId) { /* ... */ }
const u = userId("u_123")
const o = orderId("o_456")
// findUser(o) // error: OrderId not assignable to UserIdMarca con unique symbol
La marca unique symbol evita las colisiones de nombres y que estos se filtren al espacio de nombres global.
declare const MeterSym: unique symbol
type Meter2 = number & { readonly [MeterSym]: "meter" }
function asMeter2(n: number): Meter2 { return n as Meter2 }
const m2 = asMeter2(5)
// const wrong: Meter2 = 5 // discourage raw assignment; prefer factoriesFactorías y validación
Proporcione la marca dentro de una factory: valide primero, marque después y utilice el valor al final. Evite usar as de forma improvisada en los puntos de llamada.
type NonEmptyString = string & { readonly __brand: "NonEmpty" }
function nonEmpty(s: string): NonEmptyString | null {
return s.trim().length > 0 ? (s as NonEmptyString) : null
}
function makeSlug(s: NonEmptyString) {
return (s as string).toLowerCase().replace(/\s+/g, "-")
}
const ok = nonEmpty(" Hello ")
if (ok) { makeSlug(ok) } // safe: validated & branded firstConsejos y aspectos importantes
Buenas prácticas:
- Mantenga los nombres de las marcas cortos y significativos.
- Exponga las factorías como la única forma de obtener valores con marca.
- No exponga las marcas en los tipos de la API pública salvo que sea necesario.
- Las marcas solo existen en el nivel de tipos: no añaden sobrecarga en tiempo de ejecución.
Comprobación de marcas
Comprobación rápida: ¿qué patrón evita confundir unidades o etiquetas?
Resumen
Resumen: Los tipos con marca u opacos separan valores parecidos (metros frente a segundos, UserId frente a OrderId). Créelos mediante factorías, utilícelos en las API y elimine las confusiones accidentales.
Aprende TypeScript con un tutor de IA — gratis
Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.
- Cursos
- 101
- Lecciones
- 352
Preguntas frecuentes
¿La lección «Tipos branded/opacos para evitar confusiones entre unidades» es gratis?
Sí — el texto completo de «Tipos branded/opacos para evitar confusiones entre unidades» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de TypeScript Academy, actualiza a CoddyKit PRO. El curso de TypeScript Academy incluye 3 lecciones en total.
¿Qué aprenderé en «Tipos branded/opacos para evitar confusiones entre unidades»?
Evite confusiones entre unidades o etiquetas intersectando tipos base con propiedades de marca fantasma; construya valores únicamente mediante funciones de fábrica. Practicas TypeScript Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar TypeScript Academy?
No se requiere experiencia previa. TypeScript Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 3.
¿Cuánto tiempo toma la lección «Tipos branded/opacos para evitar confusiones entre unidades»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de TypeScript Academy?
Sí. Cada lección de TypeScript Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Tipos branded/opacos para evitar confusiones entre unidades
- IDs etiquetados y patrones de modelado de dominio
- Modelado de dominio: agregados, invariantes y servicios