feedparser-rs 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,10 @@
 # feedparser-rs
 
-High-performance RSS/Atom/JSON Feed parser written in Rust with Node.js bindings.
+[![npm](https://img.shields.io/npm/v/feedparser-rs)](https://www.npmjs.com/package/feedparser-rs)
+[![Node](https://img.shields.io/node/v/feedparser-rs)](https://www.npmjs.com/package/feedparser-rs)
+[![License](https://img.shields.io/npm/l/feedparser-rs)](LICENSE)
+
+High-performance RSS/Atom/JSON Feed parser for Node.js, written in Rust.
 
 Drop-in replacement for Python's `feedparser` library, offering 10-100x performance improvement.
 
@@ -8,9 +12,10 @@ Drop-in replacement for Python's `feedparser` library, offering 10-100x performa
 
 - **Fast**: Written in Rust, 10-100x faster than Python feedparser
 - **Tolerant**: Handles malformed feeds with bozo flag (like feedparser)
-- **Multi-format**: Supports RSS 0.9x/1.0/2.0, Atom 0.3/1.0, JSON Feed 1.0/1.1
-- **Zero-copy**: Efficient parsing with minimal allocations
+- **Multi-format**: RSS 0.9x/1.0/2.0, Atom 0.3/1.0, JSON Feed 1.0/1.1
+- **HTTP fetching**: Built-in URL fetching with compression support
 - **TypeScript**: Full TypeScript definitions included
+- **Zero-copy**: Efficient parsing with minimal allocations
 
 ## Installation
 
@@ -22,12 +27,14 @@ yarn add feedparser-rs
 pnpm add feedparser-rs
 ```
 
+> [!IMPORTANT]
+> Requires Node.js 18 or later.
+
 ## Quick Start
 
 ```javascript
 import { parse } from 'feedparser-rs';
 
-// Parse from string
 const feed = parse(`
   <?xml version="1.0"?>
   <rss version="2.0">
@@ -44,8 +51,28 @@ const feed = parse(`
 console.log(feed.feed.title);  // "My Blog"
 console.log(feed.entries[0].title);  // "Hello World"
 console.log(feed.version);  // "rss20"
+```
+
+## HTTP Fetching
+
+Fetch and parse feeds directly from URLs:
+
+```javascript
+import { fetchAndParse } from 'feedparser-rs';
+
+const feed = await fetchAndParse('https://example.com/feed.xml');
+console.log(feed.feed.title);
+console.log(`Fetched ${feed.entries.length} entries`);
+```
+
+> [!TIP]
+> `fetchAndParse` automatically handles compression (gzip, deflate, brotli) and follows redirects.
+
+### Parsing from Buffer
+
+```javascript
+import { parse } from 'feedparser-rs';
 
-// Parse from Buffer (e.g., HTTP response)
 const response = await fetch('https://example.com/feed.xml');
 const buffer = Buffer.from(await response.arrayBuffer());
 const feed = parse(buffer);
@@ -66,24 +93,23 @@ Parse a feed from bytes or string.
 **Throws:**
 - `Error` if parsing fails catastrophically
 
-**Example:**
-```javascript
-const feed = parse('<rss version="2.0">...</rss>');
-console.log(feed.feed.title);
-console.log(feed.entries.length);
-```
+### `fetchAndParse(url: string): Promise<ParsedFeed>`
+
+Fetch and parse a feed from URL.
+
+**Parameters:**
+- `url` - Feed URL to fetch
+
+**Returns:**
+- Promise resolving to `ParsedFeed` object
 
 ### `detectFormat(source: Buffer | string | Uint8Array): string`
 
 Detect feed format without full parsing.
 
-**Parameters:**
-- `source` - Feed content as Buffer, string, or Uint8Array
-
 **Returns:**
 - Format string: `"rss20"`, `"atom10"`, `"json11"`, etc.
 
-**Example:**
 ```javascript
 const format = detectFormat('<feed xmlns="http://www.w3.org/2005/Atom">...</feed>');
 console.log(format);  // "atom10"
@@ -114,22 +140,11 @@ interface FeedMeta {
   link?: string;
   links: Link[];
   subtitle?: string;
-  subtitle_detail?: TextConstruct;
   updated?: number;  // Milliseconds since epoch
   author?: string;
-  author_detail?: Person;
   authors: Person[];
-  contributors: Person[];
-  publisher?: string;
-  publisher_detail?: Person;
   language?: string;
-  rights?: string;
-  rights_detail?: TextConstruct;
-  generator?: string;
-  generator_detail?: Generator;
   image?: Image;
-  icon?: string;
-  logo?: string;
   tags: Tag[];
   id?: string;
   ttl?: number;
@@ -142,94 +157,21 @@ interface FeedMeta {
 interface Entry {
   id?: string;
   title?: string;
-  title_detail?: TextConstruct;
   link?: string;
   links: Link[];
   summary?: string;
-  summary_detail?: TextConstruct;
   content: Content[];
   published?: number;  // Milliseconds since epoch
   updated?: number;
-  created?: number;
-  expired?: number;
   author?: string;
-  author_detail?: Person;
   authors: Person[];
-  contributors: Person[];
-  publisher?: string;
-  publisher_detail?: Person;
   tags: Tag[];
   enclosures: Enclosure[];
-  comments?: string;
-  source?: Source;
 }
 ```
 
-### Other Types
-
-```typescript
-interface TextConstruct {
-  value: string;
-  type: "text" | "html" | "xhtml";
-  language?: string;
-  base?: string;
-}
-
-interface Link {
-  href: string;
-  rel?: string;
-  type?: string;
-  title?: string;
-  length?: number;
-  hreflang?: string;
-}
-
-interface Person {
-  name?: string;
-  email?: string;
-  uri?: string;
-}
-
-interface Tag {
-  term: string;
-  scheme?: string;
-  label?: string;
-}
-
-interface Image {
-  url: string;
-  title?: string;
-  link?: string;
-  width?: number;
-  height?: number;
-  description?: string;
-}
-
-interface Enclosure {
-  url: string;
-  length?: number;
-  type?: string;
-}
-
-interface Content {
-  value: string;
-  type?: string;
-  language?: string;
-  base?: string;
-}
-
-interface Generator {
-  value: string;
-  uri?: string;
-  version?: string;
-}
-
-interface Source {
-  title?: string;
-  link?: string;
-  id?: string;
-}
-```
+> [!NOTE]
+> See `index.d.ts` for complete type definitions including `Link`, `Person`, `Tag`, `Image`, `Enclosure`, and more.
 
 ## Error Handling
 
@@ -248,11 +190,9 @@ console.log(feed.feed.title);  // "Broken"
 
 ## Dates
 
-All date fields are returned as milliseconds since Unix epoch (number type). Convert to JavaScript Date:
+All date fields are returned as milliseconds since Unix epoch. Convert to JavaScript Date:
 
 ```javascript
-const feed = parse(xmlWithDates);
-
 const entry = feed.entries[0];
 if (entry.published) {
   const date = new Date(entry.published);
@@ -269,16 +209,17 @@ Benchmarks vs Python feedparser (parsing 100KB RSS feed):
 | feedparser-rs | 0.5ms | 100x |
 | feedparser (Python) | 50ms | 1x |
 
-See [benchmarks/](../../benchmarks/) for detailed results and methodology.
-
 ## Platform Support
 
 Pre-built binaries available for:
-- macOS (Intel & Apple Silicon)
-- Linux (x64, ARM64)
-- Windows (x64)
 
-Supported Node.js versions: 18, 20, 22
+| Platform | Architecture |
+|----------|--------------|
+| macOS | Intel (x64), Apple Silicon (arm64) |
+| Linux | x64, arm64 |
+| Windows | x64 |
+
+Supported Node.js versions: 18, 20, 22+
 
 ## Development
 
@@ -291,15 +232,23 @@ npm run build
 
 # Run tests
 npm test
+
+# Run tests with coverage
+npm run test:coverage
 ```
 
 ## License
 
-MIT OR Apache-2.0
+Licensed under either of:
+
+- [Apache License, Version 2.0](../../LICENSE-APACHE)
+- [MIT License](../../LICENSE-MIT)
+
+at your option.
 
 ## Links
 
 - [GitHub](https://github.com/bug-ops/feedparser-rs)
 - [npm](https://www.npmjs.com/package/feedparser-rs)
-- [Documentation](https://docs.rs/feedparser-rs-core)
+- [Rust API Documentation](https://docs.rs/feedparser-rs)
 - [Changelog](../../CHANGELOG.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feedparser-rs",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "High-performance RSS/Atom/JSON Feed parser for Node.js",
   "main": "index.js",
   "types": "index.d.ts",