listener-rss/README.md

# easy-rss-parser

A lightweight library to give some additions for the [rss-parser package](https://github.com/rbren/rss-parser).

# USAGE

## Punctual usage

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

```js
const easyParser = require("easy-rss-parser");
const ListenerRss = easyParser.ListenerRss;

let listener = new ListenerRss("my-test-service", "fake.rss.service");

// make a request to the adr 'fake.rss.service'
myListener.fetchRSS().then((obj, err) => {
  // some act
});
```

## Recurrent usage

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

```js
const easyParser = require("easy-rss-parser");
const ListenerRss = easyParser.ListenerRss;

let listener = new ListenerRss("my-test-service", "fake.rss.service", 5 * 60);

let callback_fun = (obj, err) => {
  // some act
};
// call callback_fun each 5 minutes
listener.start(callback_fun);

/*...*/

listener.stop();
```

# Documentation

## ListenerRSSInfo

A class to structure listener's data.

### Constructor

`constructor(name, address, timeloop, customfields)`

- name : the service name
- 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)

## ListenerRSS

### Constructor

`constructor(listenerRSSInfo)`

- listenerRSSInfo : object from the ListenerRSSInfo's class.

`constructor(name, address, timeloop, customfields)`

- name : the service name
- 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)

### 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

Return an error if the server can't be resolved.

### start(callbackFun)

This function will execute the callbackFun each time loop.

#### Parameter

The `callbackFun` is the function who's going to be called each time loop. She need to be under the shape :

```js
(obj, err) => {
  /*...*/
};
```

### stop()

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

# 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'
```