api-jarvis

API Jarvis

A lightweight assistant which helping you get data more easier.

Stop suffering from getting REST API data

If you liked, gimme a star, Thanks.

Release Issues

Latest version is v3.4.0

• v3.4.0
  • Update Features add parameter plugins in fetchWithJarvis.
  • Migrate status, headers, contentType, location to meta
• v3.3.1
  • Handler status 204 to be resolve with baseResponse.
• v3.2.1
  • Fixed bugs did not export getAccessToken, setDebugMode.
• v3.2.0
  • Add function setDebugMode to set global debugger for fetchWithJarvis.
  • Fixed bugs response is neither json nor text then throw error. (Fixed to be responsed).
• v3.1.2
  • Fixed bugs http code 1XX, 3XX, 5XX not resolve.

Special Thanks to 'Pitipat Doppy Srichairat'

He is founder of this module.

Prerequisite

This project uses library ES2015 syntax, fetch and isomorphic-fetch. Let's checked it out.

• ES2015 https://babeljs.io/learn-es2015/
• isomorphic-fetch https://github.com/matthew-andrews/isomorphic-fetch

Installation

NPM

$ npm install api-jarvis --save

YARN

$ yarn add api-jarvis

Live Demo

https://hlex.github.io/api-jarvis/demo

The live demo is still running api-jarvis v2.2.0

Basic Usage

import { fetchWithJarvis } from 'api-jarvis'

const data = getData();

export const getData = () => {
  return fetchWithJarvis('http://httpstat.us/200')
  .then((response) => {
    // get yours data
    return response
  })
}

Features

• Http status error handle build-in (such as http error code = 4XX, 5XX)
• Timeout handle build-in (in seconds)
• Default fetch options
  • Content-Type: 'application/json'
  • method: 'GET'
  • credentials: 'same-origin'
• Custom options
• Default throw error conditional
• Custom throw error conditional
• Default error class
• Custom error class
• Set access_token to your fetch's header
• Easy to generate url parameters from object
• Providing many Utility functions

Basic Usage with Error Handling

Using handleResponseCatchError from api-jarvis at the top of your js file.

import { fetchWithJarvis, handleResponseCatchError } from 'api-jarvis'

const data = getData();

export const getData = () => {
  return fetchWithJarvis('http://httpstat.us/500')
  .then((response) => {
    handleResponseCatchError(response) // this line automatically throw error if response has fault key
  return response;
  })
}

handleResponseCatchError(response, isError, convertResponseToAppFormat)

Let's me talk about handleResponseCatchError function a little bit (you can read full docs here)

Property	Type
response	Object
isError	Function (optional)
convertResponseToAppFormat	Function (optional)

You might not want to send isError or convertFormat functions (as you seen, it is optional) so these are defaults

Default isError function

isError is a function which using to decide that this response is error or not

For example, isError default fucntion check if response object contain key 'fault' is will be decided as error

const isError = (response) => {
  return response.fault !== undefined;
}

Example customize your isError

import { fetchWithJarvis, handleResponseCatchError } from 'api-jarvis'

const data = getData();

const myIsError = (response) => {
  return response.indexOf('500') >= 0
}

export const getData = () => {
  return fetchWithJarvis('http://httpstat.us/500')
  .then((response) => {
    handleResponseCatchError(response, myIsError)
    return response
  })
  .catch((error) => {
    console.error(error);
  })
}

Default convertResponseToAppFormat function

convertResponseToAppFormat is a function that receive response then itself will return another data. Normally, it uses to normalize any data from server format to be an application data format.

For example, convertResponseToAppFormat default function receive response then return instance of ApplicationError Class (you can see class definition below)

default class ApplicationError extends Error {
  constructor({ type, trxId, processInstance, fault, displayMessages }) {
    super(type);
    this.type = type || 'ERROR';
    this.trxId = trxId;
    this.processInstance = processInstance;
    this.code = fault.code;
    this.fault = fault;
    this.displayMessages = displayMessages;
    this.message = {
      th: displayMessages[0]['th-message'],
      en: displayMessages[0]['en-message'],
      technical: displayMessages[0]['technical-message'],
    };
    if (typeof Error.captureStackTrace === 'function') {
      Error.captureStackTrace(this, this.constructor);
    } else {
      this.stack = (new Error(type)).stack;
    }
  }
}

const convertResponseToAppFormat = (response) => {
  return new ApplicationError({
    type: getErrorType(response),
    trxId: response['trx-id'],
    processInstance: response['process-instance'],
    status: response.status,
    fault: response.fault,
    displayMessages: response['display-messages'],
  });
};

Example customize your convertor

import { fetchWithJarvis, handleResponseCatchError } from 'api-jarvis'

const data = getData();

const myConvertResponseToAppFormat = (response) => {
  return {
    code: Date.now(),
    message: response,
  }
}

const myIsError = (response) => {
  return response.indexOf('500') >= 0
}

export const getData = () => {
  return fetchWithJarvis('http://httpstat.us/500')
  .then((response) => {
    handleResponseCatchError(response, myIsError, myConvertResponseToAppFormat)
    return response
  })
  .catch((error) => {
    console.error(error);
  })
}

You can find more feature's examples in DOC.MD

Documentation

Read more DOC.MD

Contact Me !

[e-mail]

License

API Jarvis is licensed under the MIT license