Sebuf

Phase 04 Plan 04: Enum Encoding Summary

Custom enum value JSON mapping with enum_value annotation and NUMBER encoding support across all 4 generators

Performance#

  • Duration: ~25 min
  • Started: 2026-02-06
  • Completed: 2026-02-06
  • Tasks: 3
  • Files modified: 21

Accomplishments#

  • Implemented enum encoding in Go generators (httpgen, clientgen) with custom MarshalJSON/UnmarshalJSON
  • Added enum lookup maps (toJSON/fromJSON) for bidirectional custom value mapping
  • Updated ts-client to generate custom union types and number type for NUMBER encoding
  • Updated OpenAPI to generate custom enum values and integer type for NUMBER encoding
  • Added comprehensive golden file tests for enum encoding across all 4 generators

Task Commits#

Each task was committed atomically:

  1. Task 1: Implement enum encoding in Go generators - 9874a8e (feat)
  2. Task 2: Implement enum encoding in ts-client and OpenAPI - ed5bb67 (feat)
  3. Task 3: Add golden file tests for enum encoding - e470e25 (test)

Files Created/Modified#

Created:

  • internal/httpgen/enum_encoding.go - Enum MarshalJSON/UnmarshalJSON generation for httpgen
  • internal/clientgen/enum_encoding.go - Identical enum encoding for clientgen
  • internal/httpgen/testdata/proto/enum_encoding.proto - Test proto with Status (custom values) and Priority enums
  • internal/httpgen/testdata/golden/enum_encoding_enum_encoding.pb.go - Generated enum encoding code
  • internal/tsclientgen/testdata/golden/enum_encoding_client.ts - TypeScript with custom union types
  • internal/openapiv3/testdata/golden/yaml/EnumEncodingService.openapi.yaml - OpenAPI with custom enum schemas

Modified:

  • internal/httpgen/generator.go - Calls validateEnumAnnotationsInFile and generateEnumEncodingFile
  • internal/clientgen/generator.go - Same changes for client generator
  • internal/tsclientgen/types.go - Updated generateEnumType, tsFieldType, tsElementType for custom values and NUMBER encoding
  • internal/openapiv3/types.go - Updated convertEnumField for custom values and integer enum schema

Decisions Made#

  • D-04-04-01: Created separate enum_encoding.go files to avoid import conflicts with existing encoding.go (int64)
  • D-04-04-02: UnmarshalJSON accepts both proto name AND custom value for backward compatibility
  • D-04-04-03: NUMBER encoding produces number in TypeScript and integer in OpenAPI

Deviations from Plan#

None - plan executed exactly as written.

Issues Encountered#

None.

User Setup Required#

None - no external service configuration required.

Next Phase Readiness#

  • Enum encoding complete across all 4 generators
  • Ready for Plan 05 (cross-generator consistency tests)
  • All existing tests pass

Phase: 04-json-primitive-encoding Completed: 2026-02-06