Promise-based HTTP/HTTPS Client

1.0.3 · maintenance · verified Wed Apr 22

http-request-plus is a lightweight, promise-oriented, and stream-capable wrapper around Node.js's built-in `http` and `https` modules. Designed for Node.js environments (requiring `node >=14.18`), it offers a minimalistic API for making network requests, handling redirects, and processing responses as buffers, text, or JSON. The current stable version is 1.0.3, with updates appearing infrequently, suggesting a maintenance-focused cadence rather than active feature development. Its key differentiator is being a thin abstraction directly over native Node.js HTTP capabilities, providing fine-grained control and stream processing without the overhead of more feature-rich alternatives like `axios` or `node-fetch`, while still offering promise-based convenience.

Common errors

```
FATAL: Error: getaddrinfo ENOTFOUND nonexistent-domain-12345.com
```
cause This error indicates that the domain name could not be resolved. This is a network-level error, typically due to a typo in the hostname or the domain simply not existing.

fix Double-check the URL for typos. Ensure your network connection is active and that the DNS server can resolve the domain.
```
FATAL: Error: Request aborted
```
cause The request was aborted, often due to a timeout or an explicit `AbortSignal` being triggered before the response was fully received.

fix Increase the `timeout` option in the request configuration if the server is slow to respond, or ensure your `AbortSignal` logic is correct and not prematurely aborting requests. Check server logs for long processing times.
```
TypeError: response.json is not a function
```
cause This error occurs when you forget to `await` the `httpRequestPlus` call, meaning `response` is still a Promise, not the actual response object.

fix Ensure you `await` the `httpRequestPlus` call: `const response = await httpRequestPlus(url);`.
```
FATAL: Error: Response status code 404
```
cause By default, `http-request-plus` throws an `Error` object when the HTTP response status code is 4xx or 5xx.

fix If you want to handle 4xx/5xx status codes without throwing, set `bypassStatusCheck: true` in your request options: `httpRequestPlus(url, { bypassStatusCheck: true })`. Then, manually check `response.statusCode`.

Warnings

gotcha By default, `http-request-plus` throws an error for any response with a status code outside the 2xx range. This can be unexpected for users accustomed to libraries that require explicit status code checking.
Fix: To prevent throwing on non-2xx status codes, set the `bypassStatusCheck` option to `true` in the request configuration: `httpRequestPlus(url, { bypassStatusCheck: true })`.
gotcha Error handling for timeouts and network issues (e.g., DNS resolution failures) must be done via a `catch` block on the promise returned by `httpRequestPlus`. Additionally, errors after the response is received (like a streaming body error) are emitted as `error` events on the `response` object itself.
Fix: Always wrap `httpRequestPlus` calls in a `try...catch` block or chain a `.catch()` method to handle initial request errors. For stream-related errors, attach an `'error'` event listener to the `response` object: `response.on('error', (err) => console.error('Response stream error:', err));`
gotcha The package currently uses the `master` branch as its primary development line on GitHub. While not inherently problematic, this naming convention is deprecated in many open-source projects, which now favor `main`.
Fix: No direct fix for consumers, but be aware when contributing or referencing repository branches.

Install

npm install http-request-plus npm
yarn add http-request-plus yarn
pnpm add http-request-plus pnpm

Imports

httpRequestPlus
wrong:
```
import { httpRequestPlus } from 'http-request-plus';
```
correct:
```
import httpRequestPlus from 'http-request-plus';
```
The library exports a default function for making requests. There are no named exports for the core request functionality.
CommonJS require
```
const httpRequestPlus = require('http-request-plus');
```
For CommonJS environments, use `require` to import the default exported function.

Quickstart

This quickstart demonstrates how to make a GET request, handle potential network errors or non-2xx status codes, and retrieve the response body as text. It includes basic error handling and an example of setting headers and a timeout.

import httpRequestPlus from 'http-request-plus';

async function fetchData(url) {
  try {
    // Makes a GET request to the specified URL.
    // By default, throws an error for non-2xx status codes.
    // Options for `maxRedirects` and `bypassStatusCheck` are available.
    const response = await httpRequestPlus(url, {
      // Example of adding a custom header
      headers: {
        'User-Agent': 'http-request-plus-example/1.0'
      },
      // Timeout after 5 seconds
      timeout: 5000
    });

    if (response.statusCode >= 400) {
      console.error(`Received status code ${response.statusCode}: ${response.statusMessage}`);
      return;
    }

    // Access the response body as plain text
    const data = await response.text();
    console.log(`Successfully fetched ${url}:\n`, data.substring(0, 200) + '...'); // Log first 200 chars

  } catch (error) {
    // Catches network errors, timeouts, and non-2xx status codes (by default)
    console.error(`Error fetching ${url}:`, error.message);
    if (error.code) {
      console.error(`Error code: ${error.code}`);
    }
  }
}

fetchData('http://example.com');
// fetchData('http://nonexistent-domain-12345.com'); // Uncomment to test connection error
// fetchData('http://httpbin.org/status/404'); // Uncomment to test 404 status (will throw by default)

view raw JSON →