Waterfalls: detectarlos y disparar en paralelo

Un waterfall es el enemigo silencioso de la latencia percibida: peticiones que podrían viajar juntas y en cambio esperan una a otra, encadenadas en serie por accidente. El componente monta, pide un dato, y solo cuando llega pide el siguiente, que no dependía del primero; o la ruta descarga su código, y solo entonces empieza a pedir datos. Cada eslabón suma su latencia a la del anterior, y el usuario espera la suma de todas. La cura es estructural: disparar las peticiones desde el preload de la ruta para que salgan en paralelo, apoyarse en query para que las lecturas anidadas reusen lo que ya está en vuelo, y reservar la secuencia solo para las dependencias que de verdad lo son.

Qué es un waterfall

Hay dos formas canónicas. La primera es el waterfall de datos: dos peticiones independientes que se esperan porque las escribiste en serie. La segunda es el waterfall de código y datos: la ruta espera a descargar su JavaScript antes de empezar a pedir. En ambos casos, tiempos que podían solaparse se suman.

// WATERFALL de datos: posts NO depende de perfil, pero lo espera
async function cargar(id: string) {
  const perfil = await getPerfil(id);   // primero esto...
  const posts = await getPosts(id);      // ...y solo despues esto
  return { perfil, posts };              // latencia = perfil + posts
}

Nada obliga a que posts espere a perfil: ambos dependen solo de id, que ya tienes. La estructura del código —dos await seguidos— ha inventado una dependencia que no existe, y el usuario paga la suma de dos latencias donde debería pagar la mayor de las dos.

Detectarlos: la forma de escalera

Un waterfall tiene una firma visual inconfundible en la pestaña de red: las barras de las peticiones se dibujan escalonadas, cada una empezando donde la anterior terminó, como peldaños que bajan hacia la derecha. Peticiones paralelas, en cambio, arrancan alineadas a la izquierda y se solapan en el tiempo.

// Escalera (malo):        Paralelo (bueno):
// perfil  [====]          perfil  [====]
// posts        [====]     posts   [====]
// avatar            [==]  avatar  [==]

La regla de lectura es directa: si ves peldaños y las peticiones de abajo no dependían de las de arriba, has encontrado un waterfall accidental. El objetivo es aplanar esos peldaños hasta alinearlos a la izquierda.

Disparar en paralelo desde la ruta

La palanca estructural es el preload de la ruta. Ahí invocas todas las queries que la pantalla necesitará sin esperarlas: al no haber await, salen todas a la vez, en paralelo, en cuanto hay intención de navegar. Los componentes las leen luego con createAsync, y query garantiza que esa lectura recoja la petición ya en vuelo en vez de lanzar una nueva.

// routes/usuarios/[id].tsx
export const route = {
  preload: ({ params }) => {
    getPerfil(params.id);  // se disparan
    getPosts(params.id);   // las dos
    getAvatar(params.id);  // a la vez
  },
} satisfies RouteDefinition;

Este es el porqué de que query y preload no fueran dos temas sueltos sino uno solo. La deduplicación por clave es lo que permite disparar en la ruta y leer en cualquier componente anidado sin duplicar: no importa a qué profundidad del árbol un componente pida getPosts(id), resolverá a la misma clave que el preload ya calentó. El paralelismo se declara arriba, en la ruta; la lectura se reparte abajo, en los componentes; y la clave los cose sin una sola petición de más.

flowchart LR
subgraph Serie [waterfall en serie]
  direction TB
  P1[perfil] --> P2[posts] --> P3[avatar]
end
subgraph Paralelo [preload dispara a la vez]
  direction TB
  R[preload de ruta] --> Q1[perfil]
  R --> Q2[posts]
  R --> Q3[avatar]
end
Serie --> L1[latencia = suma]
Paralelo --> L2[latencia = la mayor]
style Serie fill:#f38ba8,color:#11111b
style Paralelo fill:#a6e3a1,color:#11111b

Cuando la latencia manda dentro de una misma función de servidor, Promise.all expresa el paralelismo de forma explícita: lanzas las promesas y esperas a todas juntas, no una tras otra.

async function cargar(id: string) {
  const [perfil, posts] = await Promise.all([getPerfil(id), getPosts(id)]);
  return { perfil, posts }; // latencia = la mayor, no la suma
}

Hay una tercera fuente de waterfalls, más sigilosa, en la colocación de los Suspense. Dos createAsync hermanos bajo un mismo límite de Suspense disparan sus peticiones a la vez y revelan juntos; pero si anidas un Suspense dentro de otro, el interior no empieza a montar —ni a pedir— hasta que el exterior resuelve, y has vuelto a serializar. La regla práctica es agrupar bajo un solo límite lo que puede cargar en paralelo, y anidar límites solo cuando de verdad quieras que una sección espere a otra.

// Paralelo: ambos createAsync corren bajo el MISMO Suspense
<Suspense fallback={<Cargando />}>
  <Perfil id={id} />   {/* getPerfil */}
  <Posts id={id} />    {/* getPosts, a la vez que getPerfil */}
</Suspense>

Cuando la dependencia es real

No todo encadenamiento es un pecado. A veces la segunda petición necesita el resultado de la primera: pides un pedido para conocer el id de su cliente, y solo entonces puedes pedir ese cliente. Esa dependencia es real y no se puede paralelizar —ningún truco adelanta un dato que aún no existe—. Lo que sí puedes es minimizar la cadena: prefetchar la primera petición en el preload para que su leg arranque durante la navegación, mantener la profundidad de la cadena tan corta como el dominio permita, y no colgar de ella peticiones que en realidad no dependían.

// Dependencia REAL: el cliente sale del pedido, no hay como paralelizar
const pedido = await getPedido(pedidoId);
const cliente = await getCliente(pedido.clienteId); // necesita pedido

La disciplina, entonces, no es “nunca encadenes” sino “encadena solo lo que el dato obliga, y que cada eslabón se gane su lugar”. Un waterfall es aceptable exactamente en la medida en que refleja una dependencia genuina; deja de serlo en cuanto encadena cosas que podían haber volado juntas.