Aumento de módulos em TypeScript e manuseio de ficheiros JavaScript aninhados

O TypeScript tem sido uma adição valiosa ao ecossistema JavaScript há mais de uma década, ganhando popularidade devido à sua capacidade de fornecer segurança de tipos ao código JavaScript.

Tipos para pacotes JavaScript#

Por questão de compatibilidade retroativa e flexibilidade, o TypeScript permite que autores de pacotes forneçam definições de tipos para seus pacotes JavaScript. Essas definições de tipos geralmente são armazenadas no repositório "DefinitelyTyped". Pode utilizar o âmbito @types para instalar essas definições de tipos, por exemplo, @types/react é a definição de tipo para o pacote React.

Após instalar essas definições de tipos, pode utilizar o pacote com confiança na segurança de tipos. Aqui está um exemplo de como definir um componente React com segurança de tipos:

Aumento de módulos#

Embora a maioria dos pacotes JavaScript populares tenha definições de tipos prontamente disponíveis no âmbito @types, alguns pacotes podem não ter definições de tipos ou ter definições desatualizadas. Nesses casos, o TypeScript fornece um recurso poderoso conhecido como "aumento de módulos" para adicionar definições de tipos para esses pacotes. Vejamos um exemplo:

Agora pode utilizar essa definição de tipo aumentada no seu código:

O aumento de módulos não apenas permite que adicione definições de tipos para pacotes, mas também estende definições de tipos existentes. Por exemplo, pode adicionar uma nova propriedade ao objeto window:

E utilizá-la no seu código:

Em um post anterior, falámos sobre um problema de tipo na biblioteca React Router e tivemos que superar o impacto extendendo e aumentando o tipo existente através de um ficheiro de declaração personalizado.

Lembre-se de que, ao utilizar o aumento de módulos, é crucial garantir a precisão das suas definições de tipos, inspecionando cuidadosamente o código-fonte JavaScript. Definições de tipos incorretas podem levar a erros em tempo de execução. No exemplo acima, a propriedade window.foo deve ser uma string que existe no objeto window.

Aumento global#

Às vezes, pode encontrar scripts que introduzem variáveis globais e desejar fornecer definições de tipos para essas variáveis globais para utilizá-las no seu código TypeScript. Por exemplo, se tiver um script que define uma variável global chamada __DEV__:

Pode adicionar definições de tipos para essa variável global desta forma:

Agora pode utilizá-la no seu código TypeScript:

Ao combinar o aumento de módulos e o aumento global, pode até estender definições de tipos para protótipos JavaScript. No entanto, isso geralmente não é recomendado, pois pode poluir o escopo global.

O poder do aumento de módulos permite tais extensões, mas seja cauteloso para evitar a poluição do escopo global.

Ficheiros JavaScript aninhados#

Nos exemplos mencionados anteriormente, assumimos que as importações poderiam ser resolvidas através do ficheiro de entrada do pacote. No entanto, alguns pacotes exportam ficheiros JavaScript aninhados sem as correspondentes definições de tipos. Considere um pacote chamado foo com a seguinte estrutura:

O pacote foo exporta o ficheiro index.js como o ponto de entrada e também exporta o diretório bar.

Para aumentar as definições de tipos para o pacote foo, pode criar um ficheiro foo.d.ts:

No entanto, se tentar importar o ficheiro baz.js no TypeScript, encontrará um erro:

Para aumentar as definições de tipos para o ficheiro baz.js, é necessário criar um ficheiro baz.d.ts separado:

Isso garante que o TypeScript possa localizar o módulo e as suas definições de tipos associadas:

Para manter as definições de tipos organizadas, pode imitar a estrutura do pacote nos seus ficheiros de definição de tipos:

Essa abordagem mantém o seu código TypeScript estruturado e seguro em termos de tipos, mesmo ao lidar com ficheiros JavaScript aninhados.