Tipar Server Actions no Next.js: Guia

// app/actions/auth.ts
"use server";

// Tipo do retorno padronizado
type ActionResult<T = void> = 
  | { success: true; data: T }
  | { success: false; error: string };

// Tipo dos dados do form
type LoginData = {
  email: string;
  password: string;
};

export async function loginAction(
  formData: FormData
): Promise<ActionResult<{ token: string }>> {
  // Extrai e valida campos
  const email = formData.get("email") as string | null;
  const password = formData.get("password") as string | null;

  if (!email || !password) {
    return { success: false, error: "Email e senha obrigatórios" };
  }

  try {
    const token = await authenticate(email, password);
    return { success: true, data: { token } };
  } catch (err) {
    return { success: false, error: "Credenciais inválidas" };
  }
}

// app/actions/contact.ts
"use server";

import { z } from "zod";

// Schema Zod gera o tipo automaticamente
const contactSchema = z.object({
  name: z.string().min(2, "Nome muito curto"),
  email: z.string().email("Email inválido"),
  message: z.string().min(10, "Mensagem muito curta"),
});

// Tipo inferido do schema
type ContactData = z.infer<typeof contactSchema>;

type ActionResult = 
  | { success: true; message: string }
  | { success: false; errors: Record<string, string[]> };

export async function submitContact(
  formData: FormData
): Promise<ActionResult> {
  const raw = {
    name: formData.get("name"),
    email: formData.get("email"),
    message: formData.get("message"),
  };

  const result = contactSchema.safeParse(raw);

  if (!result.success) {
    // Erros tipados por campo
    return {
      success: false,
      errors: result.error.flatten().fieldErrors as Record<string, string[]>,
    };
  }

  // result.data tem tipo ContactData
  await saveContact(result.data);
  return { success: true, message: "Mensagem enviada" };
}

// app/components/ContactForm.tsx
"use client";

import { useActionState } from "react";
import { submitContact } from "@/app/actions/contact";

// Tipo do state da action
type FormState = {
  success: boolean;
  message?: string;
  errors?: Record<string, string[]>;
} | null;

export function ContactForm() {
  // useActionState com tipos genéricos
  const [state, formAction, isPending] = useActionState<FormState, FormData>(
    async (prevState: FormState, formData: FormData) => {
      const result = await submitContact(formData);
      return result;
    },
    null // estado inicial tipado como FormState
  );

  return (
    <form action={formAction}>
      <input name="name" disabled={isPending} />
      <input name="email" type="email" disabled={isPending} />
      <textarea name="message" disabled={isPending} />

      {state?.errors?.email && (
        <p className="text-red-500">{state.errors.email[0]}</p>
      )}

      <button type="submit" disabled={isPending}>
        {isPending ? "Enviando..." : "Enviar"}
      </button>
    </form>
  );
}

// app/actions/posts.ts
"use server";

import { revalidatePath, revalidateTag } from "next/cache";
import { redirect } from "next/navigation";

type CreatePostInput = {
  title: string;
  content: string;
  published: boolean;
};

type PostResult = {
  id: string;
  title: string;
  slug: string;
};

export async function createPost(
  formData: FormData
): Promise<{ success: true; data: PostResult } | { success: false; error: string }> {
  const title = formData.get("title") as string;
  const content = formData.get("content") as string;
  const published = formData.get("published") === "on";

  if (!title || !content) {
    return { success: false, error: "Título e conteúdo obrigatórios" };
  }

  const post = await db.post.create({
    data: { title, content, published },
  });

  // Revalida o cache da página de listagem
  revalidatePath("/blog");
  revalidateTag("posts");

  // Redireciona pro post criado
  redirect(`/blog/${post.slug}`);
}

// app/actions/favorites.ts
"use server";

import { revalidatePath } from "next/cache";

// Action que recebe argumentos tipados diretamente
export async function toggleFavorite(
  productId: string,
  userId: string
): Promise<{ isFavorite: boolean }> {
  const existing = await db.favorite.findUnique({
    where: { userId_productId: { userId, productId } },
  });

  if (existing) {
    await db.favorite.delete({ where: { id: existing.id } });
    revalidatePath("/favorites");
    return { isFavorite: false };
  }

  await db.favorite.create({ data: { userId, productId } });
  revalidatePath("/favorites");
  return { isFavorite: true };
}

// No componente client:
// const result = await toggleFavorite(productId, userId);
// result.isFavorite é boolean tipado