wobbuffetch

Reactive wrapper for HTTP requests using Fetch API

Why

Handling asynchronous and event-based requests is boring. Sometimes we need to manipulate data loaded from a server with only what we need, merge, debounce, distinct and so on. Wobbuffetch is a reactive http library that wraps Fetch API along with a set of observable collections that make your life easier.

Features

• Easy to use
• Fetch API features
• Observable api collections (RxJS)
• Automatic transforms for JSON data
• Runs from browser and server

Learn

• About Fetch API: Using Fetch MDN, fetch API - david walsh
• About ReactiveX: RxJS Doc, RxJS Github
• See the Observable super power in RX Marbles - Interactive diagrams

Installing

Via npm:

$ npm install wobbuffetch

Via cdn:

<script src="https://unpkg.com/wobbuffetch/dist/wobbuffetch.min.js"></script>

How to use

GET example:

import wfetch from 'wobbuffetch';

/* api data posts
"posts": [
    {
      "id": 1,
      "title": "FRP for life",
      "author": "anonymous"
    },
    {
      "id": 2,
      "title": "Imperative programming from hell",
      "author": "Demo"
    }
  ]
*/

wfetch.get('http://api.mydomain.com/posts').subscribe(res => console.log(res))

/* response:
{
  data: [
    { "id": 1, "title": "FRP for life", "author": "anonymous" },
    { "id": 2, "title": "Imperative programming from hell", "author": "Demo" }
  ],
  status: 200,
  statusText: 'Ok',
  headers: { Content-Type: application/json },
}
*/

wfetch.get('http://api.mydomain.com/posts').flatMap(res => res.data).subscribe(post => console.log(post))

/* response with flatMap:
  { "id": 1, "title": "FRP for life", "author": "anonymous" },
  { "id": 2, "title": "Imperative programming from hell", "author": "Demo" }
*/

POST example:

wfetch.post('http://api.mydomain.com/posts' {
  data: {
    title: 'How Reactive js works',
    author: 'You'
  }}).subscribe(res => console.log(res))

/* response:
{
  data: { "id": 3, "title": "How wobbuffetch js works", "author": "You" },
  status: 200,
  statusText: 'Ok',
  headers: { Content-Type: application/json },
}
*/

wfetch.post('http://api.mydomain.com/posts' {
  data: {
    title: 'Wobbuffetch js is handy',
    author: 'me'
  }}).map(res => res.data.title).subscribe(title => console.log(title))

/* response with map:
  'Wobbuffetch js is handy'
*/

Error handling:

function _success(response) {
  console.log(`Success: ${response.status}`)
}

function _error({ response }) {
  console.log(`Error: ${response.status}`)
}


wfetch.get('http://mydomain/api/posts/30').subscribe(_success, _error)

/* response Error:
  'Error: 404'
*/

To learn more see RxJS from promise.

Default configuration

We often need to set additional request options, but some of them are default in the wobbuffetch library. For more information and options check out Fetch API options.

An important change in Fetch API is that the option body is now data in wobbuffetch.

{
  baseUrl: '', // Base URL to use in every request
  headers: { 'Content-Type': 'application/json' }, // Fetch API:  Object literal as headers
  credentials: 'same-origin', // Fetch API: Only send cookies if the URL is from the same origin as the calling script.
  cache: 'default',  // Fetch API:  The browser looks for a matching request in its HTTP cache.
  responseType: 'json', // Methods to extract the body from the response (ex: 'arrayBuffer', 'blob', 'json', 'text')
  // Defines if the response will be resolved or rejected given a status.
  validateStatus: function (status) {
    return status >= 200 && status < 300
  }
}

Config default:

import wfetch from 'wobbuffetch';

wfetch.defaults.baseURL = 'http://api.mydomain.com'
wfetch.defaults.headers = { 'Content-Type': 'text/xml' }
wfetch.defaults.responseType = 'text'

Response schema

{
	status: 200, // HTTP status code from the server
	statusText: 'OK', // HTTP status message from the server
	headers: {}, // Headers from the server
	data: {}, // Response data requested from the server ( 'HEAD' method does not receive this)
}

Methods

Instance methods: wobbuffetch#method(url[, config])

GET

wobbuffetch.get('http://api.mydomain.com/posts').subscribe(res => {
	// Do something ...
})

with params:

wobbuffetch.get('http://api.mydomain.com/posts', { // http://api.mydomain.com/posts?title=you
	params: { title: 'you' }
}).subscribe(res => {
	// Do something ...
})

HEAD

// Method 'head' has no 'data'
wobbuffetch.head('http://api.mydomain.com/posts').subscribe(res => {
	console.log(res.data) // undefined
})

DELETE

wobbuffetch.delete('http://api.mydomain.com/posts/1').subscribe(res => {
	// Do something ...
})

POST

// Wobbuffetch there is no options 'body' anymore, use 'data' instead
wobbuffetch.post('http://api.mydomain.com/posts', {
	data: { // It can receives object literal now
		title: 'something',
		author: 'unknown'
	}
}).subscribe(res => {
	// Do something ...
})

PUT

// Wobbuffetch has no option 'body' anymore, use 'data' instead
wobbuffetch.put('http://api.mydomain.com/posts', {
	data: { // It can receive object literals now
		title: 'something',
		author: 'unknown'
	}
}).subscribe(res => {
	// Do something ...
})

PATCH

// Wobbuffetch has no option 'body' anymore, use 'data' instead
wobbuffetch.patch('http://api.mydomain.com/posts', {
	data: { // It can receives object literal now
		title: 'something',
		author: 'unknown'
	}
}).subscribe(res => {
	// Do something ...
})

by

@pedrotcaraujo