TypeScript Academy · Lección

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.

Lección 1 de 38 pasos

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 match

Ayudante 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 UserId

Marca 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 factories

Factorí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 first

Consejos 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.

Gratis para empezar

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

  1. Tipos branded/opacos para evitar confusiones entre unidades
  2. IDs etiquetados y patrones de modelado de dominio
  3. Modelado de dominio: agregados, invariantes y servicios
← Volver a TypeScript Academy