Ações Assíncronas

Q: Como funciona o padrão de atualização otimista no Zustand?

Use get() para capturar o estado atual antes da operação assíncrona. Aplique a mudança otimista imediatamente com set. Se a chamada assíncrona falhar, reverta chamando set com o snapshot.

Q: Uma ação assíncrona pode retornar um valor para o chamador?

Sim. Ações assíncronas podem retornar Promise. O componente chamador pode usar await no resultado, por exemplo, para navegar após uma criação bem-sucedida.

Q: Armadilha: O que acontece quando duas ações assíncronas compartilham um único booleano isLoading?

Elas entram em conflito. Se fetchProducts e fetchProduct ambos definem isLoading, um pode sobrescrever o estado de carregamento do outro. Use chaves de carregamento por ação (por exemplo, loading: Record) para evitar isso.

Q: Armadilha: Como lidar com condições de corrida com chamadas assíncronas repetidas rapidamente?

Use um AbortController para cancelar a requisição anterior em andamento. Verifique AbortError no bloco catch e ignore-o.

Q: O que acontece se set for chamado após o componente que disparou a ação ser desmontado?

A chamada set ainda atualiza o store -- stores Zustand vivem fora do React. Não há erro, mas a limpeza do efeito do componente desmontado foi perdida.

Q: Como tipificar uma ação assíncrona em TypeScript?

Use Promise para ações "fire-and-forget" e Promise ao retornar dados.

Q: Como tipificar o erro em um bloco catch com TypeScript?

Blocos catch recebem unknown em TypeScript. Faça o cast para Error explicitamente: (err as Error).message. Alternativamente, use um type guard para um narrowing mais seguro.

Receita

Defina funções assíncronas como ações de store. Use set para gerenciar estados de carregamento e erro junto com a operação assíncrona. Nenhuma middleware especial é necessária.

import { create } from "zustand";
 
interface User {
  id: string;
  name: string;
  email: string;
}
 
interface UserStore {
  users: User[];
  isLoading: boolean;
  error: string | null;
  fetchUsers: () => Promise<void>;
}
 
export const useUserStore = create<UserStore>((set) => ({
  users: [],
  isLoading: false,
  error: null,
 
  fetchUsers: async () => {
    set({ isLoading: true, error: null });
    try {
      const res = await fetch("/api/users");
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      const users = await res.json();
      set({ users, isLoading: false });
    } catch (err) {
      set({ error: (err as Error).message, isLoading: false });
    }
  },
}));

Exemplo Funcional

// stores/product-store.ts
import { create } from "zustand";
 
interface Product {
  id: string;
  name: string;
  price: number;
  stock: number;
}
 
interface ProductStore {
  products: Product[];
  selectedProduct: Product | null;
  isLoading: boolean;
  error: string | null;
 
  fetchProducts: () => Promise<void>;
  fetchProduct: (id: string) => Promise<void>;
  createProduct: (input: Omit<Product, "id">) => Promise<Product>;
  updateStock: (id: string, delta: number) => Promise<void>;
}
 
export const useProductStore = create<ProductStore>((set, get) => ({
  products: [],
  selectedProduct: null,
  isLoading: false,
  error: null,
 
  fetchProducts: async () => {
    set({ isLoading: true, error: null });
    try {
      const res = await fetch("/api/products");
      const products = await res.json();
      set({ products, isLoading: false });
    } catch (err) {
      set({ error: (err as Error).message, isLoading: false });
    }
  },
 
  fetchProduct: async (id) => {
    set({ isLoading: true, error: null });
    try {
      const res = await fetch(`/api/products/${id}`);
      const product = await res.json();
      set({ selectedProduct: product, isLoading: false });
    } catch (err) {
      set({ error: (err as Error).message, isLoading: false });
    }
  },
 
  createProduct: async (input) => {
    set({ isLoading: true, error: null });
    try {
      const res = await fetch("/api/products", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(input),
      });
      const newProduct = await res.json();
      set((state) => ({
        products: [...state.products, newProduct],
        isLoading: false,
      }));
      return newProduct;
    } catch (err) {
      set({ error: (err as Error).message, isLoading: false });
      throw err;
    }
  },
 
  updateStock: async (id, delta) => {
    // Atualização otimista
    const previousProducts = get().products;
    set((state) => ({
      products: state.products.map((p) =>
        p.id === id ? { ...p, stock: p.stock + delta } : p
      ),
    }));
 
    try {
      await fetch(`/api/products/${id}/stock`, {
        method: "PATCH",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ delta }),
      });
    } catch (err) {
      // Reversão em caso de falha
      set({ products: previousProducts, error: (err as Error).message });
    }
  },
}));

// components/product-list.tsx
"use client";
 
import { useEffect } from "react";
import { useProductStore } from "@/stores/product-store";
 
export function ProductList() {
  const products = useProductStore((s) => s.products);
  const isLoading = useProductStore((s) => s.isLoading);
  const error = useProductStore((s) => s.error);
  const fetchProducts = useProductStore((s) => s.fetchProducts);
 
  useEffect(() => {
    fetchProducts();
  }, [fetchProducts]);
 
  if (isLoading) return <div>Carregando produtos...</div>;
  if (error) return <div>Erro: {error}</div>;
 
  return (
    <div>
      {products.map((p) => (
        <div key={p.id}>
          <h3>{p.name}</h3>
          <p>${p.price} - {p.stock} em estoque</p>
        </div>
      ))}
    </div>
  );
}

Análise Detalhada

Como Funciona

As ações do Zustand são funções simples. Não há distinção entre ações síncronas e assíncronas no nível do store.
set pode ser chamado múltiplas vezes em uma ação assíncrona: uma para definir o carregamento, outra para definir os dados ou o erro.
Cada chamada de set dispara uma atualização de estado síncrona. O React 18+ agrupa renders, então chamadas sequenciais rápidas de set podem ser agrupadas.
Atualizações otimistas usam get() para capturar o estado atual antes da operação assíncrona, e depois revertem em caso de falha.
Ações assíncronas podem retornar valores, permitindo que o chamador reaja ao resultado (por exemplo, navegar após a criação).

Variações

Helper genérico de ação assíncrona:

function asyncAction<T>(
  set: any,
  fn: () => Promise<T>,
  onSuccess: (data: T) => Partial<any>
) {
  set({ isLoading: true, error: null });
  return fn()
    .then((data) => {
      set({ ...onSuccess(data), isLoading: false });
      return data;
    })
    .catch((err) => {
      set({ error: (err as Error).message, isLoading: false });
      throw err;
    });
}
 
// Uso
const useStore = create((set) => ({
  items: [],
  isLoading: false,
  error: null,
  fetchItems: () =>
    asyncAction(set, () => fetch("/api/items").then((r) => r.json()), (items) => ({ items })),
}));

Estados de carregamento por ação:

interface Store {
  data: Record<string, unknown>;
  loading: Record<string, boolean>;
  setLoading: (key: string, value: boolean) => void;
}
 
const useStore = create<Store>((set) => ({
  data: {},
  loading: {},
  setLoading: (key, value) =>
    set((s) => ({ loading: { ...s.loading, [key]: value } })),
}));

Controlador de abortagem para cancelamento:

const useStore = create((set) => {
  let controller: AbortController | null = null;
 
  return {
    data: null,
    fetchData: async () => {
      controller?.abort();
      controller = new AbortController();
 
      try {
        const res = await fetch("/api/data", { signal: controller.signal });
        set({ data: await res.json() });
      } catch (err) {
        if ((err as Error).name !== "AbortError") {
          set({ error: (err as Error).message });
        }
      }
    },
  };
});

Notas de TypeScript

Ações assíncronas retornam Promise<void> ou Promise<T> e devem ser tipificadas de acordo.
A redução de tipos de erro com (err as Error).message é comum, já que blocos catch recebem unknown.

interface AsyncState {
  isLoading: boolean;
  error: string | null;
}
 
interface WithAsync<T> extends AsyncState {
  data: T | null;
  fetch: () => Promise<void>;
}

Armadilhas

Um único booleano isLoading compartilhado entre múltiplas ações assíncronas pode conflitar. Se fetchProducts e fetchProduct usarem o mesmo isLoading, um pode sobrescrever o outro.
Condições de corrida ocorrem quando a mesma ação é chamada múltiplas vezes rapidamente. A última chamada vence, mas chamadas intermediárias de set ainda são disparadas. Use controladores de abortagem ou ignore respostas obsoletas.
set dentro de um try/catch com código assíncrono não reverte automaticamente em caso de erro. Você precisa lidar com a lógica de reversão manualmente.
Se uma ação assíncrona lançar um erro após o componente ter sido desmontado, a chamada set ainda atualizará o store (sem erro, mas o efeito do componente antigo foi limpo).
Zustand não rastreia promises pendentes. Se você precisar desduplicar requisições em andamento, implemente essa lógica você mesmo.

Alternativas

Abordagem	Prós	Contras
Ações assíncronas inline	Simples, sem middleware	Gerenciamento manual de estado de carregamento/erro
SWR ou React Query para fetching	Cache automático, dedup, retry	Separado do store Zustand
Redux Toolkit createAsyncThunk	Ciclo de vida estruturado (pending, fulfilled, rejected)	Ecossistema Redux necessário
Middleware assíncrono customizado	Reutilizável entre ações	Complexidade adicionada

FAQs

Você precisa de middleware especial para usar ações assíncronas no Zustand?

Não. As ações do Zustand são funções simples; não há distinção entre síncronas e assíncronas no nível do store.
Apenas defina uma função async que chama set em diferentes pontos (carregamento, sucesso, erro).

Como você gerencia estados de carregamento e erro para uma ação assíncrona?

fetchUsers: async () => {
  set({ isLoading: true, error: null });
  try {
    const res = await fetch("/api/users");
    const users = await res.json();
    set({ users, isLoading: false });
  } catch (err) {
    set({ error: (err as Error).message, isLoading: false });
  }
},

Como funciona o padrão de atualização otimista no Zustand?

Use get() para capturar o estado atual antes da operação assíncrona.
Aplique a mudança otimista imediatamente com set.
Se a chamada assíncrona falhar, reverta chamando set com o snapshot.

Uma ação assíncrona pode retornar um valor para o chamador?

Sim. Ações assíncronas podem retornar Promise<T>.
O componente chamador pode usar await no resultado, por exemplo, para navegar após uma criação bem-sucedida.

Armadilha: O que acontece quando duas ações assíncronas compartilham um único booleano `isLoading`?

Elas entram em conflito. Se fetchProducts e fetchProduct ambos definem isLoading, um pode sobrescrever o estado de carregamento do outro.
Use chaves de carregamento por ação (por exemplo, loading: Record<string, boolean>) para evitar isso.

Armadilha: Como lidar com condições de corrida com chamadas assíncronas repetidas rapidamente?

Use um AbortController para cancelar a requisição anterior em andamento.
Verifique AbortError no bloco catch e ignore-o.

controller?.abort();
controller = new AbortController();
const res = await fetch(url, { signal: controller.signal });

O `set` dentro de um bloco `catch` reverte automaticamente chamadas `set` anteriores?

Não. Zustand não reverte automaticamente.
Você deve implementar a lógica de reversão manualmente usando um snapshot do estado tirado antes da operação assíncrona.

O que acontece se `set` for chamado após o componente que disparou a ação ser desmontado?

A chamada set ainda atualiza o store -- stores Zustand vivem fora do React.
Não há erro, mas a limpeza do efeito do componente desmontado foi perdida.

Como tipificar uma ação assíncrona em TypeScript?

interface UserStore {
  users: User[];
  isLoading: boolean;
  error: string | null;
  fetchUsers: () => Promise<void>;
  createUser: (input: Omit<User, "id">) => Promise<User>;
}

Use Promise<void> para ações "fire-and-forget" e Promise<T> ao retornar dados.

Como tipificar o erro em um bloco `catch` com TypeScript?

Blocos catch recebem unknown em TypeScript.
Faça o cast para Error explicitamente: (err as Error).message.
Alternativamente, use um type guard para um narrowing mais seguro.

O Zustand desduplica requisições em andamento automaticamente?

Não. Zustand não rastreia promises pendentes.
Se você precisar de desduplicação, implemente-a você mesmo (por exemplo, com um flag ou AbortController).

Como um helper genérico de ação assíncrona reduz o boilerplate?

Ele encapsula o padrão set({ isLoading: true }) / try / catch / set({ isLoading: false }) em uma função reutilizável.
Cada ação só precisa fornecer a lógica de fetch e um mapper de sucesso.

Links Relacionados

Receita

Defina funções assíncronas como ações de store. Use set para gerenciar estados de carregamento e erro junto com a operação assíncrona. Nenhuma middleware especial é necessária.

import { create } from "zustand";
 
interface User {
  id: string;
  name: string;
  email: string;
}
 
interface UserStore {
  users: User[];
  isLoading: boolean;
  error: string | null;
  fetchUsers: () => Promise<void>;
}
 
export const useUserStore = create<UserStore>((set) => ({
  users: [],
  isLoading: false,
  error: null,
 
  fetchUsers: async () => {
    set({ isLoading: true, error: null });
    try {
      const res = await fetch("/api/users");
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      const users = await res.json();
      set({ users, isLoading: false });
    } catch (err) {
      set({ error: (err as Error).message, isLoading: false });
    }
  },
}));

Exemplo Funcional

// stores/product-store.ts
import { create } from "zustand";
 
interface Product {
  id: string;
  name: string;
  price: number;
  stock: number;
}
 
interface ProductStore {
  products: Product[];
  selectedProduct: Product | null;
  isLoading: boolean;
  error: string | null;
 
  fetchProducts: () => Promise<void>;
  fetchProduct: (id: string) => Promise<void>;
  createProduct: (input: Omit<Product, "id">) => Promise<Product>;
  updateStock: (id: string, delta: number) => Promise<void>;
}
 
export const useProductStore = create<ProductStore>((set, get) => ({
  products: [],
  selectedProduct: null,
  isLoading: false,
  error: null,
 
  fetchProducts: async () => {
    set({ isLoading: true, error: null });
    try {
      const res = await fetch("/api/products");
      const products = await res.json();
      set({ products, isLoading: false });
    } catch (err) {
      set({ error: (err as Error).message, isLoading: false });
    }
  },
 
  fetchProduct: async (id) => {
    set({ isLoading: true, error: null });
    try {
      const res = await fetch(`/api/products/${id}`);
      const product = await res.json();
      set({ selectedProduct: product, isLoading: false });
    } catch (err) {
      set({ error: (err as Error).message, isLoading: false });
    }
  },
 
  createProduct: async (input) => {
    set({ isLoading: true, error: null });
    try {
      const res = await fetch("/api/products", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(input),
      });
      const newProduct = await res.json();
      set((state) => ({
        products: [...state.products, newProduct],
        isLoading: false,
      }));
      return newProduct;
    } catch (err) {
      set({ error: (err as Error).message, isLoading: false });
      throw err;
    }
  },
 
  updateStock: async (id, delta) => {
    // Atualização otimista
    const previousProducts = get().products;
    set((state) => ({
      products: state.products.map((p) =>
        p.id === id ? { ...p, stock: p.stock + delta } : p
      ),
    }));
 
    try {
      await fetch(`/api/products/${id}/stock`, {
        method: "PATCH",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ delta }),
      });
    } catch (err) {
      // Reversão em caso de falha
      set({ products: previousProducts, error: (err as Error).message });
    }
  },
}));

// components/product-list.tsx
"use client";
 
import { useEffect } from "react";
import { useProductStore } from "@/stores/product-store";
 
export function ProductList() {
  const products = useProductStore((s) => s.products);
  const isLoading = useProductStore((s) => s.isLoading);
  const error = useProductStore((s) => s.error);
  const fetchProducts = useProductStore((s) => s.fetchProducts);
 
  useEffect(() => {
    fetchProducts();
  }, [fetchProducts]);
 
  if (isLoading) return <div>Carregando produtos...</div>;
  if (error) return <div>Erro: {error}</div>;
 
  return (
    <div>
      {products.map((p) => (
        <div key={p.id}>
          <h3>{p.name}</h3>
          <p>${p.price} - {p.stock} em estoque</p>
        </div>
      ))}
    </div>
  );
}

Análise Detalhada

Como Funciona

As ações do Zustand são funções simples. Não há distinção entre ações síncronas e assíncronas no nível do store.
set pode ser chamado múltiplas vezes em uma ação assíncrona: uma para definir o carregamento, outra para definir os dados ou o erro.
Cada chamada de set dispara uma atualização de estado síncrona. O React 18+ agrupa renders, então chamadas sequenciais rápidas de set podem ser agrupadas.
Atualizações otimistas usam get() para capturar o estado atual antes da operação assíncrona, e depois revertem em caso de falha.
Ações assíncronas podem retornar valores, permitindo que o chamador reaja ao resultado (por exemplo, navegar após a criação).

Variações

Helper genérico de ação assíncrona:

function asyncAction<T>(
  set: any,
  fn: () => Promise<T>,
  onSuccess: (data: T) => Partial<any>
) {
  set({ isLoading: true, error: null });
  return fn()
    .then((data) => {
      set({ ...onSuccess(data), isLoading: false });
      return data;
    })
    .catch((err) => {
      set({ error: (err as Error).message, isLoading: false });
      throw err;
    });
}
 
// Uso
const useStore = create((set) => ({
  items: [],
  isLoading: false,
  error: null,
  fetchItems: () =>
    asyncAction(set, () => fetch("/api/items").then((r) => r.json()), (items) => ({ items })),
}));

Estados de carregamento por ação:

interface Store {
  data: Record<string, unknown>;
  loading: Record<string, boolean>;
  setLoading: (key: string, value: boolean) => void;
}
 
const useStore = create<Store>((set) => ({
  data: {},
  loading: {},
  setLoading: (key, value) =>
    set((s) => ({ loading: { ...s.loading, [key]: value } })),
}));

Controlador de abortagem para cancelamento:

const useStore = create((set) => {
  let controller: AbortController | null = null;
 
  return {
    data: null,
    fetchData: async () => {
      controller?.abort();
      controller = new AbortController();
 
      try {
        const res = await fetch("/api/data", { signal: controller.signal });
        set({ data: await res.json() });
      } catch (err) {
        if ((err as Error).name !== "AbortError") {
          set({ error: (err as Error).message });
        }
      }
    },
  };
});

Notas de TypeScript

Ações assíncronas retornam Promise<void> ou Promise<T> e devem ser tipificadas de acordo.
A redução de tipos de erro com (err as Error).message é comum, já que blocos catch recebem unknown.

interface AsyncState {
  isLoading: boolean;
  error: string | null;
}
 
interface WithAsync<T> extends AsyncState {
  data: T | null;
  fetch: () => Promise<void>;
}

Armadilhas

Um único booleano isLoading compartilhado entre múltiplas ações assíncronas pode conflitar. Se fetchProducts e fetchProduct usarem o mesmo isLoading, um pode sobrescrever o outro.
Condições de corrida ocorrem quando a mesma ação é chamada múltiplas vezes rapidamente. A última chamada vence, mas chamadas intermediárias de set ainda são disparadas. Use controladores de abortagem ou ignore respostas obsoletas.
set dentro de um try/catch com código assíncrono não reverte automaticamente em caso de erro. Você precisa lidar com a lógica de reversão manualmente.
Se uma ação assíncrona lançar um erro após o componente ter sido desmontado, a chamada set ainda atualizará o store (sem erro, mas o efeito do componente antigo foi limpo).
Zustand não rastreia promises pendentes. Se você precisar desduplicar requisições em andamento, implemente essa lógica você mesmo.

Alternativas

Abordagem	Prós	Contras
Ações assíncronas inline	Simples, sem middleware	Gerenciamento manual de estado de carregamento/erro
SWR ou React Query para fetching	Cache automático, dedup, retry	Separado do store Zustand
Redux Toolkit createAsyncThunk	Ciclo de vida estruturado (pending, fulfilled, rejected)	Ecossistema Redux necessário
Middleware assíncrono customizado	Reutilizável entre ações	Complexidade adicionada

FAQs

Você precisa de middleware especial para usar ações assíncronas no Zustand?

Não. As ações do Zustand são funções simples; não há distinção entre síncronas e assíncronas no nível do store.
Apenas defina uma função async que chama set em diferentes pontos (carregamento, sucesso, erro).

Como você gerencia estados de carregamento e erro para uma ação assíncrona?

fetchUsers: async () => {
  set({ isLoading: true, error: null });
  try {
    const res = await fetch("/api/users");
    const users = await res.json();
    set({ users, isLoading: false });
  } catch (err) {
    set({ error: (err as Error).message, isLoading: false });
  }
},

Como funciona o padrão de atualização otimista no Zustand?

Use get() para capturar o estado atual antes da operação assíncrona.
Aplique a mudança otimista imediatamente com set.
Se a chamada assíncrona falhar, reverta chamando set com o snapshot.

Uma ação assíncrona pode retornar um valor para o chamador?

Sim. Ações assíncronas podem retornar Promise<T>.
O componente chamador pode usar await no resultado, por exemplo, para navegar após uma criação bem-sucedida.

Armadilha: O que acontece quando duas ações assíncronas compartilham um único booleano `isLoading`?

Elas entram em conflito. Se fetchProducts e fetchProduct ambos definem isLoading, um pode sobrescrever o estado de carregamento do outro.
Use chaves de carregamento por ação (por exemplo, loading: Record<string, boolean>) para evitar isso.

Armadilha: Como lidar com condições de corrida com chamadas assíncronas repetidas rapidamente?

Use um AbortController para cancelar a requisição anterior em andamento.
Verifique AbortError no bloco catch e ignore-o.

controller?.abort();
controller = new AbortController();
const res = await fetch(url, { signal: controller.signal });

O `set` dentro de um bloco `catch` reverte automaticamente chamadas `set` anteriores?

Não. Zustand não reverte automaticamente.
Você deve implementar a lógica de reversão manualmente usando um snapshot do estado tirado antes da operação assíncrona.

O que acontece se `set` for chamado após o componente que disparou a ação ser desmontado?

A chamada set ainda atualiza o store -- stores Zustand vivem fora do React.
Não há erro, mas a limpeza do efeito do componente desmontado foi perdida.

Como tipificar uma ação assíncrona em TypeScript?

interface UserStore {
  users: User[];
  isLoading: boolean;
  error: string | null;
  fetchUsers: () => Promise<void>;
  createUser: (input: Omit<User, "id">) => Promise<User>;
}

Use Promise<void> para ações "fire-and-forget" e Promise<T> ao retornar dados.

Como tipificar o erro em um bloco `catch` com TypeScript?

Blocos catch recebem unknown em TypeScript.
Faça o cast para Error explicitamente: (err as Error).message.
Alternativamente, use um type guard para um narrowing mais seguro.

O Zustand desduplica requisições em andamento automaticamente?

Não. Zustand não rastreia promises pendentes.
Se você precisar de desduplicação, implemente-a você mesmo (por exemplo, com um flag ou AbortController).

Como um helper genérico de ação assíncrona reduz o boilerplate?

Ele encapsula o padrão set({ isLoading: true }) / try / catch / set({ isLoading: false }) em uma função reutilizável.
Cada ação só precisa fornecer a lógica de fetch e um mapper de sucesso.

Ações Assíncronas

Buscar na documentação

Ações Assíncronas