JSDoc: obtenga sugerencias de tipo sin TypeScript

Al finalizar este tema

Aprenderá a agregar información de tipo a JavaScript mediante comentarios JSDoc. Entenderá que puede disfrutar de las sugerencias y la verificación de tipo en su editor sin adoptar TypeScript.

El problema: TypeScript es bueno, pero su adopción es compleja

TypeScript le ayuda a detectar errores de tipo de forma temprana. Es excelente. Sin embargo, para adoptar TypeScript en un proyecto de JavaScript existente, debe configurar tsconfig.json, modificar el proceso de compilación y cambiar las extensiones de archivo de .js a .ts. Aplicar esto de una sola vez en un proyecto heredado de 100 000 líneas es poco práctico.

JSDoc resuelve este problema. No es necesario cambiar la extensión del archivo ni modificar la configuración de compilación; solo debe agregar comentarios.

Conceptos básicos de JSDoc: agregue tipos a las funciones

/**
 * @param {string} name - Nombre del usuario
 * @param {number} age - Edad
 * @returns {string} Mensaje de saludo
 */
function greet(name, age) {
  return `${name} tiene ${age} años.`;
}

Si se escribe así, VS Code indicará que al llamar a greet, name debe ser una cadena y age debe ser un número. También aparecerá una línea roja, y mostrará una advertencia si se hace greet(123, "twenty").

Lo importante es esto: .js es un archivo que realiza la verificación de tipos, al igual que TypeScript. Dado que es un comentario, se ignora por completo en tiempo de ejecución.

Asignar tipos a objetos y arreglos

/**
 * @param {{ id: number, name: string }} user
 * @param {string[]} tags
 * @returns {boolean}
 */
function hasTag(user, tags) {
  return tags.includes(user.name);
}

Aquí se declara que user es un objeto que contiene id y name, y que tags es una matriz de cadenas. Al escribir user. en el editor, id y name se completan automáticamente.

Cuando se utilizan objetos complejos repetidamente, se puede asignar un nombre mediante @typedef:

/**
 * @typedef {Object} Product
 * @property {number} id
 * @property {string} name
 * @property {number} price
 */

/** @param {Product} item */
function formatPrice(item) {
  return `${item.name}: ${item.price} won`;
}

Una vez que se define el tipo Product, se puede hacer referencia a él en cualquier parte del proyecto mediante @param {Product}.

Úsalo directamente en VS Code

Si agregas una sola línea al inicio del archivo JS, el verificador de tipos de TypeScript inspeccionará ese archivo:

// @ts-check

Esto es todo. Sin necesidad de tsconfig.json ni de instalar TypeScript, el servidor de lenguaje TypeScript integrado en VS Code lee los comentarios JSDoc para realizar la verificación de tipos.

También puedes colocar @ts-check solo en un archivo, o configurar jsconfig.json con "checkJs": true para aplicarlo a todo el proyecto.

Enfoques utilizados en la práctica

Migración progresiva: Antes de adoptar TypeScript por completo, se utilizan comentarios JSDoc para tipificar los archivos clave. Incluso si luego se migra a TypeScript, la información de tipos ya definida en JSDoc facilita la conversión.

Distribución de bibliotecas: Muchos proyectos distribuyen paquetes npm en JavaScript, pero proporcionan información de tipos mediante JSDoc. Svelte es un ejemplo destacado; los usuarios pueden recibir autocompletado incluso sin tener el código fuente de TypeScript.

Elección de desarrolladores de JavaScript con 20 años de experiencia: Algunos prefieren simplemente añadir comentarios a JavaScript, que ya conocen, en lugar de aprender la sintaxis de TypeScript. La diferencia de productividad es pequeña y se reduce un paso del proceso de compilación.

Limitaciones de JSDoc

No es una solución universal. Cuando los tipos genéricos o las uniones se vuelven complejos, los comentarios pueden ser más largos que el código. Las funciones avanzadas de TypeScript, como los tipos condicionales (Conditional Types) o los tipos mapeados (Mapped Types), no se pueden expresar en JSDoc o resultan muy incómodas.

A medida que el proyecto y el equipo crecen, finalmente es más ventajoso para el mantenimiento migrar a TypeScript. Puedes considerar JSDoc como "una herramienta para maximizar la seguridad de tipos en situaciones en las que aún no es posible usar TypeScript".

Puntos clave

JSDoc es un método que añade información de tipos a JavaScript únicamente mediante comentarios. Puedes obtener autocompletado del editor y verificación de tipos sin necesidad de adoptar TypeScript. Solo necesitas añadir una línea con // @ts-check en la parte superior del archivo para activarlo inmediatamente.