Type Definitions

interface ParserOptions {
  headers?: Record<string, string>;
  xml2js?: xml2js.OptionsV2;
  customFields?: {
    item?: string[];
    feed?: string[];
  };
  requestOptions?: any;
  maxRedirects?: number;
  timeout?: number;
  defaultRSS?: 0.9 | 1 | 2;
}

interface ParsedFeed {
  title?: string;
  description?: string;
  link?: string;
  feedUrl?: string;
  language?: string;
  lastBuildDate?: string;
  image?: {
    url?: string;
    title?: string;
    link?: string;
    width?: string;
    height?: string;
  };
  items: ParsedItem[];
  paginationLinks?: Record<string, string>;
  itunes?: any;
  [key: string]: any;
}

interface ParsedItem {
  title?: string;
  link?: string;
  pubDate?: string;
  date?: string;
  isoDate?: string;
  author?: string;
  content?: string;
  contentSnippet?: string;
  summary?: string;
  guid?: string | { _: string; $?: { isPermaLink?: string } };
  enclosure?: { url?: string; length?: string; type?: string };
  categories?: any[];
  itunes?: any;
  [key: string]: any;
}

interface FeedOptions {
  id: string;
  title: string;
  updated?: Date;
  generator?: string;
  language?: string;
  ttl?: number;
  feed?: string;
  feedLinks?: any;
  hub?: string;
  docs?: string;
  podcast?: boolean;
  category?: string;
  author?: Author;
  link?: string;
  description?: string;
  image?: string;
  favicon?: string;
  copyright: string;
}

interface Item {
  title: string;
  id?: string;
  link: string;
  date: Date;
  description?: string;
  content?: string;
  category?: Category[];
  guid?: string;
  image?: string | Enclosure;
  audio?: string | Enclosure;
  video?: string | Enclosure;
  enclosure?: Enclosure;
  author?: Author[];
  contributor?: Author[];
  published?: Date;
  copyright?: string;
  extensions?: Extension[];
}

interface Author {
  name?: string;
  email?: string;
  link?: string;
  avatar?: string;
}

interface Category {
  name?: string;
  domain?: string;
  scheme?: string;
  term?: string;
}

interface Enclosure {
  url: string;
  type?: string;
  length?: number;
  title?: string;
  duration?: number;
}

interface Extension {
  name: string;
  objects: any;
}

interface ValidationResult {
  valid: boolean;
  errors: string[];
  warnings: string[];
}

interface OPMLDocument {
  version?: string;
  title?: string;
  dateCreated?: Date;
  dateModified?: Date;
  ownerName?: string;
  ownerEmail?: string;
  outlines: OPMLOutline[];
}

interface OPMLOutline {
  text?: string;
  title?: string;
  type?: string;
  xmlUrl?: string;
  htmlUrl?: string;
  description?: string;
  category?: string[];
  outlines?: OPMLOutline[];
}

interface FeedDiffResult {
  added: ParsedItem[];
  removed: ParsedItem[];
  modified: ParsedItem[];
  unchanged: ParsedItem[];
}

function isParsedFeed(value: any): value is ParsedFeed {
  return value && typeof value === 'object' && Array.isArray(value.items);
}

function isParsedItem(value: any): value is ParsedItem {
  return value && typeof value === 'object';
}

function isOPMLDocument(value: any): value is OPMLDocument {
  return value && typeof value === 'object' && Array.isArray(value.outlines);
}

type FeedItem = ParsedItem | Item;

type AnyFeed = ParsedFeed | FeedOptions;

import { ParserOptions, ParsedFeed } from 'rss.today';
 
interface CustomParserOptions extends ParserOptions {
  customFields: {
    item: string[];
    feed: string[];
  };
}
 
interface CustomParsedFeed extends ParsedFeed {
  'dc:creator'?: string;
  'dc:date'?: string;
  'media:thumbnail'?: string;
}

interface ITunesExtension {
  name: 'itunes';
  objects: {
    author?: string;
    summary?: string;
    explicit?: string;
    keywords?: string | string[];
    image?: string;
    owner?: {
      name?: string;
      email?: string;
    };
  };
}
 
interface MediaExtension {
  name: 'media';
  objects: {
    thumbnail?: {
      url?: string;
      width?: number;
      height?: number;
    };
  };
}

type AudioEnclosure = Enclosure & {
  type: 'audio/mpeg' | 'audio/mp4' | 'audio/ogg';
};
 
type VideoEnclosure = Enclosure & {
  type: 'video/mp4' | 'video/webm' | 'video/ogg';
};
 
type ImageEnclosure = Enclosure & {
  type: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
};

type FeedOutline = OPMLOutline & {
  type: 'rss';
  xmlUrl: string;
  htmlUrl?: string;
};
 
type FolderOutline = OPMLOutline & {
  type: 'folder' | undefined;
  outlines: OPMLOutline[];
};
 
type LinkOutline = OPMLOutline & {
  type: 'link';
  url: string;
};

import { Parser, ParserOptions, ParsedFeed } from 'rss.today';
 
const options: ParserOptions = {
  customFields: {
    feed: ['dc:creator', 'dc:date'],
    item: ['dc:subject', 'media:thumbnail']
  }
};
 
const parser = new Parser(options);
 
async function parseFeed(url: string): Promise<ParsedFeed> {
  const feed = await parser.parseURL(url);
 
  // Access custom fields with type assertion
  const creator = feed['dc:creator'] as string | undefined;
  const date = feed['dc:date'] as string | undefined;
 
  return feed;
}

import { Feed, FeedOptions, Item, Author, Category } from 'rss.today';
 
const feedOptions: FeedOptions = {
  id: 'https://example.com/feed',
  title: 'My Feed',
  copyright: '2024',
  language: 'en',
  author: {
    name: 'Author Name',
    email: 'author@example.com'
  }
};
 
const feed = new Feed(feedOptions);
 
const item: Item = {
  title: 'Post Title',
  link: 'https://example.com/post',
  date: new Date(),
  description: 'Post description',
  category: [
    { name: 'Technology' },
    { name: 'Web Development' }
  ],
  author: [{
    name: 'Author Name',
    email: 'author@example.com'
  }]
};
 
feed.addItem(item);

import { validateRSS2, validateAtom, ValidationResult } from 'rss.today';
import { ParsedFeed } from 'rss.today';
 
function validateFeed(feed: ParsedFeed): ValidationResult {
  // Try RSS 2.0 first
  const rss2Result = validateRSS2(feed);
  if (rss2Result.valid) {
    return rss2Result;
  }
 
  // Fall back to Atom
  return validateAtom(feed);
}

import { OPMLParser, OPMLGenerator, OPMLDocument, OPMLOutline } from 'rss.today';
 
const opmlDocument: OPMLDocument = {
  title: 'My Subscriptions',
  dateCreated: new Date(),
  outlines: [
    {
      text: 'Technology',
      outlines: [
        {
          text: 'TechCrunch',
          type: 'rss',
          xmlUrl: 'https://techcrunch.com/feed/',
          htmlUrl: 'https://techcrunch.com'
        } as OPMLOutline
      ]
    } as OPMLOutline
  ]
};
 
const generator = new OPMLGenerator();
const opmlXml = generator.generateOPML(opmlDocument);

import {
  mergeFeeds,
  diffFeeds,
  FeedDiffResult
} from 'rss.today';
import { ParsedFeed } from 'rss.today';
 
async function compareFeeds(
  oldFeedUrl: string,
  newFeedUrl: string
): Promise<FeedDiffResult> {
  const parser = new Parser();
 
  const [oldFeed, newFeed] = await Promise.all([
    parser.parseURL(oldFeedUrl),
    parser.parseURL(newFeedUrl)
  ]);
 
  return diffFeeds(oldFeed, newFeed);
}

type FeedBuilder<T extends FeedOptions = FeedOptions> = (options: T) => Feed;

type ParserResult<T = ParsedFeed> = Promise<T>;

type FeedProcessor<T = ParsedFeed> = (feed: T) => T;

type FeedFilter<T = ParsedItem> = (item: T, index: number) => boolean;

type FeedComparator<T = ParsedItem> = (a: T, b: T) => number;

interface StrictParsedFeed {
  title: string;
  link?: string;
  feedUrl?: string;
  description?: string;
  language?: string;
  lastBuildDate?: string;
  image?: FeedImage;
  items: StrictParsedItem[];
}
 
interface StrictParsedItem {
  title: string;
  link: string;
  pubDate?: string;
  isoDate?: string;
  author?: string;
  content?: string;
  contentSnippet?: string;
  summary?: string;
  guid?: string;
  enclosure?: Enclosure;
  categories?: Category[];
}

interface StrictFeedOptions {
  id: string;
  title: string;
  copyright: string;
  link?: string;
  description?: string;
  language?: string;
  updated?: Date;
  generator?: string;
  author?: StrictAuthor;
}
 
interface StrictAuthor {
  name: string;
  email?: string;
  link?: string;
}