
앞서 작성한 Domain-Oriented Data Fetching 포스트에서는 fetcher를 한 단락 정도로만 소개했다. openapi-typescript가 만든 paths 안에는 경로와 HTTP 메서드, 요청 인자와 응답의 관계가 이미 들어 있다. 그런데 API를 호출할 때마다 그 관계를 사람이 다시 꺼내 DTO로 조립하고 있는 것이 영 찝찝했고, 그래서 호출 코드가 paths를 그대로 따라가게 만들었다는 이야기였다.
내가 호출하는 쪽에서 보고 싶었던 모양은 이 정도였다.
fetcher.get('health');fetcher.get('users', { query: { page: 1 },});fetcher.post('users', { body: { name: 'Ayden' },});경로와 메서드를 고르면 필요한 인자가 따라오고, 반환값도 해당 엔드포인트의 응답 타입으로 정해진다. 사용하는 쪽에서는 그냥 타입을 잘 아는 ky처럼 보이면 됐다. 문제는 저 평범한 호출 모양을 만들기 위해, 평범하지 않은 타입을 꽤 많이 거쳐야 했다는 것이다.
먼저 이 질문에 답하려고 호출 API를 직접 만들던 초기 구현을 따라가고, 그다음에는 같은 문제를 지금의 @ilokesto/fetcher가 어떻게 풀고 있는지 살펴보려고 한다. 전반부의 코드는 현재 API 레퍼런스라기보다 초기 설계의 기록에 가깝다. 전체 파일을 그대로 옮긴 것이 아니라, 각 단계의 질문에 답하는 타입과 구현만 발췌했다. 후반부는 @ilokesto/fetcher 1.0.5의 실제 소스를 기준으로 한다. 구현의 모양은 많이 달라졌지만 출발점의 질문은 같다. OpenAPI 타입 안에 이미 있는 관계를 어떻게 실제 호출 계약으로 옮길 것인가.
유저랜드에서 호출 API를 직접 만들던 시절
시작은 조금 수상한 빈 객체였다
초기 Fetcher 클래스는 이렇게 생겼다. 빈 객체를 FetcherInstance라고 단언한 뒤 HTTP 메서드별 함수를 런타임에 하나씩 꽂아 넣는다. 지금 봐도 약간 수상하다. 무엇보다 코드만 보면 왜 굳이 이런 모양이 되었는지 알기 어렵다.
public get: FetcherInstance['get'];public post: FetcherInstance['post'];private createFetcher(environment: Environment): FetcherInstance { const kyInstance = this.createKyInstance(environment); const fetcher = {} as FetcherInstance; (Object.values(HTTPMethod) as HttpMethod[]).forEach((method) => { fetcher[method] = (async (...) => { // ... }) as FetcherInstance[typeof method]; }); return fetcher;}다만 이 클래스가 먼저 있었던 것은 아니다. /api 접두사를 감추는 타입, 경로에서 가능한 메서드를 찾는 타입, 요청과 응답을 꺼내는 타입이 먼저 여기저기 생겼다. Fetcher는 그 타입들이 요구한 호출 모양을 마지막에 ky와 연결하는 역할을 맡았을 뿐이다. 그러니 이 수상한 빈 객체를 이해하려면, 저 타입들이 생긴 순서부터 거꾸로 따라가야 한다.
호출 코드에 /api까지 반복하고 싶지는 않았다
출발점은 openapi-typescript가 만들어 준 paths 타입이다. 서버가 OpenAPI 스펙에 /api/users/{userId}를 기록해 두면 생성된 타입도 당연히 그 경로를 안다. 하지만 클라이언트의 ky에는 이미 prefixUrl: '/api'가 설정되어 있었다. 실행할 때 사라질 접두사를 호출 코드와 자동완성에 계속 노출하고 싶지는 않았다.
그래서 타입에는 /api가 붙은 경로를 남기되, 호출할 때는 그 접두사를 뺀 경로를 쓰게 만들었다.
type ApiPrefix = '/api';type AddApiPrefix<T extends string> = `${ApiPrefix}/${T}`;export type PathWithoutApi<T extends keyof paths> = T extends `${ApiPrefix}/${infer Rest}` ? Rest : never;하는 일만 보면 별것 아닌 문자열 처리다. 호출자에게는 users/{userId}를 보여 주고, 타입 내부에서는 다시 /api/users/{userId}로 복원해 paths를 조회한다. 다만 이 작은 결정 때문에 이후의 모든 타입은 “사람이 입력하는 경로”와 “OpenAPI가 기억하는 경로” 사이를 오가게 된다.
그런데 경로를 찾았다고 요청이 정해지는 것은 아니다. 같은 users/{userId}에도 GET과 PATCH가 있을 수 있고, 둘이 받는 인자와 돌려주는 응답은 전혀 다르다.
경로와 메서드가 만나야 요청이 정해진다
그래서 openapi.ts에는 서로 비슷해 보이지만 답하는 질문이 다른 타입이 두 개 생겼다. 하나는 전체 API에 존재하는 HTTP 메서드를 구하고, 다른 하나는 선택한 경로에서 실제로 사용할 수 있는 메서드만 구한다.
export type ApiMethod = Extract< { [K in keyof ApiPaths]: keyof ApiPaths[K] }[keyof ApiPaths], string>;type ApiMethodForPath< T extends PathWithoutApi<keyof ApiPaths>> = keyof ApiPaths[AddApiPrefix<T>];처음에는 paths에서 경로 하나만 선택하면 충분할 것 같았다. 하지만 경로는 주소일 뿐이다. GET users/{userId}는 조회이고 PATCH users/{userId}는 수정이며, 요청 본문이 필요한 쪽과 쿼리 스트링만 받는 쪽도 그때 갈린다.
이 지점부터 이후의 타입은 늘 경로와 메서드를 함께 받는다. paths를 단순한 경로 목록이 아니라, 경로와 메서드의 조합으로 연산을 찾는 인덱스처럼 쓰기 시작한 것이다.
요청에 필요한 값은 한곳에 모여 있지 않았다
다음 문제는 찾아낸 연산에서 요청 타입을 꺼내는 일이었다. OpenAPI에서 경로 매개변수와 쿼리 스트링, 헤더는 parameters에 있지만 JSON 본문은 requestBody에 있다. 어떤 엔드포인트에는 둘 중 하나만 있고, 둘 다 없는 엔드포인트도 있다. 호출자는 요청 한 번을 보내는데 타입은 여러 군데 흩어져 있는 셈이다.
ApiRequestParams는 이 조각들을 호출자가 넘길 하나의 요청 객체로 모으는 타입이다.
export type ApiRequestParams< T extends PathWithoutApi<keyof ApiPaths>, M extends ApiMethod,> = ExtractParams< M extends ApiMethodForPath<T> ? Roll< ApiPaths[AddApiPrefix<T>][M] extends { parameters: infer P; } ? P : Record<string, never> > & (ApiPaths[AddApiPrefix<T>][M] extends { requestBody: { content: { 'application/json': infer B }; }; } ? { body: B } : Record<string, never>) : Record<string, never>>;타입은 길지만 질문은 단순하다. parameters가 있으면 가져오고, JSON 요청 본문이 있으면 { body: B }로 바꾼 뒤 둘을 교차 타입으로 합친다. 문제는 이렇게 합친 타입에 never나 undefined만 남은 필드가 따라붙기 쉽다는 점이다. 사람이 호출할 API에 타입 시스템의 청소 전 흔적까지 보여 줄 이유는 없어서 Clean과 ExtractParams가 뒤에 붙었다.
type Clean<T> = { [K in keyof T as T[K] extends undefined | never ? never : K]: T[K];};type ExtractParams<P> = P extends object ? Clean<P> : Record<string, never>;여기서 한 번 생각이 바뀌었다. 타입스크립트가 OpenAPI 문서를 읽게 만드는 것과, 사람이 이해할 수 있는 호출 API를 만드는 것은 같은 일이 아니었다. 전자는 스펙을 따라가면 되지만 후자는 필요 없는 흔적을 걷어 내고, 무엇을 호출자에게 보여 줄지 결정해야 한다.
요청을 골랐다면 응답도 따라와야 한다
요청 인자만 정확하고 반환값이 unknown이라면 절반만 연결한 셈이다. 같은 경로와 메서드의 조합에서 요청을 꺼냈으니, 응답도 그 조합에서 따라와야 한다. ApiResponse는 선택한 연산의 응답 가운데 성공한 JSON 본문을 찾는다.
export type ApiResponse< T extends PathWithoutApi<keyof ApiPaths>, M extends ApiMethod,> = M extends ApiMethodForPath<T> ? ApiPaths[AddApiPrefix<T>][M] extends { responses: { 200: { content: { 'application/json': infer R200 }; }; }; } ? R200 : ApiPaths[AddApiPrefix<T>][M] extends { responses: { 201: { content: { 'application/json': infer R201 }; }; }; } ? R201 : ApiPaths[AddApiPrefix<T>][M] extends { responses: { 204: { content: { 'application/json': infer R204 }; }; }; } ? R204 : never : never;처음부터 모든 HTTP 상태 코드와 모든 콘텐츠 타입을 완벽하게 해석하려고 하지는 않았다. 실제 API에서 자주 만나는 200, 201, 204 응답을 호출 결과에 연결하는 일이 먼저였다. 대신 경계도 분명했다. 204는 보통 본문이 없는데 이 타입은 application/json을 전제하고 있고, 오류 응답은 성공 반환 타입에 포함하지 않는다.
초기 런타임 구현에서도 이 경계가 그대로 드러난다. 성공하면 response.json()을 반환하지만 HTTPError가 발생하면 응답 본문을 읽어 예외로 던졌다. 성공 응답을 추론하는 일과 실패를 어떤 값으로 모델링할지는 같은 문제가 아니었고, 당시에는 두 문제를 억지로 한 타입에 넣지 않았다.
인자가 있느냐보다 언제 필수냐가 더 어려웠다
이제 글 앞에서 본 세 호출을 다시 볼 수 있다. health 요청에는 추가 인자가 없고, GET users의 쿼리는 엔드포인트에 따라 선택적일 수 있지만, POST users의 본문은 빠지면 안 된다. 요청 타입을 꺼내는 것만으로는 이 차이가 함수 호출에 반영되지 않는다.
처음에는 요청 객체 전체를 선택 인자로 두는 쪽이 편해 보였다. 하지만 그렇게 하면 본문이 필수인 요청도 fetcher.post('users')처럼 호출할 수 있다. 자동완성은 그럴듯한데 정작 중요한 제약을 놓치는, 별로 반갑지 않은 타입 안전성이다.
그래서 요청 객체 안에 필수 키가 하나라도 있는지를 검사하는 타입이 필요해졌다.
type RequiredKeys<T> = { [K in keyof T]-?: object extends Pick<T, K> ? never : K;}[keyof T];type HasRequiredKeys<T> = [RequiredKeys<T>] extends [never] ? false : true;여기서부터는 요청 객체가 아니라 함수의 인자 목록 자체를 조건부로 바꾸게 된다. 요청에 필수 값이 하나라도 있으면 [path, params, options?]를 강제하고, 그렇지 않으면 [path, options?]와 [path, params, options?]를 모두 허용한다. HasRequiredKeys는 작은 타입이지만, 호출 경험을 결정하는 데에는 앞의 긴 타입들만큼 중요했다.
흩어진 타입이 함수 시그니처를 얻었다
이제야 앞에서 만든 타입들을 get, post, put, delete, patch라는 호출 API로 묶을 수 있다. 그 역할을 맡은 타입이 FetcherInstance다.
type OptionalParamsArgs< P extends RelativeURLwithSwagger, M extends HttpMethod,> = | [path: P, options?: Options] | [path: P, params: RequestParams<P, M>, options?: Options];export type FetcherInstance = { [M in HttpMethod]: <P extends string>( ...args: P extends RelativeURLwithSwagger ? HasRequiredKeys< RequestParams<Extract<P, RelativeURLwithSwagger>, M> > extends true ? [ path: P, params: RequestParams<Extract<P, RelativeURLwithSwagger>, M>, options?: Options, ] : OptionalParamsArgs<Extract<P, RelativeURLwithSwagger>, M> : [path: P, options?: Options] ) => Promise< P extends RelativeURLwithSwagger ? ApiResponse<Extract<P, RelativeURLwithSwagger>, M> : unknown >;};처음 보면 가장 읽기 싫은 타입이기도 하다. 그래도 앞의 질문을 순서대로 대입하면 하는 일은 보인다. HTTP 메서드마다 같은 모양의 함수를 만들고, 입력한 경로가 OpenAPI에 있는지 확인하고, 알려진 경로라면 요청 인자의 필수성을 계산한 뒤 같은 경로와 메서드에서 응답 타입을 꺼낸다.
한 가지는 일부러 느슨하게 남겼다. OpenAPI에 없는 경로라고 해서 호출 자체를 막지는 않고, 일반 string 경로와 ky 옵션을 받는 탈출구를 두었다. 스펙에 등록되지 않은 임시 엔드포인트 하나 때문에 HTTP 클라이언트 전체를 우회하게 만드는 것도 이상하다고 생각했다. 대신 그 탈출구를 선택한 순간 반환 타입은 unknown이 된다.
이런 이유로 FetcherInstance는 Fetcher 클래스에 딸린 부수적인 타입이 아니다. 경로와 메서드, 요청과 응답, 필수 인자와 선택 인자에 관한 결정이 처음으로 하나의 함수 시그니처를 얻은 자리다. 오히려 런타임 클래스가 이 계약을 따라가야 했다.
타입 계약만으로는 요청을 보낼 수 없으니까
물론 타입이 아무리 정교해도 실제 HTTP 요청은 나가지 않는다. 호출자는 경로 매개변수와 쿼리, 본문이 담긴 객체를 넘기지만 ky는 완성된 URL과 Options를 받아야 한다. BaseHttpClient는 이 두 언어 사이를 번역하는 레이어였다.
export abstract class BaseHttpClient extends AuthRefresh { protected processRequestParams( path: string, paramsOrOptions?: Record<string, unknown> | Options, additionalOptions?: Options, ): { finalPath: string; finalOptions: Options } { return processRequestParams(path, paramsOrOptions, additionalOptions); } protected processPathParams( path: string, pathParams?: Record<string, string>, ): string { return processPathParams(path, pathParams); } protected buildKyOptions(params: Record<string, unknown>): Options { return buildKyOptions(params); }}구체적으로는 경로 매개변수를 URL에 치환하고, 요청 객체의 쿼리와 본문을 ky 옵션으로 바꾼다. 인증 갱신처럼 모든 요청에 걸치는 관심사도 이 경계에 모았다. 타입에서 path, query, body를 한 객체로 합친 것은 호출자의 편의를 위한 결정이고, 런타임에서는 결국 그것을 다시 HTTP 클라이언트가 이해하는 모양으로 풀어야 했다.
FetcherInstance가 호출자의 계약이라면 BaseHttpClient는 그 계약을 실제 요청으로 옮기는 기반이다. 둘 중 하나만 있어서는 타입이 맞는 척만 하거나, 반대로 요청은 나가지만 호출할 때마다 타입을 다시 조립해야 한다.
그래서 처음의 Fetcher는 저런 모양이었다
이제 글 첫머리의 수상한 코드로 돌아갈 수 있다. Fetcher는 환경에 따라 서로 다른 ky 인스턴스를 만들고, FetcherInstance가 요구하는 메서드를 런타임 객체에 연결한다.
private createFetcher(environment: Environment): FetcherInstance { const kyInstance = this.createKyInstance(environment); const fetcher = {} as FetcherInstance; (Object.values(HTTPMethod) as HttpMethod[]).forEach((method) => { fetcher[method] = (async ( path: string, paramsOrOptions?: Record<string, unknown> | Options, options?: Options, ) => { const { finalPath, finalOptions } = this.processRequestParams( path, paramsOrOptions, options, ); const kyMethod = kyInstance[method]; const response = await kyMethod.call( kyInstance, finalPath, finalOptions, ); return response.json(); }) as FetcherInstance[typeof method]; }); return fetcher;}이 구현은 FetcherInstance의 복잡한 판단을 런타임에서 다시 수행하지 않는다. 런타임은 경로와 옵션을 정리해 ky를 호출하면 된다. 경로가 OpenAPI에 정의되어 있는지, 요청 본문이 반드시 필요한지, 어떤 응답 타입을 돌려줄지는 타입 시스템이 호출 전에 맡는다. 타입과 런타임이 같은 일을 두 번 하는 것이 아니라, 서로 다른 책임을 나눠 가진 셈이다.
물론 서버와 브라우저가 요청을 보내는 방식까지 같지는 않았다. 서버에서는 쿠키를 전달하고 요청 시간을 기록해야 했고, 브라우저에서는 credentials: 'include'와 401 처리 훅이 필요했다. 그래도 외부에 노출되는 호출 계약은 같은 FetcherInstance로 유지할 수 있었다. 타입 계약은 하나이고, 환경 차이는 그 계약 아래의 런타임 구현이 맡았다.
fetcher라는 이름은 나중에 붙었다
처음부터 “타입 추론 엔진이 내장된 ky를 만들자”라고 시작한 것은 아니었다. /api를 호출 코드에서 감추고 싶었고, 경로에서 가능한 메서드를 찾고 싶었고, OpenAPI 여러 곳에 흩어진 요청 타입을 사람이 넘길 객체 하나로 모으고 싶었다. 그러다 보니 필수 키를 함수 인자에 반영해야 했고, 같은 조합에서 응답 타입도 꺼내야 했다.
FetcherInstance는 이 조각들이 더는 각자의 유틸리티 타입으로 남아 있을 수 없게 된 자리였다. 타입이 실제 함수 시그니처가 되면서 비로소 호출 경험이 생겼고, Fetcher 클래스는 그 계약을 ky에 연결했다. 구현 순서로 보면 클래스보다 타입이 먼저였고, 타입보다 먼저 있었던 것은 “이미 paths 안에 있는 관계를 왜 내가 다시 조립하고 있지?”라는 찝찝함이었다.
지금의 @ilokesto/fetcher는 이 초기 구현과 같은 모양이 아니다. 그래도 내가 이 설계에서 계속 가져가고 싶은 것은 복잡한 유틸리티 타입 자체가 아니라, OpenAPI의 관계를 호출 코드에서 다시 선언하지 않는다는 원칙이다. fetcher는 그 원칙이 경로, 메서드, 요청, 응답을 하나의 호출로 묶은 뒤에야 붙은 이름이었다.
지금의 fetcher는 ky를 다시 만들지 않는다
초기 구현을 독립 패키지로 떼어 내면서 가장 먼저 다시 생각한 것은 타입보다 런타임이었다. 당시의 Fetcher는 겉으로는 ky처럼 보였지만 실제로는 ky 위에 별도의 HTTP 클라이언트를 하나 더 만든 구조였다. 환경별 인스턴스를 직접 만들고, 메서드를 빈 객체에 설치하고, 응답을 곧바로 json()으로 파싱했다. 새로운 기능을 붙일수록 ky가 이미 해결한 일을 Fetcher에서도 다시 설명해야 했다.
지금의 기준은 반대다. HTTP 요청의 동작은 ky가 소유하고, fetcher는 OpenAPI 타입으로 호출 계약을 만들고 그 입력을 ky가 이해할 수 있는 값으로 정규화하는 일만 맡는다. 말하자면 ky를 닮은 클라이언트를 만드는 대신, 실제 KyInstance 위에 **OpenAPI를 아는 얇은 호출 API를 올린다.**
출발점이 빈 객체가 아니라 KyInstance가 되었다
현재의 createFetcher는 옵션을 받아 ky 인스턴스를 만들거나, 이미 만들어진 KyInstance를 그대로 받는다. 그리고 두 경우 모두 같은 decorateKyInstance로 넘긴다.
export function createFetcher<Paths extends PathsLike>(): Fetcher<Paths>;export function createFetcher<Paths extends PathsLike>( defaultOptions: Options,): Fetcher<Paths>;export function createFetcher<Paths extends PathsLike>( instance: KyInstance,): Fetcher<Paths>;export function createFetcher<Paths extends PathsLike>( input?: Options | KyInstance,): Fetcher<Paths> { const instance = typeof input === 'function' ? input : ky.create(input); return decorateKyInstance<Paths>(instance);}이 차이는 생각보다 크다. 예전의 Fetcher는 환경, 인증, 오류 처리, 응답 파싱을 자기 클래스 안에서 조합했다. 지금의 createFetcher는 ky.create()가 만든 인스턴스뿐 아니라 애플리케이션이 이미 훅과 재시도, 사용자 정의 fetch를 설정해 둔 인스턴스도 받을 수 있다. fetcher가 설정의 주인이 되지 않아도 된다.
그래서 패키지의 중심 질문도 달라졌다. “HTTP 클라이언트를 어떻게 구현할까?”가 아니라 “이 KyInstance에 OpenAPI 호출 계약을 어떻게 덧붙일까?”가 되었다.
클래스 계층 대신 호출 가능한 함수를 꾸민다
KyInstance는 그 자체로 호출 가능한 함수다. 현재 구현은 이 성질을 그대로 이용한다. 직접 호출할 때 사용할 call 함수를 만들고, 여기에 get, post, safe, create, extend를 붙여 Fetcher<Paths>로 돌려준다.
src/core/createFetcher.ts 221-280행에서 기본 옵션과 safe, 파생 인스턴스를 다루는 부분을 덜어 내고 핵심 흐름만 남기면 다음과 같다. 그대로 복사해 쓸 수 있는 전체 구현은 아니다.
const decorateKyInstance = <Paths extends PathsLike>( instance: KyInstance,): Fetcher<Paths> => { const call = (input: Input, options?: Options) => { // 기본 method와 Request 입력을 처리하는 분기는 생략했다. const request = prepareKyRequest({ input, method: toOpenApiMethod(options?.method), options, }); return executeKyCall( request.input, request.options, (nextInput, nextOptions) => instance(nextInput, nextOptions), ); }; const fetcher = call as Fetcher<Paths>; fetcher.get = bindShortcutMethod(instance, 'get'); fetcher.post = bindShortcutMethod(instance, 'post'); fetcher.put = bindShortcutMethod(instance, 'put'); fetcher.patch = bindShortcutMethod(instance, 'patch'); fetcher.delete = bindShortcutMethod(instance, 'delete'); return fetcher;};여전히 타입 단언은 있다. 런타임에 프로퍼티를 붙여 호출 가능한 교차 타입을 만드는 이상, call as Fetcher<Paths> 같은 경계는 피하기 어렵다. 다만 단언이 맡는 책임은 예전보다 훨씬 좁다. 빈 객체 전체가 올바른 HTTP 클라이언트라고 믿는 대신, 이미 동작하는 KyInstance로 향하는 함수에 타입이 보장한 호출 계약을 붙인다.
각 단축 메서드도 실제 요청을 새로 구현하지 않는다. bindShortcutMethod는 입력을 준비한 뒤 instance[method](...)를 호출한다. 재시도, 타임아웃, 훅, HTTPError 같은 동작은 계속 ky의 것이다. fetcher가 하는 일은 요청이 그 지점에 도달하기 전까지다.
요청 타입을 한 덩어리로 만들지 않는다
초기 구현의 ApiRequestParams에는 매개변수 추출, 요청 본문 추출, 불필요한 키 정리가 한꺼번에 들어 있었다. 현재 소스에서는 이 책임을 파일 단위로 나눴다.
parameters.ts는path,query,header,cookie를 읽고 필수 여부를 계산한다.bodies.ts는 JSON,multipart/form-data,application/x-www-form-urlencoded본문을 구분한다.responses.ts는 연산에서 JSON 응답 타입을 고른다.fetcher.ts는 이 타입들을 공개 호출 시그니처로 조합한다.
공개 요청 타입을 만드는 부분만 보면 이 구분이 더 잘 보인다.
type ShortcutRequest< Paths extends PathsLike, Path extends PathKey<Paths>, Method extends string,> = DistributiveSimplify< MaybeProperty< 'params', ShortcutRequestParams<Path, OperationFor<Paths, Path, Method>>, HasRequiredKeys< ShortcutRequestParams<Path, OperationFor<Paths, Path, Method>> >, HasMeaningfulKeys< ShortcutRequestParams<Path, OperationFor<Paths, Path, Method>> > > & MaybeProperty< 'headers', HeaderParameters<OperationFor<Paths, Path, Method>>, HeaderParametersRequired<OperationFor<Paths, Path, Method>>, HasMeaningfulKeys<HeaderParameters<OperationFor<Paths, Path, Method>>> > & ShortcutRequestPayload<OperationFor<Paths, Path, Method>>>;여전히 짧은 타입은 아니다. 대신 각 조각이 답하는 질문은 분명하다. 이 연산에 의미 있는 매개변수가 있는가, 그중 필수 값이 있는가, 헤더가 존재하는가, 어떤 본문 형식을 허용하는가를 각각 계산한 뒤 마지막에 합친다.
본문 타입도 단순히 body 하나로 뭉개지 않는다. OpenAPI가 JSON만 허용하면 json만 나타나고, 멀티파트 요청이면 formData, URL 인코딩 요청이면 formUrlEncoded가 나타난다. 여러 형식이 선언되어 있더라도 한 호출에서 둘을 동시에 넘길 수 없도록 나머지 키를 never로 만든다.
type ShortcutPayloadMember< Key extends ShortcutBodyKey, Value, IsRequired extends boolean,> = DistributiveSimplify< MaybeProperty<Key, Value, IsRequired, true> & { [K in Exclude<ShortcutBodyKey, Key>]?: never; }>;초기 구현이 “요청에 본문이 있는가”를 물었다면, 지금은 “어떤 미디어 타입의 본문을, 필수로, 다른 본문과 겹치지 않게 받아야 하는가”까지 호출 계약에 옮긴다. 복잡성이 사라진 것은 아니다. 다만 한 타입 안에서 뒤엉키지 않고 각 책임에 이름이 생겼다.
OpenAPI 요청과 ky 옵션을 일부러 분리했다
현재 단축 메서드는 인자를 세 층으로 나눈다.
api.post( '/widgets/{widgetId}', { params: { path: { widgetId: '42' }, query: { draft: true }, }, headers: { 'x-trace': 'typed-trace', }, json: { title: 'typed widget', }, }, { retry: 1, timeout: 5_000, },);첫 번째 인자는 OpenAPI 경로다. 두 번째 인자는 그 경로와 메서드에서 추론한 매개변수, 헤더, 본문이다. 세 번째 인자는 재시도나 타임아웃처럼 전송 자체를 제어하는 ky 옵션이다.
초기 구현의 paramsOrOptions는 두 번째 인자가 요청 매개변수인지 ky 옵션인지 런타임에서 구분해야 했다. 지금의 구조에도 호환성을 위한 판별 코드는 남아 있지만, 타입이 적용되는 정식 호출에서는 두 역할이 시그니처부터 분리된다. 요청 데이터와 전송 정책을 같은 객체에 섞지 않는 셈이다.
이 호출은 곧장 ky로 가지 않는다. 중간에는 두 단계의 정규화가 있다.
OpenAPI 요청 객체 → normalizeGroupedRequestOptions → ky가 이해할 수 있는 RuntimeOptions → prepareKyRequest → 경로가 치환되고 OpenAPI context가 붙은 요청 → KyInstancenormalizeGroupedRequestOptions는 params.query를 searchParams로 옮기고, 요청 헤더와 명시적인 ky 헤더를 합치며, json, formData, formUrlEncoded를 실제 본문 옵션으로 바꾼다. 그다음 prepareKyRequest가 {id} 같은 경로 토큰을 치환하고, path와 cookie처럼 ky가 모르는 내부 필드를 제거한다.
src/internal/runtime.ts 121-155행에서 타입 선언과 문자열이 아닌 입력에 대한 가드를 줄이면 다음 흐름이 남는다.
export const prepareKyRequest = ({ input, method, options }) => { const runtimeOptions: RuntimeOptions = options ? { ...options } : {}; const path = runtimeOptions.path; const interpolatedInput = typeof input === 'string' ? interpolatePathTemplate(input, path) : input; delete runtimeOptions.path; delete runtimeOptions.cookie; runtimeOptions.context = { ...runtimeOptions.context, openapi: { ...readOpenApiContext(runtimeOptions.context), method, ...(typeof input === 'string' ? { pathTemplate: input } : {}), }, }; return { input: interpolatedInput, options: runtimeOptions };};여기서 context.openapi에는 치환 전의 경로 템플릿과 메서드가 들어간다. 실제 요청 URL은 /users/42가 되더라도 훅에서는 /users/{id}와 get을 읽을 수 있다. 로깅이나 관측 도구가 요청마다 달라지는 실제 URL 대신 같은 OpenAPI 연산을 기준으로 묶을 수 있는 정보다.
한계도 있다. cookie 매개변수는 현재 타입 검사에만 쓰이고 실제 Cookie 헤더로 직렬화되지 않는다. 브라우저와 서버의 쿠키 정책은 단순한 객체 변환으로 대신하기 어렵기 때문에, 인증과 쿠키 전달은 여전히 ky 인스턴스의 설정이나 애플리케이션이 책임진다.
/api를 지우는 규칙도 패키지 밖으로 밀어냈다
초기 구현의 PathWithoutApi는 애플리케이션의 OpenAPI 경로에서 /api를 지웠다가, 타입을 조회할 때 다시 붙였다. 한 프로젝트 안에서는 괜찮았지만 독립 패키지의 규칙으로 삼기에는 지나치게 구체적이었다. 모든 API가 /api를 접두사로 쓰는 것도 아니고, 어떤 스키마는 이미 호스트 기준의 상대 경로만 담고 있기 때문이다.
현재 패키지는 /api라는 문자열을 모른다. 호출 경로는 Paths의 키를 그대로 사용하고, 기준 URL은 ky의 prefixUrl에 맡긴다. 다만 ky는 prefixUrl을 사용할 때 입력이 /로 시작하면 오류를 던지는데, OpenAPI 경로는 보통 /users/{id}처럼 시작한다. 이 충돌만 아주 좁게 보정한다.
src/core/createFetcher.ts 16-30행에서 타입 선언만 줄인 모습은 다음과 같다.
const executeKyCall = <Result>(input, options, runner): Result => { try { return runner(input, options); } catch (error) { if ( isKyPrefixUrlLeadingSlashError(error) && typeof input === 'string' && input.startsWith('/') ) { return runner(stripLeadingSlash(input), options); } throw error; }};아무 오류나 잡아서 경로를 고치는 것은 아니다. prefixUrl과 선행 슬래시 때문에 ky가 동기적으로 던진 오류이면서 입력이 /로 시작하는 문자열일 때만, 슬래시 하나를 제거해 다시 호출한다. URL이나 Request 객체, 관련 없는 예외에는 이 재시도를 적용하지 않는다. 절대 URL 문자열도 별도로 보정하지 않고 ky의 prefixUrl 규칙을 그대로 따른다.
이 방식은 /api를 자동으로 제거해 주지 않는다. OpenAPI의 경로와 prefixUrl이 어떻게 나뉘는지는 사용하는 애플리케이션이 맞춰야 한다. 대신 패키지는 특정 프로젝트의 접두사 규칙을 타입 전체에 새기지 않고, OpenAPI 경로와 ky의 URL 규칙이 실제로 충돌하는 경계만 처리한다.
응답을 미리 열지 않고 ResponsePromise를 돌려준다
초기 Fetcher는 모든 성공 응답에 곧바로 response.json()을 호출했다. 그 덕분에 호출 결과의 타입은 단순했지만, 응답 헤더나 상태 코드를 먼저 보거나 text(), blob(), formData()로 읽는 ky의 사용감은 사라졌다. 본문이 없는 응답에 JSON 파싱을 시도하는 문제도 런타임 구현이 떠안았다.
현재 단축 메서드는 Promise<ApiResponse<...>>가 아니라 ResponsePromise<InferJson<...>>를 반환한다.
type TypedShortcutMethod< Paths extends PathsLike, Method extends ShortcutMethod,> = { <Path extends PathKeysWithMethod<Paths, Method>>( ...args: TypedShortcutArguments<Paths, Path, Method> ): ResponsePromise<InferJson<Paths, Path, Method>>;};그래서 호출자는 응답을 언제, 어떤 형식으로 읽을지 직접 정한다.
const response = await api.get('/users/{id}', { params: { path: { id: '42' }, },});response.status;response.headers.get('etag');const user = await response.json();json()의 반환 타입은 선택한 경로와 메서드에서 추론되지만, 모든 성공 응답을 합치는 구조는 아니다. 현재 InferJson은 200, 201, 204, default 순서로 처음 찾은 JSON 응답을 사용하고, 해당 응답이 없으면 unknown이 된다. 실제 응답은 여전히 ky의 ResponsePromise다. 타입 추론을 얻기 위해 HTTP 클라이언트의 응답 모델을 포기하지 않아도 된다. 지금 구현에서 가장 마음에 드는 경계가 있다면 아마 이 부분일 것이다. OpenAPI는 .json()이 무엇을 돌려주는지 알고, 응답을 언제 어떤 형식으로 소비할지는 호출자가 결정한다.
예외를 값으로 받고 싶을 때만 safe를 고른다
실패 처리도 같은 원칙을 따른다. 기본 호출은 ky처럼 HTTP 실패에 HTTPError를 던진다. 패키지가 모든 호출을 임의의 결과 객체로 바꾸지 않는다. 대신 예외를 던지지 않는 흐름이 필요한 곳에서는 safe를 명시적으로 선택할 수 있다.
const result = await api.safe.get('/users/{id}', { params: { path: { id: '42' }, },});if (result.ok) { result.data; result.response;} else { result.error; result.response;}safe는 성공 응답의 JSON을 미리 읽어 { ok: true, data, response }를 돌려주고, 요청 준비 오류나 네트워크 오류, HTTPError, JSON 파싱 오류는 { ok: false, error, response }로 바꾼다. 응답을 받기 전에 실패했다면 response는 null이고, HTTP 응답이나 파싱할 응답이 있었다면 그 객체를 보존한다.
중요한 점은 이 동작이 기본 호출의 의미를 바꾸지 않는다는 것이다. 지연 파싱과 예외를 원하는 코드는 api.get()을 쓰고, 파싱된 데이터와 구별 가능한 실패 값을 원하는 경계만 api.safe.get()을 쓴다. 하나의 오류 처리 방식을 모든 사용처에 강요하지 않는다.
create와 extend도 다시 같은 호출 API를 얻는다
실제 KyInstance를 감싼다고 해도 api.extend()를 호출한 순간 타입이 사라진다면 그다지 쓸 만하지 않다. 그래서 현재 구현은 ky가 새 인스턴스를 만들 때마다 그 결과를 다시 decorateKyInstance에 통과시킨다.
fetcher.create = ((defaultOptions?: Options) => { return decorateKyInstance<Paths>(instance.create(defaultOptions));}) as Fetcher<Paths>['create'];fetcher.extend = ((defaultOptions) => { return decorateKyInstance<Paths>(instance.extend(defaultOptions));}) as Fetcher<Paths>['extend'];이 덕분에 공통 헤더를 추가한 인스턴스도, 별도의 기준 URL을 가진 인스턴스도 같은 Fetcher<Paths> 계약과 safe를 유지한다.
const adminApi = api.extend({ headers: { 'x-admin': '1', },});const user = await adminApi .get('/users/{id}', { params: { path: { id: '42' }, }, }) .json();초기 구현에서는 서버와 브라우저용 Fetcher를 클래스 안에서 나눴다. 지금은 애플리케이션이 ky.create()와 extend()로 필요한 인스턴스를 조합하고, fetcher는 어떤 인스턴스에서도 같은 OpenAPI 계약을 다시 올린다. 환경 차이를 패키지의 클래스 계층이 아니라 조합 가능한 HTTP 클라이언트 설정으로 다루는 쪽에 가깝다.
스펙 바깥의 경로도 두 가지 방식으로 남겨 둔다
OpenAPI가 항상 애플리케이션의 모든 호출을 설명하는 것은 아니다. 아직 스펙에 들어가지 않은 엔드포인트를 잠깐 호출해야 할 수도 있고, 프론트엔드 전용 BFF 경로처럼 생성된 스키마 밖에서 관리할 계약도 있다.
현재 Fetcher는 모르는 문자열 경로를 완전히 막지 않는다. 그런 호출은 ky 옵션을 받을 수 있지만 JSON 응답 타입은 unknown으로 돌아간다. 초기 구현의 탈출구를 그대로 남기되, 타입이 없는 호출이라는 사실을 숨기지 않는 방식이다.
반면 스키마 밖의 경로가 계속 사용될 계약이라면 MergePaths로 생성 타입과 애플리케이션 타입을 합칠 수 있다.
type ApiPaths = MergePaths<GeneratedPaths, ExtraPaths>;const api = createFetcher<ApiPaths>({ prefixUrl: '/api',});src/openapi/shared.ts 52-69행의 MergePaths는 양쪽의 경로와 메서드를 합친다. 같은 경로에 서로 다른 메서드가 있으면 둘 다 보존하고, 같은 경로의 같은 메서드가 겹치면 ExtraPaths의 연산이 우선한다.
따라서 선택 기준도 비교적 분명하다. 정말 임시인 호출은 unknown을 감수하고 탈출구를 쓰고, 애플리케이션이 계속 책임질 계약이라면 Paths에 합쳐 호출 API의 일부로 만든다. 스펙에 없다는 이유만으로 무조건 타입 안전성을 포기할 필요는 없다.
타입을 얹는 것보다는 책임을 덜어 내는 쪽으로
유저랜드 구현과 패키지의 구현은 모두 동일한 질문에서 출발한다. 경로와 메서드로 OpenAPI 연산을 찾고, 그 연산에서 요청과 응답을 추론해 호출 API로 만든다. 유저랜드에서 만든 타입들이 틀렸던 것은 아니다. 오히려 그 타입들이 있었기 때문에 어떤 호출 경험을 원하는지 알 수 있었다.
달라진 것은 런타임의 책임이다. 유저랜드의 Fetcher는 ky를 사용하면서도 별도의 클라이언트처럼 행동했다. 패키지의 fetcher는 OpenAPI 요청을 정규화한 뒤 실제 KyInstance에 넘기고, 응답도 ResponsePromise 그대로 돌려준다. 필요한 경우에만 safe로 파싱과 오류 모델을 바꾸며, create와 extend로 파생된 인스턴스도 같은 호출 API로 다시 꾸민다.
paths → 경로와 메서드로 연산 선택 → 요청 계약과 응답 타입 추론 → 요청 객체를 ky 옵션으로 정규화 → 실제 KyInstance에 위임 → 타입이 연결된 ResponsePromise현재 구현이 예전보다 나아진 이유는 조건부 타입이 사라졌기 때문이 아니다. 오히려 지원하는 요청 형식과 호출 방식이 늘면서 타입은 더 많아졌다. 대신 타입은 타입의 책임 안에서 나뉘고, 런타임은 ky가 이미 잘하는 일을 다시 흉내 내지 않는다.
돌아보면 초기 구현에서 가장 복잡했던 것은 타입 자체가 아니라, Fetcher가 너무 많은 것을 알고 있었다는 점이다. OpenAPI에서 호출 계약을 꺼내는 일과 URL을 만들고 요청을 보내고 응답을 파싱하는 일이 한곳에 모여 있었다. 지금은 fetcher가 경로와 메서드에서 요청과 응답의 계약을 만들고, 그 입력을 ky가 이해할 수 있는 모양으로 바꾸는 데까지만 관여한다.
실제 요청을 실행하고 응답을 다루는 일은 다시 ky의 몫이다. 결국 구현을 예쁘게 만든 것은 조건부 타입을 더 영리하게 쓴 일이 아니라, 각 결정을 가장 잘 아는 쪽으로 돌려보낸 일이었다. 처음의 빈 객체는 꽤 수상했지만, 지금의 fetcher에는 적어도 설명하기 어려운 책임이 남아 있지 않다.
댓글
댓글을 불러오는 중...