nexus-request

v1.1.4

Published

a year ago

HTTP/HTTP2 client for NodeJS with ZSTD support.

Downloads

0High
0Medium
0Low

kaykyramos

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