콘텐츠로 이동
Fuery

뮤테이션 옵션

Mutation과 NoVariablesMutation의 모든 옵션과 타입, 기본값, 뮤테이션을 실행하는 메서드, 그리고 MutateOptions와 MutationPersist예요. 모든 뮤테이션이나 한 키 아래의 뮤테이션에 gcTime(가비지 컬렉션 시간), retry, retryDelay, networkMode, meta를 설정하려면 MutationDefaults(기본값)를 사용하세요. 옵션을 사용하는 예는 뮤테이션에 있어요.

옵션

섹션 제목: “옵션”
옵션 타입 기본값 하는 일
mutationFn Future<TData> Function(TVariables variables) 필수 바꿀 내용을 서버에 보내요. 매개변수 타입이 TVariables가 되고, 반환 타입이 TData가 돼요.
mutationKey List<Object?> 없음 실행(mutate 호출 한 번)을 구분해요. MutationState 위젯, useMutationState, MutationFilters, restore는 이 키로 실행을 찾아요. setMutationDefaults는 자신이 받은 키로 mutationKey가 시작하는 뮤테이션에 모두 기본값을 적용해요.
gcTime Duration 5분 실행이 끝나고 따라가는 옵저버가 없을 때, 실행이 뮤테이션 캐시에 남는 시간이에요. infiniteDuration이면 clear()까지 남아요.
retry RetryPolicy RetryPolicy.never() 실패한 시도를 얼마나 재시도할지 정해요. .count(n), .always(), .when((count, error) => ...) 중 하나예요.
retryDelay Duration Function(int failureCount, Object error) 1초, 2초, 4초, … 최대 30초 재시도하기 전에 기다리는 시간
networkMode NetworkMode NetworkMode.online online은 시도할 때마다 먼저 네트워크를 기다려요. always는 네트워크를 무시해요. offlineFirst는 첫 시도는 실행하고, 재시도 전에는 네트워크를 기다려요.
scope MutationScope 없음 스코프의 id가 같은 실행은 시작한 순서대로 하나씩 실행돼요. 차례를 기다리는 동안 실행의 isPaused는 true예요.
persist MutationPersist<TVariables> 없음 실행이 pending 상태인 동안 변수를 기기에 저장해요. 그래서 앱을 다시 시작한 뒤 restore(mutations:)가 그 실행을 다시 시작해요. mutationKey와 storage가 있는 클라이언트가 필요해요. mutationKey는 assert로 확인해요. MutationPersist를 참고하세요.
meta Map<String, Object?> 없음 아무 값이나 담아요. MutationCacheConfig 콜백과 MutationFilters.predicate는 이 값을 mutation.options.meta로 읽어요.
onMutate 콜백 참고 없음 mutationFn보다 먼저 실행돼요. 반환값이 TContext를 정하고 context가 돼요.
onSuccess 콜백 참고 없음 mutationFn이 성공한 뒤 실행돼요.
onError 콜백 참고 없음 마지막 시도가 실패한 뒤 실행돼요.
onSettled 콜백 참고 없음 성공이나 실패 뒤에 실행돼요.

뮤테이션 실행하기

섹션 제목: “뮤테이션 실행하기”

정의는 이 메서드로 뮤테이션을 직접 실행해요. client는 생략할 수 있고, 생략하면 호출하는 시점의 Fuery.client를 사용해요.

메서드 반환 타입 하는 일
mutate(variables, [client]) void 실행을 시작하고 기다리지 않아요. 에러는 호출한 쪽이 아니라 실행의 상태와 콜백으로 전달돼요.
mutateAsync(variables, [client]) Future<TData> 실행을 시작하고 그 데이터를 반환해요. 실행이 실패하면 에러가 발생해요.
observe({client}) MutationObserver<TData, TVariables, TContext> 뮤테이션을 실행하고 가장 최근 실행을 알리는 새 옵저버를 반환해요. 옵저버 하나 공유하기를 참고하세요.
  • 정의는 상태를 담지 않아요. mutate나 mutateAsync로 시작한 실행은 클라이언트의 뮤테이션 캐시에 속하고, 어떤 옵저버도 그 실행을 담지 않아요. 실행은 끝나고 gcTime이 지나면 캐시에서 사라져요.
  • MutationState 위젯, useMutationState, isMutating은 mutationKey로 그 실행을 찾아요. MutationResult에는 나타나지 않아요.
  • 이 실행도 옵저버에서 시작한 실행처럼 클라이언트의 기본값, scope, persist를 받아요.
  • 두 메서드 모두 MutateOptions를 받지 않아요. 호출 한 번에만 필요한 처리는 mutateAsync를 await로 기다린 뒤에 하세요.
  • 클라이언트를 따로 둔 FueryProvider 아래에서는 context.queryClient를 넘기세요.

콜백

섹션 제목: “콜백”
콜백 인수 반환 타입
onMutate TVariables variables, QueryClient client FutureOr<TContext?>. 반환값이 context가 돼요.
onSuccess TData data, TVariables variables, TContext? context, QueryClient client FutureOr<void>
onError Object error, TVariables variables, TContext? context, QueryClient client FutureOr<void>
onSettled TData? data, Object? error, TVariables variables, TContext? context, QueryClient client FutureOr<void>

client는 뮤테이션을 실행하는 클라이언트예요. Fuery는 콜백을 이 순서로 실행해요.

  1. 클라이언트의 MutationCacheConfig에 있는 콜백(캐시 콜백)
  2. 뮤테이션 자체의 콜백
  3. 두 onSettled 콜백이 끝나면 실행의 상태가 success나 error로 바뀌어요. 그다음 그 호출의 MutateOptions 콜백이 실행되고, 그 뒤에 위젯이 새 상태를 받아요.
  • 1단계와 2단계에서 Future를 반환하면 Fuery가 await로 기다려요. 그래서 Future가 완료될 때까지 실행은 pending 상태로 남아요.
  • onMutate에서, 또는 성공한 뒤 onSuccess나 onSettled에서 에러가 발생하면 실행이 실패하고 그 에러가 onError로 전달돼요.
  • 실패한 실행의 onError나 onSettled에서 발생한 에러는 onUncaughtError로 전달돼요.
  • restore(mutations:)로 복원한 실행은 onMutate를 건너뛰고, 콜백은 context로 null을 받아요.
  • clear()가 멈춘 실행을 버리면 그 실행은 CancelledError로 실패해요. onMutate 뒤의 콜백은 하나도 실행되지 않고, 그 호출의 MutateOptions 콜백도 실행되지 않아요.

NoVariablesMutation

섹션 제목: “NoVariablesMutation”

NoVariablesMutation<TData, TContext>는 Mutation과 같은 옵션을 받아요. 다만 mutationFn과 콜백에는 변수가 없어요.

옵션 인수 반환 타입
mutationFn 없음 Future<TData>
onMutate QueryClient client FutureOr<TContext?>
onSuccess TData data, TContext? context, QueryClient client FutureOr<void>
onError Object error, TContext? context, QueryClient client FutureOr<void>
onSettled TData? data, Object? error, TContext? context, QueryClient client FutureOr<void>

정의는 mutate()와 mutateAsync()로 뮤테이션을 실행해요. 클라이언트를 넘기려면 첫 인수로 null을 넘기세요. mutate(null, client)처럼 호출해요.

NoVariablesMutation은 Mutation<TData, void, TContext>예요. 그래서 이렇게 동작해요.

  • 위젯과 훅은 mutate(null)이나 mutateAsync(null)로 실행해요.
  • MutateOptions 콜백에는 변수 인수가 그대로 있고, 그 값은 null이에요.
  • observe()는 NoVariablesMutationObserver를 반환하고, 이 옵저버는 mutate()와 mutateAsync()로 뮤테이션을 실행해요. MutateOptions를 넘기려면 첫 인수로 null을 넘기세요. mutate(null, options)처럼 호출해요.

저장하려면 MutationPersist.noVariables를 넘기세요.

MutateOptions

섹션 제목: “MutateOptions”

MutateOptions는 호출 한 번의 콜백을 담아요. 결과나 옵저버의 mutate, mutateAsync에 두 번째 인수로 넘겨요. 정의의 mutate는 MutateOptions를 받지 않아요.

필드 인수 실행 시점
onSuccess TData data, TVariables variables, TContext? context, QueryClient client 호출이 성공한 뒤
onError Object error, TVariables variables, TContext? context, QueryClient client 호출이 실패한 뒤
onSettled TData? data, Object? error, TVariables variables, TContext? context, QueryClient client 성공이나 실패 뒤
  • 실행이 끝나면 뮤테이션 자체의 콜백 뒤에 실행돼요. Fuery는 이 콜백을 기다리지 않아요.
  • 같은 옵저버에서 다시 호출하면 콜백이 바뀌어요. 그래서 가장 최근 호출의 콜백만 실행돼요.
  • reset()을 호출하면 콜백을 버려요. 옵저버를 소유한 위젯이 언마운트되거나, 훅이나 슬롯이 해제될 때도 버려요.
  • 공유하는 옵저버는 구독하는 것이 있든 없든 이 콜백을 실행해요. 콜백에서 BuildContext를 사용하기 전에 context.mounted를 확인하세요.
  • 이 콜백에서 발생한 에러는 onUncaughtError로 전달돼요.

MutationPersist

섹션 제목: “MutationPersist”

MutationPersist<TVariables>는 뮤테이션의 변수를 JSON으로 바꾸고 다시 되돌려요. 그래서 앱을 다시 시작한 뒤 restore(mutations:)가 저장된 실행을 다시 시작할 수 있어요. 설정 방법은 뮤테이션 저장하기에 있어요.

매개변수 타입 기본값 하는 일
toJson Object? Function(TVariables variables) 필수 변수를 jsonEncode가 받을 수 있는 값으로 바꿔요. 인코딩할 수 없는 변수는 저장하지 않고, 실행은 계속돼요.
fromJson TVariables Function(Object? json) 필수 jsonDecode가 만든 값을 다시 변수로 바꿔요.
version int 1 버전이 다른 저장된 실행은 Fuery가 실행하지 않고 삭제해요. JSON 형식이 바뀌면 값을 올리세요.

MutationPersist.noVariables는 저장할 변수가 없는 NoVariablesMutation용 MutationPersist<void>예요.