为什么要在DefinitelyTyped上为Javascript库发布TypeScript声明文件？

Question

我在npm上发布了两个Javascript库，用户要求它们都提供TypeScript类型定义。我自己不使用TypeScript，也没有计划用TypeScript重写这些库，但是我仍然想添加类型定义文件，如果只是为了更好地完成IntelliSense代码。我正在寻找一些建议。

我从阅读DefinitelyTyped project的文档和publishing a declaration file for an npm package的文档开始。这两个来源都指出，对于非TypeScript编写的项目，首选方法是“在npm上发布到@types组织”。

为什么与通过types中的package.json字段与库本身一起发布类型定义相比，它为什么更受青睐？我真的看不到让第三方参与其中的意义。这样看来，更新类型定义并对其进行版本控制似乎更加复杂。

上面引用的文档中的语录（强调我的意思）

来自DefinitelyTyped：

  

如果您是库作者，并且您的包是用TypeScript编写的，则捆绑自动生成的声明文件而不是发布到“确定类型”中。

来自typescriptlang.org：

  

现在您已经按照本指南的步骤编写了声明文件，现在是将其发布到npm的时候了。可以将声明文件发布到npm的主要方法有两种：

     

  
• 与您的npm软件包捆绑在一起，或
  
• 在npm上发布到@types组织。
  

     

如果您的软件包是使用TypeScript 编写的，则倾向于采用第一种方法。使用--declaration标志生成声明文件。这样，您的声明和JavaScript将始终保持同步。

     

如果您的软件包不是不是用TypeScript编写的，则第二是首选方法。

两个人都说：

if (isAuthor && lang === "typescript")
  bundle();
else
  publishOnDefinitelyTyped();

Answer 1

类型声明发布指南在某些方面似乎有些过时和稀疏。

我将尝试比较两种情况。

1。与npm软件包捆绑在一起的类型

1.1。从包装消费者的角度来看

1.1.1。优点

通常，由于简化了依赖关系管理，软件包捆绑类型更加方便。

• 不需要其他@types依赖项（添加程序包依赖项）
• 无需在软件包及其类型之间同步版本（升级软件包依赖性）

1.1.2。缺点

• 限制使用软件包捆绑类型的方式

  涉及使用者需要修改或替换类型声明的情况。

  在采用过硬的构建设置的项目中，该过程可能会出现很多问题， 由于配置选项已经很有限。

1.2。从软件包作者的角度来看

1.2.1。优点

• 图书馆所有者可以根据自己的意愿随时随地或按计划发布补丁和类型声明的更新
• 对第三方或外部类型依赖项没有限制
• 提供对多个版本的并发支持的方式与对实际代码的执行方式相同

1.2.2。缺点

与包捆绑在一起的类型意味着实际上每次发布一个版本都会发布两个API合同。

示例：

让我们假设一个旨在符合semver版本控制的库。

• 最新版本-> 1.0.0
• 主要版本因重大更改而发生变化-> 2.0.0
• 报告了类型声明中的一个严重错误，针对具有打字稿项目的一组用户，该版本已被破坏
• 类型修复是一项重大变化

下一版本的选项是：

A。 2.X.X->违反了用于类型声明的semver规则

B。 3.0.0->违反了实际代码的存储规则

这种情况可能有很多变化。

2。发布到确定类型的存储库

2.1。从包装消费者的角度来看

2.1.1。优点

• 通过删除@types依赖项来轻松退出

2.1.2。缺点

• 程序包使用者负责使程序包和相关类型的版本保持同步

2.2。从软件包作者的角度来看

2.2.1。优点

• 类型对软件包的发布周期没有影响

• DT回购具有两个额外的特征：

  • 用于类型声明和类型测试的dts-lint库
  • 深入的性能和编译器占用空间分析，包括最新软件包版本和PR修改后的软件包之间的区别。

  第一个工具可以轻松地合并到另一个软件包仓库中。 我不确定分析是否可以在自己的存储库中复制，但是其中包含很多有价值的数据。

2.2.2。缺点

• 支持过去版本的非标准方式

• 类型发布时间表受DT审查和发布周期限制

  假设DefinitelyTyped PR创建者是@types包所有者，通常 PR合并之前需要一到两天。此外，还有一个未成年人 在类型发布者更新PR相关的@types npm软件包之前延迟。

  在PR是作者对给定程序包的第一笔稿件中，还涉及其他审查过程。

• 使用外部依赖项

  TypeScript手册说：

    

  如果您的类型定义依赖于另一个程序包：

       

  请勿将其与您的文件合并在一起，将它们保存在各自的文件中。

       

  也不要复制包装中的声明。

       

  如果不打包其声明文件，请依赖npm类型声明包。

  从冗余实用程序类型的数量来看，它们几乎不受尊重。

  允许类型声明的作者使用相邻的DT存储库类型。 取决于此列表以外的软件包，要求它们位于“类型-发布者”白名单中。

  可以通过向类型发布者提交PR来将新软件包列入白名单。 我的PR合并花了两个多星期。我不知道这是平常的，因为我提交了一份PR。

• DT回购量

  我没有跨IDE比较或经验，但是就JetBrains IDE而言，完全索引的DT repo项目的内存占用使该IDE无法使用。

  禁用更改的重新编译在一定程度上有所帮助。可以通过删除与目标软件包无关的DT回购内容来解决令人沮丧的IDE体验。