Batching y paginación

Consultas concurrentes

El siguiente patrón agrupa búsquedas concurrentes de productos y deduplica los counts idénticos. Correlo con tu cliente del lado del servidor para inspeccionar los requests reales con el hook onRequest.

await Promise.all([
  ...ids.map((id) => nube.products.findUnique({ where: { id }, select: { id: true, variants: true } })),
  ...handles.map((handle) => nube.products.findUnique({ where: { handle }, select: { id: true, images: true } })),
  nube.products.count(), nube.products.count(), nube.products.count(),
])

Cómo funciona el batching

• Las llamadas a findUnique se encolan durante una ventana corta (batch.windowMs, 2ms por defecto, suficiente para agarrar React Server Components hermanos).
• Cuando se cierra la ventana, las keys se deduplican y se agrupan en GET /products?ids=… o ?handles=…, hasta 30 por request (el límite de la API), y los lotes se piden en paralelo.
• El request pide la unión de los campos de todas las llamadas. Después, cada llamada recibe solo su propia selección, así que los tipos y los valores en runtime coinciden.
• Los productos que no existen resuelven a null solo para su llamada. Si un request falla, se rechazan únicamente las llamadas de ese lote.
• findMany({ where: { ids } }) pasa por la misma cola, así que 65 ids se convierten en 3 requests y se combinan con cualquier findUnique concurrente.

Esto significa que los componentes pueden pedir exactamente lo que necesitan, sin prop drilling ni loaders hechos a mano:

// Cada tarjeta pide sus datos por separado: la página igual manda un solo request.
async function Card({ id }: { id: number }) {
  const p = await nube.products.findUnique({ where: { id }, select: { name: true, images: true } })
  return <ProductCard product={p} />
}

Deduplicación y cache

• Los GET idénticos que están en curso comparten una misma promesa, sin importar qué método los haya disparado.
• Cache TTL en memoria opcional con cache: { ttlMs }. En Next.js, preferí fetchOptions: { next: { revalidate } } y dejá que el framework se encargue de la cache.

Paginación

findMany pide la página 1 con per_page=200 (el máximo), lee total_pages y después trae el resto de las páginas en forma concurrente, con el tope que marca concurrency. Así, 900 categorías llevan 5 requests, enviados en paralelo.

await nube.categories.findMany()                         // las 900, 5 requests en paralelo
await nube.products.findMany({ limit: 50 })               // 1 request, per_page=50
for await (const c of nube.categories.iterate()) { … }   // lazy, página por página

Concurrencia y reintentos

• Un semáforo limita los requests en paralelo (concurrency, 8 por defecto) en todo lo que hace el cliente.
• Ante un 429, se espera lo que indica Retry-After. Los 502/503/504 y los errores de red se reintentan con backoff exponencial y jitter.
• Crear un checkout no es idempotente, así que los POST solo se reintentan ante un 429, cuando la API rechazó el request antes de hacer nada.