@sevn/reqcache

Cache de requisições HTTP em localStorage, pensado para cenários de alto volume em curto período (ex.: apuração de eleições).

• Lazy: só revalida quando você chama getFetch e o cache expirou. Nada roda em segundo plano.
• Regra monotônica: após expirar, só aceita o dado novo se um valor numérico tiver aumentado (protege contra respostas inconsistentes da API).
• Deduplicação: chamadas simultâneas à mesma rota disparam um único fetch.
• Limite de espaço: maxEntries remove a rota menos usada (LRU) automaticamente; nunca estoura o localStorage.
• Resiliência: se a API falhar, devolve o último dado válido (staleOnError).

Instalação

npm install @sevn/reqcache

Uso básico

import { requestCache } from "@sevn/reqcache";

// 1ª chamada: bate na API e cacheia por 10s.
// Chamadas dentro dos 10s: vêm do cache.
const dados = await requestCache.getFetch(
  "https://api.eleicoes.gov/resultado/presidente",
  10_000 // TTL em milissegundos
);

Com a regra monotônica

Ideal para contagens que só devem crescer (votos apurados, por exemplo):

const resultado = await requestCache.getFetch(
  "https://api.eleicoes.gov/resultado/presidente",
  10_000,
  { monotonicKey: "resultado.votosApurados" }
);

Se, na revalidação, a API devolver um votosApurados menor ou igual ao guardado, a resposta nova é descartada e o dado antigo é mantido.

Configuração

import { RequestCache } from "@sevn/reqcache";

const cache = new RequestCache({
  storageKey: "eleicoes-cache", // chave única no localStorage
  maxEntries: 200,              // limite de rotas antes de acionar o LRU
});

Opções de getFetch(url, ttlMs, options)

| Opção | Tipo | Padrão | Descrição | | -------------- | ------------- | ------ | ---------------------------------------------------------------- | | monotonicKey | string | — | Caminho da chave numérica ("a.b.c") que só pode crescer. | | fetchOptions | RequestInit | — | Repassado ao fetch nativo (headers, method, signal...). | | staleOnError | boolean | true | Devolve o dado antigo se a revalidação falhar. | | fetcher | typeof fetch| fetch| fetch customizado (útil para testes). |

Limpeza

O maxEntries já protege o espaço automaticamente a cada gravação. Para uma limpeza explícita de rotas abandonadas, chame cleanup na inicialização do app:

requestCache.cleanup(); // remove rotas expiradas há mais de 1h (padrão)

Outros métodos: invalidate(url) remove uma rota, clear() esvazia tudo.

Quando migrar para IndexedDB

O localStorage é síncrono e limitado a ~5 MB por domínio. Para respostas pequenas de placar/apuração, é suficiente. Se você for cachear payloads grandes (ex.: resultado seção por seção) ou notar travadinhas no pico, troque o backend por IndexedDB — o storage é injetável, então a lógica de cache não muda:

new RequestCache({ storage: meuAdaptadorIndexedDB });

Desenvolvimento

npm run typecheck   # checagem de tipos
npm test            # roda os testes (vitest)
npm run build       # gera dist/ (JS + tipos)

Licença

MIT