Skip to content

Latest commit

 

History

History
566 lines (395 loc) · 38.2 KB

README.pt.md

File metadata and controls

566 lines (395 loc) · 38.2 KB
Raw

Definitely Typed

O repositório para definições de tipo do TypeScript de alta qualidade.

Veja também o site definitelytyped.org, embora as informações neste README sejam mais atualizadas.

Link para o manual do Admin

Tabela de Conteúdos

Status atual

Essa seção acompanha a saúde do respositório e o processo de publicação. Ela pode servir de ajuda para contribuidores que estejam passado por problemas com suas PRs e pacotes.

Se algo aqui parece estar errado, ou se algum dos itens acima está falhando, por favor fale sobre este problema no canal do Definitely Typed no Discord.

O que são arquivos de declaração?

Veja o manual do TypeScript.

Como eu consigo eles?

NPM

Esse é o método aconselhável:

npm install --save-dev @types/node

Os tipos então devem ser automaticamente incluidos pelo compilador. Talvez você precise adicionar a referência types se não estiver usando módulos:

/// <reference types="node" />

Veja mais no manual.

Para um pacote "foo" do NPM, suas tipagens serão "@types/foo". Se você não conseguir achar o pacote desejado, procure no TypeSearch.

Se você mesmo assim não consegue achar o pacote, verifique se ele inclui seus próprios tipos. Isso normalmente é informado nos campos "types" ou "typings" no package.json, ou apenas procure por qualquer arquivo ".d.ts" no pacote e manualmente inclua-os com /// <reference path="" />.

Versões antigas do TypeScript (3.1 e anteriores)

O Definitely Typed testa apenas pacotes em versões do TypeScript que tenham sido lançadas a menos de 2 anos. Atualmente, as versões 3.2 e acima são testadas. Se você está usando as versões 2.0 a 3.1 do TypeScript, você ainda pode tentar instalar os pacotes @types — a maioria dos pacotes não usam as novas funcionalidades chiques do TypeScript. Mas não tem nenhuma garantia de que elas funcionarão. Esta é a tabela de duração de suporte das versões.

Versão Lançada em Término do suporte
2.8 Março 2018 Março 2020
2.9 Maio 2018 Maio 2020
3.0 Julho 2018 Julho 2020
3.1 Setembro 2018 Setembro 2020
3.2 Novembro 2018 Novembro 2020
3.3 Janeiro 2019 Janeiro 2021
3.4 Março 2019 Março 2021
3.5 Maio 2019 Maio 2021
3.6 Agosto 2019 Agosto 2021
3.7 Novembro 2019 Novembro 2021
3.8 Fevereiro 2020 Fevereiro 2022
3.9 Maio 2020 Maio 2022
4.0 Agosto 2020 Agosto 2022

Pacotes @types têm tags para versões do TypeScript que elas explicitamente suportam, então normalmente você pode usar versões mais antigas dos pacotes que precedem o período de 2 anos. Por exemplo, se você executar o comando npm dist-tags @types/react, você verá que o TypeScript 2.5 pode usar os tipos para o react@16.0, enquanto o TypeScript 2.6 e 2.7 podem usar os tipos para o react@16.4:

Tag Versão
latest 16.9.23
ts2.0 15.0.1
... ...
ts2.5 16.0.36
ts2.6 16.4.7
ts2.7 16.4.7
... ...

TypeScript 1.*

  • Faça download manualmente da branch master deste repositório e adicione-o no seu projeto
  • Typings (use alternativas aconselhadas. O typings foi descontinuado)
  • NuGet (use alternativas aconselhadas. A publicação de tipos do NuGet DT foi desligada)

Talvez você precise adicionar referências manuais.

Como eu posso contribuir?

O Definitely Typed só funciona por causa de contribuições de usuários como você!

Testando

Antes de compartilhar sua melhora com o mundo, use-a você mesmo.

Teste editando um pacote existente

Para testar localmente em seu aplicativo, você pode usar o acréscimo de módulos para herdar os tipos existentes do módulo DT que você quer editar. Você também pode editar os tipos diretamente em node_modules/@types/foo/index.d.ts para validar suas mudanças, e então trazer suas mudanças para o respositório seguindo os passos abaixo.

Adicionando testes ao novo pacote

Adicione ao seu tsconfig.json:

"baseUrl": "types",
"typeRoots": ["types"],

Crie o arquivo types/foo/index.d.ts contendo as declarações para o módulo "foo". Você deve conseguir fazer imports de "foo" em seu código e ele será redirecionado para a nova definição de tipos. Então faça uma build e execute o código para ter certeza que sua definição de tipos realmente corresponde ao que acontece em tempo de execução.

Se você está se perguntando por onde começar os testes em seu código, os exemplos no README do módulo são um ótimo lugar para começar.

Logo após testar suas definições com um código real, faça uma PR e então siga as instruções para editar um pacote existente ou criar um novo pacote.

Faça uma pull request

Logo após testar seu pacote, você pode compartilhá-lo aqui no Definitely Typed.

Primeiro, faça um fork deste respositório, instale o node, e execute npm install.

Edite um pacote existente

  • cd types/meu-pacote-para-editar

  • Faça as mudanças. Lembre de editar os testes. Se você está fazendo mudanças que podem "quebrar" o pacote, não se esqueça de atualizar a versão principal.

  • Se há um tslint.json, execute npm run lint nome-do-pacote. Senão, execute tsc no diretório do pacote.

Quando você fizer uma PR para editar um pacote existente, o dt-bot deve mencionar (usando "@") os antigos autores. Se ele não o fizer, você mesmo pode fazer isso no comentário associado a PR.

Editando testes em um pacote existente

Deve existir um arquivo [nomedomódulo]-tests.ts, que é considerado seu arquivo de teste, junto a qualquer arquivo *.ts que ele importar. Se você não encontrou nenhum arquivo de teste na pasta do módulo, crie um arquivo [nomedomódulo]-tests.ts. Esses arquivos serão usados para validar a API exportada dos arquivos *.d.ts que são enviadas como @types/seumódulo.

Mudanças nos arquivos *.d.ts devem ser acompanhadas de mudanças nos arquivos *.ts que mostrem que a API sendo usada, para que ninguém acidentalmente "quebre" o código do qual você depende. Se você não encontrou nenhum arquivo de teste na pasta do módulo, crie um arquivo [nomedomódulo]-tests.ts.

Abaixo há um exemplo dessas mudanças em uma função em um arquivo d.ts adicionando um novo parâmetro à função:

index.d.ts:

- export function twoslash(body: string): string
+ export function twoslash(body: string, config?: { version: string }): string

index-tests.ts:

import {twoslash} from "./"

// $ExpectType string
const result = twoslash("//")

+ // Lida com o parâmetro options
+ const resultWithOptions = twoslash("//", { version: "3.7" })
+ // Quando o parâmetro está incorreto
+ // $ExpectError
+ const resultWithOptions = twoslash("//", {  })

Você pode validar suas mudanças executando npm test na raiz deste repositório, que leva em consideração os arquivos alterados.

Crie um novo pacote

Se você é o autor de uma biblioteca e seu pacote está escrito em TypeScript, inclua os arquivos de declaração gerados automaticamente em seu pacote, em vez de publicá-los no Definitely Typed.

Se você está adicionando tipos para um pacote do NPM, crie um diretório com o mesmo nome do pacote. Se o pacote ao qual você está adicionando tipos não está no NPM, tenha certeza de que o nome escolhido para ele não entre em conflito com o nome de um outro pacote no NPM. (Você pode executar npm info foo para verificar a existência do pacote foo.)

Seu pacote deve possuir a seguinte estrutura:

Arquivo Propósito
index.d.ts Contém os tipos para o pacote.
foo-tests.ts Contém código de exemplo que testa os tipos. Esse código não é executado, mas seus tipos são checados.
tsconfig.json Permite que você execute tsc dentro do pacote.
tslint.json Habilita a análise do código pelo linter.

Gere esses arquivos executando npx dts-gen --dt --name nome-do-seu-pacote --template module se você possuir a versão 5.2.0 ou mais recente do NPM ou npm install -g dts-gen e dts-gen --dt --name nome-do-seu-pacote --template module caso possua uma versão mais antiga. Veja todas as opções em dts-gen.

Você pode editar o tsconfig.json para adicionar novos arquivos de teste, para adicionar "target": "es6" (necessário para funções assíncronas), para adicionar a "lib", ou para adicionar a opção "jsx" do compilador. Se há outros arquivos .d.ts além do arquivo index.d.ts, tenha certeza de que eles são referenciados no arquivo index.d.ts ou nos testes.

Se um arquivo não for testado nem referenciado no index.d.ts, adicione-o em um arquivo chamado OTHER_FILES.txt. Este arquivo é uma lista de outros arquivos que precisam ser incluidos no pacote de tipos, um arquivo por linha.

Os membros do Definitely Typed frequentemente monitoram os novos PRs, porém tenha em mente de que a quantidade de PRs pode atrasar o processo.

Para ver um bom exemplo, veja o pacote base64-js.

Donos de definição

O DT tem o coneito de "Donos de definição", que são pessoas que querem manter a qualidade dos tipos de um módulo específico

  • Adicionar você mesmo à lista, vai garantir que você seja notificado (pelo seu usuário do GitHub) sempre que qualquer um fizer uma pull request ou um issue sobre o pacote.
  • Suas revisões da PR terão uma precedência de importância maior para o bot que mantém este repositório.
  • Os mantenedores do DT estão confiando nos donos da definição para garantir um ecossistema estável, por favor não se adicione apenas por adicionar.

Para se adicionar como um Dono de definição:

  • Adicione seu nome ao final da linha, por exemplo: // Definitions by: Alice <https://github.com/alice>, Bob <https://github.com/bob>.
  • Ou se há muitas pessoas, pode ser em várias linhas:
// Definitions by: Alice <https://github.com/alice>
//                 Bob <https://github.com/bob>
//                 Steve <https://github.com/steve>
//                 John <https://github.com/john>

Uma vez por semana os Donos de definição são sincronizados para o arquivo .github/CODEOWNERS, que é a nossa fonte da verdade.

Erros comuns

  • Primeiro, siga as instruções do manual.
  • Formatação: Use 4 espaços. O Prettier está configurado neste repositório, então você pode executar npm run prettier -- --write path/to/package/**/*.ts. Se estiver usando asserções, adicione a tag de exclusão // prettier-ignore para marcar linhas de código como exclusas da formatação: 
    // prettier-ignore
const incompleteThemeColorModes: Theme = { colors: { modes: { papaya: { // $ExpectError
  • function sum(nums: number[]): number: Use ReadonlyArray se a função não adiciona valores a seus parâmetros.
  • interface Foo { new(): Foo; }: Isto define um tipo de objeto que pode ser instanciado utlizando o operador new. Você provavelmente deveria escrever declare class Foo { constructor(); }.
  • const Class: { new(): IClass; }: Prefira usar a declaração de classe class Class { constructor(); } em vez de uma constante que pode ser instanciada utlizando o operador new.
  • getMeAT<T>(): T: Se um parâmetro de tipo não estiver no tipo de nenhum dos parâmetros, então você não tem realmente uma função genérica, você só tem uma asserção de tipos disfarçada. Prefira usar uma asserção de tipos real, por exemplo getMeAT() as number. Um exemplo onde um parâmetro de tipo é aceitável: function id<T>(value: T): T;. Um exemplo onde não é aceitável: function parseJson<T>(json: string): T;. Exceção: new Map<string, number>() é aceitável.
  • Usar os tipos Function e Object quase nunca é uma boa ideia. Em 99% dos casos é possível especificar um tipo mais específico. Por exemplo (x: number) => number para funções e { x: number, y: number } para objetos. Se você não tem nenhuma certeza sobre o tipo, any é a escolha correta, não Object. Se a única certeza sobre o tipo é que ele é algum objeto, use o tipo object, não Object ou { [key: string]: any }.
  • var foo: string | any: Quando any é usado em um tipo de união, o tipo resultante ainda é any. Então, enquanto a parte da anotação de tipo string pode parecer útil, na verdade ela não oferece nenhuma verificação de tipo adicional do que simplesmente usar any. Dependendo da intenção, alternativas aceitáveis podem ser any, string, ou string | object.

Removendo um pacote

Quando um pacote inclui seus próprios tipos, os tipos devem ser removidos do Definitely Typed para evitar confusão.

Você pode removê-lo executando npm run not-needed -- typingsPackageName asOfVersion sourceRepoURL [libraryName]

  • typingsPackageName: O nome do diretório a ser deletado.
  • asOfVersion: Um esboço será publicado em @types/foo com essa versão. Deve ser maior do que qualquer versão atualmente publicada, e deve ser uma versão de foo no npm.
  • sourceRepoURL: Essa URL deve apontar um repositório que contém os tipos.
  • libraryName: Nome do pacote no npm que substitui os tipos do Definitely Typed. Normalmente é idêntico ao "typingsPackageName", e nesse caso pode ser omitido.

Quaisquer outros pacotes no Definitely Typed que referenciavam o pacote deletado devem ser atualizados para referenciar os tipos inclusos pelo pacote. Você pode obter esta lista olhando os erros do npm run test. Para corrigir os erros, adicione o arquivo package.json com "dependencies": { "foo": "x.y.z" }. Por exemplo:

{
  "private": true,
  "dependencies": {
    "foo": "^2.6.0"
  }
}

Quando você adicionar um package.json aos dependentes de foo, você também precisará abrir uma PR para adicionar foo ao dependenciesWhitelist.txt em types-publisher.

Se um pacote nunca esteve no Definitely Typed, ele não precisa ser adicionado ao notNeededPackages.json.

Linter

Todos os novos pacotes devem passar pelo linter. Para habilitar o linter num pacote, adicione um tslint.json para aquele pacote, contendo:

{
    "extends": "dtslint/dt.json"
}

Este deve ser o único conteúdo no arquivo tslint.json de um projeto finalizado. Se um tslint.json desabilitar certas regras, é porque elas ainda não foram corrigidas. Por exemplo:

{
    "extends": "dtslint/dt.json",
    "rules": {
        // Este pacote usa o tipo Function, e vai dar trabalho para arrumar.
        "ban-types": false
    }
}

(Para indicar que uma regra de lint de fato não se aplica, use // tslint:disable nome-da-regra ou até mesmo, //tslint:disable-next-line nome-da-regra.)

Para afirmar que uma expressão é de um tipo determinado, use $ExpectType. Para afirmar que uma expressão causa um erro de compilador, use $ExpectError.

// $ExpectType void
f(1);

// $ExpectError
f("um");

Para mais detalhes, veja o arquivo readme do dtslint.

Verificando

Teste suas mudanças executando o comando npm run lint nome-do-pacote onde nome-do-pacote é o nome do seu pacote.

Este script usa o dtslint para executar o compilador de TypeScript em seus arquivos dts.

FAQ

Qual exatamente é a relação entre este repositório e os pacotes @types no NPM?

A branch master é automaticamente publicada ao escopo @types no NPM graças ao types-publisher.

Eu já enviei uma pull request. Quanto tempo pode demorar até que haja um merge?

Depende, mas a maioria das pull requests sofrem merge dentro de uma semana. Algumas PRs podem sofrer merge pelos donos de um módulo, fazendo com que elas sejam mescladas muito mais rapidamente. Superficialmente:

PRs que alteram apenas os tipos de um módulo, e têm mudanças de testes correspondentes sofrerão merges muito mais rapidamente.

PRs que forem aprovadas por um autor listado no cabeçalho da definição geralmente sofrem merge mais rápido; PRs para novas definições levarão mais tempo para serem aprovadas, uma vez que requerem mais revisão dos mantenedores. Cada PR é revisada por um membro do time do TypeScript ou Definitely Typed antes de sofrer merge, então por favor, seja paciente, pois fatores humanos podem causar alguns atrasos. Verifique o Painel de Status de Novas Pull Requests para checar o progresso enquanto os mantenedores revisam as PRs abertas.

Minha PR já sofreu merge; Quando é que o pacote @types no NPM será atualizado?

Pacotes do NPM devem atualizar dentro de alguns minutos. Se já passou de uma hora, mencione o número da PR no canal do Discord do Definitely Typed e um mantenedor vai contatar o membro certo do time para investigar.

Eu estou criando uma definição que depende de outra definição. Eu deveria usar <reference types="" /> ou um import?

Se o módulo o qual você está referenciando é um módulo externo (usa export), use um import. Se o módulo que você está referenciando é um módulo de ambiente (usa declare module, ou apenas declara globalmente), use <reference types="" />.

Eu percebi que alguns pacotes tem um package.json aqui.

Geralmente você não precisa disso. O distribuidor de pacotes do Definitely Typed cria um package.json para pacotes sem dependências fora do Definitely Typed. Um package.json pode ser incluído para especificar dependências que não são outros pacotes @types. Pikaday é um bom exemplo. Mesmo se você criar seu próprio package.json, você pode apenas especificar dependências; outros campos como "description" não são permetidos. Você também precisa adicionar uma dependência à lista de pacotes permitidos. Essa lista é atualizada por um humano, o que nos dá a chance de nos certificar que os pacotes @types não dependem de pacotes maliciosos.

Nos caso raro que um pacote @types é deletado e removido em favor dos tipos enviados pelo pacote-fonte e você precise depender do pacote antigo @types, já removido, você pode adicionar a dependência no pacote @types. Tenha certeza de explicar isso quando adicioná-lo à lista de pacotes permitidos, para que o mantenedor humano saiba o que está acontecendo.

Alguns pacotes não têm tslint.json, e alguns arquivos tsconfig.json não têm "noImplicitAny": true, "noImplicitThis": true, ou "strictNullChecks": true.

Então eles estão errados, e nós não notamos ainda. Você pode ajudar enviando uma pull request pra consertá-los.

Posso requisitar uma definição?

Aqui estão as definições requisitadas atualmente.

Mas e as definições de tipo para a DOM?

Se os tipos são parte de um padrão de web, eles devem ser enviados para o TSJS-lib-generator, fazendo com que eles se tornem parte do lib.dom.d.ts.

Eu deveria adicionar um namespace vazio para um pacote que não exporta um módulo, para usar imports no estilo do ES6?

Alguns pacotes, como o chai-http, exportam uma função.

Importar este módulo com o estilo de import do ES6 na forma de import * as foo from "foo"; resulta no erro:

error TS2497: Module 'foo' resolves to a non-module entity and cannot be imported using this construct

Este erro pode ser suprimido por mesclar a declaração da função com um namespace vazio do mesmo nome, mas essa prática é desencorajada. Isso é recorrentemente citado nesta resposta do Stack Overflow que fala sobre essa prática.

É mais apropriado importar o módulo usando a sintaxe import foo = require("foo");. Mesmo assim, se você quer usar um import padrão como import foo from "foo";, você tem duas opções:

Um pacote usa um export =, mas eu prefiro usar os imports padrão. Eu posso mudar o export = para export default?

Como na pergunta anterior, lembre-se de que você pode usar as opções de compilador --allowSyntheticDefaultImports e --esModuleInterop.

Não mude a definição de tipo se ela já está correta. Para um pacote NPM, export = é o certo, se node -p 'require("foo")' funciona para importar um módulo, e export default é o certo se node -p 'require("foo").default' funciona para importar um módulo.

Eu quero usar features do TypeScript 3.3 ou superior.

Então você vai precisar adicionar este comentário na última linha do seu cabeçalho de definição (depois de // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped): // Minimum TypeScript Version: 3.3.

Entretanto, se o seu projeto precisa manter tipos que são compatíveis com o 3.1 e superior ao mesmo tempo que tipos que são compatíveis com o 3.0 ou inferior, você vai precisar usar a feature typesVersions, que está disponível no TypeScript 3.1 e superior. Você pode achar uma explicação detalhada dessa feature na documentação oficial do TypeScript.

Aqui vai uma explicação curta pra te ajudar:

  1. Você vai precisar adicionar um arquivo package.json à sua definição de pacote, com os seguintes conteúdos:
{
    "private": true,
    "types": "index",
    "typesVersions": {
        ">=3.1.0-0": { "*": ["ts3.1/*"] }
    }
}

  1. Crie o sub-diretório mencionado no campo typesVersions dentro do seu diretório de tipos (ts3.1/ neste exemplo) e adicione os tipos e testes específicos para a nova versão do TypeScript. Você não precisa do típico cabeçalho de definição nos arquivos do diretório ts3.1/.

  2. Defina as opções baseUrl e typeRoots no ts3.1/tsconfig.json para os caminhos corretos. Eles devem ficar semelhantes a isto:

{
    "compilerOptions": {
        "baseUrl": "../../",
        "typeRoots": ["../../"]
    }
}

Você pode verificar aqui e aqui para exemplos.

Eu quero adicionar uma API da DOM não presente no TypeScript por padrão.

Isso talvez pertença ao TSJS-Lib-Generator. Veja as regras lá. Se esse padrão ainda é um rascunho, ele pertence a aqui. Use o nome começando com dom- e inclua um link para o padrão como o link do "Projeto" no cabeçalho. Quando o padrão sair do papel, nós o removeremos do Definitely Typed e descontinuaremos os pacotes @types associados.

Como as versões do pacote do Definitely Typed se relacionam às versões da biblioteca correspondente?

NOTA: A discussão nesta sessão supõe familiaridade com versionamento semântico

Cada pacote do Definitely Typed é versionado ao ser publicado ao NPM. O types-publisher (a ferramenta que publica pacotes @types ao NPM) definirá a declaração da versão do pacote usando o número da versão major.minor listado na primeira linha do seu arquivo index.d.ts. Por exemplo, aqui estão as primeiras linhas das declarações de tipo do Node para a versão 10.12.x, no momento de escrita:

// Type definitions for Node.js 10.12
// Project: http://nodejs.org/
// Definitions by: Microsoft TypeScript <https://github.com/Microsoft>
//                 Definitely Typed <https://github.com/DefinitelyTyped>
//                 Alberto Schiabel <https://github.com/jkomyno>

A versão do NPM do pacote @types/node será 10.12.x porque está escrito 10.12 no final da primeira linha. Note que o comentário da primeira linha no arquivo index.d.ts deve conter apenas a versão major.minor (por exemplo, 10.12) e não deve conter uma versão de patch. (por exemplo, 10.12.4). Isto acontece porque apenas os números de release "major" e "minor" estão alinhados entre os pacotes de biblioteca e os pacotes de declaração de tipo. O número de release do patch do pacote de declaração de tipo (.0 em 10.12.0) é inicializado como zero pelo Definitely Typed e é incrementado a cada vez que um novo pacote @types/node é publicado ao NPM para a mesma versão "major"/"minor" da biblioteca correspondente.

Algumas vezes as versões de pacotes de declaração de tipo e as versões de pacotes de biblioteca podem sair de sincronia. Abaixo estão algumas razões do porquê, por causa do quanto elas incomodam os usuários de uma biblioteca. Apenas o último caso é tipicamente problemático.

  • Como notado acima, a versão do patch do pacote de declaração de tipo não está relacionada à versão do patch da biblioteca. Isso permite que o Definitely Typed atualize as declarações de tipo de forma segura para a mesma versão "major"/"minor" de uma biblioteca.
  • Caso esteja atualizando um pacote para uma nova funcionalidade, não se esqueça de atualizar o número da versão para alinhá-lo com aquela versão da biblioteca. Caso os usuários tenham certeza de que versões correspondam entre os pacotes JavaScript e seus respectivos pacotes @types, então um npm update deve tipicamente funcionar.
  • É comum para atualizações de um pacote de declaração de tipos ficarem atrasadas em relação às atualizações da biblioteca, porque é mais comum que os usuários das bibliotecas, não os mantenedores, atualizem o Definitely Typed quando novas features da biblioteca são lançadas. Então talvez haja um atraso de alguns dias, semanas ou até mesmo meses antes de um membro solidário da comunidade mandar uma PR para atualizar o pacote de declaração de tipos para uma nova release da biblioteca. Se você estiver comovido com isso, você pode ser a mudança que você quer ver no mundo, e você pode ser esse membro solidário da comunidade!

❗ Se você está atualizando as declarações de tipo para uma biblioteca, sempre defina a versão major.minor na primeira linha do index.d.ts correspondendo à versão da biblioteca que você está documentando! ❗

Se uma biblioteca for atualizada para uma nova versão "major" com mudanças drásticas, como eu devo atualizar a declaração de tipos?

Versionamento semântico requer que versões com mudanças drásticas devem incrementar o número "major" da versão. Por exemplo, uma biblioteca que remove uma função publicamente exportada depois de sua release 3.5.8 deve aumentar sua versão para 4.0.0 na próxima release. Além do mais, quando a release 4.0.0 da biblioteca for publicada, seu pacote de declaração de tipos do Definitely Typed deve também ser atualizado para 4.0.0, incluindo quaisquer mudanças drásticas para a API da biblioteca.

Muitas bibliotecas têm uma grande base de desenvolvedores instalados (incluindo mantenedores de outros pacotes usando aquela biblioteca como dependência) os quais não vão migrar imediatamente para a nova versão que tem mudanças drásticas, porque pode levar meses até que um mantenedor tenha tempo de reescrever o código para adaptá-lo à nova versão. Enquanto isso, usuários das versões antigas da biblioteca ainda podem querer atualizar as declarações de tipo para versões antigas.

Se você pretende continuar atualizando a versão mais antiga de uma declaração de tipos de uma biblioteca, você pode criar uma nova sub-pasta (por exemplo, /v2/), nomeá-la de acordo com a versão atual (que será antiga em breve), e copiar os arquivos da versão atual para essa pasta.

Porque o diretório-raíz deve sempre conter as declarações de tipo para as últimas versões ("novas"), você precisará fazer algumas mudanças aos arquivos do seu sub-diretório da sua versão antiga para garantir que as referências de caminho relativo apontam ao sub-diretório, não ao diretório-raíz.

  1. Atualize os caminhos relativos no tsconfig.json, assim como no tslint.json.
  2. Adicione regras de mapeamento de caminhos para garantir que os testes estão sendo executados sobre a versão pretendida.

Por exemplo, a biblioteca history introduziu mudanças drásticas entre a versão 2.x e 3.x. Mas porque muitos usuários ainda consumiam a antiga versão 2.x, o mantenedor que queria atualizar as declarações de tipo dessa biblioteca para a versão 3.x adidionou uma pasta v2 dentro do repositório "history" que contém declarações de tipo para a versão anterior. No tempo de escrita, a history v2 tsconfig.json está assim:

{
    "compilerOptions": {
        "baseUrl": "../../",
        "typeRoots": ["../../"],
        "paths": {
            "history": [ "history/v2" ]
        },
    },
    "files": [
        "index.d.ts",
        "history-tests.ts"
    ]
}

Se há outros pacotes no Definitely Typed que são incompatíveis com a nova versão, você precisará adicionar mapeamentos de caminho para a versão antiga. Você também precisará fazer isso recursivamente para pacotes dependentes da versão antiga.

Por exemplo, react-router depende de history@2, então o tsconfig.json do react-router tem um mapeamento de caminho para "history": [ "history/v2" ]. Provisoriamente, o react-router-bootstrap (que depende do react-router) também precisou ter o mesmo mapeamento de caminhos adicionado ("history": [ "history/v2" ]) no seu tsconfig.json até que o sua dependência react-router fosse atualizada para a última versão.

/// <reference types=".." /> também não vai funcionar com o mapeamento de caminhos, então dependências devem usar import.

Como eu crio definições para pacotes que podem ser usados globalmente e como um módulo?

O manual do TypeScript contém excelentes informações gerais sobre criar definições, e também este arquivo de definição de exemplo que mostra como criar uma definição usando a sintaxe de módulo no estilo ES6, enquanto também especifica os objetos que tornaram-se disponíveis ao escopo global. Essa técnica é demonstrada de forma prática na definição da big.js, que é uma biblioteca que pode ser carregada globalmente via tags de script numa página da web, ou importada via require ou via imports no estilo do ES6.

Para testar como sua definição pode ser usada tanto quando referenciada globalmente quanto como um módulo importável, crie uma pasta test, e coloque dois arquivos de teste nela. Chame um de NomeDaSuaBiblioteca-global.test.ts e o outro de NomeDaSuaBiblioteca-module.test.ts. O arquivo de teste global deve exercer a definição de acordo com como ele seria usado num script carregado numa página da web onde a biblioteca está disponível no escopo global - nesse cenário você não deve especificar uma declaração de importação. O arquivo de teste module deve exercer a definição de acordo com como ele seria usado quando importado (incluindo a(s) definição(ões) de import). Se Você especificar uma propriedade files no seu arquivo tsconfig.json, tenha certeza de incluir ambos os arquivos de teste. Um exemplo prático de como fazer isso também está disponível na definição da big.js.

Por favor note que isso não é obrigatório para exercer completamente a definição em cada arquivo de teste - é suficiente para testar apenas os elementos accessíveis globalmente no arquivo de teste global e exercer a definição no arquivo de teste do módulo, ou vice versa.

Mas e os pacotes com escopo?

Tipos para um pacote com escopo @foo/bar devem estar em types/foo__bar. Note o underscore duplo.

Quando dts-gen for usado para montar um pacote com escopo, a propriedade paths tem de ser manualmente adaptada no arquivo tsconfig.json gerado, para referenciar corretamente o segundo pacote com escopo:

{
    "paths":{
      "@foo/*": ["foo__*"]
    }
}

O histórico do arquivo no GitHub parece incompleto.

O GitHub não suporta histórico de arquivos renomeados. Use git log --follow ao invés disso.

Licença

Esse projeto é licenciado sob a licença MIT.

Copyrights nos arquivos de definição são respectivos de cada contribuidor listado no começo de cada arquivo de definição.