nuxt-safe-action 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip Rutberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# nuxt-safe-action
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Type-safe and validated server actions for Nuxt.
+
+End-to-end type safety, input/output validation via Zod, composable middleware, and Vue composables with loading states, error handling, and optimistic updates.
+
+```ts
+// server/actions/create-post.ts
+import { z } from 'zod'
+import { actionClient } from '../utils/action-client'
+
+export default actionClient
+  .schema(z.object({
+    title: z.string().min(1).max(200),
+    body: z.string().min(1),
+  }))
+  .action(async ({ parsedInput }) => {
+    const post = await db.post.create({ data: parsedInput })
+    return { id: post.id, title: post.title }
+  })
+```
+
+```vue
+<script setup lang="ts">
+import { createPost } from '#safe-action/actions'
+
+const { execute, data, status, validationErrors } = useAction(createPost)
+</script>
+```
+
+## Features
+
+- **End-to-end type safety** — Input and output types flow from server to client automatically
+- **Input validation** — Zod schemas validate input before your handler runs
+- **Composable middleware** — Chain auth checks, rate limiting, logging, and more
+- **Vue composables** — `useAction` with reactive `status`, `data`, `error`, and `validationErrors`
+- **Auto route generation** — Define actions in `server/actions/`, routes are created for you
+- **H3Event access** — Full request context in middleware (headers, cookies, IP, sessions)
+- **Nuxt-native** — Auto-imports, works with Nuxt DevTools, familiar conventions
+
+## Quick Setup
+
+Install the module:
+
+```bash
+npx nuxi module add nuxt-safe-action
+```
+
+Or manually:
+
+```bash
+pnpm add nuxt-safe-action zod
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-safe-action'],
+})
+```
+
+## Usage
+
+### 1. Create an action client
+
+```ts
+// server/utils/action-client.ts
+import { createSafeActionClient } from '#safe-action'
+
+export const actionClient = createSafeActionClient({
+  handleServerError: (error) => {
+    console.error('Action error:', error.message)
+    return error.message
+  },
+})
+
+// Optional: create an authenticated client
+export const authActionClient = actionClient
+  .use(async ({ next, event }) => {
+    const session = await getUserSession(event)
+    if (!session) throw new Error('Unauthorized')
+    return next({ ctx: { userId: session.user.id } })
+  })
+```
+
+### 2. Define actions
+
+Create action files in `server/actions/`. Each file should export a default action:
+
+```ts
+// server/actions/greet.ts
+import { z } from 'zod'
+import { actionClient } from '../utils/action-client'
+
+export default actionClient
+  .schema(z.object({
+    name: z.string().min(1, 'Name is required'),
+  }))
+  .action(async ({ parsedInput }) => {
+    return { greeting: `Hello, ${parsedInput.name}!` }
+  })
+```
+
+### 3. Use in components
+
+```vue
+<script setup lang="ts">
+import { greet } from '#safe-action/actions'
+
+const { execute, data, status, validationErrors, isExecuting, hasSucceeded } = useAction(greet, {
+  onSuccess({ data }) {
+    console.log(data.greeting) // fully typed!
+  },
+  onError({ error }) {
+    console.error(error)
+  },
+})
+</script>
+
+<template>
+  <form @submit.prevent="execute({ name: 'World' })">
+    <button :disabled="isExecuting">
+      {{ isExecuting ? 'Loading...' : 'Greet' }}
+    </button>
+    <p v-if="hasSucceeded">{{ data?.greeting }}</p>
+  </form>
+</template>
+```
+
+## API
+
+### `createSafeActionClient(opts?)`
+
+Creates a new action client. Call this once and reuse it across actions.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `handleServerError` | `(error: Error) => string` | Transform server errors before sending to client |
+
+### Builder chain
+
+| Method | Description |
+|--------|-------------|
+| `.schema(zodSchema)` | Set input validation schema |
+| `.outputSchema(zodSchema)` | Set output validation schema |
+| `.use(middleware)` | Add middleware to the chain |
+| `.metadata(meta)` | Attach metadata (accessible in middleware) |
+| `.action(handler)` | Define the action handler (terminal) |
+
+### `useAction(action, callbacks?)`
+
+Vue composable for executing actions.
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `execute(input)` | `(input: TInput) => void` | Fire-and-forget execution |
+| `executeAsync(input)` | `(input: TInput) => Promise<ActionResult>` | Awaitable execution |
+| `data` | `Ref<TOutput \| undefined>` | Success data |
+| `serverError` | `Ref<string \| undefined>` | Server error message |
+| `validationErrors` | `Ref<Record<string, string[]> \| undefined>` | Per-field validation errors |
+| `status` | `Ref<ActionStatus>` | `'idle' \| 'executing' \| 'hasSucceeded' \| 'hasErrored'` |
+| `isIdle` | `ComputedRef<boolean>` | Status shortcut |
+| `isExecuting` | `ComputedRef<boolean>` | Status shortcut |
+| `hasSucceeded` | `ComputedRef<boolean>` | Status shortcut |
+| `hasErrored` | `ComputedRef<boolean>` | Status shortcut |
+| `reset()` | `() => void` | Reset all state to initial |
+
+**Callbacks:**
+
+| Callback | Description |
+|----------|-------------|
+| `onSuccess({ data, input })` | Called when the action succeeds |
+| `onError({ error, input })` | Called on server or validation error |
+| `onSettled({ result, input })` | Called after every execution |
+| `onExecute({ input })` | Called when execution starts |
+
+### Middleware
+
+```ts
+actionClient.use(async ({ ctx, next, event, metadata, clientInput }) => {
+  // ctx: context from previous middleware
+  // event: H3Event with full request access
+  // metadata: action metadata
+  // clientInput: raw input before validation
+  return next({ ctx: { ...ctx, myData: 'value' } })
+})
+```
+
+### Error handling
+
+```ts
+import { ActionError, returnValidationErrors } from '#safe-action'
+
+// Throw a server error
+throw new ActionError('Not enough credits')
+
+// Return per-field validation errors
+returnValidationErrors({
+  email: ['This email is already taken'],
+})
+```
+
+## Configuration
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-safe-action'],
+  safeAction: {
+    actionsDir: 'actions', // relative to server/ directory (default: 'actions')
+  },
+})
+```
+
+## How it works
+
+1. You define actions in `server/actions/` using the builder chain
+2. The module scans this directory and auto-generates Nitro API routes at `/api/_actions/<name>`
+3. A typed virtual module `#safe-action/actions` provides client-side references with full type inference
+4. `useAction()` calls the generated route via `$fetch` and returns reactive state
+
+## Inspiration
+
+Inspired by [next-safe-action](https://github.com/TheEdoRan/next-safe-action) — adapted for the Nuxt ecosystem with H3Event access, auto route generation, and Vue reactivity.
+
+## Contributing
+
+<details>
+  <summary>Local development</summary>
+
+  ```bash
+  # Install dependencies
+  pnpm install
+
+  # Generate type stubs
+  pnpm run dev:prepare
+
+  # Develop with the playground
+  pnpm run dev
+
+  # Build the playground
+  pnpm run dev:build
+
+  # Run ESLint
+  pnpm run lint
+
+  # Run Vitest
+  pnpm run test
+  pnpm run test:watch
+  ```
+
+</details>
+
+## License
+
+[MIT](./LICENSE)
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-safe-action/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/nuxt-safe-action
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-safe-action.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/nuxt-safe-action
+
+[license-src]: https://img.shields.io/npm/l/nuxt-safe-action.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/nuxt-safe-action
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,13 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    /**
+     * Directory where action files are located, relative to the server directory.
+     * @default 'actions'
+     */
+    actionsDir?: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-safe-action",
+  "configKey": "safeAction",
+  "compatibility": {
+    "nuxt": ">=4.0.0"
+  },
+  "version": "0.1.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,130 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join, posix, basename } from 'node:path';
+import { useLogger, defineNuxtModule, createResolver, addImportsDir, addServerImports, addTemplate } from '@nuxt/kit';
+
+const logger = useLogger("nuxt-safe-action");
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-safe-action",
+    configKey: "safeAction",
+    compatibility: {
+      nuxt: ">=4.0.0"
+    }
+  },
+  defaults: {
+    actionsDir: "actions"
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    addImportsDir(resolve("./runtime/composables"));
+    addServerImports([
+      { name: "createSafeActionClient", from: resolve("./runtime/server/createSafeActionClient") },
+      { name: "ActionError", from: resolve("./runtime/server/errors") },
+      { name: "ActionValidationError", from: resolve("./runtime/server/errors") },
+      { name: "returnValidationErrors", from: resolve("./runtime/server/errors") }
+    ]);
+    nuxt.options.alias["#safe-action"] = resolve("./runtime/server/index");
+    const actionsDir = options.actionsDir || "actions";
+    nuxt.hook("nitro:config", (nitroConfig) => {
+      const serverDir2 = nuxt.options.serverDir;
+      const fullActionsDir2 = join(serverDir2, actionsDir);
+      if (!existsSync(fullActionsDir2)) {
+        logger.info(
+          `No actions directory found at ${fullActionsDir2} \u2014 skipping action route generation.`
+        );
+        return;
+      }
+      const actionFiles = scanActionFiles(fullActionsDir2);
+      if (actionFiles.length === 0) {
+        logger.info("No action files found.");
+        return;
+      }
+      logger.info(
+        `Found ${actionFiles.length} action file(s): ${actionFiles.map((a) => a.name).join(", ")}`
+      );
+      nitroConfig.virtual = nitroConfig.virtual || {};
+      nitroConfig.handlers = nitroConfig.handlers || [];
+      for (const action of actionFiles) {
+        const virtualKey = `#safe-action-handler/${action.name}`;
+        nitroConfig.virtual[virtualKey] = generateHandlerCode(action);
+        nitroConfig.handlers.push({
+          route: `/api/_actions/${action.name}`,
+          method: "post",
+          handler: virtualKey
+        });
+      }
+    });
+    const serverDir = nuxt.options.serverDir;
+    const fullActionsDir = join(serverDir, actionsDir);
+    addTemplate({
+      filename: "safe-action/actions.ts",
+      write: true,
+      getContents: () => {
+        if (!existsSync(fullActionsDir)) {
+          return "export {}\n";
+        }
+        const actionFiles = scanActionFiles(fullActionsDir);
+        if (actionFiles.length === 0) {
+          return "export {}\n";
+        }
+        const lines = [
+          `import type { SafeActionReference } from '#safe-action'`,
+          ""
+        ];
+        for (const action of actionFiles) {
+          const exportName = toCamelCase(action.name);
+          const relativePath = posix.join("../..", "server", actionsDir, action.name);
+          lines.push(`import type _action_${exportName} from '${relativePath}'`);
+        }
+        lines.push("");
+        for (const action of actionFiles) {
+          const exportName = toCamelCase(action.name);
+          lines.push(
+            `export const ${exportName}: SafeActionReference<(typeof _action_${exportName})['_types']['input'], (typeof _action_${exportName})['_types']['output'], (typeof _action_${exportName})['_types']['serverError']> = Object.freeze({ __safeActionPath: '${action.name}' }) as any`
+          );
+        }
+        return lines.join("\n") + "\n";
+      }
+    });
+    nuxt.hook("prepare:types", ({ tsConfig }) => {
+      tsConfig.compilerOptions = tsConfig.compilerOptions || {};
+      tsConfig.compilerOptions.paths = tsConfig.compilerOptions.paths || {};
+      tsConfig.compilerOptions.paths["#safe-action/actions"] = ["./safe-action/actions"];
+      tsConfig.compilerOptions.paths["#safe-action"] = [
+        resolve("./runtime/server/index").replace(/\.ts$/, "")
+      ];
+    });
+    nuxt.options.alias["#safe-action/actions"] = join(nuxt.options.buildDir, "safe-action/actions");
+  }
+});
+function scanActionFiles(dir, prefix = "") {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...scanActionFiles(fullPath, prefix ? `${prefix}/${entry.name}` : entry.name));
+    } else if (entry.isFile() && entry.name.endsWith(".ts") && !entry.name.endsWith(".d.ts") && entry.name !== "index.ts") {
+      const name = prefix ? `${prefix}/${basename(entry.name, ".ts")}` : basename(entry.name, ".ts");
+      results.push({ name, filePath: fullPath });
+    }
+  }
+  return results;
+}
+function generateHandlerCode(action) {
+  return `
+import { defineEventHandler, readBody } from 'h3'
+import action from '${action.filePath}'
+
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event).catch(() => undefined)
+  return action._execute(body, event)
+})
+`;
+}
+function toCamelCase(name) {
+  return name.replace(/[/-](\w)/g, (_, c) => c.toUpperCase()).replace(/^(\w)/, (_, c) => c.toLowerCase());
+}
+
+export { module$1 as default };

package/dist/runtime/composables/useAction.d.ts

@@ -0,0 +1,15 @@
+import type { SafeAction, SafeActionReference, UseActionReturn, UseActionCallbacks } from '../types.js';
+/**
+ * Vue composable for executing a safe action with reactive status tracking.
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * import { createPost } from '#safe-action/actions'
+ *
+ * const { execute, data, status, error } = useAction(createPost, {
+ *   onSuccess({ data }) { console.log('Created:', data) },
+ * })
+ * </script>
+ * ```
+ */
+export declare function useAction<TInput, TOutput, TServerError = string>(action: SafeAction<TInput, TOutput, TServerError> | SafeActionReference<TInput, TOutput, TServerError>, callbacks?: UseActionCallbacks<TInput, TOutput, TServerError>): UseActionReturn<TInput, TOutput, TServerError>;

package/dist/runtime/composables/useAction.js

@@ -0,0 +1,76 @@
+import { ref, computed, readonly } from "vue";
+export function useAction(action, callbacks) {
+  const actionPath = action.__safeActionPath;
+  const data = ref();
+  const serverError = ref();
+  const validationErrors = ref();
+  const status = ref("idle");
+  async function executeAsync(input) {
+    serverError.value = void 0;
+    validationErrors.value = void 0;
+    status.value = "executing";
+    callbacks?.onExecute?.({ input });
+    try {
+      const result = await $fetch(
+        `/api/_actions/${actionPath}`,
+        {
+          method: "POST",
+          body: input
+        }
+      );
+      if (result.data !== void 0) {
+        data.value = result.data;
+        status.value = "hasSucceeded";
+        callbacks?.onSuccess?.({ data: result.data, input });
+      } else if (result.serverError !== void 0) {
+        serverError.value = result.serverError;
+        status.value = "hasErrored";
+        callbacks?.onError?.({
+          error: { serverError: result.serverError },
+          input
+        });
+      } else if (result.validationErrors !== void 0) {
+        validationErrors.value = result.validationErrors;
+        status.value = "hasErrored";
+        callbacks?.onError?.({
+          error: { validationErrors: result.validationErrors },
+          input
+        });
+      }
+      callbacks?.onSettled?.({ result, input });
+      return result;
+    } catch (fetchError) {
+      const message = fetchError instanceof Error ? fetchError.message : "An unexpected error occurred";
+      serverError.value = message;
+      status.value = "hasErrored";
+      const result = {
+        serverError: message
+      };
+      callbacks?.onError?.({ error: { serverError: message }, input });
+      callbacks?.onSettled?.({ result, input });
+      return result;
+    }
+  }
+  function execute(input) {
+    executeAsync(input);
+  }
+  function reset() {
+    data.value = void 0;
+    serverError.value = void 0;
+    validationErrors.value = void 0;
+    status.value = "idle";
+  }
+  return {
+    execute,
+    executeAsync,
+    data: readonly(data),
+    serverError: readonly(serverError),
+    validationErrors: readonly(validationErrors),
+    status: readonly(status),
+    isIdle: computed(() => status.value === "idle"),
+    isExecuting: computed(() => status.value === "executing"),
+    hasSucceeded: computed(() => status.value === "hasSucceeded"),
+    hasErrored: computed(() => status.value === "hasErrored"),
+    reset
+  };
+}

package/dist/runtime/server/createSafeActionClient.d.ts

@@ -0,0 +1,52 @@
+import type { ZodType } from 'zod';
+import type { SafeAction, SafeActionClientOpts, ActionMetadata, MiddlewareFn, ActionHandler } from '../types.js';
+declare class SafeActionBuilder<TCtx, TInput, TServerError> {
+    private _middlewares;
+    private _inputSchema?;
+    private _outputSchema?;
+    private _metadata;
+    private _handleServerError?;
+    constructor(opts: {
+        middlewares: MiddlewareFn<any, any>[];
+        inputSchema?: ZodType;
+        outputSchema?: ZodType;
+        metadata: ActionMetadata;
+        handleServerError?: (error: Error) => TServerError;
+    });
+    /**
+     * Add a Zod schema for input validation.
+     */
+    schema<TSchema extends ZodType>(schema: TSchema): SafeActionBuilder<TCtx, TSchema extends ZodType<infer T> ? T : never, TServerError>;
+    /**
+     * Add a Zod schema for output validation.
+     */
+    outputSchema<TSchema extends ZodType>(schema: TSchema): SafeActionBuilder<TCtx, TInput, TServerError>;
+    /**
+     * Add middleware to the action chain.
+     * Middleware runs in order, and each can extend the context.
+     */
+    use<TNewCtx>(middleware: MiddlewareFn<TCtx, TNewCtx>): SafeActionBuilder<TNewCtx, TInput, TServerError>;
+    /**
+     * Attach metadata to the action (e.g. action name, tags).
+     * Accessible in middleware via `args.metadata`.
+     */
+    metadata(meta: ActionMetadata): SafeActionBuilder<TCtx, TInput, TServerError>;
+    /**
+     * Define the action handler. This is the terminal method of the chain.
+     * Returns a `SafeAction` object that can be exported from `server/actions/`.
+     */
+    action<TOutput>(handler: ActionHandler<TCtx, TInput, TOutput>): SafeAction<TInput, TOutput, TServerError>;
+}
+/**
+ * Create a safe action client with optional global configuration.
+ *
+ * ```ts
+ * import { createSafeActionClient } from '#safe-action'
+ *
+ * export const actionClient = createSafeActionClient({
+ *   handleServerError: (e) => e.message,
+ * })
+ * ```
+ */
+export declare function createSafeActionClient<TServerError = string>(opts?: SafeActionClientOpts<TServerError>): SafeActionBuilder<Record<string, never>, undefined, TServerError>;
+export {};

package/dist/runtime/server/createSafeActionClient.js

@@ -0,0 +1,169 @@
+import { ActionError, ActionValidationError } from "./errors.js";
+function formatZodErrors(zodError) {
+  const errors = {};
+  for (const issue of zodError.issues) {
+    const path = issue.path.join(".") || "_root";
+    if (!errors[path]) {
+      errors[path] = [];
+    }
+    errors[path].push(issue.message);
+  }
+  return errors;
+}
+async function executeMiddlewareChain(middlewares, initialCtx, clientInput, metadata, event, innerFn) {
+  let execute = innerFn;
+  for (let i = middlewares.length - 1; i >= 0; i--) {
+    const nextExecute = execute;
+    const middleware = middlewares[i];
+    execute = async (ctx) => {
+      let result;
+      await middleware({
+        ctx,
+        clientInput,
+        metadata,
+        event,
+        next: async ({ ctx: newCtx }) => {
+          result = await nextExecute(newCtx);
+          return { ctx: newCtx };
+        }
+      });
+      return result;
+    };
+  }
+  return execute(initialCtx);
+}
+class SafeActionBuilder {
+  _middlewares;
+  _inputSchema;
+  _outputSchema;
+  _metadata;
+  _handleServerError;
+  constructor(opts) {
+    this._middlewares = opts.middlewares;
+    this._inputSchema = opts.inputSchema;
+    this._outputSchema = opts.outputSchema;
+    this._metadata = opts.metadata;
+    this._handleServerError = opts.handleServerError;
+  }
+  /**
+   * Add a Zod schema for input validation.
+   */
+  schema(schema) {
+    return new SafeActionBuilder({
+      middlewares: this._middlewares,
+      inputSchema: schema,
+      outputSchema: this._outputSchema,
+      metadata: this._metadata,
+      handleServerError: this._handleServerError
+    });
+  }
+  /**
+   * Add a Zod schema for output validation.
+   */
+  outputSchema(schema) {
+    return new SafeActionBuilder({
+      middlewares: this._middlewares,
+      inputSchema: this._inputSchema,
+      outputSchema: schema,
+      metadata: this._metadata,
+      handleServerError: this._handleServerError
+    });
+  }
+  /**
+   * Add middleware to the action chain.
+   * Middleware runs in order, and each can extend the context.
+   */
+  use(middleware) {
+    return new SafeActionBuilder({
+      middlewares: [...this._middlewares, middleware],
+      inputSchema: this._inputSchema,
+      outputSchema: this._outputSchema,
+      metadata: this._metadata,
+      handleServerError: this._handleServerError
+    });
+  }
+  /**
+   * Attach metadata to the action (e.g. action name, tags).
+   * Accessible in middleware via `args.metadata`.
+   */
+  metadata(meta) {
+    return new SafeActionBuilder({
+      middlewares: this._middlewares,
+      inputSchema: this._inputSchema,
+      outputSchema: this._outputSchema,
+      metadata: { ...this._metadata, ...meta },
+      handleServerError: this._handleServerError
+    });
+  }
+  /**
+   * Define the action handler. This is the terminal method of the chain.
+   * Returns a `SafeAction` object that can be exported from `server/actions/`.
+   */
+  action(handler) {
+    const config = {
+      middlewares: this._middlewares,
+      inputSchema: this._inputSchema,
+      outputSchema: this._outputSchema,
+      metadata: this._metadata,
+      handler,
+      handleServerError: this._handleServerError
+    };
+    return {
+      _execute: (rawInput, event) => executeAction(rawInput, event, config)
+    };
+  }
+}
+async function executeAction(rawInput, event, config) {
+  try {
+    return await executeMiddlewareChain(
+      config.middlewares,
+      {},
+      rawInput,
+      config.metadata,
+      event,
+      async (ctx) => {
+        let parsedInput = rawInput;
+        if (config.inputSchema) {
+          const result = config.inputSchema.safeParse(rawInput);
+          if (!result.success) {
+            return { validationErrors: formatZodErrors(result.error) };
+          }
+          parsedInput = result.data;
+        }
+        const data = await config.handler({
+          parsedInput,
+          ctx,
+          event
+        });
+        if (config.outputSchema) {
+          const result = config.outputSchema.safeParse(data);
+          if (!result.success) {
+            throw new Error(
+              `Output validation failed: ${JSON.stringify(formatZodErrors(result.error))}`
+            );
+          }
+          return { data: result.data };
+        }
+        return { data };
+      }
+    );
+  } catch (error) {
+    if (error instanceof ActionValidationError) {
+      return { validationErrors: error.validationErrors };
+    }
+    if (error instanceof ActionError) {
+      return { serverError: error.message };
+    }
+    if (config.handleServerError) {
+      return { serverError: config.handleServerError(error) };
+    }
+    return { serverError: "An unexpected error occurred" };
+  }
+}
+export function createSafeActionClient(opts = {}) {
+  return new SafeActionBuilder({
+    middlewares: [],
+    metadata: {},
+    handleServerError: opts.handleServerError
+  });
+}

package/dist/runtime/server/errors.d.ts

@@ -0,0 +1,31 @@
+import type { ValidationErrors } from '../types.js';
+/**
+ * Throw this inside an action handler or middleware to return a typed
+ * server error to the client.
+ *
+ * ```ts
+ * throw new ActionError('Not enough credits')
+ * ```
+ */
+export declare class ActionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Throw this inside an action handler to return per-field validation
+ * errors to the client (useful when Zod alone isn't enough).
+ *
+ * ```ts
+ * throw new ActionValidationError({
+ *   email: ['This email is already taken'],
+ * })
+ * ```
+ */
+export declare class ActionValidationError extends Error {
+    readonly validationErrors: ValidationErrors;
+    constructor(validationErrors: ValidationErrors);
+}
+/**
+ * Utility to throw validation errors from within an action handler.
+ * Shorthand for `throw new ActionValidationError(errors)`.
+ */
+export declare function returnValidationErrors(errors: ValidationErrors): never;

package/dist/runtime/server/errors.js

@@ -0,0 +1,17 @@
+export class ActionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ActionError";
+  }
+}
+export class ActionValidationError extends Error {
+  validationErrors;
+  constructor(validationErrors) {
+    super("Validation failed");
+    this.name = "ActionValidationError";
+    this.validationErrors = validationErrors;
+  }
+}
+export function returnValidationErrors(errors) {
+  throw new ActionValidationError(errors);
+}

package/dist/runtime/server/handler.d.ts

@@ -0,0 +1,6 @@
+import type { SafeAction } from '../types.js';
+/**
+ * Creates a Nitro event handler for a given safe action.
+ * Used internally by the module to generate route handlers.
+ */
+export declare function createActionHandler(action: SafeAction<any, any, any>): import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../types.js").ActionResult<any, any>>>;

package/dist/runtime/server/handler.js

@@ -0,0 +1,7 @@
+import { defineEventHandler, readBody } from "h3";
+export function createActionHandler(action) {
+  return defineEventHandler(async (event) => {
+    const body = await readBody(event).catch(() => void 0);
+    return action._execute(body, event);
+  });
+}

package/dist/runtime/server/index.d.ts

@@ -0,0 +1,3 @@
+export { createSafeActionClient } from './createSafeActionClient.js';
+export { ActionError, ActionValidationError, returnValidationErrors } from './errors.js';
+export type { SafeAction, SafeActionReference, InferSafeActionInput, InferSafeActionOutput, InferSafeActionServerError, } from '../types.js';

package/dist/runtime/server/index.js

@@ -0,0 +1,2 @@
+export { createSafeActionClient } from "./createSafeActionClient.js";
+export { ActionError, ActionValidationError, returnValidationErrors } from "./errors.js";

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json"
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,103 @@
+import type { H3Event } from 'h3';
+import type { ZodType } from 'zod';
+export interface ActionResult<TOutput, TServerError = string> {
+    data?: TOutput;
+    serverError?: TServerError;
+    validationErrors?: ValidationErrors;
+}
+export type ValidationErrors = Record<string, string[]>;
+/**
+ * A safe action carries phantom types for input/output inference plus
+ * an internal `_execute` method used by the generated Nitro handler.
+ *
+ * On the **client** side the runtime value is a lightweight reference
+ * `{ __safeActionPath: string }` — the types are applied via a generated
+ * declaration file so that `useAction` can infer `TInput` and `TOutput`.
+ */
+export interface SafeAction<TInput = unknown, TOutput = unknown, TServerError = string> {
+    /** phantom field — carries generic types for inference, never set at runtime */
+    readonly _types: {
+        input: TInput;
+        output: TOutput;
+        serverError: TServerError;
+    };
+    /** used by the generated Nitro handler */
+    _execute: (rawInput: unknown, event: H3Event) => Promise<ActionResult<TOutput, TServerError>>;
+}
+export interface SafeActionReference<TInput = unknown, TOutput = unknown, TServerError = string> {
+    readonly __safeActionPath: string;
+    /** phantom field — carries generic types for inference, never set at runtime */
+    readonly _types: {
+        input: TInput;
+        output: TOutput;
+        serverError: TServerError;
+    };
+}
+export interface MiddlewareArgs<TCtx> {
+    ctx: TCtx;
+    clientInput: unknown;
+    metadata: ActionMetadata;
+    event: H3Event;
+    next: <TNewCtx>(opts: {
+        ctx: TNewCtx;
+    }) => Promise<MiddlewareResult<TNewCtx>>;
+}
+export interface MiddlewareResult<TCtx> {
+    ctx: TCtx;
+}
+export type MiddlewareFn<TCtxIn = Record<string, unknown>, TCtxOut = TCtxIn> = (args: MiddlewareArgs<TCtxIn>) => Promise<MiddlewareResult<TCtxOut>>;
+export interface ActionHandlerArgs<TCtx, TInput> {
+    parsedInput: TInput;
+    ctx: TCtx;
+    event: H3Event;
+}
+export type ActionHandler<TCtx, TInput, TOutput> = (args: ActionHandlerArgs<TCtx, TInput>) => Promise<TOutput> | TOutput;
+export type ActionMetadata = Record<string, unknown>;
+export interface SafeActionClientOpts<TServerError = string> {
+    handleServerError?: (error: Error) => TServerError;
+}
+export interface ActionConfig<TServerError = string> {
+    middlewares: MiddlewareFn<any, any>[];
+    inputSchema?: ZodType;
+    outputSchema?: ZodType;
+    metadata: ActionMetadata;
+    handler: ActionHandler<any, any, any>;
+    handleServerError?: (error: Error) => TServerError;
+}
+export type ActionStatus = 'idle' | 'executing' | 'hasSucceeded' | 'hasErrored';
+export type InferSafeActionInput<T> = T extends SafeAction<infer I, any, any> ? I : T extends SafeActionReference<infer I, any, any> ? I : never;
+export type InferSafeActionOutput<T> = T extends SafeAction<any, infer O, any> ? O : T extends SafeActionReference<any, infer O, any> ? O : never;
+export type InferSafeActionServerError<T> = T extends SafeAction<any, any, infer E> ? E : T extends SafeActionReference<any, any, infer E> ? E : string;
+export interface UseActionReturn<TInput, TOutput, TServerError = string> {
+    execute: (input: TInput) => void;
+    executeAsync: (input: TInput) => Promise<ActionResult<TOutput, TServerError>>;
+    data: Readonly<import('vue').Ref<TOutput | undefined>>;
+    serverError: Readonly<import('vue').Ref<TServerError | undefined>>;
+    validationErrors: Readonly<import('vue').Ref<ValidationErrors | undefined>>;
+    status: Readonly<import('vue').Ref<ActionStatus>>;
+    isIdle: import('vue').ComputedRef<boolean>;
+    isExecuting: import('vue').ComputedRef<boolean>;
+    hasSucceeded: import('vue').ComputedRef<boolean>;
+    hasErrored: import('vue').ComputedRef<boolean>;
+    reset: () => void;
+}
+export interface UseActionCallbacks<TInput, TOutput, TServerError = string> {
+    onSuccess?: (args: {
+        data: TOutput;
+        input: TInput;
+    }) => void;
+    onError?: (args: {
+        error: {
+            serverError?: TServerError;
+            validationErrors?: ValidationErrors;
+        };
+        input: TInput;
+    }) => void;
+    onSettled?: (args: {
+        result: ActionResult<TOutput, TServerError>;
+        input: TInput;
+    }) => void;
+    onExecute?: (args: {
+        input: TInput;
+    }) => void;
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "nuxt-safe-action",
+  "version": "0.1.1",
+  "description": "Type-safe and validated server actions for Nuxt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rutbergphilip/nuxt-safe-action.git"
+  },
+  "homepage": "https://github.com/rutbergphilip/nuxt-safe-action",
+  "bugs": {
+    "url": "https://github.com/rutbergphilip/nuxt-safe-action/issues"
+  },
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "server-actions",
+    "type-safe",
+    "validation",
+    "zod",
+    "middleware",
+    "vue"
+  ],
+  "author": "Philip Rutberg",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.3.1",
+    "defu": "^6.1.4"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.1.1",
+    "@nuxt/eslint-config": "^1.14.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.3.1",
+    "@nuxt/test-utils": "^4.0.0",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "nuxt": "^4.3.1",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.18",
+    "vue-tsc": "^3.2.4",
+    "zod": "^3.24.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  }
+}