feat(ts): ts_error_handling=result — typed Result return for es-mode client

[hishamank]

What

Adds an opt-in ts_error_handling=result option to protoc-gen-ts-client. In protobuf-es mode it switches unary client methods from throwing to returning a typed discriminated union, so RPC error handling is compiler-checked instead of try/catch over unknown.

const r = await client.getAccount({ id });
if (!r.ok) {
  const e = r.error; // ValidationError | ApiError | NotFoundError | LoginError | ...
  if (e instanceof ValidationError) { /* e.violations */ }
  else if (e instanceof ApiError) { /* e.statusCode, e.body */ }
  else switch (e.$typeName) { case "pkg.NotFoundError": /* e.resourceType */ }
  return;
}
r.data; // Account (typed, non-null)

Default (throwing) behavior and hand-rolled output are unchanged. The flag fails loud without ts_runtime=protobuf-es.

Why

Per a product directive: when consumers use the protobuf-es client, errors should be typed and returned, not thrown — a method should return either data or a typed error.

Design

• Result shape — { ok: true; data: T; error?: undefined } | { ok: false; data?: undefined; error: E }. ok discriminant and always-present data/error (inactive one undefined), so both if (r.ok) and const { data, error } work.
• Typed error union — sebuf has no per-RPC error declaration (any handler may return any *Error), so ClientError = ValidationError | ApiError | <every proto *Error type>. A shared result.ts carries a structural registry + decodeError (400+violations → ValidationError; else first *Error whose JSON marker keys all match → typed proto error, narrowable via protobuf-es $typeName; fallback ApiError). This mirrors the Python client's _ERROR_CLASSES.
• Scope — unary only. SSE keeps AsyncGenerator<T> and still throws on stream-open (a single Result doesn't fit a stream). handleError is emitted only when an SSE method still needs it.

Tests / verification

• es-result golden fixtures: with proto errors (result_errors.proto), without (get_params), and mixed unary+SSE (sse) — each in its own golden subdir since result.ts is invocation-global.
• tsc --noEmit typecheck of the es-result goldens against the real @bufbuild/protobuf@2.12.1 — proves the Result return, the ClientError union, the registry, and $typeName narrowing all compile.
• Unit tests for ParseErrorHandling / ValidateRuntimeOptions (result-without-es fails loud).
• Full go test ./internal/... green; existing es/hand-rolled goldens byte-identical (no behavior change in throw mode).
• Docs: new "Typed Result returns" section in docs/client-generation.md.

Base

Targets feat/ts-es-transport (#207) since it reuses that branch's es transport + modules machinery. Rebase onto main once #207 (and its base) land.

🤖 Generated with Claude Code

[SebastienMelki]

Thanks Hicham — the Result mode is well-designed and composes cleanly with the es transport. The three-tier decode (ValidationError → structural registry → ApiError) mirrors the Python client nicely, and the conditional handleError omission for SSE is handled correctly. Ready to merge once #207 lands and the one suggestion below is addressed.

---

Suggestion (non-blocking but worth fixing before consumers hit it)

Empty-field error messages match everything in the registry

In result.go, the registry entry for a proto *Error message uses its field JSON names as discriminator keys:

if (keys.every((k) => k in json)) {

[].every(...) returns true for any predicate. So a message InternalError {} (zero fields) would match every response body, shadowing all subsequent registry entries. This is a realistic edge case — simple sentinel error messages with no payload are common.

Fix options:

• Skip zero-field error messages from the registry entirely (they can't be structurally distinguished anyway — fall through to ApiError)
• Or require keys.length > 0 && keys.every(...) in the emitted decodeError

Either way, consider documenting that the registry relies on distinct field sets for disambiguation — like the Python client does.

---

Observations (all positive)

• Result type shape is correct — { ok: true; data: T; error?: undefined } | { ok: false; data?: undefined; error: E } enables both if (r.ok) narrowing and const { data, error } destructuring.
• ValidateRuntimeOptions correctly rejects result without protobuf-es — good fail-loud behavior.
• handleError omission is precisely scoped: emitted only when SSE methods exist in result mode, avoiding noUnusedLocals violations.
• Test coverage is solid: three golden subdirs (no-errors, typed-errors, mixed SSE), plus tsc --noEmit typecheck against real @bufbuild/protobuf, plus unit tests for parse/validation.
• DescMessage import correctly added as type-only to the @bufbuild/protobuf import machinery.
• No regressions — existing es and hand-rolled goldens byte-identical.

Nice work on this one — the typed Result pattern will be a big DX improvement for consumers.