rss.today 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rssToday
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,702 @@
+# rss.Today
+
+A modern TypeScript library for parsing and generating RSS/Atom feeds. Supports multiple input sources, all common feed formats, and podcast extensions.
+
+## Features
+
+- **Parse** RSS 0.9, RSS 1.0, RSS 2.0, Atom 1.0, and JSON Feed 1.0
+- **Generate** RSS 0.9, RSS 1.0, RSS 2.0, Atom 1.0, and JSON Feed 1.0
+- **Multiple input sources**: URL, string, file, buffer, or stream
+- **Feed validation**: Validate feeds against RSS 2.0, Atom 1.0, and JSON Feed 1.0 specifications
+- **Feed conversion**: Convert feeds between different formats
+- **Podcast support**: iTunes namespace extensions
+- **TypeScript**: Fully typed with comprehensive type definitions
+- **ESM**: Modern ES modules support
+
+## Installation
+
+```bash
+npm install rss.today
+```
+
+```bash
+yarn add rss.today
+```
+
+```bash
+pnpm add rss.today
+```
+
+## Quick Start
+
+### Parsing Feeds
+
+```typescript
+import { Parser } from 'rss.today';
+
+const parser = new Parser();
+
+// Parse from URL
+const feed = await parser.parseURL('https://example.com/feed.xml');
+console.log(feed.title);
+console.log(feed.items);
+
+// Parse from XML string
+const xml = '<?xml version="1.0"?><rss version="2.0">...</rss>';
+const feed = await parser.parseString(xml);
+
+// Parse from local file
+const feed = await parser.parseFile('./feeds/my-feed.xml');
+
+// Parse from Buffer
+const buffer = Buffer.from(xmlContent);
+const feed = await parser.parseBuffer(buffer);
+
+// Parse from Stream
+const stream = fs.createReadStream('./feed.xml');
+const feed = await parser.parseStream(stream);
+```
+
+### Generating Feeds
+
+```typescript
+import { Feed } from 'rss.today';
+
+const feed = new Feed({
+  title: 'My Blog',
+  description: 'A blog about technology',
+  link: 'https://example.com',
+  id: 'https://example.com/feed',
+  language: 'en',
+});
+
+// Add items
+feed.addItem({
+  title: 'First Post',
+  link: 'https://example.com/first-post',
+  description: 'This is my first post',
+  date: new Date(),
+});
+
+// Generate RSS 0.9
+const rss09 = feed.rss0_9();
+
+// Generate RSS 1.0
+const rss1 = feed.rss1();
+
+// Generate RSS 2.0
+const rss = feed.rss2();
+
+// Generate Atom 1.0
+const atom = feed.atom1();
+
+// Generate JSON Feed 1.0
+const json = feed.json1();
+```
+
+## API Documentation
+
+### Parser Class
+
+#### Constructor
+
+```typescript
+constructor(options?: ParserOptions)
+```
+
+**Options:**
+```typescript
+interface ParserOptions {
+  headers?: Record<string, string>;
+  xml2js?: xml2js.OptionsV2;
+  customFields?: {
+    item?: string[];
+    feed?: string[];
+  };
+  defaultRSS?: 0.9 | 1 | 2;
+}
+```
+
+**Example with custom fields:**
+```typescript
+const parser = new Parser({
+  customFields: {
+    feed: ['dc:creator', 'dc:date'],
+    item: ['dc:subject', 'media:thumbnail']
+  }
+});
+```
+
+#### Methods
+
+##### `parseString(xml: string): Promise<ParsedFeed>`
+
+Parse feed from XML string.
+
+```typescript
+const feed = await parser.parseString(xmlString);
+```
+
+##### `parseURL(url: string): Promise<ParsedFeed>`
+
+Parse feed from URL.
+
+```typescript
+const feed = await parser.parseURL('https://example.com/feed.xml');
+```
+
+##### `parseFile(filePath: string): Promise<ParsedFeed>`
+
+Parse feed from local file.
+
+```typescript
+const feed = await parser.parseFile('./feed.xml');
+```
+
+##### `parseBuffer(buffer: Buffer, encoding?: BufferEncoding): Promise<ParsedFeed>`
+
+Parse feed from Buffer.
+
+```typescript
+const feed = await parser.parseBuffer(buffer, 'utf-8');
+```
+
+##### `parseStream(stream: Readable, maxChunkSize?: number): Promise<ParsedFeed>`
+
+Parse feed from Node.js Readable stream.
+
+```typescript
+const feed = await parser.parseStream(stream, 10 * 1024 * 1024);
+```
+
+##### `parseJSON(json: string): Promise<ParsedFeed>`
+
+Parse JSON Feed 1.0 from JSON string.
+
+```typescript
+const feed = await parser.parseJSON('{"version": "https://jsonfeed.org/version/1", "title": "My Feed", ...}');
+```
+
+#### ParsedFeed Interface
+
+```typescript
+interface ParsedFeed {
+  title?: string;
+  description?: string;
+  link?: string;
+  feedUrl?: string;
+  language?: string;
+  lastBuildDate?: string;
+  image?: {
+    url?: string;
+    title?: string;
+    link?: string;
+  };
+  items: ParsedItem[];
+  itunes?: any;  // Podcast metadata
+  [key: string]: any;  // Custom fields
+}
+```
+
+#### ParsedItem Interface
+
+```typescript
+interface ParsedItem {
+  title?: string;
+  link?: string;
+  pubDate?: string;
+  date?: string;
+  isoDate?: string;
+  author?: string;
+  content?: string;
+  contentSnippet?: string;
+  summary?: string;
+  guid?: string;
+  enclosure?: {
+    url?: string;
+    length?: string;
+    type?: string;
+  };
+  categories?: any[];
+  itunes?: any;  // Podcast metadata
+  [key: string]: any;  // Custom fields
+}
+```
+
+### Feed Class
+
+#### Constructor
+
+```typescript
+constructor(options: FeedOptions)
+```
+
+**Options:**
+```typescript
+interface FeedOptions {
+  title: string;
+  description?: string;
+  link?: string;
+  id?: string;
+  language?: string;
+  copyright?: string;
+  updated?: Date;
+  author?: Author;
+}
+```
+
+#### Methods
+
+##### `addItem(item: Item): void`
+
+Add an item to the feed.
+
+```typescript
+feed.addItem({
+  title: 'Post Title',
+  link: 'https://example.com/post',
+  description: 'Post description',
+  content: 'Full HTML content',
+  author: 'Author Name',
+  date: new Date(),
+});
+```
+
+##### `addCategory(category: string): void`
+
+Add a category to the feed.
+
+```typescript
+feed.addCategory('technology');
+feed.addCategory('programming');
+```
+
+##### `addContributor(contributor: Author): void`
+
+Add a contributor to the feed.
+
+```typescript
+feed.addContributor({
+  name: 'Jane Doe',
+  email: 'jane@example.com',
+  link: 'https://example.com/jane',
+});
+```
+
+##### `addExtension(extension: Extension): void`
+
+Add a custom extension to the feed.
+
+```typescript
+feed.addExtension({
+  name: 'itunes',
+  objects: { author: 'Podcast Author' },
+});
+```
+
+##### `rss2(): string`
+
+Generate RSS 2.0 feed.
+
+```typescript
+const rss = feed.rss2();
+```
+
+##### `atom1(): string`
+
+Generate Atom 1.0 feed.
+
+```typescript
+const atom = feed.atom1();
+```
+
+##### `json1(): string`
+
+Generate JSON Feed 1.0.
+
+```typescript
+const json = feed.json1();
+```
+
+### Validation Utilities
+
+The library includes feed validation utilities to help ensure feeds meet format specifications:
+
+#### `validateRSS2(feed: ParsedFeed): ValidationResult`
+
+Validate RSS 2.0 feeds for compliance.
+
+```typescript
+import { validateRSS2 } from 'rss.today';
+
+const result = validateRSS2(parsedFeed);
+
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+if (result.warnings.length > 0) {
+  console.warn('Validation warnings:', result.warnings);
+}
+```
+
+#### `validateAtom(feed: ParsedFeed): ValidationResult`
+
+Validate Atom 1.0 feeds for compliance.
+
+```typescript
+import { validateAtom } from 'rss.today';
+
+const result = validateAtom(parsedFeed);
+```
+
+#### `validateJSONFeed(feed: any): ValidationResult`
+
+Validate JSON Feed 1.0 for compliance.
+
+```typescript
+import { validateJSONFeed } from 'rss.today';
+
+const result = validateJSONFeed(jsonFeed);
+```
+
+### Conversion Utilities
+
+Convert parsed feeds between different formats:
+
+#### `convertToRSS2(feed: ParsedFeed): string`
+
+Convert any parsed feed to RSS 2.0 format.
+
+```typescript
+import { Parser, convertToRSS2 } from 'rss.today';
+
+const parser = new Parser();
+const atomFeed = await parser.parseString(atomXml);
+const rss2Xml = convertToRSS2(atomFeed);
+```
+
+#### `convertToAtom(feed: ParsedFeed): string`
+
+Convert any parsed feed to Atom 1.0 format.
+
+```typescript
+import { convertToAtom } from 'rss.today';
+
+const rss2Feed = await parser.parseString(rssXml);
+const atomXml = convertToAtom(rss2Feed);
+```
+
+#### `convertToJSON(feed: ParsedFeed): string`
+
+Convert any parsed feed to JSON Feed 1.0 format.
+
+```typescript
+import { convertToJSON } from 'rss.today';
+
+const atomFeed = await parser.parseString(atomXml);
+const jsonFeed = convertToJSON(atomFeed);
+```
+
+### Feed Utilities
+
+Utilities for manipulating and managing feeds:
+
+#### `mergeFeeds(feeds: ParsedFeed[]): ParsedFeed`
+
+Combine multiple feeds into one, automatically removing duplicates.
+
+```typescript
+import { Parser, mergeFeeds } from 'rss.today';
+
+const parser = new Parser();
+const feeds = await Promise.all([
+  parser.parseURL('https://example.com/feed1.xml'),
+  parser.parseURL('https://example.com/feed2.xml')
+]);
+
+const merged = mergeFeeds(feeds);
+console.log(`Merged ${merged.items.length} items`);
+```
+
+#### `diffFeeds(oldFeed: ParsedFeed, newFeed: ParsedFeed): FeedDiffResult`
+
+Compare two feeds to find differences.
+
+```typescript
+import { Parser, diffFeeds } from 'rss.today';
+
+const oldFeed = await parser.parseFile('./old-feed.xml');
+const newFeed = await parser.parseFile('./new-feed.xml');
+
+const diff = diffFeeds(oldFeed, newFeed);
+
+console.log(`Added: ${diff.added.length}`);
+console.log(`Removed: ${diff.removed.length}`);
+console.log(`Modified: ${diff.modified.length}`);
+```
+
+#### `filterFeed(feed: ParsedFeed, predicate: (item, ParsedItem) => boolean): ParsedFeed`
+
+Filter feed items using a custom predicate.
+
+#### `filterByCategory(feed: ParsedFeed, category: string): ParsedFeed`
+
+Filter items by category.
+
+```typescript
+import { filterByCategory } from 'rss.today';
+
+const techFeed = filterByCategory(feed, 'technology');
+```
+
+#### `filterByDateRange(feed: ParsedFeed, startDate: Date, endDate?: Date): ParsedFeed`
+
+Filter items by date range.
+
+```typescript
+import { filterByDateRange } from 'rss.today';
+
+const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+const recentFeed = filterByDateRange(feed, weekAgo);
+```
+
+#### `sortByDate(feed: ParsedFeed, order?: 'asc' | 'desc'): ParsedFeed`
+
+Sort feed items by date.
+
+```typescript
+import { sortByDate } from 'rss.today';
+
+const sorted = sortByDate(feed, 'desc'); // newest first
+```
+
+#### `sortByTitle(feed: ParsedFeed, order?: 'asc' | 'desc'): ParsedFeed`
+
+Sort feed items by title.
+
+#### `limitFeed(feed: ParsedFeed, count: number): ParsedFeed`
+
+Limit feed to a specific number of items.
+
+```typescript
+import { limitFeed } from 'rss.today';
+
+const latest10 = limitFeed(feed, 10);
+```
+
+#### `deduplicateFeed(feed: ParsedFeed): ParsedFeed`
+
+Remove duplicate items from a feed.
+
+```typescript
+import { deduplicateFeed } from 'rss.today';
+
+const unique = deduplicateFeed(feed);
+```
+
+### OPML Support
+
+Parse and generate OPML (Outline Processor Markup Language) files for feed subscriptions:
+
+#### `OPMLParser`
+
+Parse OPML subscription lists.
+
+```typescript
+import { OPMLParser } from 'rss.today';
+
+const parser = new OPMLParser();
+const opml = await parser.parseOPML(opmlXml);
+
+console.log(opml.title);
+console.log(opml.outlines.length);
+```
+
+#### `OPMLGenerator`
+
+Generate OPML subscription lists.
+
+```typescript
+import { OPMLGenerator, type OPMLDocument } from 'rss.today';
+
+const opml: OPMLDocument = {
+  title: 'My Subscriptions',
+  outlines: [
+    {
+      text: 'TechCrunch',
+      type: 'rss',
+      xmlUrl: 'https://techcrunch.com/feed/',
+      htmlUrl: 'https://techcrunch.com'
+    }
+  ]
+};
+
+const generator = new OPMLGenerator();
+const opmlXml = generator.generateOPML(opml);
+```
+
+## Supported Formats
+
+| Format | Parse | Generate |
+|--------|-------|----------|
+| RSS 0.9 | ✅ | ✅ |
+| RSS 1.0 | ✅ | ✅ |
+| RSS 2.0 | ✅ | ✅ |
+| Atom 1.0 | ✅ | ✅ |
+| JSON Feed 1.0 | ✅ | ✅ |
+
+## Podcast Support
+
+The parser automatically detects and extracts iTunes podcast metadata:
+
+```typescript
+const feed = await parser.parseURL('https://example.com/podcast.xml');
+
+console.log(feed.itunes?.author);
+console.log(feed.itunes?.summary);
+console.log(feed.itunes?.image);
+
+// Items also have iTunes metadata
+feed.items.forEach(item => {
+  console.log(item.itunes?.duration);
+  console.log(item.itunes?.subtitle);
+});
+```
+
+## Error Handling
+
+```typescript
+import { Parser } from 'rss.today';
+
+const parser = new Parser();
+
+try {
+  const feed = await parser.parseURL('https://example.com/feed.xml');
+  console.log(feed.title);
+} catch (error) {
+  if (error.message.includes('Feed not recognized')) {
+    console.error('Unsupported feed format');
+  } else if (error.message.includes('File not found')) {
+    console.error('File does not exist');
+  } else {
+    console.error('Error:', error.message);
+  }
+}
+```
+
+## Complete Examples
+
+### Parse a Blog Feed
+
+```typescript
+import { Parser } from 'rss.today';
+
+async function displayLatestPosts(url: string, count: number = 5) {
+  const parser = new Parser();
+  const feed = await parser.parseURL(url);
+
+  console.log(`=== ${feed.title} ===`);
+  console.log(feed.description);
+  console.log(`Last updated: ${feed.lastBuildDate}\n`);
+
+  feed.items.slice(0, count).forEach((item, index) => {
+    console.log(`${index + 1}. ${item.title}`);
+    console.log(`   ${item.link}`);
+    console.log(`   ${item.pubDate}\n`);
+  });
+}
+
+displayLatestPosts('https://example.com/blog/feed.xml');
+```
+
+### Generate a Podcast Feed
+
+```typescript
+import { Feed } from 'rss.today';
+
+const feed = new Feed({
+  title: 'My Podcast',
+  description: 'A podcast about interesting topics',
+  link: 'https://example.com',
+  id: 'https://example.com/feed',
+  language: 'en',
+});
+
+// Add iTunes extension
+feed.addExtension({
+  name: 'itunes',
+  objects: {
+    author: 'Podcast Author',
+    summary: 'A podcast about interesting topics',
+    explicit: 'no',
+    image: 'https://example.com/podcast.jpg',
+  },
+});
+
+// Add episodes
+feed.addItem({
+  title: 'Episode 1: Introduction',
+  link: 'https://example.com/episode-1',
+  description: 'Welcome to our first episode!',
+  date: new Date('2024-01-01'),
+  enclosure: {
+    url: 'https://example.com/episode-1.mp3',
+    type: 'audio/mpeg',
+    length: '12345678',
+  },
+});
+
+const rss = feed.rss2();
+console.log(rss);
+```
+
+### Parse from Multiple Sources
+
+```typescript
+import { Parser } from 'rss.today';
+import * as fs from 'fs/promises';
+
+const parser = new Parser();
+
+// Parse from URL
+const feed1 = await parser.parseURL('https://example.com/feed.xml');
+
+// Parse from string
+const xml = await fs.readFile('./feed.xml', 'utf-8');
+const feed2 = await parser.parseString(xml);
+
+// Parse from file
+const feed3 = await parser.parseFile('./feed.xml');
+
+// Parse from buffer
+const buffer = Buffer.from(xml);
+const feed4 = await parser.parseBuffer(buffer);
+
+// Parse from stream
+const stream = fs.createReadStream('./feed.xml');
+const feed5 = await parser.parseStream(stream);
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+## License
+
+ISC
+
+## Repository
+
+[https://github.com/rssToday/rsstoday](https://github.com/rssToday/rsstoday)

package/dist/atom1.d.ts

@@ -0,0 +1,8 @@
+import type { Feed } from "./feed";
+/**
+ * Returns an Atom feed
+ * @param ins
+ */
+declare const _default: (ins: Feed) => string;
+export default _default;
+//# sourceMappingURL=atom1.d.ts.map