Files

T

koriweb d8a80f6272 chore(wiki): dangling 링크 canonical 정규화 (768파일/1200건)

이름만 다른(표기 변형) [[위키링크]]를 대상 문서의 canonical 제목으로 치환해
끊겼던 1,200개 링크를 연결. 제목/파일명 정규화 일치만 적용하고 별칭 매칭은
과병합 위험으로 제외(애매성 가드). 원본은 _link_reconcile_backup/ 에 백업.
도구: Datacollect/scripts/link_reconcile_apply.mjs

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-08 12:24:15 +09:00

7.2 KiB

Raw Blame History

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

title

API Response & State Modeling

📌 한 줄 통찰

"매 invalid state 의 unrepresentable". Discriminated union + Result type. 매 compile-time exhaustive check. 매 runtime bug 의 prevent.

📖 핵심

매 problem (without modeling)

// ❌ Optional everything
type Response = {
  data?: User;
  error?: string;
  loading?: boolean;
};

// 매 combination 의 가능?
// loading=true, data=set ?
// error=set, data=set ?
// 매 inconsistent state.

Solution: Discriminated Union (Tagged Union)

type Response =
  | { type: 'idle' }
  | { type: 'loading' }
  | { type: 'success'; data: User }
  | { type: 'error'; message: string };

// 매 state 의 explicit. 매 invalid 의 impossible.

Result type

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

// Usage
async function fetchUser(id: string): Promise<Result<User>> {
  try {
    const user = await api.users.get(id);
    return { ok: true, value: user };
  } catch (e) {
    return { ok: false, error: e as Error };
  }
}

// Caller
const result = await fetchUser('123');
if (result.ok) {
  console.log(result.value.name);   // type: User
} else {
  console.error(result.error);
}

Exhaustive check

function render(state: Response) {
  switch (state.type) {
    case 'idle': return <Idle />;
    case 'loading': return <Spinner />;
    case 'success': return <Profile user={state.data} />;
    case 'error': return <Error msg={state.message} />;
    default:
      const _: never = state;   // compile error if state added
      throw new Error('unreachable');
  }
}

→ 매 새 state 의 추가 시 compiler 의 exhaustive check.

매 application

React state

const [state, setState] = useState<Response>({ type: 'idle' });

// 매 fetching
setState({ type: 'loading' });

const result = await fetchUser(id);
if (result.ok) {
  setState({ type: 'success', data: result.value });
} else {
  setState({ type: 'error', message: result.error.message });
}

TanStack Query (built-in)

const { data, error, isLoading, isSuccess } = useQuery({...});

if (isLoading) return <Spinner />;
if (error) return <Error msg={error.message} />;
return <Profile user={data} />;

→ 매 query state 의 already discriminated.

State machine (XState)

import { createMachine } from 'xstate';

const machine = createMachine({
  id: 'fetch',
  initial: 'idle',
  states: {
    idle: { on: { FETCH: 'loading' } },
    loading: { on: { SUCCESS: 'success', ERROR: 'error' } },
    success: { on: { REFETCH: 'loading' } },
    error: { on: { RETRY: 'loading' } },
  },
});

매 API response shape

Success / Error envelope

type APIResponse<T> = 
  | { status: 'ok'; data: T }
  | { status: 'error'; code: string; message: string };

Pagination

type Paginated<T> = {
  data: T[];
  meta: { total: number; page: number; perPage: number };
};

Nullable vs Optional

// Nullable: 명시적 null
type User = { name: string; bio: string | null };

// Optional: 매 absent
type Update = { name?: string; bio?: string };

→ 매 different semantic.

Validation (runtime, Zod)

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  age: z.number().int().min(0),
});

type User = z.infer<typeof UserSchema>;

// 매 API response 의 parse + validate
const result = UserSchema.safeParse(await response.json());
if (result.success) {
  // result.data: User
} else {
  console.error(result.error);
}

→ 매 type + runtime 의 둘 다.

Branded types (extra safety)

type UserId = string & { __brand: 'UserId' };
type OrderId = string & { __brand: 'OrderId' };

function getUser(id: UserId) { ... }

const id = '123' as UserId;
getUser(id);          // OK
getUser('123');       // ❌ string ≠ UserId

💻 Code Pattern

Result + chain

class Result<T, E> {
  constructor(
    public readonly ok: boolean,
    public readonly value?: T,
    public readonly error?: E
  ) {}
  
  map<U>(fn: (v: T) => U): Result<U, E> {
    return this.ok ? Result.ok(fn(this.value!)) : Result.err(this.error!);
  }
  
  flatMap<U>(fn: (v: T) => Result<U, E>): Result<U, E> {
    return this.ok ? fn(this.value!) : Result.err(this.error!);
  }
  
  static ok<T, E>(value: T): Result<T, E> { return new Result(true, value); }
  static err<T, E>(error: E): Result<T, E> { return new Result(false, undefined, error); }
}

// Usage
const result = await fetchUser('123');
const name = result.map(u => u.name).map(s => s.toUpperCase());

Effect-TS (advanced FP)

import { Effect, pipe } from 'effect';

const program = pipe(
  Effect.tryPromise(() => api.users.get('123')),
  Effect.map(u => u.name),
  Effect.catchAll(e => Effect.succeed('Unknown')),
);

const result = await Effect.runPromise(program);

React hook with state

function useFetchUser(id: string) {
  const [state, setState] = useState<{
    status: 'idle' | 'loading' | 'success' | 'error';
    data?: User;
    error?: Error;
  }>({ status: 'idle' });
  
  useEffect(() => {
    setState({ status: 'loading' });
    fetchUser(id)
      .then(data => setState({ status: 'success', data }))
      .catch(error => setState({ status: 'error', error }));
  }, [id]);
  
  return state;
}

🤔 결정 기준

상황	추천
Simple state	Discriminated union
Async result	Result type
Complex state	XState machine
API response	Envelope + Zod validation
Type identity	Branded type
FP heavy	Effect-TS

기본값: Discriminated union + Result type + Zod validation.

🔗 Graph

부모: TypeScript · State Management · API-Design
변형: Discriminated-Union · Tagged-Union · Result Type
응용: XState · Effect TS
Adjacent: Branded-Types · Exhaustive-Check

🤖 LLM 활용

언제: 매 TypeScript app 의 state design. 매 API contract 의 type-safe. 언제 X: 매 simple primitive (boolean enough). 매 prototype.

❌ 안티패턴

Optional everything: invalid state.
any for response: type 의 가치 X.
No exhaustive check: 매 새 state 의 missed.
Throw + catch 만: Result type 의 더 explicit.
No runtime validation: 매 wrong API response 의 silent.

🧪 검증 / 중복

Verified (TypeScript handbook, neverthrow library docs).
신뢰도 B.
Related: Tagged_Union_Discriminated_Types · TS_Schema_Validation_Comparison.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-09	Manual cleanup — discriminated union + Result + state machine + code

7.2 KiB Raw Blame History