@sevn/reqcache 1.1.0 → 1.3.0

package/dist/request-cache.d.ts

@@ -13,8 +13,8 @@
  *  1. Primeira chamada -> faz o fetch e grava a entrada da rota no array.
  *  2. Durante o TTL -> devolve os dados do cache, sem tocar na rede.
  *  3. Após expirar -> SÓ revalida quando o client chamar de novo (lazy).
- *     Se houver `monotonicKey`, só aceita o novo dado quando o valor numérico
- *     dessa chave for MAIOR que o guardado; senão mantém o antigo.
+ *     Se houver `monotonicKey`, só aceita o novo dado quando TODAS as chaves
+ *     tiverem AVANÇADO; senão mantém o antigo.
  *
  * Proteção de espaço (limite de ~5 MB do localStorage):
  *  - `maxEntries`: ao gravar, se passar do limite, remove a rota menos
@@ -31,13 +31,48 @@ export interface StorageLike {
     setItem(key: string, value: string): void;
     removeItem(key: string): void;
 }
+/**
+ * Como comparar o valor de uma chave monotônica:
+ *  - `"number"` — numérica. Aceita `number` e string numérica ("2232575810").
+ *  - `"date"`   — por timestamp. Aceita o que o `Date.parse` resolver
+ *                 ("2026-10-04T18:23:00Z") e também epoch em ms.
+ *  - `"string"` — lexicográfica.
+ */
+export type MonotonicType = "number" | "date" | "string";
+/**
+ * Chave(s) monotônica(s). Três formas:
+ *  - `"summary.ballots_counted"` — uma chave, tipo detectado pelo valor.
+ *  - `["idg", "summary.last_updated"]` — várias, tipo detectado pelo valor.
+ *  - `{ idg: "number", "summary.last_updated": "date" }` — várias, com o tipo
+ *    declarado por nome de chave (recomendado: não depende de adivinhação).
+ */
+export type MonotonicKey = string | string[] | Record<string, MonotonicType>;
 export interface GetFetchOptions {
     /**
-     * Caminho da chave numérica monotônica. Suporta aninhamento com ponto.
-     * Ex.: "total", "resultado.votosApurados", "data.candidato.votos".
-     * Se o valor novo NÃO for maior que o antigo, mantém o dado em cache.
+     * Caminho(s) da chave monotônica. Suporta aninhamento com ponto.
+     *
+     *   monotonicKey: "resultado.votosApurados"
+     *   monotonicKey: ["idg", "summary.last_updated"]
+     *   monotonicKey: { idg: "number", "summary.last_updated": "date" }
+     *
+     * Com mais de uma chave, TODAS são comparadas e o dado novo só é aceito
+     * quando todas concordam que ele é mais recente — se qualquer uma vier
+     * igual ou menor, a resposta é descartada e o dado em cache é mantido.
+     * A comparação é sempre estrita: o valor novo precisa ser MAIOR que o
+     * guardado, nunca igual.
+     *
+     * O tipo de cada chave é resolvido nesta ordem:
+     *   1. declarado na forma de mapa;
+     *   2. conhecido pelo NOME da chave (`idg` é número, `last_updated` é data —
+     *      veja `TIPOS_POR_NOME`, extensível via `monotonicTypes` na config);
+     *   3. detectado pelo valor: número, string que converte para número finito,
+     *      string que o `Date.parse` resolve e, por fim, lexicográfica.
+     *
+     * TODAS as chaves precisam ter crescido. Uma chave incomparável (ausente de
+     * um dos lados, ilegível ou fora do tipo esperado) conta como "não cresceu"
+     * e derruba a resposta nova junto com as demais.
      */
-    monotonicKey?: string;
+    monotonicKey?: MonotonicKey;
     /** Opções nativas repassadas ao fetch (headers, method, body, signal...). */
     fetchOptions?: RequestInit;
     /**
@@ -67,6 +102,10 @@ export interface CacheEntry<T = unknown> {
     expiresAt: number;
     lastAccess: number;
 }
+/** Uma linha de log do modo debug. */
+export interface DebugLogFn {
+    (message: string, details?: Record<string, unknown>): void;
+}
 export interface RequestCacheConfig {
     /** Storage a usar. Padrão: localStorage (se disponível). */
     storage?: StorageLike;
@@ -74,6 +113,30 @@ export interface RequestCacheConfig {
     storageKey?: string;
     /** Máximo de rotas em cache. Excedeu -> remove a menos usada (LRU). Padrão 100. */
     maxEntries?: number;
+    /**
+     * Se true, imprime logs detalhados de cada operação (fetch de rede,
+     * cache hit, deduplicação, fallback, LRU, etc.). Padrão false.
+     * Útil para identificar se estão sendo feitas mais chamadas de rede
+     * do que o necessário. Pode ser ligado/desligado em runtime com
+     * `setDebug()`.
+     */
+    debug?: boolean;
+    /** Logger customizado usado quando `debug` está ligado. Padrão: `console.debug`. */
+    logger?: DebugLogFn;
+    /**
+     * Tipos monotônicos adicionais, por nome de chave. Somado (e com prioridade
+     * sobre) a tabela embutida `TIPOS_POR_NOME`, para que o chamador possa
+     * continuar passando `monotonicKey` como lista de caminhos e ainda assim ter
+     * a comparação certa:
+     *
+     *   new RequestCache({ monotonicTypes: { data_apuracao: "date" } })
+     *   ...
+     *   getFetch(url, 10_000, { monotonicKey: ["idg", "data_apuracao"] })
+     *
+     * Aceita o caminho completo ("summary.last_updated") ou só o último trecho
+     * ("last_updated").
+     */
+    monotonicTypes?: Record<string, MonotonicType>;
 }
 export declare class RequestCache {
     private storage;
@@ -82,7 +145,12 @@ export declare class RequestCache {
     private inflight;
     /** Relógio de acesso monotônico: sempre cresce, mesmo com acessos no mesmo ms. */
     private tick;
+    private debug;
+    private logger;
+    private monotonicTypes;
     constructor(config?: RequestCacheConfig);
+    /** Liga/desliga o modo debug em runtime, sem precisar recriar a instância. */
+    setDebug(enabled: boolean): void;
     /**
      * Busca uma URL usando cache.
      * @param url    Rota da requisição (também é a chave do cache).
@@ -102,6 +170,8 @@ export declare class RequestCache {
     clear(): void;
     /** Retorna um número de acesso estritamente crescente (para o LRU). */
     private nextAccess;
+    /** Emite uma linha de log, só quando o modo debug está ligado. */
+    private log;
     /**
      * Tenta cada URL da lista em ordem (primário, depois os `fallbackUrls`).
      * Devolve o JSON da primeira que responder OK; se todas falharem, lança o

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sevn/reqcache",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Cache de requisicoes HTTP em localStorage, com regra monotonica, deduplicacao e limite LRU. Pensado para cenarios de alto volume (ex.: apuracao de eleicoes).",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",