reqi

Reqi

Reqi is a Promisified request library with built in functionality for retries, redirects, and body parsing.

Installation

npm install reqi

Usage

Using Reqi is like using your favorite request libraries, but with promises. Require reqi, instantiate a client, and fire away!

const client = new (require('reqi'))({ json: true })
let data = await client.get('https://example.com/posts')

Reqi also includes convience methods for quick requests, such as get and put.

;(async function (postNum = 1) {
  // create a new reqi client with json parsing
  const jsonClient = new (require('reqi'))({ json: true })

  try {
    // grab a post
    let { body } = await jsonClient.get(
      `https://jsonplaceholder.typicode.com/posts/${postNum}`
    )

    // soup up the original post a bit
    let shnazzyTitle = body.title.toUpperCase() + '!!!'
    let excitingContent = body.body.replace('.', '!')

    const recycledPost = {
      userId: 1,
      id: 1,
      title: shnazzyTitle,
      body: excitingContent
    }

    // publish our new post
    let res = await jsonClient.put(
      `https://jsonplaceholder.typicode.com/posts/${postNum}`,
      recycledPost
    )

    console.log(res.statusCode)
  } catch (err) {
    console.error(err)
  }
})()

See Options for more information regarding clientOptions and requestOptions.

API

new ReqiClient([clientOptions])

• clientOptions: <Object> See clientOptions

Creates a new client with the supplied clientOptions overriding defaults.

request(requestOptions[, body=null])

• requestOptions: <Object> See requestOptions
• body: <Object> | <string> | <Buffer> | <stream> An acceptable request body.

request(url[, body=null])

• url: <string> | <URL> A parsable WHATWG input URL, or URL class.
• body: <Object> | <string> | <Buffer> | <stream> An acceptable request body.

Options

clientOptions

• clientOptions: <Object>
  • redirect: <boolean> | <number> Controls request redirection. If a positive number is passed, the redirect option will delimit the maximum redirect amount. Upon being set to 'true', all redirects will be followed.
  • retry: <boolean> | <number> Control request retries. If a positive number is passed, the retry option will delimit the maximum retry amount. Upon being set to 'true', retry attempts will be made until a success code is recieved.
  • retryCodes: number | <number[]> HTTP response code(s) to retry upon i.e. 101 or [426, 429].
  • maxWait: <number> The maximum number of seconds to wait before retrying a request. Deals primarily with rate limits.
  • json: <boolean> Enables or disables automatic request and response body parsing. If enabled, 'true', both bodies sent and recieved by the client are serialized and parsed, respectively.

Reqi gives you the option to control retries and redirects, as well as the ability to enable automatic body parsing.

const retryClient = new ReqiClient({ retry: 3, retryCodes: [429] })

By default, retries, redirects, and body parsing are disabled.

Client options are mutable too!

// for example
client.clientOptions.retry = 1

Default ReqiClient Configuration:

this.clientOptions = {
  redirect: false,
  retry: false,
  retryCodes: [],
  maxWait: 3, // seconds
  json: false
}

These clientOptions are bound to the request client and allow for subsequent requests without reconfiguration.

requestOptions

• requestOptions: <Object>
  • url: <string> | <URL> (Required) A parsable WHATWG input URL, or URL class.

Just like what you're used to with Node Core, Reqi supports all core HTTP/HTTPS request options, with a few defaults:

• method: the desired HTTP request method, defaulting to 'GET'.
• port: the desired HTTP host port. If no port is provided, Reqi will use either a 80 or 443 value depending on the request protocol.

For more information on the supported requestOptions, consult the following Node.js documentation:

• Core HTTP
• Core HTTPS
• Core TLS (SSL)

Contributing

Contributing via DCO 1.1.

License

Licensed under the MIT License. See the LICENSE file for more details.