request-compose

What is request-compose?

The request-compose npm package is a versatile tool for making HTTP requests and composing them in a functional manner. It allows for chaining requests, handling responses, and managing errors in a streamlined way.

What are request-compose's main functionalities?

Making HTTP Requests

This feature allows you to make HTTP requests using a simple and intuitive API. The example demonstrates how to make a GET request to an API endpoint and log the response body.

const { compose } = require('request-compose');
const { Request } = compose;

(async () => {
  const { res, body } = await Request({
    url: 'https://jsonplaceholder.typicode.com/posts/1',
    method: 'GET'
  });
  console.log(body);
})();

Chaining Requests

This feature allows you to chain multiple HTTP requests together. The example demonstrates making a GET request followed by a POST request, showing how to handle multiple requests in sequence.

const { compose } = require('request-compose');
const { Request } = compose;

(async () => {
  const { res: res1, body: body1 } = await Request({
    url: 'https://jsonplaceholder.typicode.com/posts/1',
    method: 'GET'
  });
  const { res: res2, body: body2 } = await Request({
    url: 'https://jsonplaceholder.typicode.com/posts',
    method: 'POST',
    body: { title: 'foo', body: 'bar', userId: 1 },
    json: true
  });
  console.log(body2);
})();

Error Handling

This feature provides robust error handling for HTTP requests. The example demonstrates how to catch and handle errors when a request fails.

const { compose } = require('request-compose');
const { Request } = compose;

(async () => {
  try {
    const { res, body } = await Request({
      url: 'https://jsonplaceholder.typicode.com/invalid-url',
      method: 'GET'
    });
    console.log(body);
  } catch (error) {
    console.error('Request failed:', error.message);
  }
})();

Other packages similar to request-compose

axios

Axios is a popular promise-based HTTP client for the browser and Node.js. It provides a simple API for making HTTP requests and supports features like interceptors, request cancellation, and automatic JSON transformation. Compared to request-compose, Axios is more widely used and has a larger community, but it may not offer the same level of composability.

node-fetch

Node-fetch is a lightweight module that brings the Fetch API to Node.js. It is minimalistic and focuses on providing a fetch-like interface for making HTTP requests. While it is simpler and more lightweight than request-compose, it lacks the advanced composability and chaining features.

superagent

Superagent is a small, progressive client-side HTTP request library that also works in Node.js. It provides a flexible API for making HTTP requests and supports features like query string parsing, form submissions, and file uploads. Superagent is more feature-rich than node-fetch but may not offer the same level of composability as request-compose.

README

request-compose

Composable HTTP Client

var compose = require('request-compose')
var Request = compose.Request
var Response = compose.Response

;(async () => {
  try {
    var {res, body} = await compose(
      Request.defaults({headers: {'user-agent': 'request-compose'}}),
      Request.url('https://api.github.com/users/simov'),
      Request.send(),
      Response.buffer(),
      Response.string(),
      Response.parse(),
    )()
    console.log(res.statusCode, res.statusMessage)
    console.log(res.headers['x-ratelimit-remaining'])
    console.log(body)
  }
  catch (err) {
    console.error(err)
  }
})()

Goals

• No dependencies
• No abstraction
• No state

Table of Contents

• Compose
• Bundled Middlewares
• Opinionated Client
  • client
  • buffer
  • stream
  • options
• Errors
• Debug Logs
• Examples

Compose

In computer science, function composition (not to be confused with object composition) is an act or mechanism to combine simple functions to build more complicated ones. Like the usual composition of functions in mathematics, the result of each function is passed as the argument of the next, and the result of the last one is the result of the whole.

source: Wikipedia

var compose = require('request-compose')

Accepts a list of functions to execute and returns a Promise:

var doit = compose(
  (a) => a + 2,
  (a) => a * 2,
)

Then we can call it:

var result = await doit(5) // 14

A more practical example however would be to compose our own HTTP client:

var compose = require('request-compose')
var https = require('https')

var request = compose(
  (options) => {
    options.headers = options.headers || {}
    options.headers['user-agent'] = 'request-compose'
    return options
  },
  (options) => new Promise((resolve, reject) => {
    https.request(options)
      .on('response', resolve)
      .on('error', reject)
      .end()
  }),
  async (res) => await new Promise((resolve, reject) => {
    var body = ''
    res
      .on('data', (chunk) => body += chunk)
      .on('end', () => resolve({res, body}))
      .on('error', reject)
  }),
  ({res, body}) => ({res, body: JSON.parse(body)}),
)

Then we can use it like this:

;(async () => {
  try {
    var {res, body} = await request({
      protocol: 'https:',
      hostname: 'api.github.com',
      path: '/users/simov',
    })
    console.log(res.statusCode, res.statusMessage)
    console.log(res.headers['x-ratelimit-remaining'])
    console.log(body)
  }
  catch (err) {
    console.error(err)
  }
})()

Bundled Middlewares

request-compose comes with a bunch of pre-defined middlewares for transforming the request and the response:

var compose = require('request-compose')
var Request = compose.Request
var Response = compose.Response

We can use these middlewares to compose our own HTTP client:

;(async () => {
  try {
    var {res, body} = await compose(
      Request.defaults({headers: {'user-agent': 'request-compose'}}),
      Request.url('https://api.github.com/users/simov'),
      Request.send(),
      Response.buffer(),
      Response.string(),
      Response.parse(),
    )()
    console.log(res.statusCode, res.statusMessage)
    console.log(res.headers['x-ratelimit-remaining'])
    console.log(body)
  }
  catch (err) {
    console.error(err)
  }
})()

Opinionated Client

request-compose comes with opinionated HTTP client that is composed of the above middlewares.

There are 3 types of composition available based on the returned data type:

client

var request = require('request-compose').client
var {res, body} = await request({options})

The client composition parses the response body to string using utf8 encoding by default. Additonally it tries to parse JSON and Querystring response bodies with valid content-type.

buffer

var request = require('request-compose').buffer
var {res, body} = await request({options})

The buffer composition returns the response body as raw Buffer.

stream

var request = require('request-compose').stream
var {res} = await request({options})

The stream composition returns the response Stream.

options

The above compositions accept any of the Node's http.request and https.request options:

var {res, body} = await request({
  method: 'GET',
  url: 'https://api.github.com/users/simov',
  headers: {
    'user-agent': 'request-compose'
  }
})

Additionally the following options are available:

Option	Type	Description
url	'string' url object	URL (encoding - see below)
qs	{object} 'string'	URL querystring (encoding - see below)
form	{object} 'string'	application/x-www-form-urlencoded request body (encoding - see below)
json	{object} 'string'	JSON encoded request body
multipart	{object} [array]	multipart request body using request-multipart, see examples
body	'string' Buffer Stream	request body
auth	{user, pass}	Basic authorization
oauth	{object}	OAuth authorization using request-oauth, see examples
encoding	'string'	response body encoding (default: 'utf8')
cookie	{object}	cookie store using request-cookie, see examples
redirect	{object}	see below

Querystring set in the url, and/or in qs and/or in form as 'string' is left untouched, meaning that the proper encoding is left to the user.

When qs and/or form is {object} the querystring is encoded using the Node's querystring module which mirrors the global encodeURIComponent method. Additionally all reserved characters according to RFC3986 are encoded as well. Full list of all reserved characters that are being encoded can be found here.

redirect

Option	Default	Description
max	3	maximum number of redirects to follow
all	false	follow non-GET HTTP 3xx responses as redirects
method	true	follow original HTTP method, otherwise convert all redirects to GET
auth	true	keep Authorization header when changing hostnames
referer	false	add Referer header

Errors

Non 200/300 responses are returned as Error object with the following properties:

• message - status code + status message
• res - the response object
• body - the parsed response body
• raw - the raw response body

Debug Logs

Fancy request-logs:

npm i --save-dev request-logs

Pick any of the following debug options:

DEBUG=req,res,body,json,nocolor node app.js

Examples

Topic	Example
Types of lambda functions	Get GitHub user profile
Bundled middlewares	Get GitHub user profile
Client composition	Get GitHub user profile
Buffer composition	Decoding response body using iconv-lite
Stream composition	Stream Tweets
OAuth middleware	Get Twitter User Profile
Multipart middleware	Upload photo to Twitter
Override bundled middleware - process-wide	Override the form and the parse middlewares to use the qs module
Override bundled middleware - per compose instance	Override the qs middleware
Stream request body	Upload file to Dropbox
HTTP stream	Upload image from Dropbox to Slack
HTTP stream	Copy file from Dropbox to GDrive
Login using cookies	Login to Wallhaven.cc
Pipeline	Slack Weather Status

Changelog

v0.0.19 (2018/07/10)

• Last development release