http-basic

8.1.3 verified Sat Apr 25 auth: no javascript

Low-level wrapper around Node.js http.request/https.request with built-in support for gzip/deflate, redirects, caching (memory/file), retries, and timeouts. Version 8.1.3 requires Node >=6.0.0. Includes TypeScript type definitions. Unlike higher-level libraries like `got` or `node-fetch`, this package provides a minimal, callback-based API that exposes raw streams and does not handle JSON parsing or body collection. The cache system supports Etag/Last-Modified validation and custom matchers. Maintained as a stable base for other packages.

Common errors

error TypeError: Cannot read property 'statusCode' of undefined ↓

cause Callback not called due to request not being ended or network error not handled.

fix

Ensure you call req.end() on the returned stream. Check for err in callback.

error Error: write after end ↓

cause Attempting to write to the request stream after calling .end().

fix

Write all body data before calling .end(). Use .once('finish', ...) to know when the request completes.

error RequestError: Invalid URI ↓

cause URL is malformed or not fully qualified (must start with http:// or https://).

fix

Pass a valid URL string starting with http:// or https://, e.g., 'http://example.com'.

error TypeError: request is not a function ↓

cause import instead of require (package is CJS only).

fix

Use const request = require('http-basic');

Warnings

breaking In v8.0.0, the callback signature changed to (err, res) from (err, res, body). Body is no longer collected; you must handle the stream. ↓

fix Use res.body to read the stream instead of relying on a third callback argument.

deprecated The 'cache' option with value 'memory' or 'file' uses bundled cache implementations that are deprecated in favor of custom cache objects implementing the ICache interface. ↓

fix Pass a custom cache object with get(url) and set(url, response) methods.

gotcha Calling request() returns a WritableStream, but must still call .end() to send the request even if no body is written. ↓

fix Always call .end() on the returned stream to complete the request.

breaking In v7.0.0, the default value for the 'duplex' option changed. GET/HEAD/OPTIONS now default duplex: false, others default true. ↓

fix Explicitly set duplex: true if you want to send a body with methods that normally don't have one.

gotcha The request stream must be ended synchronously. If you attach data handlers to the returned stream, you must call .end() synchronously after the handler. ↓

fix Write any body data before calling .end() and avoid async operations between creating the request and ending it.

deprecated You can no longer pass a string URL with query parameters; the library does not encode them. Use the URL constructor instead. ↓

fix Use new URL('http://example.com?key=value').href to ensure proper encoding.

Install

npm install http-basic

yarn add http-basic

pnpm add http-basic

Imports

request

wrong

import request from 'http-basic';

correct

const request = require('http-basic');

Package does not export ESM. Only CommonJS via require().

HttpRequestOptions
```
import type { HttpRequestOptions } from 'http-basic';
```
TypeScript type import for options object. Available from v8.0.0+.
Response
wrong
```
import { Response } from 'http-basic';
```
correct
```
import type { Response } from 'http-response-object';
```
Response type is re-exported by http-basic, but the canonical source is 'http-response-object'. Prefer importing from the latter for stability.

Quickstart

Simple GET request with gzip and redirect handling, streaming response body.

const request = require('http-basic');

request('GET', 'http://example.com', { followRedirects: true, gzip: true }, function (err, res) {
  if (err) {
    console.error('Request failed:', err);
    return;
  }
  console.log('Status:', res.statusCode);
  // Stream the body to stdout
  res.body.pipe(process.stdout);
});