Merge branch 'main' into 'next'

packages/example-app/src/app/hook/deleteuser-form.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useAction } from "next-safe-action/hooks";
+import { isExecuting } from "next-safe-action/status";
 import { deleteUser } from "./deleteuser-action";
 
 type Props = {
@@ -57,7 +58,7 @@ const DeleteUserForm = ({ userId }: Props) => {
 			</form>
 			<div id="result-container">
 				<pre>Deleted user ID: {userId}</pre>
-				<pre>Is executing: {JSON.stringify(status === "executing")}</pre>
+				<pre>Is executing: {JSON.stringify(isExecuting(status))}</pre>
 				<div>Action result:</div>
 				<pre className="result">
 					{

packages/next-safe-action/package.json

@@ -11,7 +11,8 @@
 	],
 	"exports": {
 		".": "./dist/index.mjs",
-		"./hooks": "./dist/hooks.mjs"
+		"./hooks": "./dist/hooks.mjs",
+		"./status": "./dist/status.mjs"
 	},
 	"typesVersions": {
 		"*": {
@@ -20,6 +21,9 @@
 			],
 			"hooks": [
 				"./dist/hooks.d.mts"
+			],
+			"status": [
+				"./dist/status.d.mts"
 			]
 		}
 	},

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

@@ -0,0 +1,37 @@
+import type { HookActionStatus } from "./hooks";
+
+/**
+ * Returns true if the action is idle.
+ * @param status
+ * @returns
+ */
+export function isIdle(status: HookActionStatus): status is "idle" {
+	return status === "idle";
+}
+
+/**
+ * Returns true if the action is executing.
+ * @param status
+ * @returns
+ */
+export function isExecuting(status: HookActionStatus): status is "executing" {
+	return status === "executing";
+}
+
+/**
+ * Returns true if the action has succeeded.
+ * @param status
+ * @returns
+ */
+export function hasSucceeded(status: HookActionStatus): status is "hasSucceeded" {
+	return status === "hasSucceeded";
+}
+
+/**
+ * Returns true if the action has errored.
+ * @param status
+ * @returns
+ */
+export function hasErrored(status: HookActionStatus): status is "hasErrored" {
+	return status === "hasErrored";
+}

packages/next-safe-action/tsup.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from "tsup";
 
 export default defineConfig({
-	entry: ["src/index.ts", "src/hooks.ts"],
+	entry: ["src/index.ts", "src/hooks.ts", "src/status.ts"],
 	format: ["esm"],
 	clean: true,
 	splitting: false,

website/docs/usage/client-components/hooks/checking-action-status.md

@@ -0,0 +1,21 @@
+---
+sidebar_position: 4
+description: Learn how to check the current action status.
+---
+
+# Checking action status
+
+There are two ways to get the current action status:
+
+1. Directly via the `status` property returned by `useAction` and `useOptimisticAction` hooks.
+2. Using utility functions imported from `next-safe-action/status`.
+
+## Utility functions
+
+You can import `isIdle`, `isExecuting`, `hasSucceeded`, and `hasErrored` from `next-safe-action/status`. This emulates the pre v4 implementation, and it's similar to the [Tanstack Query](https://tanstack.com/query/latest) API.
+
+### Why using single `status` property is better?
+
+The reason for the v4 change, other than debloating the hook result object, is that using a single `status` string property is discriminating, i.e. **only one** status can be active at a specific time. Instead, returning multiple functions to check status as before v4, doesn't guarantee the same behavior.
+
+If you use the utility functions imported from `next-safe-action/status` you get the same discriminated status string, thanks to TypeScript's [type predicates](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) feature.