几个月前，JavaScript 生态系统出现了一些问题。

这是 Svelte 代码库从 TypeScript 迁移到 JavaScript 的过程。

是的，这不是一个错字。

Svelte 在版本 3 到版本 4 的升级过程中，用 JavaScript 进行了重写，并将现有的 TypeScript 代码推送到了分支version-3。

尽管 Svelte 社区对 Rich Harris 和 Svelte 团队的这一决定非常担忧，但自 Svelte 4 发布以来已经过去了两个月，他们已经证明了他们的选择是正确的。

在本文中，我们将探讨如何使用 JSDoc 编写 npm 包以及它如何显着增强开发人员体验。

例子

单独用文字来解释多段源代码似乎很难，所以我准备了StackBlitz和Github链接。

代码分析

从package.json项目根目录中的文件开始，让我们快速浏览一下重要部分

// ./package.json  "scripts": {    "dts": "pnpm -r dts",    "lint": "tsc && eslint --fix .",    "test": "vitest run"  },

该文件中package.json包含三个脚本。

dts用于.d.ts使用 JSDoc 生成文件，lint执行编码约定检查，并test用于运行测试。

// ./pnpm-workspace.yamlpackages:  - 'packages/*'

该pnpm-workspace.yaml文件是用于管理本地包的配置文件。

// ./tsconfig.json    "module": "ES6",    "moduleResolution": "Node",    "noEmit": true,

在该tsconfig.json文件中，module和moduleResolution选项分别设置为ES6和Node，用于兼容性检查。此外，该noEmit选项设置为true仅在运行命令时执行类型检查pnpm lint。

// ./.eslintrc.json  "ignorePatterns": ["**/@types/**/*.d.ts"]

该文件夹中的文件@types是自动生成的，因此它们被排除在 eslint 检查之外。

在syntax和test文件夹中，创建文件用于类型检查和测试目的。库包位于该packages文件夹下。

// ./packages/my-lib/package.json  "exports": {    ".": {      "default": "./index.js",      "types": "./@types/index.d.ts"    },    "./math": {      "default": "./src/math/index.js",      "types": "./@types/src/math/index.d.ts"    },    "./string": {      "default": "./src/string/index.js",      "types": "./@types/src/string/index.d.ts"    },    "./type-test": {      "default": "./src/type-test/index.js",      "types": "./@types/src/type-test/index.d.ts"    },    "./@types": "./src/public.d.ts"  },  "typesVersions": {    "*": {      "*": ["@types/index.d.ts"],      "math": ["@types/src/math/index.d.ts"],      "string": ["@types/src/string/index.d.ts"],      "type-test": ["@types/src/type-test/index.d.ts"],      "@types": ["src/public.d.ts"]    }  },

要在库中定义子路径模块，我们需要在package.json文件中使用多个选项。

如果用户设置moduleResolution为Node16或NodeNextin tsconfig.json，exports则仅该选项就足够了。

不过，对于没有此配置的用户，我们还需要设置该typesVersions选项。

// ./packages/my-lib/tsconfig.json{  "compilerOptions": {    "allowJs": true,    "allowSyntheticDefaultImports": true,    "checkJs": true,    "declaration": true,    "declarationDir": "@types",    "declarationMap": true,    "emitDeclarationOnly": true,    "lib": ["ES2020", "DOM", "DOM.Iterable"],    "module": "NodeNext",    "outDir": "silences wrong TS error, we don't compile, we only typecheck",    "skipLibCheck": true,    "strict": true,    "target": "ESNext"  }}

为了在项目中使用JSDoc，我们需要将allowJs和checkJs设置为true。

outDir 选项在 tsconfig.json 文件中配置以抑制错误消息。

如果另外配置了declaration、declarationDir、declarationMap和emitDeclarationOnly选项，则可以使用tsc命令分析JSDoc并在@types文件夹中生成d.ts和d.ts.map文件。

使用 JSDoc 时，将模块选项设置为 NodeNext 可以提供多种便利的好处。

// ./packages/my-lib/src/private.d.ts/* eslint-disable no-unused-vars */type NumberType = number;type ConcatParam = string | number | boolean;type A = {  type: 'A';  a(): string;};type B = {  type: 'B';  b(): string;};type C = {  type: 'C';  c(): string;};type ABC = A | B | C;

通常，类型以private.d.ts.

为了抑制 ESLint 扩展的错误消息，我们使用eslint-disable no-unused-vars.

// ./packages/my-lib/src/public.d.ts/* eslint-disable no-undef */export {  ConcatParam}

要导出写入的类型private.d.ts，我们需要export在单独的文件中编写语句public.d.ts。

不幸的是，不支持自动完成，因此我们需要小心拼写错误。

同样，为了忽略来自 VSCode 扩展的错误消息，我们使用eslint-disable no-undef.

JS文档

TypeScript 提供静态类型检查，帮助开发人员提前识别代码中的潜在错误。但是，您可以将 JSDoc 引入现有的 JavaScript 项目，而无需从头开始，从而获得好处。通过使用 JSDoc 指定变量、函数、类等的类型信息，TypeScript 还可以利用此信息进行类型检查。

// js source/** @param {ABC} abc */export default function(abc) {  if (abc.type == "A") return abc.a()  if (abc.type == "B") return abc.b()  return abc.c()}

@type您可以使用、@param、等标签应用类型@return，并且还支持类型保护等类似功能，没有任何问题。

此外，将module选项设置tsconfig.json为NodeNext使您能够使用在d.ts不包含export语句的文件中编写的类型，而不会出现任何问题。

// js source/** * @param {import("../../public.js").ConcatParam[]} strs */export default function concat(...strs) {    let result = ""    for (const str of strs) {        result += str    }    return result}

// auto-generated d.ts/** * @param {import("../../public.js").ConcatParam[]} strs */export default function concat(...strs: import("../../public.js").ConcatParam[]): string;//# sourceMappingURL=concat.d.ts.map

JSDoc 的import语句允许您从其他文件导入类型，但它们与d.ts该命令生成的文件不兼容tsc，因此建议不要使用它们。

/** @typedef {string | number} ConcatParam *//** * @param {ConcatParam[]} strs */export default function concat(...strs) {    let result = ""    for (const str of strs) {        result += str    }    return result}

// auto-generated d.ts/** @typedef {string | number} ConcatParam *//** * @param {ConcatParam[]} strs */export default function concat(...strs: ConcatParam[]): string;export type ConcatParam = string | number;//# sourceMappingURL=concat.d.ts.map

@typedef由于类似的兼容性问题，也不建议使用标签。

结论

我们详细介绍了如何使用 JSDoc 创建 npm 包，包括子路径模块。