tsrs Node API完全参考：同步与异步API构建你自己的TypeScript工具链

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

所有子路径均附带类型声明，配合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 个有成功响应。

常用方法分组速览：

常见问题与注意事项

❓与 TypeScript 5 的createProgram兼容吗？不兼容。tsrs 不提供一次性 CLI 包装对象，协议来自 TypeScript 7 原生 API 移植，客户端与服务端必须来自同一提交（无版本协商）。

❓自动补全需要自动导入时怎么办？先调用updateSnapshot并传prepareAutoImports（附带要索引的文件），再以includeSymbol: true调用getCompletionsAtPosition；未准备的快照会收到客户端错误。

❓相对路径的编译选项如何解析？快照程序和 transpile 请求支持原始编译选项，其中相对选项路径基于 API 服务进程的当前目录解析；initialize响应会报告caseSensitivity与currentDirectory。

❓同步客户端崩溃后行为如何？同步客户端不做补丁，服务崩溃后下一次调用会立即抛出管道错误；异步客户端则如前文所述以连接丢失错误快速失败。

相关文件与延伸阅读

• 官方使用文档：docs/NODE_API.md
• npm 打包与 JS API 说明：npm/README.md
• SDK 方法清单与测试统计：npm/sdk/METHODS.md
• 同步客户端源码：npm/tsrs/src/api/sync/api.ts
• 异步客户端与连接丢失补丁：npm/tsrs/src/api/async/client.ts
• 客户端选项定义：npm/tsrs/src/api/options.ts
• Rust 服务端核心：crates/tsrs_api/src/lib.rs、crates/tsrs_api_transport/src/lib.rs

掌握tsrs/sync与tsrs/async这两套 API，你就能在 CI 门禁、代码生成器、LSP 之外的工具场景里，把 TypeScript 7 级别的类型能力无缝集成进自己的工具链 🚀