@sevn/reqcache 1.2.0 → 1.4.0

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,70 @@ 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>;
+/**
+ * Qualidade de rede estimada pelo browser (Network Information API).
+ * É uma ESTIMATIVA baseada em latência e throughput recentes, não o rádio do
+ * aparelho: um 4g congestionado é reportado como "2g" — que é exatamente o
+ * caso que interessa aqui.
+ */
+type EffectiveConnectionType = "slow-2g" | "2g" | "3g" | "4g";
+/**
+ * Timeout de UMA tentativa de fetch, em ms, por qualidade de rede.
+ * `desconhecida` é o que vale em SSR e nos browsers sem a Network Information
+ * API (Safari e Firefox).
+ */
+type TimeoutTiers = Partial<Record<EffectiveConnectionType | "desconhecida", number>>;
+/**
+ * Falha de HTTP com o status preservado. É o que permite decidir se vale a
+ * pena tentar o próximo domínio (503, sim) ou não (404).
+ */
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(status: number, url: string);
+}
 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;
     /**
@@ -58,6 +115,21 @@ interface GetFetchOptions {
      * (`url` + `fallbackUrls`). Útil para observabilidade/log.
      */
     onFallback?: (failedUrl: string, error: unknown) => void;
+    /**
+     * Timeout de CADA tentativa, em ms. Quando omitido, sai da tabela por rede
+     * (`timeoutTiers` na config). Vale por candidato, não pela fila toda: com
+     * dois `fallbackUrls`, o pior caso é 3x esse valor.
+     */
+    timeoutMs?: number;
+    /**
+     * Status HTTP que NÃO devem acionar o fallback. Padrão: `[404]`.
+     *
+     * Um 404 é uma resposta correta do servidor — "esse recurso não existe" —,
+     * não uma indisponibilidade. Repetir o mesmo caminho em outro domínio tende
+     * a devolver o mesmo 404, só que N vezes mais devagar, então o erro sobe na
+     * hora. Passe `[]` para voltar ao comportamento antigo (tentar todos).
+     */
+    statusSemFallback?: number[];
 }
 /** Uma entrada do cache. `rota` é a chave identificadora. */
 interface CacheEntry<T = unknown> {
@@ -88,6 +160,29 @@ interface RequestCacheConfig {
     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>;
+    /**
+     * Timeout de cada tentativa de fetch, por qualidade de rede do client.
+     * O que for passado aqui é mesclado sobre `TIMEOUTS_POR_REDE`:
+     *
+     *   new RequestCache({ timeoutTiers: { "slow-2g": 120_000 } })
+     *
+     * Um `timeoutMs` na chamada tem prioridade sobre esta tabela.
+     */
+    timeoutTiers?: TimeoutTiers;
 }
 declare class RequestCache {
     private storage;
@@ -98,6 +193,8 @@ declare class RequestCache {
     private tick;
     private debug;
     private logger;
+    private monotonicTypes;
+    private timeoutTiers;
     constructor(config?: RequestCacheConfig);
     /** Liga/desliga o modo debug em runtime, sem precisar recriar a instância. */
     setDebug(enabled: boolean): void;
@@ -122,10 +219,27 @@ declare class RequestCache {
     private nextAccess;
     /** Emite uma linha de log, só quando o modo debug está ligado. */
     private log;
+    /**
+     * Timeout de UMA tentativa, em ms. A ordem de prioridade é:
+     *   1. `timeoutMs` passado na chamada;
+     *   2. o tier da rede atual do client (`navigator.connection`);
+     *   3. o tier `desconhecida`, usado em SSR, Safari e Firefox.
+     *
+     * A rede é relida a cada tentativa de propósito: numa apuração o client pode
+     * sair do wi-fi e cair no 3g no meio da fila de fallback.
+     */
+    private resolverTimeout;
     /**
      * 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
      * último erro.
+     *
+     * Duas situações encerram a fila antes do fim, em vez de seguir para o
+     * próximo candidato:
+     *  - um status listado em `statusSemFallback` (padrão: 404). É resposta do
+     *    servidor, não indisponibilidade — o outro domínio diria o mesmo.
+     *  - o `signal` do chamador abortado. Foi cancelamento de quem pediu;
+     *    insistir só trocaria o erro real pelo AbortError do último candidato.
      */
     private fetchComRedundancia;
     private revalidate;
@@ -136,8 +250,21 @@ declare class RequestCache {
     private readAll;
     private writeAll;
 }
+/**
+ * Tier list de timeout por qualidade de rede, em ms, aplicado a CADA tentativa.
+ *
+ *   4g / desconhecida  30 s — base
+ *   3g                 45 s — 1,5x
+ *   2g                 60 s — 2x
+ *   slow-2g            90 s — 3x; borda de cobertura, interior
+ *
+ * A folga cresce com a rede ruim para não matar uma resposta que ainda viria
+ * num client lento. O custo aparece em `fallbackUrls`, porque a fila é
+ * sequencial: o pior caso é N x o tier — veja `timeoutMs` em GetFetchOptions.
+ */
+declare const TIMEOUTS_POR_REDE: Record<EffectiveConnectionType | "desconhecida", number>;
 /** Instância pronta para uso, caso não queira configurar nada. */
 declare const requestCache: RequestCache;
 
-export { RequestCache, requestCache };
-export type { CacheEntry, DebugLogFn, GetFetchOptions, RequestCacheConfig, StorageLike };
+export { HttpError, RequestCache, TIMEOUTS_POR_REDE, requestCache };
+export type { CacheEntry, DebugLogFn, EffectiveConnectionType, GetFetchOptions, MonotonicKey, MonotonicType, RequestCacheConfig, StorageLike, TimeoutTiers };

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
@@ -26,9 +26,21 @@
  *  - Deduplicação: chamadas simultâneas à mesma rota disparam 1 só fetch.
  *  - staleOnError: se a rede/API falhar, devolve o último dado válido.
  */
+/**
+ * Falha de HTTP com o status preservado. É o que permite decidir se vale a
+ * pena tentar o próximo domínio (503, sim) ou não (404).
+ */
+class HttpError extends Error {
+    constructor(status, url) {
+        super(`HTTP ${status} ao buscar ${url}`);
+        this.status = status;
+        this.url = url;
+        this.name = "HttpError";
+    }
+}
 class RequestCache {
     constructor(config = {}) {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d, _e, _f, _g;
         this.inflight = new Map();
         /** Relógio de acesso monotônico: sempre cresce, mesmo com acessos no mesmo ms. */
         this.tick = 0;
@@ -37,6 +49,8 @@ class RequestCache {
         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 : {}) };
+        this.timeoutTiers = { ...TIMEOUTS_POR_REDE, ...((_g = config.timeoutTiers) !== null && _g !== void 0 ? _g : {}) };
     }
     /** Liga/desliga o modo debug em runtime, sem precisar recriar a instância. */
     setDebug(enabled) {
@@ -115,27 +129,78 @@ class RequestCache {
             return;
         this.logger(message, details);
     }
+    /**
+     * Timeout de UMA tentativa, em ms. A ordem de prioridade é:
+     *   1. `timeoutMs` passado na chamada;
+     *   2. o tier da rede atual do client (`navigator.connection`);
+     *   3. o tier `desconhecida`, usado em SSR, Safari e Firefox.
+     *
+     * A rede é relida a cada tentativa de propósito: numa apuração o client pode
+     * sair do wi-fi e cair no 3g no meio da fila de fallback.
+     */
+    resolverTimeout(options) {
+        var _a;
+        if (typeof options.timeoutMs === "number")
+            return options.timeoutMs;
+        return this.timeoutTiers[(_a = detectarRede()) !== null && _a !== void 0 ? _a : "desconhecida"];
+    }
     /**
      * 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
      * último erro.
+     *
+     * Duas situações encerram a fila antes do fim, em vez de seguir para o
+     * próximo candidato:
+     *  - um status listado em `statusSemFallback` (padrão: 404). É resposta do
+     *    servidor, não indisponibilidade — o outro domínio diria o mesmo.
+     *  - o `signal` do chamador abortado. Foi cancelamento de quem pediu;
+     *    insistir só trocaria o erro real pelo AbortError do último candidato.
      */
     async fetchComRedundancia(candidatos, fetcher, options) {
-        var _a;
+        var _a, _b, _c, _d, _e;
+        const semFallback = new Set((_a = options.statusSemFallback) !== null && _a !== void 0 ? _a : STATUS_SEM_FALLBACK_PADRAO);
+        const externo = (_c = (_b = options.fetchOptions) === null || _b === void 0 ? void 0 : _b.signal) !== null && _c !== void 0 ? _c : null;
         let ultimoErro;
         for (const candidato of candidatos) {
-            this.log("fetch de rede", { url: candidato });
+            if (externo === null || externo === void 0 ? void 0 : externo.aborted) {
+                this.log("cancelado pelo chamador: fila interrompida", { url: candidato });
+                throw (_d = externo.reason) !== null && _d !== void 0 ? _d : new Error("Requisição cancelada pelo chamador");
+            }
+            const timeoutMs = this.resolverTimeout(options);
+            const tentativa = criarSinal(timeoutMs, externo);
+            this.log("fetch de rede", { url: candidato, timeoutMs, rede: detectarRede() });
             try {
-                const res = await fetcher(candidato, options.fetchOptions);
+                const res = await fetcher(candidato, {
+                    ...options.fetchOptions,
+                    signal: tentativa.signal,
+                });
                 if (!res.ok)
-                    throw new Error(`HTTP ${res.status} ao buscar ${candidato}`);
+                    throw new HttpError(res.status, candidato);
+                const json = (await res.json());
                 this.log("fetch OK", { url: candidato, status: res.status });
-                return (await res.json());
+                return json;
             }
-            catch (err) {
+            catch (bruto) {
+                // Um abort disparado pelo nosso timer chega aqui como AbortError
+                // genérico; troca por um erro que diz o que de fato aconteceu.
+                const err = tentativa.estourou()
+                    ? erroDeTimeout(candidato, timeoutMs)
+                    : bruto;
                 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);
+                (_e = options.onFallback) === null || _e === void 0 ? void 0 : _e.call(options, candidato, err);
+                if (err instanceof HttpError && semFallback.has(err.status)) {
+                    this.log("status sem fallback: fila interrompida", {
+                        url: candidato,
+                        status: err.status,
+                    });
+                    throw err;
+                }
+            }
+            finally {
+                // Obrigatório: sem isso sobra um timer de minutos pendurado por
+                // tentativa, segurando o event loop no Node e vazando no browser.
+                tentativa.cancelar();
             }
         }
         throw ultimoErro;
@@ -161,17 +226,15 @@ 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,
-                    oldVal,
-                    newVal,
+                    chaves: veredito.detalhes,
                 });
                 this.upsert({
                     ...cached,
@@ -261,6 +324,260 @@ 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 };
+}
+/** Status que, por padrão, NÃO acionam o fallback: o servidor já respondeu. */
+const STATUS_SEM_FALLBACK_PADRAO = [404];
+/**
+ * Tier list de timeout por qualidade de rede, em ms, aplicado a CADA tentativa.
+ *
+ *   4g / desconhecida  30 s — base
+ *   3g                 45 s — 1,5x
+ *   2g                 60 s — 2x
+ *   slow-2g            90 s — 3x; borda de cobertura, interior
+ *
+ * A folga cresce com a rede ruim para não matar uma resposta que ainda viria
+ * num client lento. O custo aparece em `fallbackUrls`, porque a fila é
+ * sequencial: o pior caso é N x o tier — veja `timeoutMs` em GetFetchOptions.
+ */
+const TIMEOUTS_POR_REDE = {
+    "slow-2g": 90000,
+    "2g": 60000,
+    "3g": 45000,
+    "4g": 30000,
+    desconhecida: 30000,
+};
+const REDES_CONHECIDAS = ["slow-2g", "2g", "3g", "4g"];
+/**
+ * Lê `navigator.connection.effectiveType` (Network Information API).
+ * Só Chromium e Android implementam; Safari, Firefox e SSR devolvem `null` e
+ * caem no tier `desconhecida`.
+ */
+function detectarRede() {
+    var _a, _b;
+    try {
+        if (typeof navigator === "undefined")
+            return null;
+        const nav = navigator;
+        const conexao = (_b = (_a = nav.connection) !== null && _a !== void 0 ? _a : nav.mozConnection) !== null && _b !== void 0 ? _b : nav.webkitConnection;
+        const tipo = conexao === null || conexao === void 0 ? void 0 : conexao.effectiveType;
+        if (!tipo)
+            return null;
+        return REDES_CONHECIDAS.indexOf(tipo) >= 0
+            ? tipo
+            : null;
+    }
+    catch (_c) {
+        return null;
+    }
+}
+/** Erro dedicado do timeout, para não subir como um `AbortError` sem contexto. */
+function erroDeTimeout(url, timeoutMs) {
+    const err = new Error(`Timeout de ${timeoutMs}ms ao buscar ${url}`);
+    err.name = "TimeoutError";
+    return err;
+}
+/**
+ * Monta o `signal` de UMA tentativa: o timeout da vez encadeado com o `signal`
+ * que o chamador passou em `fetchOptions`, para que cancelar por fora continue
+ * funcionando.
+ *
+ * Feito na mão com `AbortController` em vez de `AbortSignal.any` +
+ * `AbortSignal.timeout`, que só existem em Safari 17.4+ e Node 20+. Também
+ * evita o problema de um `AbortSignal.timeout` passado pelo chamador: o
+ * relógio dele começa na criação, então viraria um orçamento da fila inteira,
+ * deixando os fallbacks sem tempo nenhum.
+ */
+function criarSinal(timeoutMs, externo) {
+    if (!(timeoutMs > 0) || typeof AbortController === "undefined") {
+        return {
+            signal: externo !== null && externo !== void 0 ? externo : undefined,
+            estourou: () => false,
+            cancelar: () => { },
+        };
+    }
+    const ctrl = new AbortController();
+    let porTimeout = false;
+    const timer = setTimeout(() => {
+        porTimeout = true;
+        ctrl.abort();
+    }, timeoutMs);
+    const repassar = () => ctrl.abort();
+    if (externo) {
+        if (externo.aborted)
+            ctrl.abort();
+        else
+            externo.addEventListener("abort", repassar);
+    }
+    return {
+        signal: ctrl.signal,
+        estourou: () => porTimeout,
+        cancelar: () => {
+            clearTimeout(timer);
+            externo === null || externo === void 0 ? void 0 : externo.removeEventListener("abort", repassar);
+        },
+    };
+}
 function isQuotaError(err) {
     return (err instanceof Error &&
         (err.name === "QuotaExceededError" ||
@@ -293,5 +610,5 @@ function getDefaultStorage() {
 /** Instância pronta para uso, caso não queira configurar nada. */
 const requestCache = new RequestCache();
 
-export { RequestCache, requestCache };
+export { HttpError, RequestCache, TIMEOUTS_POR_REDE, requestCache };
 //# sourceMappingURL=index.esm.js.map