@wenathlan/saddle 1.8.17 → 2.0.2

package/docs/plans/17.research.caching.md

@@ -1,1610 +0,0 @@
-# Pesquisa: Caching Strategies para Web Scraping (2026)
-
-## Table of Contents
-
-- [Visão Geral](#visão-geral)
-- [HTTP Response Caching](#http-response-caching)
-- [In-Memory Caches](#in-memory-caches)
-- [Abstraction Layers](#abstraction-layers)
-- [Disk-Based Caching](#disk-based-caching)
-- [TTL Strategies por Tipo de Conteúdo](#ttl-strategies-por-tipo-de-conteúdo)
-- [Cache Invalidation](#cache-invalidation)
-- [Crawlee Request Deduplication](#crawlee-request-deduplication)
-- [Playwright Response Caching](#playwright-response-caching)
-- [Multi-Layer Architecture](#multi-layer-architecture)
-- [Código Completo](#código-completo)
-
----
-
-## Visão Geral
-
-Caching em web scraping serve para três propósitos principais:
-
-1. **Reduzir requests HTTP** — Evitar baixar o mesmo conteúdo repetidamente
-2. **Aumentar velocidade** — Respostas do cache são instantâneas vs. rede
-3. **Respeitar rate limits** — Menos requests = menos chance de bloqueio
-
-### Estratégias de Caching
-
-| Nível | Armazenamento | Latência | Persistência | Caso de Uso |
-|---|---|---|---|---|
-| L1 | Memória (RAM) | <1ms | Volátil | Cache quente |
-| L2 | Disco | 1-10ms | Persistente | Cache frio |
-| HTTP | CDN/Proxy | Variável | Variável | Cache de rede |
-| Browser | Playwright Page | N/A | Sessão | Cache de sessão |
-
----
-
-## HTTP Response Caching
-
-### ETag / If-None-Match
-
-O servidor retorna um `ETag` (hash do conteúdo). Na próxima request, o cliente envia `If-None-Match` com o ETag. Se o conteúdo não mudou, o servidor retorna `304 Not Modified` (sem corpo).
-
-```ts
-import { gotScraping } from 'got-scraping';
-
-class EtagCache {
-    private store = new Map<string, { etag: string; body: string; timestamp: number }>();
-
-    async fetch(url: string): Promise<{ body: string; fromCache: boolean }> {
-        const cached = this.store.get(url);
-
-        const headers: Record<string, string> = {};
-        if (cached?.etag) {
-            headers['If-None-Match'] = cached.etag;
-        }
-
-        const response = await gotScraping(url, {
-            headers,
-            throwHttpErrors: false,
-        });
-
-        if (response.statusCode === 304 && cached) {
-            console.log(`ETag HIT: ${url}`);
-            return { body: cached.body, fromCache: true };
-        }
-
-        const etag = response.headers['etag'];
-        if (etag) {
-            this.store.set(url, {
-                etag,
-                body: response.body,
-                timestamp: Date.now(),
-            });
-        }
-
-        console.log(`ETag MISS: ${url}`);
-        return { body: response.body, fromCache: false };
-    }
-}
-
-const cache = new EtagCache();
-const result = await cache.fetch('https://example.com/api/data');
-// Primeira request: MISS, baixa conteúdo, armazena ETag
-// Segunda request: HIT, servidor retorna 304, usa cache local
-```
-
-### Last-Modified / If-Modified-Since
-
-Similar ao ETag, mas usa timestamps. O servidor retorna `Last-Modified` e o cliente envia `If-Modified-Since`.
-
-```ts
-import { gotScraping } from 'got-scraping';
-
-class ModifiedCache {
-    private store = new Map<string, {
-        lastModified: string;
-        body: string;
-        timestamp: number;
-    }>();
-
-    async fetch(url: string): Promise<{ body: string; fromCache: boolean }> {
-        const cached = this.store.get(url);
-
-        const headers: Record<string, string> = {};
-        if (cached?.lastModified) {
-            headers['If-Modified-Since'] = cached.lastModified;
-        }
-
-        const response = await gotScraping(url, {
-            headers,
-            throwHttpErrors: false,
-        });
-
-        if (response.statusCode === 304 && cached) {
-            console.log(`Last-Modified HIT: ${url}`);
-            return { body: cached.body, fromCache: true };
-        }
-
-        const lastModified = response.headers['last-modified'];
-        if (lastModified) {
-            this.store.set(url, {
-                lastModified,
-                body: response.body,
-                timestamp: Date.now(),
-            });
-        }
-
-        console.log(`Last-Modified MISS: ${url}`);
-        return { body: response.body, fromCache: false };
-    }
-}
-```
-
-### Cache-Control Directives
-
-`Cache-Control` define regras de caching do lado do servidor:
-
-| Diretiva | Significado |
-|---|---|
-| `max-age=N` | Cache válido por N segundos |
-| `no-cache` | Revalidar antes de usar cache |
-| `no-store` | Não armazenar em cache |
-| `must-revalidate` | Revalidar quando expirar |
-| `public` | Pode ser cacheado por CDNs |
-| `private` | Só o cliente pode cachear |
-| `s-maxage=N` | Max-age para shared caches (CDNs) |
-
-```ts
-import { gotScraping } from 'got-scraping';
-
-function parseCacheControl(header: string): Record<string, string | boolean> {
-    const directives: Record<string, string | boolean> = {};
-
-    for (const part of header.split(',')) {
-        const [key, value] = part.trim().split('=');
-        directives[key.trim()] = value?.trim() ?? true;
-    }
-
-    return directives;
-}
-
-function getCacheMaxAge(url: string, headers: Record<string, string>): number | null {
-    const cacheControl = headers['cache-control'];
-    if (!cacheControl) return null;
-
-    const directives = parseCacheControl(cacheControl);
-
-    if (directives['no-store'] || directives['no-cache']) {
-        return 0; // Não cachear
-    }
-
-    const maxAge = directives['max-age'] ?? directives['s-maxage'];
-    if (typeof maxAge === 'string') {
-        return Number.parseInt(maxAge, 10) * 1000; // Converter para ms
-    }
-
-    return null;
-}
-
-class SmartCache {
-    private store = new Map<string, { body: string; expiry: number }>();
-
-    async fetch(url: string): Promise<{ body: string; fromCache: boolean }> {
-        const cached = this.store.get(url);
-
-        // Verificar se cache ainda é válido
-        if (cached && cached.expiry > Date.now()) {
-            console.log(`Cache HIT: ${url}`);
-            return { body: cached.body, fromCache: true };
-        }
-
-        // Buscar novo conteúdo
-        const response = await gotScraping(url, { throwHttpErrors: false });
-
-        if (response.statusCode === 200) {
-            const maxAge = getCacheMaxAge(url, response.headers as Record<string, string>);
-
-            if (maxAge === null || maxAge > 0) {
-                this.store.set(url, {
-                    body: response.body,
-                    expiry: Date.now() + (maxAge ?? 300_000), // Default 5 min
-                });
-            }
-        }
-
-        console.log(`Cache MISS: ${url}`);
-        return { body: response.body, fromCache: false };
-    }
-}
-```
-
----
-
-## In-Memory Caches
-
-### lru-cache 11.x
-
-`lru-cache` é a biblioteca de cache LRU mais popular no Node.js. Versão 11.x adiciona suporte a `fetchMethod` para cache transparente.
-
-**Características:**
-- LRU (Least Recently Used) eviction
-- TTL (Time-To-Live) por item
-- `fetchMethod` para cache transparente
-- Max size com weighted size
-- Stale-while-revalidate pattern
-
-```ts
-import { LRUCache } from 'lru-cache';
-
-// Cache básico
-const cache = new LRUCache<string, string>({
-    max: 500,                    // Máximo 500 itens
-    ttl: 1000 * 60 * 5,         // TTL de 5 minutos
-});
-
-cache.set('key1', 'value1');
-const value = cache.get('key1');
-// → 'value1'
-
-// Cache com fetchMethod (transparente)
-const apiCache = new LRUCache<string, string>({
-    max: 100,
-    ttl: 1000 * 60 * 10,        // 10 minutos
-    fetchMethod: async (key) => {
-        console.log(`Buscando: ${key}`);
-        const response = await fetch(key);
-        return response.text();
-    },
-});
-
-// Se a chave existe, retorna do cache. Se não, busca e armazena.
-const html = await apiCache.fetch('https://example.com');
-// → Busca da web e armazena
-
-const cached = await apiCache.fetch('https://example.com');
-// → Retorna do cache (sem buscar)
-
-// Cache com stale-while-revalidate
-const swrCache = new LRUCache<string, string>({
-    max: 100,
-    ttl: 1000 * 60 * 5,          // 5 min para fresh
-    allowStale: true,             // Permitir stale
-    updateAgeOnGet: true,         // Renovar TTL ao acessar
-    fetchMethod: async (key) => {
-        const response = await fetch(key);
-        return response.text();
-    },
-});
-
-// Retorna stale imediatamente, revalida em background
-const html2 = await swrCache.fetch('https://example.com');
-```
-
-### node-cache 5.7.7
-
-`node-cache` é uma alternativa simples com suporte nativo a stdTTL e eventos.
-
-```ts
-import NodeCache from 'node-cache';
-
-const cache = new NodeCache({
-    stdTTL: 300,          // TTL padrão de 5 minutos
-    checkperiod: 60,      // Verificar expirados a cada 60s
-    useClones: false,     // Não clonar valores (performance)
-});
-
-// Set com TTL customizado
-cache.set('key1', 'value1', 600);  // 10 minutos
-cache.set('key2', 'value2');       // TTL padrão (5 min)
-
-// Get
-const value = cache.get<string>('key1');
-
-// Eventos
-cache.on('expired', (key, value) => {
-    console.log(`Chave expirada: ${key}`);
-});
-
-cache.on('del', (key, value) => {
-    console.log(`Chave deletada: ${key}`);
-});
-
-// Stats
-const stats = cache.getStats();
-console.log(`Hits: ${stats.hits}, Misses: ${stats.misses}`);
-```
-
-### quick-lru 7.x
-
-`quick-lru` é uma implementação LRU ultraleve e rápida. Sem TTL, sem features extras — apenas LRU puro.
-
-```ts
-import QuickLRU from 'quick-lru';
-
-const cache = new QuickLRU<string, string>({
-    maxSize: 1000,
-});
-
-cache.set('key1', 'value1');
-cache.get('key1');
-// → 'value1'
-
-// Iterador
-for (const [key, value] of cache) {
-    console.log(`${key}: ${value}`);
-}
-
-// Resizing
-cache.resize(2000);
-```
-
-### Comparação de In-Memory Caches
-
-| Feature | lru-cache 11.x | node-cache 5.7 | quick-lru 7.x |
-|---|---|---|---|
-| LRU | ✅ | ❌ (FIFO) | ✅ |
-| TTL | ✅ | ✅ | ❌ |
-| fetchMethod | ✅ | ❌ | ❌ |
-| Eventos | ❌ | ✅ | ❌ |
-| Tamanho | ~20KB | ~15KB | ~3KB |
-| Performance | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ |
-| Use case | Geral | Simples | Performance |
-
----
-
-## Abstraction Layers
-
-### cache-manager 7.2.8
-
-`cache-manager` abstrai o storage e permite trocar backends (memória, Redis, S3, etc.) sem mudar código.
-
-**Características:**
-- Multi-store (L1 + L2)
-- Store switching (memória → Redis)
-- Wrap pattern (cache transparente)
-- Eventos
-
-```ts
-import { caching } from 'cache-manager';
-
-// Cache de memória
-const memoryCache = await caching('memory', {
-    max: 1000,
-    ttl: 300, // 5 minutos
-});
-
-// Usar
-await memoryCache.set('key1', 'value1', 600); // TTL de 10 min
-const value = await memoryCache.get<string>('key1');
-
-// Wrap — cache transparente
-const data = await memoryCache.wrap('expensive-query', async () => {
-    // Esta função só executa se não houver cache
-    const result = await fetchExpensiveData();
-    return result;
-}, { ttl: 600 });
-
-// Store de Redis (se disponível)
-// import { redisStore } from 'cache-manager-redis-yet';
-// const redisCache = await caching(redisStore, {
-//     host: 'localhost',
-//     port: 6379,
-//     ttl: 300,
-// });
-```
-
-### keyv 4.x
-
-`keyv` é uma abstração simples com suporte a múltiplos backends via plugins.
-
-```ts
-import Keyv from 'keyv';
-
-// Cache de memória
-const cache = new Keyv({ ttl: 300_000 }); // 5 min
-
-// Usar
-await cache.set('key1', 'value1');
-const value = await cache.get('key1');
-
-// Com Redis (se disponível)
-// import KeyvRedis from '@keyv/redis';
-// const cache = new Keyv(new KeyvRedis('redis://localhost:6379'));
-
-// Namespace
-const userCache = new Keyv({ namespace: 'users' });
-const productCache = new Keyv({ namespace: 'products' });
-
-await userCache.set('user:123', { name: 'João' });
-await productCache.set('product:456', { name: 'Produto' });
-
-// Iteração
-for await (const [key, value] of cache.iterator()) {
-    console.log(`${key}: ${value}`);
-}
-```
-
----
-
-## Disk-Based Caching
-
-### cacache 21.0.0
-
-`cacache` é um cache content-addressable (baseado em hash do conteúdo). Usado pelo npm internamente.
-
-**Características:**
-- Content-addressable (hash SHA-512 do conteúdo)
-- Integrity verification automática
-- Suporte a metadados
-- Compactação
-- Não expira por padrão (usar cleanup manual)
-
-```ts
-import cacache from 'cacache';
-import { tmpdir } from 'os';
-import { join } from 'path';
-
-const CACHE_DIR = join(tmpdir(), 'my-scraper-cache');
-
-// Armazenar
-const data = { url: 'https://example.com', content: '<html>...</html>' };
-await cacache.put(CACHE_DIR, 'https://example.com', JSON.stringify(data));
-
-// Recuperar
-const cached = await cacache.get(CACHE_DIR, 'https://example.com');
-if (cached) {
-    const parsed = JSON.parse(cached.data.toString());
-    console.log('Cache HIT:', parsed.url);
-}
-
-// Verificar se existe
-const hasKey = await cacache.get(CACHE_DIR, 'https://example.com');
-console.log('Existe:', !!hasKey);
-
-// Deletar
-await cacache.rm(CACHE_DIR, 'https://example.com');
-
-// Listar todas as chaves
-const entries = await cacache.ls(CACHE_DIR);
-for (const [key, entry] of Object.entries(entries)) {
-    console.log(`${key}: ${entry.integrity}`);
-}
-
-// Cleanup de entradas antigas
-const { entries: allEntries } = await cacache.get(CACHE_DIR);
-```
-
-### flat-cache 6.1.22
-
-`flat-cache` armazena tudo em um único arquivo JSON. Simples e rápido para caches pequenos.
-
-```ts
-import flatCache from 'flat-cache';
-import { join } from 'path';
-
-const cacheDir = join(process.cwd(), '.cache');
-const cache = flatCache.load('scraper-cache', cacheDir);
-
-// Set
-cache.set('https://example.com', {
-    content: '<html>...</html>',
-    timestamp: Date.now(),
-});
-cache.save(true); // true = pretty print
-
-// Get
-const cached = cache.getKey('https://example.com');
-console.log(cached);
-
-// Deletar
-cache.removeKey('https://example.com');
-
-// Listar
-const keys = cache.allKeys();
-console.log(keys);
-
-// Cleanup de itens antigos
-const allEntries = cache.all();
-const oneHourAgo = Date.now() - 3600_000;
-
-for (const [key, entry] of Object.entries(allEntries)) {
-    if ((entry as any).timestamp < oneHourAgo) {
-        cache.removeKey(key);
-    }
-}
-cache.save();
-```
-
-### Comparação de Disk-Based Caches
-
-| Feature | cacache 21.0 | flat-cache 6.1 |
-|---|---|---|
-| Armazenamento | Content-addressable | JSON file |
-| Integridade | SHA-512 automática | Nenhuma |
-| Performance | ⭐⭐⭐ | ⭐⭐⭐⭐ |
-| Tamanho | Grande (hashes) | Pequeno |
-| Use case | Cache robusto | Cache simples |
-| Cleanup | Manual | Manual |
-
----
-
-## TTL Strategies por Tipo de Conteúdo
-
-### Estimativas de TTL
-
-| Tipo de Conteúdo | TTL | Exemplo |
-|---|---|---|
-| **Estático** | 24-72 horas | Páginas de termos, sobre, FAQ |
-| **Semi-estático** | 4-24 horas | Blog posts, documentação |
-| **Dinâmico** | 30 min - 4 horas | Páginas de produto, preços |
-| **Tempo real** | 30 segundos - 5 minutos | Busca, feed, cotações |
-| **Transacional** | 0 (não cachear) | Checkout, login, pagamento |
-
-### Implementação por Tipo
-
-```ts
-import { LRUCache } from 'lru-cache';
-
-enum ContentType {
-    STATIC = 'static',
-    SEMI_STATIC = 'semi-static',
-    DYNAMIC = 'dynamic',
-    REALTIME = 'realtime',
-    TRANSACTIONAL = 'transactional',
-}
-
-const TTL_CONFIG: Record<ContentType, { ttl: number; staleWhileRevalidate?: number }> = {
-    [ContentType.STATIC]: {
-        ttl: 1000 * 60 * 60 * 24, // 24 horas
-        staleWhileRevalidate: 1000 * 60 * 60 * 48, // 48h stale
-    },
-    [ContentType.SEMI_STATIC]: {
-        ttl: 1000 * 60 * 60 * 4, // 4 horas
-        staleWhileRevalidate: 1000 * 60 * 60 * 12, // 12h stale
-    },
-    [ContentType.DYNAMIC]: {
-        ttl: 1000 * 60 * 30, // 30 minutos
-        staleWhileRevalidate: 1000 * 60 * 60, // 1h stale
-    },
-    [ContentType.REALTIME]: {
-        ttl: 1000 * 30, // 30 segundos
-        staleWhileRevalidate: 1000 * 60, // 1 minuto stale
-    },
-    [ContentType.TRANSACTIONAL]: {
-        ttl: 0, // Não cachear
-    },
-};
-
-function classifyContentType(url: string): ContentType {
-    const parsed = new URL(url);
-    const path = parsed.pathname.toLowerCase();
-
-    if (path.match(/\.(css|js|png|jpg|gif|svg|ico|woff2?)$/)) {
-        return ContentType.STATIC;
-    }
-
-    if (path.startsWith('/terms') || path.startsWith('/privacy') || path.startsWith('/about')) {
-        return ContentType.STATIC;
-    }
-
-    if (path.startsWith('/blog/') || path.startsWith('/docs/')) {
-        return ContentType.SEMI_STATIC;
-    }
-
-    if (path.startsWith('/products/') || path.startsWith('/categories/')) {
-        return ContentType.DYNAMIC;
-    }
-
-    if (path.startsWith('/search') || path.startsWith('/api/search')) {
-        return ContentType.REALTIME;
-    }
-
-    if (path.startsWith('/checkout') || path.startsWith('/cart')) {
-        return ContentType.TRANSACTIONAL;
-    }
-
-    return ContentType.DYNAMIC;
-}
-
-// Cache com TTL dinâmico
-class DynamicTTLCache {
-    private cache = new LRUCache<string, { body: string; type: ContentType }>({
-        max: 1000,
-    });
-
-    async fetch(url: string, fetcher: () => Promise<string>): Promise<string> {
-        const type = classifyContentType(url);
-        const config = TTL_CONFIG[type];
-
-        if (config.ttl === 0) {
-            // Não cachear
-            return fetcher();
-        }
-
-        const cached = this.cache.get(url);
-        if (cached && cached.type === type) {
-            return cached.body;
-        }
-
-        const body = await fetcher();
-        this.cache.set(url, { body, type }, { ttl: config.ttl });
-
-        return body;
-    }
-}
-```
-
-### Detecção de Tipo via Headers
-
-```ts
-function detectContentType(headers: Record<string, string>): ContentType {
-    const contentType = headers['content-type'] ?? '';
-    const cacheControl = headers['cache-control'] ?? '';
-
-    // Se servidor diz "no-store", não cachear
-    if (cacheControl.includes('no-store')) {
-        return ContentType.TRANSACTIONAL;
-    }
-
-    // Se servidor diz "max-age", usar esse valor
-    const maxAgeMatch = cacheControl.match(/max-age=(\d+)/);
-    if (maxAgeMatch) {
-        const maxAge = Number.parseInt(maxAgeMatch[1], 10);
-        if (maxAge <= 60) return ContentType.REALTIME;
-        if (maxAge <= 3600) return ContentType.DYNAMIC;
-        if (maxAge <= 86400) return ContentType.SEMI_STATIC;
-        return ContentType.STATIC;
-    }
-
-    // Classificar por content-type
-    if (contentType.includes('json')) return ContentType.DYNAMIC;
-    if (contentType.includes('html')) return ContentType.SEMI_STATIC;
-    if (contentType.includes('image') || contentType.includes('css') || contentType.includes('js')) {
-        return ContentType.STATIC;
-    }
-
-    return ContentType.DYNAMIC;
-}
-```
-
----
-
-## Cache Invalidation
-
-### TTL-Based
-
-O formato mais simples: cada item tem um TTL e é automaticamente removido quando expira.
-
-```ts
-import { LRUCache } from 'lru-cache';
-
-const cache = new LRUCache<string, string>({
-    max: 1000,
-    ttl: 1000 * 60 * 5, // 5 minutos
-});
-
-// Item expira automaticamente após 5 minutos
-cache.set('key', 'value');
-```
-
-### Explicit Invalidation
-
-Delete manualmente quando o conteúdo muda.
-
-```ts
-class ExplicitCache {
-    private cache = new Map<string, { body: string; version: number }>();
-
-    set(url: string, body: string): void {
-        const existing = this.cache.get(url);
-        this.cache.set(url, {
-            body,
-            version: (existing?.version ?? 0) + 1,
-        });
-    }
-
-    get(url: string): string | null {
-        return this.cache.get(url)?.body ?? null;
-    }
-
-    invalidate(url: string): void {
-        this.cache.delete(url);
-    }
-
-    invalidatePattern(pattern: RegExp): number {
-        let count = 0;
-        for (const key of this.cache.keys()) {
-            if (pattern.test(key)) {
-                this.cache.delete(key);
-                count++;
-            }
-        }
-        return count;
-    }
-
-    invalidateAll(): void {
-        this.cache.clear();
-    }
-}
-
-const cache = new ExplicitCache();
-cache.set('https://example.com/page1', 'content1');
-
-// Invalidar uma URL
-cache.invalidate('https://example.com/page1');
-
-// Invalidar todas as URLs de um domínio
-cache.invalidatePattern(/^https:\/\/example\.com\//);
-```
-
-### Versioned Keys
-
-Cada versão do conteúdo tem uma chave diferente. Cache antigo continua válido até expirar.
-
-```ts
-class VersionedCache {
-    private cache = new Map<string, { body: string; version: number }>();
-    private versions = new Map<string, number>();
-
-    getCurrentVersion(url: string): number {
-        return this.versions.get(url) ?? 0;
-    }
-
-    set(url: string, body: string): void {
-        const version = this.getCurrentVersion(url) + 1;
-        this.versions.set(url, version);
-        this.cache.set(`${url}#v${version}`, { body, version });
-    }
-
-    get(url: string): string | null {
-        const version = this.getCurrentVersion(url);
-        if (version === 0) return null;
-
-        const cached = this.cache.get(`${url}#v${version}`);
-        return cached?.body ?? null;
-    }
-
-    // Versão específica
-    getAtVersion(url: string, version: number): string | null {
-        const cached = this.cache.get(`${url}#v${version}`);
-        return cached?.body ?? null;
-    }
-
-    // Limpar versões antigas (manter últimas N)
-    cleanup(url: string, keepLast: number = 3): void {
-        const currentVersion = this.getCurrentVersion(url);
-        const versionsToDelete = currentVersion - keepLast;
-
-        for (let v = 1; v <= versionsToDelete; v++) {
-            this.cache.delete(`${url}#v${v}`);
-        }
-    }
-}
-
-const cache = new VersionedCache();
-cache.set('https://example.com', 'v1');
-cache.set('https://example.com', 'v2');
-cache.set('https://example.com', 'v3');
-
-console.log(cache.get('https://example.com'));          // v3
-console.log(cache.getAtVersion('https://example.com', 1)); // v1
-```
-
-### Pattern-Based Invalidation
-
-Invalidar múltiplas chaves que correspondem a um padrão.
-
-```ts
-class PatternCache {
-    private cache = new Map<string, string>();
-
-    set(key: string, value: string): void {
-        this.cache.set(key, value);
-    }
-
-    get(key: string): string | null {
-        return this.cache.get(key) ?? null;
-    }
-
-    invalidate(pattern: string | RegExp): string[] {
-        const deleted: string[] = [];
-        const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
-
-        for (const key of this.cache.keys()) {
-            if (regex.test(key)) {
-                this.cache.delete(key);
-                deleted.push(key);
-            }
-        }
-
-        return deleted;
-    }
-
-    // Invalidar por domínio
-    invalidateDomain(domain: string): string[] {
-        return this.invalidate(new RegExp(`^https?://${domain.replace('.', '\\.')}/`));
-    }
-
-    // Invalidar por path
-    invalidatePath(path: string): string[] {
-        return this.invalidate(new RegExp(`${path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
-    }
-}
-
-const cache = new PatternCache();
-cache.set('https://example.com/page1', 'c1');
-cache.set('https://example.com/page2', 'c2');
-cache.set('https://other.com/page1', 'c3');
-
-const deleted = cache.invalidateDomain('example.com');
-// → ['https://example.com/page1', 'https://example.com/page2']
-```
-
-### Event-Driven Invalidation
-
-Invalidar cache quando um evento externo ocorre.
-
-```ts
-import { EventEmitter } from 'events';
-
-class EventDrivenCache extends EventEmitter {
-    private cache = new Map<string, { body: string; tags: string[] }>();
-
-    set(url: string, body: string, tags: string[] = []): void {
-        this.cache.set(url, { body, tags });
-    }
-
-    get(url: string): string | null {
-        return this.cache.get(url)?.body ?? null;
-    }
-
-    // Invalidar por tag
-    invalidateTag(tag: string): string[] {
-        const deleted: string[] = [];
-
-        for (const [key, entry] of this.cache.entries()) {
-            if (entry.tags.includes(tag)) {
-                this.cache.delete(key);
-                deleted.push(key);
-            }
-        }
-
-        this.emit('invalidated', { tag, count: deleted.length });
-        return deleted;
-    }
-
-    // Invalidar quando conteúdo muda
-    onContentChange(url: string, tags: string[]): void {
-        // Invalidar todas as entradas com tags relacionadas
-        for (const tag of tags) {
-            this.invalidateTag(tag);
-        }
-    }
-}
-
-const cache = new EventDrivenCache();
-cache.on('invalidated', ({ tag, count }) => {
-    console.log(`Tag "${tag}" invalidou ${count} entradas`);
-});
-
-cache.set('https://example.com/products', 'products-list', ['products', 'homepage']);
-cache.set('https://example.com/product/1', 'product-1', ['products', 'product-1']);
-cache.set('https://example.com/blog', 'blog-list', ['blog', 'homepage']);
-
-cache.invalidateTag('products');
-// → Invalidou 2 entradas
-```
-
----
-
-## Crawlee Request Deduplication
-
-### uniqueKey
-
-Crawlee usa `uniqueKey` para deduplicação automática de requests. Cada request tem uma chave única derivada da URL e opções.
-
-```ts
-import { PlaywrightCrawler } from 'crawlee';
-
-const crawler = new PlaywrightCrawler({
-    requestHandlerTimeoutSecs: 30,
-    async requestHandler({ page, enqueueLinks, request }) {
-        // Crawlee automaticamente ignora URLs duplicadas
-        // baseado no uniqueKey
-
-        const links = await page.$$eval('a[href]', anchors =>
-            anchors.map(a => a.href)
-        );
-
-        // enqueueLinks deduplica automaticamente
-        await enqueueLinks({ urls: links });
-    },
-});
-
-// Crawlee mantém um set de uniqueKeys em memória e disco
-// URLs com o mesmo uniqueKey são ignoradas
-```
-
-### customKeyFunction
-
-Para customizar a deduplicação (ex: ignorar query params):
-
-```ts
-import { PlaywrightCrawler, Request } from 'crawlee';
-
-const crawler = new PlaywrightCrawler({
-    requestHandlerTimeoutSecs: 30,
-    async requestHandler({ page, enqueueLinks }) {
-        const links = await page.$$eval('a[href]', anchors =>
-            anchors.map(a => a.href)
-        );
-
-        // Criar requests com chave customizada
-        for (const url of links) {
-            const request = new Request({
-                url,
-                // Crawlee usa URL como uniqueKey por padrão
-                // Para customizar, usar手動 construction
-            });
-        }
-
-        // Ou usar glob patterns no enqueueLinks
-        await enqueueLinks({
-            globs: ['https://example.com/**'],
-            exclude: ['**/page=*'],  // Excluir paginação
-        });
-    },
-});
-```
-
-### Request Queue Persistence
-
-O `RequestQueue` persiste em disco (SQLite via `@crawlee/storage`), sobrevivendo a crashes:
-
-```ts
-import { RequestQueue, PlaywrightCrawler } from 'crawlee';
-
-// Abrir fila persistente
-const queue = await RequestQueue.open('my-crawl-queue');
-
-// Adicionar request
-await queue.addRequest({
-    url: 'https://example.com',
-    userData: { depth: 0 },
-});
-
-// Abrir crawler com fila existente
-const crawler = new PlaywrightCrawler({
-    requestQueue: queue,
-    async requestHandler({ page, request }) {
-        // Processar...
-    },
-});
-
-// Mesmo após crash, a fila continua de onde parou
-await crawler.run(); // Retoma automaticamente
-```
-
----
-
-## Playwright Response Caching
-
-### page.route() Interception
-
-Interceptar responses no Playwright para cache de sessão:
-
-```ts
-import { chromium } from 'playwright';
-
-class PlaywrightCache {
-    private cache = new Map<string, { body: string; headers: Record<string, string> }>();
-
-    async setupCache(page: any): Promise<void> {
-        await page.route('**/*', async (route: any) => {
-            const url = route.request().url();
-            const cached = this.cache.get(url);
-
-            if (cached) {
-                console.log(`Playwright cache HIT: ${url}`);
-                await route.fulfill({
-                    status: 200,
-                    contentType: 'text/html',
-                    body: cached.body,
-                });
-                return;
-            }
-
-            // Continuar request normalmente
-            const response = await route.fetch();
-            const body = await response.text();
-
-            // Armazenar em cache
-            this.cache.set(url, {
-                body,
-                headers: response.headers(),
-            });
-
-            await route.fulfill({
-                status: response.status(),
-                headers: response.headers(),
-                body,
-            });
-        });
-    }
-}
-
-// Usar
-const browser = await chromium.launch();
-const context = await browser.newContext();
-const page = await context.newPage();
-
-const cache = new PlaywrightCache();
-await cache.setupCache(page);
-
-// Primeira visita: baixa da web
-await page.goto('https://example.com');
-// Segunda visita: usa cache
-await page.goto('https://example.com');
-```
-
-### Cache com Estratégia de Revalidação
-
-```ts
-import { chromium } from 'playwright';
-
-class RevalidatingCache {
-    private cache = new Map<string, {
-        body: string;
-        etag?: string;
-        lastModified?: string;
-        expiry: number;
-    }>();
-
-    async setupCache(page: any, defaultTtl = 300_000): Promise<void> {
-        await page.route('**/*', async (route: any) => {
-            const url = route.request().url();
-            const cached = this.cache.get(url);
-
-            // Verificar se cache ainda é válido
-            if (cached && cached.expiry > Date.now()) {
-                console.log(`Cache HIT: ${url}`);
-                await route.fulfill({
-                    status: 200,
-                    body: cached.body,
-                });
-                return;
-            }
-
-            // Cache expirado ou inexistente — buscar com headers de revalidação
-            const headers: Record<string, string> = {};
-            if (cached?.etag) headers['If-None-Match'] = cached.etag;
-            if (cached?.lastModified) headers['If-Modified-Since'] = cached.lastModified;
-
-            const response = await route.fetch({ headers });
-
-            if (response.status() === 304 && cached) {
-                // Conteúdo não mudou — renovar TTL
-                console.log(`Revalidado: ${url}`);
-                this.cache.set(url, {
-                    ...cached,
-                    expiry: Date.now() + defaultTtl,
-                });
-
-                await route.fulfill({
-                    status: 200,
-                    body: cached.body,
-                });
-                return;
-            }
-
-            // Conteúdo mudou — atualizar cache
-            const body = await response.text();
-            const responseHeaders = response.headers();
-
-            this.cache.set(url, {
-                body,
-                etag: responseHeaders['etag'] ?? cached?.etag,
-                lastModified: responseHeaders['last-modified'] ?? cached?.lastModified,
-                expiry: Date.now() + defaultTtl,
-            });
-
-            console.log(`Cache MISS: ${url}`);
-            await route.fulfill({
-                status: response.status(),
-                headers: responseHeaders,
-                body,
-            });
-        });
-    }
-}
-```
-
-### Cache Seletivo (Apenas para Tipos Específicos)
-
-```ts
-class SelectiveCache {
-    private cache = new Map<string, string>();
-
-    async setupCache(page: any): Promise<void> {
-        await page.route('**/*', async (route: any) => {
-            const url = route.request().url();
-            const resourceType = route.request().resourceType();
-
-            // Cache apenas para CSS, JS e imagens
-            if (!['stylesheet', 'script', 'image', 'font'].includes(resourceType)) {
-                await route.continue();
-                return;
-            }
-
-            const cached = this.cache.get(url);
-            if (cached) {
-                console.log(`Cache HIT (${resourceType}): ${url}`);
-                await route.fulfill({ body: cached });
-                return;
-            }
-
-            const response = await route.fetch();
-            const body = await response.text();
-
-            if (response.status() === 200) {
-                this.cache.set(url, body);
-            }
-
-            await route.fulfill({
-                status: response.status(),
-                body,
-            });
-        });
-    }
-}
-```
-
----
-
-## Multi-Layer Architecture
-
-### L1 (Memória) + L2 (Disco)
-
-Arquitetura de duas camadas: cache quente em memória, cache frio em disco.
-
-```ts
-import { LRUCache } from 'lru-cache';
-import cacache from 'cacache';
-import { join } from 'path';
-import { tmpdir } from 'os';
-
-class MultiLayerCache {
-    private l1: LRUCache<string, string>;
-    private l2Dir: string;
-
-    constructor(l2Dir?: string) {
-        this.l1 = new LRUCache<string, string>({
-            max: 500,
-            ttl: 1000 * 60 * 5, // 5 minutos
-        });
-
-        this.l2Dir = l2Dir ?? join(tmpdir(), 'scraper-cache');
-    }
-
-    async get(url: string): Promise<{ body: string; source: 'l1' | 'l2' | null }> {
-        // L1: Memória
-        const l1Value = this.l1.get(url);
-        if (l1Value) {
-            return { body: l1Value, source: 'l1' };
-        }
-
-        // L2: Disco
-        try {
-            const l2Entry = await cacache.get(this.l2Dir, url);
-            if (l2Entry) {
-                const body = l2Entry.data.toString();
-                // Promover para L1
-                this.l1.set(url, body);
-                return { body, source: 'l2' };
-            }
-        } catch {
-            // Cache miss no disco
-        }
-
-        return { body: '', source: null };
-    }
-
-    async set(url: string, body: string): Promise<void> {
-        // Armazenar em L1
-        this.l1.set(url, body);
-
-        // Armazenar em L2
-        await cacache.put(this.l2Dir, url, body, {
-            metadata: { url, timestamp: Date.now() },
-        });
-    }
-
-    async invalidate(url: string): Promise<void> {
-        this.l1.delete(url);
-        await cacache.rm(this.l2Dir, url);
-    }
-
-    async invalidateDomain(domain: string): Promise<void> {
-        // L1: invalidar todas as chaves do domínio
-        for (const key of this.l1.keys()) {
-            if (key.includes(domain)) {
-                this.l1.delete(key);
-            }
-        }
-
-        // L2: listar e deletar
-        const entries = await cacache.ls(this.l2Dir);
-        for (const [key] of Object.entries(entries)) {
-            if (key.includes(domain)) {
-                await cacache.rm(this.l2Dir, key);
-            }
-        }
-    }
-
-    async stats(): Promise<{ l1Size: number; l2Size: number }> {
-        const entries = await cacache.ls(this.l2Dir);
-        return {
-            l1Size: this.l1.size,
-            l2Size: Object.keys(entries).length,
-        };
-    }
-}
-
-// Usar
-const cache = new MultiLayerCache();
-
-// Fetch com cache de duas camadas
-async function fetchWithCache(url: string): Promise<string> {
-    const cached = await cache.get(url);
-    if (cached.source) {
-        console.log(`Cache HIT (${cached.source}): ${url}`);
-        return cached.body;
-    }
-
-    console.log(`Cache MISS: ${url}`);
-    const response = await fetch(url);
-    const body = await response.text();
-
-    await cache.set(url, body);
-    return body;
-}
-```
-
-### L1 + L2 com Stale-While-Revalidate
-
-```ts
-class SWRCache {
-    private l1: LRUCache<string, { body: string; expiry: number }>;
-    private l2Dir: string;
-
-    constructor(l2Dir: string) {
-        this.l1 = new LRUCache<string, { body: string; expiry: number }>({
-            max: 500,
-        });
-        this.l2Dir = l2Dir;
-    }
-
-    async fetch(
-        url: string,
-        fetcher: () => Promise<string>,
-        options: { ttl?: number; swr?: number } = {},
-    ): Promise<string> {
-        const { ttl = 300_000, swr = 600_000 } = options; // 5 min TTL, 10 min SWR
-        const now = Date.now();
-
-        // L1 check
-        const l1 = this.l1.get(url);
-        if (l1 && l1.expiry > now) {
-            return l1.body; // Fresh
-        }
-
-        if (l1 && l1.expiry + swr > now) {
-            // Stale mas utilizável — revalidar em background
-            console.log(`SWR: Revalidating ${url} in background`);
-            fetcher().then(body => {
-                this.l1.set(url, { body, expiry: now + ttl });
-                cacache.put(this.l2Dir, url, body);
-            });
-            return l1.body; // Return stale imediatamente
-        }
-
-        // L2 check
-        try {
-            const l2 = await cacache.get(this.l2Dir, url);
-            if (l2) {
-                const body = l2.data.toString();
-                this.l1.set(url, { body, expiry: now + ttl });
-                return body;
-            }
-        } catch {
-            // L2 miss
-        }
-
-        // Fetch completo
-        console.log(`Full fetch: ${url}`);
-        const body = await fetcher();
-
-        this.l1.set(url, { body, expiry: now + ttl });
-        await cacache.put(this.l2Dir, url, body);
-
-        return body;
-    }
-}
-```
-
----
-
-## Código Completo
-
-### Exemplo 1: Web Scraper com Cache Completo
-
-```ts
-import { PlaywrightCrawler } from 'crawlee';
-import { LRUCache } from 'lru-cache';
-import cacache from 'cacache';
-import { join } from 'path';
-import { tmpdir } from 'os';
-
-interface ScrapeCacheConfig {
-    l1MaxSize: number;
-    l1Ttl: number;
-    l2Dir: string;
-    defaultTtl: number;
-}
-
-class ScrapeCache {
-    private l1: LRUCache<string, string>;
-    private l2Dir: string;
-
-    constructor(config: ScrapeCacheConfig) {
-        this.l1 = new LRUCache({
-            max: config.l1MaxSize,
-            ttl: config.l1Ttl,
-        });
-        this.l2Dir = config.l2Dir;
-    }
-
-    async get(url: string): Promise<string | null> {
-        const l1 = this.l1.get(url);
-        if (l1) return l1;
-
-        try {
-            const l2 = await cacache.get(this.l2Dir, url);
-            if (l2) {
-                const body = l2.data.toString();
-                this.l1.set(url, body);
-                return body;
-            }
-        } catch {}
-
-        return null;
-    }
-
-    async set(url: string, body: string): Promise<void> {
-        this.l1.set(url, body);
-        await cacache.put(this.l2Dir, url, body, {
-            metadata: { url, timestamp: Date.now() },
-        });
-    }
-
-    async size(): Promise<number> {
-        const entries = await cacache.ls(this.l2Dir);
-        return Object.keys(entries).length;
-    }
-}
-
-// Configurar
-const cache = new ScrapeCache({
-    l1MaxSize: 500,
-    l1Ttl: 1000 * 60 * 5,
-    l2Dir: join(tmpdir(), 'webscrape-cache'),
-    defaultTtl: 1000 * 60 * 60,
-});
-
-// Crawler com cache
-const crawler = new PlaywrightCrawler({
-    maxConcurrency: 3,
-    requestHandlerTimeoutSecs: 30,
-    async requestHandler({ page, request }) {
-        const url = request.url;
-
-        // Verificar cache
-        const cached = await cache.get(url);
-        if (cached) {
-            console.log(`Cache HIT: ${url}`);
-            // Processar HTML do cache
-            return;
-        }
-
-        // Cache miss — buscar
-        console.log(`Cache MISS: ${url}`);
-        const html = await page.content();
-
-        // Armazenar em cache
-        await cache.set(url, html);
-
-        // Processar...
-    },
-});
-
-await crawler.run(['https://example.com']);
-
-// Estatísticas
-console.log(`Cache size: ${await cache.size()}`);
-```
-
-### Exemplo 2: Cache com ETag e Revalidação
-
-```ts
-import got from 'got';
-
-interface CachedResponse {
-    body: string;
-    etag?: string;
-    lastModified?: string;
-    expiry: number;
-}
-
-class ETagRevalidatingCache {
-    private cache = new Map<string, CachedResponse>();
-
-    async fetch(url: string, ttl = 300_000): Promise<string> {
-        const cached = this.cache.get(url);
-        const now = Date.now();
-
-        if (cached && cached.expiry > now) {
-            return cached.body;
-        }
-
-        const headers: Record<string, string> = {};
-        if (cached?.etag) headers['If-None-Match'] = cached.etag;
-        if (cached?.lastModified) headers['If-Modified-Since'] = cached.lastModified;
-
-        const response = await got(url, {
-            headers,
-            throwHttpErrors: false,
-        });
-
-        if (response.statusCode === 304 && cached) {
-            this.cache.set(url, { ...cached, expiry: now + ttl });
-            return cached.body;
-        }
-
-        const body = response.body;
-        const newCached: CachedResponse = {
-            body,
-            etag: response.headers['etag'] ?? cached?.etag,
-            lastModified: response.headers['last-modified'] ?? cached?.lastModified,
-            expiry: now + ttl,
-        };
-
-        this.cache.set(url, newCached);
-        return body;
-    }
-}
-```
-
-### Exemplo 3: Cache com Playwright e Intercepção
-
-```ts
-import { chromium } from 'playwright';
-
-class PlaywrightMultiLayerCache {
-    private memoryCache = new Map<string, { body: Buffer; contentType: string }>();
-
-    async scrapeWithCache(url: string): Promise<{ html: string; fromCache: boolean }> {
-        const browser = await chromium.launch();
-        const page = await browser.newPage();
-
-        let fromCache = false;
-
-        await page.route('**/*', async (route) => {
-            const requestUrl = route.request().url();
-            const resourceType = route.request().resourceType();
-
-            // Cache apenas para páginas HTML
-            if (resourceType !== 'document') {
-                await route.continue();
-                return;
-            }
-
-            const cached = this.memoryCache.get(requestUrl);
-            if (cached) {
-                fromCache = true;
-                await route.fulfill({
-                    status: 200,
-                    contentType: cached.contentType,
-                    body: cached.body,
-                });
-                return;
-            }
-
-            const response = await route.fetch();
-            const body = await response.body();
-
-            if (response.status() === 200) {
-                this.memoryCache.set(requestUrl, {
-                    body,
-                    contentType: response.headers()['content-type'] ?? 'text/html',
-                });
-            }
-
-            await route.fulfill({
-                status: response.status(),
-                headers: response.headers(),
-                body,
-            });
-        });
-
-        await page.goto(url, { waitUntil: 'networkidle' });
-        const html = await page.content();
-        await browser.close();
-
-        return { html, fromCache };
-    }
-}
-
-// Usar
-const cache = new PlaywrightMultiLayerCache();
-const result = await cache.scrapeWithCache('https://example.com');
-console.log(`From cache: ${result.fromCache}`);
-```
-
-### Exemplo 4: Cache Manager com Múltiplos Backends
-
-```ts
-import { caching } from 'cache-manager';
-
-async function createMultiBackendCache() {
-    // L1: Memória
-    const l1 = await caching('memory', {
-        max: 500,
-        ttl: 300, // 5 min
-    });
-
-    // L2: Redis (se disponível)
-    // const l2 = await caching(redisStore, {
-    //     host: 'localhost',
-    //     port: 6379,
-    //     ttl: 3600, // 1 hora
-    // });
-
-    async function get<T>(key: string): Promise<T | null> {
-        // L1
-        const l1Value = await l1.get<T>(key);
-        if (l1Value !== undefined) return l1Value;
-
-        // L2 (se disponível)
-        // const l2Value = await l2.get<T>(key);
-        // if (l2Value !== undefined) {
-        //     await l1.set(key, l2Value, 300); // Promover para L1
-        //     return l2Value;
-        // }
-
-        return null;
-    }
-
-    async function set<T>(key: string, value: T, ttl?: number): Promise<void> {
-        await l1.set(key, value, ttl ?? 300);
-        // await l2.set(key, value, ttl ?? 3600);
-    }
-
-    async function invalidate(key: string): Promise<void> {
-        await l1.del(key);
-        // await l2.del(key);
-    }
-
-    return { get, set, invalidate };
-}
-
-const cache = await createMultiBackendCache();
-await cache.set('key', 'value');
-const value = await cache.get<string>('key');
-```
-
----
-
-## Referências
-
-- [lru-cache npm](https://www.npmjs.com/package/lru-cache)
-- [node-cache npm](https://www.npmjs.com/package/node-cache)
-- [quick-lru npm](https://www.npmjs.com/package/quick-lru)
-- [cache-manager npm](https://www.npmjs.com/package/cache-manager)
-- [keyv npm](https://www.npmjs.com/package/keyv)
-- [cacache npm](https://www.npmjs.com/package/cacache)
-- [flat-cache npm](https://www.npmjs.com/package/flat-cache)
-- [got-scraping npm](https://www.npmjs.com/package/got-scraping)
-- [Playwright Network Interception](https://playwright.dev/docs/network)
-- [Crawlee Documentation](https://crawlee.dev)