@riligar/contract 1.0.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@riligar/contract",
-    "version": "1.0.1",
+    "version": "1.1.0",
     "license": "MIT",
     "type": "module",
     "description": "O contrato de API da stack RiLiGar: envelope \u00fanico, cat\u00e1logo de c\u00f3digos de erro e os helpers que tornam imposs\u00edvel responder fora dele.",

package/src/index.js

@@ -22,4 +22,4 @@
 // requisito legítimo daquele caminho — declarado no export map, não escondido
 // numa cadeia de reexports.
 export { CODES, STATUS_BY_CODE, RETRIABLE, isCode, toCode, codeFromStatus, ALIASES } from './codes.js'
-export { ok, criado, colecao, falha, falhaComStatus, corpoDeFalha, paginacao } from './respostas.js'
+export { ok, criado, colecao, falha, falhaComStatus, corpoDeFalha, paginacao, pagina } from './respostas.js'

package/src/respostas.js

@@ -48,17 +48,42 @@ export const criado = (recurso, { headers } = {}) => responder(recurso, 201, hea
  *
  * `hasMore` é explícito de propósito: o consumidor não deveria precisar
  * comparar `offset + limit` com `total` para saber se continua paginando.
- * Quando `total` não é conhecido (contar custaria uma query a mais em coisa
- * que ninguém pagina), `hasMore` sai do tamanho da página cheia.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * `total: null` QUANDO NINGUÉM CONTOU — e isso é o ponto deste helper.
+ *
+ * Até 10/09 os defaults preenchiam `page` a partir do próprio array: uma rota
+ * que NUNCA paginou devolvia `{limit: N, offset: 0, total: N, hasMore: false}`,
+ * byte a byte idêntico ao de uma rota que paginou e chegou ao fim. Das 39
+ * rotas de coleção da stack, 29 não paginavam e todas as 29 afirmavam
+ * `hasMore: false` — o campo que existe para o agente não ter de deduzir
+ * deduzia errado em 87% dos casos.
+ *
+ * Agora: quem não passa `total` recebe `total: null` e `hasMore: null`. Nulo é
+ * "não sei", e é diferente de zero e de falso. O agente que lê `total: null`
+ * sabe que precisa perguntar de outro jeito; o que lê `hasMore: false` para de
+ * paginar — e essas duas conclusões não podem sair da mesma resposta.
+ *
+ * Quem pagina de verdade passa `total` e recebe `hasMore` calculado. Quem
+ * devolve a lista inteira de propósito passa `total: itens.length`, e aí o
+ * `hasMore: false` é uma afirmação, não um default.
  */
 export const colecao = (itens, pagina = {}, { status = 200, headers } = {}) => {
     const items = Array.isArray(itens) ? itens : []
     const limit = pagina.limit ?? items.length
     const offset = pagina.offset ?? 0
-    const total = pagina.total ?? offset + items.length
-    const hasMore = pagina.hasMore ?? offset + items.length < total
 
-    return responder({ items, page: { limit, offset, total, hasMore } }, status, headers)
+    // `null` só quando NINGUÉM contou. `total: 0` é uma contagem legítima.
+    const total = pagina.total ?? null
+    const hasMore = pagina.hasMore ?? (total === null ? null : offset + items.length < total)
+
+    /*
+     * `extra` vai na RAIZ, não dentro de `page`. O `activeDeployId` do Hoster e
+     * as `contagens` do Monitors são contexto do CONJUNTO, não paginação —
+     * dentro de `page` eles diriam que são, e um cliente genérico que lê
+     * `page` para paginar tropeçaria neles.
+     */
+    return responder({ items, page: { limit, offset, total, hasMore }, ...(pagina.extra ?? {}) }, status, headers)
 }
 
 /**
@@ -118,6 +143,33 @@ export const paginacao = (url, { limitPadrao = 50, limitMaximo = 200 } = {}) =>
     return { limit, offset }
 }
 
+/**
+ * A página de uma consulta paginada, pronta para o `colecao`.
+ *
+ * Existe para tornar MECÂNICO o que a stack errava à mão em duas frentes:
+ *
+ * 1. **O `limit` reportado tem de ser o APLICADO.** Duas rotas clampavam na
+ *    camada de dados e reportavam o valor cru da query: com `?limit=5000`
+ *    devolviam 200 linhas e diziam `page:{limit:5000, hasMore:false}`. O
+ *    cliente conclui "pedi 5000, vieram 200, logo acabou" — e para de paginar
+ *    no meio.
+ *
+ * 2. **`total` vem de quem contou.** Passar `total` é obrigatório aqui, porque
+ *    o `colecao` sozinho não tem como saber se ninguém contou ou se a conta
+ *    deu o tamanho do array.
+ *
+ *   const { limit, offset } = paginacao(url)
+ *   const linhas = await buscar(limit, offset)
+ *   const [{ total }] = await contar()
+ *   return colecao(linhas, pagina({ limit, offset, total }))
+ */
+export const pagina = ({ limit, offset = 0, total, extra }) => {
+    if (!Number.isFinite(total)) {
+        throw new TypeError('pagina() exige `total` numérico — use colecao(itens) direto quando ninguém contou.')
+    }
+    return { limit, offset, total, extra }
+}
+
 /**
  * Uma falha de que só se sabe o status HTTP.
  *