[React Query 공식문서] ReactQuery TypeScript

React Query는 이제 TypeScript로 작성되어, 라이브러리와 프로젝트가 타입 안전성을 보장합니다!

유의사항

• 현재 타입은 TypeScript v4.7 이상을 요구합니다.
• 이 저장소의 타입 변경은 비파괴적(non-breaking)으로 간주되며,
  일반적으로 패치 세멘틱 버전 변경으로 릴리스됩니다(모든 타입 개선이 주요 버전이 되지 않도록 하기 위함).
• react-query 패키지 버전을 특정 패치 릴리스로 고정하고,
  릴리스 간에 타입이 수정되거나 업그레이드될 수 있다는 기대를 가지고 업그레이드하는 것이 강력히 권장됩니다.
• React Query의 비타입 관련 공개 API는 여전히 시멘틱 버전 관리를 매우 엄격하게 따릅니다.

 

타입 추론

React Query의 타입은 일반적으로 잘 흐르기 때문에, 사용자가 직접 타입 주석을 제공할 필요가 없습니다.

이것은 queryFn이 잘 정의된 반환 타입을 가질 때 가장 잘 작동합니다.

대부분의 데이터 페칭 라이브러리는 기본적으로 any를 반환하므로, 이를 적절한 타입의 함수로 추출하는 것이 중요합니다.

타입 좁히기

React Query는 쿼리 결과에 대해 상태 필드와 파생된 상태 불리언 플래그로 구분된 유니온 타입을 사용합니다.

이를 통해 성공 상태를 확인하여 데이터를 정의할 수 있습니다.

에러 필드 타입 지정

에러의 기본 타입은 Error로 설정되어 있습니다. 이는 대부분의 사용자가 기대하는 것입니다.

사용자가 커스텀 에러를 던지거나, 에러가 아닌 다른 것을 던지고 싶다면, 에러 필드의 타입을 지정할 수 있습니다.

하지만 이 경우, useQuery의 다른 제네릭에 대한 타입 추론이 더 이상 작동하지 않는 단점이 있습니다.

에러가 아닌 것을 던지는 것은 일반적으로 좋은 관행으로 간주되지 않으므로,

AxiosError와 같은 서브클래스를 사용하는 경우 타입 좁히기를 통해 에러 필드를 더 구체적으로 만들 수 있습니다.

전역 에러 등록

TanStack Query v5는 호출 측에서 제네릭을 지정하지 않고도

모든 것에 대한 전역 에러 타입을 설정할 수 있는 방법을 제공합니다.

이를 통해 추론이 여전히 작동하지만, 에러 필드는 지정된 타입이 됩니다.

전역 메타 등록

전역 에러 타입을 등록하는 것과 유사하게, 전역 메타 타입을 등록할 수도 있습니다.

이를 통해 쿼리와 변이의 선택적 메타 필드가 일관성을 유지하고 타입 안전성을 보장합니다.

등록된 타입은 메타가 객체로 남아 있도록 Record<string, unknown>을 확장해야 합니다.

쿼리 옵션 타입 지정

쿼리 옵션을 useQuery에 인라인으로 작성하면 자동 타입 추론이 가능합니다.

그러나 쿼리 옵션을 별도의 함수로 추출하여 useQuery와 prefetchQuery 간에 공유하고 싶을 경우, 타입 추론이 사라집니다.

이를 되찾기 위해 queryOptions 헬퍼를 사용할 수 있습니다.

또한, queryOptions에서 반환된 queryKey는 관련된 queryFn에 대한 정보를 알고 있으며,

이 타입 정보를 활용하여 queryClient.getQueryData와 같은 함수가 이러한 타입을 인식하도록 만들 수 있습니다.

queryOptions 없이, data의 타입은 알 수 없으며, 제네릭을 전달하지 않는 한 unknown이 됩니다.

 

쿼리 비활성화의 타입 안전한 방법

TypeScript를 사용하는 경우, 조건에 따라 쿼리를 비활성화할 때 skipToken을 사용할 수 있습니다.

이는 쿼리를 비활성화하면서도 타입 안전성을 유지하고 싶을 때 유용합니다.