/requestq

An intelligent queue for requests in the browser

Primary LanguageTypeScriptMIT LicenseMIT

requestq

A tiny, intelligent queue for ajax requests in the browser:

  • Prioritize requests, even cancelling long-running low-priority requests when high-priority requests come in.
  • Throttle requests, executing only a set number at a time
  • Retry requests
  • Only 2KB (minified and gzipped)

Installation

npm install requestq --save

If you need to support most browsers, you will also need a Promise polyfill if you do not already have one:

npm install promise-polyfill --save-exact

Usage

import {RequestQueue} from 'requestq';

const requests = new RequestQueue()
requests.get('https://example.com/terms.txt').then((response) => {
  console.log('Got terms: ', response)  
}).catch(() => {
  console.error('Request failed')
})

Advanced Usage

import {RequestQueue, RequestPriority} from 'requestq';

const requests = new RequestQueue({
    retries: 3,
    concurrency: 5
})

let terms = requests.get('https://example.com/terms.txt), {
  priority: RequestPriority.LOW
}).then((response) => {
  console.log('Got terms: ' + response)  
}).catch(() => {
  console.error('Request failed after 3 retries')
})

let names = requests.get('https://example.com/names.json', {
    priority: RequestPriority.HIGHEST,
    responseType: 'json'
}).then((response) => {
  // Use the response object
}).catch(() => {
  console.error('Request failed after 3 retries')
})
await Promise.all([terms, names])

Documentation

new RequestQueue({options})

Makes a new RequestQueue. Options:

  • retries: number of times a GET request will be retried on errors. (Default: 3)
    • Only GET requests are retried, as retrying POST can create duplicate objects or unwanted effects.
  • concurrency: number of concurrent requests the queue can have in-flight (Default: 6)

RequestQueue.request(method, url, {options})

Puts request in the queue. Returns a promise that resolves when the request is done, or rejects if it fails.

  • method: the HTTP method for the request, e.g. "GET"
  • url: The URL for the request
  • options:
    • priority: Defines the order in which requests get sent. One of the following:

      • RequestQueue.LOW
      • RequestQueue.MEDIUM (default)
      • RequestQueue.HIGH
      • RequestQueue.HIGHEST

      HIGHEST is special: It actually aborts HIGH, MEDIUM or LOW requests to be tried again, if there are too many requests in flight)

    • body: The request body if applicable. Either a string or an object (automatically JSON.stringified)

    • maxRetries: The maximum number of retries that this request will use, overrides the main RequestQueue retries.

    • responseType: One of the following:

      • null (default, uses browser behavior)
      • json: Parses the response as JSON and returns an object. Sets Accept: application/json as a request header.
      • text: Returns the response as text
      • blob: Returns a Blob
      • arraybuffer: Returns an ArrayBuffer
      • image: Returns an Image
    • headers: Object of additional headers to set

    • auth: contents of the 'Authorization' header if supplied

RequestQueue.get(url, {options})

RequestQueue.post(url, {options})

RequestQueue.patch(url, {options})

RequestQueue.delete(url, {options})

RequestQueue.head(url, {options})

RequestQueue.options(url, {options})

Shorthands for RequestQueue.request("method" ...).

FAQ

Why are you not using the Fetch API?

  • The Fetch API does not support aborting a request, which is required for high priority requests to abort and requeue lower priority requests.

Why does this not support Node?

  • Keeping the library tiny. If you need a universal client, axios is really neat.

Does this library have Typescript declarations?

  • Yup :)

License

MIT