|
| 1 | +--- |
| 2 | +"@ascorbic/feed-loader": major |
| 3 | +--- |
| 4 | + |
| 5 | +**BREAKING CHANGE**: Updated underlying feed parser library |
| 6 | + |
| 7 | +This release updates the underlying feed parsing library from the previous parser to `@rowanmanning/feed-parser`, which provides more robust and standardized feed parsing. There is a legacy mode for the previous data shape. This change includes several breaking changes to the data structure: |
| 8 | + |
| 9 | +## Schema Changes |
| 10 | + |
| 11 | +### Category Structure |
| 12 | + |
| 13 | +- **BREAKING**: Category objects now use `label`, `term`, and `url` fields instead of `name` and `domain` |
| 14 | + - Old: `{ name: string, domain: string | null }` |
| 15 | + - New: `{ label: string, term: string, url: string | null }` |
| 16 | + |
| 17 | +### Media/Enclosure Structure |
| 18 | + |
| 19 | +- **BREAKING**: Media objects now include additional fields and renamed properties |
| 20 | + - Old: `{ url: string, type: string | null, length: number | null }` |
| 21 | + - New: `{ url: string, image: string | null, title: string | null, length: number | null, type: string | null, mimeType: string | null }` |
| 22 | + |
| 23 | +### Field Name Changes |
| 24 | + |
| 25 | +- **BREAKING**: `link` field renamed to `url` |
| 26 | +- **BREAKING**: `guid` field renamed to `id` |
| 27 | +- **BREAKING**: Atom `summary` field now maps to `description` (consistent with RSS) |
| 28 | +- **BREAKING**: RSS/Atom `enclosure`/`link[@rel=enclosure]` elements now map to `media` array |
| 29 | + |
| 30 | +## Error Message Changes |
| 31 | + |
| 32 | +- Updated error messages to match new parser behavior: |
| 33 | + - "Item does not have a guid, skipping" → "Item does not have an id or url, skipping" |
| 34 | + - "Response body is empty" → "Feed response is empty" |
| 35 | + |
| 36 | +## Benefits |
| 37 | + |
| 38 | +- More robust XML/Atom/RSS parsing |
| 39 | +- Better handling of malformed feeds |
| 40 | +- Standardized data structure across feed types |
| 41 | +- Improved character encoding support |
| 42 | +- More comprehensive category and media handling |
| 43 | + |
| 44 | +## Legacy Mode Support |
| 45 | + |
| 46 | +To ease migration, this release includes a **temporary legacy mode** that maintains backward compatibility: |
| 47 | + |
| 48 | +```js |
| 49 | +// Enable legacy mode for backward compatibility |
| 50 | +const loader = feedLoader({ |
| 51 | + url: "https://example.com/feed.xml", |
| 52 | + legacy: true, // Will show deprecation warning |
| 53 | +}); |
| 54 | +``` |
| 55 | + |
| 56 | +⚠️ **Legacy mode is deprecated** and will be removed in a future major version. Use it only as a temporary migration aid. |
| 57 | + |
| 58 | +## Migration Guide |
| 59 | + |
| 60 | +### Option 1: Use Legacy Mode (Temporary) |
| 61 | + |
| 62 | +Enable legacy mode to maintain the old data structure while you plan your migration: |
| 63 | + |
| 64 | +```js |
| 65 | +const loader = feedLoader({ |
| 66 | + url: "https://example.com/feed.xml", |
| 67 | + legacy: true, |
| 68 | +}); |
| 69 | +// Data will be in the old format with categories[].name, enclosures, link, guid |
| 70 | +``` |
| 71 | + |
| 72 | +### Option 2: Update to New Format (Recommended) |
| 73 | + |
| 74 | +Update your code to handle the new structured data format: |
| 75 | + |
| 76 | +#### Field Name Changes |
| 77 | + |
| 78 | +```js |
| 79 | +// Item fields |
| 80 | +item.link → item.url |
| 81 | +item.guid → item.id |
| 82 | +item.pubdate/item.date → item.published |
| 83 | +item.summary → item.description (Atom feeds) |
| 84 | +item.enclosures → item.media |
| 85 | +``` |
| 86 | + |
| 87 | +#### Author Structure Change |
| 88 | + |
| 89 | +```js |
| 90 | +// Old: Single string format |
| 91 | +item.author = "email (name)"; |
| 92 | + |
| 93 | +// New: Array of objects |
| 94 | +item.authors = [{ email: "email", name: "name" }]; |
| 95 | +// Access: item.authors[0]?.name, item.authors[0]?.email |
| 96 | +``` |
| 97 | + |
| 98 | +#### Category Structure Change |
| 99 | + |
| 100 | +```js |
| 101 | +// Old: Array of strings |
| 102 | +item.categories = ["category1", "category2"]; |
| 103 | + |
| 104 | +// New: Array of objects |
| 105 | +item.categories = [{ label: "category1", term: "category1", url: null }]; |
| 106 | +// Access: item.categories[0].label |
| 107 | +``` |
| 108 | + |
| 109 | +#### Media/Enclosure Structure Change |
| 110 | + |
| 111 | +```js |
| 112 | +// Old: Basic enclosure format |
| 113 | +item.enclosures = [ |
| 114 | + { |
| 115 | + url: "http://example.com/file.mp3", |
| 116 | + type: "audio/mpeg", |
| 117 | + length: "1234", |
| 118 | + }, |
| 119 | +]; |
| 120 | + |
| 121 | +// New: Enhanced media format |
| 122 | +item.media = [ |
| 123 | + { |
| 124 | + url: "http://example.com/file.mp3", |
| 125 | + mimeType: "audio/mpeg", |
| 126 | + length: 1234, |
| 127 | + image: null, |
| 128 | + title: null, |
| 129 | + }, |
| 130 | +]; |
| 131 | +``` |
| 132 | + |
| 133 | +#### Image Structure Change |
| 134 | + |
| 135 | +```js |
| 136 | +// Old: Simple object with undefined for missing values |
| 137 | +item.image = { url: "http://example.com/image.jpg", title: undefined }; |
| 138 | + |
| 139 | +// New: Full object structure |
| 140 | +item.image = { |
| 141 | + url: "http://example.com/image.jpg", |
| 142 | + title: "Image Title", |
| 143 | + description: "Image description", |
| 144 | +}; |
| 145 | +``` |
| 146 | + |
| 147 | +#### Meta Structure Changes |
| 148 | + |
| 149 | +```js |
| 150 | +// Feed generator changed from string to object |
| 151 | +meta.generator = "WordPress" → feed.generator = { name: "WordPress" } |
| 152 | + |
| 153 | +// Authors follow same pattern as items |
| 154 | +meta.author = "email (name)" → feed.authors = [{ email: "email", name: "name" }] |
| 155 | +``` |
| 156 | + |
| 157 | +Most users who only access `title`, `description`, `url`, and basic fields will not need changes. |
0 commit comments