Mensajes de error en DSL a nivel de tipos
Muestre errores de compilación útiles a los usuarios del DSL.
Mensajes de error en DSL a nivel de tipos es una lección gratuita de TypeScript Academy en CoddyKit. Esta es la lección 4 de 4. 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 4 lecciones en total.
Errores útiles en DSL a nivel de tipos
La parte más difícil de un DSL a nivel de tipos es conseguir que los fallos sean legibles. Los errores sin formato con never o «no se puede asignar» confunden a los usuarios. Mostramos errores descriptivos mediante tipos de error con marca y mensajes personalizados basados en never.
El problema de never
Cuando la validación falla al resolverse en never, el compilador indica «el argumento de tipo X no se puede asignar a never», lo que no explica al usuario por qué. Podemos hacerlo mejor.
Tipos de error con marca
En lugar de devolver un never simple, devuelva un tipo de error con una forma única que contenga una cadena de mensaje legible para las personas en su tipo.
type TypeError<Msg extends string> = {
readonly __error: Msg;
};
type E = TypeError<"Column 'foo' does not exist">;Devolver errores desde la validación
Un validador devuelve el tipo del valor válido o un error con marca que describe el problema. La comprobación «tiene un punto» es un patrón de literal de plantilla (con backticks en el código real); aquí la representamos como HasDot.
// HasDot<S> is the backtick pattern: any text, ".", any text.
type Validate<S extends string> =
S extends HasDot
? S
: TypeError<"Path must contain a dot, e.g. user.name">;Hacer que el error se muestre
Restrinja el parámetro para que pasar cualquier valor que no se pueda asignar a la marca de error muestre el mensaje. El tipo de error aparece directamente en la salida del compilador.
declare function path<S extends string>(
p: Validate<S> extends TypeError<infer M> ? TypeError<M> : S
): void;
path("oops");
// Error message includes: __error: "Path must contain a dot..."Distinguir varios errores
Los distintos fallos devuelven mensajes diferentes, de modo que los usuarios reciben indicaciones específicas en lugar de un único rechazo genérico. HasDot vuelve a ser el patrón de literal de plantilla con backticks para «contiene un punto».
type Check<S extends string> =
S extends "" ? TypeError<"Path cannot be empty">
: S extends HasDot ? S
: TypeError<"Missing dot separator">;never con un giro
Otra técnica combina una posición de valor con un mensaje literal para que este se muestre al pasar el cursor. Se intersecta el tipo problemático con un objeto etiquetado.
type Invalid<M extends string> = { error: M } & never;
// using never keeps it unassignable while the label hints the causeErrores en DSL fluidos
En un DSL encadenado, haga que el siguiente paso no válido devuelva un tipo con marca de error en lugar de una etapa válida, para que el editor muestre el mensaje justo donde se produce el error.
interface Stage {
// calling done() before where() yields a labeled error
done(): TypeError<"Call .where() before .done()">;
}Mantener los mensajes breves
Los tipos de mensaje largos aumentan la salida del compilador y ralentizan las herramientas. Prefiera frases concisas y prácticas. Incluya el token problemático cuando sea sencillo, pero evite interpolaciones enormes.
Probar los errores
Escriba pruebas a nivel de tipos que comprueben que la marca de error aparece para entradas que se sabe que son incorrectas, de modo que las refactorizaciones no deterioren silenciosamente la experiencia del desarrollador.
type Expect<T extends true> = T;
type _t = Expect<Validate<"oops"> extends TypeError<any> ? true : false>;Por qué es importante
Un DSL solo es tan bueno como sus errores. Los tipos de error con marca convierten los fallos crípticos de never en mensajes que se explican por sí mismos, lo que mejora enormemente la experiencia de uso de su API a nivel de tipos.
Comprobación rápida
Confirme su comprensión de los mensajes de error a nivel de tipos.
Resumen
Para que los DSL a nivel de tipos sean fáciles de usar, sustituya el never simple por tipos de error con marca que incorporen mensajes legibles. Los validadores devuelven el tipo válido o una marca de error específica; restringir los parámetros muestra el mensaje en la salida del compilador. Mantenga los mensajes breves y pruébelos.
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 «Mensajes de error en DSL a nivel de tipos» es gratis?
Sí — el texto completo de «Mensajes de error en DSL a nivel de tipos» 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 4 lecciones en total.
¿Qué aprenderé en «Mensajes de error en DSL a nivel de tipos»?
Muestre errores de compilación útiles a los usuarios del DSL. 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 4 de 4.
¿Cuánto tiempo toma la lección «Mensajes de error en DSL a nivel de tipos»?
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
- Qué es un DSL a nivel de tipos
- Diseño de un DSL fluido de consultas
- Validación de entradas en tiempo de compilación
- Mensajes de error en DSL a nivel de tipos