Parallel Promises & Promise.all

// Promise.all - fails fast if any promise rejects
const [users, posts, stats] = await Promise.all([
  getUsers(),
  getPosts(),
  getStats(),
]);
 
// Promise.allSettled - never rejects, returns status for each
const results = await Promise.allSettled([
  getUsers(),
  getPosts(),
  getStats(),
]);
 
// Promise.race - resolves/rejects with the first to settle
const fastest = await Promise.race([
  fetchFromPrimary(),
  fetchFromFallback(),
]);
 
// Promise.any - resolves with the first to fulfill (ignores rejections)
const firstSuccess = await Promise.any([
  fetchFromCDN1(),
  fetchFromCDN2(),
]);

// 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";
 
  // All three fetches start at the same time
  const [user, orders, notifications] = await Promise.all([
    getUser(userId),
    getOrders(userId),
    getNotifications(userId),
  ]);
 
  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      <p>{notifications.length} unread notifications</p>
      <h2>Recent Orders</h2>
      <ul>
        {orders.map((order: { id: string; total: number }) => (
          <li key={order.id}>${order.total}</li>
        ))}
      </ul>
    </div>
  );
}

export default async function DashboardPage() {
  const results = await Promise.allSettled([
    getUser("user-123"),
    getOrders("user-123"),
    getRecommendations("user-123"), // Might fail, non-critical
  ]);
 
  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>
  );
}

// Each section loads independently - no Promise.all needed
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>
  );
}
 
// Each component fetches its own data
async function UserProfile({ id }: { id: string }) {
  const user = await getUser(id);
  return <h1>{user.name}</h1>;
}

// When fetch B depends on fetch A, sequential is correct
export default async function UserPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const user = await getUser(id);
 
  // These depend on user data, but are independent of each other
  const [posts, followers] = await Promise.all([
    getPostsByAuthor(user.id),
    getFollowers(user.id),
  ]);
 
  return <Profile user={user} posts={posts} followers={followers} />;
}

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]> }>;
}
 
// Usage - fully typed results
const [user, posts] = await fetchParallel(
  getUser("123"),    // User type
  getPosts("123"),   // Post[] type
);

// Promise.all preserves tuple types
const results = await Promise.all([
  getUser("1"),      // returns Promise<User>
  getPosts("1"),     // returns Promise<Post[]>
  getCount(),        // returns Promise<number>
]);
// results is [User, Post[], number]
 
// Promise.allSettled result type
type SettledResult<T> =
  | { status: "fulfilled"; value: T }
  | { status: "rejected"; reason: unknown };
 
// Type guard for settled results
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);

// Bad: sequential (each await blocks)
const users = await getUsers();
const posts = await getPosts();
 
// Good: parallel (both start immediately)
const [users, posts] = await Promise.all([getUsers(), getPosts()]);

// Production example: Admin documents API with 6 parallel Prisma queries
// File: 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([
    // Main query with pagination trick: fetch limit+1 to detect if more pages exist
    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' } }),
 
    // Postgres-specific raw query for aggregation
    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,
  });
}