Promises Paralelas e Promise.all

Q: O que acontece se uma promise rejeitar em Promise.all?

Promise.all rejeita imediatamente com esse erro Todos os outros resultados são perdidos, mesmo de promises que já tiveram sucesso Use Promise.allSettled quando algumas buscas não forem críticas

Q: Por que chamadas await sequenciais criam um waterfall mesmo que cada promise comece imediatamente?

Promises começam a executar quando criadas, mas await bloqueia a próxima linha const a = await fetchA(); const b = await fetchB(); espera A terminar antes de criar B Para rodar em paralelo, crie todas as promises primeiro, depois await Promise.all([...])

Q: Qual a diferença entre Promise.race e Promise.any?

Promise.race resolve ou rejeita com a primeira promise a resolver/rejeitar (seja cumprir ou rejeitar) Promise.any resolve com a primeira promise a cumprir, ignorando rejeições Promise.any só rejeita se todas as promises rejeitarem (com um AggregateError)

Q: Por que o exemplo do mundo real converte bigint para Number() antes de retornar JSON?

O Postgres retorna bigint para agregações SUM bigint não pode ser serializado diretamente para JSON (gera TypeError) Number() o converte para um número regular; use .toString() se o valor puder exceder Number.MAX_SAFE_INTEGER

Busque múltiplas fontes de dados em paralelo para eliminar waterfalls e acelerar a renderização do servidor.

Receita

Referência rápida para padrões de busca de dados paralelos.

// Promise.all - falha rapidamente se qualquer promise rejeitar
const [users, posts, stats] = await Promise.all([
  getUsers(),
  getPosts(),
  getStats(),
]);
 
// Promise.allSettled - nunca rejeita, retorna status para cada uma
const results = await Promise.allSettled([
  getUsers(),
  getPosts(),
  getStats(),
]);
 
// Promise.race - resolve/rejeita com a primeira a resolver/rejeitar
const fastest = await Promise.race([
  fetchFromPrimary(),
  fetchFromFallback(),
]);
 
// Promise.any - resolve com a primeira a cumprir (ignora rejeições)
const firstSuccess = await Promise.any([
  fetchFromCDN1(),
  fetchFromCDN2(),
]);

Quando usar isso: Você tem múltiplas buscas de dados independentes em um Server Component e quer que elas rodem simultaneamente em vez de sequencialmente.

Exemplo Funcional

// app/dashboard/page.tsx
import { Suspense } from "react";
 
async function getUser(id: string) {
  const res = await fetch(`https://api.example.com/users/${id}`);
  return res.json();
}
 
async function getOrders(userId: string) {
  const res = await fetch(`https://api.example.com/orders?userId=${userId}`);
  return res.json();
}
 
async function getNotifications(userId: string) {
  const res = await fetch(`https://api.example.com/notifications?userId=${userId}`);
  return res.json();
}
 
export default async function DashboardPage() {
  const userId = "user-123";
 
  // Todas as três buscas começam ao mesmo tempo
  const [user, orders, notifications] = await Promise.all([
    getUser(userId),
    getOrders(userId),
    getNotifications(userId),
  ]);
 
  return (
    <div>
      <h1>Bem-vindo, {user.name}</h1>
      <p>{notifications.length} notificações não lidas</p>
      <h2>Pedidos Recentes</h2>
      <ul>
        {orders.map((order: { id: string; total: number }) => (
          <li key={order.id}>${order.total}</li>
        ))}
      </ul>
    </div>
  );
}

O que isso demonstra:

Três chamadas de API independentes executam em paralelo
O tempo total é igual ao da chamada mais lenta (não a soma das três)
Desestruturação limpa dos resultados
Server Component sem JavaScript do lado do cliente

Mergulho Profundo

Como Funciona

Promise.all recebe um array de promises e retorna uma única promise que resolve para um array de resultados
Todas as promises começam a executar imediatamente quando criadas (não quando aguardadas)
A promise retornada resolve quando TODAS as promises cumprem
Se QUALQUER promise rejeitar, Promise.all rejeita imediatamente com esse erro
O fetch do Next.js em Server Components é automaticamente deduped e cacheado

Parâmetros e Valores de Retorno

Método	Resolve Quando	Rejeita Quando	Retorna
`Promise.all`	Todas cumprem	Qualquer uma rejeita	Array de valores
`Promise.allSettled`	Todas resolvem/rejeitam	Nunca	Array de `{status, value}` ou `{status, reason}`
`Promise.race`	A primeira a resolver/rejeitar	A primeira a rejeitar	Valor único
`Promise.any`	A primeira a cumprir	Todas rejeitam	Valor único

Variações

Promise.allSettled para falhas parciais:

export default async function DashboardPage() {
  const results = await Promise.allSettled([
    getUser("user-123"),
    getOrders("user-123"),
    getRecommendations("user-123"), // Pode falhar, não é crítico
  ]);
 
  const user = results[0].status === "fulfilled" ? results[0].value : null;
  const orders = results[1].status === "fulfilled" ? results[1].value : [];
  const recs = results[2].status === "fulfilled" ? results[2].value : [];
 
  return (
    <div>
      {user && <h1>{user.name}</h1>}
      <OrderList orders={orders} />
      {recs.length > 0 && <Recommendations items={recs} />}
    </div>
  );
}

Buscas paralelas com Suspense (streaming independente):

// Cada seção carrega independentemente - não precisa de Promise.all
export default function DashboardPage() {
  return (
    <div>
      <Suspense fallback={<Skeleton />}>
        <UserProfile id="user-123" />
      </Suspense>
      <Suspense fallback={<Skeleton />}>
        <OrderList userId="user-123" />
      </Suspense>
      <Suspense fallback={<Skeleton />}>
        <Notifications userId="user-123" />
      </Suspense>
    </div>
  );
}
 
// Cada componente busca seus próprios dados
async function UserProfile({ id }: { id: string }) {
  const user = await getUser(id);
  return <h1>{user.name}</h1>;
}

Buscas dependentes (waterfall está correto):

// Quando a busca B depende da busca A, sequencial está correto
export default async function UserPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const user = await getUser(id);
 
  // Estas dependem dos dados do usuário, mas são independentes entre si
  const [posts, followers] = await Promise.all([
    getPostsByAuthor(user.id),
    getFollowers(user.id),
  ]);
 
  return <Profile user={user} posts={posts} followers={followers} />;
}

Função auxiliar para buscas paralelas tipadas:

async function fetchParallel<T extends readonly Promise<unknown>[]>(
  ...promises: T
): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }> {
  return Promise.all(promises) as Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }>;
}
 
// Uso - resultados totalmente tipados
const [user, posts] = await fetchParallel(
  getUser("123"),    // Tipo User
  getPosts("123"),   // Tipo Post[]
);

Notas de TypeScript

// Promise.all preserva tipos de tupla
const results = await Promise.all([
  getUser("1"),      // retorna Promise<User>
  getPosts("1"),     // retorna Promise<Post[]>
  getCount(),        // retorna Promise<number>
]);
// results é [User, Post[], number]
 
// Tipo de resultado de Promise.allSettled
type SettledResult<T> =
  | { status: "fulfilled"; value: T }
  | { status: "rejected"; reason: unknown };
 
// Type guard para resultados resolvidos/rejeitados
function isFulfilled<T>(
  result: PromiseSettledResult<T>
): result is PromiseFulfilledResult<T> {
  return result.status === "fulfilled";
}
 
const results = await Promise.allSettled([getUsers(), getPosts()]);
const successfulResults = results.filter(isFulfilled).map(r => r.value);

Armadilhas

Promise.all falha rapidamente. Se uma promise rejeitar, você perde TODOS os resultados, mesmo daqueles que tiveram sucesso. Correção: Use Promise.allSettled quando algumas buscas não forem críticas, ou envolva promises individuais em try/catch.
Promises começam imediatamente, não quando aguardadas. const p = fetch(url) inicia a busca imediatamente. await apenas espera pelo resultado. Se você criar promises em um loop, todas elas começarão em paralelo. Correção: Geralmente é o que você quer, mas esteja ciente para APIs com limites de taxa.
Rejeição não tratada em Promise.all. Se você esquecer de capturar a rejeição de Promise.all, ela se torna uma rejeição de promise não tratada e pode travar seu servidor. Correção: Sempre envolva em try/catch ou use Promise.allSettled.
Não é realmente paralelo. Se você acidentalmente await cada busca antes de iniciar a próxima, elas rodam sequencialmente. Correção: Crie todas as promises primeiro, depois await elas juntas.

// Ruim: sequencial (cada await bloqueia)
const users = await getUsers();
const posts = await getPosts();
 
// Bom: paralelo (ambas começam imediatamente)
const [users, posts] = await Promise.all([getUsers(), getPosts()]);

Muitas requisições paralelas. Disparar 50 buscas em paralelo pode sobrecarregar APIs ou atingir limites de taxa. Correção: Use um limitador de concorrência como p-limit ou agrupe requisições.

Alternativas

Alternativa	Use Quando	Não Use Quando
`await` Sequencial	Buscas dependem umas das outras (B precisa do resultado de A)	Buscas independentes (cria waterfalls)
Limites de Suspense	Cada seção deve fazer streaming independentemente	Você precisa de todos os dados antes de renderizar qualquer coisa
`Promise.allSettled`	Algumas buscas são opcionais ou podem falhar	Todos os dados são necessários para renderizar
`Promise.race`	Você quer a resposta mais rápida de múltiplas fontes	Você precisa de todos os resultados
`p-limit`	Você precisa limitar a concorrência (APIs com limite de taxa)	Poucas buscas paralelas

Exemplo do Mundo Real

De uma aplicação SaaS em produção Next.js 15 / React 19 (SystemsArchitect.io).

// Exemplo de produção: API de documentos para administradores com 6 consultas Prisma paralelas
// Arquivo: app/api/admin/documents/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { prisma } from '@/lib/prisma';
 
export async function GET(request: NextRequest) {
  const { searchParams } = request.nextUrl;
  const page = parseInt(searchParams.get('page') ?? '1', 10);
  const limit = parseInt(searchParams.get('limit') ?? '20', 10);
  const offset = (page - 1) * limit;
 
  const [
    documents,
    totalCount,
    categoryCounts,
    recentlyUpdated,
    publishedCount,
    storageUsed,
  ] = await Promise.all([
    // Consulta principal com truque de paginação: busca limit+1 para detectar se há mais páginas
    prisma.document.findMany({
      take: limit + 1,
      skip: offset,
      orderBy: { updatedAt: 'desc' },
      include: { author: { select: { name: true, email: true } } },
    }),
 
    prisma.document.count(),
 
    prisma.document.groupBy({
      by: ['categoryId'],
      _count: { id: true },
    }),
 
    prisma.document.findMany({
      take: 5,
      orderBy: { updatedAt: 'desc' },
      where: { updatedAt: { gte: new Date(Date.now() - 24 * 60 * 60 * 1000) } },
    }),
 
    prisma.document.count({ where: { status: 'PUBLISHED' } }),
 
    // Consulta bruta específica do Postgres para agregação
    prisma.$queryRaw<[{ total: bigint }]>`
      SELECT COALESCE(SUM("file_size"), 0) as total FROM "Document"
    `,
  ]);
 
  const hasMore = documents.length > limit;
  const paginatedDocs = hasMore ? documents.slice(0, limit) : documents;
  const totalStorage = Number(storageUsed[0]?.total ?? 0n);
 
  return NextResponse.json({
    documents: paginatedDocs,
    hasMore,
    totalCount,
    categoryCounts,
    recentlyUpdated,
    publishedCount,
    totalStorage,
  });
}

O que isso demonstra em produção:

O truque de paginação take: limit + 1 evita uma consulta de contagem separada apenas para saber se há uma próxima página. Se você receber mais linhas do que limit, há mais páginas. Corte a linha extra antes de retornar.
$queryRaw é usado para a agregação COALESCE(SUM(...)) específica do Postgres porque a API de agregação do Prisma não suporta COALESCE. O tipo de retorno deve ser anotado explicitamente como [{ total: bigint }] porque o Postgres retorna bigint para SUM.
O bigint do Postgres não pode ser serializado diretamente para JSON. Number(storageUsed[0]?.total ?? 0n) o converte para um número regular. Para valores que podem exceder Number.MAX_SAFE_INTEGER, use .toString() em vez disso.
Seis consultas paralelas executam simultaneamente via Promise.all. O tempo total é a duração da consulta mais lenta, não a soma de todas as seis. Em um cold start, isso reduziu o endpoint de cerca de 1200ms (sequencial) para menos de 300ms.
O dimensionamento do pool de conexões é importante com consultas paralelas. Seis consultas Prisma simultâneas consomem seis conexões do pool. O tamanho padrão do pool do Prisma é num_cpus * 2 + 1. Em plataformas serverless, mantenha a contagem de consultas paralelas dentro dos limites do pool ou aumente o tamanho do pool na string de conexão.

FAQs

O que acontece se uma promise rejeitar em `Promise.all`?

Promise.all rejeita imediatamente com esse erro
Todos os outros resultados são perdidos, mesmo de promises que já tiveram sucesso
Use Promise.allSettled quando algumas buscas não forem críticas

Quando você deve usar `Promise.allSettled` em vez de `Promise.all`?

Quando algumas buscas são opcionais ou não críticas (por exemplo, recomendações)
Quando você quer dados parciais em vez de uma falha completa
Cada resultado tem um status de "fulfilled" ou "rejected" para que você possa lidar com cada um individualmente

Por que chamadas `await` sequenciais criam um waterfall mesmo que cada promise comece imediatamente?

Promises começam a executar quando criadas, mas await bloqueia a próxima linha
const a = await fetchA(); const b = await fetchB(); espera A terminar antes de criar B
Para rodar em paralelo, crie todas as promises primeiro, depois await Promise.all([...])

// Ruim: sequencial
const users = await getUsers();
const posts = await getPosts();
 
// Bom: paralelo
const [users, posts] = await Promise.all([getUsers(), getPosts()]);

Qual a diferença entre `Promise.race` e `Promise.any`?

Promise.race resolve ou rejeita com a primeira promise a resolver/rejeitar (seja cumprir ou rejeitar)
Promise.any resolve com a primeira promise a cumprir, ignorando rejeições
Promise.any só rejeita se todas as promises rejeitarem (com um AggregateError)

Como `Promise.all` preserva os tipos de tupla do TypeScript?

const results = await Promise.all([
  getUser("1"),   // Promise<User>
  getPosts("1"),  // Promise<Post[]>
  getCount(),     // Promise<number>
]);
// results é [User, Post[], number] -- totalmente tipado

Como escrever um type guard para resultados de `Promise.allSettled`?

function isFulfilled<T>(
  result: PromiseSettledResult<T>
): result is PromiseFulfilledResult<T> {
  return result.status === "fulfilled";
}
 
const results = await Promise.allSettled([getUsers(), getPosts()]);
const successes = results.filter(isFulfilled).map((r) => r.value);

Quando um waterfall sequencial está realmente correto?

Quando a busca B depende do resultado da busca A (por exemplo, você precisa do ID do usuário antes de buscar seus posts)
Combine: busque a dependência primeiro, depois use Promise.all para sub-buscas independentes

const user = await getUser(id);
const [posts, followers] = await Promise.all([
  getPostsByAuthor(user.id),
  getFollowers(user.id),
]);

O que acontece se você disparar muitas requisições paralelas de uma vez?

Você pode sobrecarregar APIs ou atingir limites de taxa
Pools de conexão de banco de dados podem ser esgotados (por exemplo, o tamanho padrão do pool do Prisma é num_cpus * 2 + 1)
Use um limitador de concorrência como p-limit para agrupar requisições

Como funciona o truque de paginação `take: limit + 1` do exemplo do mundo real?

Busque uma linha extra além do tamanho da sua página
Se você receber mais linhas do que limit, há mais páginas (hasMore = true)
Corte a linha extra antes de retornar ao cliente
Isso evita uma consulta COUNT(*) separada apenas para verificar a próxima página

Você pode usar limites de Suspense em vez de `Promise.all` para carregamento de dados paralelo?

Sim. Cada Server Component assíncrono em seu próprio limite <Suspense> busca independentemente
Diferente de Promise.all, as seções renderizam à medida que resolvem em vez de esperar que todas terminem
Use Suspense quando as seções devem fazer streaming independentemente; use Promise.all quando você precisa de todos os dados antes de renderizar

Por que o exemplo do mundo real converte `bigint` para `Number()` antes de retornar JSON?

O Postgres retorna bigint para agregações SUM
bigint não pode ser serializado diretamente para JSON (gera TypeError)
Number() o converte para um número regular; use .toString() se o valor puder exceder Number.MAX_SAFE_INTEGER

O que é a função auxiliar `fetchParallel` e por que ela é útil?

async function fetchParallel<T extends readonly Promise<unknown>[]>(
  ...promises: T
): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }> {
  return Promise.all(promises) as any;
}

Ela preserva os tipos individuais para cada promise na tupla
Fornece resultados desestruturados totalmente tipados sem anotações de tipo manuais

Relacionados

Busca de Dados - buscar em Server Components
Streaming - streaming paralelo baseado em Suspense
Cache - deduplicação e cache de requisições
Generators - iteração assíncrona para grandes conjuntos de dados

Receita

Referência rápida para padrões de busca de dados paralelos.

// Promise.all - falha rapidamente se qualquer promise rejeitar
const [users, posts, stats] = await Promise.all([
  getUsers(),
  getPosts(),
  getStats(),
]);
 
// Promise.allSettled - nunca rejeita, retorna status para cada uma
const results = await Promise.allSettled([
  getUsers(),
  getPosts(),
  getStats(),
]);
 
// Promise.race - resolve/rejeita com a primeira a resolver/rejeitar
const fastest = await Promise.race([
  fetchFromPrimary(),
  fetchFromFallback(),
]);
 
// Promise.any - resolve com a primeira a cumprir (ignora rejeições)
const firstSuccess = await Promise.any([
  fetchFromCDN1(),
  fetchFromCDN2(),
]);

Quando usar isso: Você tem múltiplas buscas de dados independentes em um Server Component e quer que elas rodem simultaneamente em vez de sequencialmente.

Exemplo Funcional

// app/dashboard/page.tsx
import { Suspense } from "react";
 
async function getUser(id: string) {
  const res = await fetch(`https://api.example.com/users/${id}`);
  return res.json();
}
 
async function getOrders(userId: string) {
  const res = await fetch(`https://api.example.com/orders?userId=${userId}`);
  return res.json();
}
 
async function getNotifications(userId: string) {
  const res = await fetch(`https://api.example.com/notifications?userId=${userId}`);
  return res.json();
}
 
export default async function DashboardPage() {
  const userId = "user-123";
 
  // Todas as três buscas começam ao mesmo tempo
  const [user, orders, notifications] = await Promise.all([
    getUser(userId),
    getOrders(userId),
    getNotifications(userId),
  ]);
 
  return (
    <div>
      <h1>Bem-vindo, {user.name}</h1>
      <p>{notifications.length} notificações não lidas</p>
      <h2>Pedidos Recentes</h2>
      <ul>
        {orders.map((order: { id: string; total: number }) => (
          <li key={order.id}>${order.total}</li>
        ))}
      </ul>
    </div>
  );
}

O que isso demonstra:

Três chamadas de API independentes executam em paralelo
O tempo total é igual ao da chamada mais lenta (não a soma das três)
Desestruturação limpa dos resultados
Server Component sem JavaScript do lado do cliente

Mergulho Profundo

Como Funciona

Promise.all recebe um array de promises e retorna uma única promise que resolve para um array de resultados
Todas as promises começam a executar imediatamente quando criadas (não quando aguardadas)
A promise retornada resolve quando TODAS as promises cumprem
Se QUALQUER promise rejeitar, Promise.all rejeita imediatamente com esse erro
O fetch do Next.js em Server Components é automaticamente deduped e cacheado

Parâmetros e Valores de Retorno

Método	Resolve Quando	Rejeita Quando	Retorna
`Promise.all`	Todas cumprem	Qualquer uma rejeita	Array de valores
`Promise.allSettled`	Todas resolvem/rejeitam	Nunca	Array de `{status, value}` ou `{status, reason}`
`Promise.race`	A primeira a resolver/rejeitar	A primeira a rejeitar	Valor único
`Promise.any`	A primeira a cumprir	Todas rejeitam	Valor único

Variações

Promise.allSettled para falhas parciais:

export default async function DashboardPage() {
  const results = await Promise.allSettled([
    getUser("user-123"),
    getOrders("user-123"),
    getRecommendations("user-123"), // Pode falhar, não é crítico
  ]);
 
  const user = results[0].status === "fulfilled" ? results[0].value : null;
  const orders = results[1].status === "fulfilled" ? results[1].value : [];
  const recs = results[2].status === "fulfilled" ? results[2].value : [];
 
  return (
    <div>
      {user && <h1>{user.name}</h1>}
      <OrderList orders={orders} />
      {recs.length > 0 && <Recommendations items={recs} />}
    </div>
  );
}

Buscas paralelas com Suspense (streaming independente):

// Cada seção carrega independentemente - não precisa de Promise.all
export default function DashboardPage() {
  return (
    <div>
      <Suspense fallback={<Skeleton />}>
        <UserProfile id="user-123" />
      </Suspense>
      <Suspense fallback={<Skeleton />}>
        <OrderList userId="user-123" />
      </Suspense>
      <Suspense fallback={<Skeleton />}>
        <Notifications userId="user-123" />
      </Suspense>
    </div>
  );
}
 
// Cada componente busca seus próprios dados
async function UserProfile({ id }: { id: string }) {
  const user = await getUser(id);
  return <h1>{user.name}</h1>;
}

Buscas dependentes (waterfall está correto):

// Quando a busca B depende da busca A, sequencial está correto
export default async function UserPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const user = await getUser(id);
 
  // Estas dependem dos dados do usuário, mas são independentes entre si
  const [posts, followers] = await Promise.all([
    getPostsByAuthor(user.id),
    getFollowers(user.id),
  ]);
 
  return <Profile user={user} posts={posts} followers={followers} />;
}

Função auxiliar para buscas paralelas tipadas:

async function fetchParallel<T extends readonly Promise<unknown>[]>(
  ...promises: T
): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }> {
  return Promise.all(promises) as Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }>;
}
 
// Uso - resultados totalmente tipados
const [user, posts] = await fetchParallel(
  getUser("123"),    // Tipo User
  getPosts("123"),   // Tipo Post[]
);

Notas de TypeScript

// Promise.all preserva tipos de tupla
const results = await Promise.all([
  getUser("1"),      // retorna Promise<User>
  getPosts("1"),     // retorna Promise<Post[]>
  getCount(),        // retorna Promise<number>
]);
// results é [User, Post[], number]
 
// Tipo de resultado de Promise.allSettled
type SettledResult<T> =
  | { status: "fulfilled"; value: T }
  | { status: "rejected"; reason: unknown };
 
// Type guard para resultados resolvidos/rejeitados
function isFulfilled<T>(
  result: PromiseSettledResult<T>
): result is PromiseFulfilledResult<T> {
  return result.status === "fulfilled";
}
 
const results = await Promise.allSettled([getUsers(), getPosts()]);
const successfulResults = results.filter(isFulfilled).map(r => r.value);

Armadilhas

Promise.all falha rapidamente. Se uma promise rejeitar, você perde TODOS os resultados, mesmo daqueles que tiveram sucesso. Correção: Use Promise.allSettled quando algumas buscas não forem críticas, ou envolva promises individuais em try/catch.
Promises começam imediatamente, não quando aguardadas. const p = fetch(url) inicia a busca imediatamente. await apenas espera pelo resultado. Se você criar promises em um loop, todas elas começarão em paralelo. Correção: Geralmente é o que você quer, mas esteja ciente para APIs com limites de taxa.
Rejeição não tratada em Promise.all. Se você esquecer de capturar a rejeição de Promise.all, ela se torna uma rejeição de promise não tratada e pode travar seu servidor. Correção: Sempre envolva em try/catch ou use Promise.allSettled.
Não é realmente paralelo. Se você acidentalmente await cada busca antes de iniciar a próxima, elas rodam sequencialmente. Correção: Crie todas as promises primeiro, depois await elas juntas.

// Ruim: sequencial (cada await bloqueia)
const users = await getUsers();
const posts = await getPosts();
 
// Bom: paralelo (ambas começam imediatamente)
const [users, posts] = await Promise.all([getUsers(), getPosts()]);

Muitas requisições paralelas. Disparar 50 buscas em paralelo pode sobrecarregar APIs ou atingir limites de taxa. Correção: Use um limitador de concorrência como p-limit ou agrupe requisições.

Alternativas

Alternativa	Use Quando	Não Use Quando
`await` Sequencial	Buscas dependem umas das outras (B precisa do resultado de A)	Buscas independentes (cria waterfalls)
Limites de Suspense	Cada seção deve fazer streaming independentemente	Você precisa de todos os dados antes de renderizar qualquer coisa
`Promise.allSettled`	Algumas buscas são opcionais ou podem falhar	Todos os dados são necessários para renderizar
`Promise.race`	Você quer a resposta mais rápida de múltiplas fontes	Você precisa de todos os resultados
`p-limit`	Você precisa limitar a concorrência (APIs com limite de taxa)	Poucas buscas paralelas

Exemplo do Mundo Real

De uma aplicação SaaS em produção Next.js 15 / React 19 (SystemsArchitect.io).

// Exemplo de produção: API de documentos para administradores com 6 consultas Prisma paralelas
// Arquivo: app/api/admin/documents/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { prisma } from '@/lib/prisma';
 
export async function GET(request: NextRequest) {
  const { searchParams } = request.nextUrl;
  const page = parseInt(searchParams.get('page') ?? '1', 10);
  const limit = parseInt(searchParams.get('limit') ?? '20', 10);
  const offset = (page - 1) * limit;
 
  const [
    documents,
    totalCount,
    categoryCounts,
    recentlyUpdated,
    publishedCount,
    storageUsed,
  ] = await Promise.all([
    // Consulta principal com truque de paginação: busca limit+1 para detectar se há mais páginas
    prisma.document.findMany({
      take: limit + 1,
      skip: offset,
      orderBy: { updatedAt: 'desc' },
      include: { author: { select: { name: true, email: true } } },
    }),
 
    prisma.document.count(),
 
    prisma.document.groupBy({
      by: ['categoryId'],
      _count: { id: true },
    }),
 
    prisma.document.findMany({
      take: 5,
      orderBy: { updatedAt: 'desc' },
      where: { updatedAt: { gte: new Date(Date.now() - 24 * 60 * 60 * 1000) } },
    }),
 
    prisma.document.count({ where: { status: 'PUBLISHED' } }),
 
    // Consulta bruta específica do Postgres para agregação
    prisma.$queryRaw<[{ total: bigint }]>`
      SELECT COALESCE(SUM("file_size"), 0) as total FROM "Document"
    `,
  ]);
 
  const hasMore = documents.length > limit;
  const paginatedDocs = hasMore ? documents.slice(0, limit) : documents;
  const totalStorage = Number(storageUsed[0]?.total ?? 0n);
 
  return NextResponse.json({
    documents: paginatedDocs,
    hasMore,
    totalCount,
    categoryCounts,
    recentlyUpdated,
    publishedCount,
    totalStorage,
  });
}

O que isso demonstra em produção:

O truque de paginação take: limit + 1 evita uma consulta de contagem separada apenas para saber se há uma próxima página. Se você receber mais linhas do que limit, há mais páginas. Corte a linha extra antes de retornar.
$queryRaw é usado para a agregação COALESCE(SUM(...)) específica do Postgres porque a API de agregação do Prisma não suporta COALESCE. O tipo de retorno deve ser anotado explicitamente como [{ total: bigint }] porque o Postgres retorna bigint para SUM.
O bigint do Postgres não pode ser serializado diretamente para JSON. Number(storageUsed[0]?.total ?? 0n) o converte para um número regular. Para valores que podem exceder Number.MAX_SAFE_INTEGER, use .toString() em vez disso.
Seis consultas paralelas executam simultaneamente via Promise.all. O tempo total é a duração da consulta mais lenta, não a soma de todas as seis. Em um cold start, isso reduziu o endpoint de cerca de 1200ms (sequencial) para menos de 300ms.
O dimensionamento do pool de conexões é importante com consultas paralelas. Seis consultas Prisma simultâneas consomem seis conexões do pool. O tamanho padrão do pool do Prisma é num_cpus * 2 + 1. Em plataformas serverless, mantenha a contagem de consultas paralelas dentro dos limites do pool ou aumente o tamanho do pool na string de conexão.

FAQs

O que acontece se uma promise rejeitar em `Promise.all`?

Promise.all rejeita imediatamente com esse erro
Todos os outros resultados são perdidos, mesmo de promises que já tiveram sucesso
Use Promise.allSettled quando algumas buscas não forem críticas

Quando você deve usar `Promise.allSettled` em vez de `Promise.all`?

Quando algumas buscas são opcionais ou não críticas (por exemplo, recomendações)
Quando você quer dados parciais em vez de uma falha completa
Cada resultado tem um status de "fulfilled" ou "rejected" para que você possa lidar com cada um individualmente

Por que chamadas `await` sequenciais criam um waterfall mesmo que cada promise comece imediatamente?

Promises começam a executar quando criadas, mas await bloqueia a próxima linha
const a = await fetchA(); const b = await fetchB(); espera A terminar antes de criar B
Para rodar em paralelo, crie todas as promises primeiro, depois await Promise.all([...])

// Ruim: sequencial
const users = await getUsers();
const posts = await getPosts();
 
// Bom: paralelo
const [users, posts] = await Promise.all([getUsers(), getPosts()]);

Qual a diferença entre `Promise.race` e `Promise.any`?

Promise.race resolve ou rejeita com a primeira promise a resolver/rejeitar (seja cumprir ou rejeitar)
Promise.any resolve com a primeira promise a cumprir, ignorando rejeições
Promise.any só rejeita se todas as promises rejeitarem (com um AggregateError)

Como `Promise.all` preserva os tipos de tupla do TypeScript?

const results = await Promise.all([
  getUser("1"),   // Promise<User>
  getPosts("1"),  // Promise<Post[]>
  getCount(),     // Promise<number>
]);
// results é [User, Post[], number] -- totalmente tipado

Como escrever um type guard para resultados de `Promise.allSettled`?

function isFulfilled<T>(
  result: PromiseSettledResult<T>
): result is PromiseFulfilledResult<T> {
  return result.status === "fulfilled";
}
 
const results = await Promise.allSettled([getUsers(), getPosts()]);
const successes = results.filter(isFulfilled).map((r) => r.value);

Quando um waterfall sequencial está realmente correto?

Quando a busca B depende do resultado da busca A (por exemplo, você precisa do ID do usuário antes de buscar seus posts)
Combine: busque a dependência primeiro, depois use Promise.all para sub-buscas independentes

const user = await getUser(id);
const [posts, followers] = await Promise.all([
  getPostsByAuthor(user.id),
  getFollowers(user.id),
]);

O que acontece se você disparar muitas requisições paralelas de uma vez?

Você pode sobrecarregar APIs ou atingir limites de taxa
Pools de conexão de banco de dados podem ser esgotados (por exemplo, o tamanho padrão do pool do Prisma é num_cpus * 2 + 1)
Use um limitador de concorrência como p-limit para agrupar requisições

Como funciona o truque de paginação `take: limit + 1` do exemplo do mundo real?

Busque uma linha extra além do tamanho da sua página
Se você receber mais linhas do que limit, há mais páginas (hasMore = true)
Corte a linha extra antes de retornar ao cliente
Isso evita uma consulta COUNT(*) separada apenas para verificar a próxima página

Você pode usar limites de Suspense em vez de `Promise.all` para carregamento de dados paralelo?

Sim. Cada Server Component assíncrono em seu próprio limite <Suspense> busca independentemente
Diferente de Promise.all, as seções renderizam à medida que resolvem em vez de esperar que todas terminem
Use Suspense quando as seções devem fazer streaming independentemente; use Promise.all quando você precisa de todos os dados antes de renderizar

Por que o exemplo do mundo real converte `bigint` para `Number()` antes de retornar JSON?

O Postgres retorna bigint para agregações SUM
bigint não pode ser serializado diretamente para JSON (gera TypeError)
Number() o converte para um número regular; use .toString() se o valor puder exceder Number.MAX_SAFE_INTEGER

O que é a função auxiliar `fetchParallel` e por que ela é útil?

async function fetchParallel<T extends readonly Promise<unknown>[]>(
  ...promises: T
): Promise<{ -readonly [K in keyof T]: Awaited<T[K]> }> {
  return Promise.all(promises) as any;
}

Ela preserva os tipos individuais para cada promise na tupla
Fornece resultados desestruturados totalmente tipados sem anotações de tipo manuais

Relacionados

Busca de Dados - buscar em Server Components
Streaming - streaming paralelo baseado em Suspense
Cache - deduplicação e cache de requisições
Generators - iteração assíncrona para grandes conjuntos de dados

Promises Paralelas e Promise.all

Buscar na documentação

Promises Paralelas e Promise.all