Atom Feed Reference

Atom is a syndication format based on XML that provides a robust framework for web feeds. Feedsmith provides comprehensive parsing and generation capabilities.

Versions	0.3, 1.0
Specification	RFC 4287 - Atom Syndication Format
Namespaces	Dublin Core, Dublin Core Terms, Syndication, Slash, iTunes, Podlove Simple Chapters, Media RSS, Google Play Podcast, arXiv, OpenSearch, ccREL, Creative Commons, Atom Threading, Atom Publishing Protocol, Comment API, Administrative, Pingback, Trackback, YouTube, W3C Basic Geo, GeoRSS Simple, XML

Functions

parseAtomFeed()

Parses Atom feed content and returns a typed Atom object.

import { parseAtomFeed } from 'feedsmith'

const atomFeed = parseAtomFeed(xmlContent)
// Returns: object with all fields optional and dates as strings

// Limit number of entries parsed
const atomFeed = parseAtomFeed(xmlContent, { maxItems: 10 })

Parameters

Parameter	Type	Description
content	string	The Atom XML content to parse
options	object	Optional parsing settings

Options

Option	Type	Default	Description
maxItems	number	-	Limit the number of entries parsed. Use 0 to skip entries entirely, useful when only feed metadata is needed

Returns

object - Parsed Atom feed with all fields optional and dates as strings

generateAtomFeed()

Generates Atom XML from feed data.

import { generateAtomFeed } from 'feedsmith'

const xml = generateAtomFeed(feedData, {
  stylesheets: [{ type: 'text/xsl', href: '/feed.xsl' }]
})

Parameters

Parameter	Type	Description
data	object	Atom feed data to generate
options	object	Optional generation settings

Options

Option	Type	Default	Description
strict	boolean	false	Enable strict mode for spec-required field validation, see Strict Mode
stylesheets	Stylesheet[]	-	Add stylesheets for visual formatting, see Feed Styling

Returns

string - Generated Atom XML

detectAtomFeed()

Detects if the provided content is an Atom feed.

Parameters

Parameter	Type	Description
content	string	The content to check

Returns

boolean - true if content appears to be Atom format

Example

import { detectAtomFeed } from 'feedsmith'

const isAtom = detectAtomFeed(xmlContent)

Types

All Atom types are available under the Atom namespace:

import type { Atom } from 'feedsmith'

// Access any type from the definitions below
type Feed = Atom.Feed<Date>
type Entry = Atom.Entry<Date>
type Link = Atom.Link
type Person = Atom.Person
// … see type definitions below for all available types

See the TypeScript guide for usage examples.

Type Definitions

INFO

For details on type parameters (TDate, TStrict) and Requirable<T> markers, see TypeScript Reference.

export namespace Atom {
  // For simplicity's sake, a string is used for now, but this may be reconsidered in the future.
  export type Text = string

  export type Link<TDate extends DateLike, TStrict extends boolean = false> = Strict<
    {
      href: Requirable<string> // Required in spec.
      rel?: string
      type?: string
      hreflang?: string
      title?: string
      length?: number
      thr?: ThrNs.Link<TDate>
    },
    TStrict
  >

  export type Person<TStrict extends boolean = false> = Strict<
    {
      name: Requirable<string> // Required in spec.
      uri?: string
      email?: string
      arxiv?: ArxivNs.Author
    },
    TStrict
  >

  export type Category<TStrict extends boolean = false> = Strict<
    {
      term: Requirable<string> // Required in spec.
      scheme?: string
      label?: string
    },
    TStrict
  >

  export type Generator<TStrict extends boolean = false> = Strict<
    {
      text: Requirable<string> // Required in spec.
      uri?: string
      version?: string
    },
    TStrict
  >

  export type Source<TDate extends DateLike, TStrict extends boolean = false> = {
    authors?: Array<Person<TStrict>>
    categories?: Array<Category<TStrict>>
    contributors?: Array<Person<TStrict>>
    generator?: Generator<TStrict>
    icon?: string
    id?: string
    links?: Array<Link<TDate, TStrict>>
    logo?: string
    rights?: Text
    subtitle?: Text
    title?: Text
    updated?: TDate
  }

  export type Entry<TDate extends DateLike, TStrict extends boolean = false> = Strict<
    {
      authors?: Array<Person<TStrict>>
      categories?: Array<Category<TStrict>>
      content?: Text
      contributors?: Array<Person<TStrict>>
      id: Requirable<string> // Required in spec.
      links?: Array<Link<TDate, TStrict>>
      published?: TDate
      rights?: Text
      source?: Source<TDate, TStrict>
      summary?: Text
      title: Requirable<Text> // Required in spec.
      updated: Requirable<TDate> // Required in spec.
      app?: AppNs.Entry<TDate>
      arxiv?: ArxivNs.Entry
      cc?: CcNs.ItemOrFeed
      dc?: DcNs.ItemOrFeed<TDate>
      slash?: SlashNs.Item
      itunes?: ItunesNs.Item
      googleplay?: GooglePlayNs.Item<TStrict>
      psc?: PscNs.Item<TStrict>
      media?: MediaNs.ItemOrFeed<TStrict>
      georss?: GeoRssNs.ItemOrFeed<TStrict>
      geo?: GeoNs.ItemOrFeed
      thr?: ThrNs.Item<TStrict>
      dcterms?: DcTermsNs.ItemOrFeed<TDate>
      creativeCommons?: CreativeCommonsNs.ItemOrFeed
      wfw?: WfwNs.Item
      yt?: YtNs.Item
      pingback?: PingbackNs.Item
      trackback?: TrackbackNs.Item
      xml?: XmlNs.ItemOrFeed
    },
    TStrict
  >

  export type Feed<TDate extends DateLike, TStrict extends boolean = false> = Strict<
    {
      authors?: Array<Person<TStrict>>
      categories?: Array<Category<TStrict>>
      contributors?: Array<Person<TStrict>>
      generator?: Generator<TStrict>
      icon?: string
      id: Requirable<string> // Required in spec.
      links?: Array<Link<TDate, TStrict>>
      logo?: string
      rights?: Text
      subtitle?: Text
      title: Requirable<Text> // Required in spec.
      updated: Requirable<TDate> // Required in spec.
      entries?: Array<Entry<TDate, TStrict>>
      cc?: CcNs.ItemOrFeed
      dc?: DcNs.ItemOrFeed<TDate>
      sy?: SyNs.Feed<TDate>
      itunes?: ItunesNs.Feed<TStrict>
      googleplay?: GooglePlayNs.Feed<TStrict>
      media?: MediaNs.ItemOrFeed<TStrict>
      georss?: GeoRssNs.ItemOrFeed<TStrict>
      geo?: GeoNs.ItemOrFeed
      dcterms?: DcTermsNs.ItemOrFeed<TDate>
      creativeCommons?: CreativeCommonsNs.ItemOrFeed
      opensearch?: OpenSearchNs.Feed<TStrict>
      yt?: YtNs.Feed
      admin?: AdminNs.Feed
      pingback?: PingbackNs.Feed
      xml?: XmlNs.ItemOrFeed
    },
    TStrict
  >
}

Related

• Parsing Atom Feeds - How to parse Atom content
• Generating Atom Feeds - How to create Atom feeds
• Atom Detection - Detecting Atom format