11

Estudando TypeScript reparei que existem arquivos .d.ts e que é possível declarar os tipos lá, mas:

  • Qual a utilidade de fato dos arquivos .d.ts?
  • Se eu já declaro os tipos no arquivo .ts, ainda devo ter um .d.ts correspondente?
  • Quando faz sentido eles serem gerados automaticamente? - Existe a configuração declaration no tsconfig.json para isso, mas não entendi quando faz sentido usá-la.

3 Respostas 3

11

Os arquivos *.d.ts são chamados arquivos de declaração. O d no nome vem de declaration.

A principal utilidade é declarar tipos para aplicações ou bibliotecas originalmente feitas em JavaScript. Desse modo, quem for usar, em TypeScript, a API (codificados em JavaScript) terá acesso aos tipos, mesmo que eles não tenham sido diretamente definidos na implementação.

É muito útil para bibliotecas oferecerem suporte a usuários de TypeScript sem a necessidade de reescrever todo o código-fonte em uma outra linguagem.

Se eu já declaro os tipos no arquivo .ts, ainda devo ter um .d.ts correspondente?

Na maioria das vezes, não. Se você estiver escrevendo o seu código em TypeScript, as definições estáticas de tipos já estarão "incluídas" nele, ao lado da implementação. Há casos mais complexos em que a separação pode ser útil.

Quando faz sentido eles serem gerados automaticamente?

A opção --declaration deve ser usada se você quiser gerar os arquivos de declaração. É especialmente útil se você quiser criar uma biblioteca que já "venha" com definição de tipos. Tendo em vista que ao ser compilado, o código-fonte do TypeScript "perde" os tipos estáticos, os arquivos de declaração são o único jeito de manter essa informação após a compilação.

Existe a propriedade types (ou typings) do package.json. Você pode utilizá-la para "publicar" um arquivo de definição de tipos padrão no seu pacote.

A documentação cobre alguns outros casos de uso e informações.

7

O principal ponto da criação de TypeScript é dar mais robustez para sistemas complexos. JavaScript foi criada pensando para uso em scripts muito simples para automatizar alguma ação em uma página, não para fazer softwares de verdade.

Apesar de TypeScript ter script no nome ela não é para isso. O ponto principal que diferencia uma linguagem de script para uma linguagem capaz de lidar com bases de códigos mais complexas é tipagem dinâmica.

TypeScript usa tipagem estática em seu código. Então há contratos mais rígidos, que é o que dá robustez.

Mas TS foi criada para ser compatível com JS, e de fato TS compila para um código alvo JS (por isso na execução a tipagem passa ser dinâmica, mas depois de compilado a robustez já foi garantida, só a performance será de linguagem dinâmica, que é pior, mas pode não ser tanto porque já há algumas garantias que o JITter pode se beneficiar em alguns pontos). Você pode misturar código TS e JS, então TS nasceu muito forte.

Mas códigos JS não tem tipos manifestos então não tem esses contratos. Enquanto é algo local não muda nada para o TypeScript, mas quando falta a tipagem em APIs públicas (parâmetros e retorno de métodos por exemplo) o compilador do TS fica rendido e não pode dar as garantias que normalmente ele pode dar. Tudo funciona, mas ele não pega erros possíveis ali, e ferramentas podem não ajudar tanto.

O que fazer então para colocar tipos em algo que não tinha tipos?

Bom, em C/C++ esses contratos sempre estiveram em arquivos separados (em geral os .h de header). Você primeiro os criava para todas aplicações usarem eles porque e só o que o compilador precisava para garantir os contratos e depois criava os códigos reais que atendiam esses contratos.

Em TS fizeram o contrário, começaram criar esses arquivos depois que já existiam códigos em JS. Algumas pessoas foram nas principais bibliotecas existentes para TS viram quais eram os contratos, até onde dava para ver (algumas bibliotecas são muito ruins e o contrato deixava muito aberto, aí não tem muito o que fazer a não ser dizer explicitamente que está aberto mesmo, só para não dar erro à toa), e aí colocaram nesses arquivos .d os tipos dos dados que seriam usados nas APIs existentes. Assim o compilador do TS pode usá-los para dar as garantias necessárias. O .ts final é para indicar claramente que isso é do TS, apesar de ser relacionado a um código JS, para o JS não precisa disso.

Qualquer biblioteca pública séria criada hoje em dia para front web que não é escrita em TS (e muitas cada vez mais são), e que então foram escritas em JS (sai uma nova por segundo, você sabe disso :P :D) se ela for séria a pessoa já cria esses arquivos com os contratos para rodar bem junto com TS.

Se está fazendo o código em TS mesmo então esses arquivos não são necessários, pelo menos se está tipando tudo direitinho como o TS manda. Se não está tipando então seu código é meio JS ainda, aí precisaria, mas isso não faz sentido quando usa o TS.

Coloquei no GitHub para referência futura.

2

Ele serve pra fornecer informacoes de tipo em API escrita em JavaScript. Por exemplo, usar um JQuery no seu codigo, voce usa esse tipo de arquivo para isto, em vez de reescrever o JQuery todo em TS, pode pode apenas declarar os tipos nesse arquivo .d.ts.

Para mapear, ate onde me lembro, voce deve criar um arquivo d.ts de mesmo nome do arquivo .js. Exemplo:

codigo React com TS:

import * as myMod from 'my-module';

 // ...

Codigo no index.js:

module.exports = function(qualquer) {

 // ....

 return qualquer
}

Adiciona tipos criando um index.d.ts

declare module 'my-module' {
 export default function qualquer(arg1: string, arg2: string): QualquerCoisa;
}

interface QualquerCoisa {
 idade: number;
 altura: number;
}

Resumindom, d.ts e um arquivo de declaracoes para o TypeScript de um arquivo JavaScript. *Lembrando que quem vai ser importado vai ser o index.d.ts pois ele vai ser uma interface entre seu codigo JS e o TS.

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .