5. Estado assíncrono e compartilhado
5.1. Exemplo 19: processamento assíncrono
Muitas coisas acontecem “depois”: tiques de um temporizador, teclas digitadas, respostas do servidor. [Angular] baseia-se, para isso, na biblioteca [RxJS] e em seus observables. [React] não tem ferramentas assíncronas próprias: combinamos estado, efeitos e sua limpeza, que guardamos em hooks; e, a partir do [React] 19, [use()] e [<Suspense>] permitem esperar por uma promise.
5.1.1. Uma contagem regressiva
| // =========================================================================
// 19-asynchronous/src/hooks/useCountdown.ts - um timer em um hook
// -------------------------------------------------------------------------
// De start até 0, um valor por segundo. O timer é parado quando a
// contagem chega a 0... ou quando o componente desaparece (limpeza).
// =========================================================================
import { useEffect, useState } from 'react';
export function useCountdown(start: number): number {
const [remaining, setRemaining] = useState(start);
// [remaining > 0]: o efeito é reiniciado quando esta condição muda - ou seja,
// uma vez, quando a contagem chega a 0 (o timer então é parado)
const active = remaining > 0;
useEffect(() => {
if (!active) return;
const timer = setInterval(() => setRemaining((r) => r - 1), 1000);
return () => clearInterval(timer);
}, [active]);
return remaining;
}
|
- linha 11: o contador;
- linha 15: o contador;
- linhas 16–20: o efeito depende somente de [active]: ele é executado na inicialização (o temporizador começa), depois apenas mais uma vez, quando a contagem chega a 0; sua limpeza então interrompe o temporizador, e a nova execução não faz nada. [setRemaining((r) => r - 1)] usa a forma “função” da atualização: o temporizador foi criado uma vez por todas e não vê os novos valores de [remaining]; a função, por sua vez, recebe o valor atual.
5.1.2. Antirrebote
| // =========================================================================
// 19-asynchronous/src/hooks/useDebouncedValue.ts - "debounce"
// -------------------------------------------------------------------------
// Retorna o valor recebido... mas somente quando ele não mudou mais
// por delay milissegundos. Para uma busca enquanto se digita:
// esperamos o usuário fazer uma pausa antes de consultar o servidor,
// em vez de enviar uma requisição por tecla.
// O princípio: cada novo valor reinicia o efeito, cuja limpeza
// cancela o timer do valor anterior.
// =========================================================================
import { useEffect, useState } from 'react';
export function useDebouncedValue<T>(value: T, delay: number): T {
const [debounced, setDebounced] = useState(value);
useEffect(() => {
const timer = setTimeout(() => setDebounced(value), delay);
return () => clearTimeout(timer); // uma tecla antes do fim: cancelar
}, [value, delay]);
return debounced;
}
|
Para a funcionalidade de “busca enquanto se digita”, esperamos que o usuário faça uma pausa antes de consultar o servidor, em vez de enviar uma requisição a cada tecla digitada: isso é o antirrebote ([debounce]). O hook retorna o valor recebido... mas somente quando ele não muda há [delay] milissegundos:
- linhas 17–20: cada novo valor reinicia o efeito, que define um temporizador; e a limpeza da execução anterior CANCELA o temporizador do valor anterior. Assim, apenas o último valor, seguido de uma pausa, chega a [setDebounced].
O hook é genérico ([<T>]): ele funciona para valores de qualquer tipo.
5.1.3. A página
| // =========================================================================
// 19-asynchronous/src/App.tsx - timers, busca enquanto se digita, use()
// -------------------------------------------------------------------------
// Muitas coisas acontecem "depois": os ticks de um timer, as
// teclas digitadas, a resposta de um servidor. O React não tem ferramenta própria
// para assincronia (o Angular usa a biblioteca RxJS): combinamos
// o estado, os efeitos e sua limpeza, guardados em hooks (hooks/),
// e, desde o React 19, use() + <Suspense> para esperar uma promise.
// =========================================================================
import { Suspense, use, useEffect, useState } from 'react';
import { useCountdown } from './hooks/useCountdown';
import { useDebouncedValue } from './hooks/useDebouncedValue';
const DOCTORS = ['Marie PELISSIER', 'Paul TATOU', 'Sophie DUPONT', 'Jacques DURAND', 'Martine PELLETIER'];
// um "servidor" simulado: a resposta chega após um atraso aleatório
function search(text: string): Promise<string[]> {
const found = DOCTORS.filter((m) => m.toLowerCase().includes(text));
return new Promise((resolve) => setTimeout(() => resolve(found), 200 + Math.random() * 600));
}
// 3. uma promise, criada UMA vez (fora do componente): ela resolve após
// um segundo
const messagePromise = new Promise<string>((resolve) =>
setTimeout(() => resolve('three (one second later)'), 1000),
);
// use(promise): o valor da promise. Enquanto ela não está
// resolvida, o componente "suspende" sua exibição: o <Suspense> mais próximo
// exibe no lugar seu conteúdo de espera (fallback)
function Message({ promise }: { promise: Promise<string> }) {
const value = use(promise);
return <p className="mb-0">received: {value}</p>;
}
export default function App() {
const [log, setLog] = useState<string[]>([]);
const trace = (message: string) => setLog((j) => [...j, `${new Date().toLocaleTimeString()} ${message}`]);
// 1. uma contagem regressiva: um hook caseiro
const countdown = useCountdown(20);
// 2. uma busca enquanto se digita
const [input, setInput] = useState('');
const text = useDebouncedValue(input.trim().toLowerCase(), 400); // após 400 ms sem nenhuma tecla
const [results, setResults] = useState<string[]>([]);
useEffect(() => {
if (text.length < 2) {
return; // nenhuma busca (e nenhuma limpeza)
}
// "obsoleta": uma resposta que chega DEPOIS de outra busca ter sido
// iniciada deve ser ignorada (caso contrário uma resposta lenta de uma
// busca antiga sobrescreveria a da nova)
let stale = false;
trace(`search sent: "${text}"`);
search(text).then((found) => {
if (stale) {
trace(`response ignored (stale): "${text}"`);
return;
}
setResults(found);
});
// a limpeza: executada quando text muda (nova busca) ou na remoção
return () => {
stale = true;
};
}, [text]);
// menos de duas letras: nenhum resultado, sejam quais forem as da
// última busca (um valor calculado, não mais um estado)
const displayed = text.length < 2 ? [] : results;
return (
<div className="container py-4" style={{ maxWidth: 720 }}>
<h1 className="h3 mb-3">Example 19 - asynchrony</h1>
<div className="card p-3 mb-3">
<h2 className="h6">A countdown (setInterval in a hook)</h2>
<p className="display-6 mb-0">{countdown}</p>
</div>
<div className="card p-3 mb-3">
<h2 className="h6">A search as you type (debounce, stale responses)</h2>
<input className="form-control mb-2" placeholder="at least two letters: pel, dur..." value={input}
onChange={(e) => setInput(e.target.value)} />
<ul className="mb-0">
{displayed.map((r) => <li key={r}>{r}</li>)}
{displayed.length === 0 && <li className="text-muted">no result</li>}
</ul>
</div>
<div className="card p-3 mb-3">
<h2 className="h6">Waiting for a promise (use and Suspense)</h2>
<Suspense fallback={<p className="text-muted mb-0">waiting...</p>}>
<Message promise={messagePromise} />
</Suspense>
</div>
<h2 className="h6">Log</h2>
<ol className="small">
{log.map((line, i) => <li key={i}>{line}</li>)}
</ol>
</div>
);
}
|
- linhas 18–21: um “servidor” simulado: a resposta chega após um atraso aleatório de 200 a 800 ms;
- linhas 25–27: uma promise, criada UMA ÚNICA vez (fora do componente), resolvida após um segundo;
- linhas 32–35: [use(promise)] retorna o valor de uma promise. Enquanto ela não é resolvida, o componente “suspende” sua exibição: o [<Suspense>] mais próximo (linha 96) exibe seu conteúdo provisório ([fallback]). Quando a promise é resolvida, o [React] chama o componente novamente, e [use] retorna o valor. A promise deve ser criada FORA do componente ou por uma biblioteca que a mantenha em cache: uma promise criada durante a renderização seria recriada a cada chamada, e a espera nunca terminaria;
- linha 42: o hook personalizado;
- linha 46: o texto da busca, após 400 ms sem teclas digitadas;
- linhas 49–69: a busca, reiniciada quando o texto (em cache) muda:
- o problema das respostas obsoletas: você digita “pel”, faz uma pausa, e a busca começa; você digita “du”, faz uma pausa, e uma segunda busca começa. Se a resposta a “pel” chegar DEPOIS da de “du” (os atrasos de rede são imprevisíveis), ela sobrescreveria os resultados corretos;
- A solução (linhas 56–67): uma variável específica de CADA execução do efeito, que é redefinida como [true] quando o texto muda. Qualquer resposta que chegue depois é ignorada;
- linha 73: menos de duas letras: nenhum resultado, independentemente dos resultados da última busca. Este é um valor calculado, não um estado adicional.
Você digita “pel”, espera um instante e depois digita “du”; a resposta a “pel” chega tarde demais e é ignorada:

Escrever o próprio código de tratamento de consultas (em andamento, bem-sucedida, com erro, expirada, já em cache etc.) é trabalhoso. Para se comunicar com um servidor, na prática usa-se uma biblioteca que cuida disso: no Exemplo 24, será o [TanStack Query].
5.2. Exemplo 20: um estado compartilhado
O Exemplo 18 mostra como escrever um store à mão. A biblioteca [Zustand] faz a mesma coisa em poucas linhas e é uma das bibliotecas mais utilizadas para gerenciar estado compartilhado em uma aplicação [React] (junto com o [Redux Toolkit], que é mais completo, mas também mais pesado).
5.2.1. O carrinho de compras
| // =========================================================================
// 20-shared-state/src/stores/cart.ts - um ESTADO COMPARTILHADO, com Zustand
// -------------------------------------------------------------------------
// Um "store" é um estado que vive FORA dos componentes, em UMA única
// cópia, compartilhada por todos os que o leem. O exemplo 18 escreveu
// um à mão (useSyncExternalStore); a biblioteca Zustand faz a
// mesma coisa em poucas linhas:
//
// const useCart = create<Cart>()((set, get) => ({ ...state and actions... }));
//
// create retorna um HOOK. Um componente lê nele o que precisa, por meio de um
// "seletor": useCart((p) => p.items). Ele só é chamado de novo se ESTE
// pedaço do estado mudar. Organização usual:
// - o ESTADO: dados (items);
// - as AÇÕES: funções, as únicas a modificar o estado, por meio de set();
// - os valores calculados: funções (ou seletores).
// O store vive enquanto a aplicação vive: ele sobrevive à remoção de um
// componente... mas não ao recarregamento da página (F5), que reinicia
// a aplicação. (Context + useReducer podem fazer o mesmo trabalho;
// um store tem a vantagem de ser legível também FORA dos componentes.)
// =========================================================================
import { create } from 'zustand';
export interface Item {
label: string;
price: number;
}
interface Cart {
items: Item[];
add: (item: Item) => void;
clear: () => void;
}
export const useCart = create<Cart>()((set) => ({
items: [],
// set(function): recebe o estado atual, retorna o que muda (o resto é mantido)
add: (item) => set((p) => ({ items: [...p.items, item] })),
clear: () => set({ items: [] }),
}));
// seletores reutilizáveis: valores calculados a partir do estado
export const itemCount = (p: Cart) => p.items.length;
export const cartTotal = (p: Cart) => p.items.reduce((s, a) => s + a.price, 0);
|
- linha 23: a função que cria um store;
- linhas 30–34: o tipo do store: o estado ([items]) e as ações ([add], [clear]), que são as únicas que podem modificá-lo;
- linhas 36–41: [create<Cart>()(factory)] cria o store e retorna um hook. A factory recebe [set], que modifica o estado: [set(object)] ou [set((state) => object)]; apenas as alterações são passadas; o resto é preservado. Como com [useState], o próprio estado nunca é modificado: um novo é criado;
- Linhas 44–45: seletores — funções que calculam um valor a partir do estado.
O store existe enquanto a aplicação estiver em execução, em UMA ÚNICA cópia: ele sobrevive à remoção de um componente... mas não a um recarregamento da página (F5), que reinicia a aplicação. Um contexto e o [useReducer] poderiam fazer o mesmo trabalho; um store tem duas vantagens: ele também pode ser lido fora dos componentes (por um guard do roteador, por exemplo), e um componente só é chamado novamente se a parte do estado que ele lê tiver mudado.
5.2.2. Preferências
| // =========================================================================
// 20-shared-state/src/stores/preferences.ts - um estado que sobrevive ao F5
// -------------------------------------------------------------------------
// Para que um dado sobreviva ao recarregamento da página, ou ao fechamento
// do navegador, ele deve ser guardado NO navegador: localStorage (um
// pequeno dicionário chave -> string, específico de cada site).
// O "middleware" persist do Zustand cuida disso: ele relê o localStorage na
// criação do store e o reescreve a cada mudança (chave
// "example20.preferences", valor: o JSON do estado).
// NUNCA guarde dados sensíveis nele (senha, token): qualquer script
// da página pode ler o localStorage.
// =========================================================================
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
interface Preferences {
dark: boolean;
size: number; // tamanho do texto, em px
update: (change: Partial<Pick<Preferences, 'dark' | 'size'>>) => void;
}
export const usePreferences = create<Preferences>()(
persist(
(set) => ({
dark: false,
size: 16,
update: (change) => set(change),
}),
{ name: 'example20.preferences' },
),
);
|
Para que os dados persistam após o recarregamento da página ou o fechamento do navegador, eles devem ser armazenados NO navegador: [localStorage], um pequeno dicionário de chave/string específico de cada site. O “middleware” [persist] do [Zustand] cuida disso (linhas 24–31): ele lê o [localStorage] quando o store é criado e o reescreve a cada alteração, sob a chave [example20.preferences] (linha 30). Dados sensíveis (senhas, tokens) NUNCA são armazenados ali: qualquer script da página pode ler o [localStorage].
5.2.3. Os componentes
| // 20-shared-state/src/components/Shop.tsx - ADICIONA ao carrinho compartilhado
import { useCart, type Item } from '../stores/cart';
const PRODUCTS: Item[] = [
{ label: 'Consultation', price: 30 },
{ label: 'Vaccine', price: 12.5 },
];
export default function Shop() {
// só a ação é lida: Shop não é chamado de novo quando o carrinho muda
const add = useCart((p) => p.add);
return (
<div className="card p-3 h-100">
<h2 className="h6">Shop</h2>
{PRODUCTS.map((p) => (
<button key={p.label} className="btn btn-sm btn-outline-primary mb-2" onClick={() => add(p)}>
+ {p.label} (€{p.price})
</button>
))}
</div>
);
}
|
[useCart((p) => p.add)]: um componente lê o store por meio de um seletor e só é chamado novamente se A parte do estado que ele lê mudar. [Shop] lê apenas a ação [add], que nunca muda: ele nunca é chamado novamente quando o carrinho de compras muda.
| // 20-shared-state/src/components/CartSummary.tsx - LÊ o mesmo carrinho
import { itemCount, cartTotal, useCart } from '../stores/cart';
export default function CartSummary() {
const count = useCart(itemCount);
const total = useCart(cartTotal);
const clear = useCart((p) => p.clear);
return (
<div className="card p-3 h-100">
<h2 className="h6">Cart</h2>
<p className="mb-2">{count} item(s), €{total}</p>
<button className="btn btn-sm btn-outline-danger align-self-start" disabled={count === 0} onClick={clear}>Clear</button>
</div>
);
}
|
[CartSummary] lê o número de itens e o total usando os seletores do store.
| // 20-shared-state/src/components/LocalCounter.tsx - um estado LOCAL, que desaparece com o componente
import { useState } from 'react';
export default function LocalCounter({ title }: { title: string }) {
const [clicks, setClicks] = useState(0);
return (
<div className="card p-3 h-100">
<h2 className="h6">{title}</h2>
<button className="btn btn-sm btn-outline-secondary align-self-start" onClick={() => setClicks(clicks + 1)}>
{clicks} click(s)
</button>
</div>
);
}
|
Um estado LOCAL, que desaparece junto com o componente.
5.2.4. A página
| // =========================================================================
// 20-shared-state/src/App.tsx - três "escopos" de dados no lado do cliente
// -------------------------------------------------------------------------
// Mesma questão do exemplo 23 do curso de NestJS (escopo de aplicação, de requisição,
// de cliente), transposta para o navegador:
// - o estado LOCAL de um componente (LocalCounter) desaparece com ele;
// - o estado de um STORE (o carrinho) é compartilhado por todos os componentes
// e sobrevive à remoção deles - mas não ao F5;
// - o estado guardado no localStorage (as preferências) sobrevive ao F5 e ao
// fechamento do navegador.
// E uma novidade do React 19.2, <Activity mode="hidden">: o conteúdo é
// OCULTADO, mas não removido; seu estado local é mantido.
// Desmarque e marque de novo "mostrar a área", depois recarregue a página: compare.
// =========================================================================
import { Activity, useState } from 'react';
import { usePreferences } from './stores/preferences';
import Shop from './components/Shop';
import CartSummary from './components/CartSummary';
import LocalCounter from './components/LocalCounter';
export default function App() {
const { dark, size, update } = usePreferences();
const [areaVisible, setAreaVisible] = useState(true);
return (
<div className={`min-vh-100 ${dark ? 'bg-dark text-light' : ''}`} style={{ fontSize: size }}>
<div className="container py-4">
<h1 className="h3 mb-3">Example 20 - a shared state</h1>
<div className="d-flex flex-wrap gap-4 mb-3">
<label className="form-check-label">
<input type="checkbox" className="form-check-input" checked={dark}
onChange={(e) => update({ dark: e.target.checked })} /> dark theme
</label>
<label>
text size{' '}
<input type="range" min={12} max={22} value={size}
onChange={(e) => update({ size: e.target.valueAsNumber })} /> {size} px
</label>
<label className="form-check-label">
<input type="checkbox" className="form-check-input" checked={areaVisible}
onChange={(e) => setAreaVisible(e.target.checked)} /> show the area
</label>
</div>
<div className="row g-3 text-body">
{/* removidos: esses componentes desaparecem, com seu estado local */}
{areaVisible && (
<>
<div className="col-md-3"><Shop /></div>
<div className="col-md-3"><CartSummary /></div>
<div className="col-md-3"><LocalCounter title="Local state" /></div>
</>
)}
{/* oculto: o componente permanece na memória, seu estado é mantido */}
<Activity mode={areaVisible ? 'visible' : 'hidden'}>
<div className="col-md-3"><LocalCounter title="Local state, in an Activity" /></div>
</Activity>
</div>
<p className="mt-3 mb-2">Outside the area, a second summary of the SAME cart (it stays there when the area disappears):</p>
<div className="text-body"><CartSummary /></div>
</div>
</div>
);
}
|
- linha 23: sem um seletor, o store inteiro é lido (e o componente é chamado novamente a cada alteração);
- linhas 47–53: o campo é removido quando a caixa de seleção é desmarcada: seus componentes desaparecem, junto com seu estado local;
- linhas 55–57: [<Activity mode="hidden">] ([React] 19.2) oculta seu conteúdo sem removê-lo: o componente permanece na memória, junto com seu estado. Isso é útil para abas ou para uma página que você deixa e à qual volta;
- linha 60: fora da área, um segundo resumo do MESMO carrinho de compras.
Adicione dois itens ao carrinho de compras, dê dois cliques no primeiro contador local e três cliques no de [Activity], desmarque e marque novamente “show the area” e marque “dark theme”:

O carrinho de compras permanece intacto (ele está no store); o primeiro contador voltou a 0 (seu componente foi removido e depois recriado); o de [Activity] manteve seu valor. Quando você recarrega a página (F5), o carrinho de compras fica vazio, mas o tema e o tamanho do texto são preservados ([localStorage]).
Este é o mesmo problema do Exemplo 23 do curso de [NestJS] (escopo da aplicação, consulta, cliente), transposto para o navegador.