diff --git a/README.md b/README.md index 55c385a8cb..a550b47210 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > The repository for *high quality* TypeScript type definitions. -*You can also read this README in [Spanish](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.es.md), [Korean](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ko.md), [Russian](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ru.md), and [Chinese](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.cn.md)!* +*You can also read this README in [Spanish](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.es.md), [Korean](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ko.md), [Russian](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ru.md), [Chinese](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.cn.md) and [Portuguese](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.pt.md)!* *Link to [Admin manual](./docs/admin.md)* @@ -569,4 +569,4 @@ GitHub doesn't [support](http://stackoverflow.com/questions/5646174/how-to-make- This project is licensed under the MIT license. -Copyrights on the definition files are respective of each contributor listed at the beginning of each definition file. +Copyrights on the definition files are respective of each contributor listed at the beginning of each definition file. \ No newline at end of file diff --git a/README.pt.md b/README.pt.md new file mode 100644 index 0000000000..d1b58d9639 --- /dev/null +++ b/README.pt.md @@ -0,0 +1,571 @@ +# Definitely Typed + +> O repositório para definições de tipo do TypeScript de *alta qualidade*. + +Veja também o site [definitelytyped.org](http://definitelytyped.org), embora as informações neste README sejam mais atualizadas. + +*Link para o [manual do Admin](./docs/admin.md)* + +## Tabela de Conteúdos + +* [Status atual](#status-atual) +* [Como eu posso contribuir?](#como-eu-posso-contribuir) + * [Testando](#testando) + * [Faça uma pull request](#faça-uma-pull-request) + * [Edite um pacote existente](#edite-um-pacote-existente) + * [Crie um novo pacote](#crie-um-novo-pacote) + * [Erros comuns](#erros-comuns) + * [Removendo um pacote](#removendo-um-pacote) + * [Linter](#linter) + * [Verificando](#verificando) +* [FAQ](#faq) + +## 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. + +* Build mais recente com [tipagem checada/analisada pelo linter](https://github.com/Microsoft/dtslint) de forma limpa: [![Build Status](https://dev.azure.com/definitelytyped/DefinitelyTyped/_apis/build/status/DefinitelyTyped.DefinitelyTyped?branchName=master)](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=1&branchName=master) +* Todos os pacotes tem seus tipos checados/são analisadas pelo linter no typescript@next: [![Build Status](https://dev.azure.com/definitelytyped/DefinitelyTyped/_apis/build/status/DefinitelyTyped.dtslint-runner?branchName=master)](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=2&branchName=master) +* Todos os pacotes estão sendo [publicados no NPM](https://github.com/microsoft/types-publisher) em menos de uma hora: [![Publish Status](https://dev.azure.com/definitelytyped/DefinitelyTyped/_apis/build/status/DefinitelyTyped.types-publisher-watchdog?branchName=master)](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=5&branchName=master) +* [typescript-bot](https://github.com/typescript-bot) esteve ativo no Definitely Typed [![Activity Status](https://dev.azure.com/definitelytyped/DefinitelyTyped/_apis/build/status/DefinitelyTyped.typescript-bot-watchdog?branchName=master)](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=6&branchName=master) +* [Atualizações do status da infraestrutura](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/44317) atual + +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 Gitter](https://gitter.im/DefinitelyTyped/DefinitelyTyped). + +[![Entre no chat em https://gitter.im/DefinitelyTyped/DefinitelyTyped](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/DefinitelyTyped/DefinitelyTyped?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) + +## O que são arquivos de declaração? + +Veja o [manual do TypeScript](http://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html). + +## Como eu consigo eles? + +### NPM + +Esse é o método aconselhável. Por exemplo: + +```sh +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 você não estiver usando módulos: + +```ts +/// +``` + +Veja mais no [manual](http://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html). + +Para um pacote "foo" do NPM, suas tipagens serão "@types/foo". +Se você não conseguir achar o pacote desejado, procure no [TypeSearch](https://microsoft.github.io/TypeSearch/). + +Se você mesmo assim não consegue achar o pacote, verifique se ele [inclui](http://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) 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 `/// `. + +#### Versões antigas do TypeScript (2.8 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 2.9 e acima são testadas. +Se você está usando as versões 2.0 a 2.8 do TypeScript, você ainda mode 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 + +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](https://github.com/typings/typings)~~ (use alternativas aconselhadas. O typings foi descontinuado) +* ~~[NuGet](http://nuget.org/packages?q=DefinitelyTyped)~~ (use alternativas aconselhadas. A publicação de tipos do NuGet DT foi desligada) + +Talvez você precise adicionar [referências](http://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) 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](http://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) 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`: + +```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](#faça-uma-pull-request) +e então siga as instruções para [editar um pacote existente](#edite-um-pacote-existente) ou +[criar um novo pacote](#crie-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](https://guides.github.com/activities/forking/) deste respositório, instale o [node](https://nodejs.org/), 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-uma-biblioteca-for-atualizada-para-uma-nova-versão-major-com-mudanças-drásticas-como-eu-devo-atualizar-a-declaração-de-tipos). + +* 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 teste 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`: + +```diff +- export function twoslash(body: string): string ++ export function twoslash(body: string, config?: { version: string }): string +``` + +`index-tests.ts`: +```diff +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](http://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) 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](https://github.com/Microsoft/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. + +O 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](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/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 a lista você mesmo, 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](https://github.com/DefinitelyTyped/dt-mergebot) 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 , Bob `. + - Ou se há muitas pessoas, pode ser em várias linhas: + ```typescript + // Definitions by: Alice + // Bob + // Steve + // John + ``` + +Uma vez por semana os Donos de definição são sincronizados para o arquivo [.github/CODEOWNERS](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/.github/CODEOWNERS), que é a nossa fonte da verdade. + +#### Erros comuns + +* Primeiro, siga as instruções do [manual](http://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html). +* 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](https://github.com/SamVerschueren/tsd#assertions), adicione a tag de exclusão `// prettier-ignore` para marcar linhas de código como exclusas da formatação: + ```tsx + // 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`: + 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(value: T): T;`. + Um exemplo onde não é aceitável: `function parseJson(json: string): T;`. + Exceção: `new Map()` é 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](http://www.typescriptlang.org/docs/handbook/functions.html#function-types) e `{ x: number, y: number }` para objetos. Se você não tem nenhuma certeza sobre o tipo, [`any`](http://www.typescriptlang.org/docs/handbook/basic-types.html#any) é a escolha correta, não `Object`. Se a única certeza sobre o tipo é que ele é algum objeto, use o tipo [`object`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#object-type), 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, mas 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](http://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) seus próprios tipos, os tipos devem ser removidos do Definitely Typed para evitar confusão. + +Você podem 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: + +```json +{ + "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](https://github.com/Microsoft/types-publisher/blob/master/dependenciesWhitelist.txt). + +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: +```js +{ + "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: + +```js +{ + "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`. + +```js +// $ExpectType void +f(1); + +// $ExpectError +f("um"); +``` + +Para mais detalhes, veja o arquivo readme do [dtslint](https://github.com/Microsoft/dtslint#write-tests). + +## 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](https://github.com/Microsoft/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](https://github.com/Microsoft/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](https://github.com/DefinitelyTyped/DefinitelyTyped/projects/5) 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 Gitter do Definitely Typed](https://gitter.im/DefinitelyTyped/DefinitelyTyped) 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 `` 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 ``. + +#### 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.](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json) +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](https://github.com/microsoft/types-publisher/blob/master/dependenciesWhitelist.txt). +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](https://github.com/DefinitelyTyped/DefinitelyTyped/labels/Definition%3ARequest). + +#### 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](https://github.com/Microsoft/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](https://github.com/chaijs/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](https://stackoverflow.com/questions/39415661/what-does-resolves-to-a-non-module-entity-and-cannot-be-imported-using-this) 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: +- você pode usar a [opção de compilador `--allowSyntheticDefaultImports`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-1-8.html#support-for-default-import-interop-with-systemjs) se o seu módulo suporta, em tempo de execução, um esquema de interop para módulos não-ECMAScript, isto é, se os imports padrão funcionam no seu ambiente (por exemplo, Webpack, SystemJS, esm). +- você pode usar a [opção de compilador `--esModuleInterop`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#support-for-import-d-from-cjs-form-commonjs-modules-with---esmoduleinterop) se você quiser que o TypeScript tome conta dos interop não-ECMAScript (desde o TypeScript 2.7). + +#### 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`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-1-8.html#support-for-default-import-interop-with-systemjs) +e [`--esModuleInterop`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#support-for-import-d-from-cjs-form-commonjs-modules-with---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 2.9 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`): `// TypeScript Version: 2.9`. + +#### Eu quero usar features do TypeScript 3.1 ou superior. + +Você pode usar o mesmo comentário `// TypeScript Version: 3.1` como descrito acima. +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](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-1.html#version-selection-with-typesversions). + +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: + +```json +{ + "private": true, + "types": "index", + "typesVersions": { + ">=3.1.0-0": { "*": ["ts3.1/*"] } + } +} +``` + +2. 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/`. + +3. Defina as opções `baseUrl` e `typeRoots` no `ts3.1/tsconfig.json` para os caminhos corretos. Eles devem ficar semelhantes a isto: +```json +{ + "compilerOptions": { + "baseUrl": "../../", + "typeRoots": ["../../"] + } +} +``` + +Você pode verificar [aqui](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/debounce-promise) e [aqui](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/create-html-element) 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](https://github.com/Microsoft/TSJS-lib-generator#readme). 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](https://semver.org/)_ + +Cada pacote do Definitely Typed é versionado ao ser publicado ao NPM. +O [types-publisher](https://github.com/Microsoft/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](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/1253faabf5e0d2c5470db6ea87795d7f96fef7e2/types/node/index.d.ts) para a versão `10.12.x`, no momento de escrita: + +```js +// Type definitions for Node.js 10.12 +// Project: http://nodejs.org/ +// Definitions by: Microsoft TypeScript +// Definitely Typed +// Alberto Schiabel +``` + +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! + +:exclamation: 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! :exclamation: + +#### 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](https://semver.org/) 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`](https://github.com/ReactTraining/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`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/1253faabf5e0d2c5470db6ea87795d7f96fef7e2/types/history/v2/tsconfig.json) está assim: + +```json +{ + "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](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/react-router/v2/tsconfig.json) 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. + +`/// ` 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](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html), e também [este arquivo de definição de exemplo](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/global-modifying-module-d-ts.html) 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](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/big.js/index.d.ts), 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](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/big.js/test) 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: + +```json +{ + "paths":{ + "@foo/bar": ["foo__bar"] + } +} +``` + + +#### O histórico do arquivo no GitHub parece incompleto. + +O GitHub não [suporta](http://stackoverflow.com/questions/5646174/how-to-make-github-follow-directory-history-after-renames) histórico para arquivos renomeados. Use [`git log --follow`](https://www.git-scm.com/docs/git-log) ou 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.