hifetch
A minimal higher-level wrapper around Fetch API
Built on top of isomorphic-fetch
Get started
npm install hifetch
Hifetch is optimized for JSON API.
You can fetch, process and consume JSON response with minimal custom options.
; // GET http://www.mydomain.com/users/1/?mobile=true// + Response 200 (application/json; charset=utf-8)// + Headers// X-API-Version: 1.0// + Body// {// "status": 0,// "username": "xxx"// };
By default, Hifetch supports JSON response in Goolge JSON Style
// GET http://www.mydomain.com/users/wrong-id/// + Response 400 (application/json; charset=utf-8)// + Body// {// "error": {// "code": 400,// "message": "User Not Found", // human readable message// "errors": [{// "reason": "ResourceNotFoundException", // Unique Identifier// "message": "User Not Found", // human readable message// }]// }// }; // GET http://www.mydomain.com/users/1/// + Response 200 (application/json; charset=utf-8)// + Body// {// "data": {// "otherDataA": ...// "otherDataB": ...// },// };
Hifetch also supports JSON response with unix-style exit status
A zero exit status indicates succeeded. A nonzero exit status indicates failure (Hifetch only supports negative number)
You can use this style by responseStyle
option
// GET http://www.mydomain.com/users/wrong-id/// + Response 200 (application/json; charset=utf-8)// + Body// {// "status": -1, // Unique Identifier// "message": "User Not Found" // human readable message// "otherData": ...// }; // GET http://www.mydomain.com/users/1/// + Response 200 (application/json; charset=utf-8)// + Body// {// "status": 0,// "otherDataA": ...// "otherDataB": ...// };
You can disable this feature by disableResponseStyle
option
HTTP status code validation
;
Error response caused by user-defined hook function (validateStatus
, parser
, handler
, success
, error
)
;
By default, Hifetch directly uses response body as the result.
When the response body is JSON object format, you can merge some response headers into the result.
// GET http://www.mydomain.com/users/1/// + Response 200 (application/json; charset=utf-8)// + Headers// X-API-Version: 1.0// + Body// {// "status": 0,// "username": "xxx"// };
When enableMeta
is true, the result is a meta object.
// GET http://www.mydomain.com/users/1/// + Response 200 (application/json; charset=utf-8)// + Headers// X-API-Version: 1.0// + Body// {// "status": 0,// "username": "xxx"// }; ;
Use custom responseType
and parser
to fetch HTML string:
Post JSON with urlencoded body
Post JSON with JSON-encoded body
Post form-data body
const formData = ;formData;
or
Post form-data body with files
or
const formData = ;formData;formData;formData;
Custom validator and processor for response data
Options
Request
url
- Required
method
- Default:
'get'
- Default:
query
- Type: plain object
dataType
- Default:
'application/x-www-form-urlencoded'
- Custom
'Content-Type'
header
- Default:
data
- Type: plain object, FormData object or String
- When using FormData,
dataType
can be omitted (always be 'multipart/form-data')
FormData
- Required in node.js environment
- FormData class
headers
- Other custom request headers
jwtToken
- Add JWT header
Response
responseType
- Default:
'application/json'
- Custom
'Accept'
header
- Default:
responseStyle
- Type: 'google' | 'unix'
- Default:
'google'
- Automatically processing the JSON response based on special style guide
mergeHeaders
- Type: plain object
- Default: null
- Merge some response headers into the JSON object reponse
- Example:
{ poweredBy: 'X-Powered-By' }
filterHeaders
- Type: plain object
- Default: null
- Pick some response headers.
- Example:
{ 'X-Powered-By': true }
or{ 'x-powered-by': true }
timeout
- Millisecond
enableCookies
- Type: Boolean
- Default: false
- Automatically send cookies
disableCORS
- Type: Boolean
- Default: false
disableStatusValidator
- Type: Boolean
- Default: false
- Skip the
validateStatus
hook
disableResponseStyle
- Type: Boolean
- Default: false
- Disable the automatic processing (like 'REMOTE ERROR') triggered by the special format of JSON response
enableMeta
- Type: Boolean
- Default: false
- Embed response body into a meta object
enableResponseObject
- Type: Boolean
- Default: false
- Like
enableMeta
, plus the response object
Hooks
validateStatus
- Default:
status >= 200 && status < 300
- Custom validator for acceptable HTTP response status code
- Default:
parser
- Default:
response => response.json()
- Default:
handler
- Custom validator and processor for response data
success
- Default:
res => res
- Default:
error
- Default:
res => Promise.reject(res)
- Default:
Actions
send()
- Return: Promise
- Automatically nterrupt latest outstanding request each time it's called
cancel()
- Interrupt latest outstanding request, nothing happen
error()
- Interrupt latest outstanding request, trigger error callback
See actions.spec.js for more detail.
Development
npm run lint
npm run test