typescript - 如何为包中的类型指定最低 Typescript 版本？

Question

我正在发布一个 Typescript 包，连同它的 Javascript 编译和一个 types.d.ts 文件。

我对 Typescript 的开发依赖是 ^4.5。

"devDependencies": {
  "typescript": "^4.5"
}

我有一个用户在最近的更新中报告了一个破损，因为他们使用的是 Typescript 4.1，而我的类型开始使用 Typescript 4.4 中添加的功能。

我不认为我可以使用 peerDependency，因为 Typescript 的使用是可选的。

如何在我的包中注册最低预期版本的 Typescript？

Answer 1

如果您愿意做一些额外的工作来添加对旧的 TypeScript 类型语法的支持，那么您晚上不必这样做。

无需额外工作的选项

如果您不想投入这项工作，您可以将其作为一项重大更改来接受，以停止支持旧的 .d.ts 文件语法。如果您的包裹遵循semantic versioning ，在你的变更日志中修改主要版本和文档，有一个重大变化，即打字现在需要 typescript 4.4 或更高版本。这与 semver-ts.org in their "supported compiler versions" section 上的建议一致.

额外的工作

您可以在发出的 .d.ts 文件中支持多种 typescript 语言版本。

参见 the "'Downleveling' Types" section of semver-ts.org :

When a new version of TypeScript includes a backwards-incompatible change to emitted type definitions, as they did in 3.7, the strategy of changing the types directly may not work. However, it is still possible to provide backwards-compatible types, using the combination of downlevel-dts and typesVersions. (In some cases, this may also require some manual tweaking of types, but this should be rare for most packages.)

• The downlevel-dts tool allows you to take a .d.ts file which is not valid for an earlier version of TypeScript (e.g. the changes to class field emit mentioned in Breaking Changes), and emit a version which is compatible with that version. It supports targeting all TypeScript versions later than 3.4.

• TypeScript supports using the typesVersions key in a package.json file to specify a specific set of type definitions (which may consist of one or more .d.ts files) which correspond to a specific TypeScript version.

The recommended flow would be as follows:

1. Add downlevel-dts, npm-run-all, and rimraf to your dev dependencies:

   npm install --save-dev downlevel-dts npm-run-all rimraf
   

2. Create a script to downlevel the types to all supported TypeScript versions:

   # scripts/downlevel.sh
   npm run downlevel-dts . --to 3.7 ts3.7
   npm run downlevel-dts . --to 3.8 ts3.8
   npm run downlevel-dts . --to 3.9 ts3.9
   npm run downlevel-dts . --to 4.0 ts4.0
   

3. Update the scripts key in package.json to generate downleveled types generated by running downlevel-dts on the output from tsc, and to clean up the results after publication. For example, using ember-cli-typescript’s tooling:

   {
     "scripts": {
   -   "prepublishOnly": "ember ts:precompile",
   +   "prepublish:types": "ember ts:precompile",
   +   "prepublish:downlevel": "./scripts/downlevel.sh",
   +   "prepublishOnly": "run-s prepublish:types prepublish:downlevel",
   -   "postpublish": "ember ts:clean",
   +   "clean:ts": "ember ts:clean",
   +   "clean:downlevel": "rimraf ./ts3.7 ./ts3.8 ./ts3.9 ./ts4.0",
   +   "clean": "npm-run-all --aggregate-output --parallel clean:*",
   +   "postpublish": "npm run clean",
     }
   }
   

4. Add a typesVersions key to package.json, with the following contents:

   {
     "types": "index.d.ts",
     "typesVersions": {
       "3.7": { "*": ["ts3.7/*"] },
       "3.8": { "*": ["ts3.8/*"] },
       "3.9": { "*": ["ts3.9/*"] },
       "4.0": { "*": ["ts4.0/*"] },
     }
   }
   

   This will tell TypeScript how to use the types generated by this process. Note that we explicitly include the types key so TypeScript will fall back to the defaults for 3.9 and higher.
5. If using the files key in package.json to specify files to include (unusual but not impossible for TypeScript-authored packages), add each of the output directories (ts3.7, ts3.8, ts3.9, ts4.0) to the list of entries.

Now consumers using older versions of TypeScript will be buffered from the breaking changes in type definition emit.

If the community adopts this practice broadly we will want to invest in tooling to automate support for managing dependencies, downleveling, and type tests. However, the core constraints of this RFC do not depend on such tooling existing, and the exact requirements of those tools will emerge organically as the community begins implementing this RFC's recommendations.

使用这种方法可以降级的事物有一些局限性，因此请务必阅读 downlevel-dts 的文档以确保您不会遇到这些边缘情况。