http-ask
v0.0.0-rc5A flexible promise based HTTP client for Node.js and browser.
Features
- Cloneable and combinable request config
- Support Node.js and browser
- Promise/A+ based
- Chainable API
- Cancelable
- Support timeout
Installing
Using npm:
$ npm install http-ask
Using yarn:
$ yarn add http-ask
Usage
Basic GET
request
// Fetch a user with query (eg: http://localhost/api/users?page=32)
Ask
.create('http://localhost/api/users')
.query({ page: 32 })
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
// Optionally, you can use an `ask` instance
const ask = new Ask('http://localhost/api/users');
ask
.query({ page: 32 })
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
Combinable url
// Fetch a user by id. (eg: http://localhost/api/users/2333)
const id = 2333;
Ask
.create(`http://localhost/api/users/${id}`)
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
// Above could also be done as
Ask
.create('http://localhost')
.url('api/users')
.url(id)
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
Combinable query
// Fetch users with token and other query. (eg: http://localhost/api/users?token=asdf&page=23&count=10)
const token = 'asdf';
Ask
.create('http://localhost/api/users')
.query({ token, page: 23, count: 10 })
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
// Above could also be done as
Ask
.create('/users')
.query({ token })
.query({ page: 23, count: 10 })
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
Clone ask
instance
const apiHost = 'http://localhost/api';
const token = 'asdf';
// create a common api `ask` instance
const askApiWithToken = new Ask(apiHost).query({ token });
askApiWithToken
.clone()
.url('users')
.query({ page: 23, count: 10 })
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
askApiWithToken
.clone()
.url('users')
.query({ page: 1 })
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
Performing POST
, PUT
, DELETE
request
// create a common posts `ask` instance
const askPosts = askApiWithToken.clone().url('posts');
// post
askPosts
.clone()
.post()
.body({ name: 'Chirs' })
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
// put
askPosts
.clone()
.put(id)
.body({ name: 'Chirs' })
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
// delete
askPosts
.clone()
.method('delete')
.url(id)
// Above two lines are equal with `.delete(id)`
.exec()
.then((data) => console.log(data))
.catch((error) => console.log(error))
;
API
Class: new Ask([url[, config]])
Create an ask instance.
Arguments
url
(String): Request URL. In fact, it could be a part (or prefix) of URL.config
(Object): Supportquery
,method
,url
,headers
,cancellation
,timeout
, and any other options from fetch api options
Return
(Object): ask
instance.
Example
// es6
import Ask from 'http-ask';
// es5
// var Ask = require('http-ask').default;
const ask = new Ask('url', {
method: 'post',
body: { ur: 'awesome' }
});
Static Method: Ask.create([url[, config]])
The same with new Ask()
.
Return
(Object): ask
instance.
Static Method: Ask.request(url[, config])
Short hand for Ask.create(url, config).exec()
;
Return
(Promise): A promise to get response data.
Static Method: Ask.clone(ask)
The same with ask.clone()
.
Return
(Object): ask
instance.
Static Property: Ask.Cancellation()
See the follow Cancellation
section for detail.
Return
(Object): cancellation
instance, which has a cancel
method.
Method: ask#method(method)
Set HTTP request method
Arguments
method
(String): All HTTP methods are supported. Default toget
.
Return
(Object): ask
instance.
Method: ask#get([url])
Set GET
method and url.
Arguments
- [
url
] (String): Request URL.
Return
(Object): ask
instance.
Method: ask#post([url])
Set POST
method and url.
Arguments
- [
url
] (String): Request URL.
Return
(Object): ask
instance.
Method: ask#put([url])
Set PUT
method and url.
Arguments
- [
url
] (String): Request URL.
Return
(Object): ask
instance.
Method: ask#patch([url])
Set PATCH
method and url.
Arguments
- [
url
] (String): Request URL.
Return
(Object): ask
instance.
Method: ask#delete([url])
Set DELETE
method and url.
Arguments
- [
url
] (String): Request URL.
Return
(Object): ask
instance.
Method: ask#url(url)
Set or join URL.
Arguments
url
(String): Request URL.
Return
(Object): ask
instance.
Example
// `url` doesn't start with `/`
Ask
.create('http://you.are')
.url('very/very')
.url('awesome')
.exec()
// the final url is: 'http://you.are/very/very/awesome'
;
// `url` starts with '/'
Ask
.create('http://you.are')
.url('very/very')
.url('/awesome') // start with `/`
.exec()
// the final url is: 'http://you.are/awesome'
;
Method: ask#query(query)
Set URL query.
Arguments
query
(Object): URL queryJSON
.
Return
(Object): ask
instance.
Example
Ask
.create('http://localhost', {
query: { a: 1, b: 2 },
})
.query({ b: 3, c: 4 })
.query({ c: 5 })
.exec()
// the final url is: 'http://localhost/?a=1&b=3&c=5'
;
Method: ask#body(body)
Set HTTP request body.
Arguments
body
(Object): AJSON
or instance ofFormData
as usual.
Return
(Object): ask
instance.
Method: ask#set(headerKey, headerValue)
Set HTTP request header.
Arguments
headerKey
(String): Header key.headerValue
(String): Header value.
Return
(Object): ask
instance.
Method: ask#parser(parser)
Add a response parser.
A parser is a function that receives two arguments:
data
(Any): The response dataresponse
(Response): The Response instance
Parser should return a promise. The promise value will be passed to the next parser.
Arguments
parser
(Function): Response parser.
Return
(Object): ask
instance.
Example
Ask
.create('http://localhost/test')
.parser((data, response) => {
console.log('Status:', response.status);
Promise.resolve('awesome!!!');
})
.parser((data, response) => {
console.log('Data:', data);
return data;
})
.exec()
;
// will log:
// Status: 200
// Data: awesome!!!
Method: ask#timeout(ms)
Set HTTP request timeout.
Arguments
ms
(Number): Timeout(ms). Defaults to 30000.
Return
(Object): ask
instance.
Method: ask#cancellation(cancellation)
Set a cancellation token. See the follow example for detail.
Arguments
cancellation
(Cancellation).
Return
(Object): ask
instance.
Example
import Ask, { Cancellation } from 'http-ask';
const cancellation = new Cancellation();
setTimeout(() => {
cancellation.cancel(); // trigger cancel
}, 0);
return Ask
.create('http://localhost/')
.cancellation(cancellation) // register a cancellation
.exec()
.then(() => assert(false, 'should not go here'))
.catch((err) => assert(err instanceof Cancellation))
;
Method: ask#clone()
Clone ask
with current config.
Return
(Object): ask
instance.
Method: ask#exec()
Execute request.
Return
(Promise): A promise to get response data.
Property: ask#response
Http Response instance. It is null
before .exec()
.
Example
const ask = new Ask('http://localhost/');
ask.exec().then((data) => {
console.log('response data', data);
console.log('response status', ask.response.status);
});
License
MIT