SporkFeed Core

$3

This can be used to implement a SporkFeed reader application. It tracks feeds, and remembers which articles have been read or saved.

To see the core in action, check out https://github.com/sbj42/sporkfeed-cli - a command-line RSS/Atom feed reader.

Installation



npm install sporkfeed-core





Usage

js

var sporkfeed = require('sporkfeed-core');





Create a new reader, and save its' state:

js

var reader = sporkfeed.startReader();

var state = reader.save();

// save the state somewhere (e.g. JSON.stringify(state) then write to disk)





Load previous state and resume a reader:

js

var state = / load the state from somewhere (e.g. read from disk and JSON.parse) /

var reader = sporkfeed.startReader(state);





Fetch feed data:

js

// if you know the feed url:

sporkfeed.fetchFeed(url).then(function(result) {

    // ...

});



// if you want to find a feed suggested by a website:

sporkfeed.fetchFeedOrFeedReferences(url).then(function(result) {

    if (Array.isArray(result)) {

        // choose a feed from the ones referenced by the website

        return sporkfeed.fetchFeed(result[0].url);

    }

    return result;

}).then(function(result) {

    // ...

});





Add a feed to the reader:

js

var feedData = // fetch feed data as above



reader.addFeed(feedData);





Refresh a feed:

js

// choose a feed from the ones in the reader

var feed = reader.feeds()[0];

// fetch new feed data

sporkfeed.fetchFeed(feed.url).then(function(result) {

    // merge the new feed data into the feed state

    feed.refresh(result);

    // don't forget to save the reader state...

});





Get articles to read:

js

var articles = reader.getArticles();





Mark an article as read:

js

article.setRead();

// don't forget to save the reader state...

API

sporkfeed.startReader([state])





Starts a new reader session, either by loading saved state from an earlier session, or by creating a new, empty reader state.



#### Params



*

[state]

 {State}: Previously saved state, if any



#### Returns



* {Reader}: A reader

sporkfeed.fetchFeed(url)





Fetch a feed from a url.

 

#### Params



*

url

 {string}: The URL of the feed



#### Returns



* {FeedResult}: Feed information fetched from the URL

sporkfeed.fetchFeedOrFeedLinks(url)





Fetches data from a URL and determines if it is a feed or an HTML page.  If a feed, return the feed data.  If an HTML page, look inside to see if there are any links to feeds and return those.  This is useful if the user provides a non-feed URL (e.g.

https://xkcd.com/

) which contains link tags in the head which point to the actual feed URLs.



Note that an HTML page may have multiple feed links, in which case the user may be required to choose which one to use.  That's why this doesn't automatically follow the feed link.

 

#### Params



*

url

 {string}: The URL of the feed or website



#### Returns



* {FeedResult | FeedLink[]}: Feed information fetched from the URL, or links to feeds found at the URL

State





A state object is a plain javascript object, suitable for saving as JSON.

Reader





A reader object holds a bunch of feeds.  The feeds track unread, read, and starred articles.

Reader.feeds()





The feeds being tracked by the reader.



#### Returns



* {Feed[]}: The feeds being tracked by the reader

Reader.unreadArticles()





A list of unread articles across all feeds.  Articles are listed in chronological order by the posting date (from oldest to newest).



#### Returns



* {Article[]}: Unread articles across all feeds

Reader.readArticles()





A list of recently read articles across all feeds.  Articles are listed in chronological order by the date they were read (from oldest to newest).



#### Returns



* {Article[]}: Recently read articles across all feeds

Reader.starredArticles()





A list of starred articles across all feeds.  Articles are listed in chronological order by the date they were starred (from oldest to newest).



#### Returns



* {Article[]}: Starred articles across all feeds

Reader.oldestUnreadArticle()





The oldest unread article that has a posting date, if any.



#### Returns



* {Article | undefined}: The oldest unread article that has a posting date, if any

Reader.newestUnreadArticle()





The newest unread article that has a posting date, if any.



#### Returns



* {Article | undefined}: The newest unread article that has a posting date, if any

Reader.oldestStarredArticle()





The oldest starred article that has a posting date, if any.



#### Returns



* {Article | undefined}: The oldest starred article that has a posting date, if any

Reader.newestStarredArticle()





The newest starred article that has a posting date, if any.



#### Returns



* {Article | undefined}: The newest starred article that has a posting date, if any

Reader.addFeed(feedResult)





Adds a feed to the reader state.  The feed should have previously been fetched using fetchFeed or fetchFeedOrFeedLinks.



All of the articles in the feed result are added as unread.  The feed is named based on the feed properties returned by the feed, but that name can be changed later.



#### Params



*

feedResult

 {FeedResult}: Fetched feed data, as returned by fetchFeed or fetchFeedOrFeedLinks



#### Returns



* {Feed}: The newly added feed

Reader.save()





Saves the reader state to a javscript object, which can be stored using

JSON.stringify()

.  This is when article count limits are enforced.  If there are too many read articles or unread articles in a feed, some will be removed.  Starred articles are not limited.



#### Returns



* {State}: A plain javascript object representing the state of the reader

FeedResult





The data returned by a feed: properties of the feed itself and a list of articles.



#### Properties



*

url

 {string}: The URL of the feed

*

feed

 {FeedData}: Information about the feed as a whole

*

articles

 {ArticleData[]}: Information about the articles currently in the feed

FeedLink





A link to a feed, as may be found in an HTML file.



#### Properties



*

url

 {string}: The URL of the feed

*

[title]

 {string}: The title of the feed link (not necessarily of the feed itself)

Feed





A feed being tracked by the reader.



#### Properties



*

reader

 {Reader}: The reader tracking this feed

*

name

 {string}: The name of the feed.  This is automatically generated when the feed is added, but can be changed later by the user.

*

url

 {string}: The url used to fetch the feed (i.e. to the rss/atom xml data)

*

added

 {Date}: The time that the feed was added

*

lastRefresh

 {Date}: The time that the feed was last refreshed

*

data

 {FeedData}: The feed properties returned by the feed the last time it was refreshed

*

readCount

 {number}: How many articles have been read since the feed was added.  When an article is marked as read this is incremented.  When a read article is marked as unread or starred, this is decremented.

Feed.unreadArticles()





Articles that have not yet been read.  When saving the reader state, articles may be removed from this list if it gets too long.  Articles in this array are listed in chronological order by posting date (from oldest to newest).  Articles without posting dates are sorted earlier than those with posting dates.



#### Returns



* {Article[]}: Articles that have not yet been read

Feed.readArticles()





Articles that have recently been read.  These are kept around in case the user wants to look at recently-read articles, for instance to mark them as unread or star them.  When saving the reader state, articles may be removed from this list if it gets too long.  Articles in this array are listed in chronological order by the date the user read them (from oldest to newest).



#### Returns



* {Article[]}: Articles that have recently been read

Feed.starredArticles()





Articles that have been starred.  Articles are never automatically removed from this list.  The user must explicitly move them by making them read or unread.  Articles in this array are listed in chronological order by the date the user starred them (from oldest to newest).



#### Returns



* {Article[]}: Articles that have been starred

Feed.oldestUnreadArticle()





The oldest unread article that has a posting date, if any.



#### Returns



* {Article | undefined}: The oldest unread article that has a posting date, if any

Feed.newestUnreadArticle()





The newest unread article that has a posting date, if any.



#### Returns



* {Article | undefined}: The newest unread article that has a posting date, if any

Feed.oldestStarredArticle()





The oldest starred article that has a posting date, if any.



#### Returns



* {Article | undefined}: The oldest starred article that has a posting date, if any

Feed.newestStarredArticle()





The newest starred article that has a posting date, if any.



#### Returns



* {Article | undefined}: The newest starred article that has a posting date, if any

Feed.forget()





Removes a feed from the reader.  This also removes information about which articles were read.  No undo facility is provided, so be careful.

Feed.refresh(feedResult)





Refreshes a feed.  The feed should have previously been fetched using fetchFeed on the feed's url.  Any article in the new feed data that has not been seen by the reader will be added to unreadArticles.



#### Params



*

feedResult

 {FeedResult}: Fetched feed data, as returned by fetchFeed or fetchFeedOrFeedLinks



#### Returns



* {RefreshInfo}: Information about the refresh

Feed.save()





Saves the reader state to a javscript object, which can be stored using

JSON.stringify()

.  This is when article count limits are enforced.  If there are too many read articles or unread articles in a feed, some will be removed.  Starred articles are not limited.



#### Returns



* {State}: A plain javascript object representing the state of the reader

RefreshInfo





Information about what happened when a feed was refreshed.



#### Properties



* newCount {number}: How many new unread articles were added

FeedData





Some of the feed properties returned by a feed.



#### Properties



*

[title]

 {string}: The title of the feed or site, as specified by the feed

*

[description]

 {string}: A description of the feed or site, as specified by the feed

*

[canonicalUrl]

 {string}: The canonical link to the feed, as specified by the feed

*

[link]

 {string}: A link to the feed's site, as specified by the feed.

Article





An article being tracked by the reader.



TODO

ArticleData`

Some of the article properties returned by a feed.

TODO

SporkFeed Core

$3

Installation



npm install sporkfeed-core





Usage

js

var sporkfeed = require('sporkfeed-core');





Create a new reader, and save its' state:

js

var reader = sporkfeed.startReader();

var state = reader.save();

// save the state somewhere (e.g. JSON.stringify(state) then write to disk)





Load previous state and resume a reader:

js

var state = / load the state from somewhere (e.g. read from disk and JSON.parse) /

var reader = sporkfeed.startReader(state);





Fetch feed data:

js

// if you know the feed url:

sporkfeed.fetchFeed(url).then(function(result) {

    // ...

});



// if you want to find a feed suggested by a website:

sporkfeed.fetchFeedOrFeedReferences(url).then(function(result) {

    if (Array.isArray(result)) {

        // choose a feed from the ones referenced by the website

        return sporkfeed.fetchFeed(result[0].url);

    }

    return result;

}).then(function(result) {

    // ...

});





Add a feed to the reader:

js

var feedData = // fetch feed data as above



reader.addFeed(feedData);





Refresh a feed:

js

// choose a feed from the ones in the reader

var feed = reader.feeds()[0];

// fetch new feed data

sporkfeed.fetchFeed(feed.url).then(function(result) {

    // merge the new feed data into the feed state

    feed.refresh(result);

    // don't forget to save the reader state...

});





Get articles to read:

js

var articles = reader.getArticles();





Mark an article as read:

js

article.setRead();

// don't forget to save the reader state...

API

sporkfeed.startReader([state])





Starts a new reader session, either by loading saved state from an earlier session, or by creating a new, empty reader state.



#### Params



*

[state]

 {State}: Previously saved state, if any



#### Returns



* {Reader}: A reader

sporkfeed.fetchFeed(url)





Fetch a feed from a url.

 

#### Params



*

url

 {string}: The URL of the feed



#### Returns



* {FeedResult}: Feed information fetched from the URL

sporkfeed.fetchFeedOrFeedLinks(url)





Fetches data from a URL and determines if it is a feed or an HTML page.  If a feed, return the feed data.  If an HTML page, look inside to see if there are any links to feeds and return those.  This is useful if the user provides a non-feed URL (e.g.

https://xkcd.com/

) which contains link tags in the head which point to the actual feed URLs.



Note that an HTML page may have multiple feed links, in which case the user may be required to choose which one to use.  That's why this doesn't automatically follow the feed link.

 

#### Params



*

url

 {string}: The URL of the feed or website



#### Returns



* {FeedResult | FeedLink[]}: Feed information fetched from the URL, or links to feeds found at the URL

State





A state object is a plain javascript object, suitable for saving as JSON.

Reader





A reader object holds a bunch of feeds.  The feeds track unread, read, and starred articles.

Reader.feeds()





The feeds being tracked by the reader.



#### Returns



* {Feed[]}: The feeds being tracked by the reader

Reader.unreadArticles()





A list of unread articles across all feeds.  Articles are listed in chronological order by the posting date (from oldest to newest).



#### Returns



* {Article[]}: Unread articles across all feeds

Reader.readArticles()





A list of recently read articles across all feeds.  Articles are listed in chronological order by the date they were read (from oldest to newest).



#### Returns



* {Article[]}: Recently read articles across all feeds

Reader.starredArticles()





A list of starred articles across all feeds.  Articles are listed in chronological order by the date they were starred (from oldest to newest).



#### Returns



* {Article[]}: Starred articles across all feeds

Reader.oldestUnreadArticle()





The oldest unread article that has a posting date, if any.



#### Returns



* {Article | undefined}: The oldest unread article that has a posting date, if any

Reader.newestUnreadArticle()





The newest unread article that has a posting date, if any.



#### Returns



* {Article | undefined}: The newest unread article that has a posting date, if any

Reader.oldestStarredArticle()





The oldest starred article that has a posting date, if any.



#### Returns



* {Article | undefined}: The oldest starred article that has a posting date, if any

Reader.newestStarredArticle()





The newest starred article that has a posting date, if any.



#### Returns



* {Article | undefined}: The newest starred article that has a posting date, if any

Reader.addFeed(feedResult)





Adds a feed to the reader state.  The feed should have previously been fetched using fetchFeed or fetchFeedOrFeedLinks.



All of the articles in the feed result are added as unread.  The feed is named based on the feed properties returned by the feed, but that name can be changed later.



#### Params



*

feedResult

 {FeedResult}: Fetched feed data, as returned by fetchFeed or fetchFeedOrFeedLinks



#### Returns



* {Feed}: The newly added feed

Reader.save()





Saves the reader state to a javscript object, which can be stored using

JSON.stringify()

.  This is when article count limits are enforced.  If there are too many read articles or unread articles in a feed, some will be removed.  Starred articles are not limited.



#### Returns



* {State}: A plain javascript object representing the state of the reader

FeedResult





The data returned by a feed: properties of the feed itself and a list of articles.



#### Properties



*

url

 {string}: The URL of the feed

*

feed

 {FeedData}: Information about the feed as a whole

*

articles

 {ArticleData[]}: Information about the articles currently in the feed

FeedLink





A link to a feed, as may be found in an HTML file.



#### Properties



*

url

 {string}: The URL of the feed

*

[title]

 {string}: The title of the feed link (not necessarily of the feed itself)

Feed





A feed being tracked by the reader.



#### Properties



*

reader

 {Reader}: The reader tracking this feed

*

name

 {string}: The name of the feed.  This is automatically generated when the feed is added, but can be changed later by the user.

*

url

 {string}: The url used to fetch the feed (i.e. to the rss/atom xml data)

*

added

 {Date}: The time that the feed was added

*

lastRefresh

 {Date}: The time that the feed was last refreshed

*

data

 {FeedData}: The feed properties returned by the feed the last time it was refreshed

*

readCount

 {number}: How many articles have been read since the feed was added.  When an article is marked as read this is incremented.  When a read article is marked as unread or starred, this is decremented.

Feed.unreadArticles()





Articles that have not yet been read.  When saving the reader state, articles may be removed from this list if it gets too long.  Articles in this array are listed in chronological order by posting date (from oldest to newest).  Articles without posting dates are sorted earlier than those with posting dates.



#### Returns



* {Article[]}: Articles that have not yet been read

Feed.readArticles()





Articles that have recently been read.  These are kept around in case the user wants to look at recently-read articles, for instance to mark them as unread or star them.  When saving the reader state, articles may be removed from this list if it gets too long.  Articles in this array are listed in chronological order by the date the user read them (from oldest to newest).



#### Returns



* {Article[]}: Articles that have recently been read

Feed.starredArticles()





Articles that have been starred.  Articles are never automatically removed from this list.  The user must explicitly move them by making them read or unread.  Articles in this array are listed in chronological order by the date the user starred them (from oldest to newest).



#### Returns



* {Article[]}: Articles that have been starred

Feed.oldestUnreadArticle()





The oldest unread article that has a posting date, if any.



#### Returns



* {Article | undefined}: The oldest unread article that has a posting date, if any

Feed.newestUnreadArticle()





The newest unread article that has a posting date, if any.



#### Returns



* {Article | undefined}: The newest unread article that has a posting date, if any

Feed.oldestStarredArticle()





The oldest starred article that has a posting date, if any.



#### Returns



* {Article | undefined}: The oldest starred article that has a posting date, if any

Feed.newestStarredArticle()





The newest starred article that has a posting date, if any.



#### Returns



* {Article | undefined}: The newest starred article that has a posting date, if any

Feed.forget()





Removes a feed from the reader.  This also removes information about which articles were read.  No undo facility is provided, so be careful.

Feed.refresh(feedResult)





Refreshes a feed.  The feed should have previously been fetched using fetchFeed on the feed's url.  Any article in the new feed data that has not been seen by the reader will be added to unreadArticles.



#### Params



*

feedResult

 {FeedResult}: Fetched feed data, as returned by fetchFeed or fetchFeedOrFeedLinks



#### Returns



* {RefreshInfo}: Information about the refresh

Feed.save()





Saves the reader state to a javscript object, which can be stored using

JSON.stringify()

.  This is when article count limits are enforced.  If there are too many read articles or unread articles in a feed, some will be removed.  Starred articles are not limited.



#### Returns



* {State}: A plain javascript object representing the state of the reader

RefreshInfo





Information about what happened when a feed was refreshed.



#### Properties



* newCount {number}: How many new unread articles were added

FeedData





Some of the feed properties returned by a feed.



#### Properties



*

[title]

 {string}: The title of the feed or site, as specified by the feed

*

[description]

 {string}: A description of the feed or site, as specified by the feed

*

[canonicalUrl]

 {string}: The canonical link to the feed, as specified by the feed

*

[link]

 {string}: A link to the feed's site, as specified by the feed.

Article





An article being tracked by the reader.



TODO

ArticleData`

Some of the article properties returned by a feed.

TODO