Aumento de módulo de TypeScript y manejo de archivos JavaScript anidados

TypeScript ha sido una adición valiosa al ecosistema de JavaScript durante más de una década, ganando popularidad debido a su capacidad para proporcionar seguridad de tipos para el código JavaScript.

Tipos para paquetes de JavaScript#

Para la compatibilidad hacia atrás y la flexibilidad, TypeScript permite a los autores de paquetes proporcionar definiciones de tipos para sus paquetes de JavaScript. Estas definiciones de tipos generalmente se almacenan en el repositorio "DefinitelyTyped". Puedes usar el alcance @types para instalar estas definiciones de tipos, por ejemplo, @types/react es la definición de tipos para el paquete React.

Después de instalar estas definiciones de tipos, puedes usar el paquete con confianza en la seguridad de tipos. Aquí tienes un ejemplo de cómo definir un componente React con seguridad de tipos:

Aumento de módulo#

Aunque la mayoría de los paquetes populares de JavaScript tienen definiciones de tipos disponibles en el alcance @types, algunos paquetes pueden carecer de definiciones de tipos o tener versiones obsoletas. En tales casos, TypeScript ofrece una poderosa característica conocida como "aumento de módulo" para agregar definiciones de tipos para estos paquetes. Veamos un ejemplo:

Ahora puedes usar esta definición de tipo aumentada en tu código:

El aumento de módulo no solo te permite agregar definiciones de tipos para paquetes, sino también extender definiciones de tipos existentes. Por ejemplo, puedes agregar una nueva propiedad al objeto window:

Y usarla en tu código:

En una publicación anterior, hablamos sobre un problema de tipos en la biblioteca React Router, y tuvimos que superar el impacto extendiendo y aumentando el tipo existente a través de un archivo de declaración personalizado.

Recuerda que al usar el aumento de módulo, es crucial garantizar la precisión de tus definiciones de tipos inspeccionando cuidadosamente el código fuente de JavaScript. Las definiciones de tipos incorrectas pueden provocar errores en tiempo de ejecución. En el ejemplo anterior, la propiedad window.foo debe ser una cadena que exista en el objeto window.

Aumento global#

A veces, puedes encontrarte con scripts que introducen variables globales, y es posible que desees proporcionar definiciones de tipos para estas variables globales para usarlas en tu código TypeScript. Por ejemplo, si tienes un script que establece una variable global llamada __DEV__:

Puedes agregar definiciones de tipos para esta variable global de la siguiente manera:

Ahora puedes usarla en tu código TypeScript:

Al combinar el aumento de módulos y el aumento global, incluso puedes extender definiciones de tipos para los prototipos de JavaScript. Sin embargo, generalmente no se recomienda esto, ya que puede contaminar el ámbito global.

El poder del aumento de módulos permite tales extensiones, pero actúa con precaución para evitar la contaminación del ámbito global.

Archivos JavaScript anidados#

En los ejemplos mencionados anteriormente, asumimos que las importaciones podían resolverse a través del archivo de entrada del paquete. Sin embargo, algunos paquetes exportan archivos JavaScript anidados sin definir las correspondientes definiciones de tipos. Considera un paquete llamado foo con la siguiente estructura:

El paquete foo exporta el archivo index.js como punto de entrada y también exporta el directorio bar.

Para aumentar las definiciones de tipos para el paquete foo, puedes crear un archivo foo.d.ts:

Sin embargo, si intentas importar el archivo baz.js en TypeScript, encontrarás un error:

Para aumentar las definiciones de tipos para el archivo baz.js, necesitas crear un archivo baz.d.ts separado:

Esto garantiza que TypeScript pueda localizar el módulo y sus definiciones de tipos asociadas:

Para mantener definiciones de tipos organizadas, puedes imitar la estructura del paquete en tus archivos de definición de tipos:

Este enfoque mantiene tu código TypeScript estructurado y seguro en términos de tipos, incluso cuando se trata de archivos JavaScript anidados.