paginate-and-filter
Skill0 starsChanged 5 months agoMITView on GitHub
Usar al diseñar o implementar un endpoint que devuelve una colección, una vista de tabla/lista en frontend, o al notar que un endpoint devuelve N+ resultados sin paginar. También al modelar filtros para una pantalla de exploración de datos.
In this repository18 other files it gives its agents.
- adversarial-code-reviewSkill
- api-schema-separationSkill
- careful-destructive-opsSkill
- comments-disciplineSkill
- delegate-to-codexSkill
- design-rigor-alternativesSkill
- frontend-screen-and-loadingSkill
- migrations-alwaysSkill
- no-premature-abstractionSkill
- openapi-frontend-syncSkill
- pr-disciplineSkill
- pre-deploy-checklistSkill
- public-artifact-hygieneSkill
- read-before-writeSkill
- reuse-existing-patternsSkill
- secrets-handlingSkill
- test-layer-disciplineSkill
- use-worktreesSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 145
No usar el mismo "No hay datos" para los dos casos de empty — son problemas distintos.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Paginate and Filter
Overview
Devolver listas completas de golpe es la causa #1 de endpoints que se caen cuando los datos crecen, vistas que tardan segundos en cargar, y quejas del usuario "no encuentro nada". La regla es simple: ninguna vista, ningún endpoint, ningún query devuelve "todo".
Principio: todo listado se pagina y se filtra. El usuario no debería tener que scrollear 10.000 items para encontrar uno.
Anunciar al inicio: "Aplicando paginate-and-filter antes de
diseñar este listado."
Step 1: Elegir el modelo de paginación
Dos opciones — elegir antes de implementar:
| Modelo | Cuándo |
Offset/Limit (?page=2&pageSize=20) | Listas con números de página visibles, tablas administrativas, datos que cambian poco |
Cursor-based (?cursor=abc&limit=20) | Feeds infinite scroll, datos que cambian rápido (orden por created_at), datasets grandes |
Reglas:
- Offset es más simple pero degrada con datasets grandes (
OFFSET 10000es lento) y muestra duplicados si hay inserts mientras scrolleas. - Cursor es estable y rápido pero no permite "ir a la página 50" directo.
- Si el caller necesita "total count + page X de Y", solo offset funciona. Si necesita "siguiente página estable", cursor.
Step 2: Response shape estándar
Todos los endpoints paginados devuelven la misma forma. Ejemplo:
{
"data": [ ... ],
"pagination": {
"page": 2,
"pageSize": 20,
"total": 347,
"totalPages": 18,
"nextCursor": "abc123"
}
}Reglas:
datasiempre es array, nunca el item directamente.- Incluir
totalsolo si el modelo es offset (cursor no lo necesita). nextCursor: nullindica fin de la lista.pageSizedefault razonable (20–50). Max enforced (típico 100) — rechazar requests conpageSize > maxcon 400.
Step 3: Filtros server-side, no client-side
Los filtros se aplican en el query de DB, no en JavaScript después de cargar todo. Filtrar en cliente requiere cargar todo primero — el anti-patrón que estás evitando.
Tipos comunes de filtros que tu endpoint debería soportar:
| Filtro | Param de query |
| Búsqueda full-text | ?search=texto |
| Igualdad | ?status=active |
| Múltiples valores | ?status=active,pending |
| Rango fecha | ?from=2026-01-01&to=2026-06-30 |
| Rango numérico | ?minAmount=100&maxAmount=500 |
| Ordenamiento | ?orderBy=created_at&order=desc |
| Inclusión de relaciones | ?include=user,items |
Cada uno se valida (whitelist de campos ordenables y filtrables — nunca
aceptar orderBy=cualquierColumna sin restricción, eso permite leak
o injection).
Step 4: Evitar N+1 al paginar
Paginación + relaciones = trampa clásica. Si tu endpoint devuelve
orders y cada uno tiene user, paginar a 20 órdenes y hacer 20
queries para los usuarios es N+1.
Patrones de fix por ORM:
# SQLAlchemy
stmt = select(Order).options(selectinload(Order.user)).offset(...).limit(...)
# Django ORM
qs = Order.objects.select_related('user').prefetch_related('items')[offset:offset+limit]
# Prisma
const orders = await prisma.order.findMany({
include: { user: true, items: true },
skip, take,
});
# TypeORM
const orders = await repo.find({ relations: ['user', 'items'], skip, take });Verificar con query log o con tool del ORM (EXPLAIN, debug toolbar)
que el endpoint hace 1–3 queries, no 2 + N.
Step 5: UI side — query state en la URL
Los filtros y la página actual viven en la URL, no solo en estado del componente:
/orders?status=pending&from=2026-01-01&page=3Razones:
- El usuario puede compartir el link y otra persona ve lo mismo.
- Refresh de página no pierde el estado.
- Back/forward del browser funcionan.
- Marcar como favorito un set de filtros es trivial.
En React/Next: usar useSearchParams o nuqs/use-query-state. En
Vue: useRoute. En Angular: ActivatedRoute. En frameworks de UI
sin router: query string parsing manual.
Step 6: Skeleton + empty state + error
Cada vista paginada tiene cuatro estados visuales claros:
| Estado | UI |
| Loading | Skeleton con la forma de la tabla/lista (ver frontend-screen-and-loading) |
| Empty (no data) | Mensaje intencional + CTA si aplica ("aún no tienes órdenes — crear la primera") |
| Empty (filtered) | "Ningún resultado con estos filtros" + botón "limpiar filtros" |
| Error | Mensaje claro + retry button |
No usar el mismo "No hay datos" para los dos casos de empty — son problemas distintos.
Quick Reference
| Situación | Acción |
| Voy a crear endpoint que devuelve lista | Step 1 (elegir modelo) + Step 2 (shape estándar) |
| Voy a mostrar tabla en frontend | Step 3 (filtros server-side) + Step 5 (URL state) |
| Endpoint devuelve >100 items sin paginar | Refactor inmediato — agregar paginación |
Filtros aplicados con .filter() en JS después del fetch | Mover al backend |
| Endpoint con relaciones devuelve 20 items en 2 segundos | Step 4 (probable N+1) |
| Vista sin loading state | Step 6 (skeleton) |
| Vista de "sin datos" idéntica con/sin filtros | Step 6 (separar empty vs empty-filtered) |
Common Mistakes
- Devolver "todo" porque "son pocos registros por ahora". El día que crezca, el endpoint se rompe y tu vista también.
- Filtrar en cliente. Trae todo primero, filtra después — el antipatrón que esta skill previene.
orderBysin whitelist. Permite que el caller ordene porpassword_hash(leak) o cause queries lentas a propósito.- N+1 oculto. El endpoint "funciona" en dev con 5 registros y explota en prod con 500.
- Estado de filtros solo en componente. El usuario pierde contexto al refrescar o compartir.
pageSizesin max. El caller pide?pageSize=1000000y rompe el server.- Empty state genérico para "sin datos" y "filtrado sin matches". Confunde al usuario.
Red Flags
Nunca:
- Diseñar un endpoint que devuelve "todo" sin paginar.
- Filtrar en cliente cuando los datos pueden crecer.
- Aceptar
orderByarbitrario sin whitelist. - Olvidar el max de
pageSize(deja la puerta abierta a DoS barato). - Devolver lista paginada con N+1 en relaciones.
Siempre:
- Elegir el modelo (offset vs cursor) antes de codear.
- Validar y limitar
pageSize. - Filtros server-side, validados contra whitelist.
- Verificar con query log que no hay N+1.
- Filtros + página en la URL, no solo en componente.
- Loading + empty (sin datos) + empty (sin matches) + error como estados separados.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

