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.
Files changed (217) hide show
  1. package/README.md +77 -767
  2. package/dist/common/config.js +0 -1
  3. package/dist/common/parse.d.ts +4 -4
  4. package/dist/common/parse.js +8 -9
  5. package/dist/common/types.d.ts +18 -3
  6. package/dist/common/types.js +0 -1
  7. package/dist/common/utils.d.ts +6 -4
  8. package/dist/common/utils.js +26 -11
  9. package/dist/feeds/atom/common/types.d.ts +11 -11
  10. package/dist/feeds/atom/common/types.js +1 -1
  11. package/dist/feeds/atom/detect/index.js +1 -2
  12. package/dist/feeds/atom/generate/config.js +1 -2
  13. package/dist/feeds/atom/generate/index.d.ts +3 -3
  14. package/dist/feeds/atom/generate/index.js +1 -2
  15. package/dist/feeds/atom/generate/utils.d.ts +6 -5
  16. package/dist/feeds/atom/generate/utils.js +12 -13
  17. package/dist/feeds/atom/parse/config.js +1 -2
  18. package/dist/feeds/atom/parse/index.d.ts +2 -2
  19. package/dist/feeds/atom/parse/index.js +3 -4
  20. package/dist/feeds/atom/parse/utils.d.ts +2 -2
  21. package/dist/feeds/atom/parse/utils.js +11 -12
  22. package/dist/feeds/json/common/types.d.ts +1 -1
  23. package/dist/feeds/json/common/types.js +1 -1
  24. package/dist/feeds/json/detect/index.js +2 -3
  25. package/dist/feeds/json/generate/index.d.ts +3 -2
  26. package/dist/feeds/json/generate/index.js +0 -1
  27. package/dist/feeds/json/generate/utils.d.ts +1924 -35
  28. package/dist/feeds/json/generate/utils.js +4 -4
  29. package/dist/feeds/json/parse/index.d.ts +2 -2
  30. package/dist/feeds/json/parse/index.js +2 -3
  31. package/dist/feeds/json/parse/utils.d.ts +2 -2
  32. package/dist/feeds/json/parse/utils.js +1 -2
  33. package/dist/feeds/rdf/common/types.d.ts +10 -10
  34. package/dist/feeds/rdf/common/types.js +1 -1
  35. package/dist/feeds/rdf/detect/index.js +1 -2
  36. package/dist/feeds/rdf/parse/config.js +1 -2
  37. package/dist/feeds/rdf/parse/index.d.ts +2 -2
  38. package/dist/feeds/rdf/parse/index.js +3 -4
  39. package/dist/feeds/rdf/parse/utils.d.ts +2 -2
  40. package/dist/feeds/rdf/parse/utils.js +10 -11
  41. package/dist/feeds/rss/common/types.d.ts +14 -14
  42. package/dist/feeds/rss/common/types.js +1 -1
  43. package/dist/feeds/rss/detect/index.js +1 -2
  44. package/dist/feeds/rss/generate/config.js +1 -2
  45. package/dist/feeds/rss/generate/index.d.ts +3 -3
  46. package/dist/feeds/rss/generate/index.js +1 -2
  47. package/dist/feeds/rss/generate/utils.d.ts +4 -4
  48. package/dist/feeds/rss/generate/utils.js +15 -16
  49. package/dist/feeds/rss/parse/config.js +1 -2
  50. package/dist/feeds/rss/parse/index.d.ts +2 -2
  51. package/dist/feeds/rss/parse/index.js +3 -4
  52. package/dist/feeds/rss/parse/utils.d.ts +2 -2
  53. package/dist/feeds/rss/parse/utils.js +14 -15
  54. package/dist/index.d.ts +19 -19
  55. package/dist/index.js +14 -15
  56. package/dist/namespaces/atom/common/types.d.ts +2 -2
  57. package/dist/namespaces/atom/common/types.js +1 -1
  58. package/dist/namespaces/atom/generate/utils.d.ts +4 -4
  59. package/dist/namespaces/atom/generate/utils.js +1 -2
  60. package/dist/namespaces/atom/parse/utils.d.ts +2 -2
  61. package/dist/namespaces/atom/parse/utils.js +1 -2
  62. package/dist/namespaces/content/common/types.js +1 -1
  63. package/dist/namespaces/content/generate/utils.d.ts +2 -2
  64. package/dist/namespaces/content/generate/utils.js +1 -2
  65. package/dist/namespaces/content/parse/utils.d.ts +2 -2
  66. package/dist/namespaces/content/parse/utils.js +1 -2
  67. package/dist/namespaces/dc/common/types.d.ts +1 -1
  68. package/dist/namespaces/dc/common/types.js +1 -1
  69. package/dist/namespaces/dc/generate/utils.d.ts +3 -3
  70. package/dist/namespaces/dc/generate/utils.js +1 -2
  71. package/dist/namespaces/dc/parse/utils.d.ts +2 -2
  72. package/dist/namespaces/dc/parse/utils.js +1 -2
  73. package/dist/namespaces/dcterms/common/types.d.ts +1 -1
  74. package/dist/namespaces/dcterms/common/types.js +1 -1
  75. package/dist/namespaces/dcterms/generate/utils.d.ts +3 -3
  76. package/dist/namespaces/dcterms/generate/utils.js +1 -2
  77. package/dist/namespaces/dcterms/parse/utils.d.ts +2 -2
  78. package/dist/namespaces/dcterms/parse/utils.js +1 -2
  79. package/dist/namespaces/georss/common/types.js +1 -1
  80. package/dist/namespaces/georss/generate/utils.d.ts +2 -2
  81. package/dist/namespaces/georss/generate/utils.js +1 -2
  82. package/dist/namespaces/georss/parse/utils.d.ts +2 -2
  83. package/dist/namespaces/georss/parse/utils.js +1 -2
  84. package/dist/namespaces/itunes/common/types.js +1 -1
  85. package/dist/namespaces/itunes/generate/utils.d.ts +2 -2
  86. package/dist/namespaces/itunes/generate/utils.js +1 -2
  87. package/dist/namespaces/itunes/parse/utils.d.ts +2 -2
  88. package/dist/namespaces/itunes/parse/utils.js +1 -2
  89. package/dist/namespaces/media/common/types.js +1 -1
  90. package/dist/namespaces/media/generate/utils.d.ts +2 -2
  91. package/dist/namespaces/media/generate/utils.js +1 -2
  92. package/dist/namespaces/media/parse/utils.d.ts +2 -2
  93. package/dist/namespaces/media/parse/utils.js +1 -2
  94. package/dist/namespaces/podcast/common/types.d.ts +1 -1
  95. package/dist/namespaces/podcast/common/types.js +1 -1
  96. package/dist/namespaces/podcast/generate/utils.d.ts +6 -6
  97. package/dist/namespaces/podcast/generate/utils.js +1 -2
  98. package/dist/namespaces/podcast/parse/utils.d.ts +2 -2
  99. package/dist/namespaces/podcast/parse/utils.js +1 -2
  100. package/dist/namespaces/slash/common/types.js +1 -1
  101. package/dist/namespaces/slash/generate/utils.d.ts +2 -2
  102. package/dist/namespaces/slash/generate/utils.js +1 -2
  103. package/dist/namespaces/slash/parse/utils.d.ts +2 -2
  104. package/dist/namespaces/slash/parse/utils.js +1 -2
  105. package/dist/namespaces/sy/common/types.d.ts +1 -1
  106. package/dist/namespaces/sy/common/types.js +1 -1
  107. package/dist/namespaces/sy/generate/utils.d.ts +3 -3
  108. package/dist/namespaces/sy/generate/utils.js +1 -2
  109. package/dist/namespaces/sy/parse/utils.d.ts +2 -2
  110. package/dist/namespaces/sy/parse/utils.js +1 -2
  111. package/dist/namespaces/thr/common/types.d.ts +1 -1
  112. package/dist/namespaces/thr/common/types.js +1 -1
  113. package/dist/namespaces/thr/generate/utils.d.ts +3 -3
  114. package/dist/namespaces/thr/generate/utils.js +1 -2
  115. package/dist/namespaces/thr/parse/utils.d.ts +2 -2
  116. package/dist/namespaces/thr/parse/utils.js +1 -2
  117. package/dist/namespaces/wfw/common/types.js +1 -1
  118. package/dist/namespaces/wfw/generate/utils.d.ts +2 -2
  119. package/dist/namespaces/wfw/generate/utils.js +1 -2
  120. package/dist/namespaces/wfw/parse/utils.d.ts +2 -2
  121. package/dist/namespaces/wfw/parse/utils.js +1 -2
  122. package/dist/namespaces/yt/common/types.js +1 -1
  123. package/dist/namespaces/yt/generate/utils.d.ts +2 -2
  124. package/dist/namespaces/yt/generate/utils.js +1 -2
  125. package/dist/namespaces/yt/parse/utils.d.ts +2 -2
  126. package/dist/namespaces/yt/parse/utils.js +1 -2
  127. package/dist/opml/common/types.d.ts +1 -1
  128. package/dist/opml/common/types.js +1 -1
  129. package/dist/opml/generate/config.js +1 -2
  130. package/dist/opml/generate/index.d.ts +3 -3
  131. package/dist/opml/generate/index.js +1 -2
  132. package/dist/opml/generate/utils.d.ts +6 -6
  133. package/dist/opml/generate/utils.js +1 -2
  134. package/dist/opml/parse/config.js +1 -2
  135. package/dist/opml/parse/index.d.ts +2 -2
  136. package/dist/opml/parse/index.js +0 -1
  137. package/dist/opml/parse/utils.d.ts +2 -2
  138. package/dist/opml/parse/utils.js +1 -2
  139. package/package.json +11 -6
  140. package/dist/common/config.js.map +0 -1
  141. package/dist/common/parse.js.map +0 -1
  142. package/dist/common/types.js.map +0 -1
  143. package/dist/common/utils.js.map +0 -1
  144. package/dist/feeds/atom/common/types.js.map +0 -1
  145. package/dist/feeds/atom/detect/index.js.map +0 -1
  146. package/dist/feeds/atom/generate/config.js.map +0 -1
  147. package/dist/feeds/atom/generate/index.js.map +0 -1
  148. package/dist/feeds/atom/generate/utils.js.map +0 -1
  149. package/dist/feeds/atom/parse/config.js.map +0 -1
  150. package/dist/feeds/atom/parse/index.js.map +0 -1
  151. package/dist/feeds/atom/parse/utils.js.map +0 -1
  152. package/dist/feeds/json/common/types.js.map +0 -1
  153. package/dist/feeds/json/detect/index.js.map +0 -1
  154. package/dist/feeds/json/generate/index.js.map +0 -1
  155. package/dist/feeds/json/generate/utils.js.map +0 -1
  156. package/dist/feeds/json/parse/index.js.map +0 -1
  157. package/dist/feeds/json/parse/utils.js.map +0 -1
  158. package/dist/feeds/rdf/common/types.js.map +0 -1
  159. package/dist/feeds/rdf/detect/index.js.map +0 -1
  160. package/dist/feeds/rdf/parse/config.js.map +0 -1
  161. package/dist/feeds/rdf/parse/index.js.map +0 -1
  162. package/dist/feeds/rdf/parse/utils.js.map +0 -1
  163. package/dist/feeds/rss/common/types.js.map +0 -1
  164. package/dist/feeds/rss/detect/index.js.map +0 -1
  165. package/dist/feeds/rss/generate/config.js.map +0 -1
  166. package/dist/feeds/rss/generate/index.js.map +0 -1
  167. package/dist/feeds/rss/generate/utils.js.map +0 -1
  168. package/dist/feeds/rss/parse/config.js.map +0 -1
  169. package/dist/feeds/rss/parse/index.js.map +0 -1
  170. package/dist/feeds/rss/parse/utils.js.map +0 -1
  171. package/dist/index.js.map +0 -1
  172. package/dist/namespaces/atom/common/types.js.map +0 -1
  173. package/dist/namespaces/atom/generate/utils.js.map +0 -1
  174. package/dist/namespaces/atom/parse/utils.js.map +0 -1
  175. package/dist/namespaces/content/common/types.js.map +0 -1
  176. package/dist/namespaces/content/generate/utils.js.map +0 -1
  177. package/dist/namespaces/content/parse/utils.js.map +0 -1
  178. package/dist/namespaces/dc/common/types.js.map +0 -1
  179. package/dist/namespaces/dc/generate/utils.js.map +0 -1
  180. package/dist/namespaces/dc/parse/utils.js.map +0 -1
  181. package/dist/namespaces/dcterms/common/types.js.map +0 -1
  182. package/dist/namespaces/dcterms/generate/utils.js.map +0 -1
  183. package/dist/namespaces/dcterms/parse/utils.js.map +0 -1
  184. package/dist/namespaces/georss/common/types.js.map +0 -1
  185. package/dist/namespaces/georss/generate/utils.js.map +0 -1
  186. package/dist/namespaces/georss/parse/utils.js.map +0 -1
  187. package/dist/namespaces/itunes/common/types.js.map +0 -1
  188. package/dist/namespaces/itunes/generate/utils.js.map +0 -1
  189. package/dist/namespaces/itunes/parse/utils.js.map +0 -1
  190. package/dist/namespaces/media/common/types.js.map +0 -1
  191. package/dist/namespaces/media/generate/utils.js.map +0 -1
  192. package/dist/namespaces/media/parse/utils.js.map +0 -1
  193. package/dist/namespaces/podcast/common/types.js.map +0 -1
  194. package/dist/namespaces/podcast/generate/utils.js.map +0 -1
  195. package/dist/namespaces/podcast/parse/utils.js.map +0 -1
  196. package/dist/namespaces/slash/common/types.js.map +0 -1
  197. package/dist/namespaces/slash/generate/utils.js.map +0 -1
  198. package/dist/namespaces/slash/parse/utils.js.map +0 -1
  199. package/dist/namespaces/sy/common/types.js.map +0 -1
  200. package/dist/namespaces/sy/generate/utils.js.map +0 -1
  201. package/dist/namespaces/sy/parse/utils.js.map +0 -1
  202. package/dist/namespaces/thr/common/types.js.map +0 -1
  203. package/dist/namespaces/thr/generate/utils.js.map +0 -1
  204. package/dist/namespaces/thr/parse/utils.js.map +0 -1
  205. package/dist/namespaces/wfw/common/types.js.map +0 -1
  206. package/dist/namespaces/wfw/generate/utils.js.map +0 -1
  207. package/dist/namespaces/wfw/parse/utils.js.map +0 -1
  208. package/dist/namespaces/yt/common/types.js.map +0 -1
  209. package/dist/namespaces/yt/generate/utils.js.map +0 -1
  210. package/dist/namespaces/yt/parse/utils.js.map +0 -1
  211. package/dist/opml/common/types.js.map +0 -1
  212. package/dist/opml/generate/config.js.map +0 -1
  213. package/dist/opml/generate/index.js.map +0 -1
  214. package/dist/opml/generate/utils.js.map +0 -1
  215. package/dist/opml/parse/config.js.map +0 -1
  216. package/dist/opml/parse/index.js.map +0 -1
  217. 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
- [Features](#supported-formats)
20
+ **[Read full docs ↗](https://feedsmith.dev)**
21
21
    ·  
22
- [Installation](#installation)
22
+ [Quick Start](#quick-start)
23
23
    ·  
24
- [Parsing](#parsing)
24
+ [Why Feedsmith?](#why-feedsmith)
25
25
    ·  
26
- [Generating](#generating)
27
-   ·  
28
- [Benchmarks](#benchmarks)
29
-   ·  
30
- [FAQ](#faq)
26
+ [Benchmarks →](benchmarks/README.md)
31
27
 
32
28
  ---
33
29
 
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.
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
- * **Smart namespace handling** 🧠 — Automatically normalizes custom namespace prefixes to standard ones (e.g., `<custom:creator>` becomes `dc.creator`).
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
- #### 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.
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
- #### Compatibility
46
- * Works in Node.js and all modern browsers.
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 formats
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
  &nbsp;&nbsp;·&nbsp;&nbsp;
@@ -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[^1] | Supported in | Parsing | Generating |
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
- ## Installation
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
- ## Parsing
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
- ```ts
117
+ ```typescript
108
118
  import { parseFeed } from 'feedsmith'
109
119
 
110
- const { format, feed } = parseFeed('feed content')
120
+ // Works with RSS, Atom, JSON Feed, and RDF
121
+ const { format, feed } = parseFeed(feedContent)
111
122
 
112
- console.log('Feed format:', format) // → rss, atom, json, rdf
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
- ### Dedicated feed parsers
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
- ```ts
125
- import { parseAtomFeed, parseJsonFeed, parseRssFeed, parseRdfFeed } from 'feedsmith'
135
+ ```typescript
136
+ import {
137
+ parseAtomFeed,
138
+ parseJsonFeed,
139
+ parseRssFeed,
140
+ parseRdfFeed
141
+ } from 'feedsmith'
126
142
 
127
- // Parse the feed content
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
- // Then read the TypeScript suggestions for the specific feed format
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 parser
142
-
143
- Parsing OPML files is as simple:
155
+ ### Parse OPML Files
144
156
 
145
- ```ts
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
- ### 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
167
+ ### Generate a Feed
429
168
 
430
- ### Generating RSS Feed
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 rssFeed = generateRssFeed({
441
- title: 'My RSS Feed',
172
+ const rss = generateRssFeed({
173
+ title: 'My Blog',
442
174
  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
- ],
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
- 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
- ```
184
+ console.log(rss) // Complete RSS XML
563
185
 
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>
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
- ### 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
- ```
193
+ ### Handle Errors
629
194
 
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
- ],
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
- ### 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:
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
- 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.
206
+ Why should you use this library over the alternatives?
828
207
 
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.
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).