2nd/10_Wiki/Topics/Frontend/Discriminated-Unions-for-Error-Handling.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-discriminated-unions-for-error-h	Discriminated Unions for Error Handling	10_Wiki/Topics	verified	self	Tagged Unions Result Type Sum Types	none	A	0.9	applied	typescript error-handling type-system functional		2026-05-10	pending	language framework TypeScript none

Discriminated Unions for Error Handling

매 한 줄

"매 throw 의 의 X — return value 의 success/failure 의 model". ML/Haskell Either, Rust Result<T, E> 의 TypeScript port. 2026 의 매 typed exception 의 alternative — exhaustive checking + traceable failure path.

매 핵심

매 왜 throw 의 X 의

• throw 의 type-erased — caller 의 매 catch 의 type 의 unknown.
• Control flow 의 invisible — 매 implicit goto.
• async 의 매 unhandled rejection 의 silent.

매 discriminator tag

• 매 literal field (type, tag, _tag, kind) 의 매 union 의 narrow.
• TypeScript 의 control-flow analysis 의 if (r.type === "ok") 의 narrow.
• exhaustive check 의 switch + never 의 가능.

매 응용

1. API client (network/parse/validation 의 error 의 분리).
2. Form validation (field-level error).
3. Parser combinator (success/fail with location).
4. State machine (state 의 each 의 tag).

💻 패턴

기본 Result type

type Result<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E };

const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
const err = <E>(error: E): Result<never, E> => ({ ok: false, error });

Domain error 의 tagged

type FetchUserError =
  | { type: "network"; cause: unknown }
  | { type: "not_found"; userId: string }
  | { type: "unauthorized" }
  | { type: "parse"; raw: unknown; issue: string };

async function fetchUser(id: string): Promise<Result<User, FetchUserError>> {
  let res: Response;
  try {
    res = await fetch(`/api/users/${id}`);
  } catch (cause) {
    return err({ type: "network", cause });
  }
  if (res.status === 404) return err({ type: "not_found", userId: id });
  if (res.status === 401) return err({ type: "unauthorized" });

  const raw = await res.json();
  const parsed = UserSchema.safeParse(raw);
  if (!parsed.success) {
    return err({ type: "parse", raw, issue: parsed.error.message });
  }
  return ok(parsed.data);
}

Exhaustive handling

function renderError(e: FetchUserError): string {
  switch (e.type) {
    case "network":      return "Network failure. Retry?";
    case "not_found":    return `User ${e.userId} 의 X.`;
    case "unauthorized": return "Login 의 필요.";
    case "parse":        return `Bad response: ${e.issue}`;
    default: {
      const _exhaustive: never = e;  // 매 compile error 의 새 case 의 추가 시
      return _exhaustive;
    }
  }
}

Caller 의 narrow 의 사용

const r = await fetchUser("abc");
if (!r.ok) {
  // r.error: FetchUserError — 매 fully typed
  return renderError(r.error);
}
// r.value: User — 매 narrowed
console.log(r.value.email);

Combinator (map / flatMap)

function map<T, U, E>(r: Result<T, E>, f: (t: T) => U): Result<U, E> {
  return r.ok ? ok(f(r.value)) : r;
}

function flatMap<T, U, E>(r: Result<T, E>, f: (t: T) => Result<U, E>): Result<U, E> {
  return r.ok ? f(r.value) : r;
}

// 매 chained pipeline
const result = flatMap(
  await fetchUser(id),
  (u) => u.verified ? ok(u) : err({ type: "unauthorized" } as FetchUserError),
);

Form validation

type FieldResult<T> =
  | { state: "valid"; value: T }
  | { state: "invalid"; reasons: string[] }
  | { state: "pending" };

function validateEmail(s: string): FieldResult<string> {
  if (s.length === 0) return { state: "pending" };
  const reasons: string[] = [];
  if (!s.includes("@")) reasons.push("@ missing");
  if (s.length > 254)   reasons.push("Too long");
  return reasons.length ? { state: "invalid", reasons } : { state: "valid", value: s };
}

Zod 의 native return

import { z } from "zod";

const UserSchema = z.object({ id: z.string(), email: z.email() });
const parsed = UserSchema.safeParse(input);
// parsed: { success: true; data: User } | { success: false; error: ZodError }

neverthrow 라이브러리 (2026 standard)

import { ok, err, Result, ResultAsync } from "neverthrow";

const fetchUserSafe = (id: string): ResultAsync<User, FetchUserError> =>
  ResultAsync.fromPromise(fetch(`/api/users/${id}`), (c) => ({ type: "network", cause: c } as const))
    .andThen((res) =>
      res.ok ? ResultAsync.fromSafePromise(res.json()) : err({ type: "not_found", userId: id } as const)
    );

매 결정 기준

상황	Approach
Domain logic 의 expected failure	Discriminated union Result
Truly exceptional (OOM, bug)	Throw
Async I/O	Promise<Result<T, E>> 의 neverthrow ResultAsync
Schema parsing	Zod safeParse
Multi-step pipeline	flatMap chain 의 Effect TS

기본값: domain error 의 tagged union, infrastructure error 의 throw.

🔗 Graph

• 부모: TypeScript · TypeScript 타입 시스템 (TypeScript Type System)
• 변형: Effect TS 및 ts-brand 라이브러리 활용
• 응용: Error Boundaries
• Adjacent: Zod · Pattern Matching

🤖 LLM 활용

언제: domain error 의 modeling, exhaustive switch 의 enforce, async error path 의 explicit. 언제 X: panic-level error (assertion fail) — throw 의 더 적합.

❌ 안티패턴

• { error: string | null; data: T | null }: 매 implicit invariant — 둘 모두 null/non-null 의 type 의 allow.
• String-only error: 매 i18n / programmatic handling 의 X.
• Discriminator 의 boolean: ok: true/false 의 OK, but multi-variant 의 X — string literal 의 사용.
• Throw inside Result-returning fn: 매 hybrid 의 worst.

🧪 검증 / 중복

• Verified (TypeScript handbook, Effect-TS docs, neverthrow, Rust Result, fp-ts Either).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — exhaustive check + neverthrow + combinators 추가