Definitely Typed

El repositorio de definiciones de TypeScript de alta calidad.

You can also read this README in English, , , , Portugus, Italiano and !

Vea tambin el sitio web definitelytyped.org, aunque la informacin en este README est ms actualizada.

Qu son los declaration files?

Vea el Manual de TypeScript.

Cmo los obtengo?

npm

Este es el mtodo preferido. Solo est disponible para usuarios TypeScript 2.0+. Por ejemplo:

sh npm install --save-dev @types/node

Los types deberan ser incluidos automticamente por el compilador. Vea ms en el manual.

Para un paquete npm "foo", estos typings estarn en "@types/foo". Si no puedes encontrar tu paquete, bscalo en TypeSearch.

Si an no puedes encontrarlo, comprueba si el paquete ya incluye los typings. Esto es provisto usualmente en el campo "types" o "typings" en el package.json, o solo busca por cualquier archivo ".d.ts" en el paquete e inclyelo manualmente con un /// <reference path="" />.

Support window

Cmo puedo contribuir?

Definitely Typed solo trabaja gracias a contribuidores como t!

Prueba

Antes de compartir tu mejora con el mundo, selo usted mismo.

Prueba editando un paquete existente

Para agregar nuevas funciones puedes usar el module augmentation. Tambin puedes editar directamente los types en node_modules/@types/foo/index.d.ts, o copiarlos de ah y seguir los pasos explicados a continuacin.

Prueba un nuevo paquete

Aade a tu tsconfig.json:

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

(Tambin puedes usar src/types.) Crea un types/foo/index.d.ts que contenga declaraciones del mdulo "foo". Ahora deberas poder importar desde "foo" a tu cdigo y te enviar a un nuevo tipo de definicin. Entonces compila y ejecuta el cdigo para asegurarte que el tipo de definicin en realidad corresponde a lo que suceda en el momento de la ejecucin. Una vez que hayas probado tus definiciones con el cdigo real, haz un PR luego sigue las instrucciones para editar un paquete existente o crear un nuevo paquete.

Haz un pull request

Una vez que hayas probado tu paquete, podrs compartirlo en Definitely Typed.

Primero, bifurca este repositorio, instala node, y luego ejecuta el comando npm install.

Editar un paquete existente

• cd types/<package to edit>
• Haz cambios. Recuerda editar las pruebas. Si realiza cambios importantes, no olvide actualizar una versin principal.
• Tambin puede que quieras aadirle la seccin "Definitions by" en el encabezado del paquete.
  • Esto har que seas notificado (a travs de tu nombre de usuario en GitHub) cada vez que alguien haga un pull request o issue sobre el paquete.
  • Haz esto aadiendo tu nombre al final de la lnea, as como en // Definitions by: Alice <https://github.com/alice>, Bob <https://github.com/bob>.
  • O si hay ms personas, puede ser multiline typescript // Definitions by: Alice <https://github.com/alice> // Bob <https://github.com/bob> // Steve <https://github.com/steve> // John <https://github.com/john>
• Ejecuta npm test <package to test>.

Cuando hagas un PR para editar un paquete existente, dt-bot deber @-mencionar a los autores previos. Si no lo hace, puedes hacerlo en el comentario asociado con el PR.

Crear un nuevo paquete

Si eres el autor de la librera, o puedes hacer un pull request a la biblioteca, bundle types en vez de publicarlo en Definitely Typed.

Si ests agregando typings para un paquete npm, crea un directorio con el mismo nombre. Si el paquete al que le ests agregando typings no es para npm, asegrate de que el nombre que escojas no genere problemas con el nombre del paquete en npm. (Puedes usar npm info <my-package> para verificar la existencia del paquete <my-package>.)

Tu paquete debera tener esta estructura:

| Archivo | Propsito | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | index.d.ts | Este contiene los typings del paquete. | | <my-package>-tests.ts | Este contiene una muestra del cdigo con el que se realiza la prueba de escritura. Este cdigo no es ejecutable, pero s es type-checked. | | tsconfig.json | Este permite ejecutar tsc dentro del paquete. |

Generalas ejecutando npm install -g dts-gen y dts-gen --dt --name <my-package> --template module. Ve todas las opciones en dts-gen.

Los miembros de Definitely Typed frecuentemente monitorean nuevos PRs, pero ten en mente que la cantidad de PRs podran ralentizar el proceso.

Para un buen paquete de ejemplo, vea base64-js.

Remover un paquete

Cuando un paquete bundles sus propios tipos, estos tipos debern ser removidos de Definitely Typed para evitar que generen confusin.

Se puede remover ejecutando pnpm run not-needed -- <typingsPackageName> <asOfVersion> [<libraryName>].

• <typingsPackageName>: Este es el nombre del directorio que tienes que eliminar.
• <asOfVersion>: Un stub ser publicado a @types/<typingsPackageName> con esta versin. Debera ser ms grande que cualquier versin publicada actualmente.
• <libraryName>: Un nombre descriptivo de la librera, p.ej. "Angular 2" en vez de "angular2". (Si es omitido, ser idntico a <typingsPackageName>.)

Cualquier otro paquete en Definitely Typed que referencie el paquete eliminado deber ser actualizado para referenciar los tipos bundled. para hacer esto, aade package.json con "dependencies": { "<libraryName>": "x.y.z" }.

Si un paquete nunca estuvo en Definitely Typed, no ser necesario aadirlo a notNeededPackages.json.

Running tests

Realiza una prueba ejecutando npm test <package to test> donde <package to test> es el nombre de tu paquete. Este script utiliza dtslint.

Naming

Si ests agregando typings para un paquete npm, crea un directorio con el mismo nombre. Si el paquete al que le ests agregando typings no es para npm, asegrate de que el nombre que escojas no genere problemas con el nombre del paquete en npm. (Puedes usar npm info <my-package> para verificar la existencia del paquete <my-package>.)

Si un non-npm package entra en conflicto con un paquete npm existente, intenta aadir -browser al final del nombre para obtener <my-package>-browser.

<my-package>-tests.ts

Debera haber un archivo <my-package>-tests.ts, el cual es considerado tu archivo de prueba, junto con cualquier archivo *.ts que importe. Si no ves ningn archivo de prueba en la carpeta del mdulo, crea un <my-package>-tests.ts. Estos archivos son usados para validar la API exportada desde los archivos *.d.ts los cuales son enviados como @types/<my-package>.

Los cambios a los archivos *.d.ts deberan incluir un cambio correspondiente en un archivo *.ts el cual muestre la API siendo usada, para que alguien no rompa accidentalmente el cdigo en el que dependes. Si no ves ningn archivo de prueba en la carpeta del mdulo, crea un <my-package>-tests.ts.

Por ejemplo, este cambio a una funcin en un archivo .d.ts aadiendo un nuevo parmetro a una funcin:

index.d.ts:

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

<my-package>-tests.ts:

```diff import {twoslash} from "./"

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

• // Handle options param
• const resultWithOptions = twoslash("//", { version: "3.7" })
• // When the param is incorrect
• // @ts-expect-error
• const resultWithOptions = twoslash("//", { }) ```

Si ests preguntndote por dnde empezar con el cdigo de prueba, los ejemplos en el README del mdulo son un buen lugar para comenzar.

Puedes validar tus cambios con npm test <package to test> desde la raz de este repositorio, el cual toma en cuenta los archivos cambiados.

Para afirmar que una expresin es de un tipo dado, utiliza $ExpectType. Para afirmar que una expresin causa un error de compilacin, utiliza @ts-expect-error.

```js // $ExpectType void f(1);

// @ts-expect-error f("one"); ```

Para ms detalles, vea el dtslint readme.

Linter: .eslintrc.json

El archivo de configuracin del linter, tslint.json debera contener { "extends": "@definitelytyped/dtslint/dt.json" }, y no reglas adicionales.

Si por alguna razn alguna regla necesita ser deshabilitada, deshabiltala para esa lnea especfica usando // tslint:disable-next-line:[ruleName] no para todo el paquete, para que la deshabilitacin pueda ser revisada. (Hay algunas configuraciones de lint heredadas que tienen contenido adicional, pero esto no debera ocurrir en un nuevo trabajo.)

tsconfig.json

tsconfig.json debera tener noImplicitAny, noImplicitThis, strictNullChecks, y strictFunctionTypes configurados a true.

Tambin puedes configurar el tsconfig.json para aadir nuevos archivos, para agregar un "target": "es6" (necesitado por las funciones asncronas), para agregar a la "lib", o para agregar la opcin de compilacin "jsx".

package.json

Normalmente no lo necesitars. Cuando publicas un paquete normalmente nosotros automticamente crearemos un package.json para eso. Un package.json puede ser incluido por el bien de especificar dependencias. Aqu tienen un ejemplo. No aceptamos otros campos, tales como "description", para que sean definidos manualmente. Adems, si necesitas referencia a una versin anterior de typings, debes hacerlo aadiendo "dependencies": { "@types/<libraryName>": "x.y.z" } al package.json.

OTHER_FILES.txt

Si un archivo no es probado ni referenciado en index.d.ts, adelo a un archivo llamado OTHER_FILES.txt. Este archivo es una lista de otros archivos que necesitan ser incluidos en el paquete de typings, un archivo por lnea.

Errores comunes

• Primero, sigue el consejo del manual.
• Formatear: Utiliza 4 espacios.
• function sum(nums: number[]): number: Utiliza ReadonlyArray si una funcin no escribe a sus parmetros.
• interface Foo { new(): Foo; }: Este define el tipo de objeto que esten nuevos. Probablemente quieras declare class Foo { constructor(); }.
• const Class: { new(): IClass; }: Prefiere usar una declaracin de clase class Class { constructor(); } En vez de una nueva constante.
• getMeAT<T>(): T: Si un tipo de parmetro no aparece en los tipos de ningn parmetro, no tienes una funcin genrica, solo tienes un afirmacin del tipo disfrazado. Prefiera utilizar una afirmacin de tipo real, p.ej. getMeAT() as number. Un ejemplo donde un tipo de parmetro es aceptable: function id<T>(value: T): T;. Un ejemplo donde no es aceptable: function parseJson<T>(json: string): T;. Una excepcin: new Map<string, number>() est bien.
• Utilizando los tipos Function y Object casi nunca es una buena idea. En 99% de los casos es posible especificar un tipo ms especfico. Los ejemplos son (x: number) => number para funciones y { x: number, y: number } para objetos. Si no hay certeza en lo absoluto del tipo, any es la opcin correcta, no Object. Si el nico hecho conocido sobre el tipo es que es un objecto, usa el tipo object, no Object o { [key: string]: any }.
• var foo: string | any: Cuando es usado any en un tipo de unin, el tipo resultante todava es any. As que mientras la porcin string de este tipo de anotacin puede verse til, de hecho, no ofrece ningn typechecking adicional ms que un simple any. Dependiendo de la intencin, una alternativa aceptable puede ser any, string, o string | object.

Propietarios de Definiciones

DT tiene el concepto de "Propietarios de Definiciones" que son personas que desean mantener la calidad de los tipos de un mdulo en particular.

• Agregarte a la lista har que recibas notificaciones (a travs de tu nombre de usuario de GitHub) cada vez que alguien haga una solicitud de extraccin o informe sobre el paquete.
• Tus revisiones de solicitudes de extraccin tendrn una mayor importancia para el bot que mantiene este repositorio.
• Los mantenedores de DT confan en los propietarios de las definiciones para asegurar un ecosistema estable, as que por favor, no te agregues ligeramente.

Para agregarte como Propietario de Definiciones:

• Agrega tu nombre al final de la lnea, como en // Definitions by: Alice <https://github.com/alice>, Bob <https://github.com/bob>.
• O si hay ms personas, puede ser en varias lneas typescript // Definitions by: Alice <https://github.com/alice> // Bob <https://github.com/bob> // Steve <https://github.com/steve> // John <https://github.com/john>

Una vez a la semana, los Propietarios de Definiciones se sincronizan con el archivo .github/CODEOWNERS, que es nuestra fuente de verdad.

FAQ

Cul es exactamente la relacin entre este repositorio y los paquetes de @types en npm?

La master branch es automticamente publicada en el alcance de los @types en npm gracias a los DefinitelyTyped-tools.

He enviado un pull request. Cunto tardar en ser merged?

Esto depende, pero la mayora de los pull requests sern merged en alrededor de una semana. PRs que hayan sido aprobados por un autor listado en el encabezado de las definiciones usualmente son merged ms rpidamente; PRs para nuevas definiciones tomarn ms tiempo ya que requieren ms revisiones de los mantenedores. Cada PR es revisado por un miembro de TypeScript o Definitely Typed antes de ser merged, por favor s paciente debido a que factores humanos pueden causar retrasos. Revisa el Pull Request Status Board para ver el progreso mientras los mantenedores trabajan en los PRs abiertos.

Mi PR ha sido merged; cundo ser actualizado el paquete de @types npm?

Los paquetes npm debern ser actualizados en unas cuantas horas. Si ha pasado ms de 24 horas, menciona a @RyanCavanaugh y/o a @andy-ms en el PR para investigar.

Estoy escribiendo una definicin que depende de otra definicin. Debera utilizar <reference types="" /> o una import?

Si el mdulo al cual te ests refiriendo es un mdulo externo (utiliza export), utilice una import. Si el mdulo al cual te refieres es un mdulo ambiente (utiliza declare module, o simplemente declara las globales), utilice <reference types="" />.

Algunos paquetes no tienen tslint.json, y algunos tsconfig.json no contienen "noImplicitAny": true, "noImplicitThis": true, o "strictNullChecks": true.

Entonces estn equivocados. Puedes ayudar enviando un pull request para arreglarlos.

Puedo pedir una definition?

Aqu estn las definiciones solicitadas actualmente.

Qu pasa con las type definitions para el DOM?

Si las types son parte de los estndares web, estas debern ser contribuidas a TSJS-lib-generator para que se hagan parte de la librera predeterminada lib.dom.d.ts.

Un paquete utiliza export =, pero prefiero utilizar las import predeterminadas. Puedo cambiar export = por export default?

Si el import predeterminado trabaja en tu ambiente, considera hacer un cambio en la opcin de compilacin --allowSyntheticDefaultImports opcin compilar. No cambies la type definition si es preciso. Para un paquete npm, export = es exacto si node -p 'require("foo")' es la export, y export default es exacto si node -p 'require("foo").default' es el export.

Quiero usar las caractersticas de TypeScript 3.3 o superior.

Entonces debers aadir un comentario a la ltima lnea de la definicin en el encabezado (despues de // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped): // Minimum TypeScript Version: 3.3.

Quiero aadir un DOM API que no est presente en TypeScript por defecto.

Esto puede pertenecer a TSJS-Lib-Generator. Vea las guas all. Si el estndar sigue siendo un borrador, este pertenece aqu. Utilice un nombre que empiece con dom- e incluya un link al estndar como el "Project" con el link en el encabezado. Cuando ya no sea un borrador, lo podremos eliminar desde DefinitelyType y hacer obsoleto el paquete @types asociado.

Quiero actualizar un paquete a una nueva versin principal

Si planeas continuar actualizando la versin anterior del paquete, puedes crear una subcarpeta con la versin actual p.ej. v2, y copia los archivos existentes. Si es as, necesitars:

1. Actualiza las rutas relativas en tsconfig.json al igual que tslint.json.
2. Aadir reglas de mapeo de rutas para asegurarte de que la prueba se est ejecutando contra la versin prevista.

Por ejemplo history v2 tsconfig.json se ve as:

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

Si hay otros paquetes en Definitely Typed que son incompatibles con la nueva versin, necesitars mapear las rutas a la versin anterior. Tambin deber hacer esto para los paquetes que dependen de paquetes que dependen de una version anterior.

Por ejemplo, browser-sync depende de micromatch@2, as que browser-sync tsconfig.json tiene una ruta mapeada a "micromatch": [ "micromatch/v2" ]; transitivo as mismo, browser-sync-webpack-plugin (que depende de browser-sync) tambin aade una ruta mapeada en su tsconfig.json.

Adems, /// <reference types=".." /> no trabajar con rutas mapeadas, as que las dependencias debern utilizar import.

Cmo escribo definitions para paquetes que pueden ser usados globalmente y como un mdulo?

El manual de TypeScript contiene excelente informacin general para escribir definiciones, adems este archivo de definiciones de ejemplo el cual muestra como crear una definicin utilizando la sintaxis de mdulo en ES6, asi como tambin especificando objetos que son disponibles en el alcance global. Esta tcnica es demostrada prcticamente en la definicin para big.js, el cual es una librera que puede ser cargada globalmente a travs de una etiqueta script en una pgina web, o importada va require o imports estilo ES6.

Para probar como puede ser usada tu definicin cuando se refieren globalmente o como un mdulo importado, crea una carpeta test, y coloca dos archivos de prueba en l. nombra uno YourLibraryName-global.test.ts y el otro YourLibraryName-module.test.ts. El archivo de prueba global debe ejercer la definicin de acuerdo como va a ser usado en un script cargado en una pgina web donde la librera estar disponible en el alcance global - en este escenario no debes de especificar la sentencia de import. El archivo mdulo de prueba debe de ejercer la definicin de acuerdo a como va a ser utilizado cuando sea importado (incluyendo las sentencias import). Si especificas una propiedad files en tu archivo tsconfig.json, asegurate de incluir ambos archivos de prueba. Un ejemplo prctico de esto es tambin disponible en la definicin de big.js.

Por favor tenga en cuenta que no es necesario para ejercer plenamente la definicin en cada archivo de prueba - Es suficiente con probar solo los elementos globalmente accesibles en la prueba de archivos globales y ejercer la definicin en el mdulo del archivo de prueba, o viceversa.

Qu pasa con paquetes scoped?

Types para un paquete scoped @foo/bar debern ir en types/foo__bar. tenga en cuenta el doble guin bajo.

Cuando dts-gen es utilizado como scaffold en un paquete scoped, las propiedades paths debern ser adaptadas manualmente en el paquete generado tsconfig.json para referenciar correctamente el paquete scoped:

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

Debera aadir un namespace que no exporte un mdulo que utilice que utilice imports estilo ES6?

Algunos paquetes, como chai-http, exportan una funcin.

importar este mdulo con un ES6 style import de forma import * as foo from "foo"; conduce al error:

error ts2497: El mdulo 'foo' se resuelve en una entidad que no es un mdulo y no se puede importar mediante esta construccin

Este error puede ser suprimido al unir la declaracin de una funcin con un namespace vaco del mismo nombre pero esta prctica no es recomendable. Esto es un citado comn Respuestas de Stack Overflow con respecto a este asunto.

Es ms apropiado importar este mdulo utilizando la sintaxis import foo = require("foo");, o utilizando una importacin predeterminada como import foo from "foo"; si usas la bandera --allowSyntheticDefaultImports si la ejecucin de tu mdulo soporta un esquema de interoperacin para mdulos no ECMAScript como tal.

Licencia

Este proyecto es licenciado bajo la licencia MIT.

Los derechos de autor de cada archivo de definicin son respectivos de cada contribuidor listado al comienzo de cada archivo de definicin.