handy-http

1.0.2 verified Sat Apr 25 auth: no javascript maintenance

Simple wrapper for native NodeJS http[s].request providing a flexible interface for making HTTP/HTTPS requests. Stable version 1.0.2. Lightweight copy-paste reducer supporting various data types (plain objects, Buffer, ReadableStream), multipart file uploads, proxy requests, and automatic JSON parsing. Keeps access to native NodeJS http.ClientRequest events. Less feature-rich than axios or request but minimal and dependency-free.

Common errors

error TypeError: HTTPClient is not a constructor ↓

cause Forgetting 'new' when instantiating HTTPClient.

fix

Use 'new HTTPClient()' or 'new (require('handy-http'))()'.

error Unhandled 'error' event ↓

cause No error callback provided; request fails silently.

fix

Pass a callback function with two parameters: (err, res).

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

cause client.open returns undefined if not called correctly (e.g., wrong arguments).

fix

Ensure first argument is a string URL or options object, second is callback.

Warnings

gotcha Callback receives error first (Node.js convention). ↓

fix Always check first argument for error before using response.

gotcha Must use 'new' keyword when instantiating HTTPClient. Forgetting 'new' may cause errors or unexpected behavior. ↓

fix Always do: var client = new HTTPClient();

gotcha Data as Buffer or Stream sends raw binary without content-type; caller must set appropriate headers. ↓

fix Set 'content-type' header explicitly when sending Buffer/Stream.

gotcha Multipart upload requires files array and headers['content-type'] = 'multipart/form-data'. If not set, data won't be multipart. ↓

fix Explicitly set headers.content-type to 'multipart/form-data' when using files.

gotcha Proxy support is basic; no authentication or HTTPS proxy handling. ↓

fix Use a more feature-rich library like 'request' or 'axios' for advanced proxy needs.

Install

npm install handy-http

yarn add handy-http

pnpm add handy-http

Imports

HTTPClient

wrong

var client = new require('handy-http')();

correct

var HTTPClient = require('handy-http');
var client = new HTTPClient();

CommonJS only. Must instantiate with 'new'.

client.open

wrong

client.open('http://example.com', {}, callback);

correct

client.open({ url: 'http://example.com', method: 'POST', data: { key: 'value' } }, callback);

Second argument is callback, not options. Options go in first argument as object or URL string.

request object

wrong

client.open({ url: '...' }, callback).on('socket', ...);

correct

var request = client.open({ url: '...' }, callback);
request.on('socket', function(socket) { /* ... */ });

client.open returns the native NodeJS http.ClientRequest object; can attach event listeners.

Quickstart

Shows GET and POST requests with error handling using handy-http. Demonstrates simple URL string and options object usage.

var HTTPClient = require('handy-http');
var client = new HTTPClient();

// Simple GET request
client.open('http://jsonplaceholder.typicode.com/posts/1', function(err, res) {
  if (err) { console.error(err); return; }
  console.log('Response:', res);
});

// POST request with data
client.open({
  url: 'http://jsonplaceholder.typicode.com/posts',
  method: 'POST',
  data: { title: 'foo', body: 'bar', userId: 1 }
}, function(err, res) {
  if (err) { console.error(err); return; }
  console.log('Created:', res);
});