Promise based HTTP/1.1 HTTP/2.0 client with ZSTD support for NodeJS (only for server-side). I've created it for my personal usage in a specific project so, I decided to share code with the community. I hope this can help anyone.
- 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
Using npm:
$ npm install nexus-requestUsing yarn:
$ yarn add nexus-requestOnce the package is installed, you can import the library using import or require approach:
import { Nexus, NexusException } from './libs/nexusjs/src/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/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)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/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/awaitis 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]
})Requests can be made by passing the relevant config to nexus.
// Send a POST request
import nexus from './libs/nexusjs/src/src'
nexus('https://httpbin.org/post', {
method: 'post',
data: {
firstName: 'Fred',
lastName: 'Flintstone'
}
})You can create a new instance of nexus with a custom config.
import { Nexus } from './libs/nexusjs/src/src'
const instance = new Nexus({
baseURL: 'https://httpbin.org/',
headers: {'X-Custom-Header': 'foobar'},
response: {
transformJson: true,
stringifyBigInt: true,
forceCamelCase: true,
}
});The available instance methods are listed below. The specified config will be merged with the instance 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
}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: {},
}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: {}
}