medium-rss-feed-parser

A lightweight Node.js library for fetching and parsing Medium RSS feeds using the AllOrigins proxy.

Table of Contents

• medium-rss-feed-parser
  • Table of Contents
  • Introduction
  • Installation
  • API Reference
    • getFeed(authorUsername)
    • parseFeed(authorUsername)
    • Error Classes
  • Dependencies
  • Usage
    • Example: getFeed
    • Example: parseFeed
    • Handling Errors
  • Limitations
  • License

Introduction

medium-rss-feed-parser provides a fetch of the Medium author's RSS feed by username and returns the parsed response in JSON. The package is compatible with ESM, CommonJS, and TypeScript.

[!NOTE] The package uses AllOrigins to bypass Medium's CORS restrictions. If AllOrigins is unavailable, requests will fail.

Installation

npm install medium-rss-feed-parser

API Reference

getFeed(authorUsername)

• Parameters: authorUsername (string) – must start with @ and contain letters, numbers, ., or _ (max 30 chars).
• Returns: Promise<Object> resolving with the RSS feed in JSON format and the feed contents in RSS format.
• Throws: One of the custom public error classes listed below.

parseFeed(authorUsername)

• Parameters: authorUsername (string) – must start with @ and contain letters, numbers, ., or _ (max 30 chars).
• Returns: Promise<Object> resolving with the parsed feed metadata and a list article of contents in JSON format.
• Throws: One of the custom public error classes listed below.

Error Classes

The package exports the following errors:

• UnknownAuthorError – validation failure for username. (public)
• StructureError – RSS response didn't have expected shape. (public)
• RssError – generic wrapper for network/HTTP/parse errors. (public)
  • NetworkError – network request failed.
  • HttpError – response returned non-OK status.
  • ParseError – failure parsing JSON.
  • FetchError – low-level fetch failure.

[!TIP] RssError is usually thrown due to a NetworkError and can often be resolved by initiating a retry request. A retry request does not consistently resolve the other wrapped errors, in which case, a user-friendly UX is recommended to address the error.

Dependencies

This library has no runtime dependencies other than the fetch API (available in Node.js 18+ or with a polyfill).

[!IMPORTANT] Make sure fetch is available in your environment. For older Node versions, install a polyfill like node-fetch and set global.fetch.

Usage

Example: getFeed

import mediumFetcher from "medium-rss-feed-parser/fetcher";

async function main() {
  const feed = await mediumFetcher
    .getFeed("@jaustinjr")
    .then((feed) => {
      console.log(feed.contents);
    })
    .catch((err) => {
      console.error("Failed to fetch feed:", err);
    });

  // Use RSS feed contents as needed
}

main();

Example: parseFeed

import mediumParser from "medium-rss-feed-parser/parser";

async function main() {
  try {
    const parsedFeed = await mediumParser.parseFeed("@jaustinjr");

    // Use parsed feed and contents as needed
    console.log(parsedFeed);
  } catch (err) {
    console.error("Failed to parse feed:", err);
  }
}

main();

Handling Errors

The library exports several error classes, allowing callers to distinguish between different failure modes, three of which are public:

import { fetcher, errors } from "medium-rss-feed-parser";

try {
  await fetcher.getFeed("invalid"); // will throw UnknownAuthorError
} catch (err) {
  if (err instanceof errors.UnknownAuthorError) {
    // username validation failed or username was not found
  } else if (err instanceof errors.StructureError) {
    // response missing expected fields
  } else if (err instanceof errors.RssError) {
    // fetch/network/parse/http error wrapped, send a retry request
  } else {
    // other unexpected error
  }
}

Limitations

• CORS Proxy Reliance: The package depends entirely on AllOrigins. Downtime or rate limits on their service will break functionality.
• No Caching: Each call issues a fresh network request; there is no built-in caching mechanism.
• Minimal Validation: Only basic username validation is performed; Medium usernames may change or contain other characters in the future.
• Only Medium RSS Feeds: JSON export of specific Medium articles or other APIs are not supported.

License

medium-rss-feed-parser is licensed under the MIT License.