TypeScript y el error que aparece según cómo escribes el código, no según los datos
Hay comportamientos en TypeScript que parecen magia negra la primera vez que los ves. Mismo objeto, misma función, mismo tipo declarado — y aun así, una versión del código lanza un error y la otra no. Si alguna vez te pasó esto y no entendiste por qué, este artículo es para ti.
Google for Developers planteó este escenario como un desafío para desarrolladores: dos programadores usan la misma función con datos idénticos para registrar nuevos usuarios, y solo uno de los dos obtiene un error de TypeScript. La pregunta es cuál y, más importante, por qué. La respuesta revela uno de los comportamientos más malentendidos del lenguaje.
En este artículo vamos a desmenuzar qué es el excess property checking, cuándo se activa, cuándo no, y por qué entender esto marca una diferencia real en la calidad de tu código TypeScript.
El comportamiento que sorprende a casi todos
Imagina que tienes un tipo User con propiedades básicas como name y email, y una función sendWelcomeEmail(user: User). Ahora tienes dos formas de llamarla:
La primera opción es pasar el objeto directamente como argumento literal: sendWelcomeEmail({ name: "Alice", email: "alice@email.com", role: "admin" }). La segunda es primero asignar ese objeto a una variable y luego pasarla: const userData = { name: "Bob", email: "bob@email.com", role: "admin" }; sendWelcomeEmail(userData).
Si el tipo User no incluye la propiedad role, TypeScript lanzará un error en el primer caso pero no en el segundo. Mismo objeto. Misma propiedad extra. Resultado diferente.
¿Por qué ocurre esto? El excess property checking explicado
TypeScript tiene dos modos de verificar tipos que muchos devs no distinguen con claridad. El primero es el chequeo estructural estándar: TypeScript verifica que el objeto tenga todas las propiedades requeridas. Si las tiene, el tipo es compatible, aunque tenga propiedades adicionales. Esto es lo que ocurre cuando pasas una variable. 🔍
El segundo modo es el excess property checking, que solo se activa cuando pasas un object literal directamente a una función o lo asignas directamente a una variable con tipo anotado. En ese caso, TypeScript se pone estricto: no solo verifica que las propiedades requeridas estén presentes, sino que también detecta propiedades adicionales que el tipo no contempla y las marca como error.
La lógica detrás de esto es práctica: si estás escribiendo un objeto literal en el momento, probablemente cometiste un error tipográfico o estás pasando datos que no corresponden. En cambio, si ya tienes una variable con ese objeto, TypeScript asume que fue creada con intención y solo verifica compatibilidad estructural.
¿Por qué esto importa en proyectos reales?
Este comportamiento no es un bug — es una decisión de diseño deliberada. Pero tiene consecuencias directas en cómo escribes y revisas tu código, especialmente en proyectos medianos y grandes donde múltiples desarrolladores trabajan sobre los mismos tipos.
En contextos de desarrollo empresarial con TypeScript — ya sea en aplicaciones .NET con frontend en TypeScript, APIs REST tipadas, o aplicaciones Flutter con backends TypeScript — este tipo de detalle aparece frecuentemente cuando se integran datos de fuentes externas, formularios, o respuestas de APIs. Un objeto que viene de una respuesta HTTP puede tener propiedades extra que tu tipo no contempla, y dependiendo de cómo lo pases, TypeScript puede o no advertirte sobre eso. 💡
El riesgo real no es el error en sí — ese es fácil de corregir. El riesgo es cuando TypeScript no lanza el error porque pasaste una variable, y esas propiedades extra llegan silenciosamente a capas de tu aplicación donde no deberían estar.
¿Cómo aplica esto en tu empresa?
Si tu equipo trabaja con TypeScript en proyectos de software empresarial, hay tres acciones concretas que puedes tomar hoy:
- Activa
strict: trueen tu tsconfig.json si aún no lo has hecho. Esto no resuelve el excess property checking directamente, pero activa un conjunto de verificaciones que reducen este tipo de sorpresas. - Usa tipos explícitos en tus variables intermedias: en lugar de
const userData = {...}, escribeconst userData: User = {...}. Así TypeScript aplica el excess property checking también en la asignación. - Valida los datos externos antes de tipearlos: cuando recibes datos de una API o base de datos, usa librerías de validación como Zod o io-ts para asegurarte de que el shape del objeto sea exactamente el que esperas, no solo estructuralmente compatible.
Estos ajustes son pequeños, pero en un equipo de desarrollo que mantiene un sistema ERP personalizado, una API de negocio o una app móvil con TypeScript, reducen significativamente el tiempo perdido debuggeando errores que TypeScript podría haber detectado antes.
Conclusión
TypeScript es una herramienta poderosa, pero su valor real aparece cuando el equipo entiende sus reglas — incluyendo las que parecen inconsistentes a primera vista. El excess property checking es uno de esos casos donde el lenguaje te protege, pero solo si sabes cuándo y cómo se activa.
La diferencia entre un developer que "usa TypeScript" y uno que lo domina está precisamente en estos detalles: los que no aparecen en los tutoriales básicos pero sí aparecen en producción.
En Consultoría-Ti trabajamos con TypeScript en proyectos reales de desarrollo empresarial — desde APIs REST hasta integraciones con Odoo y aplicaciones móviles con Flutter. Si tu equipo está escalando un proyecto y quiere asegurarse de estar usando el lenguaje de manera robusta, con gusto conversamos.
¿Tienes un proyecto en TypeScript y quieres una revisión técnica? Escríbenos y lo evaluamos juntos.
Fuentes y Referencias
Google for Developers — TypeScript User Challenge (YouTube Short)
✨ Contenido generado con ContentFlow — Consultoría-Ti