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）：

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("### JavaScript\n")
    console.log(host.readFile(file))

    console.log("### Type Definition\n")
    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 文件的步骤和方法，希望对你有所帮助。

参考资料：

• 从 JavaScript 文件获取 DTS
• turning-code-into-a-program
• @typescript/cfs