signature and implementation

함수 오버로딩 구조

오버로딩은 여러 호출 형태를 타입으로 보여주되 실제 실행 함수는 하나라는 점을 분명히 이해해야 합니다.

호출 시그니처

사용 가능한 형태 나열

인자 조합마다 반환 타입이 달라지는 경우를 독립된 선언으로 나눠 호출과 결과의 짝을 고정합니다.

parse(x: string): number
구현 시그니처

하나의 실제 함수

런타임에는 하나의 함수가 typeof나 Array.isArray로 경우를 나눕니다.

function parse(x: unknown)
유니온 비교

간단하면 union

반환 타입이 입력 타입과 강하게 연결되지 않으면 유니온이 더 단순할 수 있습니다.

string | number
API 문서화

호출부 예측 향상

오버로드는 다양한 사용법을 자동완성과 문서처럼 드러내는 효과가 있습니다.

overload list
관계 확인 입력 조합에 따라 반환 타입이 명확히 달라질 때 오버로드를 고려합니다.
구현 폭 구현 시그니처는 모든 오버로드 인자를 받을 수 있을 만큼 넓어야 합니다.
분기 안전 함수 내부는 타입 가드로 각 경우를 좁힌 뒤 값을 다룹니다.

오버로딩은 복잡한 함수 사용법을 호출자에게 선명하게 보여줄 때 가장 빛납니다.