❤
npm
Sign UpSign In

http-ask

0.0.0 • Public • Published

A flexible promise based HTTP client for Node.js and browser.

Build Status http-ask code style npm version

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

Readme

Keywords

Package Sidebar

Install

npm i http-ask

Repository

github.com/Cap32/http-ask

Homepage

github.com/Cap32/http-ask#readme

Weekly Downloads

2

Version

0.0.0

License

MIT

Last publish

Collaborators

  • cap32
Try on RunKit
Report malware