Deno 中使用 @typescript/vfs 生成 DTS 文件

背景

前段时间开源的 STC 工具，这是一个将 OpenApi 规范的 Swagger/Apifox 文档转换成代码的工具。可以在上一篇（《OpenApi（Swagger）快速转换成 TypeScript 代码 - STC》）随笔里面查看这个工具的介绍和使用。
为了支持生成 Javascript，近期添加了 JavaScript 插件，并且生成 DTS 文件。实现它有两个设想：

• 重新写一遍解析 OpenApi 规范的文档数据。
  
• 基于 TypeScript 插件生成的 TypeScript 代码字符串，通过编译工具转换成 JavaScript。
  

最终选择第二种实现方式，原因也很简单，TypeScript 是 JavaScript 的超集，有着丰富的编译工具（tsc、esbuild、swc、rome 等等）。相比第一种方式起来更简单，出现问题时只需要修改 TypeScript 的转译部分，还能减少多次修改的情况。通过实践，选择 swc 编译 TypeScript 代码 DTS 文件则由 tsc 生成。

代码实现

首先在 Deno 文档找了一遍，是否有满足需求我们的 Api 提供。看到文档上写着：

于是，开始另寻他路。
在尝试了 esbuild 失败后，决定使用 swc 将 TypeScript 编译成 JavaScript 代码，可是不支持生成 DTS 文件，这还需要用 tsc 来实现。其中比较棘手是 tsc 在 Deno 里面实现（应该是对 TypeScript compiler Api 不熟的原因）。
通过在网上查阅 TypeScript compiler Api 的使用资料，同时还借助 ChatGPT 的协助，对 TypeScript compiler Api 有了个初步的认识。
摘自 TypeScript wiki 的示例（从 JavaScript 文件获取 DTS）：

1. import * as ts from "typescript";
3. function compile(fileNames: string[], options: ts.CompilerOptions): void {
4.   // 创建一个带有内存发射的编译程序
5.   const createdFiles = {}
6.   const host = ts.createCompilerHost(options); // 创建编译器主机
7.   host.writeFile = (fileName: string, contents: string) => createdFiles[fileName] = contents // 覆盖写入文件的方法
8.   
9.   // 准备并发射类型声明文件
10.   const program = ts.createProgram(fileNames, options, host);
11.   program.emit();
13.   // 遍历所有输入文件
14.   fileNames.forEach(file => {
15.     console.log("### JavaScript\n")
16.     console.log(host.readFile(file))
18.     console.log("### Type Definition\n")
19.     const dts = file.replace(".js", ".d.ts")
20.     console.log(createdFiles[dts])
21.   })
22. }
24. // 运行编译器
25. compile(process.argv.slice(2), {
26.   allowJs: true,
27.   declaration: true,
28.   emitDeclarationOnly: true,
29. });

复制代码

我想法是直接是用代码字符串生成的方式，不是文件，所以这段示例不能直接应用到我们的代码里面来。结合 ChatGPT 的一些回答和网上的资料，改造如下：

1. import ts from "npm:typescript";
3. const generateDeclarationFile = () => {
4.   const sourceCode = `
5.     export type TypeTest = 1 | 0 | 3;
6.     export interface ISwagger {
7.       name: string;
8.       age: number;
9.       test: string; // Array<string>;
10.     }
12.     /**
13.      * Adds two numbers.
14.      * @param a The first number.
15.      * @param b The second number.
16.      * @returns The sum of a and b.
17.      */
18.     export function add(a: any, b: any): number {
19.       return a + b;
20.     }
21.   `;
22.   const filename = "temp.ts";
24.   // 创建一个编译选项对象
25.   const compilerOptions: ts.CompilerOptions = {
26.     target: ts.ScriptTarget.ESNext,
27.     declaration: true,
28.     emitDeclarationOnly: true,
29.     lib: ["ESNext"],
30.   };
32.   let declarationContent = "";
33.   const sourceFile = ts.createSourceFile(
34.     filename,
35.     sourceCode,
36.     ts.ScriptTarget.ESNext,
37.     true,
38.   );
40.   const defaultCompilerHost = ts.createCompilerHost(compilerOptions);
41.   const host: ts.CompilerHost = {
42.     getSourceFile: (fileName, languageVersion) => {
43.       if (fileName === filename) {
44.         return sourceFile;
45.       }
46.       return defaultCompilerHost.getSourceFile(fileName, languageVersion);
47.     },
48.     writeFile: (_name, text) => {
49.       declarationContent = text;
50.       // console.log(text);
51.     },
52.     getDefaultLibFileName: () => "./registry.npmjs.org/typescript/5.1.6/lib/lib.d.ts"
53.     useCaseSensitiveFileNames: () => true,
54.     getCanonicalFileName: (fileName) => fileName,
55.     getCurrentDirectory: () => "",
56.     getNewLine: () => "\n",
57.     getDirectories: () => [],
58.     fileExists: () => true,
59.     readFile: () => "",
60.   };
62.   // 创建 TypeScript 编译器实例
63.   const program = ts.createProgram(
64.     [filename],
65.     compilerOptions,
66.     host,
67.   );
69.   // 执行编译并处理结果
70.   const emitResult = program.emit();
72.   if (emitResult.emitSkipped) {
73.     console.error("Compilation failed");
74.     const allDiagnostics = ts
75.       .getPreEmitDiagnostics(program)
76.       .concat(emitResult.diagnostics);
78.     allDiagnostics.forEach((diagnostic) => {
79.       if (diagnostic.file) {
80.         const { line, character } = ts.getLineAndCharacterOfPosition(
81.           diagnostic.file,
82.           diagnostic.start!,
83.         );
84.         const message = ts.flattenDiagnosticMessageText(
85.           diagnostic.messageText,
86.           "\n",
87.         );
88.         console.log(
89.           `${diagnostic.file.fileName} (${line + 1},${
90.             character + 1
91.           }): ${message}`,
92.         );
93.       } else {
94.         console.log(
95.           ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
96.         );
97.       }
98.     });
99.   }
101.   return declarationContent;
102. };

复制代码

运行结果，一切正常，DTS 内容也拿到了。

这就结束了吗？修改一下 sourceCode 的内容,test: string; 改成 Array;，出错了。

这个问题是由于 lib.d.ts 文件的找不到导致的，比较棘手的是，尝试了几种修改 lib.d.ts 文件的路径方式，结果都以是吧告终。

不愿妥协的我，又开始另辟蹊径了，在网上开始搜索一番。可谓皇天不负有心人，于是找到了 @typescript/vfs 这个 npm 库。@typescript/vfs 是一个基于映射的 TypeScript 虚拟文件系统。这对于我们在 Deno 环境中很有用，它可以运行虚拟的 TypeScript 环境，其中文件不是来源于真实磁盘上的。按照文档开始改造，最终核心的实现：

1. import vfs from "npm:@typescript/vfs";
3. const generateDeclarationFile = async (sourceCode: string) => {
4.   // ...
6.   // 创建一个编译选项对象
7.   const compilerOptions: ts.CompilerOptions = {
8.     declaration: true,
9.     emitDeclarationOnly: true,
10.     lib: ["ESNext"],
11.   };
13.   // 创建一个虚拟文件系统映射，并加载 lib.d.ts 文件
14.   const fsMap = await vfs.createDefaultMapFromCDN(
15.     compilerOptions,
16.     ts.version,
17.     true,
18.     ts,
19.   );
20.   fsMap.set(filename, sourceCode);
22.   // 创建虚拟文件系统
23.   const system = vfs.createSystem(fsMap);
24.   // 创建虚拟 TypeScript 环境
25.   const env = vfs.createVirtualTypeScriptEnvironment(
26.     system,
27.     [filename],
28.     ts,
29.     compilerOptions,
30.   );
32.   // 获取 TypeScript 编译输出
33.   const output = env.languageService.getEmitOutput(filename);
34.   // 将输出的声明文件内容拼接起来
35.   const declarationContent = output.outputFiles.reduce((prev, current) => {
36.     prev += current.text;
37.     return prev;
38.   }, "");
40.   // 创建虚拟编译器主机
41.   const host = vfs.createVirtualCompilerHost(system, compilerOptions, ts);
42.   // 创建 TypeScript 程序
43.   const program = ts.createProgram({
44.     rootNames: [...fsMap.keys()],
45.     options: compilerOptions,
46.     host: host.compilerHost,
47.   });
49.   // 执行编译并获取输出结果
50.   const emitResult = program.emit();
52.   // ...
53. }

复制代码

看一下输出结果，符合我们的结果期望了，并且没有错误。

总结


问题最终是得到了很好的解决，是值得庆祝
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！