@wenathlan/saddle 1.8.2 → 1.8.5

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

@@ -0,0 +1,1610 @@
+# 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)