hydration

`dehydrate`

dehydrate는 cache의 읽기 전용 hydrate 데이터를 생성하여, 나중에 HydrationBoundary나 hydrate로 dehydrate할 수 있습니다. 이는 서버에서 클라이언트로 미리 가져온 쿼리를 전달하거나, 쿼리를 localStorage나 다른 지속적인 위치에 저장하는 데 유용합니다. 기본적으로 성공적으로 데이터를 가져온 쿼리만 포함됩니다.

import { dehydrate } from "@tanstack/react-query";
 
const dehydratedState = dehydrate(queryClient, {
  shouldDehydrateQuery,
  shouldDehydrateMutation,
});

옵션

client: QueryClient
- Required
- dehydrate할 queryClient
options: DehydrateOptions
- Optional
- shouldDehydrateMutation: (mutation: Mutation) => boolean
  - Optional
  - mutation을 dehydrate할지 여부입니다.
  - 캐시의 각 mutation에 대해 호출됩니다.
    - 이 mutation을 포함하려면 true를 반환하고, 그렇지 않으면 false를 반환합니다.
  - 기본적으로 일시 중지된 mutation만 포함됩니다.
  - 기본 동작을 유지하면서 이 함수를 확장하려면 defaultShouldDehydrateMutation을 가져와서 반환문에서 실행하면 됩니다.
- shouldDehydrateQuery: (query: Query) => boolean
  - Optional
  - 쿼리를 dehydrate할지 여부입니다.
  - 캐시의 각 쿼리에 대해 호출됩니다.
    - 이 쿼리를 포함하려면 true를 반환하고, 그렇지 않으면 false를 반환합니다.
  - 기본적으로 성공적으로 데이터를 가져온 쿼리만 포함됩니다.
  - 기본 동작을 유지하면서 이 함수를 확장하려면 defaultShouldDehydrateQuery를 가져와서 반환문에서 실행하면 됩니다.
- serializeData?: (data: any) => any
  - 데이터를 dehydrate하는 동안 변환(hydrate)할 함수입니다.

반환값

dehydratedState: DehydratedState
- 나중에 queryClient를 dehydrate하는 데 필요한 모든 것을 포함합니다.
- 이 응답의 형식에 의존해서는 안 되며, 공식 API의 일부가 아니므로 언제든지 변경될 수 있습니다.
- 이 결과는 hydrate된 형태가 아니므로, 필요에 따라 직접 hydrate해야 합니다.

Limitations

일부 저장 시스템(예: 브라우저 Web Storage API (opens in a new tab))은 JSON으로 hydrate할 수 있는 값이어야 합니다. JSON으로 자동 hydrate되지 않는 값(예: Error나 undefined)을 dehydrate해야 하는 경우, 직접 hydrate해야 합니다. 기본적으로 성공적으로 데이터를 가져온 쿼리만 포함되므로 Errors도 포함하려면 shouldDehydrateQuery를 제공해야 합니다. 예를 들면:

// 서버
const state = dehydrate(client, { shouldDehydrateQuery: () => true }); // Errors도 포함
const serializedState = mySerialize(state); // Error 인스턴스를 객체로 변환
 
// 클라이언트
const state = myDeserialize(serializedState); // 객체를 Error 인스턴스로 변환
hydrate(client, state);

`hydrate`

hydrate는 이전에 dehydrate된 상태를 cache에 추가합니다.

import { hydrate } from "@tanstack/react-query";
 
hydrate(queryClient, dehydratedState, options);

옵션

client: QueryClient
- Requied
- 상태를 hydrate할 queryClient
dehydratedState: DehydratedState
- Requied
- 클라이언트에 hydrate할 상태
options: HydrateOptions
- Optional
- defaultOptions: DefaultOptions
  - Optional
  - mutations: MutationOptions
    - 복원된 mutations에 사용할 기본 mutation 옵션
  - queries: QueryOptions
    - 복원된 쿼리에 사용할 기본 쿼리 옵션
  - deserializeData?: (data: any) => any
    - 캐시에 넣기 전에 데이터를 변환(dehydrate)할 함수입니다.
- queryClient?: QueryClient
  - 커스텀 QueryClient를 사용하려면 이 옵션을 사용합니다. 그렇지 않으면 가장 가까운 컨텍스트의 QueryClient가 사용됩니다.

Limitations

hydrate를 시도하는 쿼리가 이미 queryCache에 존재하는 경우, hydrate는 캐시의 데이터보다 최신 데이터일 때만 쿼리를 덮어씁니다. 그렇지 않으면 적용되지 않습니다.

`HydrationBoundary`

HydrationBoundary는 useQueryClient()로 반환되는 queryClient에 이전에 dehydrate된 상태를 추가합니다. 클라이언트에 이미 데이터가 있는 경우, 새로운 쿼리는 업데이트 타임스탬프를 기준으로 병합됩니다.

import { HydrationBoundary } from "@tanstack/react-query";
 
function App() {
  return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>;
}

참고: HydrationBoundary로는 오직 queries만 dehydrate할 수 있습니다.

옵션

state: DehydratedState
- dehydrate할 상태
options: HydrateOptions
- Optional
- defaultOptions: QueryOptions
  - 복원된 쿼리에 사용할 기본 쿼리 옵션
- queryClient?: QueryClient
  - 커스텀 QueryClient를 사용하려면 이 옵션을 사용합니다. 그렇지 않으면 가장 가까운 컨텍스트의 QueryClient가 사용됩니다.

Changed History

2024.10.02. @ubinquitous

[구문] 동결된 표현을 생성하여 → 읽기 전용 hydrate 데이터를 생성하여
[구문] 복원할 수 있습니다 → dehydrate할 수 있습니다
[구문] 현재 성공적인 쿼리만 포함됩니다 → 성공적으로 데이터를 가져온 쿼리만 포함됩니다.

useQueryErrorResetBoundary ESlint Plugin Query