enum.go

// Package enum: Utilities to manage Go native enum with custom metadata
// Provides type-safe enum descriptors with metadata binding
// Supports two generics: enumCode and metaType
//
// enum: Go 原生枚举元数据管理工具
// 提供带元数据绑定的类型安全枚举描述符
// 支持双泛型：enumCode 和 metaType
package enum

// Enum wraps a Go native enum with custom metadata
// Associates custom metadata with the enum value via Meta() method
// Uses two generics to maintain type checking across enum and metadata
//
// Enum 使用自定义元数据包装 Go 原生枚举
// 通过 Meta() 方法关联枚举值与自定义元数据
// 使用双泛型在枚举和元数据类型间保持类型安全
type Enum[enumCode comparable, metaType any] struct {
	code enumCode // Go native enum value (e.g. type StatusType string) // Go 原生枚举值（如 type StatusType string）
	meta metaType // Custom metadata of the enum // 枚举的自定义元数据
}

// NewEnum creates a new Enum instance with Go native enum
// Use this when you just need enum mapping without description
// Returns a reference to the created Enum instance
//
// 创建新的 Enum 实例，绑定 Go 原生枚举
// 当只需要枚举映射而不需要描述时使用此函数
// 返回创建的 Enum 实例指针
func NewEnum[enumCode comparable](code enumCode) *Enum[enumCode, *MetaNone] {
	return &Enum[enumCode, *MetaNone]{
		code: code,
		meta: &MetaNone{},
	}
}

// NewEnumWithDesc creates a new Enum instance with Go native enum and description
// Use this when you need both enum mapping and human-readable description
// The description param provides custom description used in docs and UI
//
// 创建带有 Go 原生枚举和描述的新 Enum 实例
// 当需要枚举映射和人类可读描述时使用此函数
// description 参数提供用于文档和显示的自定义描述
func NewEnumWithDesc[enumCode comparable](code enumCode, description string) *Enum[enumCode, *MetaDesc] {
	return &Enum[enumCode, *MetaDesc]{
		code: code,
		meta: &MetaDesc{
			description: description,
		},
	}
}

// NewEnumWithMeta creates a new Enum instance with Go native enum and custom metadata
// Use this when you need customized metadata types beyond simple string description
// The meta param accepts custom metadata types (e.g. i18n descriptions)
//
// 创建带有 Go 原生枚举和自定义元数据的新 Enum 实例
// 当需要超越简单字符串描述的灵活元数据类型时使用此函数
// meta 参数接受任意自定义元数据类型（如双语描述）
func NewEnumWithMeta[enumCode comparable, metaType any](code enumCode, meta metaType) *Enum[enumCode, metaType] {
	return &Enum[enumCode, metaType]{
		code: code,
		meta: meta,
	}
}

// Code returns the Go native enum value
// Provides access to the source enum value
//
// 返回 Go 原生枚举值
// 提供对源枚举值的访问
func (e *Enum[enumCode, metaType]) Code() enumCode {
	return e.code
}

// Meta returns the metadata associated with this enum
// Provides access to custom metadata like description via MetaDesc
//
// 返回与此枚举关联的元数据
// 提供对自定义元数据（如通过 MetaDesc 获取描述）的访问
func (e *Enum[enumCode, metaType]) Meta() metaType {
	return e.meta
}