npm package: @popovmp/client-request
Description: Client request for NodeJS
Latest version: 1.2.0

# Client-Request

A simple client request library for node.js.

It parses the body according to the content type and supports various HTTP methods.

## Installation

```bash
npm install @popovmp/client-request
```

## Features

- Support for GET, POST, PUT, HEAD requests
- Automatic content type detection and parsing
- Automatic decompression (gzip, deflate, brotli, zstd)
- JSON and form data support  
- Configurable timeouts
- TypeScript support
- No external dependencies (except for request parsing)

## API Reference

All functions accept optional headers as the last parameter. If no headers are provided, an empty object `{}` is used.

### HEAD request

`async function requestHead(url, headers?)`

```ja
import { requestHead } from '@popovmp/client-request';

const url = "https://httpbin.org/get";
const headers = {"Accept": "application/json"}; // optional

const res = await requestHead(url, headers);
console.log(res.statusCode); // 200
```

## GET request

`async function requestGet(url, headers?)`

```ja
import { requestGet } from '@popovmp/client-request';

const url     = "https://httpbin.org/get?foo=bar";
const headers = {"Accept": "application/json"}; // optional

const res = await requestGet(url, headers);
console.log(res.response.args); // { foo: 'bar' }
```

## POST request

`async function requestPost(url, data, headers?)`

```ja
import { requestPost } from '@popovmp/client-request';

const url     = "https://httpbin.org/post?foo=bar";
const body    = "Hello, World!";
const headers = {"Content-Type": "text/plain"}; // optional

const res  = await requestPost(url, body, headers);
console.log(res.response);
```

## PUT Request

`async function requestPut(url, data, headers?)`

Same as POST request but uses PUT method.

```ja
import { requestPut } from '@popovmp/client-request';

const url  = "https://httpbin.org/put";
const data = {message: "Hello, World!"};

const res = await requestPut(url, data);
console.log(res.response);
```

## POST JSON request

`async function requestJson(url, data, headers?)`

```ja
import { requestJson } from '@popovmp/client-request';

const url     = "https://httpbin.org/post?foo=bar";
const json    = {number: 42, text: "foo", list: [1, 2], object: {bar: "baz"}};
const headers = {User-Agent: "Request-Service"}; // optional

const res  = await requestJson(url, json, headers);
console.log(res.response.json); // parsed JSON response
```

## POST form URL encoded request

`async function requestForm(url, formData, headers?)`

```ja
import { requestForm } from '@popovmp/client-request';

const url     = "https://httpbin.org/post?foo=bar";
const form    = {number: 42, text: "foo", list: [1, 2]};
const headers = {User-Agent: "Request-Service"}; // optional

const res  = await requestForm(url, form, headers);
console.log(res.response.form); // parsed form data
```

## Response Format

All functions return a `ClientRequestResponse` object with the following properties:

```ja
{
  response     : any,    // Parsed response body (depends on content-type)
  headers      : object, // Response headers
  host         : string, // Request host
  method       : string, // HTTP method used
  path         : string, // Request path
  protocol     : string, // Protocol used (http: or https:)
  statusCode   : number, // HTTP status code
  statusMessage: string, // HTTP status message
}
```

## Timeout Configuration

By default, requests timeout after 30 seconds. You can customize this by adding a `Request-Timeout` header with the timeout in seconds:

```ja
const headers = {
  "Request-Timeout": "10" // 10 seconds timeout
};

const res = await requestGet(url, headers);
```

## Compression Support

The library automatically handles compressed responses from servers:

- **gzip**    - Most common compression
- **deflate** - Standard compression  
- **brotli**  - Modern compression (br)
- **zstd**    - New fast compression

Simply include the appropriate `Accept-Encoding` header:

```ja
const headers = {
  "Accept-Encoding": "gzip, deflate, br, zstd"
};

const res = await requestGet(url, headers);
// Response is automatically decompressed
```

If no `Accept-Encoding` header is provided, responses are processed as-is.

## Error Handling

The library throws errors for:

- Network connectivity issues
- Request timeouts
- Invalid URLs  
- Server errors
- Decompression failures

```ja
try {
  const res = await requestGet("https://invalid-url");
} catch (error) {
  console.error("Request failed:", error.message);
}
```