Documentación de Cheerio v1.2.0

Cheerio es una biblioteca rápida, flexible y elegante para analizar y manipular HTML y XML en el lado del servidor. Implementa un subconjunto de la funcionalidad principal de jQuery, proporcionando un API familiar para desarrolladores mientras está optimizada para entornos del lado del servidor.

Características de la Versión Actual (1.2.0)

Métodos Principales de Carga

La versión actual proporciona varias formas poderosas de cargar y analizar documentos HTML/XML:

import * as cheerio from 'cheerio';

// Basic loading from string
const $ = cheerio.load('<h2 class="title">Hello world</h2>');

// Loading from buffer with encoding detection
const buffer = fs.readFileSync('index.html');
const $ = cheerio.loadBuffer(buffer);

// Loading from URL with automatic encoding detection
const $ = await cheerio.fromURL('https://example.com');

// Stream-based loading for large documents
const stream = cheerio.stringStream({}, (err, $) => {
  if (!err) {
    console.log($('h1').text());
  }
});

Soporte Mejorado para TypeScript

La versión 1.2.0 incluye definiciones completas de TypeScript con seguridad de tipos mejorada:

import { CheerioAPI, Cheerio, Element } from 'cheerio';

// Strongly typed element selection
const $: CheerioAPI = cheerio.load(html);
const elements: Cheerio<Element> = $('.my-class');

Nuevo API Extract

Una nueva característica poderosa para la extracción de datos de documentos HTML:

const data = $root.extract({
  title: 'h1',
  links: [{ selector: 'a', value: 'href' }],
  metadata: {
    selector: '.meta',
    value: {
      author: '.author',
      date: '.date'
    }
  }
});

Manejo Avanzado de URL

Soporte mejorado para resolución de URL con baseURI:

const $ = cheerio.load(html, { 
  baseURI: 'https://example.com/page/' 
});

// Automatically resolves relative URLs
$('a').prop('href'); // Returns absolute URL
$('img').prop('src'); // Returns absolute URL

Características Clave por Categoría

Manipulación del DOM

• Selección de elementos estilo jQuery con selectores CSS
• Manipulación completa de atributos y propiedades
• Soporte completo para métodos de recorrido del DOM
• Inserción, eliminación y modificación de elementos

Manejo de Formularios

// Serialize forms to URL-encoded strings
$('form').serialize(); // 'name=value&email=test@example.com'

// Get form data as structured arrays
$('form').serializeArray();
// [{ name: 'username', value: 'john' }, ...]

CSS y Estilos

// Get/set CSS properties
$('.element').css('color', 'red');
$('.element').css(['margin', 'padding']); // Get multiple properties

// Class manipulation
$('.item').addClass('active selected');
$('.item').removeClass('old-class');
$('.item').toggleClass('visible');

Atributos de Datos

// HTML5 data-* attribute support with automatic type coercion
$('.widget').data('config'); // Parses JSON automatically
$('.widget').data('count', 42); // Set data programmatically

Migración desde Versiones Anteriores

De 0.x a 1.x

• Cambio disruptivo: Se requiere Node.js 12+ (se eliminó el soporte para versiones anteriores)
• Cambio disruptivo: Algunos API internos han cambiado
• Mejorado: Mejor soporte de TypeScript en general
• Nuevo: Análisis basado en streams para mejor eficiencia de memoria

Cambios Clave a Observar

// Old way (0.x) - still works but discouraged
const cheerio = require('cheerio');
const $ = cheerio.load(html);

// New way (1.x) - recommended
import * as cheerio from 'cheerio';
const $ = cheerio.load(html);

Mejoras de Rendimiento

La versión 1.2.0 incluye mejoras significativas de rendimiento:

• Análisis más rápido: Parser de HTML mejorado con mejor manejo de errores
• Eficiencia de memoria: Huella de memoria reducida para documentos grandes
• Soporte de streaming: Procesa documentos grandes sin cargarlos completamente en memoria

// Stream processing for large files
const stream = cheerio.decodeStream({
  encoding: { defaultEncoding: 'utf8' }
}, (err, $) => {
  // Process document as it streams
});

Características Avanzadas

Opciones de Parser Personalizado

const $ = cheerio.load(html, {
  xmlMode: true,        // Parse as XML
  decodeEntities: false, // Don't decode HTML entities
  scriptingEnabled: false // Disable script tag processing
});

Carga de Red con Opciones

const $ = await cheerio.fromURL('https://api.example.com/data', {
  requestOptions: {
    headers: { 'User-Agent': 'MyBot/1.0' }
  },
  encoding: { defaultEncoding: 'utf8' }
});

Mejores Prácticas

1. Usa TypeScript: Aprovecha las definiciones de tipos completas
2. Transmite documentos grandes: Usa API de streaming para mejor gestión de memoria
3. Aprovecha el API extract: Usa el nuevo método extract para extracción de datos estructurados
4. Establece baseURI: Al hacer scraping de sitios web, establece baseURI para resolución adecuada de URL

Diferencias entre Navegador y Servidor

Cheerio está diseñado para uso del lado del servidor y elimina características de jQuery específicas del navegador mientras añade funcionalidad optimizada para servidor como:

• Sin inconsistencias del DOM del navegador
• Mejor manejo de errores para HTML mal formado
• Análisis eficiente en memoria
• Capacidades de procesamiento de streams
• Detección automática de codificación

Esto hace que Cheerio sea ideal para web scraping, renderizado del lado del servidor, y cualquier tarea de procesamiento HTML/XML en entornos Node.js.