fetchfull v0.1.7

Using Fetch in a application is sometimes complicated:

• Options need to be set in each call
• You need to translate the result in json in each call
• Unauthenticated call need to be handled in every request
• There is no time-out
• When an option value is mispelled, you can search for it
• Data is not easy to manage in a put or post request
• ...

Of course, you can do it. That's not the question. The question is: should you do it?

This library help you:

• Configure fetch declaratively

(new FetchFull()).requestWithGet().requestToUrl("/blablabla")

• Manage the data for you

(new FetchFull()).requestWitPut().requestWithData({ a: 1})

• Add time-out

(new FetchFull()).requestWithTimeOut(3/*secs*/)

• Dispatch the result according to response

(new FetchFull()).onResponseCode(401, (response) => { handleIt() });

• Give you JSON as result if you need it (if the result is not a json, fallback nicefully to text)

(new FetchFull()).responseAsJson().fire()
	.then((json) => { console.log(json); });

• The configuration calls can be chained

(new FetchFull())
	.responseAsJson()
	.onResponseCode(401, fn)
	.requestWithGet()
	.requestWithHeader(key, value)
	.fire()
	.then(json => fn);

• The system can be used as a framework/factory application-wide

  function myFetchFactory(url, data) {
    let baseURL = "http://service.myproject.com/api/v1.0/"
    let fetchfull = new FetchFull()
    fetchfull
      .requestToUrl(baseURL + url)
      .requestWithGet()
      .requestWithData(data)
      .requestWithTimeOut(60) // seconds
      .responseAsJSON()
      .onTimeOut(() => {
        // Timeout
      })
      .onResponseCode(403, () => { /* Handle unauthenticated application-wide*/ })
      .onResponseCode(401, () => { /* Handle unauthorized application-wide*/ })
      .onResponseCode(500, () => { /* Handle internal server error application-wide*/ })
      ;
    return fetchfull
  }

And use it like this

request = myFetchFactory("/blablalba", { a: 1 })
    .requetWithHeader("auth", "me")
    .fire()
    .then(json => { console.log(json); })

Installation

Bower

Install it with bower:

bower install --save fetchfull

Before using it, please include "objectPath" (from bower_components/object-path/index.js)

<script type='text/javascript' src='bower_components/object-path/index.js'></script>
<script type='text/javascript' src='bower_components/fetchfull/src/fetchfull.js'></script>

NPM

You can alos use it with npm, while I didn't test it:

npm install --save fetchfull

Usage

Please look at the code (src/fetchfull.js) and at the tests (tests/*) to see how it works. The code is fully documented (and private functios marked as such). The introduction in the fetchfull.js explain a lot also. The tests have a description that would help you understanding the mecanisms.

Example of usage:

• Get text from the server

    let fetchfull = new FetchFull();
    fetchfull
      .requestToUrl(baseURL + "/test")
      .requestWithGet()
      .responseAsText()
      .fire()
      .then((data) => {
        // Data
      })

• Get result as JSON:

    let fetchfull = new FetchFull();
    fetchfull
      .requestToUrl(baseURL + "/test.json")
      .requestWithGet()
      .responseAsJson()
      .fire()
      .then((data) => {
        expect(data).toEqual({
          "email": "anybody@gmail.com"
        });
        done();
      })

It add some specific handlers.

• Handle 404:

  it("should handle 404.json", function(done) {
    let fetchfull = new FetchFull();
    fetchfull
      .requestToUrl(baseURL + "/404.json")
      .requestWithGet()
      .responseAsJson()
      .onResponseCode(404, (text) => {
        // Handle that case
      })
      .fire()

With a time-out

A generic timeout of 30 seconds is programmed, but you can specify whatever you like. It can not be disabled, just specify a long time if necessary.

    let fetchfull = new FetchFull()
    fetchfull
      .requestToUrl(baseURL + "/timeout")
      .requestWithGet()
      .requestWithTimeOut(2) // 2 seconds timeout (very short !!!)
      .responseAsText()
      .onTimeOut(() => {
        // Timeout
      })
      .fire()
      .then(() => {
        // Normal case
      })

Changelog

• 0.1.7:

  • onSuccess callbacks are now fired before .then(), and if a callback send back a promise, it will be waited on it before continuing to the next callback and to the then()

• 0.1.6:

  • add a .tag("tag") to add a tag to each message, to ease the debugging when the call fail

• 0.1.5:

  • make then(callback) working correctly
  • make requestWithCredentials work correctly

TODO

• If you find something missing, please open a bug (and a pull request if you have the energy for it :-) )... Any suggestions are welcome to enhance this code.
• I would like to minify the code
• cancel request
• try again x times every y seconds (+ signal each iteration and finish as timeout)
• work on the flux between all callback:
  • who transform what data?
  • what if success send back a promise?