Dagger TypeScript SDK 类型别名详解TypeDefWithEnumOpts 与枚举类型定义【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/daggerTypeDefWithEnumOpts是 Dagger TypeScript SDK 中用于描述枚举Enum类型定义的选项对象类型别名。它作为TypeDef.withEnum()方法的第二参数为枚举类型提供文档字符串与源码映射Source Map两类元数据。本文基于仓库源码sdk/typescript/src/api/client.gen.ts与模块注册流程sdk/typescript/src/module/entrypoint/register.ts完整讲解该类型别名的字段含义、在枚举构建与模块注册中的实际用途帮助你在开发 Dagger 模块时正确使用枚举类型定义。类型别名概览TypeDefWithEnumOpts定义于 TypeScript SDK 的自动生成客户端文件中sdk/typescript/src/api/client.gen.ts其完整定义如下export type TypeDefWithEnumOpts { /** * A doc string for the enum, if any */ description?: string /** * The source map for the enum definition. */ sourceMap?: SourceMap }它本身是一个对象字面量类型别名包含两个可选的属性属性类型是否必填说明descriptionstring可选枚举的文档字符串doc string用于说明该枚举的用途sourceMapSourceMap可选枚举定义对应的源码映射信息该类型的核心作用将枚举类型的语义说明description与源码溯源信息sourceMap作为元数据附加到 Dagger 引擎中创建的枚举类型定义上。这与TypeDefWithEnumMemberOpts、TypeDefWithEnumValueOpts等类型共同构成一组定义枚举类型的选项体系。两个可选字段的语义解析description枚举的文档字符串description是string类型的可选字段官方注释为 A doc string for the enum, if any枚举的文档字符串如果有的话。它的作用与 Dagger 引擎中withEnum参数的description一一对应sdk/typescript/src/api/client.gen.ts。从 TypeScript 模块入口的注册逻辑可以确认该字段承载的是开发者对枚举类型的自然语言说明在模块类型注册时被原样传入let typeDef dag.typeDef().withEnum(enum_.name, { description: enum_.description, sourceMap: addSourceMap(enum_), })当 SDK 扫描器scanner从源码中提取到某个枚举声明时enum_.description即该枚举上方的文档注释withEnum调用将这段描述作为元数据写入引擎侧的类型定义中。sourceMap枚举定义的源码映射sourceMap是SourceMap类型的可选字段官方注释为 The source map for the enum definition枚举定义的源码映射。SourceMap本身是一个独立的类定义于 sdk/typescript/src/api/client.gen.ts代表 Dagger 引擎中的一个源码映射对象用于记录类型定义在源文件中的位置。在模块注册流程中源码映射通过addSourceMap辅助函数生成sdk/typescript/src/module/entrypoint/register.tsfunction addSourceMap(object: Locatable): SourceMap { const { filepath, line, column } object.getLocation() return dag.sourceMap(filepath, line, column) }可以看到sourceMap记录的是枚举声明在源文件中的文件路径、行号与列号通过dag.sourceMap(filepath, line, column)构造。这个能力使得 Dagger 引擎可以在报错、调试或 IDE 集成场景中将引擎侧的枚举类型定义精准回溯到开发者源码中的具体位置。核心应用与 withEnum 的组合使用TypeDefWithEnumOpts的唯一直接使用方是TypeDef.withEnum()方法。该方法定义于 sdk/typescript/src/api/client.gen.tswithEnum (name: string, opts?: TypeDefWithEnumOpts): TypeDef { const ctx this._ctx.select(withEnum, { name, ...opts }) return new TypeDef(ctx) }其语义为返回一个名称为name、类型种类为枚举Enum的TypeDef并携带opts中提供的元数据。调用后会返回一个新的TypeDef实例因此可以链式追加后续的枚举成员定义。完整枚举构建流程枚举的完整构建通常遵循先定义枚举类型再逐个添加枚举成员的模式。在 TypeScript SDK 的模块入口注册器中sdk/typescript/src/module/entrypoint/register.ts注册一个枚举的典型代码如下// Register all enums defined by this modules Object.values(this.module.enums).forEach((enum_) { let typeDef dag.typeDef().withEnum(enum_.name, { description: enum_.description, sourceMap: addSourceMap(enum_), }) Object.values(enum_.values).forEach((value) { const memberOpts: TypeDefWithEnumMemberOpts { value: value.value, description: value.description, sourceMap: addSourceMap(value), deprecated: value.deprecated, } typeDef typeDef.withEnumMember(value.name, memberOpts) }) mod mod.withEnum(typeDef) })该流程分为三步创建枚举类型调用dag.typeDef().withEnum(name, opts)传入枚举名与TypeDefWithEnumOpts选项描述 源码映射追加枚举成员遍历enum_.values对每个成员调用typeDef.withEnumMember(name, memberOpts)其中memberOpts属于TypeDefWithEnumMemberOpts类型包含value、description、sourceMap、deprecated字段见 client.gen.ts注册到模块最后调用mod.withEnum(typeDef)将构建好的枚举类型定义注册进模块对象client.gen.ts。源码中的实际调用验证在register.ts第 307 行还有一个值得注意的使用场景当类型解析器遇到一个仅引用、不展开定义的枚举类型时会以最简形式调用withEnum不传入任何选项case TypeDefKind.EnumKind: return dag.typeDef().withEnum((type as EnumTypeDef).name)这印证了TypeDefWithEnumOpts的opts参数是可选的——在意图仅为引用一个已存在的枚举类型例如函数返回自身或其它循环引用类型时只需提供枚举名即可。这一行为在withEnum的 JSDoc 中有明确说明client.gen.tsNote that an enums values may be omitted if the intent is only to refer to an enum.在自定义 TypeScript 模块中的使用示例在 Dagger TypeScript 模块中开发者通常不直接手动构造TypeDefWithEnumOpts而是通过声明枚举类型由 SDK 扫描器自动生成。但在需要程序化构建模块类型时可以这样使用import { dag } from dagger.io/dagger // 定义一个带文档与源码映射的枚举类型 const statusTypeDef dag.typeDef().withEnum(Status, { description: The deployment status of a service, sourceMap: dag.sourceMap(src/types.ts, 12, 3), }) // 追加枚举成员 const completeTypeDef statusTypeDef .withEnumMember(success, { value: SUCCESS, description: Deployment succeeded, }) .withEnumMember(failed, { value: FAILED, description: Deployment failed, deprecated: Use withEnumMember instead, }) // 注册进模块 const module_ dag.module().withEnum(completeTypeDef)要点总结withEnum的opts两个字段均为可选最简调用只需dag.typeDef().withEnum(name)description为纯文档用途不影响类型语义sourceMap建议配合实际源码位置文件、行、列生成便于错误信息溯源枚举成员通过withEnumMember单独追加withEnumValue是已废弃的旧 APIclient.gen.ts应优先使用前者。关联 API 参考TypeDefWithEnumOpts是 Dagger TypeScript SDK 自动生成的类型定义之一与其密切相关的还有SourceMap类sourceMap字段的类型表示源码位置映射对象TypeDefWithEnumMemberOpts定义枚举成员的选项值、描述、源码映射、弃用说明见 client.gen.tsTypeDef.withEnum()与Module.withEnum()分别用于构建枚举类型与将枚举注册到模块见 client.gen.ts 与 client.gen.ts。以上类型与方法均位于 TypeScript SDK 自动生成客户端 sdk/typescript/src/api/client.gen.ts读者可结合 TypeScript SDK 入口文档docs/versioned_docs/version-0.20/reference/typescript/README.md进行更系统的查阅。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/17 9:49:06 · 阅读 1.2k Dagger TypeScript SDK 类型别名详解：TypeDefWithEnumOpts 与枚举类型定义
Dagger TypeScript SDK 类型别名详解TypeDefWithEnumOpts 与枚举类型定义【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/daggerTypeDefWithEnumOpts是 Dagger TypeScript SDK 中用于描述枚举Enum类型定义的选项对象类型别名。它作为TypeDef.withEnum()方法的第二参数为枚举类型提供文档字符串与源码映射Source Map两类元数据。本文基于仓库源码sdk/typescript/src/api/client.gen.ts与模块注册流程sdk/typescript/src/module/entrypoint/register.ts完整讲解该类型别名的字段含义、在枚举构建与模块注册中的实际用途帮助你在开发 Dagger 模块时正确使用枚举类型定义。类型别名概览TypeDefWithEnumOpts定义于 TypeScript SDK 的自动生成客户端文件中sdk/typescript/src/api/client.gen.ts其完整定义如下export type TypeDefWithEnumOpts { /** * A doc string for the enum, if any */ description?: string /** * The source map for the enum definition. */ sourceMap?: SourceMap }它本身是一个对象字面量类型别名包含两个可选的属性属性类型是否必填说明descriptionstring可选枚举的文档字符串doc string用于说明该枚举的用途sourceMapSourceMap可选枚举定义对应的源码映射信息该类型的核心作用将枚举类型的语义说明description与源码溯源信息sourceMap作为元数据附加到 Dagger 引擎中创建的枚举类型定义上。这与TypeDefWithEnumMemberOpts、TypeDefWithEnumValueOpts等类型共同构成一组定义枚举类型的选项体系。两个可选字段的语义解析description枚举的文档字符串description是string类型的可选字段官方注释为 A doc string for the enum, if any枚举的文档字符串如果有的话。它的作用与 Dagger 引擎中withEnum参数的description一一对应sdk/typescript/src/api/client.gen.ts。从 TypeScript 模块入口的注册逻辑可以确认该字段承载的是开发者对枚举类型的自然语言说明在模块类型注册时被原样传入let typeDef dag.typeDef().withEnum(enum_.name, { description: enum_.description, sourceMap: addSourceMap(enum_), })当 SDK 扫描器scanner从源码中提取到某个枚举声明时enum_.description即该枚举上方的文档注释withEnum调用将这段描述作为元数据写入引擎侧的类型定义中。sourceMap枚举定义的源码映射sourceMap是SourceMap类型的可选字段官方注释为 The source map for the enum definition枚举定义的源码映射。SourceMap本身是一个独立的类定义于 sdk/typescript/src/api/client.gen.ts代表 Dagger 引擎中的一个源码映射对象用于记录类型定义在源文件中的位置。在模块注册流程中源码映射通过addSourceMap辅助函数生成sdk/typescript/src/module/entrypoint/register.tsfunction addSourceMap(object: Locatable): SourceMap { const { filepath, line, column } object.getLocation() return dag.sourceMap(filepath, line, column) }可以看到sourceMap记录的是枚举声明在源文件中的文件路径、行号与列号通过dag.sourceMap(filepath, line, column)构造。这个能力使得 Dagger 引擎可以在报错、调试或 IDE 集成场景中将引擎侧的枚举类型定义精准回溯到开发者源码中的具体位置。核心应用与 withEnum 的组合使用TypeDefWithEnumOpts的唯一直接使用方是TypeDef.withEnum()方法。该方法定义于 sdk/typescript/src/api/client.gen.tswithEnum (name: string, opts?: TypeDefWithEnumOpts): TypeDef { const ctx this._ctx.select(withEnum, { name, ...opts }) return new TypeDef(ctx) }其语义为返回一个名称为name、类型种类为枚举Enum的TypeDef并携带opts中提供的元数据。调用后会返回一个新的TypeDef实例因此可以链式追加后续的枚举成员定义。完整枚举构建流程枚举的完整构建通常遵循先定义枚举类型再逐个添加枚举成员的模式。在 TypeScript SDK 的模块入口注册器中sdk/typescript/src/module/entrypoint/register.ts注册一个枚举的典型代码如下// Register all enums defined by this modules Object.values(this.module.enums).forEach((enum_) { let typeDef dag.typeDef().withEnum(enum_.name, { description: enum_.description, sourceMap: addSourceMap(enum_), }) Object.values(enum_.values).forEach((value) { const memberOpts: TypeDefWithEnumMemberOpts { value: value.value, description: value.description, sourceMap: addSourceMap(value), deprecated: value.deprecated, } typeDef typeDef.withEnumMember(value.name, memberOpts) }) mod mod.withEnum(typeDef) })该流程分为三步创建枚举类型调用dag.typeDef().withEnum(name, opts)传入枚举名与TypeDefWithEnumOpts选项描述 源码映射追加枚举成员遍历enum_.values对每个成员调用typeDef.withEnumMember(name, memberOpts)其中memberOpts属于TypeDefWithEnumMemberOpts类型包含value、description、sourceMap、deprecated字段见 client.gen.ts注册到模块最后调用mod.withEnum(typeDef)将构建好的枚举类型定义注册进模块对象client.gen.ts。源码中的实际调用验证在register.ts第 307 行还有一个值得注意的使用场景当类型解析器遇到一个仅引用、不展开定义的枚举类型时会以最简形式调用withEnum不传入任何选项case TypeDefKind.EnumKind: return dag.typeDef().withEnum((type as EnumTypeDef).name)这印证了TypeDefWithEnumOpts的opts参数是可选的——在意图仅为引用一个已存在的枚举类型例如函数返回自身或其它循环引用类型时只需提供枚举名即可。这一行为在withEnum的 JSDoc 中有明确说明client.gen.tsNote that an enums values may be omitted if the intent is only to refer to an enum.在自定义 TypeScript 模块中的使用示例在 Dagger TypeScript 模块中开发者通常不直接手动构造TypeDefWithEnumOpts而是通过声明枚举类型由 SDK 扫描器自动生成。但在需要程序化构建模块类型时可以这样使用import { dag } from dagger.io/dagger // 定义一个带文档与源码映射的枚举类型 const statusTypeDef dag.typeDef().withEnum(Status, { description: The deployment status of a service, sourceMap: dag.sourceMap(src/types.ts, 12, 3), }) // 追加枚举成员 const completeTypeDef statusTypeDef .withEnumMember(success, { value: SUCCESS, description: Deployment succeeded, }) .withEnumMember(failed, { value: FAILED, description: Deployment failed, deprecated: Use withEnumMember instead, }) // 注册进模块 const module_ dag.module().withEnum(completeTypeDef)要点总结withEnum的opts两个字段均为可选最简调用只需dag.typeDef().withEnum(name)description为纯文档用途不影响类型语义sourceMap建议配合实际源码位置文件、行、列生成便于错误信息溯源枚举成员通过withEnumMember单独追加withEnumValue是已废弃的旧 APIclient.gen.ts应优先使用前者。关联 API 参考TypeDefWithEnumOpts是 Dagger TypeScript SDK 自动生成的类型定义之一与其密切相关的还有SourceMap类sourceMap字段的类型表示源码位置映射对象TypeDefWithEnumMemberOpts定义枚举成员的选项值、描述、源码映射、弃用说明见 client.gen.tsTypeDef.withEnum()与Module.withEnum()分别用于构建枚举类型与将枚举注册到模块见 client.gen.ts 与 client.gen.ts。以上类型与方法均位于 TypeScript SDK 自动生成客户端 sdk/typescript/src/api/client.gen.ts读者可结合 TypeScript SDK 入口文档docs/versioned_docs/version-0.20/reference/typescript/README.md进行更系统的查阅。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考