Merge pull request #29 from macieklamberski/feat/singular-fields

feat: Make sure that singular fields are treated as such if multiple present in XML

Author: macieklamberski

README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/feedsmith.svg)](https://www.npmjs.com/package/feedsmith)
 [![license](https://img.shields.io/npm/l/feedsmith.svg)](https://github.com/macieklamberski/feedsmith/blob/main/LICENSE)
 
-Modern JavaScript utility for parsing and generating JSON Feed, Atom, RSS, and RDF feeds, with support for popular namespaces. It provides both universal and format-specific parsers that maintain the original feed structure while offering helpful normalization.
+Robust and fast JavaScript parser for RSS, Atom, JSON Feed, and RDF feeds, with support for popular namespaces. It provides both universal and format-specific parsers that maintain the original feed structure while offering helpful normalization.
 
 Feedsmith maintains the original feed structure in a clean, object-oriented format. It intelligently normalizes legacy elements, providing you with complete access to all feed data without compromising simplicity.
 
@@ -421,7 +421,7 @@ For a quick overview, here are the results of parsing RSS, Atom, and RDF feeds u
 
 ## FAQ
 
-### Why should I use Feedsmith instead of alternative modules?
+### Why should I use Feedsmith instead of alternative packages?
 
 As stated in the overview section, the key advantage of Feedsmith is that it preserves the original feed structure exactly as provided in each specific feed format.
 

benchmarks/bun.lock

@@ -10,12 +10,13 @@
     "feed-read": "^0.0.1",
     "feedme": "^2.0.2",
     "feedparser": "^2.2.10",
+    "podcast-feed-parser": "^1.0.4",
     "rss-parser": "^3.13.0",
     "tinybench": "^4.0.1"
   },
   "devDependencies": {
     "@types/benchmark": "^2.1.5",
-    "@types/bun": "^1.2.9",
+    "@types/bun": "^1.2.10",
     "@types/feedme": "^2.0.4",
     "@types/feedparser": "^2.2.8",
     "typescript": "^5.8.3"

benchmarks/package.json

@@ -5,6 +5,7 @@ import { parseFeed as rowanmanningFeedParser } from '@rowanmanning/feed-parser'
 import { rssParse as ulisesgasconRssFeedParser } from '@ulisesgascon/rss-feed-parser'
 import FeedMeJs from 'feedme'
 import FeedParser from 'feedparser'
+import { getPodcastFromFeed as podcastFeedParser } from 'podcast-feed-parser'
 import RssParser from 'rss-parser'
 import { parseAtomFeed, parseJsonFeed, parseRdfFeed, parseRssFeed } from '../src/index'
 import { loadFeedFiles, runBenchmarks, runTest } from './utils'
@@ -59,62 +60,67 @@ const atomBigFiles = loadFeedFiles('feeds/atom-big', 10)
 const atomSmallFiles = loadFeedFiles('feeds/atom-small', 50)
 const rdfFiles = loadFeedFiles('feeds/rdf', 50)
 
-await runBenchmarks('RSS feed parsing (10 files × 5MB — 50MB)', {
+await runBenchmarks('RSS feed parsing (10 files × 5MB–50MB)', {
   'rss-parser': () => runTest(rssBigFiles, rssParser),
   '@gaphub/feed': () => runTest(rssBigFiles, gaphubFeedParser),
   '@rowanmanning/feed-parser': () => runTest(rssBigFiles, rowanmanningFeedParser),
   'feedme.js': () => runTest(rssBigFiles, feedMeJs),
   '@extractus/feed-extractor': () => runTest(rssBigFiles, extractFromXml),
   '@ulisesgascon/rss-feed-parser': () => runTest(rssBigFiles, ulisesgasconRssFeedParser),
   feedparser: () => runTest(rssBigFiles, feedParser),
+  'podcast-feed-parser': () => runTest(rssBigFiles, podcastFeedParser),
   'feedsmith *': () => runTest(rssBigFiles, parseRssFeed),
 })
 
-await runBenchmarks('RSS feed parsing (50 files × 100KB — 5MB)', {
+await runBenchmarks('RSS feed parsing (50 files × 100KB–5MB)', {
   'rss-parser': () => runTest(rssSmallFiles, rssParser),
   '@gaphub/feed': () => runTest(rssSmallFiles, gaphubFeedParser),
   '@rowanmanning/feed-parser': () => runTest(rssSmallFiles, rowanmanningFeedParser),
   'feedme.js': () => runTest(rssSmallFiles, feedMeJs),
   '@extractus/feed-extractor': () => runTest(rssSmallFiles, extractFromXml),
   '@ulisesgascon/rss-feed-parser': () => runTest(rssSmallFiles, ulisesgasconRssFeedParser),
   feedparser: () => runTest(rssSmallFiles, feedParser),
+  'podcast-feed-parser': () => runTest(rssSmallFiles, podcastFeedParser),
   'feedsmith *': () => runTest(rssSmallFiles, parseRssFeed),
 })
 
-await runBenchmarks('Atom feed parsing (10 files × 5MB — 50MB)', {
+await runBenchmarks('Atom feed parsing (10 files × 5MB–50MB)', {
   'rss-parser': () => runTest(atomBigFiles, rssParser),
   '@gaphub/feed': () => runTest(atomBigFiles, gaphubFeedParser),
   '@rowanmanning/feed-parser': () => runTest(atomBigFiles, rowanmanningFeedParser),
   'feedme.js': () => runTest(atomBigFiles, feedMeJs),
   '@extractus/feed-extractor': () => runTest(atomBigFiles, extractFromXml),
   // @ulisesgascon/rss-feed-parser — does not support Atom feeds.
   feedparser: () => runTest(atomBigFiles, feedParser),
+  // podcast-feed-parser — does not support Atom feeds.
   'feedsmith *': () => runTest(atomBigFiles, parseAtomFeed),
 })
 
-await runBenchmarks('Atom feed parsing (50 files × 100KB — 5MB)', {
+await runBenchmarks('Atom feed parsing (50 files × 100KB–5MB)', {
   'rss-parser': () => runTest(atomSmallFiles, rssParser),
   '@gaphub/feed': () => runTest(atomSmallFiles, gaphubFeedParser),
   '@rowanmanning/feed-parser': () => runTest(atomSmallFiles, rowanmanningFeedParser),
   'feedme.js': () => runTest(atomSmallFiles, feedMeJs),
   '@extractus/feed-extractor': () => runTest(atomSmallFiles, extractFromXml),
   // @ulisesgascon/rss-feed-parser — does not support Atom feeds.
   feedparser: () => runTest(atomSmallFiles, feedParser),
+  // podcast-feed-parser — does not support Atom feeds.
   'feedsmith *': () => runTest(atomSmallFiles, parseAtomFeed),
 })
 
-await runBenchmarks('RDF feed parsing (50 files × 100KB — 5MB)', {
+await runBenchmarks('RDF feed parsing (50 files × 100KB–5MB)', {
   'rss-parser': () => runTest(rdfFiles, rssParser),
   '@gaphub/feed': () => runTest(rdfFiles, gaphubFeedParser),
   '@rowanmanning/feed-parser': () => runTest(rdfFiles, rowanmanningFeedParser),
   'feedme.js': () => runTest(rdfFiles, feedMeJs),
   '@extractus/feed-extractor': () => runTest(rdfFiles, extractFromXml),
   // @ulisesgascon/rss-feed-parser — does not support RDF feeds.
   feedparser: () => runTest(rdfFiles, feedParser),
+  // podcast-feed-parser — does not support RDF feeds.
   'feedsmith *': () => runTest(rdfFiles, parseRdfFeed),
 })
 
-await runBenchmarks('JSON feed parsing (50 files × 100KB — 5MB)', {
+await runBenchmarks('JSON feed parsing (50 files × 100KB–5MB)', {
   // '@extractus/feed-extractor' — does not properly parse and always returns empty feed.
   'feedsmith *': () => runTest(jsonFilesObjects, parseJsonFeed),
 })

benchmarks/parsing.ts

@@ -1,6 +1,6 @@
 {
   "name": "feedsmith",
-  "description": "Modern JavaScript utility for parsing and generating JSON Feed, Atom, RSS, and RDF feeds, with support for Dublin Core, Syndication, iTunes, and many other popular namespaces.",
+  "description": "Robust and fast parser for RSS, Atom, JSON Feed, and RDF feeds, with support for iTunes, Dublin Core, and many other popular namespaces.",
   "repository": {
     "type": "git",
     "url": "https://github.com/macieklamberski/feedsmith.git"

package.json

@@ -12,6 +12,7 @@ import {
   parseBoolean,
   parseNumber,
   parseSingular,
+  parseSingularOf,
   parseString,
   retrieveText,
   stripCdata,
@@ -903,6 +904,64 @@ describe('parseSingular', () => {
   })
 })
 
+describe('parseSingularOf', () => {
+  it('should apply parse function to the first element of an array', () => {
+    const parseToString: ParseFunction<string> = (value) => {
+      return typeof value === 'number' || typeof value === 'string' ? String(value) : undefined
+    }
+
+    expect(parseSingularOf([1, 2, 3], parseToString)).toEqual('1')
+    expect(parseSingularOf(['a', 'b', 'c'], parseToString)).toEqual('a')
+    expect(parseSingularOf([42, 'text'], parseString)).toEqual('42')
+  })
+
+  it('should apply parse function to non-array values', () => {
+    expect(parseSingularOf(42, parseString)).toEqual('42')
+    expect(parseSingularOf('123', parseNumber)).toEqual(123)
+    expect(parseSingularOf('true', parseBoolean)).toEqual(true)
+  })
+
+  it('should return undefined when the parse function returns undefined', () => {
+    expect(parseSingularOf({}, parseNumber)).toBeUndefined()
+    expect(parseSingularOf('not-a-number', parseNumber)).toBeUndefined()
+    expect(parseSingularOf([{}, 'string'], parseNumber)).toBeUndefined()
+  })
+
+  it('should handle empty arrays', () => {
+    expect(parseSingularOf([], parseString)).toBeUndefined()
+  })
+
+  it('should handle arrays with undefined or null first elements', () => {
+    expect(parseSingularOf([undefined, 1, 2], parseNumber)).toBeUndefined()
+    expect(parseSingularOf([null, 1, 2], parseNumber)).toBeUndefined()
+  })
+
+  it('should preserve the type returned by the parse function', () => {
+    const numberResult = parseSingularOf<number>('42', parseNumber)
+    const stringResult = parseSingularOf<string>(42, parseString)
+    const booleanResult = parseSingularOf<boolean>('true', parseBoolean)
+
+    expect(typeof numberResult).toEqual('number')
+    expect(typeof stringResult).toEqual('string')
+    expect(typeof booleanResult).toEqual('boolean')
+  })
+
+  it('should work with custom parse functions', () => {
+    const parseUpperCase: ParseFunction<string> = (value) => {
+      return typeof value === 'string' ? value.toUpperCase() : undefined
+    }
+
+    expect(parseSingularOf('hello', parseUpperCase)).toEqual('HELLO')
+    expect(parseSingularOf(['hello', 'world'], parseUpperCase)).toEqual('HELLO')
+    expect(parseSingularOf(123, parseUpperCase)).toBeUndefined()
+  })
+
+  it('should handle null and undefined input values', () => {
+    expect(parseSingularOf(null, parseString)).toBeUndefined()
+    expect(parseSingularOf(undefined, parseNumber)).toBeUndefined()
+  })
+})
+
 describe('parseArray', () => {
   it('should handle arrays', () => {
     const value1 = [] as Array<string>

src/common/utils.test.ts

@@ -138,10 +138,6 @@ export const parseBoolean: ParseFunction<boolean> = (value) => {
   }
 }
 
-export const parseSingular = <T>(value: T | Array<T>): T => {
-  return Array.isArray(value) ? value[0] : value
-}
-
 export const parseArray: ParseFunction<Array<Unreliable>> = (value) => {
   if (Array.isArray(value)) {
     return value
@@ -190,6 +186,14 @@ export const parseArrayOf = <R>(
   }
 }
 
+export const parseSingular = <T>(value: T | Array<T>): T => {
+  return Array.isArray(value) ? value[0] : value
+}
+
+export const parseSingularOf = <R>(value: Unreliable, parse: ParseFunction<R>): R | undefined => {
+  return parse(parseSingular(value))
+}
+
 export const createNamespaceGetter = (
   value: Record<string, Unreliable>,
   prefix: string | undefined,
@@ -211,3 +215,13 @@ export const createCaseInsensitiveGetter = (value: Record<string, unknown>) => {
     return originalKey ? value[originalKey] : undefined
   }
 }
+
+// TODO: Write tests.
+export const parseTextString: ParseFunction<string> = (value) => {
+  return parseString(retrieveText(value))
+}
+
+// TODO: Write tests.
+export const parseTextNumber: ParseFunction<number> = (value) => {
+  return parseNumber(retrieveText(value))
+}