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.
Files changed (174) hide show
  1. package/README.md +77 -777
  2. package/dist/common/config.js +0 -1
  3. package/dist/common/parse.js +0 -1
  4. package/dist/common/types.d.ts +18 -3
  5. package/dist/common/types.js +0 -1
  6. package/dist/common/utils.d.ts +6 -4
  7. package/dist/common/utils.js +26 -11
  8. package/dist/feeds/atom/common/types.js +1 -1
  9. package/dist/feeds/atom/detect/index.js +0 -1
  10. package/dist/feeds/atom/generate/config.js +0 -1
  11. package/dist/feeds/atom/generate/index.d.ts +2 -2
  12. package/dist/feeds/atom/generate/index.js +0 -1
  13. package/dist/feeds/atom/generate/utils.d.ts +5 -4
  14. package/dist/feeds/atom/generate/utils.js +0 -1
  15. package/dist/feeds/atom/parse/config.js +0 -1
  16. package/dist/feeds/atom/parse/index.js +0 -1
  17. package/dist/feeds/atom/parse/utils.js +0 -1
  18. package/dist/feeds/json/common/types.js +1 -1
  19. package/dist/feeds/json/detect/index.js +0 -1
  20. package/dist/feeds/json/generate/index.d.ts +2 -1
  21. package/dist/feeds/json/generate/index.js +0 -1
  22. package/dist/feeds/json/generate/utils.d.ts +1917 -28
  23. package/dist/feeds/json/generate/utils.js +4 -4
  24. package/dist/feeds/json/parse/index.js +0 -1
  25. package/dist/feeds/json/parse/utils.js +0 -1
  26. package/dist/feeds/rdf/common/types.js +1 -1
  27. package/dist/feeds/rdf/detect/index.js +0 -1
  28. package/dist/feeds/rdf/parse/config.js +0 -1
  29. package/dist/feeds/rdf/parse/index.js +0 -1
  30. package/dist/feeds/rdf/parse/utils.js +0 -1
  31. package/dist/feeds/rss/common/types.js +1 -1
  32. package/dist/feeds/rss/detect/index.js +0 -1
  33. package/dist/feeds/rss/generate/config.js +0 -1
  34. package/dist/feeds/rss/generate/index.d.ts +2 -2
  35. package/dist/feeds/rss/generate/index.js +0 -1
  36. package/dist/feeds/rss/generate/utils.d.ts +3 -3
  37. package/dist/feeds/rss/generate/utils.js +0 -1
  38. package/dist/feeds/rss/parse/config.js +0 -1
  39. package/dist/feeds/rss/parse/index.js +0 -1
  40. package/dist/feeds/rss/parse/utils.js +0 -1
  41. package/dist/index.js +0 -1
  42. package/dist/namespaces/atom/common/types.js +1 -1
  43. package/dist/namespaces/atom/generate/utils.d.ts +3 -3
  44. package/dist/namespaces/atom/generate/utils.js +0 -1
  45. package/dist/namespaces/atom/parse/utils.js +0 -1
  46. package/dist/namespaces/content/common/types.js +1 -1
  47. package/dist/namespaces/content/generate/utils.js +0 -1
  48. package/dist/namespaces/content/parse/utils.js +0 -1
  49. package/dist/namespaces/dc/common/types.js +1 -1
  50. package/dist/namespaces/dc/generate/utils.d.ts +2 -2
  51. package/dist/namespaces/dc/generate/utils.js +0 -1
  52. package/dist/namespaces/dc/parse/utils.js +0 -1
  53. package/dist/namespaces/dcterms/common/types.js +1 -1
  54. package/dist/namespaces/dcterms/generate/utils.d.ts +2 -2
  55. package/dist/namespaces/dcterms/generate/utils.js +0 -1
  56. package/dist/namespaces/dcterms/parse/utils.js +0 -1
  57. package/dist/namespaces/georss/common/types.js +1 -1
  58. package/dist/namespaces/georss/generate/utils.js +0 -1
  59. package/dist/namespaces/georss/parse/utils.js +0 -1
  60. package/dist/namespaces/itunes/common/types.js +1 -1
  61. package/dist/namespaces/itunes/generate/utils.js +0 -1
  62. package/dist/namespaces/itunes/parse/utils.js +0 -1
  63. package/dist/namespaces/media/common/types.js +1 -1
  64. package/dist/namespaces/media/generate/utils.js +0 -1
  65. package/dist/namespaces/media/parse/utils.js +0 -1
  66. package/dist/namespaces/podcast/common/types.js +1 -1
  67. package/dist/namespaces/podcast/generate/utils.d.ts +5 -5
  68. package/dist/namespaces/podcast/generate/utils.js +0 -1
  69. package/dist/namespaces/podcast/parse/utils.js +0 -1
  70. package/dist/namespaces/slash/common/types.js +1 -1
  71. package/dist/namespaces/slash/generate/utils.js +0 -1
  72. package/dist/namespaces/slash/parse/utils.js +0 -1
  73. package/dist/namespaces/sy/common/types.js +1 -1
  74. package/dist/namespaces/sy/generate/utils.d.ts +2 -2
  75. package/dist/namespaces/sy/generate/utils.js +0 -1
  76. package/dist/namespaces/sy/parse/utils.js +0 -1
  77. package/dist/namespaces/thr/common/types.js +1 -1
  78. package/dist/namespaces/thr/generate/utils.d.ts +2 -2
  79. package/dist/namespaces/thr/generate/utils.js +0 -1
  80. package/dist/namespaces/thr/parse/utils.js +0 -1
  81. package/dist/namespaces/wfw/common/types.js +1 -1
  82. package/dist/namespaces/wfw/generate/utils.js +0 -1
  83. package/dist/namespaces/wfw/parse/utils.js +0 -1
  84. package/dist/namespaces/yt/common/types.js +1 -1
  85. package/dist/namespaces/yt/generate/utils.js +0 -1
  86. package/dist/namespaces/yt/parse/utils.js +0 -1
  87. package/dist/opml/common/types.js +1 -1
  88. package/dist/opml/generate/config.js +0 -1
  89. package/dist/opml/generate/index.d.ts +2 -2
  90. package/dist/opml/generate/index.js +0 -1
  91. package/dist/opml/generate/utils.d.ts +5 -5
  92. package/dist/opml/generate/utils.js +0 -1
  93. package/dist/opml/parse/config.js +0 -1
  94. package/dist/opml/parse/index.js +0 -1
  95. package/dist/opml/parse/utils.js +0 -1
  96. package/package.json +11 -6
  97. package/dist/common/config.js.map +0 -1
  98. package/dist/common/parse.js.map +0 -1
  99. package/dist/common/types.js.map +0 -1
  100. package/dist/common/utils.js.map +0 -1
  101. package/dist/feeds/atom/common/types.js.map +0 -1
  102. package/dist/feeds/atom/detect/index.js.map +0 -1
  103. package/dist/feeds/atom/generate/config.js.map +0 -1
  104. package/dist/feeds/atom/generate/index.js.map +0 -1
  105. package/dist/feeds/atom/generate/utils.js.map +0 -1
  106. package/dist/feeds/atom/parse/config.js.map +0 -1
  107. package/dist/feeds/atom/parse/index.js.map +0 -1
  108. package/dist/feeds/atom/parse/utils.js.map +0 -1
  109. package/dist/feeds/json/common/types.js.map +0 -1
  110. package/dist/feeds/json/detect/index.js.map +0 -1
  111. package/dist/feeds/json/generate/index.js.map +0 -1
  112. package/dist/feeds/json/generate/utils.js.map +0 -1
  113. package/dist/feeds/json/parse/index.js.map +0 -1
  114. package/dist/feeds/json/parse/utils.js.map +0 -1
  115. package/dist/feeds/rdf/common/types.js.map +0 -1
  116. package/dist/feeds/rdf/detect/index.js.map +0 -1
  117. package/dist/feeds/rdf/parse/config.js.map +0 -1
  118. package/dist/feeds/rdf/parse/index.js.map +0 -1
  119. package/dist/feeds/rdf/parse/utils.js.map +0 -1
  120. package/dist/feeds/rss/common/types.js.map +0 -1
  121. package/dist/feeds/rss/detect/index.js.map +0 -1
  122. package/dist/feeds/rss/generate/config.js.map +0 -1
  123. package/dist/feeds/rss/generate/index.js.map +0 -1
  124. package/dist/feeds/rss/generate/utils.js.map +0 -1
  125. package/dist/feeds/rss/parse/config.js.map +0 -1
  126. package/dist/feeds/rss/parse/index.js.map +0 -1
  127. package/dist/feeds/rss/parse/utils.js.map +0 -1
  128. package/dist/index.js.map +0 -1
  129. package/dist/namespaces/atom/common/types.js.map +0 -1
  130. package/dist/namespaces/atom/generate/utils.js.map +0 -1
  131. package/dist/namespaces/atom/parse/utils.js.map +0 -1
  132. package/dist/namespaces/content/common/types.js.map +0 -1
  133. package/dist/namespaces/content/generate/utils.js.map +0 -1
  134. package/dist/namespaces/content/parse/utils.js.map +0 -1
  135. package/dist/namespaces/dc/common/types.js.map +0 -1
  136. package/dist/namespaces/dc/generate/utils.js.map +0 -1
  137. package/dist/namespaces/dc/parse/utils.js.map +0 -1
  138. package/dist/namespaces/dcterms/common/types.js.map +0 -1
  139. package/dist/namespaces/dcterms/generate/utils.js.map +0 -1
  140. package/dist/namespaces/dcterms/parse/utils.js.map +0 -1
  141. package/dist/namespaces/georss/common/types.js.map +0 -1
  142. package/dist/namespaces/georss/generate/utils.js.map +0 -1
  143. package/dist/namespaces/georss/parse/utils.js.map +0 -1
  144. package/dist/namespaces/itunes/common/types.js.map +0 -1
  145. package/dist/namespaces/itunes/generate/utils.js.map +0 -1
  146. package/dist/namespaces/itunes/parse/utils.js.map +0 -1
  147. package/dist/namespaces/media/common/types.js.map +0 -1
  148. package/dist/namespaces/media/generate/utils.js.map +0 -1
  149. package/dist/namespaces/media/parse/utils.js.map +0 -1
  150. package/dist/namespaces/podcast/common/types.js.map +0 -1
  151. package/dist/namespaces/podcast/generate/utils.js.map +0 -1
  152. package/dist/namespaces/podcast/parse/utils.js.map +0 -1
  153. package/dist/namespaces/slash/common/types.js.map +0 -1
  154. package/dist/namespaces/slash/generate/utils.js.map +0 -1
  155. package/dist/namespaces/slash/parse/utils.js.map +0 -1
  156. package/dist/namespaces/sy/common/types.js.map +0 -1
  157. package/dist/namespaces/sy/generate/utils.js.map +0 -1
  158. package/dist/namespaces/sy/parse/utils.js.map +0 -1
  159. package/dist/namespaces/thr/common/types.js.map +0 -1
  160. package/dist/namespaces/thr/generate/utils.js.map +0 -1
  161. package/dist/namespaces/thr/parse/utils.js.map +0 -1
  162. package/dist/namespaces/wfw/common/types.js.map +0 -1
  163. package/dist/namespaces/wfw/generate/utils.js.map +0 -1
  164. package/dist/namespaces/wfw/parse/utils.js.map +0 -1
  165. package/dist/namespaces/yt/common/types.js.map +0 -1
  166. package/dist/namespaces/yt/generate/utils.js.map +0 -1
  167. package/dist/namespaces/yt/parse/utils.js.map +0 -1
  168. package/dist/opml/common/types.js.map +0 -1
  169. package/dist/opml/generate/config.js.map +0 -1
  170. package/dist/opml/generate/index.js.map +0 -1
  171. package/dist/opml/generate/utils.js.map +0 -1
  172. package/dist/opml/parse/config.js.map +0 -1
  173. package/dist/opml/parse/index.js.map +0 -1
  174. 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
- > [!IMPORTANT]
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
- [Installation](#installation)
14
+ [Quick Start](#quick-start)
23
15
    ·  
24
- [Parsing](#parsing)
16
+ [Why Feedsmith?](#why-feedsmith)
25
17
    ·  
26
- [Generating](#generating)
27
-   ·  
28
- [Benchmarks](#benchmarks)
29
-   ·  
30
- [FAQ](#faq)
18
+ [Benchmarks →](benchmarks/README.md)
31
19
 
32
20
  ---
33
21
 
34
- #### Leniency
35
- * **Normalizes legacy elements** ✨ — Upgrades feed elements to their modern equivalents so that you never need to worry about reading feeds in older formats.
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
- * **Smart namespace handling** 🧠 — Automatically normalizes custom namespace prefixes to standard ones (e.g., `<custom:creator>` becomes `dc.creator`).
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
- #### Performance and type-safety
40
- * **Fast parsing** ⚡ — One of the fastest feed parsers in JavaScript (see [benchmarks](#benchmarks)).
41
- * **Type-safe API** 🛟 — TypeScript type definitions are available for each feed format, making it easy to work with the data.
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
- #### Compatibility
46
- * Works in Node.js and all modern browsers.
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 formats
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
  &nbsp;&nbsp;·&nbsp;&nbsp;
@@ -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[^1] | Supported in | Parsing | Generating |
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
- ## Installation
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
- ## Parsing
101
+ > **Upgrading from v1.x?** Check out the [migration guide](https://feedsmith.dev/migration-to-2.x).
102
102
 
103
- ### Universal feed parser
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
- ```ts
107
+ ```typescript
108
108
  import { parseFeed } from 'feedsmith'
109
109
 
110
- const { format, feed } = parseFeed('feed content')
110
+ // Works with RSS, Atom, JSON Feed, and RDF
111
+ const { format, feed } = parseFeed(feedContent)
111
112
 
112
- console.log('Feed format:', format) // → rss, atom, json, rdf
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
- ### Dedicated feed parsers
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
- ```ts
125
- import { parseAtomFeed, parseJsonFeed, parseRssFeed, parseRdfFeed } from 'feedsmith'
125
+ ```typescript
126
+ import {
127
+ parseAtomFeed,
128
+ parseJsonFeed,
129
+ parseRssFeed,
130
+ parseRdfFeed
131
+ } from 'feedsmith'
126
132
 
127
- // Parse the feed content
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
- // Then read the TypeScript suggestions for the specific feed format
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 parser
142
-
143
- Parsing OPML files is as simple:
145
+ ### Parse OPML Files
144
146
 
145
- ```ts
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
- ### Returned values
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 &lt;em&gt;only&lt;/em&gt;</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
- 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
159
+ ```typescript
438
160
  import { generateRssFeed } from 'feedsmith'
439
161
 
440
- const rssFeed = generateRssFeed({
441
- title: 'My RSS Feed',
162
+ const rss = generateRssFeed({
163
+ title: 'My Blog',
442
164
  link: 'https://example.com',
443
- description: 'A sample RSS feed with various elements',
444
- language: 'en-US',
445
- pubDate: new Date('2024-01-15T12:00:00Z'),
446
- lastBuildDate: new Date('2024-01-15T12:00:00Z'),
447
- generator: 'Feedsmith',
448
- managingEditor: 'editor@example.com (John Editor)',
449
- webMaster: 'webmaster@example.com (Jane Webmaster)',
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
- Will output:
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
- Will output:
565
-
566
- ```xml
567
- <?xml version="1.0" encoding="utf-8"?>
568
- <feed xmlns="http://www.w3.org/2005/Atom">
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
- ### Generating JSON Feed
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
- Will output:
631
-
632
- ```json
633
- {
634
- "version": "https://jsonfeed.org/version/1.1",
635
- "title": "My Example Feed",
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
- ### Generating with Namespaces
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
- ```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
- ```
196
+ Why should you use this library over the alternatives?
772
197
 
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
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).