# microreq

> tiny convenience wrapper around http.request

Latest version **0.13.3** (published 2021-08-26) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install microreq
pnpm add microreq
yarn add microreq
bun add microreq
```

## 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.13.3 |
| Published | 2021-08-26 |
| First published | 2017-12-04 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.11 |
| Dependencies | 0 |
| Unpacked size | 13.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Andras |
| Maintainers | andrasq |
| Keywords | http, request, small, quick, minimal, thin, light |

## Links

- npm: https://www.npmjs.com/package/microreq
- Repository: https://github.com/andrasq/node-microreq
- Homepage: https://github.com/andrasq/node-microreq#readme
- Issues: https://github.com/andrasq/node-microreq/issues
- npm.io page: https://npm.io/package/microreq

## Alternatives

- [@oh-my-pi/pi-natives](https://npm.io/package/@oh-my-pi/pi-natives.md) — 51.8K weekly downloads
- [@capgo/capacitor-light-sensor](https://npm.io/package/@capgo/capacitor-light-sensor.md) — 3.0K weekly downloads
- [@heyhuynhgiabuu/pi-diff](https://npm.io/package/@heyhuynhgiabuu/pi-diff.md) — 492 weekly downloads
- [@lotsa/verdant-lang-asm](https://npm.io/package/@lotsa/verdant-lang-asm.md) — 38 weekly downloads
- [new-era-syntax](https://npm.io/package/new-era-syntax.md) — 20 weekly downloads

## Recent versions

- 0.13.3 (latest) — 2021-08-26
- 0.13.2 — 2021-04-03
- 0.13.1 — 2021-03-17
- 0.11.0 — 2020-08-01
- 0.9.1 — 2018-05-04
- 0.9.0 — 2017-12-04

## README

microreq
========
[![Build Status](https://api.travis-ci.com/andrasq/node-microreq.svg?branch=master)](https://travis-ci.com/andrasq/node-microreq?branch=master)
[![Coverage Status](https://coveralls.io/repos/github/andrasq/node-microreq/badge.svg?branch=master)](https://coveralls.io/github/andrasq/node-microreq?branch=master)

Extremely thin convenience wrapper around `http.request` to make it usable more like
[`request`](https://npmjs.com/package/request) but without the size, speed or cpu
overhead.  No frills, just convenience.

    var request = require('microreq');

    var req = request("https://github.com/andrasq", function(err, res, body) {
        // err is any socket error
        // res is the http response object
        // body is a buffer
    })


Api
---

### req = request( uri, [body,] callback(err, res, body) )

Make an http or https request to the given url.

`uri` can be a url string for a GET request, or an options object with settings for
`http/https.request`.  If a string, it must not be `''` empty.  If an object, it can
have a property `url` with the url string to call.  Properties read from the url string
(`protocol`, `host`, `path`, and possibly `port`) override properties in `uri`.
To specify the all-defaults webpage "GET http://localhost:80/", use the empty uri `{}`.

`body` is optional, if provided it will be sent in the request as the payload.  If not
provided, `req.write()` will not be called.  Strings and Buffers are sent as-is, all
else is JSON encoded first.

`request` returns the `req` request object, and calls the callback.  `callback` will
receive any emitted error, the response object, and the gathered response body in a
Buffer.  The exact behavior can be tuned with the `noResListen` and `noReqEnd` options.

Options that control the behavior of `microreq` (all other options are passed to `http`):

- `url` - web address string to call to.  If provided, it must not be the empty string `''`.
- `body` - body to send, if any.  A body passed as a function argument takes precedence.
- `noReqEnd` - do not call `req.end()` after writing the body, let the caller append
     more data.  This also sends a `Transfer-Encoding: chunked` request header.
     The caller is reponsible for calling `req.end` to launch the call.
- `noResListen` - return as soon as the response header arrives, let the caller listen
    for the `res` `'data'` and `'end'` events
- `encoding` - if set, how to decode the response.  The default is to return the raw
    received bytes in a Buffer.  The usual toString() encodings can be specified, and
    also `'json'` to JSON.parse the response and return the decoded object (or the
    utf8 response string if unable to parse).
- `auth` - http Basic auth credentials as either a colon-separated `username:password`
    string, or a `{username: <login>, password: <passwd>}` object.  The credentials
    are used to generate an `Authorization: Basic <base64>` header.  Default no auth.
- `maxRedirects` - how many 30x redirects to follow by replaying the request against the
    redirected-to location.  This is very simplistic, so use advisedly.  Default `0`,
    to not follow redirects.  Enable by setting to a positive number e.g. `10`.

### caller = request.defaults( options )

Build an request caller with the options wired in and a method `request` to make web
requests and `defaults` to build callers with inherited configs.  Also provides convenience
methods `get`, `put`, `post`, `head`, `patch` and `del` that specify the method.
All the call methods ultimately invoke `microreq.request`.

#### caller.request( uri, [body,] callback )

#### caller.get( uri, [body,] callback )

Same as specifying `{method: 'GET'}` in the `uri` of `caller.request(uri)`.

#### caller.defaults( options )

It is possible to build new callers that inherit defaults from their builder.


Change Log
----------

- **0.13.3** - fix relative-path redirects
- **0.13.2** - fix baseUrl concatenation, fix defaults() baseUrl handling
- **0.13.1** - `maxRedirects` option
- **0.12.0** - `defaults` method, `auth` option
- **0.11.1** - emit timeout errors if noResListen, faster req launch
- **0.11.0** - `timeout` option, depend on qmock
- **0.10.0** - `encoding` option supporting json, faster body decoding, guard against multiple callbacks


Todo
----


Related Work
------------

- [`http`](https://nodejs.org/dist/latest/docs/api/http.html) - nodejs http
- [`khttp`](https://github.com/andrasq/node-k-http) - fast mini request
- [`qhttp`](https://npmjs.com/package/qhttp) - fast http convenience utils
- [`request`](https://npmjs.com/package/request) - old featureful request

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