一种编辑 TypeScript 代码的方式

651 阅读5分钟

前言

众所周知,TypeScript 在 #13940 中开放了 transformer 的API,在此之后, 这些 API 已经成为在 TypeScript 生态中编写代码生成器(codegen),代码转换(transformer)的普遍方式。同时,目前这些 API 也有它的一些缺点。 本文将分享与分析作者在开发一个代码转换工具过程中遇到的问题,思考以及解决方案。

背景

传统方式:transformer API

TypeScript 目前提供了将代码解析为 AST, 并且进行转换的 API。 让我们通过一个简单的例子了解它。

目标:将 foo 标识符 转换为 bar 标识符

首先,我们要将代码解析为 AST,以 let foo = 42 为例:

import * as ts from 'typescript'

const code = "let foo = 1;" // 要转换的代码
const ast = ts.createSourceFile(
    /* filename */'dummy.ts',
    /* sourceText */ code,
    ts.ScriptTarget.Latest
) // 解析后的 AST

可以看到,调用 TypeScript 编译器解析的过程非常简单。接下来,我们创建一个非常简单的 transformer, 这个transformer 会找到所有为 foo 的标识符,并将其修改为 bar

const transformerFactory: ts.TransformerFactory<ts.Node> = (context: ts.TransformationContext) => {
    return visitor

    function visitor(node: ts.Node): ts.Node {
        if (ts.isIdentifier(node) && node.text === "foo") { // 判断是否是 foo 标识符
            return ts.createIdentifier("bar") // 如果是则替换为 bar 标识符
        }
        return ts.visitEachChild(node, visitor, context) // 否则继续遍历其他节点
    }
};

在开发 transformer 的过程中,可能涉及许多 TypeScript 的数据结构,我们可以使用 ts-ast-viewer 查看 AST 的结构并且获取生成对应代码的工厂函数。 然后我们尝试转换并生成代码:

const result = ts.transform(ast, [transformerFactory]) // 转换 AST
const node = result.transformed[0]

// 由 AST 生成代码
const printer = ts.createPrinter()
const codeAfterTransform = printer.printNode(ts.EmitHint.Unspecified, node, ast);

console.log(codeAfterTransform) // let bar = 1;

可以看到,最后生成的代码已经如我们所预期的,将标识符 foo 改为了 bar。为了验证,我们再尝试一下:

const code = "console.log(foo)"
// ...
console.log(codeAfterTransform) // console.log(bar);

以上就是一个简单的 transformer。

扩展

显而易见,我们可以由 transformer 实现基于 AST 节点的宏,即判断某些节点,并替换为其他内容。但是由于 transformer 在解析后才被执行,所以不可以像其他语言的宏一样修改/扩展语法,这也是它的限制之一。

问题

transformer API 非常简洁好用,但是它同样也有一些缺憾:

  • 对 JSDoc 以及注释支持欠佳。在某些特殊情况下会丢失注释,并且在 TypeScript 4.0 之前的版本,JSDoc 相关的 API 并没有公开,并且处理 JSDoc/注释也是非常繁琐的工作。
  • 对代码风格有很大的破坏。可以认为transformer API 解析代码后,重新根据 AST 生成了新的代码。由于在这一过程中,丢失了很多信息,例如:空行,缩进等,因此通过 transformer API 转换后的代码相比原有的代码会有很多的改动。如果我们的目的是修改已有的 codebase,并且尽可能保留原有风格,那么这是不可接受的。
  • 对跨节点的操作支持不够友好。如果需要修改同一级的两个节点,往往需要在访问公共的父节点时进行操作,这会让 transformer 的编写非常痛苦。 针对这些问题,作者经过一些尝试,找到了另外一种“新”方法。

新的选择 —— TextChanges API

什么是 TextChanges API

TypeScript 在编译器之外,还提供了 language service 的功能,它为众多编辑器提供了例如“快速修复”,“重构” 等功能。这些功能会增删改代码,并且几乎不会修改原本的格式,而这些操作则是由被称为 textChanges 的一系列 API 所提供。所以,textChangs 并不 “新”,只是很少暴露于视野中。

我们可以看到,TypeScript 在解析代码时,记录了每一个节点的位置:

export interface TextRange {
    pos: number;
    end: number;
}

export interface Node extends TextRange {
    // ...
}

在获取到这些信息后,可以直接通过字符串编辑操作更新代码。而 textChanges 就是基于这些信息进行代码编辑的一系列 API。

为什么选择 TextChanges API

由于 textChanges 基于直接的字符串操作进行,不会涉及其他代码,因此不会有上文中代码格式变动方面的问题。由于同样的原因,它并不要求在访问公共父节点时操作,提升了编辑时的灵活性。

并且我们在编辑代码时,并不只是简单的文本替换,还需要考虑到例如代码格式方面(例如逗号,括号等)的问题。自行处理的话需要花费非常大的精力,而 textChanges 作为 TypeScript 用来提供代码编辑的接口,本身处理了大量的 edge case。本着不重复造轮子的原则,我们选择其作为编辑代码的另一种选择。

实践

下面作者简单分享一些在使用 textChanges API 时的实践与经验。

使用 TypeScript 内部 API

不幸的是 textChanges 目前仅被 TypeScript 内部使用,并没有开放 API。但是由于我们最终运行的是 JavaScript,而这些 API 仅仅是没有提供类型定义,所以我们可以手动为这些内部 API 添加类型定义。例如使用作者的另一个工具 open-typescript 或自行手动添加类型定义

TextChanges 的依赖

使用 textChanges 需要构造 LanguageServiceHost,其中有一些涉及 TypeScript Compiler Host 与 VFS 的细节在此不再赘述,可以查看 hosts.tsupgrade.ts了解更多。

实现

下面我们重新使用 textChanges API 改写上面的例子:

// ...
declare const context: ts.textChanges.TextChangesContext; // 构造 context 的过程省略

const changes = ts.textChanges.ChangeTracker.with(context, tracker => {
    function changesVisitor (node: ts.Node) {
        if (ts.isIdentifier(node) && node.text === "foo") {
            tracker.replaceNode(ast, node, ts.createIdentifier("bar")) // 替换节点
        }
        ts.forEachChild(node, changesVisitor)
    }

    ts.forEachChild(ast, changesVisitor)
})

const result = ts.textChanges.applyChanges(ast.text, changes.map(change => change.textChanges).flat()) // 获取所有的 changes
console.log(result) // console.log(bar)

可以看到,在遍历 AST 时,不再需要返回更改后的节点,而是由 changeTracker 记录。在遍历结束后统一应用。这样在处理同级的节点时,只需通过各种手段(例如 symbol 等)获取到相应的节点即可。

结语

transformertextChanges 都是进行代码编辑/转换的接口,在实际开发中,应根据自己不同场景和实际的需求,选择最适合自己的工具。

感谢阅读。