Paginação e Filtragem

Q: Como paginar com duplicatas de createdAt?

Use cursor composto (createdAt, id) em tupla codificada em JSON.

Q: Paginação reversa?

Raro em REST. Suporte direction=prev com ordenação reversa se o produto exigir rolagem bidirecional.

Q: Página vazia vs 404?

Retorne 200 com data: [] e sem nextCursor - não 404.

Q: Filtros de intervalo de datas?

Use parâmetros de consulta ISO8601 createdAfter / createdBefore; valide com Zod z.coerce.date().

Q: Paginação NestJS?

DTO @Query() + método de repositório retornando metadados do cursor; mesmo envelope JSON.

Q: OpenAPI para parâmetros de lista?

Documente cada parâmetro de consulta e o esquema meta na resposta.

Endpoints de lista precisam de paginação que permaneça correta sob escritas concorrentes e filtragem que seja documentada, validada e indexada. APIs Node.js tipicamente expõem paginação por cursor para listas públicas e offset para pequenas ferramentas administrativas.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

GET /v1/orders?limit=20&cursor=eyJpZCI6Im9yZF8xMjMifQ&status=pending&customerId=cust_1

{
  "data": [ { "id": "ord_1", "status": "pending" } ],
  "meta": {
    "limit": 20,
    "nextCursor": "eyJpZCI6Im9yZF8yIn0",
    "hasMore": true
  }
}

RateLimit-Limit: 1000
RateLimit-Remaining: 998
RateLimit-Reset: 1720526400

Quando usar isso:

Tabelas excedem alguns milhares de linhas por tenant
Clientes navegam por feeds sem linhas duplicadas/faltantes em atualizações
Produto precisa de combinações de filtros (status, intervalo de datas)
API pública documenta contratos de lista no OpenAPI

Exemplo Funcional

import express from "express";
import { z } from "zod";
 
const listQuery = z.object({
  limit: z.coerce.number().int().min(1).max(100).default(20),
  cursor: z.string().optional(),
  status: z.enum(["pending", "shipped"]).optional(),
  customerId: z.string().uuid().optional(),
});
 
type Order = { id: string; customerId: string; status: string; createdAt: Date };
 
function encodeCursor(id: string): string {
  return Buffer.from(JSON.stringify({ id }), "utf8").toString("base64url");
}
 
function decodeCursor(cursor: string): { id: string } {
  return JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
}
 
async function listOrders(opts: {
  limit: number;
  cursor?: string;
  status?: string;
  customerId?: string;
}): Promise<{ rows: Order[]; nextCursor?: string }> {
  // Stand-in em memória simplificado para SQL: WHERE (id > cursorId) ORDER BY id LIMIT n+1
  const all: Order[] = [
    { id: "ord_1", customerId: "c1", status: "pending", createdAt: new Date() },
    { id: "ord_2", customerId: "c1", status: "shipped", createdAt: new Date() },
    { id: "ord_3", customerId: "c2", status: "pending", createdAt: new Date() },
  ];
 
  let filtered = all;
  if (opts.status) filtered = filtered.filter((o) => o.status === opts.status);
  if (opts.customerId) filtered = filtered.filter((o) => o.customerId === opts.customerId);
  if (opts.cursor) {
    const { id } = decodeCursor(opts.cursor);
    filtered = filtered.filter((o) => o.id > id);
  }
  filtered.sort((a, b) => a.id.localeCompare(b.id));
 
  const slice = filtered.slice(0, opts.limit + 1);
  const hasMore = slice.length > opts.limit;
  const rows = hasMore ? slice.slice(0, opts.limit) : slice;
  const nextCursor = hasMore ? encodeCursor(rows[rows.length - 1]!.id) : undefined;
  return { rows, nextCursor };
}
 
const app = express();
 
app.get("/v1/orders", async (req, res) => {
  const parsed = listQuery.safeParse(req.query);
  if (!parsed.success) {
    return res.status(400).json({ error: { code: "VALIDATION_ERROR" } });
  }
 
  const { rows, nextCursor } = await listOrders(parsed.data);
  res.setHeader("RateLimit-Limit", "1000");
  res.setHeader("RateLimit-Remaining", String(999));
  res.json({
    data: rows,
    meta: { limit: parsed.data.limit, nextCursor, hasMore: Boolean(nextCursor) },
  });
});

O que isso demonstra:

Cursor é um JSON base64url opaco (use cursores assinados em produção)
Busca limit + 1 para detectar hasMore sem consulta de contagem separada
Filtros validados com Zod a partir da string de consulta
Cabeçalhos de limite de taxa em respostas de lista

Análise Profunda

Como Funciona

Paginação por cursor: chave de ordenação estável (geralmente id ou (createdAt, id)); o cliente passa o último cursor visto
Paginação por offset: ?page=2&limit=20 mapeia para OFFSET 20 - simples, mas lento e inconsistente sob inserções
Filtragem: lista de permissões de parâmetros de consulta; rejeita filtros desconhecidos com 400
Ordenação: permite sort=createdAt:desc com lista de permissões; indexa colunas correspondentes

Cursor vs Offset

Aspecto	Cursor	Offset
Consistência sob escritas	Forte	Duplicatas/pulos
Páginas profundas	Rápido com índice	Lento `OFFSET 100000`
Pular para a página N	Difícil	Fácil
Melhor para	APIs públicas, feeds	UIs administrativas, exportações

Padrão de Cursor SQL

SELECT * FROM orders
WHERE customer_id = $1 AND status = $2
  AND (created_at, id) > ($3, $4)
ORDER BY created_at ASC, id ASC
LIMIT $5;

Notas TypeScript

// Cursor assinado impede adulteração
import { createHmac, timingSafeEqual } from "node:crypto";
 
function signCursor(payload: string, secret: string) {
  const sig = createHmac("sha256", secret).update(payload).digest("base64url");
  return `${payload}.${sig}`;
}

Armadilhas

Offset em tabelas grandes - Varredura completa da tabela na página 5000. Correção: Cursor para listas públicas; trabalhos de exportação assíncronos.
Filtros sem índice - ?search=text varredura completa da tabela. Correção: Índice ou serviço de busca dedicado.
IDs decimais como cursor - Bugs de comparação de ponto flutuante. Correção: Use ULID/UUID de string ou cursor de tupla.
Retornar contagem total sempre - COUNT(*) caro. Correção: includeTotal=true opcional ou omitir.
Sem limit máximo - Cliente solicita limit=100000. Correção: Limitar a 100 no esquema Zod.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Offset	Pequenos conjuntos de dados, pular para página	Feeds de alta escrita
Keyset (cursor)	APIs de lista de produção	Necessidade de acesso aleatório à página
Cursores Relay GraphQL	Clientes GraphQL	Parceiros apenas REST
Pesquisar depois (Algolia)	Busca de texto completo	Filtros SQL simples suficientes

FAQs

O cursor deve ser opaco?

Sim, para APIs públicas - evita que os clientes se acoplem a chaves de ordenação internas. Documente como string opaca.

Como paginar com duplicatas de createdAt?

Use cursor composto (createdAt, id) em tupla codificada em JSON.

Filtrar com condições OR?

Documente combinações suportadas. Árvores OR arbitrárias são difíceis de indexar - restrinja os padrões.

Incluir cabeçalhos RateLimit em todas as rotas?

No mínimo em endpoints de lista e busca; idealmente middleware global.

Paginação reversa?

Raro em REST. Suporte direction=prev com ordenação reversa se o produto exigir rolagem bidirecional.

Página vazia vs 404?

Retorne 200 com data: [] e sem nextCursor - não 404.

Filtros de intervalo de datas?

Use parâmetros de consulta ISO8601 createdAfter / createdBefore; valide com Zod z.coerce.date().

Paginação NestJS?

DTO @Query() + método de repositório retornando metadados do cursor; mesmo envelope JSON.

Exportar todas as linhas?

Trabalho de exportação assíncrono separado com link S3 - não limit ilimitado.

OpenAPI para parâmetros de lista?

Documente cada parâmetro de consulta e o esquema meta na resposta.

Relacionados

Noções Básicas de Design de API - URLs de recursos
OpenAPI & Swagger - documentar parâmetros de lista
Padrões de Resposta de Erro - erros de validação
Performance - ajuste de índice
Fundamentos HTTP em Node - cabeçalhos

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

GET /v1/orders?limit=20&cursor=eyJpZCI6Im9yZF8xMjMifQ&status=pending&customerId=cust_1

{
  "data": [ { "id": "ord_1", "status": "pending" } ],
  "meta": {
    "limit": 20,
    "nextCursor": "eyJpZCI6Im9yZF8yIn0",
    "hasMore": true
  }
}

RateLimit-Limit: 1000
RateLimit-Remaining: 998
RateLimit-Reset: 1720526400

Quando usar isso:

Tabelas excedem alguns milhares de linhas por tenant
Clientes navegam por feeds sem linhas duplicadas/faltantes em atualizações
Produto precisa de combinações de filtros (status, intervalo de datas)
API pública documenta contratos de lista no OpenAPI

Exemplo Funcional

import express from "express";
import { z } from "zod";
 
const listQuery = z.object({
  limit: z.coerce.number().int().min(1).max(100).default(20),
  cursor: z.string().optional(),
  status: z.enum(["pending", "shipped"]).optional(),
  customerId: z.string().uuid().optional(),
});
 
type Order = { id: string; customerId: string; status: string; createdAt: Date };
 
function encodeCursor(id: string): string {
  return Buffer.from(JSON.stringify({ id }), "utf8").toString("base64url");
}
 
function decodeCursor(cursor: string): { id: string } {
  return JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
}
 
async function listOrders(opts: {
  limit: number;
  cursor?: string;
  status?: string;
  customerId?: string;
}): Promise<{ rows: Order[]; nextCursor?: string }> {
  // Stand-in em memória simplificado para SQL: WHERE (id > cursorId) ORDER BY id LIMIT n+1
  const all: Order[] = [
    { id: "ord_1", customerId: "c1", status: "pending", createdAt: new Date() },
    { id: "ord_2", customerId: "c1", status: "shipped", createdAt: new Date() },
    { id: "ord_3", customerId: "c2", status: "pending", createdAt: new Date() },
  ];
 
  let filtered = all;
  if (opts.status) filtered = filtered.filter((o) => o.status === opts.status);
  if (opts.customerId) filtered = filtered.filter((o) => o.customerId === opts.customerId);
  if (opts.cursor) {
    const { id } = decodeCursor(opts.cursor);
    filtered = filtered.filter((o) => o.id > id);
  }
  filtered.sort((a, b) => a.id.localeCompare(b.id));
 
  const slice = filtered.slice(0, opts.limit + 1);
  const hasMore = slice.length > opts.limit;
  const rows = hasMore ? slice.slice(0, opts.limit) : slice;
  const nextCursor = hasMore ? encodeCursor(rows[rows.length - 1]!.id) : undefined;
  return { rows, nextCursor };
}
 
const app = express();
 
app.get("/v1/orders", async (req, res) => {
  const parsed = listQuery.safeParse(req.query);
  if (!parsed.success) {
    return res.status(400).json({ error: { code: "VALIDATION_ERROR" } });
  }
 
  const { rows, nextCursor } = await listOrders(parsed.data);
  res.setHeader("RateLimit-Limit", "1000");
  res.setHeader("RateLimit-Remaining", String(999));
  res.json({
    data: rows,
    meta: { limit: parsed.data.limit, nextCursor, hasMore: Boolean(nextCursor) },
  });
});

O que isso demonstra:

Cursor é um JSON base64url opaco (use cursores assinados em produção)
Busca limit + 1 para detectar hasMore sem consulta de contagem separada
Filtros validados com Zod a partir da string de consulta
Cabeçalhos de limite de taxa em respostas de lista

Análise Profunda

Como Funciona

Paginação por cursor: chave de ordenação estável (geralmente id ou (createdAt, id)); o cliente passa o último cursor visto
Paginação por offset: ?page=2&limit=20 mapeia para OFFSET 20 - simples, mas lento e inconsistente sob inserções
Filtragem: lista de permissões de parâmetros de consulta; rejeita filtros desconhecidos com 400
Ordenação: permite sort=createdAt:desc com lista de permissões; indexa colunas correspondentes

Cursor vs Offset

Aspecto	Cursor	Offset
Consistência sob escritas	Forte	Duplicatas/pulos
Páginas profundas	Rápido com índice	Lento `OFFSET 100000`
Pular para a página N	Difícil	Fácil
Melhor para	APIs públicas, feeds	UIs administrativas, exportações

Padrão de Cursor SQL

SELECT * FROM orders
WHERE customer_id = $1 AND status = $2
  AND (created_at, id) > ($3, $4)
ORDER BY created_at ASC, id ASC
LIMIT $5;

Notas TypeScript

// Cursor assinado impede adulteração
import { createHmac, timingSafeEqual } from "node:crypto";
 
function signCursor(payload: string, secret: string) {
  const sig = createHmac("sha256", secret).update(payload).digest("base64url");
  return `${payload}.${sig}`;
}

Armadilhas

Offset em tabelas grandes - Varredura completa da tabela na página 5000. Correção: Cursor para listas públicas; trabalhos de exportação assíncronos.
Filtros sem índice - ?search=text varredura completa da tabela. Correção: Índice ou serviço de busca dedicado.
IDs decimais como cursor - Bugs de comparação de ponto flutuante. Correção: Use ULID/UUID de string ou cursor de tupla.
Retornar contagem total sempre - COUNT(*) caro. Correção: includeTotal=true opcional ou omitir.
Sem limit máximo - Cliente solicita limit=100000. Correção: Limitar a 100 no esquema Zod.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Offset	Pequenos conjuntos de dados, pular para página	Feeds de alta escrita
Keyset (cursor)	APIs de lista de produção	Necessidade de acesso aleatório à página
Cursores Relay GraphQL	Clientes GraphQL	Parceiros apenas REST
Pesquisar depois (Algolia)	Busca de texto completo	Filtros SQL simples suficientes

FAQs

O cursor deve ser opaco?

Sim, para APIs públicas - evita que os clientes se acoplem a chaves de ordenação internas. Documente como string opaca.

Como paginar com duplicatas de createdAt?

Use cursor composto (createdAt, id) em tupla codificada em JSON.

Filtrar com condições OR?

Documente combinações suportadas. Árvores OR arbitrárias são difíceis de indexar - restrinja os padrões.

Incluir cabeçalhos RateLimit em todas as rotas?

No mínimo em endpoints de lista e busca; idealmente middleware global.

Paginação reversa?

Raro em REST. Suporte direction=prev com ordenação reversa se o produto exigir rolagem bidirecional.

Página vazia vs 404?

Retorne 200 com data: [] e sem nextCursor - não 404.

Filtros de intervalo de datas?

Use parâmetros de consulta ISO8601 createdAfter / createdBefore; valide com Zod z.coerce.date().

Paginação NestJS?

DTO @Query() + método de repositório retornando metadados do cursor; mesmo envelope JSON.

Exportar todas as linhas?

Trabalho de exportação assíncrono separado com link S3 - não limit ilimitado.

OpenAPI para parâmetros de lista?

Documente cada parâmetro de consulta e o esquema meta na resposta.

Relacionados

Noções Básicas de Design de API - URLs de recursos
OpenAPI & Swagger - documentar parâmetros de lista
Padrões de Resposta de Erro - erros de validação
Performance - ajuste de índice
Fundamentos HTTP em Node - cabeçalhos

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.

Paginação e Filtragem

Buscar na documentação

Paginação e Filtragem