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

Async HTTP client for NodeJS. Supports HTTPS, basic authentication, proxied requests, multipart form uploads and gzip/deflate compression. Really simple stuff, around ~250 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: (error, response, body)

Options

• timeout: Returns error if response takes more than X. Defaults to 10000 (10 secs).
• compressed: Whether to ask for a deflated or gzipped response or not. Defaults to false.
• parse: Whether to parse XML or JSON response bodies automagically. Defaults to true.
• multipart: Enables multipart/form-data encoding. Defaults to false.
• username: For HTTP basic auth.
• password: For HTTP basic auth. Requires username to be passed, obviously.
• agent: Uses an http.Agent of your choice, instead of the global (default) one.
• proxy: Sends request via HTTP proxy. Eg. proxy: 'http://proxy.server.com:3128'

Examples

Simple GET.

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

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

});

You can also skip the 'http://' part if you want, by the way.

HTTPS + querystring

client.get('https://www.google.com/search?q=syd+barrett', function(err, resp, body){

  // boom! works.

});

GET with options

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

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

  // used HTTP auth

});

GET through proxy

client.get('http://search.npmjs.org', { proxy: 'http://localhost:1234' }, function(err, resp, body){

  // request passed through proxy

});

POST/PUT

client.post('https://my.app.com/endpoint', 'foo=bar', function(err, resp, body){

  // you can pass params as a string or as an object

});

POST/PUT 2

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

client.put('https://api.app.com/v2', data, function(err, resp, body){

  // if you don't pass any data, needle will throw an exception.

});

Multipart POST: passing file path

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

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

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

  // in this case, if the request takes more than 5 seconds
  // the callback will return a [Socket closed] error

});

Multipart POST 2: passing data buffer

var buffer = fs.readFileSync('/path/to/package.zip');
var data = {
  zip_file: { buffer: buffer, filename: 'mypackage.zip', content_type: 'application/octet-stream' },
}

client.post('http://somewhere.com/over/the/rainbow', data, {multipart: true}, function(err, resp, body){

  // if you see, when using buffers we need to pass the filename for the multipart body.
  // you can also pass a filename when using the file path method, in case you want to override
  // the default filename to be received on the other end.

});

Credits

Written by Tomás Pollak, with the help of contributors.

Copyright

(c) 2012 Fork Ltd. Licensed under the MIT license.