@grenzbotin/feedlink

This package contains helpful utils for reading and working with rss feeds on websites.

Contents

1. Installation
2. Functions
   • get
   • validate
   • parse
3. Shoutout

👋 Installation

npm i @grenzbotin/feedlink

🤘 Functions

Usage

Import the package.

import * as feedlink from "@grenzbotin/feedlink";

Get

Description: The get function takes any website link and tries to find and return a feed link.

Note: Will return a promise.

import * as feedlink from "@grenzbotin/feedlink";

async function getRSS(link) {
  return feedlink.get(link);
}

const rssLink = await getRSS("https://www.(Example1|2|3)");

console.log("Result: ", rssLink);

Example 1: nature.com

Result:  { success: true, href: 'https://www.nature.com/nature.rss' }

Example 2: css-tricks.com

Result:  { success: true, href: 'https://css-tricks.com/feed/' }

Example 3: science.org

Result:  { success: false, err: 'ERR_NON_2XX_3XX_RESPONSE' }

Limitation: As you see on the third example, there is no guarantee that the module will find a feed link. While the package might become more clever over time and find more rss feeds on the go, not every page has an rss feed or wants to have one.

Validate

Description: The validate function takes any feed link and returns whether its a valid link including potential errors, warnings or information with the help of the w3c validator. Not possible without the great work behind validator.w3.org/feed.

Note: Will return a promise.

import * as feedlink from "@grenzbotin/feedlink";

async function validate(link) {
  return feedlink.validate(link);
}

const result = await validate("https://some-link");

console.log("Result: ", result);

// Result:  {
//  isValid: true,
//  errorsList: [],
//  warningsList: [
//    'SelfDoesntMatchLocation',
//    'UnknownNamespace',
//    'NotHtml',
//    'NotHtml',
//    'ContainsRelRef'
//  ],
//  infoList: []
// }

Parse

Description: The parse function takes any feed link or feed string and returns feed information in json-format. It is just a simplified wrapper around the rss-parser. Thus, you can hand in the same parsing options as described here.

Note: Will return a promise.

Example 1: parse link

import * as feedlink from "@grenzbotin/feedlink";

async function parse(link) {
  return feedlink.parse(link);
}

const result = await parse("https://some-link");

console.log("Example result: ", result);

// Example result:  {
//  success: true,
//  result: {
//    items: [
//      [Object], [Object],
//      [Object], [Object],
//      [Object], [Object],
//      [Object], [Object],
//      [Object], [Object],
//      [Object], [Object],
//      [Object], [Object],
//      [Object]
//    ],
//    feedUrl: 'url',
//    image: {...},
//    paginationLinks: { self: 'url' },
//    title: 'title',
//    description: 'description',
//    generator: 'https://wordpress.org/?v=6.2.2',
//    link: 'url',
//    language: 'en-US',
//    lastBuildDate: 'Wed, 12 Apr 2023 17:42:35 +0000'
//  }
//}

Example 2: parse string

import * as feedlink from "@grenzbotin/feedlink";

async function parse(string) {
  return feedlink.parse(string);
}

const exampleString = `
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
  <channel>
    <title>Feed title</title>
    <link>Website url</link>
    <description>description</description>
    <language>en-en</language>
    <pubDate>Sun, 6 Aug 2023 2:43:19</pubDate>
    <image>
      <url>image url</url>
      <title>image title</title>
      <link>url link</link>
    </image>
    <item>
      <title>title</title>
      <description>description</description>
    </item>
  </channel>
</rss>`;

const result = await parse(exampleString);

console.log("Example result: ", result);

// Example result:  {
//  success: true,
//  result: {
//    items: [{
//      content: "description",
//      contentSnippet: "description",
//      title: "title",
//    }],
//    image: { link: 'url link', url: 'image url', title: 'image title' },
//    title: 'Feed title',
//    description: 'description',
//    pubDate: 'Sun, 6 Aug 2023 2:43:19',
//    link: 'Website url',
//    language: 'en-en'
//  }
//}

Example 3: parse string with renaming keys

import * as feedlink from "@grenzbotin/feedlink";

async function parse(string) {
  return feedlink.parse(string);
}

const exampleString = `
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
  <channel>
    <title>Feed title</title>
    <link>Website url</link>
    <description>description</description>
    <language>en-en</language>
    <pubDate>Sun, 6 Aug 2023 2:43:19</pubDate>
    <image>
      <url>image url</url>
      <title>image title</title>
      <link>url link</link>
    </image>
    <item>
      <title>title</title>
      <description>description</description>
    </item>
  </channel>
</rss>`;

const result = await parse(exampleString, {
  customFields: {
    item: [
      ["description", "👾content"],
      ["title", "👾title"],
    ],
  },
});

console.log("Example result: ", result);

// Example result:  {
//  success: true,
//  result: {
//    items: [  {
//      "👾content": "description",
//      content: "description",
//      contentSnippet: "description",
//      "👾title": "title",
//      title: "title",
//    }],
//    image: { link: 'url link', url: 'image url', title: 'image title' },
//    title: 'Feed title',
//    description: 'description',
//    pubDate: 'Sun, 6 Aug 2023 2:43:19',
//    link: 'Website url',
//    language: 'en-en'
//  }
//}

🌻 Shoutout

A big shoutout and thank you goes to

• sindresorhus for got
• ashi009 & taoqf for node-html-parser
• w3cdevs for validator.w3.org/feed
• avajs (and the team behind) for ava
• rben for the beautiful rss-parser

Notes

• v0.5.0 Temporary adjustment: rss-parser: contains a reference to a commit to solve request timeout handling due to missing merge.

MacOS arm

For users that are working on macos arm processors: Please follow the instructions mentioned in here to make the lib work on your machine: [email protected] install: node install.js on M1