WebSearch Engine

Biblioteca Node.js para busca na web em tempo real, feita para ser usada por agentes de IA.

• ✅ Sem banco de dados
• ✅ Sem cache permanente
• ✅ Sem gravação em disco
• ✅ Downloads em paralelo (Promise.all)
• ✅ Nada é persistido: toda a memória é liberada ao final da busca

Instalação

npm install

Uso

Projeto CommonJS (padrão)

const { pesquisar, pesquisarUrl } = require("web-search-engine");

const resultados = await pesquisar("Como funciona o Node.js?");

console.log(resultados);
// [
//   {
//     score: 0.98,
//     titulo: "...",
//     descricao: "...",
//     url: "...",
//     dominio: "...",
//     texto: "..."
//   }
// ]

Projeto ESM ("type": "module")

import { pesquisar, pesquisarUrl } from "web-search-engine";

const resultados = await pesquisar("Como funciona o Node.js?");

console.log(resultados);

Caso algum ambiente não resolva os imports nomeados, use o fallback:

import wse from "web-search-engine";
const { pesquisar, pesquisarUrl } = wse;

O array retornado está pronto para ser enviado diretamente a uma LLM, sem pós-processamento.

Analisar uma URL direta

const { pesquisarUrl } = require("web-search-engine");

const resultados = await pesquisarUrl("https://pt.wikipedia.org/wiki/Felipe_Neto", {
  pergunta: "Felipe Neto IA", // opcional: usada para calcular o score
  descricao: "..."            // opcional: descrição do resultado
});

Baixa a página, extrai o conteúdo útil e retorna um array com um único resultado (vazio se a página falhar).

Opções

const resultados = await pesquisar("Express", {
  limiteResultados: 10,     // quantidade de resultados (padrão: 10)
  limiteCaracteres: 10000,  // limite de caracteres por texto (padrão: 10000)
  timeout: 5000,            // timeout por página em ms (padrão: 5000)
  userAgent: "...",         // User-Agent das requisições
  seguirRedirect: true      // seguir redirecionamentos HTTP
});

Comportamento

• As páginas são baixadas em paralelo.
• Se uma página falhar ou estourar o timeout, ela é ignorada e a pesquisa continua.
• A função sempre retorna um array, mesmo que vazio. Nunca lança erro.
• O conteúdo extraído prioriza article, main e section (fallback: body).
• Scripts, CSS, SVG, iframes, menus, navegação, formulários e publicidade são removidos.
• Resultados com conteúdo praticamente idêntico são deduplicados.
• Cada resultado recebe um score de relevância entre 0 e 1.

Estrutura

src/
├── index.js                 # ponto de entrada (exporta pesquisar)
├── buscar/
│   ├── buscar.js            # orquestra a pesquisa (encontra links e coordena o fluxo)
│   └── ordenarResultados.js # ordena por score
├── downloader/
│   ├── baixarPagina.js      # baixa uma página com timeout
│   └── baixarVariasPaginas.js # baixa várias em paralelo
├── extrator/
│   ├── extrairTexto.js      # extrai o conteúdo principal
│   ├── limparHtml.js        # remove scripts, menus, navegação, etc.
│   └── removerPublicidade.js # remove blocos de anúncio
├── relevancia/
│   └── calcularScore.js     # score de relevância (0–1)
├── util/
│   ├── normalizarTexto.js   # limpa e normaliza texto
│   ├── removerDuplicados.js # remove conteúdo duplicado
│   └── limitarTexto.js      # limita o tamanho do texto
├── tipos/
│   └── ResultadoBusca.js    # cria resultados padronizados
└── constantes/
    └── configuracao.js      # valores padrão

Dependências

• axios — requisições HTTP
• cheerio — parse e limpeza de HTML

Notas

• O mecanismo de busca usado para encontrar links é o DuckDuckGo (HTML), sem necessidade de chave de API.
• Nenhuma informação é salva em disco; tudo acontece em memória durante a execução.