Sebuf

Phase 4 Plan 3: ts-client and OpenAPI Int64 Encoding Summary

TypeScript and OpenAPI generators now produce encoding-aware types for int64/uint64 fields based on int64_encoding annotation

Performance#

  • Duration: 15 min
  • Started: 2026-02-05T22:27:55Z
  • Completed: 2026-02-05T22:43:15Z
  • Tasks: 3
  • Files created: 6
  • Files modified: 5

Accomplishments#

  • TypeScript client generates number type for NUMBER-encoded int64/uint64 fields
  • TypeScript client generates string type for STRING/UNSPECIFIED (default)
  • OpenAPI generates type: integer, format: int64 for NUMBER encoding
  • OpenAPI generates type: string, format: int64 for STRING/UNSPECIFIED
  • OpenAPI includes precision warning in description for NUMBER-encoded fields
  • Golden file tests verify all encoding variants work correctly

Task Commits#

Each task was committed atomically:

  1. Task 1: Implement int64 encoding in ts-client generator - 46a0cdf (feat)
  2. Task 2: Implement int64 encoding in OpenAPI generator - fab15fb (feat)
  3. Task 3: Add golden file tests - d9e51d5 (test)
  4. Lint fixes - aa3e686 (fix)

Files Created/Modified#

ts-client changes:

  • internal/tsclientgen/types.go - Added tsScalarTypeForField, tsZeroCheckForField with encoding checks
  • internal/tsclientgen/generator.go - Updated query param zero check to use field-aware function
  • internal/tsclientgen/golden_test.go - Added int64_encoding test case

OpenAPI changes:

  • internal/openapiv3/types.go - Added encoding checks in convertScalarField, appendInt64PrecisionWarning helper
  • internal/openapiv3/exhaustive_golden_test.go - Added Int64EncodingService test cases

Test protos and golden files:

  • internal/httpgen/testdata/proto/int64_encoding.proto - Comprehensive test proto with all encoding variants
  • internal/tsclientgen/testdata/golden/int64_encoding_client.ts - Shows number/string types
  • internal/openapiv3/testdata/golden/yaml/Int64EncodingService.openapi.yaml - Shows integer/string schemas with warnings

Decisions Made#

  • D-04-03-01: tsScalarTypeForField pattern - keep base tsScalarType unchanged, add encoding-aware variant
  • D-04-03-02: appendInt64PrecisionWarning called after description set - ensures comment text + warning combined
  • D-04-03-03: nolint directives for valid lint warnings - exhaustive (has default), funlen (big switch), nestif (existing pattern)

Deviations from Plan#

None - plan executed exactly as written.

Issues Encountered#

Parallel execution with Plan 04-02:

  • Some 04-02 commits appeared interleaved with 04-03 commits
  • Leftover uncommitted 04-02 files caused test failures
  • Resolution: Discarded uncommitted 04-02 test case additions from httpgen and clientgen

User Setup Required#

None - no external service configuration required.

Next Phase Readiness#

  • ts-client and OpenAPI generators handle int64_encoding annotation
  • Plan 04-04 (enum encoding) can use same patterns
  • Plan 04-05 (cross-generator verification) can verify consistency

Golden File Verification#

TypeScript golden shows correct types:

export interface Int64EncodingTest {
  defaultInt64: string;      // no annotation -> string
  stringInt64: string;       // STRING -> string
  numberInt64: number;       // NUMBER -> number
  defaultUint64: string;     // no annotation -> string
  numberUint64: number;      // NUMBER -> number
  repeatedNumberInt64: number[];  // NUMBER repeated -> number[]
  repeatedDefaultInt64: string[]; // default repeated -> string[]
}

OpenAPI golden shows correct schemas with warning:

numberInt64:
  type: integer
  format: int64
  description: 'NUMBER encoding - should be number in JSON (precision risk for > 2^53). Warning: Values > 2^53 may lose precision in JavaScript'
defaultInt64:
  type: string
  format: int64
  description: Default int64 (no annotation) - should be string in JSON

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