tsrs Node API完全参考：同步与异步API构建你自己的TypeScript工具链-开发者社区

【免费下载链接】tsrs

Rust port of the TypeScript 7 type checker

项目地址：https://gitcode.com/gh_mirrors/ts/tsrs

tsrs 是 Rust 编写的 TypeScript 7 类型检查器，其 npm 包tsrs同时提供完整的Node API：tsrs/sync同步 API 与tsrs/async异步 API。两者可直接嵌入你的 Node.js 脚本、CLI 工具或 CI 流水线，完成类型诊断、AST 遍历、模块解析、转译与构建编排，助你快速构建自己的 TypeScript 工具链。

快速安装：一条命令接入 tsrs Node API

tsrs 的 JS API 通过 npm 分发，安装后即可在 Node.js（≥16.20）中使用：

pnpm add -D tsrs

安装完成后，根导出会给出版本信息：

const { version, typescriptVersion, typescriptCommit } = require("tsrs");

💡 主包会自动解析平台原生包（@tsrs/<os>-<arch>），无需手动下载二进制；详见 npm/README.md。

tsrs Node API 导出子路径一览

tsrs包按 TypeScript 7 官方包的子路径结构组织导出（见 npm/tsrs/package.json）：

子路径	内容
`tsrs/sync`	同步调用`API`（MessagePack 走服务端 stdio）
`tsrs/async`	返回 Promise 的异步`API`（JSON-RPC）
`tsrs/ast`（含`/is`、`/factory`、`/utils`、`/scanner`、`/visitor`、`/clone`）	AST 类型、守卫函数、工厂与遍历
`tsrs/fs`、`tsrs/proto`	文件系统回调 / 请求文件系统、协议类型
`tsrs/path`	强类型路径构造器与工具
`tsrs/vscode`	`createTypeScriptModuleLoader`与编辑器 SDK 类型

所有子路径均附带类型声明，配合tsconfig.schema.json/jsconfig.schema.json可直接做类型化开发。

同步 API：三行代码拿到类型诊断

同步 API 适合脚本和一次性任务。构造API时它会拉起tsrs --api服务进程：

import { API } from "tsrs/sync"; const api = new API({ cwd: process.cwd() }); // tsserverPath 可覆盖默认二进制 const snapshot = api.createSnapshot({ openProjects: ["/abs/path/tsconfig.json"] }); const project = snapshot.getConfiguredProject("/abs/path/tsconfig.json"); console.log(project.program.getSemanticDiagnostics("/abs/path/src/index.ts")); project.program.emit(); // 按项目的编译器选项输出 api.close();

核心对象链路是createSnapshot→Project→Program：

api.createSnapshot(params)建立一次项目集合快照，params支持openProjects、userPreferences等；
snapshot.updateSnapshot(...)可在文件变更后增量更新；
project.program上可调用getSemanticDiagnostics、getSyntacticDiagnostics、emit、emitToString等方法。

异步 API：基于 Promise 与资源自动释放

异步 API 与同步版一一对应，但每个调用返回 Promise，适合长驻服务：

import { API as AsyncAPI } from "tsrs/async"; const api = new AsyncAPI({ cwd: process.cwd() }); const snapshot = await api.createSnapshot({ openProjects: ["/abs/path/tsconfig.json"] }); const diagnostics = await snapshot .getConfiguredProject("/abs/path/tsconfig.json")! .program.getSemanticDiagnostics("/abs/path/src/index.ts"); await api.close();

资源管理细节值得注意：

异步Snapshot、Program、BuildOrchestrator实现了Symbol.asyncDispose，支持await using自动等待清理完成；
TypeScript 消费端需要esnext.disposable（或更新 lib）来支持Symbol.dispose/Symbol.asyncDispose声明；
在旧版 Node 上缺少 dispose 符号时，请显式调用close()/dispose()。

一个典型差异：若服务进程意外退出，异步 API 会让所有挂起及后续请求以API server connection lost: ...开头的错误快速失败，而不是无限挂起（见 npm/sdk/patches/ 中的补丁说明）。

实战技巧：批量请求、计时与文件系统回调

🧩批量请求：API.batch可把多个请求合并发送，减少往返。注意同步 API 的 generator 实例是单次使用的，跨batch复用会抛出Cannot execute the same generator instance more than once（与上游 TypeScript 行为一致）。

📏计时快照：设置collectTiming: true（或环境变量TS_API_TIMING_DIR指向非空目录）后，客户端close()时会写出一份包含客户端与服务端计时数据的 JSON 快照。

📁文件系统回调：APIOptions支持fs（FileSystemCallbacks）与useCaseSensitiveFileNames，让类型检查运行在你自定义的文件系统之上；也可用tsrs/fs的createFileSystem构造纯内存的请求文件系统：

import { createFileSystem, type FileSystemCallbacks } from "tsrs/fs"; import { API, type APIOptions } from "tsrs/sync"; const requestFileSystem = createFileSystem([["/a.ts", "export {};"]]); const options: APIOptions = { cwd: "/", tsserverPath: "/path/to/tsrs", fs: callbacks };

完整类型化示例可参考 npm/sdk/smoke/typed.mts。

177 个方法：覆盖矩阵与状态速查

tsrs 的 API 协议与 TypeScript 7 原生 API 完全对齐，共177 个方法（58 个 core + 119 个 checker 方法）。官方文档 docs/NODE_API.md 末尾附有完整覆盖矩阵，状态含义如下：

supported：有核心 Rust 测试覆盖的真实编译器会话行为；
partial：已实现并分派，但仅由上游 Node 测试套件或组件级检查覆盖，或存在已记录的差异；
not implemented：如startCPUProfile、stopCPUProfile、saveHeapProfile三个性能剖析方法暂未实现。

未实现的方法会返回显式api: unsupported: ...错误，绝不假装成功。方法级请求统计见 npm/sdk/METHODS.md：在上游 SDK 套件中，968/968 测试在 tsrs 上全部通过，177 个方法中 170 个有成功响应。

常用方法分组速览：

类别	代表方法
诊断	`getSemanticDiagnostics`、`getSyntacticDiagnostics`、`getDeclarationDiagnostics`
输出	`emit`、`emitToString`、`transpileModule`、`getDeclarationEmit`
符号/类型	`getSymbolAtPosition`、`getTypeAtPosition`、`typeToString`、`getCompletionsAtPosition`
模块解析	`createModuleResolver`、`resolveModuleName`
构建	`createBuildOrchestrator`、`build`、`buildReferences`、`cleanBuild`
配置	`parseCommandLine`、`readConfigFile`、`parseConfigFile`