feedsmith 2.0.0-next.3 → 2.0.0-next.5
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 -767
- package/dist/common/config.js +0 -1
- package/dist/common/parse.d.ts +4 -4
- package/dist/common/parse.js +8 -9
- 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.d.ts +11 -11
- package/dist/feeds/atom/common/types.js +1 -1
- package/dist/feeds/atom/detect/index.js +1 -2
- package/dist/feeds/atom/generate/config.js +1 -2
- package/dist/feeds/atom/generate/index.d.ts +3 -3
- package/dist/feeds/atom/generate/index.js +1 -2
- package/dist/feeds/atom/generate/utils.d.ts +6 -5
- package/dist/feeds/atom/generate/utils.js +12 -13
- package/dist/feeds/atom/parse/config.js +1 -2
- package/dist/feeds/atom/parse/index.d.ts +2 -2
- package/dist/feeds/atom/parse/index.js +3 -4
- package/dist/feeds/atom/parse/utils.d.ts +2 -2
- package/dist/feeds/atom/parse/utils.js +11 -12
- package/dist/feeds/json/common/types.d.ts +1 -1
- package/dist/feeds/json/common/types.js +1 -1
- package/dist/feeds/json/detect/index.js +2 -3
- package/dist/feeds/json/generate/index.d.ts +3 -2
- package/dist/feeds/json/generate/index.js +0 -1
- package/dist/feeds/json/generate/utils.d.ts +1924 -35
- package/dist/feeds/json/generate/utils.js +4 -4
- package/dist/feeds/json/parse/index.d.ts +2 -2
- package/dist/feeds/json/parse/index.js +2 -3
- package/dist/feeds/json/parse/utils.d.ts +2 -2
- package/dist/feeds/json/parse/utils.js +1 -2
- package/dist/feeds/rdf/common/types.d.ts +10 -10
- package/dist/feeds/rdf/common/types.js +1 -1
- package/dist/feeds/rdf/detect/index.js +1 -2
- package/dist/feeds/rdf/parse/config.js +1 -2
- package/dist/feeds/rdf/parse/index.d.ts +2 -2
- package/dist/feeds/rdf/parse/index.js +3 -4
- package/dist/feeds/rdf/parse/utils.d.ts +2 -2
- package/dist/feeds/rdf/parse/utils.js +10 -11
- package/dist/feeds/rss/common/types.d.ts +14 -14
- package/dist/feeds/rss/common/types.js +1 -1
- package/dist/feeds/rss/detect/index.js +1 -2
- package/dist/feeds/rss/generate/config.js +1 -2
- package/dist/feeds/rss/generate/index.d.ts +3 -3
- package/dist/feeds/rss/generate/index.js +1 -2
- package/dist/feeds/rss/generate/utils.d.ts +4 -4
- package/dist/feeds/rss/generate/utils.js +15 -16
- package/dist/feeds/rss/parse/config.js +1 -2
- package/dist/feeds/rss/parse/index.d.ts +2 -2
- package/dist/feeds/rss/parse/index.js +3 -4
- package/dist/feeds/rss/parse/utils.d.ts +2 -2
- package/dist/feeds/rss/parse/utils.js +14 -15
- package/dist/index.d.ts +19 -19
- package/dist/index.js +14 -15
- package/dist/namespaces/atom/common/types.d.ts +2 -2
- package/dist/namespaces/atom/common/types.js +1 -1
- package/dist/namespaces/atom/generate/utils.d.ts +4 -4
- package/dist/namespaces/atom/generate/utils.js +1 -2
- package/dist/namespaces/atom/parse/utils.d.ts +2 -2
- package/dist/namespaces/atom/parse/utils.js +1 -2
- package/dist/namespaces/content/common/types.js +1 -1
- package/dist/namespaces/content/generate/utils.d.ts +2 -2
- package/dist/namespaces/content/generate/utils.js +1 -2
- package/dist/namespaces/content/parse/utils.d.ts +2 -2
- package/dist/namespaces/content/parse/utils.js +1 -2
- package/dist/namespaces/dc/common/types.d.ts +1 -1
- package/dist/namespaces/dc/common/types.js +1 -1
- package/dist/namespaces/dc/generate/utils.d.ts +3 -3
- package/dist/namespaces/dc/generate/utils.js +1 -2
- package/dist/namespaces/dc/parse/utils.d.ts +2 -2
- package/dist/namespaces/dc/parse/utils.js +1 -2
- package/dist/namespaces/dcterms/common/types.d.ts +1 -1
- package/dist/namespaces/dcterms/common/types.js +1 -1
- package/dist/namespaces/dcterms/generate/utils.d.ts +3 -3
- package/dist/namespaces/dcterms/generate/utils.js +1 -2
- package/dist/namespaces/dcterms/parse/utils.d.ts +2 -2
- package/dist/namespaces/dcterms/parse/utils.js +1 -2
- package/dist/namespaces/georss/common/types.js +1 -1
- package/dist/namespaces/georss/generate/utils.d.ts +2 -2
- package/dist/namespaces/georss/generate/utils.js +1 -2
- package/dist/namespaces/georss/parse/utils.d.ts +2 -2
- package/dist/namespaces/georss/parse/utils.js +1 -2
- package/dist/namespaces/itunes/common/types.js +1 -1
- package/dist/namespaces/itunes/generate/utils.d.ts +2 -2
- package/dist/namespaces/itunes/generate/utils.js +1 -2
- package/dist/namespaces/itunes/parse/utils.d.ts +2 -2
- package/dist/namespaces/itunes/parse/utils.js +1 -2
- package/dist/namespaces/media/common/types.js +1 -1
- package/dist/namespaces/media/generate/utils.d.ts +2 -2
- package/dist/namespaces/media/generate/utils.js +1 -2
- package/dist/namespaces/media/parse/utils.d.ts +2 -2
- package/dist/namespaces/media/parse/utils.js +1 -2
- package/dist/namespaces/podcast/common/types.d.ts +1 -1
- package/dist/namespaces/podcast/common/types.js +1 -1
- package/dist/namespaces/podcast/generate/utils.d.ts +6 -6
- package/dist/namespaces/podcast/generate/utils.js +1 -2
- package/dist/namespaces/podcast/parse/utils.d.ts +2 -2
- package/dist/namespaces/podcast/parse/utils.js +1 -2
- package/dist/namespaces/slash/common/types.js +1 -1
- package/dist/namespaces/slash/generate/utils.d.ts +2 -2
- package/dist/namespaces/slash/generate/utils.js +1 -2
- package/dist/namespaces/slash/parse/utils.d.ts +2 -2
- package/dist/namespaces/slash/parse/utils.js +1 -2
- package/dist/namespaces/sy/common/types.d.ts +1 -1
- package/dist/namespaces/sy/common/types.js +1 -1
- package/dist/namespaces/sy/generate/utils.d.ts +3 -3
- package/dist/namespaces/sy/generate/utils.js +1 -2
- package/dist/namespaces/sy/parse/utils.d.ts +2 -2
- package/dist/namespaces/sy/parse/utils.js +1 -2
- package/dist/namespaces/thr/common/types.d.ts +1 -1
- package/dist/namespaces/thr/common/types.js +1 -1
- package/dist/namespaces/thr/generate/utils.d.ts +3 -3
- package/dist/namespaces/thr/generate/utils.js +1 -2
- package/dist/namespaces/thr/parse/utils.d.ts +2 -2
- package/dist/namespaces/thr/parse/utils.js +1 -2
- package/dist/namespaces/wfw/common/types.js +1 -1
- package/dist/namespaces/wfw/generate/utils.d.ts +2 -2
- package/dist/namespaces/wfw/generate/utils.js +1 -2
- package/dist/namespaces/wfw/parse/utils.d.ts +2 -2
- package/dist/namespaces/wfw/parse/utils.js +1 -2
- package/dist/namespaces/yt/common/types.js +1 -1
- package/dist/namespaces/yt/generate/utils.d.ts +2 -2
- package/dist/namespaces/yt/generate/utils.js +1 -2
- package/dist/namespaces/yt/parse/utils.d.ts +2 -2
- package/dist/namespaces/yt/parse/utils.js +1 -2
- package/dist/opml/common/types.d.ts +1 -1
- package/dist/opml/common/types.js +1 -1
- package/dist/opml/generate/config.js +1 -2
- package/dist/opml/generate/index.d.ts +3 -3
- package/dist/opml/generate/index.js +1 -2
- package/dist/opml/generate/utils.d.ts +6 -6
- package/dist/opml/generate/utils.js +1 -2
- package/dist/opml/parse/config.js +1 -2
- package/dist/opml/parse/index.d.ts +2 -2
- package/dist/opml/parse/index.js +0 -1
- package/dist/opml/parse/utils.d.ts +2 -2
- package/dist/opml/parse/utils.js +1 -2
- 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
|
@@ -17,36 +17,43 @@ Feedsmith provides both universal and format-specific parsers that maintain the
|
|
|
17
17
|
> npm install feedsmith@next # Development version 2.0.0-next.x
|
|
18
18
|
> ```
|
|
19
19
|
|
|
20
|
-
[
|
|
20
|
+
**[Read full docs ↗](https://feedsmith.dev)**
|
|
21
21
|
·
|
|
22
|
-
[
|
|
22
|
+
[Quick Start](#quick-start)
|
|
23
23
|
·
|
|
24
|
-
[
|
|
24
|
+
[Why Feedsmith?](#why-feedsmith)
|
|
25
25
|
·
|
|
26
|
-
[
|
|
27
|
-
·
|
|
28
|
-
[Benchmarks](#benchmarks)
|
|
29
|
-
·
|
|
30
|
-
[FAQ](#faq)
|
|
26
|
+
[Benchmarks →](benchmarks/README.md)
|
|
31
27
|
|
|
32
28
|
---
|
|
33
29
|
|
|
34
|
-
|
|
35
|
-
|
|
30
|
+
## Features
|
|
31
|
+
|
|
32
|
+
### Core
|
|
33
|
+
|
|
34
|
+
* **Comprehensive Support** 🎯 — Supports all major feed formats and feed namespaces.
|
|
35
|
+
* **Perserves Structure** 📦 — Parsed feed object maintains the original feed structure making it easy to access the data.
|
|
36
|
+
* **Smart Namespace Handling** 🧠 — Automatically normalizes custom namespace prefixes to standard ones (e.g., `<custom:creator>` becomes `dc.creator`).
|
|
37
|
+
* **Parsing & Generating** 🔩 — You can use one package for both parsing and generating feeds.
|
|
38
|
+
|
|
39
|
+
### Leniency
|
|
40
|
+
* **Normalizes Legacy Elements** ✨ — Upgrades feed elements to their modern equivalents so that you never need to worry about reading feeds in older formats.
|
|
36
41
|
* **CaSe INSENsiTive** 🐍 — Handles fields and attributes in any case (lowercase, uppercase, mixed).
|
|
37
|
-
* **
|
|
42
|
+
* **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
43
|
|
|
39
|
-
|
|
40
|
-
* **
|
|
41
|
-
* **Type-safe API** 🛟 — TypeScript
|
|
44
|
+
### Performance and Type-Safety
|
|
45
|
+
* **Ultrafast parsing** ⚡ — One of the fastest feed parsers in JavaScript ([see benchmarks](benchmarks/README.md)).
|
|
46
|
+
* **Type-safe API** 🛟 — Built with TypeScript from the ground up, it provides complete type definitions for every feed format and namespace.
|
|
42
47
|
* **Tree-shakable** 🍃 — Only include the parts of the library you need, reducing bundle size.
|
|
43
48
|
* **Well-tested** 🔬 — Comprehensive test suite with over 2000 tests and 99% code coverage.
|
|
44
49
|
|
|
45
|
-
|
|
46
|
-
* Works in Node.js and
|
|
50
|
+
### Compatibility
|
|
51
|
+
* Works in Node.js and modern browsers.
|
|
47
52
|
* Works with plain JavaScript, you don't need to use TypeScript.
|
|
48
53
|
|
|
49
|
-
## Supported
|
|
54
|
+
## Supported Formats
|
|
55
|
+
|
|
56
|
+
Feedsmith aims to fully support all major feed formats and namespaces in complete alignment with their specifications.
|
|
50
57
|
|
|
51
58
|
✅ Available
|
|
52
59
|
·
|
|
@@ -65,7 +72,7 @@ Feedsmith provides both universal and format-specific parsers that maintain the
|
|
|
65
72
|
|
|
66
73
|
### Namespaces
|
|
67
74
|
|
|
68
|
-
| Name | Prefix
|
|
75
|
+
| Name | Prefix | Supported in | Parsing | Generating |
|
|
69
76
|
|------|---------|--------------|---------|------------|
|
|
70
77
|
| [Atom](http://www.w3.org/2005/Atom) | `<atom:*>` | RSS, RDF | ✅ | ✅ |
|
|
71
78
|
| [Dublin Core](http://purl.org/dc/elements/1.1/) | `<dc:*>` | RSS, Atom, RDF | ✅ | ✅ |
|
|
@@ -84,32 +91,36 @@ Feedsmith provides both universal and format-specific parsers that maintain the
|
|
|
84
91
|
| [GML](http://www.opengis.net/gml) | `<gml:*>` | 📋 | 📋 | 📋 |
|
|
85
92
|
| [GeoRSS GML](http://www.opengis.net/gml) | `<georss:*>` | 📋 | 📋 | 📋 |
|
|
86
93
|
|
|
87
|
-
[^1]: Custom namespace prefixes are automatically normalized to standard ones (e.g., `<custom:creator>` → `dc.creator`).
|
|
88
|
-
|
|
89
94
|
### Other
|
|
90
95
|
|
|
91
96
|
| Format | Versions | Parsing | Generating |
|
|
92
97
|
|--------|----------|---------|------------|
|
|
93
98
|
| [OPML](https://opml.org/) | 1.0, 2.0 | ✅ | ✅ |
|
|
94
99
|
|
|
95
|
-
##
|
|
100
|
+
## Quick Start
|
|
101
|
+
|
|
102
|
+
This guide will get you up and running with Feedsmith in just a few minutes.
|
|
103
|
+
|
|
104
|
+
> [!IMPORTANT]
|
|
105
|
+
> For a full overview of all the features, visit the [documentation website](https://feedsmith.dev).
|
|
106
|
+
|
|
107
|
+
### Installation
|
|
96
108
|
|
|
97
109
|
```bash
|
|
98
110
|
npm install feedsmith
|
|
99
111
|
```
|
|
100
112
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
### Universal feed parser
|
|
113
|
+
### Parse Any Feed
|
|
104
114
|
|
|
105
115
|
The simplest way to parse any feed is to use the universal `parseFeed` function:
|
|
106
116
|
|
|
107
|
-
```
|
|
117
|
+
```typescript
|
|
108
118
|
import { parseFeed } from 'feedsmith'
|
|
109
119
|
|
|
110
|
-
|
|
120
|
+
// Works with RSS, Atom, JSON Feed, and RDF
|
|
121
|
+
const { format, feed } = parseFeed(feedContent)
|
|
111
122
|
|
|
112
|
-
console.log('Feed format:', format) //
|
|
123
|
+
console.log('Feed format:', format) // rss, atom, json, rdf
|
|
113
124
|
console.log('Feed title:', feed.title)
|
|
114
125
|
|
|
115
126
|
if (format === 'rss') {
|
|
@@ -117,767 +128,84 @@ if (format === 'rss') {
|
|
|
117
128
|
}
|
|
118
129
|
```
|
|
119
130
|
|
|
120
|
-
###
|
|
131
|
+
### Use Format-Specific Parsers
|
|
121
132
|
|
|
122
133
|
If you know the format in advance, you can use the format-specific parsers:
|
|
123
134
|
|
|
124
|
-
```
|
|
125
|
-
import {
|
|
135
|
+
```typescript
|
|
136
|
+
import {
|
|
137
|
+
parseAtomFeed,
|
|
138
|
+
parseJsonFeed,
|
|
139
|
+
parseRssFeed,
|
|
140
|
+
parseRdfFeed
|
|
141
|
+
} from 'feedsmith'
|
|
126
142
|
|
|
127
|
-
// Parse
|
|
143
|
+
// Parse specific formats
|
|
128
144
|
const atomFeed = parseAtomFeed('atom content')
|
|
129
145
|
const jsonFeed = parseJsonFeed('json content')
|
|
130
146
|
const rssFeed = parseRssFeed('rss content')
|
|
131
147
|
const rdfFeed = parseRdfFeed('rdf content')
|
|
132
148
|
|
|
133
|
-
//
|
|
149
|
+
// Access typed data
|
|
134
150
|
rssFeed.title
|
|
135
151
|
rssFeed.dc?.creator
|
|
136
|
-
rssFeed.dc?.date
|
|
137
|
-
rssFeed.sy?.updateBase
|
|
138
152
|
rssFeed.items?.[0]?.title
|
|
139
153
|
```
|
|
140
154
|
|
|
141
|
-
### OPML
|
|
142
|
-
|
|
143
|
-
Parsing OPML files is as simple:
|
|
155
|
+
### Parse OPML Files
|
|
144
156
|
|
|
145
|
-
```
|
|
157
|
+
```typescript
|
|
146
158
|
import { parseOpml } from 'feedsmith'
|
|
147
159
|
|
|
148
|
-
// Parse the OPML content
|
|
149
160
|
const opml = parseOpml('opml content')
|
|
150
161
|
|
|
151
|
-
// Then read the TypeScript suggestions
|
|
152
162
|
opml.head?.title
|
|
153
163
|
opml.body?.outlines?.[0].text
|
|
154
164
|
opml.body?.outlines?.[1].xmlUrl
|
|
155
165
|
```
|
|
156
166
|
|
|
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
|
|
167
|
+
### Generate a Feed
|
|
429
168
|
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
Here's an example of generating an RSS feed.
|
|
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
|
|
169
|
+
```typescript
|
|
438
170
|
import { generateRssFeed } from 'feedsmith'
|
|
439
171
|
|
|
440
|
-
const
|
|
441
|
-
title: 'My
|
|
172
|
+
const rss = generateRssFeed({
|
|
173
|
+
title: 'My Blog',
|
|
442
174
|
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
|
-
],
|
|
175
|
+
description: 'A simple blog',
|
|
176
|
+
items: [{
|
|
177
|
+
title: 'Hello World',
|
|
178
|
+
link: 'https://example.com/hello',
|
|
179
|
+
description: 'My first post',
|
|
180
|
+
pubDate: new Date()
|
|
181
|
+
}]
|
|
464
182
|
})
|
|
465
|
-
```
|
|
466
183
|
|
|
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
|
-
```
|
|
184
|
+
console.log(rss) // Complete RSS XML
|
|
563
185
|
|
|
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>
|
|
186
|
+
// You can also generate other formats:
|
|
187
|
+
// - generateAtomFeed() for Atom feeds
|
|
188
|
+
// - generateJsonFeed() for JSON feeds
|
|
189
|
+
// - generateRdfFeed() for RDF feeds
|
|
190
|
+
// - generateOpml() for OPML files
|
|
597
191
|
```
|
|
598
192
|
|
|
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
|
-
```
|
|
193
|
+
### Handle Errors
|
|
629
194
|
|
|
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
|
-
],
|
|
195
|
+
```typescript
|
|
196
|
+
try {
|
|
197
|
+
const { format, feed } = parseFeed(content)
|
|
198
|
+
// Use the feed
|
|
199
|
+
} catch (error) {
|
|
200
|
+
console.error('Invalid feed:', error.message)
|
|
652
201
|
}
|
|
653
202
|
```
|
|
654
203
|
|
|
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:
|
|
663
|
-
|
|
664
|
-
```ts
|
|
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
|
-
```
|
|
772
|
-
|
|
773
|
-
Will output:
|
|
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
|
|
204
|
+
## Why Feedsmith?
|
|
826
205
|
|
|
827
|
-
|
|
206
|
+
Why should you use this library over the alternatives?
|
|
828
207
|
|
|
829
|
-
|
|
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.
|
|
208
|
+
The key advantage of Feedsmith is that it preserves the original feed structure exactly as defined in each specific feed format.
|
|
881
209
|
|
|
882
210
|
Many alternative packages attempt to normalize data by:
|
|
883
211
|
|
|
@@ -888,24 +216,6 @@ Many alternative packages attempt to normalize data by:
|
|
|
888
216
|
|
|
889
217
|
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
218
|
|
|
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
219
|
## Acknowledgements
|
|
910
220
|
|
|
911
221
|
* The library API is inspired by the [FeedKit library for Swift](https://github.com/nmdias/FeedKit).
|