needle

What is needle?

The needle npm package is a minimalistic HTTP client for Node.js, designed for simplicity and ease of use. It provides a straightforward interface for making HTTP requests and handling responses, supporting both callbacks and streams. It is lightweight and has built-in support for multipart form-data, which makes it suitable for file uploads and other form-related tasks.

What are needle's main functionalities?

Making HTTP GET requests

This feature allows you to perform HTTP GET requests to retrieve data from a specified URL. The callback function receives an error object and the response object, which includes the status code and the response body.

const needle = require('needle');

needle.get('https://api.example.com', (error, response) => {
  if (!error && response.statusCode == 200)
    console.log(response.body);
});

Making HTTP POST requests

This feature is used to send HTTP POST requests with data to a specified URL. The data can be an object, which needle will automatically encode as application/x-www-form-urlencoded or multipart/form-data, depending on the content.

const needle = require('needle');

const data = { foo: 'bar' };
needle.post('https://api.example.com', data, (error, response) => {
  if (!error && response.statusCode == 200)
    console.log(response.body);
});

Streaming support

Needle supports streaming, which allows you to pipe the response stream to another stream, such as a file write stream. This is useful for handling large amounts of data or streaming file downloads.

const needle = require('needle');
const fs = require('fs');

const stream = needle.get('https://api.example.com/stream');
stream.pipe(fs.createWriteStream('output.txt'));

Handling multipart form-data

Needle can handle multipart form-data, which is often used for file uploads. The data object can include file buffers, streams, or paths, and needle will handle the multipart encoding for you.

const needle = require('needle');

const data = {
  file: { file: 'path/to/file.jpg', content_type: 'image/jpeg' },
  other_field: 'value'
};

needle.post('https://api.example.com/upload', data, { multipart: true }, (error, response) => {
  if (!error && response.statusCode == 200)
    console.log('Upload successful');
});

Other packages similar to needle

axios

Axios is a promise-based HTTP client for the browser and Node.js. It provides a rich set of features like interceptors, automatic JSON data transformation, and cancellation. Compared to needle, axios is more feature-rich and has a larger footprint.

request

Request is a simplified HTTP request client that offers a wide range of features including OAuth signing, form uploads, and cookies. It is more complex and heavier than needle but has been deprecated as of 2020.

got

Got is a human-friendly and powerful HTTP request library for Node.js. It supports promises and async/await, streams, retries, and more. Got is more comprehensive than needle and is designed to be a more modern alternative with a focus on simplicity and composability.

node-fetch

Node-fetch is a light-weight module that brings the Fetch API to Node.js. It is a minimal and straightforward API that closely mirrors the browser's fetch API. Compared to needle, node-fetch is more aligned with web standards.

superagent

Superagent is a small progressive client-side HTTP request library, and Node.js module with the same API, sporting many high-level HTTP client features. It is more expressive than needle and includes features like a fluent API, chaining, and more.

README

Needle

HTTP client for node. Supports HTTP basic auth, nested params and multipart form uploads. Really simple stuff, around 200 lines of code.

Usage

var client = require('needle');

client.get(url, [options], callback)
client.post(url, [data], [options], callback)
client.put(url, [data], [options], callback)
client.delete(url, [options], callback)

callback receives three arguments: (err, response, body)

Options

• timeout: Returns err if response takes more than X. Defaults to 10000 (10 secs).
• multipart: Enables multipart/form-data encoding. Defaults to false.
• username: For http auth.
• password: For http auth. Both are required of course.
• parse: Whether to parse XML or JSON response bodies automagically. Defaults to true.

Examples

Simple GET.

var client = require('needle');

client.get('http://www.google.com', function(err, resp, body){

  console.log("Got status code: " + resp.statusCode);

});

GET with options

var options = {
  username: 'you',
  password: 'secret',
  headers: {
    'X-Secret-Header': "Even more secret text"
  }
}

client.get('http://api.server.com', options, function(err, resp, body){

  // used HTTP auth

});

POST/PUT

var data = {
  foo: 'bar',
  nested: {
    params: {
      are: {
        also: 'possible'
      }
    }
  }
}

client.post('http://my.app.com', data, function(err, resp, body){

  // yay

});

Multipart POST

var data = {
  foo: bar,
  image: { file: '/home/tomas/linux.png', content_type: 'image/png' }
}

var options = {
  multipart: true,
  timeout: 10000
}

client.post('http://my.other.app.com', data, options, function(err, resp, body){

  // in this case, if the request takes more than 10 seconds
  // the callback will return an error

});

Credits

Written by Tomás Pollak.

Legal

(c) Copyright 2011 Fork Ltd. Licensed under the MIT license.