# smol-request

> Tiny http/https request wrapper for Node.js 10 and newer

Latest version **2.1.2** (published 2022-06-03) · MIT license · 0 weekly downloads

## Install

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

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.2 |
| Published | 2022-06-03 |
| First published | 2020-11-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=10.20 |
| Dependencies | 0 |
| Unpacked size | 15.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | ejnshtein |
| Maintainers | ejnshtein |
| Keywords | nodejs, http, https, async, promise |

## Links

- npm: https://www.npmjs.com/package/smol-request
- Repository: https://github.com/ejnshtein/smol-request
- Homepage: https://github.com/ejnshtein/smol-request#readme
- Issues: https://github.com/ejnshtein/smol-request/issues
- npm.io page: https://npm.io/package/smol-request

## Alternatives

- [promise-throttle](https://npm.io/package/promise-throttle.md) — 44.2K weekly downloads
- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads

## Recent versions

- 2.1.2 (latest) — 2022-06-03
- 2.1.1 — 2020-12-15
- 2.1.0 — 2020-11-11
- 2.0.2 — 2020-11-08
- 2.0.1 — 2020-11-08

## README

# Smol Request

[![npm version](https://img.shields.io/npm/v/smol-request.svg?style=flat-square)](https://www.npmjs.org/package/smol-request)
[![npm downloads](https://img.shields.io/npm/smol-request.svg?style=flat-square)](http://npm-stat.com/charts.html?package=smol-request)
[![install size](https://packagephobia.now.sh/badge?p=smol-request)](https://packagephobia.now.sh/result?p=smol-request)

Small async request client for Node.js 10+ and newer with 0 dependencies.  

# Install

>npm i smol-request

## Usage

### JSON

```js
import { request }  from 'smol-request'

request('https://ghibliapi.herokuapp.com/films', { responseType: 'json' })
  .then(({ data }) => {
    console.log(`Studio Ghibli has ${response.data.length} movies out there!`)
  })
```

### Text

```js
request('https://bbc.com')
  .then(({ data }) => {
    //  bbc page is too big to log it to console, but we can save it to the drive!
    fs.promises.writeFile('./bbc.html', data)
      .then(() => {
        console.log('bbc page saved!')
      })
  })
```

### Buffer

```js
request('https://i.picsum.photos/id/1025/200/300.jpg', { responseType: 'buffer' })
  .then(({ data }) => {
    fs.promises.writeFile('./picture.jpg', data)
      .then(() => {
        console.log('picture saved!')
      })
  })
```

### Stream

```js
request('https://i.picsum.photos/id/1025/200/300.jpg', { responseType: 'stream' })
  .then(({ data }) => {
    const stream = fs.createWriteStream('./picture.jpg')

    data.pipe(stream)

    data.once('finish', () => {
      console.log('picture saved!')
    })
  })
```

### Headers

You can get only headers without parsing body from request using `responseType: 'headers'`

```js
request('https://picsum.photos/200/300', { responseType: 'headers' })
  .then(({ headers }) => {
    console.log('Picture location - ', headers.location)
  })
```

# Example

There are a few examples in `example` folder in the [repo](https://github.com/ejnshtein/smol-request/tree/master/example).

# API

`request(url[, `[options](#RequestOptions)`[, `[formData](#formData)`]]): Promise<`[Response](#RequestResult)`>`


# Types

### RequestOptions

This client uses base http/https Node.js request client, so it inherits all options from it. ([Description](https://nodejs.org/api/http.html#http_http_request_url_options_callback))

|Name|Type|Default|Description|
|-|-|-|-|
|params|`Object`|{}|URLSearchParams of request url.(Example: `{ q: 'my search query' }` becomes -> `http://myurl?q=my+search+query`)|
|responseType|`String`|`text`|One of these values: `text`, `buffer`, `json`, `stream`, `headers` |

### RequestResult

|Name|Type|Description|
|-|-|-|
|data|`ReadableStream` \| `Object` \| `String` \| `Buffer` \| `Null` | Response data with choosen type from `responseType` .|
|headers|Object| Response headers. |
|status|Number| Reponse status. |
|statusText|String| Response status text. |

### formData

If you are sending form data note that you can send form from [FormData](https://npmjs.com/package/form-data) using it's method `form.submit(path, err => {})`.
This option can be Object(then it will become string) or your custom property that will be written to request body with req.write(). ( ‾ʖ̫‾)

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