Introdução
No fim da parte 2 a gente deixou uma pergunta no ar: e se a lista estivesse num servidor? Aí cada termo vira um HTTP request, e um map não dá conta, porque a gente precisa de um observable de resposta, e também precisa decidir o que acontece quando chega um termo novo enquanto o request anterior ainda está rodando. Neste artigo a gente vai ver switchMap, mergeMap, concatMap e exhaustMap com a mesma entrada, e também o error handling, para a busca não morrer no primeiro problema.
Os exemplos usam RxJS 7 (7.8.x). Todos os trechos de código deste artigo foram executados, e as saídas mostradas são as saídas reais.
O problema: um observable de observables
Digamos que, para cada id, a gente precise buscar um usuário. A busca é assíncrona, então ela devolve um observable, e vamos simular o request com um timer para o exemplo rodar em qualquer lugar:
import { of, timer, map, Observable } from "rxjs";
// fake "request": responds after 100 ms
const fetchUser = (id) => timer(100).pipe(map(() => `user ${id}`));
of(1, 2)
.pipe(map((id) => fetchUser(id)))
.subscribe((value) => console.log("got an Observable?", value instanceof Observable));
got an Observable? true
got an Observable? true
O map fez o que mandamos, e trocou cada id por um observable, só que a gente queria o usuário. Isso tem nome: um observable de ordem superior (higher-order observable), um observable que emite observables.
A tentação é fazer um subscribe dentro do outro:
import { of, timer, map } from "rxjs";
const fetchUser = (id) => timer(100).pipe(map(() => `user ${id}`));
// it works, but it's the anti-pattern the part 1 already called out
of(1, 2).subscribe((id) => {
fetchUser(id).subscribe((user) => console.log(user));
});
user 1
user 2
Funciona, mas a subscription de dentro fica "solta". Nesse exemplo, duas coisas podem acontecer: ninguém cancela o inner, e/ou a gente perde o controle da ordem e do error num lugar só. Foi o bug do cronômetro da parte 1, em que cada clique em Iniciar criava mais um timer.
Queremos um operator que receba o observable de dentro (o inner), faça o subscribe por nós e jogue os valores dele no stream de fora (o outer). Ele existe em quatro sabores, e a diferença é uma só: o que fazer quando chega um valor novo enquanto o inner anterior ainda está rodando?
Os quatro operators, com a mesma entrada
O cenário: três "cliques" a, b e c, com 100 ms entre eles, e para cada clique um "request" que demora 250 ms. Ou seja, quando b chega, o request de a ainda não terminou. A gente roda os quatro operators, um depois do outro, e anota o que saiu e em que momento:
import { Observable, timer, map, toArray, lastValueFrom, switchMap, mergeMap, concatMap, exhaustMap } from "rxjs";
// clicks at 0, 100 and 200 ms
const clicks = () =>
new Observable((subscriber) => {
const ids = [
setTimeout(() => subscriber.next("a"), 0),
setTimeout(() => subscriber.next("b"), 100),
setTimeout(() => subscriber.next("c"), 200),
setTimeout(() => subscriber.complete(), 201),
];
return () => ids.forEach(clearTimeout);
});
// each click fires a 250 ms "request"
const request = (click) => timer(250).pipe(map(() => click + "!"));
async function run(name, operator) {
const start = Date.now();
const stamp = (v) => `${v}@${Math.round((Date.now() - start) / 50) * 50}ms`;
const output = await lastValueFrom(clicks().pipe(operator(request), map(stamp), toArray()));
console.log(name.padEnd(11), output.join(" "));
}
await run("switchMap", switchMap);
await run("mergeMap", mergeMap);
await run("concatMap", concatMap);
await run("exhaustMap", exhaustMap);
switchMap c!@450ms
mergeMap a!@250ms b!@350ms c!@450ms
concatMap a!@250ms b!@500ms c!@750ms
exhaustMap a!@250ms
O
toArray()junta tudo num array quando o stream completa, e olastValueFrom(da parte 1) nos deixa usarawait. Só estão aí para a saída caber numa linha.
Em marble (cada - ≈ 50 ms):
clicks: a-b-c|
switchMap: ---------c!| a e b foram cancelados
mergeMap: -----a!-b!-c!| tudo em paralelo
concatMap: -----a!----b!----c!| um de cada vez, em fila
exhaustMap: -----a!| b e c ignorados: a ainda estava rodando
Agora cada um com calma.
switchMap: cancela o anterior
Quando chega um valor novo, o switchMap faz o unsubscribe do inner atual e troca para o novo, e só o request de c chegou ao fim. Nesse unsubscribe roda o teardown (parte 1): se o inner for um HTTP request feito do jeito certo, ele é abortado, e não só ignorado.
É o operator certo quando só a resposta mais recente importa: search-as-you-type, autocomplete, e também o "Iniciar" do cronômetro.
mergeMap: em paralelo
O mergeMap faz subscribe em todos os inners e repassa os valores conforme chegam. Nada é cancelado, e a saída segue a ordem em que as respostas chegam, não a dos pedidos, e aqui coincidiu porque todas demoram o mesmo.
Use quando as operações são independentes e todas precisam acontecer, como enviar vários arquivos. O segundo argumento limita a concorrência: mergeMap(fn, 3) roda no máximo 3 de cada vez.
concatMap: em fila
O concatMap espera o inner atual completar antes de começar o próximo. Os pedidos chegam e entram numa fila, e b só começou em 250 ms e c em 500 ms.
Use quando a ordem importa: salvar alterações em sequência, e operações que dependem da anterior. Cuidado: se os valores chegam mais rápido do que os inners terminam, a fila só cresce.
exhaustMap: ignora o novo
O exhaustMap é o contrário do switchMap: enquanto um inner está rodando, ele ignora os valores novos. b e c chegaram com a em andamento e foram descartados.
Use quando um novo pedido no meio do caminho é provavelmente um engano: o clássico duplo clique no botão "Salvar" ou "Pagar".
Resumo em tabela
| Operator | Chega um valor novo com o anterior rodando... | Caso típico |
|---|---|---|
switchMap |
cancela o anterior e troca | search-as-you-type |
mergeMap |
roda os dois em paralelo | uploads independentes |
concatMap |
enfileira e roda depois | salvar em ordem |
exhaustMap |
ignora o novo | evitar duplo clique em Salvar |
Na dúvida entre eles para buscar dados, comece pelo switchMap. Para escrever dados (POST, PUT), pense duas vezes antes de usá-lo: cancelar um request no navegador não garante que o servidor não o processou.
Quando dá erro
Lembra da parte 1? error é terminal: depois dele, o stream acabou. Isso tem uma consequência séria para streams de longa duração, como a nossa busca:
import { of, map } from "rxjs";
of(1, 2, 3)
.pipe(
map((n) => {
if (n === 2) throw new Error("2 went wrong");
return n * 10;
})
)
.subscribe({
next: (v) => console.log("next:", v),
error: (e) => console.log("error:", e.message),
complete: () => console.log("complete (does not appear)"),
});
next: 10
error: 2 went wrong
O 3 nunca foi processado, e numa busca um erro de rede deixa o campo mudo para sempre.
catchError: fora ou dentro?
O catchError intercepta o error e devolve um observable substituto, e a posição dele faz toda a diferença. Vamos simular três termos de busca, em que o do meio faz o "request" falhar:
import { Observable, of, timer, map, switchMap, catchError, throwError } from "rxjs";
const terms = () =>
new Observable((subscriber) => {
const ids = ["rx", "error", "rxjs"].map((t, i) => setTimeout(() => subscriber.next(t), i * 100));
const end = setTimeout(() => subscriber.complete(), 400);
return () => [...ids, end].forEach(clearTimeout);
});
const search = (term) =>
term === "error"
? throwError(() => new Error("network failure"))
: timer(50).pipe(map(() => `results for "${term}"`));
console.log("--- catchError OUTSIDE switchMap");
terms()
.pipe(
switchMap((term) => search(term)),
catchError((e) => of(`failed: ${e.message}`))
)
.subscribe({ next: (v) => console.log(v), complete: () => console.log("complete") });
setTimeout(() => {
console.log("--- catchError INSIDE switchMap");
terms()
.pipe(switchMap((term) => search(term).pipe(catchError((e) => of(`failed: ${e.message}`)))))
.subscribe({ next: (v) => console.log(v), complete: () => console.log("complete") });
}, 600);
--- catchError OUTSIDE switchMap
results for "rx"
failed: network failure
complete
--- catchError INSIDE switchMap
results for "rx"
failed: network failure
results for "rxjs"
complete
Nesse exemplo, duas coisas podem acontecer, e a diferença é só a posição do catchError:
-
Fora: o error atravessou o
switchMape matou o stream de fora. OcatchErrortrocou tudo por umof(...), que emitiu e completou, e o termo"rxjs"nunca foi buscado. - Dentro: o error morreu junto com o inner daquela busca. O stream de fora nem ficou sabendo, e a busca seguinte funcionou.
Regra prática: trate o error dentro do inner sempre que o stream de fora precisa continuar vivo.
O
throwError(() => error)cria um observable que só emite um error. Passe sempre uma função que cria o error; a formathrowError(error)está depreciada no RxJS 7.
retry
Alguns erros são passageiros: a rede piscou, o servidor engasgou. O retry refaz o subscribe na source quando ela falha, e como o observable é cold, refazer o subscribe significa rodar de novo, fazer outro request:
import { Observable, retry } from "rxjs";
let attempts = 0;
const flaky$ = new Observable((subscriber) => {
attempts++;
console.log("attempt", attempts);
if (attempts < 3) subscriber.error(new Error("server hiccup"));
else {
subscriber.next("finally!");
subscriber.complete();
}
});
flaky$.pipe(retry({ count: 2, delay: 100 })).subscribe({
next: (v) => console.log("next:", v),
error: (e) => console.log("error:", e.message),
complete: () => console.log("complete"),
});
attempt 1
attempt 2
attempt 3
next: finally!
complete
count: 2 significa até 2 novas tentativas além da primeira, e delay: 100 espera 100 ms entre elas. Se a terceira também falhasse, o error seguiria para o error.
O delay também aceita uma função (error, retryCount) que devolve um observable: se ele emitir, tenta de novo, e se ele der error, desiste. Vamos usar isso no projeto para não insistir em erros que não vão se resolver sozinhos.
finalize
O finalize(fn) roda quando o stream termina por qualquer motivo: complete, error ou unsubscribe. É o lugar certo para desligar um "loading...":
import { timer, map, finalize } from "rxjs";
const request = (name) =>
timer(100).pipe(
map(() => `${name}: data arrived`),
finalize(() => console.log(`${name}: loading off`))
);
console.log("1st: loading on");
request("1st").subscribe((v) => console.log(v));
setTimeout(() => {
console.log("2nd: loading on");
const sub = request("2nd").subscribe((v) => console.log(v));
setTimeout(() => sub.unsubscribe(), 50); // cancelled before the response
}, 200);
1st: loading on
1st: data arrived
1st: loading off
2nd: loading on
2nd: loading off
O segundo "request" foi cancelado antes de responder, e mesmo assim o finalize rodou. Se a gente desligasse o loading no next, ele ficaria ligado para sempre, e é exatamente isso que acontece com uma busca que o switchMap cancela.
Projeto: buscando repositórios no GitHub
Vamos evoluir a busca da parte 2: em vez de filtrar uma lista local, cada termo vai virar um request para a API de busca do GitHub. Ela é pública e não precisa de chave, mas sem autenticação o limite da busca é de 10 requests por minuto. Veja os limites da API. É um bom exemplo para um artigo sobre debounce e errors: se você digitar demais, vai ver um error de verdade.
O que queremos:
- Debounce e
distinctUntilChanged, como na parte 2. - Termos com menos de 2 letras não buscam nada.
- Uma busca nova cancela a anterior (o request é abortado de verdade).
- Mostrar "loading", o resultado ou o error.
- Tentar de novo em erros passageiros (rede, 5xx), mas não em erros que não vão mudar sozinhos (403 ou 429 de limite estourado, 422 de busca inválida).
- Depois de um error, a próxima digitação funciona normalmente.
O HTML é quase o mesmo:
<body>
<h1>Search repositories</h1>
<input id="search" placeholder="Type at least 2 letters..." autocomplete="off" />
<p id="status"></p>
<ul id="results"></ul>
<script type="module" src="/src/github.ts"></script>
</body>
Para o request, usamos o fromFetch, de "rxjs/fetch": um fetch com um AbortController interno, que aborta o request no unsubscribe. A opção selector deixa a leitura do corpo (response.json()) cancelável também, como recomenda a documentação do fromFetch.
O src/github.ts:
import {
fromEvent, map, debounceTime, distinctUntilChanged, switchMap, catchError,
retry, startWith, throwError, timer, of, type Observable,
} from "rxjs";
import { fromFetch } from "rxjs/fetch";
interface Repo {
full_name: string;
html_url: string;
stargazers_count: number;
}
interface SearchResponse {
total_count: number;
items: Repo[];
}
type State =
| { type: "initial" }
| { type: "loading"; term: string }
| { type: "success"; term: string; total: number; repos: Repo[] }
| { type: "error"; term: string; message: string };
class HttpError extends Error {
status: number;
constructor(status: number) {
super(`HTTP ${status}`);
this.status = status;
}
}
function searchRepos(term: string): Observable<SearchResponse> {
const url = `https://api.github.com/search/repositories?q=${encodeURIComponent(term)}&per_page=5`;
return fromFetch(url, {
selector: (response) =>
response.ok
? (response.json() as Promise<SearchResponse>)
: throwError(() => new HttpError(response.status)),
}).pipe(
retry({
count: 2,
delay: (error, attempt) =>
error instanceof HttpError && error.status < 500
? throwError(() => error) // 4xx: no point retrying
: timer(1000 * attempt), // network or 5xx: wait 1 s, then 2 s
})
);
}
const input = document.querySelector<HTMLInputElement>("#search")!;
const status = document.querySelector<HTMLElement>("#status")!;
const list = document.querySelector<HTMLUListElement>("#results")!;
const state$: Observable<State> = fromEvent(input, "input").pipe(
map(() => input.value.trim()),
debounceTime(400),
distinctUntilChanged(),
switchMap((term): Observable<State> => {
if (term.length < 2) return of({ type: "initial" });
return searchRepos(term).pipe(
map((r): State => ({ type: "success", term, total: r.total_count, repos: r.items })),
startWith<State>({ type: "loading", term }),
catchError((error: Error) => of<State>({ type: "error", term, message: error.message }))
);
}),
startWith<State>({ type: "initial" })
);
state$.subscribe((state) => {
list.innerHTML = "";
switch (state.type) {
case "initial":
status.textContent = "Type at least 2 letters.";
break;
case "loading":
status.textContent = `Searching "${state.term}"...`;
break;
case "error":
status.textContent = `Error searching "${state.term}": ${state.message}`;
break;
case "success":
status.textContent = `${state.total} repo(s) for "${state.term}"`;
for (const repo of state.repos) {
const item = document.createElement("li");
const link = document.createElement("a");
link.href = repo.html_url;
link.textContent = `${repo.full_name} (${repo.stargazers_count} stars)`;
item.append(link);
list.append(item);
}
}
});
Nesse ponto o código faz várias coisas ao mesmo tempo, e vale olhar cada pedaço.
O tipo State: em vez de espalhar if (loading) pelo código, o stream emite um state completo por vez e o subscribe só desenha. Essa ideia volta com tudo na parte 4.
searchRepos: devolve um observable cold, e nada acontece até o switchMap fazer o subscribe. O selector lê o JSON quando a resposta é 2xx e, quando não é, transforma o status num error com throwError. Um 403 não rejeita o fetch: para o fetch, uma resposta HTTP é uma resposta, então somos nós que decidimos que aquilo é um error.
retry com delay em função: para erros de rede (o fetch rejeita) e 5xx, a gente espera 1 s, depois 2 s, e tenta de novo, no máximo 2 vezes. Para 4xx, inclusive o 403/429 de limite estourado, devolvemos um throwError e o retry desiste na hora: não adianta martelar uma API que acabou de dizer "chega".
switchMap: cada termo novo aborta o request anterior, e uma resposta antiga nunca sobrescreve uma nova, que é a famosa condição de corrida do autocomplete.
startWith dentro do inner: cada busca começa emitindo loading e depois emite success. Como está dentro do switchMap, o "loading" é por busca.
catchError dentro do inner: a lição da seção anterior. O error vira um state error, o stream de fora continua vivo, e a próxima digitação busca normalmente.
startWith no final: o state da tela antes de qualquer digitação.
Com o servidor lento, se alguém digita "rx", espera o debounce e digita "rxjs" antes de a primeira resposta chegar, a tela passa por Searching "rx"... e Searching "rxjs"..., e termina com a lista de "rxjs". O request de "rx" foi abortado, e no DevTools ele aparece como cancelado.
term (after debounce): --r------j---------
searchRepos("rx"): --[------X X = aborted by switchMap
searchRepos("rxjs"): ---------[-------(d|)
state$: i-c------c-------s--
r = "rx", j = "rxjs", d = response; i = initial, c = loading, s = success
Exercício: o clássico arrastar e soltar é um ótimo treino de
switchMap: para cadamousedown, troque para osmousemovedo documento até omouseup(takeUntil, da parte 2). Tente escrever antes de procurar a resposta.
Resumo
- Quando cada valor vira uma operação assíncrona, a gente tem um observable de observables. Não faça subscribe aninhado: use um operator de mapeamento de ordem superior.
-
switchMapcancela o anterior,mergeMaproda em paralelo,concatMapenfileira,exhaustMapignora os novos enquanto está ocupado. -
erroré terminal. Coloque ocatchErrordentro do inner para o stream de fora sobreviver. -
retry({ count, delay })refaz o subscribe; comdelayem função, a gente escolhe quais errors merecem nova tentativa. -
finalizeroda em complete, error e unsubscribe: é o lugar do "desligar loading". -
fromFetch+switchMapabortam requests de verdade.
Na parte 4 a gente vai falar de um problema que ficou escondido aqui: se dois pedaços da tela fizerem subscribe no mesmo state$, são dois requests por termo. É aí que entram os Subjects e o multicast.
Links para leitura:
Top comments (0)