TypeScript
Migración e interoperabilidad con JavaScript mediante allowJs, checkJs y JSDoc para introducir comprobación de tipos sin convertir todo el proyecto de inmediato.
{
"compilerOptions": {
"allowJs": true
}
}Incluye archivos .js dentro del programa. Puede permitir imports entre TS y JS y, según configuración, emitir o generar declarations.
No activa todos los errores de tipos en JavaScript.
{
"compilerOptions": {
"allowJs": true,
"checkJs": true
}
}Activa comprobación en archivos JS.
Por archivo:
// @ts-checkDesactivar en un archivo legacy:
// @ts-nocheckUsa @ts-nocheck como deuda visible y temporal, no como configuración permanente invisible.
/**
* @param {number} price
* @param {number} quantity
* @returns {number}
*/
function subtotal(price, quantity) {
return price * quantity;
}/**
* @typedef {Object} Product
* @property {string} id
* @property {string} name
* @property {number} price
*//** @type {Product} */
const product = {
id: "p1",
name: "Keyboard",
price: 100,
};/** @typedef {import("./product.js").Product} Product */No crea un import runtime.
/**
* @template T
* @param {T} value
* @returns {{ value: T }}
*/
function wrap(value) {
return { value };
}/**
* @template {string} T
* @param {T} value
* @returns {T}
*/
function identity(value) {
return value;
}JSDoc soporta una parte importante del sistema, pero la sintaxis avanzada puede ser menos legible que .ts.
/** @satisfies {Record<string, Route>} */
const routes = {
home: { path: "/", public: true },
};Comprueba compatibilidad sin sustituir por completo la inferencia del objeto.
const input = /** @type {HTMLInputElement} */ (
document.querySelector("input")
);Es una assertion y puede mentir. Comprueba null y tipo cuando la estructura no está garantizada.
En JavaScript, TypeScript puede ser más permisivo en patrones comunes:
JSDoc ayuda a cerrar contratos gradualmente.
const { readFile } = require("node:fs/promises");
module.exports = { loadConfig };TypeScript puede inferir y comprobar muchos patrones. Para librerías, la declaration emitida debe representar correctamente export =, named exports o default interop según el runtime.
{
"compilerOptions": {
"allowJs": true,
"declaration": true,
"emitDeclarationOnly": true
}
}Puede generar .d.ts desde JSDoc y exports JavaScript. Revisa la salida: una inferencia interna no siempre es una buena API pública.
Orden práctico:
Renombrar .js a .ts puede exponer:
Corrige contratos, no solo sintaxis.
// @ts-expect-error legacy API uses an undocumented argument
legacyCall(value, true);@ts-expect-error falla si el error desaparece, por lo que es mejor para deuda conocida.
@ts-ignore silencia incluso cuando ya no hay error y puede quedar obsoleto.
Un módulo JavaScript sin tipos puede recibirse como any. Crea un adapter TypeScript que:
import legacyClient from "legacy-client";
export async function loadProduct(
id: string,
): Promise<Product> {
const value: unknown = await legacyClient.load(id);
return parseProduct(value);
}@ts-check permite migración por archivo.¿Por qué @ts-expect-error es mejor que @ts-ignore para una incompatibilidad conocida?
Porque produce un error cuando el diagnóstico esperado desaparece, evitando que el comentario quede ocultando código que ya podría corregirse.
Namespaces explica el mecanismo histórico de organización y cuándo los módulos modernos son preferibles.