http-ask v0.0.0

A 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

1. url (String): Request URL. In fact, it could be a part (or prefix) of URL.
2. config (Object): Support query, 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

1. method (String): All HTTP methods are supported. Default to get.

Return

(Object): ask instance.

Method: ask#get(url)

Set GET method and url.

Arguments

1. url: Request URL.

Return

(Object): ask instance.

Method: ask#post(url)

Set POST method and url.

Arguments

1. url: Request URL.

Return

(Object): ask instance.

Method: ask#put(url)

Set PUT method and url.

Arguments

1. url: Request URL.

Return

(Object): ask instance.

Method: ask#patch(url)

Set PATCH method and url.

Arguments

1. url: Request URL.

Return

(Object): ask instance.

Method: ask#delete(url)

Set DELETE method and url.

Arguments

1. url: Request URL.

Return

(Object): ask instance.

Method: ask#url(url)

Set or join URL.

Arguments

1. 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

1. query (Object): URL query JSON.

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

1. body (Object): A JSON or instance of FormData as usual.

Return

(Object): ask instance.

Method: ask#set(headerKey, headerValue)

Set HTTP request header.

Arguments

1. headerKey (String): Header key.
2. 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:

1. data (Any): The response data
2. response (Response): The Response instance

Parser should return a promise. The promise value will be passed to the next parser.

Arguments

1. 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

1. 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

1. 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