# http-ask

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

Latest version **0.0.0** (published 2017-12-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install http-ask
pnpm add http-ask
yarn add http-ask
bun add http-ask
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.0 |
| Published | 2017-12-02 |
| First published | 2016-10-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | cap32 |
| Maintainers | cap32 |
| Keywords | fetch, xhr, http, ajax, promise, request, node |

## Links

- npm: https://www.npmjs.com/package/http-ask
- Repository: https://github.com/Cap32/http-ask
- Homepage: https://github.com/Cap32/http-ask#readme
- Issues: https://github.com/Cap32/http-ask/issues
- npm.io page: https://npm.io/package/http-ask

## Dependencies (3)

- [url-join](https://npm.io/package/url-join.md) ^1.1.0
- [object-assign](https://npm.io/package/object-assign.md) ^4.1.0
- [isomorphic-fetch](https://npm.io/package/isomorphic-fetch.md) ^2.2.1

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 0.0.0 (latest) — 2017-12-02
- 0.0.0-rc6 — 2017-05-25
- 0.0.0-rc5 — 2017-05-25
- 0.0.0-rc4 — 2017-04-21
- 0.0.0-rc3 — 2017-04-21
- 0.0.0-rc2 — 2017-03-08
- 0.0.0-rc1 — 2017-01-02
- 0.0.0-alpha.3 — 2016-11-23
- 0.0.0-alpha.2 — 2016-11-10
- 0.0.0-alpha.1 — 2016-10-24

## README

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

[![Build Status](https://travis-ci.org/Cap32/http-ask.svg?branch=master)](https://travis-ci.org/Cap32/http-ask) [![http-ask code style](https://img.shields.io/badge/code_style-http--ask-brightgreen.svg)](https://github.com/Cap32/http-ask) [![npm version](https://badge.fury.io/js/http-ask.svg)](https://badge.fury.io/js/http-ask)

## Features

- Cloneable and combinable request config
- Support Node.js and browser
- Promise/A+ based
- Chainable API
- Cancelable
- Support timeout

## Installing

Using npm:

```bash
$ npm install http-ask
```

Using yarn:

```bash
$ yarn add http-ask
```

## Usage

Basic `GET` request

```js
// 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`

```js
// 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`

```js
// 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

```js
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

```js

// 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](https://developer.mozilla.org/en-US/docs/Web/API/GlobalFetch/fetch)

##### Return

(Object): `ask` instance.

##### Example
```js
// 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`] (String): Request URL.

##### Return

(Object): `ask` instance.

---

#### Method: ask#post([url])

Set `POST` method and url.

##### Arguments

1. [`url`] (String): Request URL.

##### Return

(Object): `ask` instance.

---

#### Method: ask#put([url])

Set `PUT` method and url.

##### Arguments

1. [`url`] (String): Request URL.

##### Return

(Object): `ask` instance.

---

#### Method: ask#patch([url])

Set `PATCH` method and url.

##### Arguments

1. [`url`] (String): Request URL.

##### Return

(Object): `ask` instance.

---

#### Method: ask#delete([url])

Set `DELETE` method and url.

##### Arguments

1. [`url`] (String): 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
```js
// `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
```js
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
```js
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

```js
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

```js
const ask = new Ask('http://localhost/');
ask.exec().then((data) => {
	console.log('response data', data);
	console.log('response status', ask.response.status);
});
```

---

## License

MIT

---
_Source: https://npm.io/package/http-ask · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._