` | (Optional) Configuration options for the action. |
| `options.retries?` | `number` | (Optional) Number of retry attempts (default: 3) |
| `options.onStart?` | `() => void` | (Optional) The function to call when the action starts |
| `options.onSuccess?` | `(data?: TOutput) => void` | (Optional) The function to call when the action succeeds |
| `options.onError?` | `(error: string) => void` | (Optional) The function to call when the action fails. |
| `options.onComplete?` | `() => void` | The function to call when the action completes. |
| `options.toastMessages?` | `{ loading: string; success: string }` | (Optional) The messages to display in the toast. |
| `options.toastMessages.loading` | `string` | The message to display when the action is in progress. |
| `options.toastMessages.success` | `string` | The message to display when the action succeeds. |
### Returns
- **`clientAction(input: TInput)`** - Function to execute the server action
- **`abortAction()`** - Signal that Cancels the execution of current action.
- **`error?`** - Error message if the action fails.
- **`data?`** - Data you returned in the server action handler function after DB interaction.
- **`isPending`** - Boolean indicating if the action is in progress.
- **`fieldErrors?`** - The field errors that occurred in zod validation if any.
- **`setFieldErrors`** - The function to set the field errors.
# 🚀 Sample Codes for each possible scenario
Any public client can consume this action
```private=false, roles=NA, args=undefined```
// src/actions/with-package.ts
"use server";
import { createSafeAction } from "safe-actions-state";
import { z } from "zod";
const postSchema = z.object({
title: z.string().min(1),
content: z.string().min(1),
});
const postHandler = async () => {
await new Promise((resolve) => setTimeout(resolve, 3000));
return { data: { id: "123", title: "Test", content: "Test Content" } };
};
export const SafeServerAction = createSafeAction({
action: { withInputs: false, handler: postHandler },
actionType: { isPrivate: false }
});
// src/app/with-package.tsx
"use client";
import { SafeServerAction } from "@/actions/with-package";
import { useSafeAction } from "safe-actions-state";
export default function Home() {
const { clientAction, isPending, error, fieldErrors, data, abortAction } = useSafeAction(SafeServerAction, {
toastMessages: {
loading: "Creating post...",
success: "Post created successfully",
},
onStart: () => console.log("STARTED"),
onSuccess: (data) => console.log("SUCCESS", data),
onError: (error) => console.log("ERROR", error),
onComplete: () => console.log("COMPLETE"),
retries: 3,
});
return (
<div className="flex flex-col items-center justify-center min-h-screen p-8 pb-20 gap-16 sm:p-20 bg-black">
<button>
className="cursor-pointer border max-w-fit px-4 py-2 rounded-2xl bg-blue-500 text-black text-2xl"
onClick={async () => await clientAction()}
>
{isPending ? "Creating..." : "Create Post"}
</button>
<pre className="text-white">
{JSON.stringify({ fieldErrors, error, data }, null, 2)}
</pre>
</div>
);
}
Any public client can consume this action with arguments
```private=false, roles=NA, args=defined```
// src/actions/with-package.ts
"use server";
import { createSafeAction } from "safe-actions-state";
import { z } from "zod";
const postSchema = z.object({
title: z.string().min(1),
content: z.string().min(1),
});
const postHandler = async (validatedData: z.infer<typeof postSchema>) => {
await new Promise((resolve) => setTimeout(resolve, 3000));
return { data: { ...validatedData, id: "123" } };
};
export const SafeServerAction = createSafeAction({
action: { withInputs: true, handler: postHandler, schema: postSchema },
actionType: { isPrivate: false }
});
// src/app/with-package.tsx
"use client";
import { SafeServerAction } from "@/actions/with-package";
import { useSafeAction } from "safe-actions-state";
export default function Home() {
const { clientAction, isPending, fieldErrors, error, data, abortAction } = useSafeAction(SafeServerAction, {
toastMessages: {
loading: "Creating post...",
success: "Post created successfully",
},
onStart: () => console.log("STARTED"),
onSuccess: (data) => console.log("SUCCESS", data),
onError: (error) => console.log("ERROR", error),
onComplete: () => console.log("COMPLETE"),
retries: 3,
});
return (
<div className="flex flex-col items-center justify-center min-h-screen p-8 pb-20 gap-16 sm:p-20 bg-black">
<button>
className="cursor-pointer border max-w-fit px-4 py-2 rounded-2xl bg-blue-500 text-black text-2xl"
onClick={async () => await clientAction({ title: "test", content: "test" })}
>
{isPending ? "Creating..." : "Create Post"}
</button>
<pre className="text-white">
{JSON.stringify({ fieldErrors, error, data }, null, 2)}
</pre>
</div>
);
}
Only allowed roles can consume this action with arguments
```private=true, roles=defined, args=defined```
// src/actions/with-package.ts
"use server";
import { createSafeAction } from "safe-actions-state";
import { z } from "zod";
const postSchema = z.object({
title: z.string().min(1),
content: z.string().min(1),
});
const postHandler = async (validatedData: z.infer<typeof postSchema>) => {
await new Promise((resolve) => setTimeout(resolve, 3000));
return { data: { ...validatedData, id: "123" } };
};
export const SafeServerAction = createSafeAction({
action: { withInputs: true, handler: postHandler, schema: postSchema },
actionType: { isPrivate: true, allowedRoles: ["admin", "founder"] }
});
// src/app/with-package.tsx
"use client";
import { SafeServerAction } from "@/actions/with-package";
import { useSafeAction } from "safe-actions-state";
export default function Home() {
const { clientAction, isPending, fieldErrors, error, data, abortAction } = useSafeAction(SafeServerAction, {
toastMessages: {
loading: "Creating post...",
success: "Post created successfully",
},
onStart: () => console.log("STARTED"),
onSuccess: (data) => console.log("SUCCESS", data),
onError: (error) => console.log("ERROR", error),
onComplete: () => console.log("COMPLETE"),
retries: 3,
});
return (
<div className="flex flex-col items-center justify-center min-h-screen p-8 pb-20 gap-16 sm:p-20 bg-black">
<button>
className="cursor-pointer border max-w-fit px-4 py-2 rounded-2xl bg-blue-500 text-black text-2xl"
onClick={async () => await clientAction({ title: "test", content: "test" })}
>
{isPending ? "Creating..." : "Create Post"}
</button>
<pre className="text-white">
{JSON.stringify({ fieldErrors, error, data }, null, 2)}
</pre>
</div>
);
}
Only allowed roles can consume this action
```private=true, roles=defined, args=undefined```
// src/actions/with-package.ts
"use server";
import { createSafeAction } from "safe-actions-state";
import { z } from "zod";
const postSchema = z.object({
title: z.string().min(1),
content: z.string().min(1),
});
const postHandler = async () => {
await new Promise((resolve) => setTimeout(resolve, 3000));
return { data: { id: "123", title: "Test", content: "Test Content" } };
};
export const SafeServerAction = createSafeAction({
action: { withInputs: false, handler: postHandler },
actionType: { isPrivate: true, allowedRoles: ["admin", "founder"] }
});
// src/app/with-package.tsx
"use client";
import { SafeServerAction } from "@/actions/with-package";
import { useSafeAction } from "safe-actions-state";
export default function Home() {
const { clientAction, isPending, error, data, abortAction } = useSafeAction(SafeServerAction, {
toastMessages: {
loading: "Creating post...",
success: "Post created successfully",
},
onStart: () => console.log("STARTED"),
onSuccess: (data) => console.log("SUCCESS", data),
onError: (error) => console.log("ERROR", error),
onComplete: () => console.log("COMPLETE"),
retries: 3,
});
return (
<div className="flex flex-col items-center justify-center min-h-screen p-8 pb-20 gap-16 sm:p-20 bg-black">
<button>
className="cursor-pointer border max-w-fit px-4 py-2 rounded-2xl bg-blue-500 text-black text-2xl"
onClick={async () => await clientAction()}
>
{isPending ? "Creating..." : "Create Post"}
</button>
<pre className="text-white">
{JSON.stringify({ fieldErrors, error, data }, null, 2)}
</pre>
</div>
);
}
Any authenticated client can consume this action with arguments
```private=true, roles=undefined, args=defined```
// src/actions/with-package.ts
"use server";
import { createSafeAction } from "safe-actions-state";
import { z } from "zod";
const postSchema = z.object({
title: z.string().min(1),
content: z.string().min(1),
});
const postHandler = async (validatedData: z.infer<typeof postSchema>) => {
await new Promise((resolve) => setTimeout(resolve, 3000));
return { data: { ...validatedData, id: "123" } };
};
export const SafeServerAction = createSafeAction({
action: { withInputs: true, handler: postHandler, schema: postSchema },
actionType: { isPrivate: true }
});
// src/app/with-package.tsx
"use client";
import { SafeServerAction } from "@/actions/with-package";
import { useSafeAction } from "safe-actions-state";
export default function Home() {
const { clientAction, isPending, fieldErrors, error, data, abortAction } = useSafeAction(SafeServerAction, {
toastMessages: {
loading: "Creating post...",
success: "Post created successfully",
},
onStart: () => console.log("STARTED"),
onSuccess: (data) => console.log("SUCCESS", data),
onError: (error) => console.log("ERROR", error),
onComplete: () => console.log("COMPLETE"),
retries: 3,
});
return (
<div className="flex flex-col items-center justify-center min-h-screen p-8 pb-20 gap-16 sm:p-20 bg-black">
<button>
className="cursor-pointer border max-w-fit px-4 py-2 rounded-2xl bg-blue-500 text-black text-2xl"
onClick={async () => await clientAction({ title: "test", content: "test" })}
>
{isPending ? "Creating..." : "Create Post"}
</button>
<pre className="text-white">
{JSON.stringify({ fieldErrors, error, data }, null, 2)}
</pre>
</div>
);
}
Any authenticated client can consume this action
```private=true, roles=undefined, args=undefined```
// src/actions/with-package.ts
"use server";
import { createSafeAction } from "safe-actions-state";
import { z } from "zod";
const postSchema = z.object({
title: z.string().min(1),
content: z.string().min(1),
});
const postHandler = async () => {
await new Promise((resolve) => setTimeout(resolve, 3000));
return { data: { id: "123", title: "Test", content: "Test Content" } };
};
export const SafeServerAction = createSafeAction({
action: { withInputs: false, handler: postHandler },
actionType: { isPrivate: true }
});
// src/app/with-package.tsx
"use client";
import { SafeServerAction } from "@/actions/with-package";
import { useSafeAction } from "safe-actions-state";
export default function Home() {
const { clientAction, isPending, error, data, abortAction } = useSafeAction(SafeServerAction, {
toastMessages: {
loading: "Creating post...",
success: "Post created successfully",
},
onStart: () => console.log("STARTED"),
onSuccess: (data) => console.log("SUCCESS", data),
onError: (error) => console.log("ERROR", error),
onComplete: () => console.log("COMPLETE"),
retries: 3,
});
return (
<div className="flex flex-col items-center justify-center min-h-screen p-8 pb-20 gap-16 sm:p-20 bg-black">
<button>
className="cursor-pointer border max-w-fit px-4 py-2 rounded-2xl bg-blue-500 text-black text-2xl"
onClick={async () => await clientAction()}
>
{isPending ? "Creating..." : "Create Post"}
</button>
<pre className="text-white">
{JSON.stringify({ fieldErrors, error, data }, null, 2)}
</pre>
</div>
);
}
---
## 🎖 Community & Contributions
🚀 **Loved this package? Give it a star!** ⭐
🔗 **[GitHub Repository](https://github.com/SadiqVali786/safe-actions-state)**\
🚀 **Try it out and give me feedback on how it can be improved!**
🔗 **[NPM Package](https://www.npmjs.com/package/safe-actions-state)**
## ❤️ Support
Want to support this project? **Donate via [Patreon](#)**.
## ⚖️ License
Licensed under **MIT License**. Free to use, modify, and distribute. Give credit when using this package.
## 🚀 Start Building Faster with Safe Actions State!
Handle Server Action errors gracefully, automate zod validation, enforce RBAC, realtime toast notifications, and `reduce your server actions developement time by 80%`. Install now:
```sh
npm install safe-actions-state
```
