Features

• Make http and http2 requests from node.js
• Supports the Promise API
• Intercept response
• Decompress ZSTD response
• Transform request and response data
• Automatic transforms for JSON data

Installing

Package manager

Using npm:

$ npm install nexus-request

Using yarn:

$ yarn add nexus-request

Once the package is installed, you can import the library using import or require approach:

import { Nexus, NexusException } from './libs/nexusjs/src'

You can also use the default export, since the named export is a export of Nexus class instance calling rawRequest method:

import nexus from './libs/nexusjs/src'

const response = await nexus('https://httpbin.org/post', {
    method: 'post',
    http2: true,
    proxy: 'http://127.0.0.1:8080',
    setURLEncoded: false,
    response: {
        transformJson: true,
        stringifyBigInt: true,
        forceCamelCase: true,
    },
})

console.log('Response: ', response.data)

Example

Note CommonJS usage In order to gain the TypeScript typings (for intellisense / autocomplete) while using CommonJS imports with require(), use the following approach:

import { Nexus } from './libs/nexusjs/src'

const nexus = new Nexus()

// Make a request for a user with a given ID
nexus.get('/user?ID=12345')
  .then(function (response) {
    // handle success
    console.log(response)
  })
  .catch(function (error) {
    // handle error
    console.log(error)
  })
  .finally(function () {
    // always executed
  })

// Make a request for a user with a given ID (Nexus Way)
nexus.get('/user')
  .addParam('ID', 12345)
  .then(function (response) {
    // handle success
    console.log(response)
  })
  .catch(function (error) {
    // handle error
    console.log(error)
  })
  .finally(function () {
    // always executed
  })

// Optionally the request above could also be done as
nexus.get('/user', {
    params: {
      ID: 12345
    }
  })
  .then(function (response) {
    console.log(response)
  })
  .catch(function (error) {
    console.log(error)
  })
  .finally(function () {
    // always executed
  })

// Want to use async/await? Add the `async` keyword to your outer function/method.
async function getUser() {
  try {
    const response = await nexus.get('/user').addParam('ID', 12345)
    console.log(response)
  } catch (error) {
    console.error(error)
  }
}

Note async/await is part of ECMAScript 2017 and is not supported in Internet Explorer and older browsers, so use with caution.

Performing a POST request

nexus.post('/user')
  .addPost('firstName', 'Fred')
  .addPost('lastName', 'Flintstone')
  .then(function (response) {
    console.log(response)
  })
  .catch(function (error) {
    console.log(error)
  })

// Optionally the request above could also be done as
nexus.post('/user', {
    data: {
        firstName: 'Fred',
        lastName: 'Flintstone'
    }
  })
  .then(function (response) {
    console.log(response)
  })
  .catch(function (error) {
    console.log(error)
  })

Performing multiple concurrent requests

function getUserAccount() {
  return nexus.get('/user/12345')
}

function getUserPermissions() {
  return nexus.get('/user/12345/permissions')
}

Promise.all([getUserAccount(), getUserPermissions()])
  .then(function (results) {
    const acct = results[0]
    const perm = results[1]
  })

Nexus API

Requests can be made by passing the relevant config to nexus.

nexus(url, config)

// Send a POST request
import nexus from './libs/nexusjs/src'

nexus('https://httpbin.org/post', {
  method: 'post',
  data: {
    firstName: 'Fred',
    lastName: 'Flintstone'
  }
})

Creating an instance

You can create a new instance of nexus with a custom config.

nexus.create([config])

import { Nexus } from './libs/nexusjs/src'

const instance = new Nexus({
  baseURL: 'https://httpbin.org/',
  headers: {'X-Custom-Header': 'foobar'},
  response: {
    transformJson: true,
    stringifyBigInt: true,
    forceCamelCase: true,
  }
});

Instance methods

The available instance methods are listed below. The specified config will be merged with the instance config.

nexus#get(url[, config])

nexus#delete(url[, config])

nexus#post(url[, data[, config]])

nexus#put(url[, data[, config]])

Request Config

These are the available config options for making requests. Only the url is required. Requests will default to GET if method is not specified.

{
  // `url` is the server URL that will be used for the request
  url | path: '/user',

  // `method` is the request method to be used when making the request
  method: 'get', // default

  // `baseURL` will be prepended to `url` unless `url` is absolute.
  // It can be convenient to set `baseURL` for an instance of nexus to pass relative URLs
  // to methods of that instance.
  baseURL: 'https://some-domain.com/api/',

  // `transformResponse` allows changes to the response data to be made before
  // it is passed to then/catch
  responseTransformer: [function (data) {
    // Do whatever you want to transform the data

    return data;
  }],

  // `headers` are custom headers to be sent
  headers: {'X-Requested-With': 'XMLHttpRequest'},

  // `params` are the URL parameters to be sent with the request
  // Must be a plain object or a URLSearchParams object
  params: {
    ID: 12345
  },

  // `data` is the data to be sent as the request body
  // Only applicable for request methods 'PUT', 'POST', 'DELETE , and 'PATCH'
  // When no `transformRequest` is set, must be of one of the following types:
  // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
  // - Browser only: FormData, File, Blob
  // - Node only: Stream, Buffer, FormData (form-data package)
  data: {
    firstName: 'Fred'
  },

  // syntax alternative to send data into the body
  // method post
  // only the value is sent, not the key
  data: 'Country=Brasil&City=Belo Horizonte',


  // `responseEncoding` indicates encoding to use for decoding responses (Node.js only)
  // Note: Ignored for `responseType` of 'stream' or client-side requests
  encoding: 'utf8', // default

  // `proxy` defines the hostname, port, and protocol of the proxy server.
  // You can also define your proxy using the conventional `http_proxy` and
  // `https_proxy` environment variables. If you are using environment variables
  // for your proxy configuration, you can also define a `no_proxy` environment
  // variable as a comma-separated list of domains that should not be proxied.
  // Use `false` to disable proxies, ignoring environment variables.
  // `auth` indicates that HTTP Basic auth should be used to connect to the proxy, and
  // supplies credentials.
  // This will set an `Proxy-Authorization` header, overwriting any existing
  // `Proxy-Authorization` custom headers you have set using `headers`.
  // If the proxy server uses HTTPS, then you must set the protocol to `https`.
  proxy: 'http://user:pass@host:port',

  // `decompress` indicates whether or not the response body should be decompressed
  // automatically. If set to `true` will also remove the 'content-encoding' header
  // from the responses objects of all decompressed responses
  // - Node only (XHR cannot turn off decompression)
  decompress: true // default
}

Response Schema

The response for a request contains the following information.

{
  // `data` is the response that was provided by the server
  data: {},

  // `status` is the HTTP status code from the server response
  statusCode: 200,

  // `statusText` is the HTTP status message from the server response
  statusText: 'OK',

  // `headers` the HTTP headers that the server responded with
  // All header names are lowercase and can be accessed using the bracket notation.
  // Example: `response.headers['content-type']`
  headers: {},

  // `config` is the config that was provided to `nexus` for the request
  data: {},
}

Nexus Response Exception Schema

The response for a request contains the following information.

{
  // `data` is the response that was provided by the server
  data: {},

  // `status` is the HTTP status code from the server response
  statusCode: 200,

  // `statusText` is the HTTP status message from the server response
  statusText: 'OK',

  // `headers` the HTTP headers that the server responded with
  // All header names are lowercase and can be accessed using the bracket notation.
  // Example: `response.headers['content-type']`
  headers: {},

  // `config` is the config that was provided to `nexus` for the request
  data: {},

  // `request` is the request that generated this response
  // It is the last ClientRequest instance in node.js (in redirects)
  // and an XMLHttpRequest instance in the browser
  request: {}
}

License

MIT