Allow custom functions for mutation

[ziimakc]

Maybe we can have useLazyMutation similar to react-query.

function AddTodo() {
	const [addTodo, { data, loading, error }] = useMutation(ADD_TODO);

	return (
		<div>
			<form
				onSubmit={(e) => {
					e.preventDefault();

					// this is a problem because
					// button is not disabled because `useMutation loading` is not part of this function
					// error thrown will not end up in `useMutation error` so you need to handle it separately
					const formData = new FormData(e.target as HTMLFormElement);
					if (formData.title.length < 10) {
						throw new Error("invalid input");
					}

					addTodo({ variables: { type: formData.title } });

					// would be nice to do something like this instead, similart to react query
					addTodo((mutationFn) => {
						const formData = new FormData(
							e.target as HTMLFormElement,
						);
						if (formData.title.length < 10) {
							throw new Error("invalid input");
						}

						return mutationFn({
							variables: {
								type: formData.title,
							},
						});
					});
				}}
			>
				<input name="title" />
				<button type="submit" disabled={loading}>
					Add Todo
				</button>
			</form>
		</div>
	);
}

[jerelmiller]

Hey @ziimakc 👋

Can you point me to the documentation in React Query with the functionality that you're referring to? I found the useMutation API documentation, but the function signature on that page only suggests that mutate takes a variables argument, not a callback function:

mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => void

button is not disabled because useMutation loading is not part of this function

Would you mind explaining this comment a bit more as well? If the work you're doing to create variables is synchronous, wouldn't the callback approach have the same timing as just calling addTodo({ variables })?

Any additional information you can provide would be super helpful. Thanks!

[ziimakc]

@jerelmiller this is example of react-query user registration component, everything is perfect:

User clicks on a submit button, Button get immediately disabled, 2 gql operations happen inside userRegisterFn. In case of validation issues operation can be stopped early with custom error handling. Doing the same is not nice with appollo.

export default function RouteComponent() {
  const globalContext = useContext(ActiveUserContext);
  const navigate = useNavigate();

  const userRegister = useMutation({
    mutationFn: userRegisterFn,
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();

        userRegister.mutate({
          formData: new FormData(e.target as HTMLFormElement),
          navigate,
          refetchActiveUser: globalContext.refetchActiveUser,
        });
      }}
    >
      <Button type="submit" disabled={userRegister.isPending}>
        Register
      </Button>
    </form>
  );
}

async function userRegisterFn({
  formData,
  navigate,
  refetchActiveUser,
}: {
  formData: FormData;
  navigate: NavigateFunction;
  refetchActiveUser: ActiveUserContextData["refetchActiveUser"];
}): Promise<void> {
  const email = formData.get("email") as string;
  const password = formData.get("password") as string;
  const passwordRepeat = formData.get("password-repeat") as string;
  const nickname = formData.get("nickname") as string;
  if (password !== passwordRepeat) {
    const err = PublicFeErr.badRequest("wrong password");
    toast.error(err.message);
    return;
  }

  const registerRes = await UserRegisterCommand.executeClient({
    email,
    password,
    nickname,
  });

  if (registerRes.error) {
    toast.error(registerRes.error.message);
    return;
  }

  // executes gql operation using apollo client
  const loginRes = await LoginCommand.executeClient({ email, password });

  if (loginRes.error) {
    toast.error(loginRes.error.message);
    return;
  }

  await refetchActiveUser();
  await navigate(
    href("/user/:userId/:userSlug?", {
      userId: registerRes.data.id,
      userSlug: registerRes.data.slug,
    })
  );
}

I use apollo because normalized cache is just too good to not have it and it decreases amount of requests, but working with mutation is much easier using react-query as a wrapper.

[jerelmiller]

Appreciate the code snippet. This helps a lot!

If I were to distill this request down, is this strictly about validating variables and allowing that validation to throw errors which could end up on the error property returned from useMutation/call onError?

---

FYI I can't guarantee we'll be able to implement anything like this for 4.0 itself as it is already quite full with changes and we are trying to limit new features (new 4.0 issues we add are generally ones with breaking changes that we've discovered while implementing other breaking changes).

That said, 2 bits of good news. Assuming my interpretation of this is correct, I believe this could be done as a feature without the need to introduce a breaking change. This makes it less essential that this would need to be part of 4.0 or wait until 5.0. The other good news here is that 4.0 does a lot of work around error handling where error is now a generic error instead of ApolloError, which makes introducing new types of errors (such as validation errors or custom error types) much easier to do.

Thanks again for the context! Please let me know if I'm misinterpreting the basis for the request 🙂

[ziimakc]

If I were to distill this request down, is this strictly about validating variables and allowing that validation to throw errors which could end up on the error property returned from useMutation?

No, I would say it's more about allowing to do before and after async actions, for example:

• before: form validation, toasts on errors, prefetch some additional data for operation
• after(on success): navigate user to another route on success, refetch global user on login.

And making this action a part of lifecycle.

[jerelmiller]

after(on success): navigate user to another route on success, refetch global user on login.

This should currently be possible today by awaiting the mutation:

const [mutate] = useMutation()

await mutate({ variables });
// or mutate.then(() => navigate('/go/to/page')) if you prefer .then

navigate('/go/to/page')

or by using the onCompleted callback:

useMutation(mutation, {
  onCompleted() {
    navigate('/go/to/page')
  }
);

// or passed to mutate directly
mutate({ 
  variables: {...}, 
  onCompleted: () => ...
})

Query refetching is also possible with refetchQueries, and if you want loading to remain true while those queries are refetched, you can pair it with awaitRefetchQueries: true.

I'm curious how would a general purpose callback function provide functionality that you can't get with the above in terms of mutation success?

---

before: form validation, toasts on errors, prefetch some additional data for operation

This still seems in the realm of variables validation to me (i.e. making sure the data you're about to send to the server is good), especially if that validation function could handle async code (I know several validation libraries out there do async validation). Is there another purpose I'm not seeing where the three things you list (form validation, toasts on errors, prefetch some additional data for operation) would not be used for this purpose?

---

FWIW, I definitely understand your point about loading and the need for setting that while this validation is happening. Today this is very tricky since you have to set your own flag if your validation is async in order for you to do things like disable buttons. I'm mostly getting at the specifics of how you would use this callback so we can name it/purpose it correctly, assuming we introduce this functionality.

[ziimakc]

It's not that it can't be done, it just requires to much boilerplate.

• onCompleted hook ignores loading, so any async operation inside will require it's own manual loading state manager, same for prehandler.
• error handling also require double effort, not only I need to handle mutation own errors, now I need to handle separately errors from onCompleted/catch blocks and so on.
• refetch can be any other non gql operation

Basically what I want is similar to react-query mutation hooks in my example tailored to gql, where you can handle everything in one place, do multiple operations and map errors to specific format used in application, something like:

export default function RouteComponent() {
	const globalContext = useContext(ActiveUserContext);
	const navigate = useNavigate();

	const userRegister = useLazyMutation({
		mutationFn: userRegisterFn,
	});

       if (userRegister.error) {
          // error here can be only my error no matter if it comes from gql or my custom validators
       }

	return (
		<form
			onSubmit={(e) => {
				e.preventDefault();

				userRegister.execute({
					formData: new FormData(e.target as HTMLFormElement),
					navigate,
					refetchActiveUser: globalContext.refetchActiveUser,
				});
			}}
		>
			<Button type="submit" disabled={userRegister.loading}>
				Register
			</Button>
		</form>
	);
}

async function userRegisterFn(
	// populated apollo data
	apolloData: {
		client: ApolloClient;
		// some additional client functionallity can be added in future
	},
	// data provided by user
	{
		formData,
		navigate,
		refetchActiveUser,
	}: {
		formData: FormData;
		navigate: NavigateFunction;
		refetchActiveUser: ActiveUserContextData["refetchActiveUser"];
	},
): Promise<{ error?: MyError, data?: MyData }> {
	const email = formData.get("email") as string;
	const password = formData.get("password") as string;
	const passwordRepeat = formData.get("password-repeat") as string;
	const nickname = formData.get("nickname") as string;
	if (password !== passwordRepeat) {
		const error = PublicFeErr.badRequest("wrong password");
		toast.error(err.message);
		return { error }; // or we can also use throw
	}

	const res = await apolloData.client.mutation(registerMutationDoc, {
		input: { email, password, nickname },
	});

	if (res.error) {
		return mapGqlError(res.error);
	}

	const loginRes = await apolloData.client.mutation(loginMutationDoc, {
		input: { email, password  },
	});

	if (loginRes.error) {
		return mapGqlError(loginRes.error);
	}

	await doesSmth()
	await refetchActiveUser();
	await navigate(
		href("/user/:userId/:userSlug?", {
			userId: registerRes.data.id,
			userSlug: registerRes.data.slug,
		}),
	);
}

Similar hook would also be nice for queries.

[jerelmiller]

@ziimakc appreciate it! I'm going to move this over to our feature requests repo, but we definitely think something like this would make sense for useMutation. Appreciate the info!