feedsmith 2.0.0-next.4 → 2.0.0-next.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +77 -777
- package/dist/common/config.js +0 -1
- package/dist/common/parse.js +0 -1
- package/dist/common/types.d.ts +18 -3
- package/dist/common/types.js +0 -1
- package/dist/common/utils.d.ts +6 -4
- package/dist/common/utils.js +26 -11
- package/dist/feeds/atom/common/types.js +1 -1
- package/dist/feeds/atom/detect/index.js +0 -1
- package/dist/feeds/atom/generate/config.js +0 -1
- package/dist/feeds/atom/generate/index.d.ts +2 -2
- package/dist/feeds/atom/generate/index.js +0 -1
- package/dist/feeds/atom/generate/utils.d.ts +5 -4
- package/dist/feeds/atom/generate/utils.js +0 -1
- package/dist/feeds/atom/parse/config.js +0 -1
- package/dist/feeds/atom/parse/index.js +0 -1
- package/dist/feeds/atom/parse/utils.js +0 -1
- package/dist/feeds/json/common/types.js +1 -1
- package/dist/feeds/json/detect/index.js +0 -1
- package/dist/feeds/json/generate/index.d.ts +2 -1
- package/dist/feeds/json/generate/index.js +0 -1
- package/dist/feeds/json/generate/utils.d.ts +1917 -28
- package/dist/feeds/json/generate/utils.js +4 -4
- package/dist/feeds/json/parse/index.js +0 -1
- package/dist/feeds/json/parse/utils.js +0 -1
- package/dist/feeds/rdf/common/types.js +1 -1
- package/dist/feeds/rdf/detect/index.js +0 -1
- package/dist/feeds/rdf/parse/config.js +0 -1
- package/dist/feeds/rdf/parse/index.js +0 -1
- package/dist/feeds/rdf/parse/utils.js +0 -1
- package/dist/feeds/rss/common/types.js +1 -1
- package/dist/feeds/rss/detect/index.js +0 -1
- package/dist/feeds/rss/generate/config.js +0 -1
- package/dist/feeds/rss/generate/index.d.ts +2 -2
- package/dist/feeds/rss/generate/index.js +0 -1
- package/dist/feeds/rss/generate/utils.d.ts +3 -3
- package/dist/feeds/rss/generate/utils.js +0 -1
- package/dist/feeds/rss/parse/config.js +0 -1
- package/dist/feeds/rss/parse/index.js +0 -1
- package/dist/feeds/rss/parse/utils.js +0 -1
- package/dist/index.js +0 -1
- package/dist/namespaces/atom/common/types.js +1 -1
- package/dist/namespaces/atom/generate/utils.d.ts +3 -3
- package/dist/namespaces/atom/generate/utils.js +0 -1
- package/dist/namespaces/atom/parse/utils.js +0 -1
- package/dist/namespaces/content/common/types.js +1 -1
- package/dist/namespaces/content/generate/utils.js +0 -1
- package/dist/namespaces/content/parse/utils.js +0 -1
- package/dist/namespaces/dc/common/types.js +1 -1
- package/dist/namespaces/dc/generate/utils.d.ts +2 -2
- package/dist/namespaces/dc/generate/utils.js +0 -1
- package/dist/namespaces/dc/parse/utils.js +0 -1
- package/dist/namespaces/dcterms/common/types.js +1 -1
- package/dist/namespaces/dcterms/generate/utils.d.ts +2 -2
- package/dist/namespaces/dcterms/generate/utils.js +0 -1
- package/dist/namespaces/dcterms/parse/utils.js +0 -1
- package/dist/namespaces/georss/common/types.js +1 -1
- package/dist/namespaces/georss/generate/utils.js +0 -1
- package/dist/namespaces/georss/parse/utils.js +0 -1
- package/dist/namespaces/itunes/common/types.js +1 -1
- package/dist/namespaces/itunes/generate/utils.js +0 -1
- package/dist/namespaces/itunes/parse/utils.js +0 -1
- package/dist/namespaces/media/common/types.js +1 -1
- package/dist/namespaces/media/generate/utils.js +0 -1
- package/dist/namespaces/media/parse/utils.js +0 -1
- package/dist/namespaces/podcast/common/types.js +1 -1
- package/dist/namespaces/podcast/generate/utils.d.ts +5 -5
- package/dist/namespaces/podcast/generate/utils.js +0 -1
- package/dist/namespaces/podcast/parse/utils.js +0 -1
- package/dist/namespaces/slash/common/types.js +1 -1
- package/dist/namespaces/slash/generate/utils.js +0 -1
- package/dist/namespaces/slash/parse/utils.js +0 -1
- package/dist/namespaces/sy/common/types.js +1 -1
- package/dist/namespaces/sy/generate/utils.d.ts +2 -2
- package/dist/namespaces/sy/generate/utils.js +0 -1
- package/dist/namespaces/sy/parse/utils.js +0 -1
- package/dist/namespaces/thr/common/types.js +1 -1
- package/dist/namespaces/thr/generate/utils.d.ts +2 -2
- package/dist/namespaces/thr/generate/utils.js +0 -1
- package/dist/namespaces/thr/parse/utils.js +0 -1
- package/dist/namespaces/wfw/common/types.js +1 -1
- package/dist/namespaces/wfw/generate/utils.js +0 -1
- package/dist/namespaces/wfw/parse/utils.js +0 -1
- package/dist/namespaces/yt/common/types.js +1 -1
- package/dist/namespaces/yt/generate/utils.js +0 -1
- package/dist/namespaces/yt/parse/utils.js +0 -1
- package/dist/opml/common/types.js +1 -1
- package/dist/opml/generate/config.js +0 -1
- package/dist/opml/generate/index.d.ts +2 -2
- package/dist/opml/generate/index.js +0 -1
- package/dist/opml/generate/utils.d.ts +5 -5
- package/dist/opml/generate/utils.js +0 -1
- package/dist/opml/parse/config.js +0 -1
- package/dist/opml/parse/index.js +0 -1
- package/dist/opml/parse/utils.js +0 -1
- package/package.json +11 -6
- package/dist/common/config.js.map +0 -1
- package/dist/common/parse.js.map +0 -1
- package/dist/common/types.js.map +0 -1
- package/dist/common/utils.js.map +0 -1
- package/dist/feeds/atom/common/types.js.map +0 -1
- package/dist/feeds/atom/detect/index.js.map +0 -1
- package/dist/feeds/atom/generate/config.js.map +0 -1
- package/dist/feeds/atom/generate/index.js.map +0 -1
- package/dist/feeds/atom/generate/utils.js.map +0 -1
- package/dist/feeds/atom/parse/config.js.map +0 -1
- package/dist/feeds/atom/parse/index.js.map +0 -1
- package/dist/feeds/atom/parse/utils.js.map +0 -1
- package/dist/feeds/json/common/types.js.map +0 -1
- package/dist/feeds/json/detect/index.js.map +0 -1
- package/dist/feeds/json/generate/index.js.map +0 -1
- package/dist/feeds/json/generate/utils.js.map +0 -1
- package/dist/feeds/json/parse/index.js.map +0 -1
- package/dist/feeds/json/parse/utils.js.map +0 -1
- package/dist/feeds/rdf/common/types.js.map +0 -1
- package/dist/feeds/rdf/detect/index.js.map +0 -1
- package/dist/feeds/rdf/parse/config.js.map +0 -1
- package/dist/feeds/rdf/parse/index.js.map +0 -1
- package/dist/feeds/rdf/parse/utils.js.map +0 -1
- package/dist/feeds/rss/common/types.js.map +0 -1
- package/dist/feeds/rss/detect/index.js.map +0 -1
- package/dist/feeds/rss/generate/config.js.map +0 -1
- package/dist/feeds/rss/generate/index.js.map +0 -1
- package/dist/feeds/rss/generate/utils.js.map +0 -1
- package/dist/feeds/rss/parse/config.js.map +0 -1
- package/dist/feeds/rss/parse/index.js.map +0 -1
- package/dist/feeds/rss/parse/utils.js.map +0 -1
- package/dist/index.js.map +0 -1
- package/dist/namespaces/atom/common/types.js.map +0 -1
- package/dist/namespaces/atom/generate/utils.js.map +0 -1
- package/dist/namespaces/atom/parse/utils.js.map +0 -1
- package/dist/namespaces/content/common/types.js.map +0 -1
- package/dist/namespaces/content/generate/utils.js.map +0 -1
- package/dist/namespaces/content/parse/utils.js.map +0 -1
- package/dist/namespaces/dc/common/types.js.map +0 -1
- package/dist/namespaces/dc/generate/utils.js.map +0 -1
- package/dist/namespaces/dc/parse/utils.js.map +0 -1
- package/dist/namespaces/dcterms/common/types.js.map +0 -1
- package/dist/namespaces/dcterms/generate/utils.js.map +0 -1
- package/dist/namespaces/dcterms/parse/utils.js.map +0 -1
- package/dist/namespaces/georss/common/types.js.map +0 -1
- package/dist/namespaces/georss/generate/utils.js.map +0 -1
- package/dist/namespaces/georss/parse/utils.js.map +0 -1
- package/dist/namespaces/itunes/common/types.js.map +0 -1
- package/dist/namespaces/itunes/generate/utils.js.map +0 -1
- package/dist/namespaces/itunes/parse/utils.js.map +0 -1
- package/dist/namespaces/media/common/types.js.map +0 -1
- package/dist/namespaces/media/generate/utils.js.map +0 -1
- package/dist/namespaces/media/parse/utils.js.map +0 -1
- package/dist/namespaces/podcast/common/types.js.map +0 -1
- package/dist/namespaces/podcast/generate/utils.js.map +0 -1
- package/dist/namespaces/podcast/parse/utils.js.map +0 -1
- package/dist/namespaces/slash/common/types.js.map +0 -1
- package/dist/namespaces/slash/generate/utils.js.map +0 -1
- package/dist/namespaces/slash/parse/utils.js.map +0 -1
- package/dist/namespaces/sy/common/types.js.map +0 -1
- package/dist/namespaces/sy/generate/utils.js.map +0 -1
- package/dist/namespaces/sy/parse/utils.js.map +0 -1
- package/dist/namespaces/thr/common/types.js.map +0 -1
- package/dist/namespaces/thr/generate/utils.js.map +0 -1
- package/dist/namespaces/thr/parse/utils.js.map +0 -1
- package/dist/namespaces/wfw/common/types.js.map +0 -1
- package/dist/namespaces/wfw/generate/utils.js.map +0 -1
- package/dist/namespaces/wfw/parse/utils.js.map +0 -1
- package/dist/namespaces/yt/common/types.js.map +0 -1
- package/dist/namespaces/yt/generate/utils.js.map +0 -1
- package/dist/namespaces/yt/parse/utils.js.map +0 -1
- package/dist/opml/common/types.js.map +0 -1
- package/dist/opml/generate/config.js.map +0 -1
- package/dist/opml/generate/index.js.map +0 -1
- package/dist/opml/generate/utils.js.map +0 -1
- package/dist/opml/parse/config.js.map +0 -1
- package/dist/opml/parse/index.js.map +0 -1
- package/dist/opml/parse/utils.js.map +0 -1
package/README.md
CHANGED
|
@@ -9,44 +9,43 @@ Robust and fast JavaScript parser and generator for RSS, Atom, JSON Feed, and RD
|
|
|
9
9
|
|
|
10
10
|
Feedsmith provides both universal and format-specific parsers that maintain the original feed structure in a clean, object-oriented format while intelligently normalizing legacy elements. Access all feed data without compromising simplicity.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
>
|
|
14
|
-
> You're viewing the README for the next version of Feedsmith (v2.0), which includes major improvements and breaking changes. While the codebase is stable, the API may still undergo slight changes. This version is currently only available through the `next` channel for early testing. For production use, it is recommended to use the latest stable version.
|
|
15
|
-
> ```bash
|
|
16
|
-
> npm install feedsmith@latest # Stable version 1.9.0
|
|
17
|
-
> npm install feedsmith@next # Development version 2.0.0-next.x
|
|
18
|
-
> ```
|
|
19
|
-
|
|
20
|
-
[Features](#supported-formats)
|
|
12
|
+
**[Read full docs ↗](https://feedsmith.dev)**
|
|
21
13
|
·
|
|
22
|
-
[
|
|
14
|
+
[Quick Start](#quick-start)
|
|
23
15
|
·
|
|
24
|
-
[
|
|
16
|
+
[Why Feedsmith?](#why-feedsmith)
|
|
25
17
|
·
|
|
26
|
-
[
|
|
27
|
-
·
|
|
28
|
-
[Benchmarks](#benchmarks)
|
|
29
|
-
·
|
|
30
|
-
[FAQ](#faq)
|
|
18
|
+
[Benchmarks →](benchmarks/README.md)
|
|
31
19
|
|
|
32
20
|
---
|
|
33
21
|
|
|
34
|
-
|
|
35
|
-
|
|
22
|
+
## Features
|
|
23
|
+
|
|
24
|
+
### Core
|
|
25
|
+
|
|
26
|
+
* **Comprehensive Support** 🎯 — Supports all major feed formats and feed namespaces.
|
|
27
|
+
* **Perserves Structure** 📦 — Parsed feed object maintains the original feed structure making it easy to access the data.
|
|
28
|
+
* **Smart Namespace Handling** 🧠 — Automatically normalizes custom namespace prefixes to standard ones (e.g., `<custom:creator>` becomes `dc.creator`).
|
|
29
|
+
* **Parsing & Generating** 🔩 — You can use one package for both parsing and generating feeds.
|
|
30
|
+
|
|
31
|
+
### Leniency
|
|
32
|
+
* **Normalizes Legacy Elements** ✨ — Upgrades feed elements to their modern equivalents so that you never need to worry about reading feeds in older formats.
|
|
36
33
|
* **CaSe INSENsiTive** 🐍 — Handles fields and attributes in any case (lowercase, uppercase, mixed).
|
|
37
|
-
* **
|
|
34
|
+
* **Forgiving** 🤝 — Handles malformed or incomplete feeds gracefully. It will extract whatever valid data it can find and ignore missing or invalid elements. This makes it suitable for use with real-world feeds that may not strictly follow specifications.
|
|
38
35
|
|
|
39
|
-
|
|
40
|
-
* **
|
|
41
|
-
* **Type-safe API** 🛟 — TypeScript
|
|
36
|
+
### Performance and Type-Safety
|
|
37
|
+
* **Ultrafast parsing** ⚡ — One of the fastest feed parsers in JavaScript ([see benchmarks](benchmarks/README.md)).
|
|
38
|
+
* **Type-safe API** 🛟 — Built with TypeScript from the ground up, it provides complete type definitions for every feed format and namespace.
|
|
42
39
|
* **Tree-shakable** 🍃 — Only include the parts of the library you need, reducing bundle size.
|
|
43
40
|
* **Well-tested** 🔬 — Comprehensive test suite with over 2000 tests and 99% code coverage.
|
|
44
41
|
|
|
45
|
-
|
|
46
|
-
* Works in Node.js and
|
|
42
|
+
### Compatibility
|
|
43
|
+
* Works in Node.js and modern browsers.
|
|
47
44
|
* Works with plain JavaScript, you don't need to use TypeScript.
|
|
48
45
|
|
|
49
|
-
## Supported
|
|
46
|
+
## Supported Formats
|
|
47
|
+
|
|
48
|
+
Feedsmith aims to fully support all major feed formats and namespaces in complete alignment with their specifications.
|
|
50
49
|
|
|
51
50
|
✅ Available
|
|
52
51
|
·
|
|
@@ -65,7 +64,7 @@ Feedsmith provides both universal and format-specific parsers that maintain the
|
|
|
65
64
|
|
|
66
65
|
### Namespaces
|
|
67
66
|
|
|
68
|
-
| Name | Prefix
|
|
67
|
+
| Name | Prefix | Supported in | Parsing | Generating |
|
|
69
68
|
|------|---------|--------------|---------|------------|
|
|
70
69
|
| [Atom](http://www.w3.org/2005/Atom) | `<atom:*>` | RSS, RDF | ✅ | ✅ |
|
|
71
70
|
| [Dublin Core](http://purl.org/dc/elements/1.1/) | `<dc:*>` | RSS, Atom, RDF | ✅ | ✅ |
|
|
@@ -80,11 +79,6 @@ Feedsmith provides both universal and format-specific parsers that maintain the
|
|
|
80
79
|
| [Dublin Core Terms](http://purl.org/dc/terms/) | `<dcterms:*>` | RSS, Atom, RDF | ✅ | ✅ |
|
|
81
80
|
| [Well-Formed Web](http://wellformedweb.org/CommentAPI/) | `<wfw:*>` | RSS, Atom, RDF | ✅ | ✅ |
|
|
82
81
|
| [YouTube](https://www.youtube.com/feeds/videos.xml) | `<yt:*>` | Atom | ✅ | ✅ |
|
|
83
|
-
| [Administrative](https://web.resource.org/rss/1.0/modules/admin/) | `<admin:*>` | 📋 | 📋 | 📋 |
|
|
84
|
-
| [GML](http://www.opengis.net/gml) | `<gml:*>` | 📋 | 📋 | 📋 |
|
|
85
|
-
| [GeoRSS GML](http://www.opengis.net/gml) | `<georss:*>` | 📋 | 📋 | 📋 |
|
|
86
|
-
|
|
87
|
-
[^1]: Custom namespace prefixes are automatically normalized to standard ones (e.g., `<custom:creator>` → `dc.creator`).
|
|
88
82
|
|
|
89
83
|
### Other
|
|
90
84
|
|
|
@@ -92,24 +86,31 @@ Feedsmith provides both universal and format-specific parsers that maintain the
|
|
|
92
86
|
|--------|----------|---------|------------|
|
|
93
87
|
| [OPML](https://opml.org/) | 1.0, 2.0 | ✅ | ✅ |
|
|
94
88
|
|
|
95
|
-
##
|
|
89
|
+
## Quick Start
|
|
90
|
+
|
|
91
|
+
This guide will get you up and running with Feedsmith in just a few minutes.
|
|
92
|
+
|
|
93
|
+
For a full overview of all the features, visit the [documentation website](https://feedsmith.dev).
|
|
94
|
+
|
|
95
|
+
### Installation
|
|
96
96
|
|
|
97
97
|
```bash
|
|
98
98
|
npm install feedsmith
|
|
99
99
|
```
|
|
100
100
|
|
|
101
|
-
|
|
101
|
+
> **Upgrading from v1.x?** Check out the [migration guide](https://feedsmith.dev/migration-to-2.x).
|
|
102
102
|
|
|
103
|
-
###
|
|
103
|
+
### Parse Any Feed
|
|
104
104
|
|
|
105
105
|
The simplest way to parse any feed is to use the universal `parseFeed` function:
|
|
106
106
|
|
|
107
|
-
```
|
|
107
|
+
```typescript
|
|
108
108
|
import { parseFeed } from 'feedsmith'
|
|
109
109
|
|
|
110
|
-
|
|
110
|
+
// Works with RSS, Atom, JSON Feed, and RDF
|
|
111
|
+
const { format, feed } = parseFeed(feedContent)
|
|
111
112
|
|
|
112
|
-
console.log('Feed format:', format) //
|
|
113
|
+
console.log('Feed format:', format) // rss, atom, json, rdf
|
|
113
114
|
console.log('Feed title:', feed.title)
|
|
114
115
|
|
|
115
116
|
if (format === 'rss') {
|
|
@@ -117,767 +118,84 @@ if (format === 'rss') {
|
|
|
117
118
|
}
|
|
118
119
|
```
|
|
119
120
|
|
|
120
|
-
###
|
|
121
|
+
### Use Format-Specific Parsers
|
|
121
122
|
|
|
122
123
|
If you know the format in advance, you can use the format-specific parsers:
|
|
123
124
|
|
|
124
|
-
```
|
|
125
|
-
import {
|
|
125
|
+
```typescript
|
|
126
|
+
import {
|
|
127
|
+
parseAtomFeed,
|
|
128
|
+
parseJsonFeed,
|
|
129
|
+
parseRssFeed,
|
|
130
|
+
parseRdfFeed
|
|
131
|
+
} from 'feedsmith'
|
|
126
132
|
|
|
127
|
-
// Parse
|
|
133
|
+
// Parse specific formats
|
|
128
134
|
const atomFeed = parseAtomFeed('atom content')
|
|
129
135
|
const jsonFeed = parseJsonFeed('json content')
|
|
130
136
|
const rssFeed = parseRssFeed('rss content')
|
|
131
137
|
const rdfFeed = parseRdfFeed('rdf content')
|
|
132
138
|
|
|
133
|
-
//
|
|
139
|
+
// Access typed data
|
|
134
140
|
rssFeed.title
|
|
135
141
|
rssFeed.dc?.creator
|
|
136
|
-
rssFeed.dc?.date
|
|
137
|
-
rssFeed.sy?.updateBase
|
|
138
142
|
rssFeed.items?.[0]?.title
|
|
139
143
|
```
|
|
140
144
|
|
|
141
|
-
### OPML
|
|
142
|
-
|
|
143
|
-
Parsing OPML files is as simple:
|
|
145
|
+
### Parse OPML Files
|
|
144
146
|
|
|
145
|
-
```
|
|
147
|
+
```typescript
|
|
146
148
|
import { parseOpml } from 'feedsmith'
|
|
147
149
|
|
|
148
|
-
// Parse the OPML content
|
|
149
150
|
const opml = parseOpml('opml content')
|
|
150
151
|
|
|
151
|
-
// Then read the TypeScript suggestions
|
|
152
152
|
opml.head?.title
|
|
153
153
|
opml.body?.outlines?.[0].text
|
|
154
154
|
opml.body?.outlines?.[1].xmlUrl
|
|
155
155
|
```
|
|
156
156
|
|
|
157
|
-
###
|
|
158
|
-
|
|
159
|
-
The objects returned from the parser functions are highly comprehensive, aiming to recreate the actual feed structure and its values, including all the supported namespaces. Below are some examples of what is available.
|
|
160
|
-
|
|
161
|
-
```ts
|
|
162
|
-
import { parseAtomFeed } from 'feedsmith'
|
|
163
|
-
|
|
164
|
-
const atomFeed = parseAtomFeed(`
|
|
165
|
-
<?xml version="1.0" encoding="utf-8"?>
|
|
166
|
-
<feed xmlns="http://www.w3.org/2005/Atom">
|
|
167
|
-
<title>Example Feed</title>
|
|
168
|
-
<id>example-feed</id>
|
|
169
|
-
<dc:creator>John Doe</dc:creator>
|
|
170
|
-
<dc:contributor>Jane Smith</dc:contributor>
|
|
171
|
-
<dc:date>2022-01-01T12:00+00:00</dc:date>
|
|
172
|
-
<dc:description>This is an example of description.</dc:description>
|
|
173
|
-
<sy:updateBase>2000-01-01T12:00+00:00</sy:updateBase>
|
|
174
|
-
<sy:updatePeriod>hourly</sy:updatePeriod>
|
|
175
|
-
<sy:updateFrequency>1</sy:updateFrequency>
|
|
176
|
-
<entry>
|
|
177
|
-
<title>Example Entry</title>
|
|
178
|
-
<id>example-entry</id>
|
|
179
|
-
<dc:creator>Jack Jackson</dc:creator>
|
|
180
|
-
<dc:date>2022-01-01T12:00+00:00</dc:date>
|
|
181
|
-
</entry>
|
|
182
|
-
</feed>
|
|
183
|
-
`)
|
|
184
|
-
|
|
185
|
-
atomFeed.title // → Example Feed
|
|
186
|
-
atomFeed.dc?.contributor // → Jane Smith
|
|
187
|
-
atomFeed.dc?.date // → 2022-01-01T12:00+00:00
|
|
188
|
-
atomFeed.sy?.updateFrequency // → 1
|
|
189
|
-
atomFeed.entries?.[0]?.title // → Example Entry
|
|
190
|
-
atomFeed.entries?.[0]?.dc?.creator // → Jack Jackson
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
Returns:
|
|
194
|
-
|
|
195
|
-
```json
|
|
196
|
-
{
|
|
197
|
-
"id": "example-feed",
|
|
198
|
-
"title": "Example Feed",
|
|
199
|
-
"entries": [
|
|
200
|
-
{
|
|
201
|
-
"id": "example-entry",
|
|
202
|
-
"title": "Example Entry",
|
|
203
|
-
"dc": {
|
|
204
|
-
"creator": "Jack Jackson",
|
|
205
|
-
"date": "2022-01-01T12:00+00:00"
|
|
206
|
-
}
|
|
207
|
-
}
|
|
208
|
-
],
|
|
209
|
-
"dc": {
|
|
210
|
-
"creator": "John Doe",
|
|
211
|
-
"description": "This is an example of description.",
|
|
212
|
-
"contributor": "Jane Smith",
|
|
213
|
-
"date": "2022-01-01T12:00+00:00"
|
|
214
|
-
},
|
|
215
|
-
"sy": {
|
|
216
|
-
"updatePeriod": "hourly",
|
|
217
|
-
"updateFrequency": 1,
|
|
218
|
-
"updateBase": "2000-01-01T12:00+00:00"
|
|
219
|
-
}
|
|
220
|
-
}
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
<details>
|
|
224
|
-
<summary>Example of a more complex RSS feed 📜</summary>
|
|
225
|
-
|
|
226
|
-
```ts
|
|
227
|
-
import { parseRssFeed } from 'feedsmith'
|
|
228
|
-
|
|
229
|
-
const rssFeed = parseRssFeed(`
|
|
230
|
-
<?xml version="1.0" encoding="utf-8"?>
|
|
231
|
-
<rss version="2.0">
|
|
232
|
-
<channel>
|
|
233
|
-
<title><![CDATA[Sample Feed]]></title>
|
|
234
|
-
<link>http://example.org/</link>
|
|
235
|
-
<description>For documentation <em>only</em></description>
|
|
236
|
-
<language>en</language>
|
|
237
|
-
<webMaster>webmaster@example.org</webMaster>
|
|
238
|
-
<pubDate>Sat, 19 Mar 1988 07:15:00 GMT</pubDate>
|
|
239
|
-
<lastBuildDate>Sat, 19 Mar 1988 07:15:00 GMT</lastBuildDate>
|
|
240
|
-
<category domain="http://www.example.com/cusips">Examples2</category>
|
|
241
|
-
<generator>Sample Toolkit</generator>
|
|
242
|
-
<docs>http://feedvalidator.org/docs/rss2.html</docs>
|
|
243
|
-
<cloud domain="rpc.example.com" port="80" path="/RPC2" registerProcedure="pingMe" protocol="soap" />
|
|
244
|
-
<ttl>60</ttl>
|
|
245
|
-
<image>
|
|
246
|
-
<title>Example banner</title>
|
|
247
|
-
<url>http://example.org/banner.png</url>
|
|
248
|
-
<link>http://example.org/</link>
|
|
249
|
-
<description>Quos placeat quod ea temporibus ratione</description>
|
|
250
|
-
<width>80</width>
|
|
251
|
-
<height>15</height>
|
|
252
|
-
</image>
|
|
253
|
-
<textInput>
|
|
254
|
-
<title>Search</title>
|
|
255
|
-
<description><![CDATA[Search this site:]]></description>
|
|
256
|
-
<name>q</name>
|
|
257
|
-
<link>http://example.org/mt/mt-search.cgi</link>
|
|
258
|
-
</textInput>
|
|
259
|
-
<skipHours>
|
|
260
|
-
<hour>0</hour>
|
|
261
|
-
<hour>20</hour>
|
|
262
|
-
<hour>21</hour>
|
|
263
|
-
<hour>22</hour>
|
|
264
|
-
<hour>23</hour>
|
|
265
|
-
</skipHours>
|
|
266
|
-
<skipDays>
|
|
267
|
-
<day>Monday</day>
|
|
268
|
-
<day>Wednesday</day>
|
|
269
|
-
<day>Friday</day>
|
|
270
|
-
</skipDays>
|
|
271
|
-
<item>
|
|
272
|
-
<title>First item title</title>
|
|
273
|
-
<link>http://example.org/item/1</link>
|
|
274
|
-
<description>Some description of the first item.</description>
|
|
275
|
-
<comments>http://example.org/comments/1</comments>
|
|
276
|
-
<enclosure url="http://example.org/audio/demo.mp3" length="1069871" type="audio/mpeg" />
|
|
277
|
-
<guid isPermaLink="true">http://example.org/guid/1</guid>
|
|
278
|
-
<pubDate>Thu, 05 Sep 2002 0:00:01 GMT</pubDate>
|
|
279
|
-
<source url="http://www.example.org/links.xml">Example's Realm</source>
|
|
280
|
-
</item>
|
|
281
|
-
</channel>
|
|
282
|
-
</rss>
|
|
283
|
-
`)
|
|
284
|
-
|
|
285
|
-
rssFeed.title // → Sample Feed
|
|
286
|
-
rssFeed.textInput?.description // → Search this site:
|
|
287
|
-
rssFeed.items?.length // → 1
|
|
288
|
-
rssFeed.items?.[0]?.enclosure?.url // → http://example.org/audio/demo.mp3
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
Returns:
|
|
292
|
-
|
|
293
|
-
```json
|
|
294
|
-
{
|
|
295
|
-
"title": "Sample Feed",
|
|
296
|
-
"link": "http://example.org/",
|
|
297
|
-
"description": "For documentation <em>only</em>",
|
|
298
|
-
"language": "en",
|
|
299
|
-
"webMaster": "webmaster@example.org",
|
|
300
|
-
"pubDate": "Sat, 19 Mar 1988 07:15:00 GMT",
|
|
301
|
-
"lastBuildDate": "Sat, 19 Mar 1988 07:15:00 GMT",
|
|
302
|
-
"categories": [{ "name": "Examples2", "domain": "http://www.example.com/cusips" }],
|
|
303
|
-
"generator": "Sample Toolkit",
|
|
304
|
-
"docs": "http://feedvalidator.org/docs/rss2.html",
|
|
305
|
-
"cloud": {
|
|
306
|
-
"domain": "rpc.example.com",
|
|
307
|
-
"port": 80,
|
|
308
|
-
"path": "/RPC2",
|
|
309
|
-
"registerProcedure": "pingMe",
|
|
310
|
-
"protocol": "soap"
|
|
311
|
-
},
|
|
312
|
-
"ttl": 60,
|
|
313
|
-
"image": {
|
|
314
|
-
"url": "http://example.org/banner.png",
|
|
315
|
-
"title": "Example banner",
|
|
316
|
-
"link": "http://example.org/",
|
|
317
|
-
"description": "Quos placeat quod ea temporibus ratione",
|
|
318
|
-
"height": 15,
|
|
319
|
-
"width": 80
|
|
320
|
-
},
|
|
321
|
-
"textInput": {
|
|
322
|
-
"title": "Search",
|
|
323
|
-
"description": "Search this site:",
|
|
324
|
-
"name": "q",
|
|
325
|
-
"link": "http://example.org/mt/mt-search.cgi"
|
|
326
|
-
},
|
|
327
|
-
"skipHours": [0, 20, 21, 22, 23],
|
|
328
|
-
"skipDays": ["Monday", "Wednesday", "Friday"],
|
|
329
|
-
"items": [
|
|
330
|
-
{
|
|
331
|
-
"title": "First item title",
|
|
332
|
-
"link": "http://example.org/item/1",
|
|
333
|
-
"description": "Some description of the first item.",
|
|
334
|
-
"comments": "http://example.org/comments/1",
|
|
335
|
-
"enclosure": {
|
|
336
|
-
"url": "http://example.org/audio/demo.mp3",
|
|
337
|
-
"length": 1069871,
|
|
338
|
-
"type": "audio/mpeg"
|
|
339
|
-
},
|
|
340
|
-
"guid": "http://example.org/guid/1",
|
|
341
|
-
"pubDate": "Thu, 05 Sep 2002 0:00:01 GMT",
|
|
342
|
-
"source": { "title": "Example's Realm", "url": "http://www.example.org/links.xml" }
|
|
343
|
-
}
|
|
344
|
-
]
|
|
345
|
-
}
|
|
346
|
-
```
|
|
347
|
-
</details>
|
|
348
|
-
|
|
349
|
-
<details>
|
|
350
|
-
<summary>Example of an OPML file 📜</summary>
|
|
351
|
-
|
|
352
|
-
```ts
|
|
353
|
-
import { parseOpml } from 'feedsmith'
|
|
354
|
-
|
|
355
|
-
const opml = parseOpml(`
|
|
356
|
-
<?xml version="1.0" encoding="utf-8"?>
|
|
357
|
-
<opml version="2.0">
|
|
358
|
-
<head>
|
|
359
|
-
<title>Tech Sites</title>
|
|
360
|
-
<dateCreated>Mon, 15 Jan 2024 09:45:30 GMT</dateCreated>
|
|
361
|
-
<ownerName>Jack Smith</ownerName>
|
|
362
|
-
</head>
|
|
363
|
-
<body>
|
|
364
|
-
<outline text="The Verge" type="rss" xmlUrl="https://www.theverge.com/rss/index.xml" htmlUrl="https://www.theverge.com/" title="The Verge" version="rss" />
|
|
365
|
-
<outline text="TechCrunch" type="rss" xmlUrl="https://techcrunch.com/feed/" htmlUrl="https://techcrunch.com/" title="TechCrunch" version="rss" />
|
|
366
|
-
</body>
|
|
367
|
-
</opml>
|
|
368
|
-
`)
|
|
369
|
-
|
|
370
|
-
opml.head?.title // → Tech Sites
|
|
371
|
-
opml.body?.outlines?.[0].text // → The Verge
|
|
372
|
-
opml.body?.outlines?.[1].xmlUrl // → https://techcrunch.com/feed/
|
|
373
|
-
|
|
374
|
-
```
|
|
375
|
-
</details>
|
|
376
|
-
|
|
377
|
-
For more examples, check the _*/references_ folders in the source code. There, you'll find the complete objects returned from the parser functions for the various feed formats and versions.
|
|
378
|
-
|
|
379
|
-
* Atom examples: [src/feeds/atom/references](https://github.com/macieklamberski/feedsmith/blob/main/src/feeds/atom/references),
|
|
380
|
-
* RSS examples: [src/feeds/rss/references](https://github.com/macieklamberski/feedsmith/blob/main/src/feeds/rss/references),
|
|
381
|
-
* RDF examples: [src/feeds/rdf/references](https://github.com/macieklamberski/feedsmith/blob/main/src/feeds/rdf/references).
|
|
382
|
-
* OPML examples: [src/opml/references](https://github.com/macieklamberski/feedsmith/blob/main/src/opml/references).
|
|
383
|
-
|
|
384
|
-
### Error handling
|
|
385
|
-
|
|
386
|
-
If the feed is unrecognized or invalid, an `Error` will be thrown with a descriptive message.
|
|
387
|
-
|
|
388
|
-
```ts
|
|
389
|
-
import { parseFeed, parseJsonFeed } from 'feedsmith'
|
|
390
|
-
|
|
391
|
-
try {
|
|
392
|
-
const universalFeed = parseFeed('<not-a-feed></not-a-feed>')
|
|
393
|
-
} catch (error) {
|
|
394
|
-
// Error: Unrecognized feed format
|
|
395
|
-
}
|
|
396
|
-
|
|
397
|
-
try {
|
|
398
|
-
const jsonFeed = parseJsonFeed('{}')
|
|
399
|
-
} catch (error) {
|
|
400
|
-
// Error: Invalid feed format
|
|
401
|
-
}
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
### Format detection
|
|
405
|
-
|
|
406
|
-
You can detect feed formats without parsing them. Detect functions are designed to quickly identify the feed format by looking for its signature, such as the the root tag, version attribute or feed elements.
|
|
407
|
-
|
|
408
|
-
```ts
|
|
409
|
-
import { detectAtomFeed, detectJsonFeed, detectRssFeed, detectRdfFeed } from 'feedsmith'
|
|
410
|
-
|
|
411
|
-
if (detectAtomFeed(content)) {
|
|
412
|
-
console.log('This is an Atom feed')
|
|
413
|
-
}
|
|
414
|
-
|
|
415
|
-
if (detectJsonFeed(content)) {
|
|
416
|
-
console.log('This is a JSON feed')
|
|
417
|
-
}
|
|
418
|
-
|
|
419
|
-
if (detectRssFeed(content)) {
|
|
420
|
-
console.log('This is an RSS feed')
|
|
421
|
-
}
|
|
422
|
-
|
|
423
|
-
if (detectRdfFeed(content)) {
|
|
424
|
-
console.log('This is an RDF feed')
|
|
425
|
-
}
|
|
426
|
-
```
|
|
427
|
-
|
|
428
|
-
## Generating
|
|
429
|
-
|
|
430
|
-
### Generating RSS Feed
|
|
157
|
+
### Generate a Feed
|
|
431
158
|
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
> [!NOTE]
|
|
435
|
-
> This is a simple example. For a complete list of available fields, see the [RSS type definitions](src/feeds/rss/common/types.ts).
|
|
436
|
-
|
|
437
|
-
```ts
|
|
159
|
+
```typescript
|
|
438
160
|
import { generateRssFeed } from 'feedsmith'
|
|
439
161
|
|
|
440
|
-
const
|
|
441
|
-
title: 'My
|
|
162
|
+
const rss = generateRssFeed({
|
|
163
|
+
title: 'My Blog',
|
|
442
164
|
link: 'https://example.com',
|
|
443
|
-
description: 'A
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
items: [
|
|
451
|
-
{
|
|
452
|
-
title: 'First RSS Item',
|
|
453
|
-
link: 'https://example.com/post/1',
|
|
454
|
-
description: 'Description of the first item',
|
|
455
|
-
pubDate: new Date('2024-01-15T10:00:00Z'),
|
|
456
|
-
guid: 'https://example.com/post/1',
|
|
457
|
-
author: 'john@example.com (John Author)',
|
|
458
|
-
categories: [
|
|
459
|
-
{ name: 'Technology' },
|
|
460
|
-
{ name: 'Programming', domain: 'https://example.com/categories' }
|
|
461
|
-
],
|
|
462
|
-
},
|
|
463
|
-
],
|
|
165
|
+
description: 'A simple blog',
|
|
166
|
+
items: [{
|
|
167
|
+
title: 'Hello World',
|
|
168
|
+
link: 'https://example.com/hello',
|
|
169
|
+
description: 'My first post',
|
|
170
|
+
pubDate: new Date()
|
|
171
|
+
}]
|
|
464
172
|
})
|
|
465
|
-
```
|
|
466
173
|
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
```xml
|
|
470
|
-
<?xml version="1.0" encoding="utf-8"?>
|
|
471
|
-
<rss version="2.0">
|
|
472
|
-
<channel>
|
|
473
|
-
<title>My RSS Feed</title>
|
|
474
|
-
<link>https://example.com</link>
|
|
475
|
-
<description>A sample RSS feed with various elements</description>
|
|
476
|
-
<language>en-US</language>
|
|
477
|
-
<pubDate>Mon, 15 Jan 2024 12:00:00 GMT</pubDate>
|
|
478
|
-
<lastBuildDate>Mon, 15 Jan 2024 12:00:00 GMT</lastBuildDate>
|
|
479
|
-
<generator>Feedsmith</generator>
|
|
480
|
-
<managingEditor>editor@example.com (John Editor)</managingEditor>
|
|
481
|
-
<webMaster>webmaster@example.com (Jane Webmaster)</webMaster>
|
|
482
|
-
<item>
|
|
483
|
-
<title>First RSS Item</title>
|
|
484
|
-
<link>https://example.com/post/1</link>
|
|
485
|
-
<description>Description of the first item</description>
|
|
486
|
-
<pubDate>Mon, 15 Jan 2024 10:00:00 GMT</pubDate>
|
|
487
|
-
<guid>https://example.com/post/1</guid>
|
|
488
|
-
<author>john@example.com (John Author)</author>
|
|
489
|
-
<category>Technology</category>
|
|
490
|
-
<category domain="https://example.com/categories">Programming</category>
|
|
491
|
-
</item>
|
|
492
|
-
</channel>
|
|
493
|
-
</rss>
|
|
494
|
-
```
|
|
495
|
-
|
|
496
|
-
### Generating Atom Feed
|
|
497
|
-
|
|
498
|
-
Here's an example of generating an Atom feed.
|
|
499
|
-
|
|
500
|
-
> [!NOTE]
|
|
501
|
-
> This is a simple example. For a complete list of available fields, see the [Atom type definitions](src/feeds/atom/common/types.ts).
|
|
502
|
-
|
|
503
|
-
```ts
|
|
504
|
-
import { generateAtomFeed } from 'feedsmith'
|
|
505
|
-
|
|
506
|
-
const atomFeed = generateAtomFeed({
|
|
507
|
-
id: 'https://example.com/feed',
|
|
508
|
-
title: 'My Atom Feed',
|
|
509
|
-
updated: new Date('2024-01-15T12:00:00Z'),
|
|
510
|
-
authors: [
|
|
511
|
-
{
|
|
512
|
-
name: 'John Author',
|
|
513
|
-
email: 'john@example.com',
|
|
514
|
-
uri: 'https://example.com/john',
|
|
515
|
-
},
|
|
516
|
-
],
|
|
517
|
-
links: [
|
|
518
|
-
{
|
|
519
|
-
href: 'https://example.com/feed.xml',
|
|
520
|
-
rel: 'self',
|
|
521
|
-
type: 'application/atom+xml',
|
|
522
|
-
},
|
|
523
|
-
{
|
|
524
|
-
href: 'https://example.com',
|
|
525
|
-
rel: 'alternate',
|
|
526
|
-
type: 'text/html',
|
|
527
|
-
},
|
|
528
|
-
],
|
|
529
|
-
subtitle: 'A sample Atom feed with various elements',
|
|
530
|
-
generator: {
|
|
531
|
-
text: 'Feedsmith',
|
|
532
|
-
uri: 'https://github.com/macieklamberski/feedsmith',
|
|
533
|
-
},
|
|
534
|
-
entries: [
|
|
535
|
-
{
|
|
536
|
-
id: 'https://example.com/entry/1',
|
|
537
|
-
title: 'First Atom Entry',
|
|
538
|
-
updated: new Date('2024-01-15T10:00:00Z'),
|
|
539
|
-
published: new Date('2024-01-15T10:00:00Z'),
|
|
540
|
-
authors: [
|
|
541
|
-
{
|
|
542
|
-
name: 'Jane Writer',
|
|
543
|
-
email: 'jane@example.com',
|
|
544
|
-
},
|
|
545
|
-
],
|
|
546
|
-
links: [
|
|
547
|
-
{
|
|
548
|
-
href: 'https://example.com/post/1',
|
|
549
|
-
rel: 'alternate',
|
|
550
|
-
type: 'text/html',
|
|
551
|
-
},
|
|
552
|
-
],
|
|
553
|
-
content: '<p>This is the complete content of the first entry.</p>',
|
|
554
|
-
summary: 'Summary of the first entry',
|
|
555
|
-
categories: [
|
|
556
|
-
{ term: 'technology', label: 'Technology' },
|
|
557
|
-
{ term: 'programming', scheme: 'https://example.com/categories' }
|
|
558
|
-
],
|
|
559
|
-
},
|
|
560
|
-
],
|
|
561
|
-
})
|
|
562
|
-
```
|
|
174
|
+
console.log(rss) // Complete RSS XML
|
|
563
175
|
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
<id>https://example.com/feed</id>
|
|
570
|
-
<title>My Atom Feed</title>
|
|
571
|
-
<updated>2024-01-15T12:00:00.000Z</updated>
|
|
572
|
-
<author>
|
|
573
|
-
<name>John Author</name>
|
|
574
|
-
<email>john@example.com</email>
|
|
575
|
-
<uri>https://example.com/john</uri>
|
|
576
|
-
</author>
|
|
577
|
-
<link href="https://example.com/feed.xml" rel="self" type="application/atom+xml"/>
|
|
578
|
-
<link href="https://example.com" rel="alternate" type="text/html"/>
|
|
579
|
-
<subtitle>A sample Atom feed with various elements</subtitle>
|
|
580
|
-
<generator uri="https://github.com/macieklamberski/feedsmith">Feedsmith</generator>
|
|
581
|
-
<entry>
|
|
582
|
-
<id>https://example.com/entry/1</id>
|
|
583
|
-
<title>First Atom Entry</title>
|
|
584
|
-
<updated>2024-01-15T10:00:00.000Z</updated>
|
|
585
|
-
<published>2024-01-15T10:00:00.000Z</published>
|
|
586
|
-
<author>
|
|
587
|
-
<name>Jane Writer</name>
|
|
588
|
-
<email>jane@example.com</email>
|
|
589
|
-
</author>
|
|
590
|
-
<link href="https://example.com/post/1" rel="alternate" type="text/html"/>
|
|
591
|
-
<content>This is the complete content of the first entry.</content>
|
|
592
|
-
<summary>Summary of the first entry</summary>
|
|
593
|
-
<category term="technology" label="Technology"/>
|
|
594
|
-
<category term="programming" scheme="https://example.com/categories"/>
|
|
595
|
-
</entry>
|
|
596
|
-
</feed>
|
|
176
|
+
// You can also generate other formats:
|
|
177
|
+
// - generateAtomFeed() for Atom feeds
|
|
178
|
+
// - generateJsonFeed() for JSON feeds
|
|
179
|
+
// - generateRdfFeed() for RDF feeds
|
|
180
|
+
// - generateOpml() for OPML files
|
|
597
181
|
```
|
|
598
182
|
|
|
599
|
-
###
|
|
600
|
-
|
|
601
|
-
Although JSON feeds are simply JSON objects that can be easily generated manually, the `generateJsonFeed` function provides helpful type hints, which can aid in feed generation. Additionally, you can use Date objects for dates, which are automatically converted to the correct format in the background.
|
|
602
|
-
|
|
603
|
-
> [!NOTE]
|
|
604
|
-
> This is a simple example. For a complete list of available fields, see the [JSON Feed type definitions](src/feeds/json/common/types.ts).
|
|
605
|
-
|
|
606
|
-
```ts
|
|
607
|
-
import { generateJsonFeed } from 'feedsmith'
|
|
608
|
-
|
|
609
|
-
const jsonFeed = generateJsonFeed({
|
|
610
|
-
title: 'My Example Feed',
|
|
611
|
-
feed_url: 'https://example.com/feed.json',
|
|
612
|
-
authors: [
|
|
613
|
-
{
|
|
614
|
-
name: 'John Doe',
|
|
615
|
-
url: 'https://example.com/johndoe',
|
|
616
|
-
},
|
|
617
|
-
],
|
|
618
|
-
items: [
|
|
619
|
-
{
|
|
620
|
-
id: '1',
|
|
621
|
-
content_html: '<p>Hello world</p>',
|
|
622
|
-
url: 'https://example.com/post/1',
|
|
623
|
-
title: 'First post',
|
|
624
|
-
date_published: new Date('2019-03-07T00:00:00+01:00'),
|
|
625
|
-
},
|
|
626
|
-
],
|
|
627
|
-
})
|
|
628
|
-
```
|
|
183
|
+
### Handle Errors
|
|
629
184
|
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
"feed_url": "https://example.com/feed.json",
|
|
637
|
-
"authors": [
|
|
638
|
-
{
|
|
639
|
-
"name": "John Doe",
|
|
640
|
-
"url": "https://example.com/johndoe",
|
|
641
|
-
},
|
|
642
|
-
],
|
|
643
|
-
"items": [
|
|
644
|
-
{
|
|
645
|
-
"id": "1",
|
|
646
|
-
"content_html": "<p>Hello world</p>",
|
|
647
|
-
"url": "https://example.com/post/1",
|
|
648
|
-
"title": "First post",
|
|
649
|
-
"date_published": "2019-03-06T23:00:00.000Z",
|
|
650
|
-
},
|
|
651
|
-
],
|
|
185
|
+
```typescript
|
|
186
|
+
try {
|
|
187
|
+
const { format, feed } = parseFeed(content)
|
|
188
|
+
// Use the feed
|
|
189
|
+
} catch (error) {
|
|
190
|
+
console.error('Invalid feed:', error.message)
|
|
652
191
|
}
|
|
653
192
|
```
|
|
654
193
|
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
RSS, Atom, and RDF feeds support various XML namespaces to extend their functionality. Feedsmith automatically includes the appropriate namespace declarations when you add namespace data to your feeds.
|
|
658
|
-
|
|
659
|
-
> [!NOTE]
|
|
660
|
-
> Namespace support varies by feed format. For complete namespace type definitions, see: [Atom](src/namespaces/atom/common/types.ts), [Content](src/namespaces/content/common/types.ts), [Dublin Core](src/namespaces/dc/common/types.ts), [DC Terms](src/namespaces/dcterms/common/types.ts), [GeoRSS](src/namespaces/georss/common/types.ts), [iTunes](src/namespaces/itunes/common/types.ts), [Media](src/namespaces/media/common/types.ts), [Podcast](src/namespaces/podcast/common/types.ts), [Slash](src/namespaces/slash/common/types.ts), [Syndication](src/namespaces/sy/common/types.ts), [Threading](src/namespaces/thr/common/types.ts), [WFW](src/namespaces/wfw/common/types.ts), [YouTube](src/namespaces/yt/common/types.ts).
|
|
661
|
-
|
|
662
|
-
Here's an example of generating an RSS feed with Dublin Core and iTunes namespaces:
|
|
194
|
+
## Why Feedsmith?
|
|
663
195
|
|
|
664
|
-
|
|
665
|
-
import { generateRssFeed } from 'feedsmith'
|
|
666
|
-
|
|
667
|
-
const rssFeed = generateRssFeed({
|
|
668
|
-
title: 'My Podcast Feed',
|
|
669
|
-
link: 'https://example.com/podcast',
|
|
670
|
-
description: 'A sample podcast with namespace elements',
|
|
671
|
-
dc: {
|
|
672
|
-
creator: 'John Podcaster',
|
|
673
|
-
contributor: 'Jane Producer',
|
|
674
|
-
date: new Date('2024-01-15T12:00:00Z'),
|
|
675
|
-
language: 'en-US',
|
|
676
|
-
},
|
|
677
|
-
itunes: {
|
|
678
|
-
author: 'John Podcaster',
|
|
679
|
-
category: [
|
|
680
|
-
{ text: 'Technology' },
|
|
681
|
-
{ text: 'Education', subcategory: [{ text: 'Courses' }] }
|
|
682
|
-
],
|
|
683
|
-
explicit: false,
|
|
684
|
-
image: { href: 'https://example.com/artwork.jpg' },
|
|
685
|
-
summary: 'A technology podcast for curious minds',
|
|
686
|
-
},
|
|
687
|
-
|
|
688
|
-
items: [
|
|
689
|
-
{
|
|
690
|
-
title: 'Episode 1: Getting Started',
|
|
691
|
-
link: 'https://example.com/episode1',
|
|
692
|
-
description: 'Our first episode covers the basics',
|
|
693
|
-
pubDate: new Date('2024-01-15T10:00:00Z'),
|
|
694
|
-
dc: {
|
|
695
|
-
creator: 'Jane Producer',
|
|
696
|
-
subject: 'Technology, Programming',
|
|
697
|
-
},
|
|
698
|
-
itunes: {
|
|
699
|
-
author: 'Jane Producer',
|
|
700
|
-
duration: '00:45:30',
|
|
701
|
-
explicit: false,
|
|
702
|
-
episode: 1,
|
|
703
|
-
episodeType: 'full',
|
|
704
|
-
},
|
|
705
|
-
},
|
|
706
|
-
],
|
|
707
|
-
})
|
|
708
|
-
```
|
|
709
|
-
|
|
710
|
-
Will output:
|
|
711
|
-
|
|
712
|
-
```xml
|
|
713
|
-
<?xml version="1.0" encoding="utf-8"?>
|
|
714
|
-
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd">
|
|
715
|
-
<channel>
|
|
716
|
-
<title>My Podcast Feed</title>
|
|
717
|
-
<link>https://example.com/podcast</link>
|
|
718
|
-
<description>A sample podcast with namespace elements</description>
|
|
719
|
-
<dc:creator>John Podcaster</dc:creator>
|
|
720
|
-
<dc:contributor>Jane Producer</dc:contributor>
|
|
721
|
-
<dc:date>Mon, 15 Jan 2024 12:00:00 GMT</dc:date>
|
|
722
|
-
<dc:language>en-US</dc:language>
|
|
723
|
-
<itunes:author>John Podcaster</itunes:author>
|
|
724
|
-
<itunes:category text="Technology"/>
|
|
725
|
-
<itunes:category text="Education">
|
|
726
|
-
<itunes:category text="Courses"/>
|
|
727
|
-
</itunes:category>
|
|
728
|
-
<itunes:explicit>false</itunes:explicit>
|
|
729
|
-
<itunes:image href="https://example.com/artwork.jpg"/>
|
|
730
|
-
<itunes:summary>A technology podcast for curious minds</itunes:summary>
|
|
731
|
-
<item>
|
|
732
|
-
<title>Episode 1: Getting Started</title>
|
|
733
|
-
<link>https://example.com/episode1</link>
|
|
734
|
-
<description>Our first episode covers the basics</description>
|
|
735
|
-
<pubDate>Mon, 15 Jan 2024 10:00:00 GMT</pubDate>
|
|
736
|
-
<dc:creator>Jane Producer</dc:creator>
|
|
737
|
-
<dc:subject>Technology, Programming</dc:subject>
|
|
738
|
-
<itunes:author>Jane Producer</itunes:author>
|
|
739
|
-
<itunes:duration>00:45:30</itunes:duration>
|
|
740
|
-
<itunes:explicit>false</itunes:explicit>
|
|
741
|
-
<itunes:episode>1</itunes:episode>
|
|
742
|
-
<itunes:episodeType>full</itunes:episodeType>
|
|
743
|
-
</item>
|
|
744
|
-
</channel>
|
|
745
|
-
</rss>
|
|
746
|
-
```
|
|
747
|
-
|
|
748
|
-
### Generating with Stylesheets
|
|
749
|
-
|
|
750
|
-
XML-based feeds and OPML files support stylesheets to provide custom styling and transformations in browsers and feed readers. Feedsmith automatically adds the appropriate XML processing instructions when you specify stylesheets. For complete stylesheet type definitions, see [`XmlStylesheet` type](src/common/types.ts).
|
|
751
|
-
|
|
752
|
-
```ts
|
|
753
|
-
import { generateRssFeed } from 'feedsmith'
|
|
754
|
-
|
|
755
|
-
const rssFeed = generateRssFeed({ /* feed data */ }, {
|
|
756
|
-
stylesheets: [
|
|
757
|
-
{
|
|
758
|
-
type: 'text/xsl',
|
|
759
|
-
href: '/styles/feed.xsl',
|
|
760
|
-
title: 'Pretty Feed',
|
|
761
|
-
media: 'screen',
|
|
762
|
-
},
|
|
763
|
-
{
|
|
764
|
-
type: 'text/css',
|
|
765
|
-
href: '/styles/feed.css',
|
|
766
|
-
media: 'screen',
|
|
767
|
-
alternate: false,
|
|
768
|
-
},
|
|
769
|
-
],
|
|
770
|
-
})
|
|
771
|
-
```
|
|
196
|
+
Why should you use this library over the alternatives?
|
|
772
197
|
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
```xml
|
|
776
|
-
<?xml version="1.0" encoding="utf-8"?>
|
|
777
|
-
<?xml-stylesheet type="text/xsl" href="/styles/feed.xsl" title="Pretty Feed" media="screen"?>
|
|
778
|
-
<?xml-stylesheet type="text/css" href="/styles/feed.css" media="screen" alternate="no"?>
|
|
779
|
-
<rss version="2.0">
|
|
780
|
-
<!-- … -->
|
|
781
|
-
</rss>
|
|
782
|
-
```
|
|
783
|
-
|
|
784
|
-
### Generating OPML
|
|
785
|
-
|
|
786
|
-
> [!NOTE]
|
|
787
|
-
> This is a simple example. For a complete list of available fields, see the [OPML type definitions](src/opml/common/types.ts).
|
|
788
|
-
|
|
789
|
-
```ts
|
|
790
|
-
import { generateOpml } from 'feedsmith'
|
|
791
|
-
|
|
792
|
-
const opml = generateOpml({
|
|
793
|
-
head: {
|
|
794
|
-
title: 'My Feed',
|
|
795
|
-
dateCreated: new Date(),
|
|
796
|
-
},
|
|
797
|
-
body: {
|
|
798
|
-
outlines: [
|
|
799
|
-
{
|
|
800
|
-
text: 'My Feed',
|
|
801
|
-
type: 'rss',
|
|
802
|
-
xmlUrl: 'https://example.com/feed.xml',
|
|
803
|
-
htmlUrl: 'https://example.com',
|
|
804
|
-
},
|
|
805
|
-
],
|
|
806
|
-
},
|
|
807
|
-
})
|
|
808
|
-
```
|
|
809
|
-
|
|
810
|
-
Will output:
|
|
811
|
-
|
|
812
|
-
```xml
|
|
813
|
-
<?xml version="1.0" encoding="utf-8"?>
|
|
814
|
-
<opml version="2.0">
|
|
815
|
-
<head>
|
|
816
|
-
<title>My Feed</title>
|
|
817
|
-
<dateCreated>Fri, 11 Apr 2025 13:05:26 GMT</dateCreated>
|
|
818
|
-
</head>
|
|
819
|
-
<body>
|
|
820
|
-
<outline text="My Feed" type="rss" xmlUrl="https://example.com/feed.xml" htmlUrl="https://example.com"/>
|
|
821
|
-
</body>
|
|
822
|
-
</opml>
|
|
823
|
-
```
|
|
824
|
-
|
|
825
|
-
## Benchmarks
|
|
826
|
-
|
|
827
|
-
A comprehensive set of benchmarks, categorized by various file sizes, is available in the _/benchmarks_ directory. These benchmarks were conducted using both Tinybench and Benchmark.js.
|
|
828
|
-
|
|
829
|
-
[See full benchmark results →](benchmarks/README.md)
|
|
830
|
-
|
|
831
|
-
For a quick overview, here are the results of parsing RSS, Atom, and RDF feeds using various JS packages with Tinybench. Feedsmith's results are marked with an asterisk (`*`).
|
|
832
|
-
|
|
833
|
-
```
|
|
834
|
-
📊 RSS feed parsing (100 files × 100KB–5MB)
|
|
835
|
-
┌───┬───────────────────────────────┬─────────┬──────────────┬──────────┬──────────┬──────┬─────────────┐
|
|
836
|
-
│ │ Package │ Ops/sec │ Average (ms) │ Min (ms) │ Max (ms) │ Runs │ Performance │
|
|
837
|
-
├───┼───────────────────────────────┼─────────┼──────────────┼──────────┼──────────┼──────┼─────────────┤
|
|
838
|
-
│ 0 │ feedsmith * │ 2.15 │ 464.233 │ 431.238 │ 560.196 │ 33 │ baseline │
|
|
839
|
-
│ 1 │ @ulisesgascon/rss-feed-parser │ 1.61 │ 619.751 │ 583.357 │ 702.199 │ 25 │ 1.3x slower │
|
|
840
|
-
│ 2 │ @gaphub/feed │ 1.51 │ 663.333 │ 615.706 │ 753.343 │ 23 │ 1.4x slower │
|
|
841
|
-
│ 3 │ podcast-feed-parser │ 1.40 │ 713.043 │ 663.199 │ 822.646 │ 22 │ 1.5x slower │
|
|
842
|
-
│ 4 │ feedparser │ 0.99 │ 1013.059 │ 943.120 │ 1140.454 │ 15 │ 2.2x slower │
|
|
843
|
-
│ 5 │ @extractus/feed-extractor │ 0.86 │ 1167.174 │ 1105.055 │ 1266.003 │ 13 │ 2.5x slower │
|
|
844
|
-
│ 6 │ feedme.js │ 0.74 │ 1347.627 │ 1192.642 │ 1633.812 │ 12 │ 2.9x slower │
|
|
845
|
-
│ 7 │ rss-parser │ 0.64 │ 1551.783 │ 1495.036 │ 1739.777 │ 10 │ 3.3x slower │
|
|
846
|
-
│ 8 │ @rowanmanning/feed-parser │ 0.46 │ 2186.174 │ 2029.103 │ 2689.577 │ 7 │ 4.7x slower │
|
|
847
|
-
└───┴───────────────────────────────┴─────────┴──────────────┴──────────┴──────────┴──────┴─────────────┘
|
|
848
|
-
|
|
849
|
-
📊 Atom feed parsing (100 files × 100KB–5MB)
|
|
850
|
-
┌───┬───────────────────────────┬─────────┬──────────────┬───────────┬───────────┬──────┬─────────────┐
|
|
851
|
-
│ │ Package │ Ops/sec │ Average (ms) │ Min (ms) │ Max (ms) │ Runs │ Performance │
|
|
852
|
-
├───┼───────────────────────────┼─────────┼──────────────┼───────────┼───────────┼──────┼─────────────┤
|
|
853
|
-
│ 0 │ feedsmith * │ 0.45 │ 2218.248 │ 2195.860 │ 2258.982 │ 7 │ baseline │
|
|
854
|
-
│ 1 │ @rowanmanning/feed-parser │ 0.18 │ 5553.175 │ 5249.846 │ 5861.476 │ 3 │ 2.5x slower │
|
|
855
|
-
│ 2 │ feedparser │ 0.17 │ 6057.445 │ 5563.861 │ 6781.359 │ 3 │ 2.7x slower │
|
|
856
|
-
│ 3 │ @extractus/feed-extractor │ 0.15 │ 6685.829 │ 6494.192 │ 6984.887 │ 3 │ 3.0x slower │
|
|
857
|
-
│ 4 │ @gaphub/feed │ 0.13 │ 7717.126 │ 6402.034 │ 9032.219 │ 2 │ 3.5x slower │
|
|
858
|
-
│ 5 │ feedme.js │ 0.12 │ 8053.625 │ 7935.369 │ 8171.881 │ 2 │ 3.6x slower │
|
|
859
|
-
│ 6 │ rss-parser │ 0.08 │ 12999.252 │ 12819.434 │ 13179.070 │ 2 │ 5.9x slower │
|
|
860
|
-
└───┴───────────────────────────┴─────────┴──────────────┴───────────┴───────────┴──────┴─────────────┘
|
|
861
|
-
|
|
862
|
-
📊 RDF feed parsing (100 files × 100KB–5MB)
|
|
863
|
-
┌───┬───────────────────────────┬─────────┬──────────────┬──────────┬──────────┬──────┬──────────────┐
|
|
864
|
-
│ │ Package │ Ops/sec │ Average (ms) │ Min (ms) │ Max (ms) │ Runs │ Performance │
|
|
865
|
-
├───┼───────────────────────────┼─────────┼──────────────┼──────────┼──────────┼──────┼──────────────┤
|
|
866
|
-
│ 0 │ feedsmith * │ 5.93 │ 168.678 │ 153.476 │ 191.892 │ 89 │ baseline │
|
|
867
|
-
│ 1 │ @rowanmanning/feed-parser │ 3.00 │ 333.512 │ 312.475 │ 387.156 │ 45 │ 2.0x slower │
|
|
868
|
-
│ 2 │ @extractus/feed-extractor │ 1.80 │ 556.240 │ 504.258 │ 621.485 │ 27 │ 3.3x slower │
|
|
869
|
-
│ 3 │ @gaphub/feed │ 1.23 │ 815.776 │ 729.150 │ 1129.571 │ 19 │ 4.8x slower │
|
|
870
|
-
│ 4 │ feedparser │ 0.92 │ 1087.980 │ 1023.638 │ 1128.518 │ 14 │ 6.5x slower │
|
|
871
|
-
│ 5 │ feedme.js │ 0.64 │ 1567.422 │ 1506.713 │ 1626.450 │ 10 │ 9.3x slower │
|
|
872
|
-
│ 6 │ rss-parser │ 0.42 │ 2368.398 │ 2288.041 │ 2438.408 │ 7 │ 14.0x slower │
|
|
873
|
-
└───┴───────────────────────────┴─────────┴──────────────┴──────────┴──────────┴──────┴──────────────┘
|
|
874
|
-
```
|
|
875
|
-
|
|
876
|
-
## FAQ
|
|
877
|
-
|
|
878
|
-
### Why should I use Feedsmith instead of alternative packages?
|
|
879
|
-
|
|
880
|
-
The key advantage of Feedsmith is that it preserves the original feed structure exactly as provided in each specific feed format.
|
|
198
|
+
The key advantage of Feedsmith is that it preserves the original feed structure exactly as defined in each specific feed format.
|
|
881
199
|
|
|
882
200
|
Many alternative packages attempt to normalize data by:
|
|
883
201
|
|
|
@@ -888,24 +206,6 @@ Many alternative packages attempt to normalize data by:
|
|
|
888
206
|
|
|
889
207
|
While this approach can be useful for quick reading of feed data, it often results in a loss of information that may be crucial for certain applications, such as reading data from specific namespaces.
|
|
890
208
|
|
|
891
|
-
### Why are date fields returned as strings?
|
|
892
|
-
|
|
893
|
-
In the course of parsing hundreds of thousands of feeds, I have found that dates in feeds use many different formats. Rather than attempting to parse them all (and potentially introducing errors), dates are returned in their original string form. This approach allows you to use your preferred date parsing library or simply the `Date` object.
|
|
894
|
-
|
|
895
|
-
### Does Feedsmith validate feeds?
|
|
896
|
-
|
|
897
|
-
Feedsmith focuses on parsing feeds rather than validating them. It will extract whatever valid data it can find, even from partially valid feeds. This approach makes it more resilient when dealing with feeds found in the wild.
|
|
898
|
-
|
|
899
|
-
It will only fail if the feed is completely invalid or it does not contain all the fields required according to the specification.
|
|
900
|
-
|
|
901
|
-
### How does Feedsmith handle missing or incomplete data?
|
|
902
|
-
|
|
903
|
-
Feedsmith is designed to be forgiving. It will extract whatever valid data it can find and ignore missing or invalid elements. This makes it suitable for use with real-world feeds that may not strictly follow specifications.
|
|
904
|
-
|
|
905
|
-
### Does Feedsmith work in the browser?
|
|
906
|
-
|
|
907
|
-
Even though Feedsmith is more suited for the Node.js environments, it was also tested in modern browsers where it works seamlessly. It's provided as an ES module.
|
|
908
|
-
|
|
909
209
|
## Acknowledgements
|
|
910
210
|
|
|
911
211
|
* The library API is inspired by the [FeedKit library for Swift](https://github.com/nmdias/FeedKit).
|