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

技术分享 3年前 (2023-08-21) 0 999+

背景

前段时间开源的 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）：

import * as ts from "typescript";  function compile(fileNames: string[], options: ts.CompilerOptions): void {   // 创建一个带有内存发射的编译程序   const createdFiles = {}   const host = ts.createCompilerHost(options); // 创建编译器主机   host.writeFile = (fileName: string, contents: string) => createdFiles[fileName] = contents // 覆盖写入文件的方法      // 准备并发射类型声明文件   const program = ts.createProgram(fileNames, options, host);   program.emit();    // 遍历所有输入文件   fileNames.forEach(file => {     console.log("### JavaScriptn")     console.log(host.readFile(file))      console.log("### Type Definitionn")     const dts = file.replace(".js", ".d.ts")     console.log(createdFiles[dts])   }) }  // 运行编译器 compile(process.argv.slice(2), {   allowJs: true,   declaration: true,   emitDeclarationOnly: true, });

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

import ts from "npm:typescript";  const generateDeclarationFile = () => {   const sourceCode = `     export type TypeTest = 1 | 0 | 3;     export interface ISwagger {       name: string;       age: number;       test: string; // Array<string>;     }      /**      * Adds two numbers.      * @param a The first number.      * @param b The second number.      * @returns The sum of a and b.      */     export function add(a: any, b: any): number {       return a + b;     }   `;   const filename = "temp.ts";    // 创建一个编译选项对象   const compilerOptions: ts.CompilerOptions = {     target: ts.ScriptTarget.ESNext,     declaration: true,     emitDeclarationOnly: true,     lib: ["ESNext"],   };    let declarationContent = "";   const sourceFile = ts.createSourceFile(     filename,     sourceCode,     ts.ScriptTarget.ESNext,     true,   );    const defaultCompilerHost = ts.createCompilerHost(compilerOptions);   const host: ts.CompilerHost = {     getSourceFile: (fileName, languageVersion) => {       if (fileName === filename) {         return sourceFile;       }       return defaultCompilerHost.getSourceFile(fileName, languageVersion);     },     writeFile: (_name, text) => {       declarationContent = text;       // console.log(text);     },     getDefaultLibFileName: () => "./registry.npmjs.org/typescript/5.1.6/lib/lib.d.ts"     useCaseSensitiveFileNames: () => true,     getCanonicalFileName: (fileName) => fileName,     getCurrentDirectory: () => "",     getNewLine: () => "n",     getDirectories: () => [],     fileExists: () => true,     readFile: () => "",   };    // 创建 TypeScript 编译器实例   const program = ts.createProgram(     [filename],     compilerOptions,     host,   );    // 执行编译并处理结果   const emitResult = program.emit();    if (emitResult.emitSkipped) {     console.error("Compilation failed");     const allDiagnostics = ts       .getPreEmitDiagnostics(program)       .concat(emitResult.diagnostics);      allDiagnostics.forEach((diagnostic) => {       if (diagnostic.file) {         const { line, character } = ts.getLineAndCharacterOfPosition(           diagnostic.file,           diagnostic.start!,         );         const message = ts.flattenDiagnosticMessageText(           diagnostic.messageText,           "n",         );         console.log(           `${diagnostic.file.fileName} (${line + 1},${             character + 1           }): ${message}`,         );       } else {         console.log(           ts.flattenDiagnosticMessageText(diagnostic.messageText, "n"),         );       }     });   }    return declarationContent; };

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

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

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

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

import vfs from "npm:@typescript/vfs";  const generateDeclarationFile = async (sourceCode: string) => {   // ...    // 创建一个编译选项对象   const compilerOptions: ts.CompilerOptions = {     declaration: true,     emitDeclarationOnly: true,     lib: ["ESNext"],   };    // 创建一个虚拟文件系统映射，并加载 lib.d.ts 文件   const fsMap = await vfs.createDefaultMapFromCDN(     compilerOptions,     ts.version,     true,     ts,   );   fsMap.set(filename, sourceCode);    // 创建虚拟文件系统   const system = vfs.createSystem(fsMap);   // 创建虚拟 TypeScript 环境   const env = vfs.createVirtualTypeScriptEnvironment(     system,     [filename],     ts,     compilerOptions,   );    // 获取 TypeScript 编译输出   const output = env.languageService.getEmitOutput(filename);   // 将输出的声明文件内容拼接起来   const declarationContent = output.outputFiles.reduce((prev, current) => {     prev += current.text;     return prev;   }, "");    // 创建虚拟编译器主机   const host = vfs.createVirtualCompilerHost(system, compilerOptions, ts);   // 创建 TypeScript 程序   const program = ts.createProgram({     rootNames: [...fsMap.keys()],     options: compilerOptions,     host: host.compilerHost,   });    // 执行编译并获取输出结果   const emitResult = program.emit();    // ... }

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

总结

问题最终是得到了很好的解决，是值得庆祝🎉的。使用了 @typescript/vfs 库提供的虚拟文件系统，达到了我们需要的结果。期间想通过解析 AST，来生成 DTS 文件，这个工程有点大，最终被劝退了。本文介绍了在 Deno 中使用 @typescript/vfs 库生成 DTS 文件的步骤和方法，希望对你有所帮助。

如果你觉得不错，可以点个 star 表示支持一下 https://github.com/long-woo/stc

参考资料：

发表评论