Composio composio/ts-builders面向 CLI 类型桩生成的 TypeScript AST 构建器与 0.2.x ESM-only 迁移指南【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composiocomposio/ts-builders是 Composio 仓库中负责**以编程方式生成 TypeScript 抽象语法树AST**的基础包它被 Composio CLIcomposio/cli用来为 TypeScript 工程生成类型桩type stubs。本文以本包 CHANGELOG.md 记录的 0.2.x 发布线为主线结合源码结构讲解它的 Builder 设计、在 CLI 代码生成管线中的位置以及 0.2.0 起 ESM-only 迁移这一破坏性变更的完整含义帮助你理解如何在 Node.js 22.22.3 环境下正确消费与使用该包。包定位一个为代码生成而生的 TypeScript 构建器从 package.json 的description字段可以看到该包是prisma/ts-builders的 forkFork of prisma/ts-builders而包自身的 README.md 进一步明确了它在 Composio 中的职责This package provides a set of utilities for programmatically generating TypeScript Abstract Syntax Trees. It is used to generate type stubs for TypeScript projects in the Composio CLI.也就是说它不参与运行时业务逻辑而是面向生成代码的代码当 CLI 需要为某个 Toolkit 生成对应的 TypeScript 类型声明文件时不会手写字符串模板而是通过一组构建器Builder对象组装出合法的 TS 语法结构最后统一渲染成源码文本。从源码结构看src/该包将常见的 TS 语法元素抽象成了可组合的构建器单元声明类Class、Interface、TypeDeclaration、ConstDeclaration、NamespaceDeclaration、AnyDeclarationBuilder、Export、ExportFrom、Import、Method、Parameter、Property类型类ArrayType、TupleType、UnionType、FunctionType、ObjectType、NamedType、KeyofType、KeyType、PrimitiveType、StringLiteralType、TypeOf、GenericParameter值/表达式类ArrayValue、ObjectValue、PropertyValue、FunctionCall、ArraySpread、WellKnownSymbol基础设施Writer、BasicBuilder、TypeBuilder、OperatorPrecedence、QuoteStyle、DocComment、stringify、isValidJsIdentifier所有这些模块统一通过 src/index.ts 以export *的形式对外暴露消费者只需import { interfaceDeclaration } from composio/ts-builders即可使用。核心设计Builder 模式与 Writer 渲染管线理解这个包的关键是两条主线BasicBuilder接口和**Writer渲染器**。BasicBuilder一切构建器的统一契约src/BasicBuilder.ts 定义了整个包的基石import { Writer } from ./Writer; export interface BasicBuilderContextType undefined { write(writer: WriterContextType): void; }任何构建器只需实现一个write(writer)方法把自己渲染到Writer上。这是典型的组合式设计复杂的构建器内部可以继续调用其他构建器的write最终形成一棵渲染树。Writer缩进、换行与上下文的排版引擎src/Writer.ts 是实际负责排版的核心类它把构建器的调用序列转换成带缩进的多行文本默认缩进为 2 个空格INDENT_SIZE 2write(value)把字符串或构建器追加到当前行不换行writeLine(line)写一行并立即换行writeJoined(separator, values)用分隔符拼接多个值如泛型参数列表T, U、extends列表withIndent(callback)提升一级缩进、执行回调、再恢复缩进是生成{ ... }代码块的标准手段afterNextNewline(callback)支持在两行之间插入装饰性内容如下划线注释addMarginSymbol(symbol)用符号替换行首第一个字符用于生成注释标记构造时可传入FormattingOptions来自 src/QuoteStyle.ts 的DEFAULT_FORMATTING_OPTIONS控制引号风格等格式细节。Writer是泛型类WriterContextType undefined可以携带一个上下文对象供各构建器在渲染时读取例如根据目标平台决定输出差异这为同一棵 AST、多种渲染策略保留了扩展点。TypeBuilder自动加括号的类型节点src/TypeBuilder.ts 是所有类型构建器的抽象基类。每个类型构建器都声明一个precedence运算符优先级并通过writeInContext(writer, context)在渲染时根据上下文自动判断是否需要括号writeInContext(writer: Writer, context: TypeContext): void { if (needsParentheses(this.precedence, context)) { writer.write((); this.write(writer); writer.write()); } else { this.write(writer); } }优先级判断逻辑集中在 src/OperatorPrecedence.ts。这意味着开发者不需要手工关心(A | B)[]到底要不要加括号——构建器会在ArrayType、IndexAccess等不同TypeContext下自动补全从机制上杜绝生成非法语法。一个完整的声明示例InterfaceDeclaration以 src/Interface.ts 为例InterfaceDeclaration采用流式 API 逐步装配成员const decl interfaceDeclaration(MyToolkit) .addGenericParameter(genericParameter(T)) .extends(namedType(BaseToolkit)) .add(property(name, stringType())) .add(method(run, ...));渲染时它会依次输出interface关键字、名称、泛型参数、extends列表然后借助withIndent生成缩进的成员块空接口则直接输出{}。同目录下的Interface.test.ts等测试文件如 ArrayType.test.ts、UnionType.test.ts、Writer.test.ts用 Vitest 覆盖了这些渲染行为可用pnpm test验证。stringify构建器到文本的最后一步src/stringify.ts 提供收尾入口export function stringify( builder: BasicBuilder, { indentLevel 0, newLine none }: StringifyOptions {} )它创建一个Writer写入构建器再按newLine选项none/leading/trailing/both控制首尾换行。helpers.ts还提供了omit(type, keyType)便捷函数等价于生成OmitT, K类型。在 Composio CLI 中的实际应用README 明确指出该包服务于 CLI 的类型桩生成。从源码结构看CLI 的 TypeScript 生成管线位于 ts/packages/cli/src/generation/typescript/其中 generate.ts、generate-toolkit-sources.ts、generate-index-source.ts 均直接引用了composio/ts-builders。可以推断CLI 在生成 Toolkit 类型声明与索引文件时正是用上述构建器把工具 schema 组装为interface/type/const声明再交给stringify输出为.d.ts或源码文件——这也是为什么本包对输出格式的合法性如此看重类型桩一旦语法错误直接破坏消费方 IDE 与编译流程。0.2.0 破坏性变更全面转向 ESM-onlyCHANGELOG 中 0.2.0 的 Minor Changes 是本包最重要的演进节点Drop CommonJS entrypoints and publish the TypeScript SDK packages as ESM-only packages. This is a breaking change within the existing 0.x release line: consumers must use Node.js 22.22.3 or newer. CommonJS callers can only rely on Nodes nativerequire(esm)interop, and the SDK no longer ships custom CommonJS compatibility machinery or.cjsartifacts.拆解这条变更可以提炼出三个层面的影响1. 包产物全面 ESM 化对比 package.json 可以验证这一声明{ main: dist/index.mjs, type: module, module: dist/index.mjs, types: dist/index.d.mts, exports: { .: { types: ./dist/index.d.mts, default: ./dist/index.mjs } } }入口从.js变为.mjs类型声明从.d.ts变为.d.mtstype: module显式声明包内全部按 ESM 语义解释exports字段中不再存在require条件分支也没有任何.cjs产物。这是ESM-only的直接证据。2. 运行时下限Node.js 22.22.3由于不再携带自定义的 CommonJS 兼容机制require()一个 ESM 包只能依赖 Node 原生的require(esm)互操作能力而该能力在 Node.js 22.22.3 及更新版本才达到稳定可用状态。因此ESM 消费者在 Node.js 22.22.3 下正常import即可无额外配置CommonJS 消费者只能通过require(composio/ts-builders)触发 Node 原生互操作需 Node.js 22.22.3不能再指望包内提供 CJS 适配层或降级产物旧版 Node 用户这是硬性破坏性变更必须升级运行时无法通过在工程里打补丁绕过。3. 工程构建链路同步调整0.2.0 的迁移不是孤立发生的——CHANGELOG 将其表述为 publish the TypeScript SDK packages as ESM-only说明这是整个 TypeScript SDK 包族sdk 系列包的协同动作。从构建配置看本包使用tsdown打包tsdown.config.ts 继承了仓库根部的 tsdown.config.base.ts并指定tsconfig.src.jsonpnpm build即产出 ESM 单一格式与不再产出.cjs产物的描述吻合。0.2.1 维护性更新依赖范围与锁文件刷新0.2.1 是紧随其后的补丁级更新Refresh dependency ranges and lockfiles across the workspace.它不涉及 API 变化属于工作区级别的依赖范围dependency ranges与锁文件刷新——这类更新通常用于让 monorepo 中所有包依赖声明保持一致、修复 lockfile 漂移或抬升某些传递依赖的版本下限。就本包而言其运行时依赖仅有babel/helper-validator-identifier见 package.json 的dependencies构建与测试依赖为tsdown与vitest0.2.1 相当于对这些依赖的引用范围做了统一对齐行为上无破坏性。在仓库中的构建与测试流程包内 package.json 定义了三条标准脚本pnpm build # 由 tsdown 按 tsconfig.src.json 打包出 dist/index.mjs 与 dist/index.d.mts pnpm test # vitest run执行 src 下所有 *.test.ts测试文件与源码同目录放置如Writer.test.ts、Interface.test.ts、UnionType.test.ts、Import.test.ts等覆盖了渲染器、各类声明与类型的输出行为sideEffects: false声明该包无副作用便于打包器做 tree-shaking。值得注意的是 package.json 中private: true——它主要作为仓库内部包被 CLI 消费而非对外公开发行的独立产品。消费者迁移建议如果你在仓库内或下游工程中直接依赖composio/ts-builders按 CHANGELOG 与包产物可以总结出如下清单升级运行时确保构建与运行环境为 Node.js 22.22.3 或更高版本检查导入方式ESM 消费者无需改动CJS 消费者改用 Node 原生require(esm)并确认没有依赖旧的.cjs产物路径回归生成结果由于本包被 ts/packages/cli/src/generation/typescript/ 使用升级后应重新跑一遍 CLI 的类型桩生成流程用tsc或 IDE 校验输出文件语法与缩进格式更新依赖声明确保 monorepo 内对该包的引用与 0.2.1 的依赖范围一致必要时刷新锁文件。小结composio/ts-builders虽然只是 Composio 仓库中的一个基础设施包但它的设计——以BasicBuilder为统一契约、以Writer为排版引擎、以TypeBuilder自动处理括号优先级——为 CLI 的 TypeScript 类型桩生成提供了可靠且可测试的底座。而 0.2.x 发布线则清晰记录了 Composio 对现代 Node.js 生态的拥抱从 0.2.0 起全面 ESM-only、将运行时下限抬升至 Node.js 22.22.3、不再维护自定义 CJS 兼容层再到 0.2.1 的依赖范围统一刷新。对于任何计划在 Node.js 22.22.3 环境下构建或扩展 Composio CLI 类型生成能力的开发者这份演进记录都是理解该包当前形态与兼容边界的第一手资料。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考