Fetch and parse RSS and Atom feeds. Fetch Feed is a Promise-based wrapper around node-feedparser.
This library requires the following to run:
- Node.js v18+
Install with npm:
npm install @rowanmanning/fetch-feed
Load the library into your code with a require
call:
const fetchFeed = require('@rowanmanning/fetch-feed');
Now you can call fetchFeed
with various options to fetch and parse RSS and Atom feeds:
const result = await fetchFeed({
url: 'https://rowanmanning.com/posts/feed.xml'
});
The node-feedparser library is stream-based, loading as little of a feed into memory as possible. This allows it to handle potentially very large feeds. Because of this, fetchFeed
does not resolve with the entire parsed feed – you must handle the parsed feed entries separately.
You do this with the onInfo
and onEntry
options, which are functions:
const result = await fetchFeed({
url: 'https://rowanmanning.com/posts/feed.xml',
// Called once
onInfo: async info => {
// Do something with the feed meta information
},
// Called for each entry found
onEntry: async entry => {
// Do something with the feed entry
}
});
The feed info and feed entry objects are documented by node-feedparser.
If these handlers return promises, then you can be sure that your code will execute in the order:
- The feed XML is requested
- In any order,
onInfo
andonEntry
will be called with the relevant data - The outer
fetchFeed
promise will resolve or reject
To make sure that we never store the full parsed feed in memory, the resolved value from fetchFeed
is a simple object with just a few feed details:
{
url: String, // The final URL of the feed (after redirects)
title: String, // The title of the feed
entryCount: Number // The number of entries that were parsed
}
If any of the following happen, the outer fetchFeed
promise will reject with an error:
- The request to fetch the feed fails in some way (e.g. an HTTP error)
- The parsing of the feed fails (e.g. malformed XML)
- The
onInfo
handler function rejects - The
onEntry
handler function rejects
It's important to note that this doesn't cancel any of the actions that occurred in handlers before the rejection, and errors in a single handled entry do not stop others from being handled correctly.
This full example fetches a feed, logs information about it, and handles errors:
try {
const result = await fetchFeed({
// Feed URL and request details
url: 'https://rowanmanning.com/posts/feed.xml',
requestOptions: {
headers: {
'User-Agent': 'Fetch Feed Example'
}
},
// Info handler
onInfo: async info => {
console.log(`Parsed feed meta information: ${info.title}`);
},
// Entry handler
onEntry: async entry => {
console.log(`Parsed feed entry: ${entry.title}`);
}
});
console.log(`Finished fetching ${result.url}. Found ${result.entryCount} entries`);
} catch (error) {
console.error(`Feed fetching failed: ${error.message}`);
}
Fetch Feed is configured using options passed into the main fetchFeed
function:
-
url
:String
. A full valid URL to an RSS or Atom feed. Required. -
requestOptions
:Object
. Config options for the HTTP request that fetches the feed. This is passed directly into Got, see Got's options documentation for more information. Defaults toundefined
(uses the default request options). -
onInfo
:Function<Promise>
. A function that is given meta information about the feed. This function will only be called once with a singleObject
argument – the feed information.onInfo
must return a Promise. Defaults toundefined
(feed information is not captured). -
onEntry
:Function<Promise>
. A function that is given information about each entry in the feed. This function will be called for each entry found in the feed, with a singleObject
argument – the entry information.onEntry
must return a Promise. Defaults toundefined
(entry information is not captured).
The contributing guide is available here. All contributors must follow this library's code of conduct.
Licensed under the MIT license.
Copyright © 2020, Rowan Manning.