api-jarvis

api jarvis project

Usage no npm install needed!

<script type="module">
  import apiJarvis from 'https://cdn.skypack.dev/api-jarvis';
</script>

README

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 v4.0.0

  • v4.0.0
    • Update Features getAutoRejectErrorFormat (thanks for GA-MO)
    • Disable autoReject 404 & 502, change it to be params flag. (thanks for GA-MO)
  • v3.7.0
    • Update Features getTimeoutErrorFormat(url, params) (thanks for GA-MO)
  • v3.6.0
    • Handle error case 'Syntax error' and 'Failed to fetch (thanks for KIRAN H
  • v3.5.0
    • Fixed cannot throw http 404, 502 (thanks for KIRAN H
  • v3.4.3
    • Fixed plugins to be default at undefined.
  • v3.4.2
    • Fixed bugs not reject properly error and should hide all log. (thanks for GA-MO)
  • v3.4.0
    • Update Features add parameter 'plugins' in fetchWithJarvis. (thanks for GA-MO)
    • Migrate 'status', 'headers', 'contentType', 'location' to 'meta' (thanks for GA-MO)
  • 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.

Getting Started

NPM

$ npm install api-jarvis --save

YARN

$ yarn add api-jarvis

Live Demo (running at api-jarvis v4.0.0)

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

Advanced Usage: Reveal Key Features

If you are newbie, PLEASE START HERE

There are many features we have provided

Basic Usage

import { fetchWithJarvis } from 'api-jarvis'

const data = getData().then((response) => {
  console.log('data', response)
});

const getData = () => {
  return fetchWithJarvis('http://httpstat.us/200')
  .then((response, meta) => {
    // get yours response
    console.log(response, meta)
    return response
  })
}

Basic Usage with Error Handling

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

By default, api-jarvis using it own 'isResponseError' and 'toErrorFormat' plugins's function.

See default plugins function description

For api-jarvis version 3.4.0

No need to import handleResponseCatchError, It will be called in function fetchWithJarvis

import { fetchWithJarvis } from 'api-jarvis'

const data = getData().then((response) => {
  console.log('data', response)
}).catch((error) => {
  console.error('error', error)
})

export const getData = () => {
  return fetchWithJarvis('http://httpstat.us/500')
   .then((response, meta) => {
    // get yours response
    console.log(response, meta)
    return response
  })
}

Example for version prior 3.4.0

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;
  })
}

API Reference

1. fetchWithJarvis (url, options, plugins)

Property Type Priority Description
url String Required url to fetch.
options Object Optional Fetch options such as 'method', 'headers', etc.
plugins PlugIns Schema Optional Plugins function to empower jarvis. (See Plugins Schema)

Example Usage

  return fetchWithJarvis()

  1.

2. handleResponseCatchError(response, isResponseError, toErrorFormat, meta)

Let's me talk about handleResponseCatchError function a little bit

This function is used to check response is success or error to manage work flow easily.

Let's see in action.

Property Type Priority Description
response Object Required Object to be parameters of isResponseError(response, meta) and toErrorFormat(response, meta)
isResponseError Function Optional Function which consider should resove or reject.
toErrorFormat Function Optional Fucntion which return error format for catch (error) {}.
meta Object Optional Object to be parameters of isResponseError(response, meta) and toErrorFormat(response, meta)

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

Default isError function

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

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);
  })
}

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

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

Documentation

Read more DOC.MD

Contact Me !

mondit.thum@gmail.com

alt text

License

API Jarvis is licensed under the MIT license