@sevn/reqcache 1.1.0 → 1.3.0

package/README.md

@@ -43,6 +43,78 @@ const resultado = await requestCache.getFetch(
 Se, na revalidação, a API devolver um `votosApurados` **menor ou igual** ao
 guardado, a resposta nova é descartada e o dado antigo é mantido.
 
+### Várias chaves ao mesmo tempo
+
+`monotonicKey` também aceita uma lista. Todas as chaves são comparadas e o
+dado novo só entra quando **todas** cresceram:
+
+```ts
+const resultado = await requestCache.getFetch(url, 10_000, {
+  monotonicKey: ["idg", "summary.last_updated"],
+});
+```
+
+Serve para quando a chave usada até então para de avançar (ex.: a apuração
+termina e `ballots_counted` congela, mas o arquivo continua sendo atualizado
+com as tags de eleito e 2º turno). Apontando também para campos que seguem
+avançando, a tela não trava.
+
+### Como o tipo de cada chave é decidido
+
+Nesta ordem:
+
+1. **Declarado** na chamada, se você usar a forma de mapa:
+   `monotonicKey: { idg: "number", "summary.last_updated": "date" }`.
+2. **Conhecido pelo nome da chave** — a lib já traz uma tabela:
+
+   | Nome | Tipo |
+   | ---- | ---- |
+   | `idg` | número |
+   | `versao` | número |
+   | `ballots_counted` | número |
+   | `last_updated` | data |
+
+   A busca é pelo caminho completo e, se não achar, pelo último trecho dele —
+   então `"summary.last_updated"` e `"dados.meta.last_updated"` caem em
+   `last_updated`. Para registrar os campos do seu projeto:
+
+   ```ts
+   const cache = new RequestCache({
+     monotonicTypes: { data_apuracao: "date", sequencial: "number" },
+   });
+   ```
+
+3. **Detectado pelo valor**, para nomes fora da tabela:
+
+   | Valor | Comparação |
+   | ----- | ---------- |
+   | `number` | numérica |
+   | string que vira número finito (`"2232575810"`) | numérica, não lexicográfica (evita `"9" > "10"`) |
+   | string que o `Date.parse` resolve (`"2026-10-04T18:23:00Z"`) | por timestamp |
+   | demais strings | lexicográfica |
+
+   A ordem não pode ser trocada: `Date.parse` aceita strings numéricas curtas
+   como data, então um id curto viraria data se a checagem de data viesse
+   primeiro. No sentido inverso não há risco —
+   `Number("2026-10-04T18:23:00Z")` é `NaN`.
+
+A comparação é sempre **estrita**: o valor novo precisa ser maior que o
+guardado, nunca igual.
+
+**Todas as chaves precisam ter crescido.** Basta uma não crescer para a
+resposta nova ser descartada e o cache mantido (só a expiração é renovada).
+
+Uma chave **incomparável** conta como "não cresceu" e derruba a resposta junto
+com as demais. Ela é incomparável quando está ausente de um dos lados, é
+ilegível (string vazia ou em branco), não bate com o tipo conhecido/declarado
+ou — só quando o tipo foi detectado pelo valor — tem tipos divergentes entre as
+versões.
+
+Consequência a considerar ao montar a lista: se um dos campos sumir ou for
+renomeado pelo back, a lib passa a rejeitar toda resposta e a tela congela no
+último dado válido. Aponte `monotonicKey` só para campos que você tem certeza
+que vêm sempre preenchidos.
+
 ## Redundância entre domínios (fallback)
 
 Se o endpoint principal cair, a lib pode tentar automaticamente uma lista de
@@ -71,6 +143,37 @@ await requestCache.getFetch(url, 10_000, {
 });
 ```
 
+## Modo debug
+
+Para ver exatamente o que a lib está fazendo — se uma chamada foi atendida
+pelo cache, disparou uma requisição de rede, entrou em deduplicação, etc. —
+ligue o modo debug:
+
+```ts
+const cache = new RequestCache({ debug: true });
+
+await cache.getFetch(url, 10_000); // imprime no console cada passo
+```
+
+Útil para identificar se estão sendo feitas mais chamadas de rede do que o
+necessário. Pode ser ligado/desligado em runtime, sem recriar a instância:
+
+```ts
+cache.setDebug(true);
+// ...
+cache.setDebug(false);
+```
+
+Por padrão os logs vão para `console.debug`, prefixados com `[reqcache]`. Para
+mandar para outro lugar (ex.: seu sistema de logging), passe um `logger`:
+
+```ts
+const cache = new RequestCache({
+  debug: true,
+  logger: (mensagem, detalhes) => meuLogger.debug(mensagem, detalhes),
+});
+```
+
 ## Configuração
 
 ```ts
@@ -82,11 +185,22 @@ const cache = new RequestCache({
 });
 ```
 
+### Opções de `new RequestCache(config)`
+
+| Opção        | Tipo                        | Padrão       | Descrição                                                        |
+| ------------ | --------------------------- | ------------ | ----------------------------------------------------------------- |
+| `storage`    | `StorageLike`                | localStorage | Storage customizado (permite trocar por IndexedDB, por exemplo). |
+| `storageKey` | `string`                     | `"reqcache"` | Chave única onde o cache é guardado.                             |
+| `maxEntries` | `number`                     | `100`        | Máximo de rotas em cache; ao exceder, remove a menos usada (LRU). |
+| `debug`      | `boolean`                    | `false`      | Liga logs detalhados de cada operação. Veja "Modo debug" acima.  |
+| `logger`     | `(msg, detalhes) => void`    | `console.debug` | Logger customizado usado quando `debug: true`.                |
+| `monotonicTypes` | `Record<string, "number"\|"date"\|"string">` | — | Tipos monotônicos por nome de chave, somados à tabela embutida. |
+
 ### 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.         |
+| `monotonicKey` | `string \| string[] \| Record<string, "number"\|"date"\|"string">` | — | Caminho(s) da chave que só pode crescer ("a.b.c"). Com mais de uma, todas precisam avançar. |
 | `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).                          |

package/dist/index.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 @@ 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.
+ */
+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).
+ */
+type MonotonicKey = string | string[] | Record<string, MonotonicType>;
 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 @@ interface CacheEntry<T = unknown> {
     expiresAt: number;
     lastAccess: number;
 }
+/** Uma linha de log do modo debug. */
+interface DebugLogFn {
+    (message: string, details?: Record<string, unknown>): void;
+}
 interface RequestCacheConfig {
     /** Storage a usar. Padrão: localStorage (se disponível). */
     storage?: StorageLike;
@@ -74,6 +113,30 @@ 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>;
 }
 declare class RequestCache {
     private storage;
@@ -82,7 +145,12 @@ 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 @@ 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
@@ -120,4 +190,4 @@ declare class RequestCache {
 declare const requestCache: RequestCache;
 
 export { RequestCache, requestCache };
-export type { CacheEntry, GetFetchOptions, RequestCacheConfig, StorageLike };
+export type { CacheEntry, DebugLogFn, GetFetchOptions, MonotonicKey, MonotonicType, RequestCacheConfig, StorageLike };

package/dist/index.esm.js

@@ -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
@@ -28,13 +28,20 @@
  */
 class RequestCache {
     constructor(config = {}) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e, _f;
         this.inflight = new Map();
         /** Relógio de acesso monotônico: sempre cresce, mesmo com acessos no mesmo ms. */
         this.tick = 0;
         this.storageKey = (_a = config.storageKey) !== null && _a !== void 0 ? _a : "reqcache";
         this.maxEntries = (_b = config.maxEntries) !== null && _b !== void 0 ? _b : 100;
         this.storage = (_c = config.storage) !== null && _c !== void 0 ? _c : getDefaultStorage();
+        this.debug = (_d = config.debug) !== null && _d !== void 0 ? _d : false;
+        this.logger = (_e = config.logger) !== null && _e !== void 0 ? _e : defaultLogger;
+        this.monotonicTypes = { ...TIPOS_POR_NOME, ...((_f = config.monotonicTypes) !== null && _f !== void 0 ? _f : {}) };
+    }
+    /** Liga/desliga o modo debug em runtime, sem precisar recriar a instância. */
+    setDebug(enabled) {
+        this.debug = enabled;
     }
     /**
      * Busca uma URL usando cache.
@@ -50,13 +57,17 @@ class RequestCache {
         if (cached && now < cached.expiresAt) {
             cached.lastAccess = this.nextAccess(); // marca uso p/ o LRU
             this.writeAll(all);
+            this.log("cache hit", { url, expiresAt: new Date(cached.expiresAt).toISOString() });
             return cached.data;
         }
         // 2. Deduplicação: se já há uma requisição em andamento p/ essa rota,
         //    todas as chamadas concorrentes aguardam a mesma Promise.
         const pending = this.inflight.get(url);
-        if (pending)
+        if (pending) {
+            this.log("dedup: aguardando requisição em andamento", { url });
             return pending;
+        }
+        this.log(cached ? "cache expirado, revalidando" : "cache miss", { url });
         const promise = this.revalidate(url, ttlMs, options, cached !== null && cached !== void 0 ? cached : null)
             .finally(() => this.inflight.delete(url));
         this.inflight.set(url, promise);
@@ -77,7 +88,10 @@ class RequestCache {
         const all = this.readAll();
         const mantidas = all.filter((e) => e.expiresAt > limite);
         this.writeAll(mantidas);
-        return all.length - mantidas.length;
+        const removidas = all.length - mantidas.length;
+        if (removidas > 0)
+            this.log("cleanup: rotas expiradas removidas", { removidas });
+        return removidas;
     }
     /** Esvazia todo o cache. */
     clear() {
@@ -96,6 +110,12 @@ class RequestCache {
         this.tick = Math.max(Date.now(), this.tick + 1);
         return this.tick;
     }
+    /** Emite uma linha de log, só quando o modo debug está ligado. */
+    log(message, details) {
+        if (!this.debug)
+            return;
+        this.logger(message, details);
+    }
     /**
      * 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
@@ -105,13 +125,16 @@ class RequestCache {
         var _a;
         let ultimoErro;
         for (const candidato of candidatos) {
+            this.log("fetch de rede", { url: candidato });
             try {
                 const res = await fetcher(candidato, options.fetchOptions);
                 if (!res.ok)
                     throw new Error(`HTTP ${res.status} ao buscar ${candidato}`);
+                this.log("fetch OK", { url: candidato, status: res.status });
                 return (await res.json());
             }
             catch (err) {
+                this.log("fetch falhou", { url: candidato, erro: String(err) });
                 ultimoErro = err;
                 (_a = options.onFallback) === null || _a === void 0 ? void 0 : _a.call(options, candidato, err);
             }
@@ -129,6 +152,7 @@ class RequestCache {
         catch (err) {
             // Todos os domínios falharam. Se temos dado antigo e staleOnError, devolve o antigo.
             if (cached && ((_c = options.staleOnError) !== null && _c !== void 0 ? _c : true)) {
+                this.log("staleOnError: devolvendo dado antigo", { url });
                 this.upsert({
                     ...cached,
                     expiresAt: Date.now() + ttlMs,
@@ -138,13 +162,16 @@ class RequestCache {
             }
             throw err;
         }
-        // 3. Regra monotônica: só aceita o novo dado se a chave numérica CRESCEU.
+        // 3. Regra monotônica: só aceita o novo dado se TODAS as chaves que
+        //    conseguiram votar tiverem avançado.
         if (cached && options.monotonicKey) {
-            const oldVal = getPath(cached.data, options.monotonicKey);
-            const newVal = getPath(fresh, options.monotonicKey);
-            const ambosNumeros = typeof oldVal === "number" && typeof newVal === "number";
-            if (ambosNumeros && newVal <= oldVal) {
-                // Valor não aumentou -> mantém o dado antigo, só renova a expiração.
+            const veredito = avaliarMonotonicidade(cached.data, fresh, options.monotonicKey, this.monotonicTypes);
+            if (!veredito.avancou) {
+                // Alguma chave não avançou -> mantém o dado antigo, só renova a expiração.
+                this.log("regra monotônica: valor não cresceu, mantendo dado antigo", {
+                    url,
+                    chaves: veredito.detalhes,
+                });
                 this.upsert({
                     ...cached,
                     expiresAt: Date.now() + ttlMs,
@@ -155,6 +182,7 @@ class RequestCache {
         }
         // 4. Grava e devolve o dado novo.
         const now = Date.now();
+        this.log("cache gravado", { url, ttlMs });
         this.upsert({
             rota: url,
             data: fresh,
@@ -179,6 +207,7 @@ class RequestCache {
                 if (all[i].lastAccess < all[idxMaisAntigo].lastAccess)
                     idxMaisAntigo = i;
             }
+            this.log("LRU: removendo rota menos usada", { url: all[idxMaisAntigo].rota });
             all.splice(idxMaisAntigo, 1);
         }
     }
@@ -207,6 +236,10 @@ class RequestCache {
             if (isQuotaError(err) && all.length > 0) {
                 const reduzido = [...all].sort((a, b) => a.lastAccess - b.lastAccess);
                 reduzido.splice(0, Math.ceil(reduzido.length / 2)); // descarta metade
+                this.log("quota excedida: descartando metade das entradas mais antigas", {
+                    totalAntes: all.length,
+                    totalDepois: reduzido.length,
+                });
                 try {
                     this.storage.setItem(this.storageKey, JSON.stringify(reduzido));
                 }
@@ -227,11 +260,182 @@ function getPath(obj, path) {
         return undefined;
     }, obj);
 }
+/**
+ * Descobre como comparar um valor. A ordem das checagens NÃO pode ser trocada:
+ * `Date.parse` aceita strings numéricas curtas como data (`Date.parse("9")` cai
+ * em setembro, `Date.parse("10")` em outubro), então um `idg` curto viraria
+ * data se a checagem de data viesse antes da numérica. No sentido inverso não
+ * há risco: `Number("2026-10-04T18:23:00Z")` é NaN.
+ *
+ * Devolve `null` quando o valor é incomparável.
+ */
+function classificar(valor) {
+    if (typeof valor === "number") {
+        return Number.isFinite(valor) ? { tipo: "number", ordem: valor } : null;
+    }
+    if (typeof valor !== "string")
+        return null;
+    // String vazia ou em branco é incomparável: `Number("")` e `Number(" ")`
+    // devolvem 0, e um campo vazio viraria um "zero" comparável.
+    if (valor.trim() === "")
+        return null;
+    const numero = Number(valor);
+    if (Number.isFinite(numero))
+        return { tipo: "number", ordem: numero };
+    const data = Date.parse(valor);
+    if (!Number.isNaN(data))
+        return { tipo: "date", ordem: data };
+    return { tipo: "string", ordem: valor };
+}
+/**
+ * Classifica um valor segundo um tipo DECLARADO pelo chamador (forma de mapa).
+ * Como o tipo veio declarado, não há adivinhação: o valor ou serve, ou a chave
+ * é incomparável (e derruba a resposta nova). É também mais tolerante que a
+ * detecção por valor — com
+ * `"number"`, `100` e `"101"` comparam entre si sem problema, já que o
+ * chamador afirmou que aquele campo é numérico.
+ */
+function classificarComTipo(valor, tipo) {
+    // String vazia ou em branco nunca é comparável: `Number("")` e `Number(" ")`
+    // devolvem 0, e um campo vazio viraria um "zero" comparável.
+    const texto = typeof valor === "string" ? valor.trim() : null;
+    if (texto === "")
+        return null;
+    if (tipo === "number") {
+        if (typeof valor === "number") {
+            return Number.isFinite(valor) ? { tipo, ordem: valor } : null;
+        }
+        if (texto === null)
+            return null;
+        const numero = Number(texto);
+        return Number.isFinite(numero) ? { tipo, ordem: numero } : null;
+    }
+    if (tipo === "date") {
+        // Um número aqui é lido como epoch em ms.
+        if (typeof valor === "number") {
+            return Number.isFinite(valor) ? { tipo, ordem: valor } : null;
+        }
+        if (texto === null)
+            return null;
+        const data = Date.parse(texto);
+        return Number.isNaN(data) ? null : { tipo, ordem: data };
+    }
+    return texto === null ? null : { tipo, ordem: texto };
+}
+/**
+ * Tipos conhecidos por NOME de chave. É o que permite ao front continuar
+ * passando só os caminhos — `["idg", "summary.last_updated"]` — e ainda assim
+ * ter `idg` comparado como número e `last_updated` como data, sem depender de
+ * adivinhação pelo valor.
+ *
+ * A busca é feita pelo caminho completo e, se não achar, pelo último trecho
+ * dele: "summary.last_updated" cai em "last_updated". Nomes fora desta tabela
+ * (e de `monotonicTypes`) continuam sendo detectados pelo valor.
+ */
+const TIPOS_POR_NOME = {
+    idg: "number",
+    versao: "number",
+    ballots_counted: "number",
+    last_updated: "date",
+};
+/**
+ * Procura o tipo de uma chave na tabela de nomes: primeiro pelo caminho
+ * completo ("summary.last_updated"), depois só pelo último trecho
+ * ("last_updated").
+ */
+function tipoConhecido(chave, tabela) {
+    if (chave in tabela)
+        return tabela[chave];
+    const ultimo = chave.slice(chave.lastIndexOf(".") + 1);
+    return ultimo in tabela ? tabela[ultimo] : null;
+}
+/**
+ * Reduz as três formas aceitas de `monotonicKey` a uma lista única, já com o
+ * tipo de cada chave resolvido: o declarado no mapa vence; senão vale o que a
+ * tabela de nomes souber; senão fica `null` e o tipo é detectado pelo valor.
+ */
+function normalizarChaves(monotonicKey, tabela) {
+    const semTipo = (chave) => {
+        const conhecido = tipoConhecido(chave, tabela);
+        return conhecido
+            ? { chave, tipo: conhecido, origem: "conhecido" }
+            : { chave, tipo: null, origem: "detectado" };
+    };
+    if (typeof monotonicKey === "string")
+        return [semTipo(monotonicKey)];
+    if (Array.isArray(monotonicKey))
+        return monotonicKey.map(semTipo);
+    return Object.entries(monotonicKey).map(([chave, tipo]) => ({
+        chave,
+        tipo,
+        origem: "declarado",
+    }));
+}
+/** `a > b`, já sabendo que os dois lados são do mesmo tipo. */
+function maior(a, b) {
+    return typeof a === "string" ? a > String(b) : a > Number(b);
+}
+/**
+ * Compara todas as chaves monotônicas entre o dado em cache e o dado novo.
+ *
+ * Verificação estrita: o dado novo só entra quando TODAS as chaves cresceram.
+ * Basta uma que não cresça para a resposta ser descartada — e uma chave
+ * incomparável (ausente de um dos lados, ilegível, fora do tipo esperado ou
+ * com tipos divergentes entre as versões) também não cresceu, então também
+ * derruba a resposta. Só entra o que comprovadamente cresceu em todas.
+ */
+function avaliarMonotonicidade(oldData, newData, monotonicKey, tabela) {
+    const detalhes = [];
+    // Sem nenhuma chave configurada não há regra a aplicar, e o dado novo passa.
+    let todasCresceram = true;
+    // Avalia TODAS as chaves: nenhuma decide sozinha e nenhuma interrompe o laço,
+    // para que o log de debug mostre o estado de cada uma.
+    for (const { chave, tipo, origem } of normalizarChaves(monotonicKey, tabela)) {
+        const oldVal = getPath(oldData, chave);
+        const newVal = getPath(newData, chave);
+        const oldCmp = tipo ? classificarComTipo(oldVal, tipo) : classificar(oldVal);
+        const newCmp = tipo ? classificarComTipo(newVal, tipo) : classificar(newVal);
+        // Quando o tipo é conhecido, ele é quem manda — `100` e `"101"` sob
+        // "number" são o mesmo campo. Quando foi detectado pelo valor, tipos
+        // divergentes entre as versões (número de um lado, string do outro; string
+        // numérica vs. string de data) são sinal de que o campo mudou de forma.
+        const divergente = tipo === null &&
+            (typeof oldVal !== typeof newVal || (oldCmp === null || oldCmp === void 0 ? void 0 : oldCmp.tipo) !== (newCmp === null || newCmp === void 0 ? void 0 : newCmp.tipo));
+        // Incomparável não é "neutro": se a lib não consegue afirmar que a chave
+        // cresceu, ela não cresceu, e a resposta nova cai.
+        if (oldCmp === null || newCmp === null || divergente) {
+            todasCresceram = false;
+            detalhes.push({ chave, tipo: null, origem, oldVal, newVal, voto: "incomparável" });
+            continue;
+        }
+        const avancou = maior(newCmp.ordem, oldCmp.ordem);
+        if (!avancou)
+            todasCresceram = false;
+        detalhes.push({
+            chave,
+            tipo: newCmp.tipo,
+            origem,
+            oldVal,
+            newVal,
+            voto: avancou ? "avançou" : "não avançou",
+        });
+    }
+    return { avancou: todasCresceram, detalhes };
+}
 function isQuotaError(err) {
     return (err instanceof Error &&
         (err.name === "QuotaExceededError" ||
             err.name === "NS_ERROR_DOM_QUOTA_REACHED"));
 }
+/** Logger padrão do modo debug: imprime no console com um prefixo fixo. */
+function defaultLogger(message, details) {
+    if (details) {
+        console.debug(`[reqcache] ${message}`, details);
+    }
+    else {
+        console.debug(`[reqcache] ${message}`);
+    }
+}
 /** Retorna localStorage se existir e funcionar; senão null (SSR, modo privado...). */
 function getDefaultStorage() {
     try {