forked from DefinitelyTyped/DefinitelyTyped
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' into pubnub/updateTypes
- Loading branch information
Showing
2,598 changed files
with
28,778 additions
and
13,483 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| #!/usr/bin/env sh | ||
| . "$(dirname -- "$0")/_/husky.sh" | ||
|
|
||
| pnpm lint-staged --config .lintstagedrc.json --allow-empty |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| { "*": "pnpm dprint fmt --allow-no-files" } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -17,8 +17,10 @@ At the very least, you may want to `git clean -fdx` the repo (or `node ./scripts | |
| This section tracks the health of the repository and publishing process. | ||
| It may be helpful for contributors experiencing any issues with their PRs and packages. | ||
|
|
||
| * Most recent build [type-checked/linted](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dtslint) cleanly: [](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=1&branchName=master) | ||
| * All packages are type-checking/linting cleanly on typescript@next: [](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=8) | ||
| * Most recent build [type-checked/linted](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dtslint) cleanly: [ | ||
| ](https://github.com/DefinitelyTyped/DefinitelyTyped/actions/workflows/CI.yml?query=branch%3Amaster+event%3Apush) | ||
| * All packages are type-checking/linting cleanly on typescript@next: [ | ||
| ](https://github.com/DefinitelyTyped/DefinitelyTyped/actions/workflows/CI.yml?query=branch%3Amaster+event%3Aschedule) | ||
| * All packages are being [published to npm](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/publisher) in under an hour and a half: [](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=5&branchName=master) | ||
| * [typescript-bot](https://github.com/typescript-bot) has been active on Definitely Typed [](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=6&branchName=master) | ||
| * Current [infrastructure status updates](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/44317) | ||
|
|
@@ -149,14 +151,13 @@ We use a bot to let a large number of pull requests to DefinitelyTyped be handle | |
| You can clone the entire repository [as per usual](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository), but it's large and includes a massive directory of type packages. This will take some time to clone and may be unnecessarily unwieldy. | ||
| For a more manageable clone that includes _only_ the type packages relevant to you, you can use git's [`sparse-checkout`](https://git-scm.com/docs/git-sparse-checkout), [`--filter`](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt) and [`--depth`](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt) features. This will reduce clone time and improve git performance. | ||
| For a more manageable clone that includes _only_ the type packages relevant to you, you can use git's [`sparse-checkout`](https://git-scm.com/docs/git-sparse-checkout) and [`--filter`](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt) features. This will reduce clone time and improve git performance. | ||
| >:warning: This requires minimum [git version 2.27.0](https://git-scm.com/downloads), which is likely newer than the default on most machines. More complicated procedures are available in older versions, but not covered by this guide. | ||
| 1. `git clone --sparse --filter=blob:none --depth=1 <forkedUrl>` | ||
| 1. `git clone --sparse --filter=blob:none <forkedUrl>` | ||
| - `--sparse` initializes the sparse-checkout file so the working directory starts with only the files in the root of the repository. | ||
| - `--filter=blob:none` will exclude files, fetching them only as needed. | ||
| - `--depth=1` will further improve clone speed by truncating commit history, but it may cause issues as summarized [here](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/). | ||
| - `--filter=blob:none` will including all commit history but exclude files, fetching them only as needed. | ||
| 2. `git sparse-checkout add types/<type> types/<dependency-type> ...` | ||
| </details> | ||
|
|
@@ -219,14 +220,99 @@ This script uses [dtslint](https://github.com/microsoft/DefinitelyTyped-tools/tr | |
| Once you have all your changes ready, use `pnpm run test-all` to see how your changes affect other modules. | ||
| ##### @arethetypeswrong/cli (`attw`) checks | ||
| dtslint includes module format and `package.json` configuration checks from [@arethetypeswrong/cli](https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli). The checks run only if a SemVer-major-compatible implementation package can be found on npm to compare against the DefinitelyTyped package. (DefinitelyTyped packages marked as `"nonNpm": true` in their `package.json` are skipped.) | ||
| Many packages currently fail the `attw` checks and need to be fixed. To allow us to make incremental progress, failed `attw` checks do not fail the `dtslint` run when the package is listed in `failingPackages` in [`attw.json`](./attw.json), but they will still be reported in the `pnpm test my-package` output. If you fix the package, remove it from `failingPackages` so that `attw` checks can start failing `dtslint` runs. | ||
| All problems reported by `attw` have documentation linked in the output. Some rules of thumb to help avoid problems: | ||
| - The `package.json` in the DefinitelyTyped package must have matching `type` and `exports` fields if the implementation package uses them in its `package.json`. For example, if an implementation `package.json` looks like: | ||
| ```json | ||
| { | ||
| "name": "my-package", | ||
| "version": "1.0.1", | ||
| "type": "module", | ||
| "main": "dist/cjs/index.cjs", | ||
| "exports": { | ||
| ".": { | ||
| "import": "./dist/esm/index.js", | ||
| "require": "./dist/cjs/index.cjs" | ||
| }, | ||
| "./subpath": { | ||
| "import": "./dist/esm/subpath.js", | ||
| "require": "./dist/cjs/subpath.cjs" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| then the DefinitelyTyped `package.json` should look something like: | ||
| ```json5 | ||
| { | ||
| "name": "@types/my-package", | ||
| "version": "1.0.9999", | ||
| "type": "module", | ||
| "types": "index.d.ts", | ||
| "exports": { | ||
| ".": { | ||
| "import": "./index.d.ts", | ||
| "require": "./index.d.cts" | ||
| }, | ||
| "./subpath": { | ||
| "import": "./subpath.d.ts", | ||
| "require": "./subpath.d.cts" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| Notice that each `exports` subpath is reflected, and each JavaScript file has a corresponding declaration file with a matching file extension—a `.d.ts` file types a `.js` file, not a `.mjs` or `.cjs` file! | ||
| - When the implementation package uses `module.exports = ...`, the DefinitelyTyped package should use `export =`, not `export default`. (Alternatively, if the `module.exports` is just an object of named properties, the DefinitelyTyped package can use a series of named exports.) The most common obstacle to correcting this problem is confusion about how to export types in addition to the primary export. For example, assume these types are incorrectly using `export default`: | ||
| ```ts | ||
| export interface Options { | ||
| // ... | ||
| } | ||
| export default function doSomething(options: Options): void; | ||
| ``` | ||
| Changing the `export default` to an `export =` creates an error: | ||
| ```ts | ||
| export interface Options { | ||
| // ... | ||
| } | ||
| declare function doSomething(options: Options): void; | ||
| export = doSomething; | ||
| // ^^^^^^^^^^^^^^^^^ | ||
| // Error: An export assignment cannot be used in a module with other exported elements. | ||
| ``` | ||
| To fix this, move the types inside a namespace with the same name as the function: | ||
| ```ts | ||
| declare namespace doSomething { | ||
| export interface Options { | ||
| // ... | ||
| } | ||
| } | ||
| declare function doSomething(options: doSomething.Options): void; | ||
| export = doSomething; | ||
| ``` | ||
| If you need help fixing a problem, please ask in the DefinitelyTyped channel on the [TypeScript Community Discord server](https://discord.gg/typescript). | ||
| #### Naming | ||
| If you are adding typings for an npm package, create a directory with the same name. | ||
| If the package you are adding typings for is not on npm, make sure the name you choose for it does not conflict with the name of a package on npm. | ||
| If the package you are adding typings for is not on npm, set `"nonNpm": true` in the `package.json`, and make sure the name you choose for it does not conflict with the name of a package on npm. | ||
| (You can use `npm info <my-package>` to check for the existence of the `<my-package>` package.) | ||
| If a non-npm package conflicts with an existing npm package try adding -browser to the end of the name to get `<my-package>-browser`. | ||
| #### `<my-package>-tests.ts` | ||
| There should be a `<my-package>-tests.ts` file, which is considered your test file, along with any `*.ts` files it imports. | ||
|
|
@@ -488,6 +574,8 @@ Then they are wrong and we've not noticed yet. You can help by submitting a pull | |
| Yes, using [dprint](https://dprint.dev). | ||
| We recommend using a [dprint extension for your editor](https://dprint.dev/install/#editor-extensions). | ||
| Alternatively, you can enable a git hook which will format your code automatically. Run `pnpm run setup-hooks`. Then, when you commit, `dprint fmt` command will be executed on changed files. If you take advantage of [partial clone](#partial-clone), make sure to call `git sparse-checkout add .husky` to check out the git hooks before running the `setup-hooks` script. | ||
| Pull requests do not require correct formatting to be merged. | ||
| Any unformatted code will be automatically reformatted after being merged. | ||
|
|
@@ -648,6 +736,13 @@ Another package may select this version by specifying: | |
|
|
||
| Also, `/// <reference types=".." />` will not work with path mapping, so dependencies must use `import`. | ||
|
|
||
| #### How do breaking type changes work if type declaration packages closely track the library package's version? | ||
|
|
||
| `@types` packages always type packages of the same version, so `@types/[email protected]` are for `[email protected]`. | ||
| As a consequence, all changes, breaking or not, are published as patch revisions, unless paired with a major/minor bump to change the package version being targeted (coincidentally or not). | ||
|
|
||
| When it comes to breaking changes, DT maintainers consider the popularity of the package, the upsides of the proposed breaking change, the effort that will be required for users to fix their code, and whether the change could reasonably be delayed until it can be synced with a major bump of the upstream library. | ||
|
|
||
| #### How do I write definitions for packages that can be used globally and as a module? | ||
|
|
||
| The TypeScript handbook contains excellent [general information about writing definitions](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html) and also [this example definition file](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/global-modifying-module-d-ts.html) which shows how to create a definition using ES6-style module syntax, while also specifying objects made available to the global scope. This technique is demonstrated practically in the [definition for `big.js`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/big.js/index.d.ts), which is a library that can be loaded globally via script tag on a web page or imported via require or ES6-style imports. | ||
|
|
||
Oops, something went wrong.