Feed Parsing: Atom and RDF

Relevant source files

The following files were used as context for generating this wiki page:

• src/index.ts
• src/FeedHandler.spec.ts
• src/fixtures/Documents/Atom_Example.xml
• src/fixtures/Documents/RDF_Example.xml
• src/Parser.ts
• src/Tokenizer.ts
• README.md

Feed parsing in htmlparser2 provides a specialized interface for processing syndication formats, specifically Atom, RDF (RSS 1.0), and RSS 2.0. By leveraging the library's high-performance XML parsing capabilities, the system extracts structured data such as titles, links, and entries into a normalized Feed object.

This module is designed to be "fast and forgiving," handling the complexities of XML namespaces and entity decoding common in web feeds. It primarily utilizes the parseFeed helper method, which internally configures the Parser in xmlMode to ensure correct handling of self-closing tags and CDATA sections found in Atom and RDF documents.

Sources: README.md:213-215, src/index.ts:74-85

Architecture and Data Flow

The feed parsing process involves three main layers: the Tokenizer for lexical analysis, the Parser for structural analysis (in xmlMode), and the domutils integration to extract specific feed metadata.

Feed Parsing Sequence

The following diagram illustrates the flow from a raw XML string to a structured Feed object.

The sequence demonstrates that parseFeed is a high-level wrapper that ensures xmlMode is active before delegating to domutils for final extraction.
Sources: src/index.ts:74-85, README.md:213-222

Key Components

Parser Configuration

For feeds like Atom and RDF, the parser must be configured with specific options to handle XML-specific syntax.

Option	Required Value	Description
xmlMode	true	Enables XML entity decoding, self-closing tags, and CDATA handling.
decodeEntities	true	Decodes HTML/XML entities (e.g., & to &).
lowerCaseTags	false	Prevents lowercasing, preserving case-sensitive XML tag names.

Sources: src/Parser.ts:162-205, README.md:104-121

Data Structures

The parser produces a Feed object (imported via domutils) which standardizes the differences between Atom and RDF/RSS.

Field	Type	Description
type	string	The feed type (e.g., "atom", "rdf", "rss").
title	string	The title of the feed.
link	string	The primary URL associated with the feed.
description	string	A brief summary of the feed content.
updated	Date	Timestamp of the last update.
author	string	The name/email of the feed creator.
items	FeedItem[]	An array of individual feed entries/articles.

Sources: README.md:218-220, src/index.ts:72

Atom Feed Implementation

Atom feeds (Namespace: http://www.w3.org/2005/Atom) utilize specific tags like <feed>, <entry>, and <content>.

The diagram shows the hierarchical structure of a standard Atom document parsed by the system.
Sources: src/fixtures/Documents/Atom_Example.xml:4-25

Implementation Detail: CDATA in Atom

Atom feeds often wrap HTML content in CDATA sections. The Parser in xmlMode routes these through the oncdatastart, ontext, and oncdataend callbacks to preserve the literal HTML string.
Sources: src/Parser.ts:601-615, src/fixtures/Documents/Atom_Example.xml:23

RDF (RSS 1.0) Implementation

RDF feeds use the rdf:RDF root element and rely heavily on namespaces and the rdf:about attribute for resource identification.

The RDF structure separates the channel metadata from the item list, both residing under the rdf:RDF root.
Sources: src/fixtures/Documents/RDF_Example.xml:2-55

Namespace Handling

The parser handles various RDF modules and namespaces, including:

• dc: Dublin Core (http://purl.org/dc/elements/1.1/)
• syn: Syndication (http://purl.org/rss/1.0/modules/syndication/)
• content: Content Module (http://purl.org/rss/1.0/modules/content/)

Sources: src/fixtures/Documents/RDF_Example.xml:2-10

Parsing API

The primary entry point for feed parsing is the parseFeed function.

// src/index.ts:79-85
export function parseFeed(
    feed: string,
    options: Options = parseFeedDefaultOptions,
): Feed | null {
    return getFeed(parseDocument(feed, options).children);
}

Usage Example

Developers can parse a feed by passing the raw string content. The xmlMode is enabled by default.

import { parseFeed } from "htmlparser2";

const feed = parseFeed(xmlString);
if (feed) {
    console.log(feed.title);
    feed.items.forEach(item => console.log(item.title));
}

Sources: src/index.ts:79-85, README.md:213-222, src/FeedHandler.spec.ts:8-33

Summary

htmlparser2 provides a robust mechanism for parsing Atom and RDF feeds by utilizing a specialized xmlMode within its core Parser. This ensures that XML-specific constructs, such as namespaces and CDATA sections, are correctly interpreted before the data is normalized into a standard Feed object via domutils. The system is validated against standard fixtures to ensure compatibility across Atom, RDF, and RSS variants.
Sources: src/FeedHandler.spec.ts:1-33, README.md:213-222