feat(hooks): return executeAsync from useAction and useOptimisticAction hooks (#147)

This PR adds the `executeAsync` function to the return object of `useAction` and `useOptimisticAction` hooks. It's currently not possible to add it to the `useStateAction` hook. As the name suggests, `executeAsync` returns a Promise with the same result of the `safeActionFn` you pass to the hook, and it allows to await the result of the action.

re #137, #72, #94

Author: TheEdoRan

apps/playground/src/app/(examples)/hook/page.tsx

@@ -10,7 +10,7 @@ import { deleteUser } from "./deleteuser-action";
 export default function Hook() {
 	// Safe action (`deleteUser`) and optional callbacks passed to `useAction` hook.
 	const {
-		execute,
+		executeAsync,
 		result,
 		status,
 		reset,
@@ -40,15 +40,17 @@ export default function Hook() {
 			<StyledHeading>Action using hook</StyledHeading>
 			<form
 				className="flex flex-col mt-8 space-y-4"
-				onSubmit={(e) => {
+				onSubmit={async (e) => {
 					e.preventDefault();
 					const formData = new FormData(e.currentTarget);
 					const input = Object.fromEntries(formData) as {
 						userId: string;
 					};
 
-					// Action call.
-					execute(input);
+					// Action call. Here we use `executeAsync` that lets us await the result. You can also use the `execute` function,
+					// which is synchronous.
+					const r = await executeAsync(input);
+					console.log("r", r);
 				}}>
 				<StyledInput
 					type="text"

packages/next-safe-action/src/hooks.ts

@@ -168,6 +168,36 @@ export const useAction = <
 		[safeActionFn]
 	);
 
+	const executeAsync = React.useCallback(
+		(input: S extends Schema ? InferIn<S> : void) => {
+			setIsIdle(false);
+			setClientInput(input);
+			setIsExecuting(true);
+
+			return new Promise<Awaited<ReturnType<typeof safeActionFn>>>((resolve, reject) => {
+				startTransition(() => {
+					safeActionFn(input as S extends Schema ? InferIn<S> : undefined)
+						.then((res) => {
+							setResult(res ?? EMPTY_HOOK_RESULT);
+							resolve(res);
+						})
+						.catch((e) => {
+							if (isRedirectError(e) || isNotFoundError(e)) {
+								throw e;
+							}
+
+							setResult({ fetchError: isError(e) ? e.message : "Something went wrong" });
+							reject(e);
+						})
+						.finally(() => {
+							setIsExecuting(false);
+						});
+				});
+			});
+		},
+		[safeActionFn]
+	);
+
 	const reset = () => {
 		setIsIdle(true);
 		setClientInput(undefined);
@@ -183,6 +213,7 @@ export const useAction = <
 
 	return {
 		execute,
+		executeAsync,
 		input: clientInput,
 		result,
 		reset,
@@ -250,6 +281,37 @@ export const useOptimisticAction = <
 		[safeActionFn, setOptimisticValue]
 	);
 
+	const executeAsync = React.useCallback(
+		(input: S extends Schema ? InferIn<S> : void) => {
+			setIsIdle(false);
+			setClientInput(input);
+			setIsExecuting(true);
+
+			return new Promise<Awaited<ReturnType<typeof safeActionFn>>>((resolve, reject) => {
+				startTransition(() => {
+					setOptimisticValue(input as S extends Schema ? InferIn<S> : undefined);
+					safeActionFn(input as S extends Schema ? InferIn<S> : undefined)
+						.then((res) => {
+							setResult(res ?? EMPTY_HOOK_RESULT);
+							resolve(res);
+						})
+						.catch((e) => {
+							if (isRedirectError(e) || isNotFoundError(e)) {
+								throw e;
+							}
+
+							setResult({ fetchError: isError(e) ? e.message : "Something went wrong" });
+							reject(e);
+						})
+						.finally(() => {
+							setIsExecuting(false);
+						});
+				});
+			});
+		},
+		[safeActionFn, setOptimisticValue]
+	);
+
 	const reset = () => {
 		setIsIdle(true);
 		setClientInput(undefined);
@@ -270,6 +332,7 @@ export const useOptimisticAction = <
 
 	return {
 		execute,
+		executeAsync,
 		input: clientInput,
 		result,
 		optimisticState,

website/docs/execution/hooks/useaction.md

@@ -75,6 +75,7 @@ As you can see, here we display a greet message after the action is performed, i
 | Name      | Type                                         | Purpose                                                                                           |
 | --------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | `execute` | `(input: InferIn<S>) => void`                | An action caller with no return. The input is the same as the safe action you passed to the hook. |
+| `executeAsync` | `(input: InferIn<S>) => Promise<Awaited<ReturnType<typeof safeActionFn>>>`                | An action caller that returns a promise with the return value of the safe action. The input is the same as the safe action you passed to the hook. |
 | `input`  | `InferIn<S> \| undefined`       | The input passed to the `execute` function.                             |
 | `result`  | [`HookResult`](/docs/types#hookresult)       | When the action gets called via `execute`, this is the result object.                             |
 | `reset`   | `() => void`                                 | Programmatically reset `input` and `result` object with this function.                            |

website/docs/execution/hooks/useoptimisticaction.md

@@ -135,6 +135,7 @@ export default function TodosBox({ todos }: Props) {
 | Name             | Type                                                                    | Purpose                                                                                                                                                                                                                                   |
 | ---------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `execute`        | `(input: InferIn<S>) => void`                                           | An action caller with no return. The input is the same as the safe action you passed to the hook.                                                                                                                                         |
+| `executeAsync` | `(input: InferIn<S>) => Promise<Awaited<ReturnType<typeof safeActionFn>>>`                | An action caller that returns a promise with the return value of the safe action. The input is the same as the safe action you passed to the hook. |
 | `input`  | `InferIn<S> \| undefined`       | The input passed to the `execute` function.                             |
 | `result`         | [`HookResult`](/docs/types#hookresult)                                  | When the action gets called via `execute`, this is the result object.                                                                                                                                                                     |
 | `optimisticState` | `State` | This contains the state that gets updated immediately after `execute` is called, with the behavior you defined in the `updateFn` function. The initial state is what you provided to the hook via `currentState` argument. If an error occurs during action execution, the `optimisticState` reverts to the state that it had pre-last-last  action execution. |

website/docs/migrations/v6-to-v7.md

@@ -157,6 +157,10 @@ Sometimes it's useful to access the input passed to an action when using hooks.
 
 Starting from version 7, `isIdle`, `isExecuting`, `hasSucceeded` and `hasErrored` are returned from hooks, in addition to the `status` property. This is the same behavior of next-safe-action pre-v4 and very similar to the [TanStack Query](https://tanstack.com/query/latest) API.
 
+### [Return `executeAsync` from `useAction` and `useOptimisticAction` hooks](https://github.com/TheEdoRan/next-safe-action/issues/146)
+
+Sometimes it's useful to await the result of an action execution. Starting from version 7, `executeAsync` is returned from `useAction` and `useOptimisticAction` hooks. It's essentially the same as the original safe action function, with the added benefits from the hooks. It's currently not possible to add this function to the `useStateAction` hook, due to internal React limitations.
+
 ## Refactors
 
 ### `serverCodeFn` signature