Nana's Plush Muppet


    1.0.3 • Public • Published


    codecov npm npm npm

    Lightweight HTTP requests library based on superagent that returns a RxJS 5 observable. This library works on browser and server side.


    This library has peer dependencies of rxjs@>=5.0.1 and superagent@>=3.3.0. To install via npm for node environment:

    npm install --save superagent rxjs universal-rx-request

    To install on the browser:

    <script type="text/javascript" src="/lib/index.js"></script>

    The library exposed a global variable called rxRequest. It also works with AMD api.

    Basic Example

    The library exposes a function which makes directly the HTTP request depending of the configuration you give. The request will return an observable.

    import rxRequest from 'universal-rx-request';
    rxRequest({ method: 'get', url: '' })
      .subscribe(result => console.log(result.body.ip), console.error);
    // print your current ip
    rxRequest({ method: 'get', url: '' })
      .subscribe(result => console.log, error => console.error(error.error.errno));
    // print ENOTFOUND

    Works great with redux and redux-observable

    You can import rx extensions which allow you to have more controls on the different steps that the request will going through (fetching => success|error).

    import rxRequest from 'universal-rx-request';
    rxRequest.importRxExtensions(); // will add operators for the observables. You only have to do once
    rxRequest({ method: 'get', url: '' })
      .mapToAction({ type: 'get_my_ip' })
      .subscribe(console.log, console.error);
    // print the emitted items as a stream
    //  |--- { type: 'get_my_ip_fetching', requestStatus: 'fetching' } ------ { type: 'get_my_ip_success', requestStatus: 'success',  data: reponse } ----|
    rxRequest({ method: 'get', url: '' })
      .mapToAction({ type: 'get_my_ip' })
      .subscribe(console.log, console.error);
    // print the emitted items as a stream
    //  |--- { type: 'get_my_ip_fetching', requestStatus: 'fetching' } ------ { type: 'get_my_ip_error', requestStatus: 'error',  error: error } ----|

    Thanks to this rx extension you will be able to handle your state after each step of the HTTP request.

    The rx extensions provide some other useful operators:

    import rxRequest from 'universal-rx-request';
    import { Observable } from 'rxjs/Observable';
    import 'rxjs/add/observable/of';
    rxRequest({ method: 'get', url: '' })
      .mapToAction({ type: 'get_my_ip' })
      .mergeMapOnSucceedRequest(result => Observable.of({ ip: }))
      .subscribe(console.log, console.error);
    // print the emitted items as a stream
    //  |--- { type: 'get_my_ip_fetching', requestStatus: 'fetching' } ------ { ip: '' } ----|

    Once you map the request to an action with maptoAction, We recommand you to use the extended operators to deal with succeed or failure request. these are the extended operators which may be useful:

    • throwErrorOnFailedRequest(): It will throw an error if the result of the http request is an error. To handle the error, you will have to catch it in the observable flow.
    • mergeMapOnSucceedRequest((result) => {...}): It acts like a classic mergeMap in the Rx world except that it will mergeMap only on succeed request (not fetching or error status). The function given as argument has to return an observable.
    • flatMapOnSucceedRequest((result) => {...}): It's an alias for mergeMapOnSucceedRequest.
    • concatMapOnSucceedRequest((result) => {...}): It's like mergeMapOnSucceedRequest except that it use the concatMap operator.
    • doOnSucceedRequest((result) => {...}): It's like mergeMapOnSucceedRequest except that it use the do operator to do side effects.
    • filterOnSucceedRequest(): It's like mergeMapOnSucceedRequest except that it use the filter operator.

    I invite you to check out the test folder which contains great example of how to use these operators correctly.



    Function that will make the HTTP request and returns an observable. Shape of the settings (only url and method fields are required):

      url: 'https://...',
      method: 'get|post|update|...',
      query: {},
      data: {},
      options: {
        only2xx: true|false,
        agent: superagent.agent(),
        json: true|false,
        headers: {},
        withCredentials: true|false,
        responseType: 'blob|...',
        timeout: {
          response: 5000,
          deadline: 60000,
        auth: ['tobi', 'learnboost'],
        redirects: 2,
        attaches: [ ['file', 'test.png'], ...],
        fields: [ ['user', 'Bob'], ...],

    The function will return an observable which will emit an object corresponding to the response of the HTTP request. If an error occurs, the observable will emit an error which can be catch in the observable flow. The error emitted will be an object containing the error and response field. For more details about the shapes of the error and response object, please check the superagent library.


    It's an object containg all the different possible state of the HTTP request:

      FETCHING: 'fetching',
      SUCCESS: 'success',
      ERROR: 'error',

    rxRequest.getStatus(action, status)

    Facility to get the type of the emitted action depending of the action object ({ type: ... }) and the status (rxRequest.STATUS).


    Function to extend the observable with new operators described above.


    npm i universal-rx-request

    DownloadsWeekly Downloads






    Last publish


    • herve-eerebout