throttled-web-client

Throttled Web Client is an npm package for making throttled web requests in Javascript. Internally, we use the request npm package to make requests. However, this package is structured into a class so that it can be extended and used in an object-oriented way! Throttled Web Client also uses promises instead of callbacks.

This is ideal for when ou need to hit a rate-limited API without exceeding a certain limit. As a user, you will specify how many requests per unit of time you want to be throttled to. You're then able to create requests as fast as you want, but they'll only be sent at an appropriate interval.

Usage

Setup

In package.json:

dependencies: {
    "throttled-web-client": "^1",
    ...
}

In whatever file:

const ThrottledWebClient = require('throttled-web-client');

Instantiating the class

Since this is an ES6 class, it must be instantiated before it can be used.

const ThrottledWebClient = require('throttled-web-client');

const myApiWebClient = new ThrottledWebClient('https://myApi.com/');

To instantiate ThrottledWebClient, you must pass in between 1 and 3 arguments.

The first argument, path, is the base URL that will be used for all requests. This argument is required. If you want a generic web client that can hit any endpoint, pass in an empty string.

The second argument, requestsPerPeriod, is a positive integer representing the maximum number of requests that can be made per period. This argument is optional, and defaults to 5.

The third argument, period, is a positive integer representing the duration of a "period" in milliseconds. This argument is optional, and defaults to 1000, which is 1 second.

For example, the default arguments of requestsPerPeriod = 5, period = 1000 mean that the client will make no more than 5 requests in any 1 second period.

Making an API call

const ThrottledWebClient = require('throttled-web-client');

const myApiWebClient = new ThrottledWebClient('https://myApi.com/');

const path = '/path/to/endpoint';
const options = {
    /* request.js options object
       see https://github.com/request/request
    */
}
myApiWebClient.request(path, options)
    .then(response => {
        console.log(response); // This will log the entire response.
    });

Built-in formatting methods

There are 3 built-in methods that will parse the response to return the part you care about, in the format you want.

• requestAsJson: Converts the body property of response to JSON, and gives you the entire response object.
• requestBody: Gives you the body property of response, discarding the rest of response.
• requestBodyAsJson: Converts the body property of response to JSON and gives you the converted body.

const ThrottledWebClient = require('javascript-web-client');

const myApiWebClient = new ThrottledWebClient('https://myApi.com/');

const path = '/path/to/endpoint';
const options = {
    /* request.js options object
       see https://github.com/request/request
    */
}
myApiWebClient.requestBodyAsJson(path, options)
    .then(response => {
        console.log(response); // This will log the response body, as an object.
    });