# client-request

> A zero-dependency stripped-down http client request module based on the http://npm.im/request API

Latest version **2.3.0** (published 2017-10-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install client-request
pnpm add client-request
yarn add client-request
bun add client-request
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.3.0 |
| Published | 2017-10-05 |
| First published | 2015-05-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Bryce B. Baril |
| Maintainers | bryce |
| Keywords | request, http, client, https |

## Links

- npm: https://www.npmjs.com/package/client-request
- Repository: https://github.com/brycebaril/client-request
- Issues: https://github.com/brycebaril/client-request/issues
- npm.io page: https://npm.io/package/client-request

## 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

- 2.3.0 (latest) — 2017-10-05
- 2.2.0 — 2017-08-10
- 2.1.0 — 2017-08-09
- 2.0.0 — 2017-04-06
- 1.2.2 — 2017-04-05
- 1.2.1 — 2017-03-31
- 1.2.0 — 2016-11-16
- 1.1.0 — 2016-09-22
- 1.0.1 — 2015-06-16
- 1.0.0 — 2015-05-24

## README

client-request
=====

[![NPM](https://nodei.co/npm/client-request.png)](https://nodei.co/npm/client-request/)

Sometimes you want to use a library that uses the (great!!) [request](http://npm.im/request) library but you can't have all those dependencies.

This library is a a very narrow subset of the common simpler uses of `request` that can be substituted for `request` without too much effort.

For the small subset of the `request` interface it implements, it is **super opinionated** and leaves any fancier features to you.

Just to be clear, this module **does not even try** to implement most of the features of `request`.

Things it does support from the `request` API:
* **Only** this call form: `var req = request(options, callback)`
* automatic selection of `http` or `https` based on the uri
* options.timeout
* options.json

If you want...
* `request.form` -- use [form-urlencoded](https://www.npmjs.com/package/form-urlencoded), a zero-deps form body encoder. (example below)
* `options.qs` -- use the core `querystring` library or [qs](http://npm.im/qs) and append the querystring to your url path prior to sending it to request
* anything else ... find a module and suggest it here!


```javascript
var request = require("client-request")

var options = {
  uri: "http://brycebaril.com",
  method: "POST",
  body: {blah: "some stuff"},
  timeout: 100,
  json: true
}

var req = request(options, function callback(err, response, body) {
  console.log(response.statusCode)
  if (body) {
    console.log(body)
  }
})

```

```javascript
var requestPromise = require("client-request/promise")

requestPromise(options).then(function (result) {
  if (result.response.statusCode === 201) {
    console.log(result.response.headers.location)
  } else {
    console.log(result.body)
  }
}).catch(err){
  console.log(err)
})
```

```javascript
var requestPromise = require("client-request/promise")

// ONLY in ES2016 and later, you can await a promise in an async function (generator)
async function(){
  try {
    let result = await requestPromise(options)
    console.log(result.response.headers.location)
  } catch (err) {
    console.log(err)
  }
}
```

WHY DID I MAKE THIS?
===

`request`
```
bryce@x1c:~/forks/request$ browserify --bare index.js -o bundle.js && wc -c bundle.js
741099 bundle.js
```

`client-request`
```
bryce@x1c:~/forks/client-request$ browserify --bare request.js -o bundle.js && wc -c bundle.js
6159 bundle.js
```

API
===

`var req = require("client-request")(options, callback)`
---

Perform a client request. Returned value is the core `http` request object.

The `callback` is executed with three arguments `callback(err, response, body)`
* err: any error when attempting to make the request, timeouts, or parse errors
* response: the core http Response object
* body: the `Buffer` returned by the server, or if `options.json` is used, the object the server's body deserializes into.

Options:
* `uri` -- a full uri, e.g. "https://example.com:9090/path?query=args"
* `method` -- GET, POST, PUT, etc. (Default GET)
* (generally similar to the core `http.request` options)
* `json` -- attempt to JSON.parse the response body and return the parsed object (or an error if it doesn't parse)
* `timeout` -- a timeout in ms for the client to abort the request
* `body` -- the raw body to send to the server (e.g. PUT or POST) -- if `body` is a string/buffer, it will send that, if `body` quacks like a stream, stream it, otherwise it will send it JSON serialized.
* `stream` -- if `true` callback will return raw `http.ServerResponse` stream. Stream error handling will be up to you.

Extensions
===

Forms
---

I suggest [form-urlencoded](https://www.npmjs.com/package/form-urlencoded) for your form needs.

Code with [request](http://npm.im/request):
```js
var request = require("request")

var form = {
  alice: "hi bob",
  bob: "hi alice"
}
var options = {
  uri: "https://mysite.example",
  form: form,
  method: "PUT",
}

var req = request(options, function callback(err, response) {
  // ...
})
```

Converted to use `client-request`:

```js
var request = require("request-client")
var encodeForm = require("form-urlencoded").encode

var form = {
  alice: "hi bob",
  bob: "hi alice"
}
var options = {
  uri: "https://mysite.example",
  body: encodeForm(form),
  method: "PUT",
  headers: {
    "content-type": "application/x-www-form-urlencoded"   // setting headers is up to *you*
  }
}

var req = request(options, function callback(err, response, body) {
  // ...
})
```

Querystrings
---

If it works for you, the core `querystring` module is a great way to avoid additional dependencies.

Code with request:
```js
var request = require("request")

var qs = {
  q: "what?",
  page: 99
}
var options = {
  uri: "https://mysite.example",
  qs: qs
}

var req = request(options, function callback(err, response, body) {
  // ...
})
```

```js
var request = require("request-client")
var encodeQuery = require("querystring").encode

var qs = {
  q: "what?",
  page: 99
}
var options = {
  uri: "https://mysite.example" + "?" + encodeQuery(qs)
}

var req = request(options, function callback(err, response, body) {
  // ...
})
```

LICENSE
=======

MIT

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