listener-rss/README.md

# listener rss

A lightweight library to make simple actions with a RSS feed.

# USAGE

## Punctual usage

You can parse RSS from a URL with some custom data.  
An example :

```js
const ListenerModule = require("ListenerRSS");
const ListenerRss = ListenerModule.ListenerRss;

const listener = new ListenerRss({
    address: "fake.rss.service"
  });

// make a request to the adr 'fake.rss.service'
const feed = await myListener.fetchRSS();
```

## Recurrent usage

You can parse RSS from a URL each n times.  
An example :

```js
const ListenerModule = require("ListenerRSS");
const ListenerRss = ListenerModule.ListenerRss;

const listener = new ListenerRss({
    address: "fake.rss.service"
  });

listener.on("update", feed => { /* ... */ });
listener.on("error", err => { /* ... */ });
listener.on("newEntries", feedEntries => { /* ... */ });


listener.start();

/*...*/

listener.stop();
```

# Documentation

## ListenerRss.Config

An interface to structure listener's data.

### Constructor

- address : the service address
- [optional] timeloop : time to wait between 2 request in seconds (default 5 minutes)
- [optional] customfields : to notice field who's custom to the service (default blank)
  [cf annexe CustomFields](#customfields)
- [optional] lastEntriesLinks : to specify an predefined history.

## ListenerRSS

### Constructor

`constructor(ListenerRss.Config)`

- ListenerRss.Config : object from the ListenerRss.Config's class.

### fetchRSS()

This function allows to make a request to the rss service.

#### Return

Return a promise object who's resolved like `resolve: (value: result_fetch) => void))` where `result_fetch` is a json
object who's contain the data. [cf Annexe Output](#output)

#### Issues

Reject the promise if the server can't be resolved.

### start()

This function will call the `update` event to each success update, the
`error` event to each fail update, and the `newEntries` event for
each update who contains a new item.

#### Events

Each event take one arg into the callback function.

```js
listener.on("update", feed => { /* ... */ });
listener.on("error", err => { /* ... */ });
listener.on("newEntries", feedEntries => { /* ... */ });

```

#### update

It used a callback who receive the received object entirely inside an object.

#### error

It used a callback who receive an error object.

#### newEntries

It used a callback who receive only new entries inside an array.

### stop()

This function will stop the execution of the callbackFun each time loop.

### getProperty()

This function will return a ListenerRss.Config (a.k.a. a JSON object) item corresponding to the internal configuration of the class.

# Annexe

## CustomFields

This parameter permit to specify some custom fields who's present in the service but not in the RFC.
For example the YouTube RSS api give some data into the `<media:group>` field. So you can give this info with this :

```js
[["media:group", "media:group"]];
```

You can also rename the field with the left part :

```js
[["my_custom_media_group_name", "media:group"]];
```

In adition you can rename child element into custom field like this :

```js
[
  ["media:group", "media:group"],
  ["description", ["media:group", "media:description"]],
  ["icon", ["media:group", "media:thumbnail"]],
];
```

In this case it's useless to specify the parent field, so you can just omit the first line :

```js
[
  ["description", ["media:group", "media:description"]],
  ["icon", ["media:group", "media:thumbnail"]],
];
```

## Output

Here an example of what type of json object is output during a fetch :

```json
{
  "feedUrl": "fake.rrs.service",
  "title": "myFakeApiTitle",
  "description": "My Fake api desc",
  "link": "fake.rrs.service",
  "items": [
    {
      "title": "My last item",
      "link": "fake.rrs.service/item1",
      "pubDate": "Thu, 12 Nov 2015 21:16:39 +0000",
      "creator": "someone",
      "content": "<a href=\"http://example.com\">this is a link</a> &amp; <b>this is bold text</b>",
      "contentSnippet": "this is a link & this is bold text",
      "guid": "fake.rrs.service/item1",
      "categories": ["test", "npm", "fakeInfos"],
      "isoDate": "2015-11-12T21:16:39.000Z"
    }
    /*Some Others items*/
  ]
}
```