bfncs / request-fluture

:butterfly: Simple HTTP requests with Fluture and request.

request-fluture

Simple HTTP requests with Flutures and request.

This is a wrapper around request to offer a Fluture API (instead of callback- or promise-based).

Install

# If you are using npm
npm install request-fluture request fluture

# If you are using yarn
yarn add request-fluture request fluture

Usage

Call the exported function with either a url or an options object according to the request docs. It returns a Fluture for your pending request. You can use the whole Fluture API to do stuff with your result.

const request = require('request-fluture');

request('http://example.com')
    .fork(
       error => console.error('Oh no!', error),
       response => console.log('Got a response!', response)
     );

Fetch data from a REST API and extract some specific data.

const request = require('request-fluture');
const { encase } = require('fluture');

request({url: 'https://api.github.com/users/github', headers: {'User-Agent': 'request-fluture'}})
    .map(res => res.body)
    .chain(encase(JSON.parse))
    .map(user => user.name)
    .fork(
      console.error,
      name => console.log(`The requested username is ${name}.`)
    );

You can cleanly cancel the request fluture anytime after using a consuming function like fork on it:

const request = require('request-fluture');

const cancel = request('http://example.com')
    .fork(console.error, console.log);

// Cancel the request
setTimeout(cancel, 1000);

This is for example also used to cleanly cancel requests whose results are not interesting anymore like when using race, saving your precious bandwidth.

Examples

Race

Race multiple requests against each other and resolve to the first settled request.

const Future = require('fluture');
const request = require('request-fluture');

// Race two requests against each other…
request('http://example.com/foo')
  .race(request('http://example.com/bar'))
  .fork(console.error, console.log);

// …or race an array of requests
const first = futures => futures.reduce(Future.race, Future.never);
first([
  request('http://example.com/foo'),
  request('http://example.com/bar'),
  request('http://example.com/baz')
])
  .fork(console.error, console.log);

You can easily implement a timeout for your requests with this:

const Future = require('fluture');
const request = require('request-fluture');

request('http://example.com/foo')
  .race(Future.rejectAfter(1000, 'Timeout'))
  .fork(console.error, console.log);

Parallel requests

Execute five requests with maximum 5 requests in parallel.

const Future = require('fluture');
const request = require('request-fluture');

const tenRequests = Array.from(Array(10).keys())
  .map(resource => request(`http://example.com/${resource}`));

Future.parallel(5, tenRequests)
  .fork(
    console.error,
    results => { results.forEach(console.log); }
  );

Prior art

This is just a slight extension of a Gist by @Avaq.

request-fluture's Issues

Stealthy require and tough-cookie?

I'm not sure what you intended with the stealth require setup, so consider this a discussion issue 😄

From what I can tell request has a fairly pure API that doesn't modify the module cache for global settings and the like. Tough cookie possibly being the only exception as a simple {jar: true} option enables the default global cookie store.

Is this stealth require intended as a reset of the global cookie store?

If so, wouldn't it be more clean to use requests' own features for this:

// Function that creates a new cookie jar.
const freshJar = request.jar();

// This method returns a wrapper around the normal request API that defaults to whatever options you pass to it.
// Note: request.defaults() does not modify the global request API; instead, it returns a wrapper that has your default settings applied to it.
const freshRequest = request.defaults({jar: freshJar});

That said, wouldn't it be fine to share the global cookie jar with direct usage of request?