useMutationState 사용법

React Query의 uesMutation을 쓸 때 마다 key는 왜 제공되는거지? 의문이었는데 최근에 그 이유를 찾았다. 제목처럼 useMutationState 에서 사용하는데, 이 함수를 사용해서 전역에서 내가 원하는 mutation의 상태를 조회할 수 있다.

useMutationState란?

공식 문서에 따르면 v5 버전부터 제공하고 MutationCache의 Mutation에 접근할 수 있는 Hook이라고 한다. 원하는 Mutation에 접근할 수 있도록 필터링을 제공한다.

그렇다면 MutationCache는 무엇이고 useMutation은 왜 MutationCache에 있는것일까?

MutationCache란?

실행된 mutation 인스턴스를 보관한다. QueryClient 객체 생성시 같이 생성된다. mutation의 default 설정을 지정할 수 있다.
useMutation이 반환하는 객체는 mutation을 실행하긴하지만 상태의 주체는 MutationCache이다. 실제 실행은 MutationCache가 보관중인 Mutation 인스턴스이다. useMutation이 반환한 객체는 그저 그 상태를 구독하는 Observer일 뿐이다.

정리하자면, useMutation이 반환한 객체를 통해 mutate() 또는 mutationAsync()로 실행을 하면 MutationCache에 새로운 Mutation 인스턴스가 생성되고 useMutationCache로 조회를 할 수 있게된다.

실행된 mutation은 useMutation 정의 시 지정한 gcTime(구 버전에서는 cacheTime) 후에 제거된다.

useMutationState 사용 예시

// createUserMutation.ts
return useMutation({
    mutationKey: ['createUser'],
    mutationFn: async (newUser) => {
      //...
    },
  	gcTime : 5000, // mutation 실행이 완료되어 결과가 반환된 시점부터 5초 후 MutationCache에서 제거
  });

// PendingUserList.tsx
function PendingUserList() {
  // MutationCache에서 'createUser' 키를 가진 pending 상태의 mutation 상태 가져오기
  const pendingUserNames = useMutationState({
    filters: { mutationKey: ['createUser'], status: 'pending' },
    select: (mutation) => mutation.state.variables.name,
  });

  if (pendingUserNames.length === 0) return null;

  return (
    <div className="status-panel">
      <h4>유저 생성 중...</h4>
      <ul>
        {pendingUserNames.map((name, index) => (
          <li key={index}>{name} 님의 정보를 등록하고 있습니다.</li>
        ))}
      </ul>
    </div>
  );
}